Add UI and styling documentation; remove idempotency and logging audits
Some checks failed
CI / test (pull_request) Failing after 1m8s
Some checks failed
CI / test (pull_request) Failing after 1m8s
- Introduced a new document outlining UI structure, reusable template components, CSS variable conventions, and per-page data/actions for the CalMiner application. - Removed outdated idempotency audit and logging audit documents as they are no longer relevant. - Updated quickstart guide to streamline developer setup instructions and link to relevant documentation. - Created a roadmap document detailing scenario enhancements and data management strategies. - Deleted the seed data plan document to consolidate information into the setup process. - Refactored setup_database.py for improved logging and error handling during database setup and migration processes.
This commit is contained in:
124
docs/developer/ui_and_style.md
Normal file
124
docs/developer/ui_and_style.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user