feat: Introduce reusable template components and enhance styling utilities for consistent UI

docs/architecture.md

@@ -14,6 +14,7 @@ The backend leverages SQLAlchemy for ORM mapping to a PostgreSQL database.
 - **Service layer** (`services/`): houses business logic. `services/reporting.py` produces statistical summaries, while `services/simulation.py` provides the Monte Carlo integration point.
 - **Persistence** (`models/`, `config/database.py`): SQLAlchemy models map to PostgreSQL tables in schema `bricsium_platform`. Relationships connect scenarios to derived domain entities.
 - **Presentation** (`templates/`, `components/`): server-rendered views extend a shared `base.html` layout with a persistent left sidebar, pull global styles from `static/css/main.css`, and surface data entry (scenario and parameter forms) alongside the Chart.js-powered dashboard.
+  - **Reusable partials** (`templates/partials/components.html`): macro library that standardises select inputs, feedback/empty states, and table wrappers so pages remain consistent while keeping DOM hooks stable for existing JavaScript modules.
 - **Middleware** (`middleware/validation.py`): applies JSON validation before requests reach routers.
 - **Testing** (`tests/unit/`): pytest suite covering route and service behavior.
 
@@ -94,6 +95,32 @@ For extended diagrams and setup instructions reference:
 
 ### UI Frontend-Backend Integration Requirements — 2025-10-20
 
+### Reusable Template Components — 2025-10-21
+
+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.
+
+Pages should import these macros via `{% from "partials/components.html" import ... with context %}` to ensure scenario lists or other context variables stay available inside the macro body.
+
+### 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.
+
+### Styling Utilities — 2025-10-21
+
+- Added spacing and typography CSS variables (e.g., `--space-sm`, `--font-size-xl`) and applied them to `.panel` and `.form-grid` elements for consistent vertical rhythm.
+- Standardised heading weights/sizes within panels so `<h2>` and `<h3>` share explicit scale tokens.
+- Updated form controls to use the new spacing tokens, preparing the layout for further responsive tweaks.
+
 #### Scenarios (`templates/ScenarioForm.html`)
 
 - **Data**: `GET /api/scenarios/` to list existing scenarios for navigation and to hydrate dropdowns in downstream forms; optional aggregation of scenario counts for dashboard badges.

static/css/main.css

@@ -20,6 +20,21 @@
   --color-surface-alt: #f8fafc;
   --color-success: #047857;
   --color-error: #b91c1c;
