@sybilion/uilib 1.3.65 → 1.3.67

package/dist/agent-glossary/workspace.generated.ts

@@ -0,0 +1,272 @@
+/** Generated by scripts/build-agent-glossary.mjs — do not edit. */
+export const WORKSPACE_AGENT_UI_GLOSSARY = `Sybilion workspace page glossary (workspace profile)
+
+
+# Page layout system
+
+Sybilion workspace and report surfaces use a small set of **Page** primitives from \`@sybilion/uilib\`. Agents must compose these instead of inventing layout with inline styles, Tailwind structure classes, or ad-hoc wrappers.
+
+## Two modes
+
+| Mode               | When                                             | Shell                                                                                 |
+| ------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| **workspace-page** | Route inside \`AppShell\` / scrolled main column   | \`PageHeader\` → \`PageContent\` → \`PageContentSection\`(s). Optional \`PageTabs\`.          |
+| **content**        | Report tiles, json-dashboard, embedded body only | No \`PageHeader\` / \`AppShell\` chrome. Map React blocks to dashboard tiles (see below). |
+
+Do not nest workspace shell components inside **content** mode output.
+
+## Mandatory workspace-page skeleton
+
+\`\`\`tsx
+<PageHeader title="…" subheader="…" breadcrumbs={[…]} actions={…} />
+<PageContent>
+  <PageContentSection>{/* section A */}</PageContentSection>
+  <PageContentSection grow={false}>{/* section B */}</PageContentSection>
+</PageContent>
+\`\`\`
+
+- **PageHeader**: one per route view in the main column; title, optional subheader, breadcrumbs, actions.
+- **PageContent**: vertical stack for the body below the header; \`variant="clean"\` when you need a flatter body (no extra chrome).
+- **PageContentSection**: primary vertical band; applies horizontal **page-x-padding** via Stylus (\`pageXPadding()\`). Use multiple sections to separate logical blocks.
+
+Global tokens (host app \`:root\`, e.g. \`standalone-global.css\`): \`--page-width\`, \`--page-x-padding\`, \`--page-y-padding\`. \`PageContent\` caps width at \`--page-width\`.
+
+## PageTabs — rules and patterns
+
+**NEVER** place \`PageTabs\` inside \`PageContentSection\`. Tabs manage their own horizontal inset via \`PageXScroll\` / \`tabsListProps.withPaddings\`.
+
+### Unified (tabs + panels inside PageContent)
+
+\`\`\`tsx
+<PageHeader … />
+<PageContent>
+  <PageTabs
+    items={[
+      { value: 'a', label: 'Tab A', content: <PageContentSection>…</PageContentSection> },
+      { value: 'b', label: 'Tab B', content: <PageContentSection>…</PageContentSection> },
+    ]}
+  />
+</PageContent>
+\`\`\`
+
+Tab **panels** use \`PageContentSection\` so section padding stays correct.
+
+### Split (bar-only sibling)
+
+Use when the tab bar must sit between header and a custom scroll region:
+
+\`\`\`tsx
+<PageHeader … />
+<PageTabs
+  items={[
+    { value: 'a', label: 'Tab A', content: null },
+    { value: 'b', label: 'Tab B', content: null },
+  ]}
+/>
+<PageContent>…</PageContent>
+\`\`\`
+
+Set \`content: null\` (or omit) for bar-only items; render panel bodies in \`PageContent\` yourself.
+
+## Spacing ownership
+
+| Component              | Owns horizontal page padding?                             |
+| ---------------------- | --------------------------------------------------------- |
+| **PageContentSection** | Yes (\`pageXPadding\`)                                      |
+| **PageTabs**           | Via \`tabsListProps.withPaddings\` + internal \`PageXScroll\` |
+| **PageXScroll**        | Reads \`--page-x-padding\` for inset when used standalone   |
+| **PageHeader**         | Own header inner layout (not \`PageContentSection\`)        |
+
+Do not duplicate \`padding-left/right\` on children that already sit in \`PageContentSection\`.
+
+## Styling rules
+
+- **No** \`style={{…}}\` for layout or spacing (margins, padding, flex, width, gap).
+- **No** Tailwind (or other) utility classes for **structural** layout on page primitives.
+- Custom layout CSS only in co-located \`ComponentName.styl\`, using design tokens (\`var(--p-*)\`, \`var(--page-x-padding)\`, \`pageXPadding()\`, etc.).
+- \`className\` on Page components is for Stylus module classes or state hooks, not one-off pixel tweaks.
+
+## Component reference
+
+### PageHeader
+
+Sticky-style page title row: breadcrumbs (optional sidebar trigger in full app), \`title\`, \`subheader\`, \`actions\`. Lives **above** \`PageContent\`, never inside a section.
+
+### PageContent / PageContentSection
+
+\`PageContent\`: column flex child, \`max-width: var(--page-width)\`.  
+\`PageContentSection\`: \`grow\` (default \`true\`) lets the section absorb remaining height in flex layouts.
+
+### PageColumns
+
+Side-by-side columns with gap. **\`fill\`** controls which column(s) grow:
+
+| \`fill\`          | Behavior                                                                                        |
+| --------------- | ----------------------------------------------------------------------------------------------- |
+| \`all\` (default) | Every column \`flex-grow: 1\`, \`max-width\` unset — use for equal split or fluid grids of columns. |
+| \`left\`          | First column grows; others stay at fixed min/max column width.                                  |
+| \`right\`         | Last column grows.                                                                              |
+
+Pass \`columns={[node1, node2, …]}\`. On mobile, stacks vertically. Typical pattern: main + aside inside one \`PageContentSection\`.
+
+### PageXScroll
+
+Horizontal scroll strip; used inside \`PageTabs\` and anywhere a overflowing row needs page-aligned padding. Props: \`size\`, \`fullWidth\`, \`innerClassName\`, \`scrollbarClassName\`.
+
+### SectionHeader
+
+In-section title block (\`title\`, \`description\`, \`actions\`). Use **inside** \`PageContentSection\`, not as a replacement for \`PageHeader\`.
+
+### PageEmptyCanvas
+
+Centered empty state: \`title\`, \`hint\`, optional \`children\` (e.g. CTA button). Use when a route has no data yet.
+
+### GridLayout
+
+Responsive CSS grid (\`repeat(auto-fit, minmax(colWidth, 1fr))\`). Use for card/tile dashboards inside a section. Report mapping: dashboard **grid** rows / multi-column tile groups.
+
+### Card / Foldable
+
+Use inside sections for grouped content; see package \`AGENT.md\` on those components when present. Do not wrap the whole page in Card.
+
+## Content mode — React → json-dashboard tiles
+
+When generating **report** / dashboard specs (not workspace routes), map UI blocks to tiles:
+
+| React / intent                  | Dashboard tile / markdown                                         |
+| ------------------------------- | ----------------------------------------------------------------- |
+| \`PageHeader\` title text         | First \`markdown\` tile \`# Title\` or report title field             |
+| \`SectionHeader\` \`title\`         | \`markdown\` with \`## …\`                                            |
+| \`SectionHeader\` \`description\`   | markdown paragraph under that heading                             |
+| \`PageContentSection\` block      | group of tiles or one markdown section                            |
+| \`GridLayout\` children           | grid row of widget tiles                                          |
+| \`ChartAreaInteractive\` / charts | \`dataset_card\`, \`performance_chart\`, etc. (see widget \`AGENT.md\`) |
+| \`PageEmptyCanvas\` copy          | \`markdown\` explanatory tile                                       |
+
+See \`AGENT.report-only-tiles.md\` in the app repo for tiles without a uilib widget.
+
+## Shell components (workspace only)
+
+Not part of the per-route skeleton but part of **workspace-page** host wiring:
+
+- **AppShell** / **AppShellMainContent** — sidebar + main column + header slot + footer.
+- **PageScroll** — scroll root for the main column.
+- **SybilionAppHeader** — workspace app switcher + user menu (lives in header slot, not inside \`PageContent\`).
+
+## Anti-patterns
+
+- \`PageTabs\` inside \`PageContentSection\`.
+- Inline styles or Tailwind for page structure.
+- Second \`PageHeader\` nested in content.
+- \`PageContent\` without sections for multi-block pages (prefer multiple \`PageContentSection\`).
+- Wrapping data widgets in extra layout divs with hard-coded padding.
+
+## Future candidates (not implemented)
+
+- **PageToolbar** — dedicated action row between header and tabs.
+- **PageFullBleed** — edge-to-edge section escape hatch.
+
+Do not add these locally; extend uilib when product needs them.
+
+# SidebarDatasetsItemsGrouped
+
+Renders: expandable sidebar groups of datasets (by target type, regions, or categories).
+
+Use when: app shell needs grouped dataset navigation.
+Not when: in-page or report content (no sidebar slot).
+
+Host provides:
+
+- \`datasets\` list (\`SidebarDatasetsItemsGroupedDataset\`)
+- \`groupBy\`, \`selectedDatasetId\`, \`onDatasetClick\`
+- Optional \`preItems\` / \`postItems\`, \`defaultExpandedGroupNames\`
+
+Report tile: Not used in report tiles.
+
+Requires: \`datasets\`; \`groupBy\`; \`onDatasetClick\` for navigation.
+
+Empty/loading: empty \`datasets\` renders no groups; loading handled by host before pass-in.
+
+# ChartAreaInteractive
+
+Renders: time-series chart with historical line, forecast lines, optional pin / quantile-band / threshold overlays.
+
+Use when: custom forecast UI with overlays or full chart control.
+Not when: packaged performance or drivers-comparison views (use PerformanceChart or DriversComparisonChart).
+
+Host provides:
+
+- \`chartData\`, \`forecastData\` built from API
+- \`timeRange\` / \`onTimeRangeChange\` or brush-only range
+- Optional \`mode\`: pin | intervals | thresholds + overlay state
+- Analysis selector and fetch outside widget
+
+Report tile: \`dataset_card\` — host loads dataset + analysis; chart inside dashboard card.
+
+Requires: \`chartData\`; \`forecastData\`; \`loading\`; \`toggleLegendSeries\` / \`ensureAnalysisSeriesVisible\` when legend is external.
+
+Empty/loading: \`loading\`, \`error\`; empty data shows chart empty state via host message props.
+
+# DriverMap
+
+Renders: world map with regional driver badges, bottom strip for world-level drivers, selection highlight.
+
+Use when: geographic driver exploration for one analysis.
+Not when: driver detail metrics card alone (pair with DriverCard) or normalized series chart (use DriversComparisonChart).
+
+Host provides:
+
+- \`drivers\` as \`DriverData[]\` from analysis API
+- Controlled \`selectedDriver\` + \`setSelectedDriver\`
+- \`isLoading\` while fetching drivers
+
+Report tile: \`drivers_map\` — tile resolves analysis id, fetches drivers, passes list + selection (see EmbeddedAnalysisSelector pattern).
+
+Requires: \`drivers\`; \`isLoading\`; \`selectedDriver\`; \`setSelectedDriver\`.
+
+Empty/loading: \`isLoading\` shows overlay; empty \`drivers\` leaves map without badges.
+
+# PerformanceChart
+
+Renders: forecast performance on ChartAreaInteractive — per-horizon tab (24m window, MAE/MAPE table) and spaghetti tab (all horizons overlaid).
+
+Use when: dataset performance tab with horizon selector and error metrics.
+Not when: simple forecast card or driver backtests — use ChartAreaInteractive or DriversComparisonChart.
+
+Host provides:
+
+- \`performanceData\` (PerformanceChartPayload) and \`historicalData\` from performance API
+- Analysis selection and fetch outside widget
+- Optional \`forecastData\`, \`customPerformanceMatrix\`, \`userSeries\` for spaghetti
+
+Report tile: \`performance_chart\` — host loads performance payload + dataset series; built-in analysis selector.
+
+Requires: \`performanceData\` — model/drift forecasts and metrics; \`historicalData\` — baseline series; \`loading\` / \`chartLoading\` / \`performanceDataLoading\` — spinners; \`runAnalysisHint\` / \`statusHint\` — empty states.
+
+Empty/loading: loading props show shimmer/spinner; null \`performanceData\` with \`runAnalysisHint\` prompts to run analysis.
+
+# DriversComparisonChart
+
+Renders: target vs drivers backtests chart with ChartAreaInteractive plus table; row click toggles series visibility.
+
+Use when: drivers comparison tab with normalized target and driver series from backtests payload.
+Not when: geographic map or performance horizons — use DriverMap or PerformanceChart.
+
+Host provides:
+
+- \`payload\`: BacktestsComponentPayload from platform SDK (host fetch per analysis)
+- Optional \`datasetHistorical\` overlay
+- \`seriesInitKey\` when selected analysis changes
+- \`viewTab\` / \`onViewTabChange\`: \`lagged\` (calendar-aligned, raw dates) or \`overlapped\` (driver series shifted backward by parsed lag months)
+
+View tabs: host should render uilib \`Tabs variant="button"\` with **Lagged** / **Overlapped** in the toolbar (analysis selector left, tabs right). Chart applies \`applyDriversComparisonViewToPayload\` internally.
+
+Report tile: \`drivers_comparison_chart\` — host loads normalized backtests payload + dataset historical; built-in analysis selector.
+
+Requires: \`payload\` — target + driver normalized_series; \`loading\` / \`chartLoading\` — spinners; \`seriesInitKey\` — reset visible series on analysis or view tab change; \`runAnalysisHint\` / \`statusHint\` — empty/error text.
+
+Lag column: **Lagged** shows API \`lag\` string (may be a range). **Overlapped** shows single \`N month(s)\` from \`parseLagMonthsFromLabel\` (range uses max month).
+
+Historical window: lead-in is anchored to the **lagged** (unshifted) view (\`computeDriversComparisonHistoricalWindowFloor\`); overlapped tab shifts driver lines backward only — switching tabs does not change historical extent when floor is pinned.
+
+Empty/loading: loading props shimmer chart; null \`payload\` with \`runAnalysisHint\` prompts to run analysis.`;

