{% 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, then leave the density field blank to use the tabulated default or 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, and any workflow-specific values.</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, 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 preview to inspect the combined plot before saving it.</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 shows the rendered image together with the selected runs and orders so you can trace exactly
    how the comparison was assembled.
  </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 copy the live preview into a chosen directory.</li>
    <li>Use <strong>Manage runs</strong> to rename or delete saved runs.</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>
  <p>
    Exported plot images are copied from the live preview so the saved file matches what you saw in the browser.
  </p>
</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 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 %}