# UI, templates and styling

This document outlines the UI structure, template components, CSS variable conventions, and per-page data/actions for the CalMiner application.

## Reusable Template Components

To reduce duplication across form-centric pages, shared Jinja macros live in `templates/partials/components.html`.

- `select_field(...)`: renders labeled `<select>` controls with consistent placeholder handling and optional preselection. Existing JavaScript modules continue to target the generated IDs, so template calls must pass the same identifiers (`consumption-form-scenario`, etc.).
- `feedback(...)` and `empty_state(...)`: wrap status messages in standard classes (`feedback`, `empty-state`) with optional `hidden` toggles so scripts can control visibility without reimplementing markup.
- `table_container(...)`: provides a semantic wrapper and optional heading around tabular content; the `{% call %}` body supplies the `<thead>`, `<tbody>`, and `<tfoot>` elements while the macro applies the `table-container` class and manages hidden state.

Pages like `templates/consumption.html` and `templates/costs.html` already consume these helpers to keep markup aligned while preserving existing JavaScript selectors.

Import macros via:

```jinja
{% from "partials/components.html" import select_field, feedback, table_container with context %}
```

## Styling Audit Notes (2025-10-21)

- **Spacing**: Panels (`section.panel`) sometimes lack consistent vertical rhythm between headings, form grids, and tables. Extra top/bottom margin utilities would help align content.
- **Typography**: Headings rely on browser defaults; font-size scale is uneven between `<h2>` and `<h3>`. Define explicit scale tokens (e.g., `--font-size-lg`) for predictable sizing.
- **Forms**: `.form-grid` uses fixed column gaps that collapse on small screens; introduce responsive grid rules to stack gracefully below ~768px.
- **Tables**: `.table-container` wrappers need overflow handling for narrow viewports; consider `overflow-x: auto` with padding adjustments.
- **Feedback/Empty states**: Messages use default font weight and spacing; a utility class for margin/padding would ensure consistent separation from forms or tables.

## CSS Variable Naming Conventions

The project adheres to a clear and descriptive naming convention for CSS variables, primarily defined in `static/css/main.css`.

## Naming Structure

Variables are prefixed based on their category:

- `--color-`: For all color-related variables (e.g., `--color-primary`, `--color-background`, `--color-text-primary`).
- `--space-`: For spacing and layout-related variables (e.g., `--space-sm`, `--space-md`, `--space-lg`).
- `--font-size-`: For font size variables (e.g., `--font-size-base`, `--font-size-lg`).
- Other specific prefixes for components or properties (e.g., `--panel-radius`, `--table-radius`).

## Descriptive Names

Color names are chosen to be semantically meaningful rather than literal color values, allowing for easier theme changes. For example:

- `--color-primary`: Represents the main brand color.
- `--color-accent`: Represents an accent color used for highlights.
- `--color-text-primary`: The main text color.
- `--color-text-muted`: A lighter text color for less emphasis.
- `--color-surface`: The background color for UI elements like cards or panels.
- `--color-background`: The overall page background color.

This approach ensures that the CSS variables are intuitive, maintainable, and easily adaptable for future theme customizations.

## Per-page data & actions

Short reference of per-page APIs and primary actions used by templates and scripts.

- Scenarios (`templates/ScenarioForm.html`):

  - Data: `GET /api/scenarios/`
  - Actions: `POST /api/scenarios/`

- Parameters (`templates/ParameterInput.html`):

  - Data: `GET /api/scenarios/`, `GET /api/parameters/`
  - Actions: `POST /api/parameters/`

- Costs (`templates/costs.html`):

  - Data: `GET /api/costs/capex`, `GET /api/costs/opex`
  - Actions: `POST /api/costs/capex`, `POST /api/costs/opex`

- Consumption (`templates/consumption.html`):

  - Data: `GET /api/consumption/`
  - Actions: `POST /api/consumption/`

- Production (`templates/production.html`):

  - Data: `GET /api/production/`
  - Actions: `POST /api/production/`

- Equipment (`templates/equipment.html`):

  - Data: `GET /api/equipment/`
  - Actions: `POST /api/equipment/`

- Maintenance (`templates/maintenance.html`):

  - Data: `GET /api/maintenance/` (pagination support)
  - Actions: `POST /api/maintenance/`, `PUT /api/maintenance/{id}`, `DELETE /api/maintenance/{id}`

- Simulations (`templates/simulations.html`):

  - Data: `GET /api/scenarios/`, `GET /api/parameters/`
  - Actions: `POST /api/simulations/run`

- Reporting (`templates/reporting.html` and `templates/Dashboard.html`):
  - Data: `POST /api/reporting/summary` (accepts arrays of `{ "result": float }` objects)
  - Actions: Trigger summary refreshes and export/download actions.

## Navigation Structure

The application uses a sidebar navigation menu organized into the following top-level categories:

- **Dashboard**: Main overview page.
- **Overview**: Sub-menu for core scenario inputs.
  - Parameters: Process parameters configuration.
  - Costs: Capital and operating costs.
  - Consumption: Resource consumption tracking.
  - Production: Production output settings.
  - Equipment: Equipment inventory (with Maintenance sub-item).
- **Simulations**: Monte Carlo simulation runs.
- **Analytics**: Reporting and analytics.
- **Settings**: Administrative settings (with Themes and Currency Management sub-items).

## UI Template Audit (2025-10-20)

- Existing HTML templates: `ScenarioForm.html`, `ParameterInput.html`, and `Dashboard.html` (reporting summary view).
- Coverage gaps remain for costs, consumption, production, equipment, maintenance, and simulation workflows—no dedicated templates yet.
- Shared layout primitives (navigation/header/footer) are absent; current pages duplicate boilerplate markup.
- Dashboard currently covers reporting metrics but should be wired to a central `/` route once the shared layout lands.
- Next steps: introduce a `base.html`, refactor existing templates to extend it, and scaffold placeholder pages for the remaining features.