zwitschi
ef4fb7dcf0
- Updated architecture constraints documentation to include detailed sections on technical, organizational, regulatory, environmental, and performance constraints. - Created separate markdown files for each type of constraint for better organization and clarity. - Revised the architecture scope section to provide a clearer overview of the system's key areas. - Enhanced the solution strategy documentation with detailed explanations of the client-server architecture, technology choices, trade-offs, and future considerations. - Added comprehensive descriptions of backend and frontend components, middleware, and utilities in the architecture documentation. - Migrated UI, templates, and styling notes to a dedicated section for better structure. - Updated requirements.txt to include missing dependencies. - Refactored user authentication logic in the users.py and security.py files to improve code organization and maintainability, including the integration of OAuth2 password bearer token handling.
125 lines
6.1 KiB
Markdown
125 lines
6.1 KiB
Markdown
# 13 — UI, templates and styling
|
|
|
|
This chapter collects UI integration notes, reusable template components, styling audit points and per-page UI data/actions.
|
|
|
|
## 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.
|