# WODA 2.4.5 — Auto-populate Overview on What-panel click (v3)

**Date:** 2026-05-21 (revised after empirical investigation)
**Scope:** WODA version **2.4.5 only**
**Author:** Hannes Nortje (with Claude Code)
**Status:** Final after multiple iterations. Supersedes v1 (`WhatPanel.class.js` target — incorrect) and v2 (`WhatPanel.class.js` target with conditional — incorrect).

## Goal

When a non-array item is clicked in the WODA What panel and the item's `ucpComponent` is a direct `UcpComponent` (not a subclass with its own `handleSelection`), enforce:

- `detailsView` opens in the **Details** panel (existing 2.4.5 behavior — Attributes editor)
- `defaultView` opens in the **Overview** panel (new behavior — gauge canvas, etc.)

For items whose `ucpComponent` is a `DefaultWebItem` (the WebItem-based hierarchy — Partners, Canvas Gauges category, etc.), the existing `WebItem.handleSelection` logic continues to apply unchanged: `overView` (the children-list summary) opens in Overview via line 466, `defaultView` opens in Details via line 474.

## Behavioral contract (post-fix)

| Item ucpComponent | Click result |
|---|---|
| `CanvasGauges` (e.g. Generic Gauge) | Overview gets `defaultView` (gauge canvas), Details gets `detailsView` (Attributes) — **NEW** |
| `DefaultWebItem` (e.g. Partners) | Overview gets `overView` (partner list), Details gets `defaultView` (Cerulean Circle content) — unchanged from 2.4.5 |
| Array-model items | `OverView.ACTION_SHOW` only — unchanged |

## Why this scope (and not WhatPanel.class.js)

Investigation revealed two facts that changed the design from v1/v2:

1. **`WhatPanel.handleSelection`'s else-branch is unreachable for the gauge case.** The handler recurses into `ucpComponent.handleSelection` for any ucpComponent that has its own handler. For CanvasGauges items, recursion lands in `UcpComponent.handleSelection`, never reaching WhatPanel's dispatch.

2. **The handler chain for CanvasGauges is `UcpComponent.handleSelection`** (located in `UcpComponentSupport.class.js:3337`), NOT `DefaultWebItem.handleSelection`. CanvasGauges extends `UcpComponent` directly; its handleSelection inherits from the UcpComponent base.

A single-line addition in `UcpComponent.handleSelection`'s non-array branch dispatches `OverView.ACTION_OPEN` alongside the existing `DetailsView.ACTION_SHOW`. This routes the defaultView to Overview while preserving the detailsView in Details.

Because `DefaultWebItem.handleSelection` overrides this method, items in the WebItem hierarchy (Partners, etc.) are untouched — their existing behavior (overView in Overview via line 466, defaultView in Details via line 474) is preserved. Navigation through nested WebItems (Partners → Canvas Gauges link) continues to work.

## Architecture

WODA panels communicate via the action bus implemented in `Components/tla/EAM/layer1/OnceServices/EventService/2.4.5/`. The fix adds one `Action.do` call to `UcpComponent.handleSelection`'s existing dispatch sequence. No new bus, no new class, no new action constant.

The "Generic Gauge" tab is added to OverviewPanel's tabPanel and (via DOM move semantics in TabPanel.add) is auto-activated. The `DetailsView.ACTION_SHOW` dispatch unchanged — adds Attributes editor to DetailsPanel.

## Files touched

| File | Change |
|---|---|
| `Components/tla/EAMD/UcpComponentSupport/2.4.5/src/js/UcpComponentSupport.class.js` | Add one line at `3373`: `Action.do(OverView.ACTION_OPEN, ucpComponent);` immediately after the existing `Action.do(DetailsView.ACTION_SHOW, ucpComponent);` in `UcpComponent.handleSelection`'s non-array branch |
| `Components/com/ceruleanCircle/EAM/5_ux/WODA/2.4.5/test/py_tests/1.0.0/TestWodaCanvasGauges.py` | Already extended in commits `b46dda3d8` + `849a3c6c6` with `click_generic_gauge_and_assert_overview_renders`. The assertion (canvas in Overview) should now pass. |

Nothing else is touched.

## Data flow (after fix)

