Show split plan actions and document frontend workflow

Author: =

apps/predbat/frontend.zip

@@ -0,0 +1,51 @@
+# Predbat Modern UI
+
+The Modern UI is a React and TypeScript application built with Vite. It is
+served by Predbat either from the development server or from the bundled
+`apps/predbat/frontend.zip` archive.
+
+## Start developing
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Open the address printed by Vite. Run Predbat locally as well when testing
+live data; the frontend reads its APIs relative to the current Predbat URL, so
+the same build works through Home Assistant ingress.
+
+## Check a change
+
+```bash
+npm test
+npm run lint
+npm run build
+```
+
+`npm run bundle` runs the production build and packages `dist/` as
+`../apps/predbat/frontend.zip`. Run it before testing a change in Home
+Assistant or opening a pull request that changes frontend behaviour.
+
+## Useful project locations
+
+| Location | Purpose |
+| --- | --- |
+| `src/pages/` | Full-page views and route-level UI |
+| `src/components/` | Reusable UI components and their CSS |
+| `src/types/` | TypeScript contracts for Predbat API data |
+| `src/utils/` | Formatting and data transformation helpers |
+| `tests/` | Node-based component and utility tests |
+| `tests/fixtures/` | Anonymised API examples for repeatable tests |
+| `docs/` | Frontend API and design conventions |
+
+## Working conventions
+
+- Keep API paths relative, for example `./api/plan_data`, so Home Assistant
+  ingress continues to work.
+- Add or update a fixture when an API field has important display behaviour.
+- Prefer a focused regression test for a reported UI problem.
+- Do not edit the generated `dist/` directory directly.
+- Read [the API contract](docs/api-contract.md) and
+  [UI conventions](docs/ui-conventions.md) before changing a page.

frontend/README.md

@@ -0,0 +1,51 @@
+# Modern UI API contract
+
+The frontend calls Predbat using relative URLs. Do not turn these into root
+URLs: Home Assistant ingress mounts Predbat below a changing path.
+
+This document records the fields whose meaning is easy to misread. It is not a
+replacement for the backend implementation; update it with a fixture and a
+test when a new field affects the UI.
+
+## `GET ./api/plan_data`
+
+Returns the active plan, previous-day plan, baseline plan, and manual
+overrides. The current plan is in `plan.rows`.
+
+### Important row fields
+
+| Field | Meaning |
+| --- | --- |
+| `time` | ISO timestamp for the start of the half-hour slot. |
+| `slot_minute` | Minute index used by manual overrides. |
+| `state` | The final action for the slot. This alone is not sufficient for split actions. |
+| `state_text` | First legacy display action, supplied for a split charge/export slot. |
+| `state2_text` | Second legacy display action. When both display fields describe actions, render both. |
+| `state_target` | Planned battery target for the action. |
+| `reasons` | Structured explanation data rendered in action tooltips. |
+| `import_rate`, `export_rate` | Base tariff rates in the configured minor currency unit. |
+| `*_rate_adjusted` | Rate after Predbat losses or an event adjustment. |
+| `*_rate_adjust_type` | Includes `future` for a predicted rate and `saving` for an energy event. |
+| `rate_event_type` | Event type used for the plan badge, such as `octopus_power_down` or `octopus_happy_hour`. |
+
+### Split charge and export actions
+
+Predbat can charge and export in one half-hour slot. In that case `state` is
+normally the final export state, while `state_text` and `state2_text` preserve
+both display actions. The Modern Plan table must show both actions rather than
+using `state` alone.
+
+Use [the split-action fixture](../tests/fixtures/plan-data-split-actions.json)
+when changing this behaviour.
+
+## Other frequently used endpoints
+
+| Endpoint | Used for |
+| --- | --- |
+| `GET ./api/status` | Predbat status, calculation state and update state. |
+| `GET ./api/power_flow` | Live power-flow and overview data. |
+| `GET ./api/chart_data?chart=<name>` | Chart series. |
+| `GET/POST ./api/config` | User-facing configuration page. |
+| `GET/POST ./api/apps_yaml` | Raw `apps.yaml` editor. |
+| `GET ./api/apps_schema` | Editor completion, validation and hover descriptions. |
+| `GET ./api/entities?all=1` | Home Assistant entity completion. |

frontend/docs/api-contract.md

