From ae4b9c136f505b4da3f25b0f02fb4eba33b2d921 Mon Sep 17 00:00:00 2001
From: zwitschi <zwitschi82@gmail.com>
Date: Tue, 21 Oct 2025 07:43:10 +0200
Subject: [PATCH] feat: Introduce reusable template components and enhance
 styling utilities for consistent UI

---
 docs/architecture.md               |  27 ++++++
 static/css/main.css                |  44 +++++++--
 templates/consumption.html         |  57 +++++-------
 templates/costs.html               | 140 +++++++++++------------------
 templates/partials/components.html |  37 ++++++++
 5 files changed, 175 insertions(+), 130 deletions(-)
 create mode 100644 templates/partials/components.html

diff --git a/docs/architecture.md b/docs/architecture.md
index 6fe411c..c1bf06f 100644
--- a/docs/architecture.md
+++ b/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.
diff --git a/static/css/main.css b/static/css/main.css
index c822ba7..a781c1d 100644
--- a/static/css/main.css
+++ b/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;
-  padding: 1.5rem;
+  border-radius: var(--panel-radius);
+  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,
diff --git a/templates/consumption.html b/templates/consumption.html
index faba55f..18e5c9d 100644
--- a/templates/consumption.html
+++ b/templates/consumption.html
@@ -1,47 +1,33 @@
-{% extends "base.html" %} {% block title %}Consumption · CalMiner{% endblock %}
-{% block content %}
+{% extends "base.html" %} {% from "partials/components.html" import
+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">
-      Scenario filter
-      <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">
-    Choose a scenario to review its consumption records.
-  </div>
-  <div id="consumption-table-wrapper" class="table-container hidden">
-    <table aria-label="Scenario consumption records">
-      <thead>
-        <tr>
-          <th scope="col">Amount</th>
-          <th scope="col">Description</th>
-        </tr>
-      </thead>
-      <tbody id="consumption-table-body"></tbody>
-    </table>
+    {{ select_field( "Scenario filter", "consumption-scenario-filter",
+    options=scenarios, placeholder="Select a scenario" ) }}
   </div>
+  {{ empty_state( "consumption-empty", "Choose a scenario to review its
+  consumption records." ) }} {% call table_container(
+  "consumption-table-wrapper", hidden=True, aria_label="Scenario consumption
+  records" ) %}
+  <thead>
+    <tr>
+      <th scope="col">Amount</th>
+      <th scope="col">Description</th>
+    </tr>
+  </thead>
+  <tbody id="consumption-table-body"></tbody>
+  {% endcall %}
 </section>
 
 <section class="panel">
   <h2>Add Consumption Record</h2>
   {% if scenarios %}
   <form id="consumption-form" class="form-grid">
-    <label for="consumption-form-scenario">
-      Scenario
-      <select id="consumption-form-scenario" name="scenario_id" required>
-        <option value="" disabled selected>Select a scenario</option>
-        {% for scenario in scenarios %}
-        <option value="{{ scenario.id }}">{{ scenario.name }}</option>
-        {% endfor %}
-      </select>
-    </label>
+    {{ select_field( "Scenario", "consumption-form-scenario",
+    name="scenario_id", options=scenarios, required=True, placeholder="Select a
+    scenario", placeholder_disabled=True ) }}
     <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>
-  {% else %}
+  {{ feedback("consumption-feedback") }} {% else %}
   <p class="empty-state">
     Create a scenario before adding consumption records.
   </p>
diff --git a/templates/costs.html b/templates/costs.html
index eebe643..2d5da3e 100644
--- a/templates/costs.html
+++ b/templates/costs.html
@@ -1,71 +1,52 @@
-{% extends "base.html" %} {% block title %}Costs · CalMiner{% endblock %} {%
-block content %}
+{% extends "base.html" %} {% from "partials/components.html" import
+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">
-      Scenario filter
-      <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.
+    {{ select_field( "Scenario filter", "costs-scenario-filter",
+    options=scenarios, placeholder="Select a scenario" ) }}
   </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">
-      <h3>Capital Expenditures (CAPEX)</h3>
-      <table aria-label="Scenario CAPEX records">
-        <thead>
-          <tr>
-            <th scope="col">Amount</th>
-            <th scope="col">Description</th>
-          </tr>
-        </thead>
-        <tbody id="capex-table-body"></tbody>
-        <tfoot>
-          <tr>
-            <th scope="row">Total</th>
-            <th id="capex-total">—</th>
-          </tr>
-        </tfoot>
-      </table>
-      <p id="capex-empty" class="empty-state hidden">
-        No CAPEX records for this scenario yet.
-      </p>
-    </div>
-
-    <div class="table-container">
-      <h3>Operational Expenditures (OPEX)</h3>
-      <table aria-label="Scenario OPEX records">
-        <thead>
-          <tr>
-            <th scope="col">Amount</th>
-            <th scope="col">Description</th>
-          </tr>
-        </thead>
-        <tbody id="opex-table-body"></tbody>
-        <tfoot>
-          <tr>
-            <th scope="row">Total</th>
-            <th id="opex-total">—</th>
-          </tr>
-        </tfoot>
-      </table>
-      <p id="opex-empty" class="empty-state hidden">
-        No OPEX records for this scenario yet.
-      </p>
-    </div>
+    {% call table_container( "capex-table-container", aria_label="Scenario CAPEX
+    records", heading="Capital Expenditures (CAPEX)" ) %}
+    <thead>
+      <tr>
+        <th scope="col">Amount</th>
+        <th scope="col">Description</th>
+      </tr>
+    </thead>
+    <tbody id="capex-table-body"></tbody>
+    <tfoot>
+      <tr>
+        <th scope="row">Total</th>
+        <th id="capex-total">—</th>
+      </tr>
+    </tfoot>
+    {% endcall %} {{ empty_state( "capex-empty", "No CAPEX records for this
+    scenario yet.", hidden=True ) }} {% call table_container(
+    "opex-table-container", aria_label="Scenario OPEX records",
+    heading="Operational Expenditures (OPEX)" ) %}
+    <thead>
+      <tr>
+        <th scope="col">Amount</th>
+        <th scope="col">Description</th>
+      </tr>
+    </thead>
+    <tbody id="opex-table-body"></tbody>
+    <tfoot>
+      <tr>
+        <th scope="row">Total</th>
+        <th id="opex-total">—</th>
+      </tr>
+    </tfoot>
+    {% endcall %} {{ empty_state( "opex-empty", "No OPEX records for this
+    scenario yet.", hidden=True ) }}
   </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">
-      Scenario
-      <select id="capex-form-scenario" name="scenario_id" required>
-        <option value="" disabled selected>Select a scenario</option>
-        {% for scenario in scenarios %}
-        <option value="{{ scenario.id }}">{{ scenario.name }}</option>
-        {% endfor %}
-      </select>
-    </label>
+    {{ select_field( "Scenario", "capex-form-scenario", name="scenario_id",
+    options=scenarios, required=True, placeholder="Select a scenario",
+    placeholder_disabled=True ) }}
     <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>
-  {% else %}
-  <p class="empty-state">Create a scenario before adding CAPEX entries.</p>
-  {% endif %}
+  {{ feedback("capex-feedback") }} {% else %} {{ empty_state(
+  "capex-form-empty", "Create a scenario before adding CAPEX entries." ) }} {%
+  endif %}
 </section>
 
 <section class="panel">
   <h2>Add OPEX Entry</h2>
   {% if scenarios %}
   <form id="opex-form" class="form-grid">
-    <label for="opex-form-scenario">
-      Scenario
-      <select id="opex-form-scenario" name="scenario_id" required>
-        <option value="" disabled selected>Select a scenario</option>
-        {% for scenario in scenarios %}
-        <option value="{{ scenario.id }}">{{ scenario.name }}</option>
-        {% endfor %}
-      </select>
-    </label>
+    {{ select_field( "Scenario", "opex-form-scenario", name="scenario_id",
+    options=scenarios, required=True, placeholder="Select a scenario",
+    placeholder_disabled=True ) }}
     <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>
-  {% else %}
-  <p class="empty-state">Create a scenario before adding OPEX entries.</p>
-  {% endif %}
+  {{ feedback("opex-feedback") }} {% else %} {{ empty_state( "opex-form-empty",
+  "Create a scenario before adding OPEX entries." ) }} {% endif %}
 </section>
 
 {% endblock %} {% block scripts %} {{ super() }}
diff --git a/templates/partials/components.html b/templates/partials/components.html
new file mode 100644
index 0000000..09901fa
--- /dev/null
+++ b/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 %}