```
User clicks <b>Generic Gauge</b> in What panel
  │
  ▼
DefaultItemView.select(event) → fires "selected" event on ucpComponent.eventSupport
  │
  ▼
WhatPanel.handleSelection(event, item:DefaultItemView)
  │
  ▼ ucpComponent = UcpComponentSupport.getUcpComponent4Object(item)
  │   → ucpComponent has handleSelection → RECURSE
  │
  ▼ (recursion eventually reaches CanvasGauges instance)
  │
UcpComponent.handleSelection(event, ucpComponent:CanvasGauges)
  │
  ▼ (non-array branch — Generic Gauge isn't an array)
  │
  Action.do(ActionsPanel.ACTION_SET_PRIMARY, DetailsView.ACTION_SHOW)
  Action.do(DetailsView.ACTION_SHOW, ucpComponent)   ◄── existing
  Action.do(OverView.ACTION_OPEN, ucpComponent)      ◄── NEW
  Action.do(Workflow.ACTION_SELECT, ucpComponent)
  │
  ├── DetailsPanel.show → adds detailsView (Attributes) to Details
  └── OverviewPanel.open → adds defaultView (gauge canvas) to Overview
```

For Partners click, the chain takes a different path that terminates in `DefaultWebItem.handleSelection` (in `WebItem.class.js`), which already dispatches `OverView.ACTION_SHOW` for items-with-children — populating Overview with the partner list. That path is unchanged by this fix.

## Edge cases

- **Item is a DefaultWebItem (Partners, etc.)** — `UcpComponent.handleSelection` is not invoked; instead `DefaultWebItem.handleSelection` runs with its existing dispatches. The new line has no effect on this path.
- **Item is a direct UcpComponent (CanvasGauges, etc.)** — `UcpComponent.handleSelection` runs; the new dispatch adds defaultView to Overview.
- **defaultView already in Overview** — `OverviewPanel._completeOpen`'s `closeCurrentView` guard returns `DO_NOT_CLOSE` if the current Overview tab is for the same ucpComponent. The add is skipped.
- **defaultView in Details** (from a prior drag-drop) — `OverviewPanel.open` adds defaultView to Overview's tabPanel; the existing DOM movement semantics (a view's element being appended to a new container removes it from the old) evict it from Details automatically.
- **Array items** — handled by the existing array branch of `UcpComponent.handleSelection` (`OverView.ACTION_SHOW`). Unchanged.

## Testing

`TestWodaCanvasGauges.py` already extended with `click_generic_gauge_and_assert_overview_renders` (commits `b46dda3d8` + `849a3c6c6`). The XPath assertion looks for a `<canvas>` inside the Overview panel container. With the fix applied, the gauge canvas is in an active, visible Overview tab — the existing XPath should match.

If the Selenium test fails after the fix lands, the cause is most likely the test's drag-drop precondition (drops `component.xml` on Overview drop-zone, not Details). Targeted Selenium-level adjustments (e.g., explicitly activating the Overview tab before the assertion, or broadening the XPath) are in scope.

## Out of scope (YAGNI)

- Changes to `WhatPanel.class.js` — verified unnecessary (the else-branch is unreachable for the gauge case).
- Changes to `WebItem.class.js` — verified unnecessary; would break Partners navigation.
- Changes to `DetailsPanel.class.js:76` (the sensor fix) — kept as-is.
- 2.4.4 behavior — reference only; the 2.4.4 mechanism relied on an accidental stale-bind cache that was intentionally removed in 2.4.5.

## Acceptance criteria

1. With the fix applied, `UcpComponent.handleSelection`'s non-array branch dispatches `OverView.ACTION_OPEN` after the existing `DetailsView.ACTION_SHOW`.
2. Live demo flow: Navigate What → What can I do → Partners → Canvas Gauges → Here in our Repository, then drag hockey puck of `CanvasGauges.component.xml` onto Details panel-heading, then click `<b>Generic Gauge</b>`:
   - Overview shows the rendered gauge canvas (39.8°C dial, active tab)
   - Details shows the Attributes editor for Generic Gauge
   - No duplicate Generic Gauge tabs
3. Partners click (and other WebItem-based items) behave exactly as before — overView in Overview, defaultView in Details, Canvas Gauges link visible for further navigation.
4. The extended `TestWodaCanvasGauges.py` passes end-to-end (or, if it fails due to the drag-drop precondition, the test is adjusted in scope to fit the new dispatch contract).
5. The final delta is one new line in `UcpComponentSupport.class.js`, plus the already-committed test extension.