{% extends "base.html" %}
{% block title %}Web UI Documentation{% endblock %}
{% block body %}
<section class="section-head">
  <div>
    <h1>Web UI Documentation</h1>
    <p>Everything you need to create gratings, run simulations, and plot results inside Grax Web.</p>
  </div>
  <div class="actions">
    <a class="button" href="{{ url_for('index') }}">Back to home</a>
    <a class="button primary" href="{{ url_for('new_grating') }}">Create grating</a>
  </div>
</section>

<section class="notice">
  <p>
    The active workspace root is <code>{{ workspace_root }}</code>. By default, Grax Web stores data in
    <code>.grax-web/</code> in the current working directory unless you switch the workspace from the home page.
  </p>
  <div class="docs-toc">
    <a class="button" href="#storage">Storage</a>
    <a class="button" href="#materials">Materials</a>
    <a class="button" href="#gratings">Gratings</a>
    <a class="button" href="#simulations">Simulations</a>
    <a class="button" href="#plots">Plots</a>
    <a class="button" href="#export">Export</a>
    <a class="button" href="#modify">Modify later</a>
  </div>
</section>

<section class="docs-section" id="storage">
  <h2>Where data is saved</h2>
  <p>
    Grax Web keeps all local state under the active workspace directory. The default workspace is
    <code>.grax-web/</code> next to where you launch <code>grax-web</code>.
  </p>
  <div class="list compact">
    <div class="row"><strong><code>saved_gratings/</code></strong><span>One JSON file per saved grating spec.</span></div>
    <div class="row"><strong><code>runs/</code></strong><span>One run directory per simulation, with manifests and CSV outputs.</span></div>
    <div class="row"><strong><code>plots/</code></strong><span>Saved comparison plots and their manifests.</span></div>
    <div class="row"><strong><code>previews/</code></strong><span>Temporary and live preview images shown in the browser.</span></div>
  </div>
  <p>
    The workspace can be changed from the home page. When you switch workspaces, the app reads and writes future
    gratings, runs, and plots in the new location.
  </p>
</section>

<section class="docs-section" id="materials">
  <h2>Materials</h2>
  <p>
    The grating form uses the same packaged Henke material list that the Python API uses. Pick a material from the
    dropdown. The density field is prefilled with the built-in default for that element, and you can type a measured
    density when your sample is a film, porous layer, or otherwise not bulk-like.
  </p>
  <p>
    xrt-style material objects still work for compatibility during the transition, but Grax will warn that this path is
    deprecated and will be removed in a future release. For new work, prefer the string material name plus an optional
    density override.
  </p>
</section>

<section class="docs-section" id="gratings">
  <h2>Create and save gratings</h2>
  <ol>
    <li>Open <strong>New grating</strong> from the top bar or the home page.</li>
    <li>Choose the grating type, period, numerical resolutions, and profile-specific parameters.</li>
    <li>Select the coating stack type and pick materials from the built-in material catalog.</li>
    <li>Use the live preview panel to confirm the shape before saving.</li>
    <li>Save the grating to store it in <code>saved_gratings/&lt;grating-id&gt;.json</code>.</li>
  </ol>
  <p>
    After saving, the grating detail page lets you edit the profile, review the preview image, or delete the grating.
    Saved gratings are the starting point for simulations. The saved JSON now stores each material as a name plus
    density pair so the same sample can be reconstructed later.
  </p>
</section>

<section class="docs-section" id="simulations">
  <h2>Run simulations</h2>
  <ol>
    <li>Open a saved grating from the home page.</li>
    <li>Pick a workflow: fixed angle, monochromator, multilayer theta search, or parameter study.</li>
    <li>Enter the energy range, diffraction order, Fourier orders, polarization, and any workflow-specific values.</li>
    <li>Add an optional run comment if you want the saved run to carry a note or experiment tag.</li>
    <li>Choose the worker mode if you want auto or manual multiprocessing.</li>
    <li>Run the sweep and follow the progress page while the simulation writes results.</li>
  </ol>
  <p>
    Each run gets its own directory under <code>runs/&lt;run-id&gt;/</code>. The manifest records the workflow, grating
    metadata, selected orders, comment, and progress state. The run directory also stores the result CSV files and
    generated preview images for that run.
  </p>
</section>

<section class="docs-section" id="plots">
  <h2>Compare and plot runs</h2>
  <ol>
    <li>Open <strong>Plots</strong> from the top bar.</li>
    <li>Select one or more saved runs.</li>
    <li>Choose the diffraction orders you want to compare.</li>
    <li>Use the live Plotly preview to inspect the combined plot before saving it.</li>
    <li>Adjust the line color, marker type, marker size, and x/y axis scales directly in the form.</li>
    <li>Save the plot to create a dedicated entry under <code>plots/&lt;plot-id&gt;/</code>.</li>
  </ol>
  <p>
    The saved plot page reopens the same interactive Plotly figure together with the selected runs and orders, so the
    comparison styling and the axis modes persist with the saved plot.
  </p>
</section>

<section class="docs-section" id="export">
  <h2>Export plots and manage saved data</h2>
  <ul>
    <li>Use <strong>Save plot</strong> in the plot builder to store the interactive compare view in <code>plots/</code>.</li>
    <li>Use <strong>Manage runs</strong> to rename saved runs, edit their comments, or delete them.</li>
    <li>Use <strong>Manage gratings</strong> to inspect, edit, or delete saved grating definitions.</li>
    <li>Use the workspace switcher on the home page if you want the app to read and write a different local folder.</li>
  </ul>
</section>

<section class="docs-section" id="modify">
  <h2>How to modify the interface later</h2>
  <p>If you want to change the Web UI, these files control the main moving parts:</p>
  <ul>
    <li><code>src/grax/web/app.py</code>: routes, workspace behavior, simulation wiring, and runtime page data.</li>
    <li><code>src/grax/web/templates/*.html</code>: page text, layout, and button placement.</li>
    <li><code>src/grax/web/static/web.css</code>: styling and responsive layout.</li>
    <li><code>src/grax/web/static/web.js</code>: client-side preview, Plotly rendering, and form interactions.</li>
    <li><code>src/grax/web/persistence.py</code>: how gratings are stored and reconstructed from JSON.</li>
    <li><code>src/grax/web/runs.py</code>: run manifests, result loading, and comparison plot saving.</li>
  </ul>
  <p>
    To change the default workspace folder, edit the <code>create_app()</code> setup in
    <code>src/grax/web/app.py</code>. To change the docs itself, edit this template and the matching external docs
    notes in <code>docs/index.md</code> and <code>docs/installation/web-ui.md</code>.
  </p>
</section>
{% endblock %}