@@ -0,0 +1,37 @@
+# Modern UI conventions
+
+## Meaningful colours
+
+- **Blue**: battery charging and charge actions.
+- **Purple**: export power and export actions.
+- **Yellow**: solar generation and solar forecast.
+- **Green**: normal live demand, completed/healthy state, and enabled controls.
+- **Muted grey**: inactive, unavailable, or zero-power values.
+
+Use the existing CSS custom properties instead of introducing page-specific
+colour values.
+
+## Plan table
+
+- The table remains horizontally scrollable on narrow screens; do not clip
+  cells or hide data to force it to fit.
+- Use compact column labels on mobile.
+- Actions remain legible pills. A split slot displays one pill for each planned
+  action.
+- Tooltips explain an action or event without duplicating visible labels.
+- Keep manual-override controls available on future slots only.
+
+## Responsive layout
+
+- Pages must not create horizontal scrolling on the document itself. Any wide
+  content belongs in a deliberately scrollable container.
+- Cards in a group should share a width and align their primary values.
+- Avoid fixed widths where a grid or flex layout can adapt to Home Assistant
+  panels, desktop windows, and mobile screens.
+
+## Accessibility and interaction
+
+- Every icon-only control needs an accessible name or visible tooltip.
+- Keep visible keyboard focus states.
+- Do not rely on colour alone to convey a planned action or warning.
+- Respect the existing light, dark and automatic theme settings.

frontend/docs/ui-conventions.md

@@ -230,7 +230,8 @@
 /*
  * Detailed action badges.
  */
-.plan-action {
+.plan-action,
+.plan-action-badge {
   display: inline-flex;
   align-items: center;
   gap: 0.35rem;
@@ -242,6 +243,19 @@
   cursor: help;
 }
 
+/* A split Predbat slot remains one editable control, with one badge per action. */
+.plan-action-multiple {
+  gap: 0.25rem;
+  padding: 0.1rem 0;
+  background: transparent;
+}
+
+.plan-action-badges {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.2rem;
+}
+
 /*
  * Active charge.
  */

frontend/src/components/PlanTable.css

@@ -750,6 +750,38 @@ function getActionType(state: string): ActionType {
   }
 }
 
+/*
+ * A charge and export plan can share one half-hour slot. Predbat supplies
+ * the two display states separately for the legacy table; its `state` field
+ * contains only the final action, so use both labels when they are present.
+ */
+function getActionTypeFromDisplayState(state?: string | null): ActionType | null {
+  if (!state) {
+    return null
+  }
+
+  if (state.includes('FrzChrg')) return 'freeze-charge'
+  if (state.includes('HoldChrg')) return 'hold-charge'
+  if (state.includes('Chrg')) return 'charge'
+  if (state.includes('FrzExp')) return 'freeze-export'
+  if (state.includes('HoldExp')) return 'hold-export'
+  if (state.includes('Exp')) return 'export'
+
+  return null
+}
+
+function getPlannedActions(row: PlanRow): ActionType[] {
+  const splitActions = [row.state_text, row.state2_text]
+    .map(getActionTypeFromDisplayState)
+    .filter((action): action is ActionType => action !== null)
+
+  if (splitActions.length > 1) {
+    return [...new Set(splitActions)]
+  }
+
+  return [getActionType(row.state)]
+}
+
 /*
  * Friendly action label.
  */