+  --space-2xs: 0.25rem;
+  --space-xs: 0.5rem;
+  --space-sm: 0.75rem;
+  --space-md: 1rem;
+  --space-lg: 1.5rem;
+  --space-xl: 2rem;
+  --space-2xl: 3rem;
+  --font-size-xs: 0.75rem;
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.25rem;
+  --font-size-xl: 1.5rem;
+  --font-size-2xl: 2rem;
+  --panel-radius: 12px;
+  --table-radius: 10px;
 }
 
 body {
@@ -318,22 +333,37 @@ body {
 
 .panel {
   background-color: var(--color-surface);
-  border-radius: 12px;
+  border-radius: var(--panel-radius);
-  padding: 1.5rem;
+  padding: var(--space-xl);
   box-shadow: 0 2px 8px var(--color-panel-shadow);
-  margin-bottom: 2rem;
+  margin-bottom: var(--space-2xl);
+}
+
+.panel h2,
+.panel h3 {
+  font-weight: 700;
+  color: var(--color-text-dark);
+  margin: 0 0 var(--space-sm);
+}
+
+.panel h2 {
+  font-size: var(--font-size-xl);
+}
+
+.panel h3 {
+  font-size: var(--font-size-lg);
 }
 
 .form-grid {
   display: grid;
-  gap: 1rem;
+  gap: var(--space-md);
   max-width: 480px;
 }
 
 .form-grid label {
   display: flex;
   flex-direction: column;
-  gap: 0.5rem;
+  gap: var(--space-sm);
   font-weight: 600;
   color: var(--color-text-strong);
 }
@@ -341,10 +371,10 @@ body {
 .form-grid input,
 .form-grid textarea,
 .form-grid select {
-  padding: 0.6rem 0.75rem;
+  padding: 0.6rem var(--space-sm);
   border: 1px solid var(--color-border-strong);
   border-radius: 8px;
-  font-size: 1rem;
+  font-size: var(--font-size-base);
 }
 
 .form-grid input:focus,

templates/consumption.html

@@ -1,23 +1,16 @@
-{% extends "base.html" %} {% block title %}Consumption · CalMiner{% endblock %}
+{% extends "base.html" %} {% from "partials/components.html" import
-{% block content %}
+select_field, feedback, empty_state, table_container with context %} {% block
+title %}Consumption · CalMiner{% endblock %} {% block content %}
 <section class="panel">
   <h2>Consumption Tracking</h2>
   <div class="form-grid">
-    <label for="consumption-scenario-filter">
+    {{ select_field( "Scenario filter", "consumption-scenario-filter",
-      Scenario filter
+    options=scenarios, placeholder="Select a scenario" ) }}
-      <select id="consumption-scenario-filter">
-        <option value="">Select a scenario</option>
-        {% for scenario in scenarios %}
-        <option value="{{ scenario.id }}">{{ scenario.name }}</option>
-        {% endfor %}
-      </select>
-    </label>
   </div>
-  <div id="consumption-empty" class="empty-state">
+  {{ empty_state( "consumption-empty", "Choose a scenario to review its
-    Choose a scenario to review its consumption records.
+  consumption records." ) }} {% call table_container(
-  </div>
+  "consumption-table-wrapper", hidden=True, aria_label="Scenario consumption
-  <div id="consumption-table-wrapper" class="table-container hidden">
+  records" ) %}
-    <table aria-label="Scenario consumption records">
   <thead>
     <tr>
       <th scope="col">Amount</th>
@@ -25,23 +18,16 @@
     </tr>
   </thead>
   <tbody id="consumption-table-body"></tbody>
-    </table>
+  {% endcall %}
-  </div>
 </section>
 
 <section class="panel">
   <h2>Add Consumption Record</h2>
   {% if scenarios %}
   <form id="consumption-form" class="form-grid">
-    <label for="consumption-form-scenario">
+    {{ select_field( "Scenario", "consumption-form-scenario",
-      Scenario
+    name="scenario_id", options=scenarios, required=True, placeholder="Select a
-      <select id="consumption-form-scenario" name="scenario_id" required>
+    scenario", placeholder_disabled=True ) }}
-        <option value="" disabled selected>Select a scenario</option>
-        {% for scenario in scenarios %}
-        <option value="{{ scenario.id }}">{{ scenario.name }}</option>
-        {% endfor %}
-      </select>
-    </label>
     <label for="consumption-form-amount">
       Amount
       <input
@@ -63,8 +49,7 @@
     </label>
     <button type="submit" class="btn primary">Add Record</button>
   </form>
-  <p id="consumption-feedback" class="feedback hidden" role="status"></p>
+  {{ feedback("consumption-feedback") }} {% else %}
-  {% else %}
   <p class="empty-state">
     Create a scenario before adding consumption records.
   </p>

templates/costs.html

@@ -1,31 +1,20 @@
-{% extends "base.html" %} {% block title %}Costs · CalMiner{% endblock %} {%
+{% extends "base.html" %} {% from "partials/components.html" import
-block content %}
+select_field, feedback, empty_state, table_container with context %} {% block
+title %}Costs · CalMiner{% endblock %} {% block content %}
 <section class="panel">
   <h2>Cost Overview</h2>
   {% if scenarios %}
   <div class="form-grid">
-    <label for="costs-scenario-filter">
+    {{ select_field( "Scenario filter", "costs-scenario-filter",
-      Scenario filter
+    options=scenarios, placeholder="Select a scenario" ) }}
-      <select id="costs-scenario-filter">
-        <option value="">Select a scenario</option>
-        {% for scenario in scenarios %}
-        <option value="{{ scenario.id }}">{{ scenario.name }}</option>
-        {% endfor %}
-      </select>
-    </label>
-  </div>
-  {% else %}
-  <p class="empty-state">Create a scenario to review cost information.</p>
-  {% endif %}
-
-  <div id="costs-empty" class="empty-state">
-    Choose a scenario to review CAPEX and OPEX details.
   </div>
+  {% else %} {{ empty_state( "costs-scenario-empty", "Create a scenario to
+  review cost information." ) }} {% endif %} {{ empty_state( "costs-empty",
+  "Choose a scenario to review CAPEX and OPEX details." ) }}
 
   <div id="costs-data" class="hidden">
-    <div class="table-container">
+    {% call table_container( "capex-table-container", aria_label="Scenario CAPEX
-      <h3>Capital Expenditures (CAPEX)</h3>
+    records", heading="Capital Expenditures (CAPEX)" ) %}
-      <table aria-label="Scenario CAPEX records">
     <thead>
       <tr>
         <th scope="col">Amount</th>
@@ -39,15 +28,10 @@ block content %}
         <th id="capex-total">—</th>
       </tr>
     </tfoot>
-      </table>
+    {% endcall %} {{ empty_state( "capex-empty", "No CAPEX records for this
-      <p id="capex-empty" class="empty-state hidden">
+    scenario yet.", hidden=True ) }} {% call table_container(
-        No CAPEX records for this scenario yet.
+    "opex-table-container", aria_label="Scenario OPEX records",
-      </p>
+    heading="Operational Expenditures (OPEX)" ) %}
-    </div>
-
-    <div class="table-container">
-      <h3>Operational Expenditures (OPEX)</h3>
-      <table aria-label="Scenario OPEX records">
     <thead>
       <tr>
         <th scope="col">Amount</th>
@@ -61,11 +45,8 @@ block content %}
         <th id="opex-total">—</th>
       </tr>
     </tfoot>
-      </table>
+    {% endcall %} {{ empty_state( "opex-empty", "No OPEX records for this
-      <p id="opex-empty" class="empty-state hidden">
+    scenario yet.", hidden=True ) }}
-        No OPEX records for this scenario yet.
-      </p>
-    </div>
   </div>
 </section>
 
@@ -73,15 +54,9 @@ block content %}
   <h2>Add CAPEX Entry</h2>
   {% if scenarios %}
   <form id="capex-form" class="form-grid">
-    <label for="capex-form-scenario">
+    {{ select_field( "Scenario", "capex-form-scenario", name="scenario_id",
-      Scenario
+    options=scenarios, required=True, placeholder="Select a scenario",
-      <select id="capex-form-scenario" name="scenario_id" required>
+    placeholder_disabled=True ) }}
-        <option value="" disabled selected>Select a scenario</option>
-        {% for scenario in scenarios %}
-        <option value="{{ scenario.id }}">{{ scenario.name }}</option>
-        {% endfor %}
-      </select>
-    </label>
     <label for="capex-form-amount">
       Amount
       <input
@@ -103,25 +78,18 @@ block content %}
     </label>
     <button type="submit" class="btn primary">Add CAPEX</button>
   </form>
-  <p id="capex-feedback" class="feedback hidden" role="status"></p>
+  {{ feedback("capex-feedback") }} {% else %} {{ empty_state(
-  {% else %}
+  "capex-form-empty", "Create a scenario before adding CAPEX entries." ) }} {%
-  <p class="empty-state">Create a scenario before adding CAPEX entries.</p>
+  endif %}
-  {% endif %}
 </section>
 
 <section class="panel">
   <h2>Add OPEX Entry</h2>
   {% if scenarios %}
   <form id="opex-form" class="form-grid">
-    <label for="opex-form-scenario">
+    {{ select_field( "Scenario", "opex-form-scenario", name="scenario_id",
-      Scenario
+    options=scenarios, required=True, placeholder="Select a scenario",
-      <select id="opex-form-scenario" name="scenario_id" required>
+    placeholder_disabled=True ) }}
-        <option value="" disabled selected>Select a scenario</option>
-        {% for scenario in scenarios %}
-        <option value="{{ scenario.id }}">{{ scenario.name }}</option>
-        {% endfor %}
-      </select>
-    </label>
     <label for="opex-form-amount">
       Amount
       <input
@@ -143,10 +111,8 @@ block content %}
     </label>
     <button type="submit" class="btn primary">Add OPEX</button>
   </form>
-  <p id="opex-feedback" class="feedback hidden" role="status"></p>
+  {{ feedback("opex-feedback") }} {% else %} {{ empty_state( "opex-form-empty",
-  {% else %}
+  "Create a scenario before adding OPEX entries." ) }} {% endif %}
-  <p class="empty-state">Create a scenario before adding OPEX entries.</p>
-  {% endif %}
 </section>
 
 {% endblock %} {% block scripts %} {{ super() }}

templates/partials/components.html

@@ -0,0 +1,37 @@
+{% macro select_field(label_text, select_id, name=None, options=[], placeholder="Select an option", required=False, include_blank=True, value_attr="id", label_attr="name", placeholder_disabled=False, placeholder_selected=True, selected_value=None) %}
+<label for="{{ select_id }}">
+  {{ label_text }}
+  <select id="{{ select_id }}"{% if name %} name="{{ name }}"{% endif %}{% if required %} required{% endif %}>
+    {% if include_blank %}
+    <option value=""{% if placeholder_disabled %} disabled{% endif %}{% if placeholder_selected %} selected{% endif %}>{{ placeholder }}</option>
+    {% endif %}
+    {% for option in options %}
+      {% if option is mapping %}
+        {% set option_value = option[value_attr] %}
+        {% set option_label = option[label_attr] %}
+      {% else %}
+        {% set option_value = attribute(option, value_attr) %}
+        {% set option_label = attribute(option, label_attr) %}
+      {% endif %}
+    <option value="{{ option_value }}"{% if selected_value is not none and option_value|string == selected_value|string %} selected{% endif %}>{{ option_label }}</option>
+    {% endfor %}
+  </select>
+</label>
+{% endmacro %}
+
+{% macro feedback(id, hidden=True, role="status", extra_classes="") %}
+<p id="{{ id }}" class="feedback{% if hidden %} hidden{% endif %}{% if extra_classes %} {{ extra_classes }}{% endif %}" role="{{ role }}"></p>
+{% endmacro %}
+
+{% macro empty_state(id, text, hidden=False, extra_classes="") %}
+<p id="{{ id }}" class="empty-state{% if hidden %} hidden{% endif %}{% if extra_classes %} {{ extra_classes }}{% endif %}">{{ text }}</p>
+{% endmacro %}
+
+{% macro table_container(wrapper_id, hidden=False, aria_label=None, extra_classes="", heading=None, heading_level="h3") %}
+<div id="{{ wrapper_id }}" class="table-container{% if hidden %} hidden{% endif %}{% if extra_classes %} {{ extra_classes }}{% endif %}">
+  {% if heading %}<{{ heading_level }}>{{ heading }}</{{ heading_level }}>{% endif %}
+  <table{% if aria_label %} aria-label="{{ aria_label }}"{% endif %}>
+    {{ caller() }}
+  </table>
+</div>
+{% endmacro %}