package/dist/agent-glossary/workspace.md

@@ -0,0 +1,271 @@
+Sybilion workspace page glossary (workspace profile)
+
+
+# Page layout system
+
+Sybilion workspace and report surfaces use a small set of **Page** primitives from `@sybilion/uilib`. Agents must compose these instead of inventing layout with inline styles, Tailwind structure classes, or ad-hoc wrappers.
+
+## Two modes
+
+| Mode               | When                                             | Shell                                                                                 |
+| ------------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| **workspace-page** | Route inside `AppShell` / scrolled main column   | `PageHeader` → `PageContent` → `PageContentSection`(s). Optional `PageTabs`.          |
+| **content**        | Report tiles, json-dashboard, embedded body only | No `PageHeader` / `AppShell` chrome. Map React blocks to dashboard tiles (see below). |
+
+Do not nest workspace shell components inside **content** mode output.
+
+## Mandatory workspace-page skeleton
+
+```tsx
+<PageHeader title="…" subheader="…" breadcrumbs={[…]} actions={…} />
+<PageContent>
+  <PageContentSection>{/* section A */}</PageContentSection>
+  <PageContentSection grow={false}>{/* section B */}</PageContentSection>
+</PageContent>
+```
+
+- **PageHeader**: one per route view in the main column; title, optional subheader, breadcrumbs, actions.
+- **PageContent**: vertical stack for the body below the header; `variant="clean"` when you need a flatter body (no extra chrome).
+- **PageContentSection**: primary vertical band; applies horizontal **page-x-padding** via Stylus (`pageXPadding()`). Use multiple sections to separate logical blocks.
+
+Global tokens (host app `:root`, e.g. `standalone-global.css`): `--page-width`, `--page-x-padding`, `--page-y-padding`. `PageContent` caps width at `--page-width`.
+
+## PageTabs — rules and patterns
+
+**NEVER** place `PageTabs` inside `PageContentSection`. Tabs manage their own horizontal inset via `PageXScroll` / `tabsListProps.withPaddings`.
+
+### Unified (tabs + panels inside PageContent)
+
+```tsx
+<PageHeader … />
+<PageContent>
+  <PageTabs
+    items={[
+      { value: 'a', label: 'Tab A', content: <PageContentSection>…</PageContentSection> },
+      { value: 'b', label: 'Tab B', content: <PageContentSection>…</PageContentSection> },
+    ]}
+  />
+</PageContent>
+```
+
+Tab **panels** use `PageContentSection` so section padding stays correct.
+
+### Split (bar-only sibling)
+
+Use when the tab bar must sit between header and a custom scroll region:
+
+```tsx
+<PageHeader … />
+<PageTabs
+  items={[
+    { value: 'a', label: 'Tab A', content: null },
+    { value: 'b', label: 'Tab B', content: null },
+  ]}
+/>
+<PageContent>…</PageContent>
+```
+
+Set `content: null` (or omit) for bar-only items; render panel bodies in `PageContent` yourself.
+
+## Spacing ownership
+
+| Component              | Owns horizontal page padding?                             |
+| ---------------------- | --------------------------------------------------------- |
+| **PageContentSection** | Yes (`pageXPadding`)                                      |
+| **PageTabs**           | Via `tabsListProps.withPaddings` + internal `PageXScroll` |
+| **PageXScroll**        | Reads `--page-x-padding` for inset when used standalone   |
+| **PageHeader**         | Own header inner layout (not `PageContentSection`)        |
+
+Do not duplicate `padding-left/right` on children that already sit in `PageContentSection`.
+
+## Styling rules
+
+- **No** `style={{…}}` for layout or spacing (margins, padding, flex, width, gap).
+- **No** Tailwind (or other) utility classes for **structural** layout on page primitives.
+- Custom layout CSS only in co-located `ComponentName.styl`, using design tokens (`var(--p-*)`, `var(--page-x-padding)`, `pageXPadding()`, etc.).
+- `className` on Page components is for Stylus module classes or state hooks, not one-off pixel tweaks.
+
+## Component reference
+
+### PageHeader
+
+Sticky-style page title row: breadcrumbs (optional sidebar trigger in full app), `title`, `subheader`, `actions`. Lives **above** `PageContent`, never inside a section.
+
+### PageContent / PageContentSection
+
+`PageContent`: column flex child, `max-width: var(--page-width)`.  
+`PageContentSection`: `grow` (default `true`) lets the section absorb remaining height in flex layouts.
+
+### PageColumns
+
+Side-by-side columns with gap. **`fill`** controls which column(s) grow:
+
+| `fill`          | Behavior                                                                                        |
+| --------------- | ----------------------------------------------------------------------------------------------- |
+| `all` (default) | Every column `flex-grow: 1`, `max-width` unset — use for equal split or fluid grids of columns. |
+| `left`          | First column grows; others stay at fixed min/max column width.                                  |
+| `right`         | Last column grows.                                                                              |
+
+Pass `columns={[node1, node2, …]}`. On mobile, stacks vertically. Typical pattern: main + aside inside one `PageContentSection`.
+
+### PageXScroll
+
+Horizontal scroll strip; used inside `PageTabs` and anywhere a overflowing row needs page-aligned padding. Props: `size`, `fullWidth`, `innerClassName`, `scrollbarClassName`.
+
+### SectionHeader
+
+In-section title block (`title`, `description`, `actions`). Use **inside** `PageContentSection`, not as a replacement for `PageHeader`.
+
+### PageEmptyCanvas
+
+Centered empty state: `title`, `hint`, optional `children` (e.g. CTA button). Use when a route has no data yet.
+
+### GridLayout
+
+Responsive CSS grid (`repeat(auto-fit, minmax(colWidth, 1fr))`). Use for card/tile dashboards inside a section. Report mapping: dashboard **grid** rows / multi-column tile groups.
+
+### Card / Foldable
+
+Use inside sections for grouped content; see package `AGENT.md` on those components when present. Do not wrap the whole page in Card.
+
+## Content mode — React → json-dashboard tiles
+
+When generating **report** / dashboard specs (not workspace routes), map UI blocks to tiles:
+
+| React / intent                  | Dashboard tile / markdown                                         |
+| ------------------------------- | ----------------------------------------------------------------- |
+| `PageHeader` title text         | First `markdown` tile `# Title` or report title field             |
+| `SectionHeader` `title`         | `markdown` with `## …`                                            |
+| `SectionHeader` `description`   | markdown paragraph under that heading                             |
+| `PageContentSection` block      | group of tiles or one markdown section                            |
+| `GridLayout` children           | grid row of widget tiles                                          |
+| `ChartAreaInteractive` / charts | `dataset_card`, `performance_chart`, etc. (see widget `AGENT.md`) |
+| `PageEmptyCanvas` copy          | `markdown` explanatory tile                                       |
+
+See `AGENT.report-only-tiles.md` in the app repo for tiles without a uilib widget.
+
+## Shell components (workspace only)
+
+Not part of the per-route skeleton but part of **workspace-page** host wiring:
+
+- **AppShell** / **AppShellMainContent** — sidebar + main column + header slot + footer.
+- **PageScroll** — scroll root for the main column.
+- **SybilionAppHeader** — workspace app switcher + user menu (lives in header slot, not inside `PageContent`).
+
+## Anti-patterns
+
+- `PageTabs` inside `PageContentSection`.
+- Inline styles or Tailwind for page structure.
+- Second `PageHeader` nested in content.
+- `PageContent` without sections for multi-block pages (prefer multiple `PageContentSection`).
+- Wrapping data widgets in extra layout divs with hard-coded padding.
+
+## Future candidates (not implemented)
+
+- **PageToolbar** — dedicated action row between header and tabs.
+- **PageFullBleed** — edge-to-edge section escape hatch.
+
+Do not add these locally; extend uilib when product needs them.
+
+# SidebarDatasetsItemsGrouped
+
+Renders: expandable sidebar groups of datasets (by target type, regions, or categories).
+
+Use when: app shell needs grouped dataset navigation.
+Not when: in-page or report content (no sidebar slot).
+
+Host provides:
+
+- `datasets` list (`SidebarDatasetsItemsGroupedDataset`)
+- `groupBy`, `selectedDatasetId`, `onDatasetClick`
+- Optional `preItems` / `postItems`, `defaultExpandedGroupNames`
+
+Report tile: Not used in report tiles.
+
+Requires: `datasets`; `groupBy`; `onDatasetClick` for navigation.
+
+Empty/loading: empty `datasets` renders no groups; loading handled by host before pass-in.
+
+# ChartAreaInteractive
+
+Renders: time-series chart with historical line, forecast lines, optional pin / quantile-band / threshold overlays.
+
+Use when: custom forecast UI with overlays or full chart control.
+Not when: packaged performance or drivers-comparison views (use PerformanceChart or DriversComparisonChart).
+
+Host provides:
+
+- `chartData`, `forecastData` built from API
+- `timeRange` / `onTimeRangeChange` or brush-only range
+- Optional `mode`: pin | intervals | thresholds + overlay state
+- Analysis selector and fetch outside widget
+
+Report tile: `dataset_card` — host loads dataset + analysis; chart inside dashboard card.
+
+Requires: `chartData`; `forecastData`; `loading`; `toggleLegendSeries` / `ensureAnalysisSeriesVisible` when legend is external.
+
+Empty/loading: `loading`, `error`; empty data shows chart empty state via host message props.
+
+# DriverMap
+
+Renders: world map with regional driver badges, bottom strip for world-level drivers, selection highlight.
+
+Use when: geographic driver exploration for one analysis.
+Not when: driver detail metrics card alone (pair with DriverCard) or normalized series chart (use DriversComparisonChart).
+
+Host provides:
+
+- `drivers` as `DriverData[]` from analysis API
+- Controlled `selectedDriver` + `setSelectedDriver`
+- `isLoading` while fetching drivers
+
+Report tile: `drivers_map` — tile resolves analysis id, fetches drivers, passes list + selection (see EmbeddedAnalysisSelector pattern).
+
+Requires: `drivers`; `isLoading`; `selectedDriver`; `setSelectedDriver`.
+
+Empty/loading: `isLoading` shows overlay; empty `drivers` leaves map without badges.
+
+# PerformanceChart
+
+Renders: forecast performance on ChartAreaInteractive — per-horizon tab (24m window, MAE/MAPE table) and spaghetti tab (all horizons overlaid).
+
+Use when: dataset performance tab with horizon selector and error metrics.
+Not when: simple forecast card or driver backtests — use ChartAreaInteractive or DriversComparisonChart.
+
+Host provides:
+
+- `performanceData` (PerformanceChartPayload) and `historicalData` from performance API
+- Analysis selection and fetch outside widget
+- Optional `forecastData`, `customPerformanceMatrix`, `userSeries` for spaghetti
+
+Report tile: `performance_chart` — host loads performance payload + dataset series; built-in analysis selector.
+
+Requires: `performanceData` — model/drift forecasts and metrics; `historicalData` — baseline series; `loading` / `chartLoading` / `performanceDataLoading` — spinners; `runAnalysisHint` / `statusHint` — empty states.
+
+Empty/loading: loading props show shimmer/spinner; null `performanceData` with `runAnalysisHint` prompts to run analysis.
+
+# DriversComparisonChart
+
+Renders: target vs drivers backtests chart with ChartAreaInteractive plus table; row click toggles series visibility.
+
+Use when: drivers comparison tab with normalized target and driver series from backtests payload.
+Not when: geographic map or performance horizons — use DriverMap or PerformanceChart.
+
+Host provides:
+
+- `payload`: BacktestsComponentPayload from platform SDK (host fetch per analysis)
+- Optional `datasetHistorical` overlay
+- `seriesInitKey` when selected analysis changes
+- `viewTab` / `onViewTabChange`: `lagged` (calendar-aligned, raw dates) or `overlapped` (driver series shifted backward by parsed lag months)
+
+View tabs: host should render uilib `Tabs variant="button"` with **Lagged** / **Overlapped** in the toolbar (analysis selector left, tabs right). Chart applies `applyDriversComparisonViewToPayload` internally.
+
+Report tile: `drivers_comparison_chart` — host loads normalized backtests payload + dataset historical; built-in analysis selector.
+
+Requires: `payload` — target + driver normalized_series; `loading` / `chartLoading` — spinners; `seriesInitKey` — reset visible series on analysis or view tab change; `runAnalysisHint` / `statusHint` — empty/error text.
+
+Lag column: **Lagged** shows API `lag` string (may be a range). **Overlapped** shows single `N month(s)` from `parseLagMonthsFromLabel` (range uses max month).
+
+Historical window: lead-in is anchored to the **lagged** (unshifted) view (`computeDriversComparisonHistoricalWindowFloor`); overlapped tab shifts driver lines backward only — switching tabs does not change historical extent when floor is pinned.
+
+Empty/loading: loading props shimmer chart; null `payload` with `runAnalysisHint` prompts to run analysis.