@@ -1326,7 +1358,11 @@ export default function PlanTable({
 
               const newDay = !previousRow || getDateKey(previousRow.time) !== getDateKey(row.time)
 
-              const action = getActionType(row.state)
+              const actions = getPlannedActions(row)
+
+              const action = actions[0]
+
+              const hasMultipleActions = actions.length > 1
 
               const reason = getReasonText(plan, row)
 
@@ -1386,7 +1422,7 @@ export default function PlanTable({
                           className={[
                             'plan-action',
                             'plan-tooltip-trigger',
-                            getActionClass(action),
+                            hasMultipleActions ? 'plan-action-multiple' : getActionClass(action),
                             manualOverride ? 'is-manual' : ''
                           ]
                             .filter(Boolean)
@@ -1409,9 +1445,26 @@ export default function PlanTable({
                             setOpenOverrideTime(menuOpen ? null : row.time)
                           }}
                         >
-                          {getActionIcon(action)}
+                          {hasMultipleActions ? (
+                            <span className="plan-action-badges">
+                              {actions.map((plannedAction) => (
+                                <span
+                                  key={plannedAction}
+                                  className={['plan-action-badge', getActionClass(plannedAction)].join(' ')}
+                                >
+                                  {getActionIcon(plannedAction)}
+
+                                  <span>{getActionLabel(plannedAction)}</span>
+                                </span>
+                              ))}
+                            </span>
+                          ) : (
+                            <>
+                              {getActionIcon(action)}
 
-                          <span>{getActionLabel(action)}</span>
+                              <span>{getActionLabel(action)}</span>
+                            </>
+                          )}
 
                           {rateEvent && (
                             <span className={`plan-saving-session-badge is-${rateEvent.colour}`}>

frontend/src/components/PlanTable.tsx

@@ -18,6 +18,13 @@ export type PlanRow = {
   rate_color_import?: string
 
   state: string
+  /**
+   * Legacy Predbat exposes two state labels when a slot is split between
+   * charging and exporting. The modern table uses these to display both
+   * planned actions instead of only the final state.
+   */
+  state_text?: string
+  state2_text?: string | null
   state_target: string
   state_override: string
 

frontend/src/types/plan.ts

@@ -0,0 +1,13 @@
+# Frontend fixtures
+
+Fixtures are small, anonymised API responses that capture UI edge cases. They
+make reported behaviour reproducible without access to a contributor's Home
+Assistant installation.
+
+When adding one:
+
+1. Remove real entity IDs, account IDs, addresses and dates that identify a
+   user.
+2. Keep only the fields needed to reproduce the display behaviour.
+3. Add a regression test that loads the fixture.
+4. Name it after the behaviour, not the reporter or hardware.

frontend/tests/fixtures/README.md

@@ -0,0 +1,36 @@
+{
+  "unchanged": false,
+  "plan": {
+    "rows": [
+      {
+        "time": "2099-01-01T14:00:00Z",
+        "slot_minute": 840,
+        "import_rate": 0,
+        "export_rate": 12,
+        "import_rate_adjusted": 0,
+        "export_rate_adjusted": 12,
+        "state": "Exp",
+        "state_text": "Chrg↗",
+        "state2_text": "Exp↘",
+        "state_target": "87",
+        "state_override": "",
+        "reasons": [],
+        "pv_forecast": 0.5,
+        "load_forecast": 0.3,
+        "soc_percent": 87,
+        "soc_change": 2,
+        "cost_change": -0.02,
+        "total_cost": 0.42,
+        "description": ""
+      }
+    ],
+    "reason_templates": {},
+    "currency_symbols": ["£", "p"],
+    "soc": 8.7,
+    "soc_max": 10,
+    "mode": "Control charge & discharge",
+    "num_cars": 0,
+    "car_charging_from_battery": false,
+    "car_energy_reported_load": false
+  }
+}

frontend/tests/fixtures/plan-data-split-actions.json

@@ -13,6 +13,7 @@ const require = createRequire(import.meta.url)
 const componentPath = fileURLToPath(new URL('../src/components/PlanTable.tsx', import.meta.url))
 const currencyUtilityPath = fileURLToPath(new URL('../src/utils/currency.ts', import.meta.url))
 const planUtilityPath = fileURLToPath(new URL('../src/utils/plan.ts', import.meta.url))
+const splitActionsFixturePath = fileURLToPath(new URL('./fixtures/plan-data-split-actions.json', import.meta.url))
 
 function loadTypeScriptModule(path) {
   const source = fs.readFileSync(path, 'utf8')
@@ -155,6 +156,21 @@ test('debug mode exposes the diagnostic plan values supplied by Predbat', () =>
   assert.match(html, />\(55\)</)
 })
 
+test('a split charge and export slot displays both planned actions', () => {
+  const fixture = JSON.parse(fs.readFileSync(splitActionsFixturePath, 'utf8'))
+
+  const html = renderPlanTable(false, {
+    ...plan,
+    ...fixture.plan
+  })
+
+  assert.match(html, /plan-action-multiple/)
+  assert.match(html, /plan-action-badge plan-action-charge/)
+  assert.match(html, /plan-action-badge plan-action-export/)
+  assert.match(html, />Charge<\/span>/)
+  assert.match(html, />Export<\/span>/)
+})
+
 test('future rates show a prediction indicator', () => {
   const html = renderPlanTable(false, {
     ...plan,