package/dist/esm/components/ui/Chart/Chart.helpers.js

@@ -1,3 +1,22 @@
+function normalizeTooltipPayload(payload) {
+    if (!payload?.length)
+        return undefined;
+    const seen = new Set();
+    const result = [];
+    for (const item of payload) {
+        if (item.value === null ||
+            item.value === undefined ||
+            item.type === 'none') {
+            continue;
+        }
+        const key = String(item.dataKey ?? item.name ?? result.length);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push({ ...item });
+    }
+    return result.length ? result : undefined;
+}
 function getPayloadConfigFromPayload(config, payload, key) {
     if (typeof payload !== 'object' || payload === null) {
         return config[key];
@@ -6,4 +25,4 @@ function getPayloadConfigFromPayload(config, payload, key) {
     return config[key] || undefined;
 }
 
-export { getPayloadConfigFromPayload };
+export { getPayloadConfigFromPayload, normalizeTooltipPayload };

package/dist/esm/components/ui/Chart/components/BaseChartWrapper.js

@@ -5,6 +5,7 @@ import { getForecastColor, ChartLines } from '../../ChartAreaInteractive/ChartLi
 import { Skeleton } from '../../Skeleton/Skeleton.js';
 import { chartRenderQueue } from '../../../../utils/chartRenderQueue.js';
 import { Tooltip, LineChart, ComposedChart } from 'recharts';
+import { normalizeTooltipPayload } from '../Chart.helpers.js';
 import { resolveChartMargin, getPlotViewBox } from '../tools/chartPlotGeometry.js';
 import { formatDate } from '../tools/formatters.js';
 import S from './BaseChartWrapper.styl.js';
@@ -165,7 +166,7 @@ const BaseChartWrapperContent = forwardRef((props, ref) => {
     const renderTooltipContent = (props) => {
         // Filter payload to exclude items with null/undefined values
         // This prevents showing stale data when hovering on dates without data points
-        const filteredPayload = props.payload?.filter((item) => item.value !== null && item.value !== undefined && item.type !== 'none');
+        const filteredPayload = normalizeTooltipPayload(props.payload);
         // If no valid payload items, render ChartTooltipContent with active=false and empty payload
         // This allows ChartTooltipContent to clear its lastTooltipData state
         if (!filteredPayload || filteredPayload.length === 0) {

package/dist/esm/components/ui/Chart/components/ChartTooltipContent.js

@@ -1,8 +1,8 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
 import cn from 'classnames';
-import { useState, useEffect, useMemo } from 'react';
+import { useState, useMemo, useEffect } from 'react';
 import { useChart } from '../Chart.context.js';
-import { getPayloadConfigFromPayload } from '../Chart.helpers.js';
+import { normalizeTooltipPayload, getPayloadConfigFromPayload } from '../Chart.helpers.js';
 import S from '../Chart.styl.js';
 import { ChartTooltipItem } from './ChartTooltipItem.js';
 
@@ -10,28 +10,31 @@ function ChartTooltipContent({ active, className, indicator = 'dot', hideLabel =
     const { config } = useChart();
     // Keep last tooltip data in state to maintain position when inactive
     const [lastTooltipData, setLastTooltipData] = useState(null);
+    const normalizedPayload = useMemo(() => normalizeTooltipPayload(payload), [payload]);
     // Update last tooltip data when active
     useEffect(() => {
-        // Clear lastTooltipData immediately if label changed (prevents stale data)
-        // Only clear if label is explicitly provided and different (not undefined)
-        if (lastTooltipData && label && lastTooltipData.label !== label) {
-            setLastTooltipData(null);
-        }
-        if (active && payload?.length) {
-            setLastTooltipData({
-                active,
-                payload: payload,
-                label,
-            });
-        }
-        // Don't clear lastTooltipData when mouse moves out - keep it for position maintenance
-        // It will be cleared when label changes (above) or when new active data arrives
-    }, [active, payload, label]);
-    // Use last tooltip data if current is inactive, otherwise use current
-    // lastTooltipData is already cleared in useEffect if label changed, so safe to use here
-    active || (lastTooltipData?.active ?? false);
-    const displayPayload = active && payload?.length
-        ? payload
+        setLastTooltipData(prev => {
+            // Clear when label changed (prevents stale data)
+            let next = prev;
+            if (prev && label && prev.label !== label) {
+                next = null;
+            }
+            if (active && normalizedPayload?.length) {
+                return {
+                    active: true,
+                    payload: normalizedPayload,
+                    label,
+                };
+            }
+            // Keep frozen snapshot when inactive (position maintenance in BaseChartWrapper)
+            if (!active && next) {
+                return { ...next, active: false };
+            }
+            return next;
+        });
+    }, [active, normalizedPayload, label]);
+    const displayPayload = active && normalizedPayload?.length
+        ? normalizedPayload
         : lastTooltipData?.payload;
     const displayLabel = active ? label : lastTooltipData?.label;
     const tooltipLabel = useMemo(() => {