@mieweb/ui 0.11.0-dev.56 → 0.11.0-dev.58

package/agent/README.md

@@ -22,8 +22,8 @@ governing spec: later tickets cite it instead of re-deciding.
 | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [mieweb-ui.instructions.md](mieweb-ui.instructions.md) | The rules template. Copied verbatim to the consumer's `.github/instructions/` (VS Code Copilot auto-applies it via the `applyTo` frontmatter) and embedded, minus frontmatter, in a marked block in the consumer's `AGENTS.md` (the cross-tool convention).                                                       |
 | [init-agent.mjs](init-agent.mjs)                       | The `mieweb-ui` bin. Idempotent — rerun after upgrading `@mieweb/ui` to refresh all targets. `--experimental-agents` additionally installs the agent team below.                                                                                                                                                  |
-| [agents/](agents/)                                     | Agent templates: `mieweb-ui-design` (orchestrator) + `mieweb-ui-styling` + `mieweb-ui-install` + `mieweb-ui-a11y` + `mieweb-ui-i18n` + `mieweb-ui-migration` + `mieweb-ui-richtext` + `mieweb-ui-grids`. Installed to the consumer's `.github/agents/` behind `--experimental-agents`.                               |
-| [skills/](skills/)                                     | Skill templates: `mieweb-ui-catalog`, `mieweb-ui-tokens`, `mieweb-ui-icons` (generated — `pnpm agent:skills`, never hand-edit) + `mieweb-ui-brands`, `mieweb-ui-tailwind4`, `mieweb-ui-a11y-checklist`, `mieweb-ui-i18n-checklist`, `mieweb-ui-kerebron`, `mieweb-ui-datavis-api` (hand-written). Installed to `.github/skills/` behind `--experimental-agents`. |
+| [agents/](agents/)                                     | Agent templates: `mieweb-ui-design` (orchestrator) + `mieweb-ui-styling` + `mieweb-ui-install` + `mieweb-ui-a11y` + `mieweb-ui-i18n` + `mieweb-ui-migration` + `mieweb-ui-richtext` + `mieweb-ui-grids` + `mieweb-ui-datavis` + `mieweb-ui-views`. Installed to the consumer's `.github/agents/` behind `--experimental-agents`.                               |
+| [skills/](skills/)                                     | Skill templates: `mieweb-ui-catalog`, `mieweb-ui-tokens`, `mieweb-ui-icons` (generated — `pnpm agent:skills`, never hand-edit) + `mieweb-ui-brands`, `mieweb-ui-tailwind4`, `mieweb-ui-a11y-checklist`, `mieweb-ui-i18n-checklist`, `mieweb-ui-kerebron`, `mieweb-ui-datavis-api`, `mieweb-ui-charts`, `mieweb-ui-views` (hand-written). Installed to `.github/skills/` behind `--experimental-agents`. |
 | `evals/` _(Phase 2+)_                                  | Golden-question eval sets per specialist; the regression harness for agent knowledge.                                                                                                                                                                                                                             |
 
 Rule content is sourced from [lessons/component-policy.md](../lessons/component-policy.md);

package/agent/agents/mieweb-ui-datavis.agent.md

@@ -0,0 +1,93 @@
+---
+name: MIE UI DataVis Agent
+description: Visualization specialist for the @mieweb/ui design system — charts, maps, globes, decks and org charts (Sparkline, DataVisNitroGraph boundary, Deck, Globe, PointMap, OrgChart, TileCartogramSection, report-template sections). Invoke for choosing or configuring a chart/map/globe/deck/org-chart, their peer-dependency and CSS errors, SSR/client-boundary issues, theming of canvas-rendered visuals, and report-page composition.
+tools: ['search', 'codebase', 'fetch', 'runInTerminal']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the visualization integration fixes identified above to the codebase.
+    send: false
+---
+
+# MIE UI DataVis Agent
+
+You are the visualization specialist for the **@mieweb/ui** design system:
+charts, maps, globes, slide decks, org charts and report-page sections. You
+help consumers pick the right visual, wire its entry point, peers and CSS,
+and debug rendering/SSR/theming problems. You diagnose from evidence and
+report a minimal fix — you do not edit files (offer the **Apply Fixes**
+handoff instead).
+
+## Your sources of truth (never inline-duplicate them)
+
+- **`mieweb-ui-charts` skill** — the domain bible: the which-visual guide,
+  the entry/peers/CSS matrix, per-component props and data shapes, the
+  client-only constraints, Globe/PointMap/OrgChart traps, the YChart
+  non-export, and the symptom→fix troubleshooting table. Start every answer
+  here.
+- **`mieweb-ui-catalog` skill** — entry points, component inventory and
+  per-entry peer requirements.
+- **`mieweb-ui-datavis-api` skill** — the boundary case: when the question
+  is really a NITRO Grid/Graph over a fetched dataset.
+- The consumer's installed package — verify props against the entry's
+  `.d.ts` when in doubt; never guess.
+
+## Workflow
+
+1. **Pick the visual before configuring it.** Dataset exploration with
+   user-changeable axes is `DataVisNitroGraph` (Grids domain, not yours);
+   inline trend is `Sparkline`; real geography is `PointMap`; equal-area
+   shading is `TileCartogramSection`; narrative is `Deck`; hierarchy is
+   `OrgChart`; network showcase is `Globe`. Hand-rolled `<svg>`/canvas
+   charts or a new charting library is the finding — redirect to the family
+   first.
+2. **Check plumbing before props.** Most failures are structural: missing
+   optional peers (they don't warn at install), the two required CSS imports
+   (Leaflet, xyflow), or a client-only component rendered during SSR.
+3. **Respect the data contracts.** Deck slides are JSON-only (behavior goes
+   through `renderers`/`graphics`/`components`); OrgChart input is
+   normalized to a forest; Sparkline takes pre-bucketed points, it does not
+   aggregate.
+4. **Carry the a11y posture.** Canvas/WebGL surfaces have no accessible
+   tree — the accessible data is the companion content (PointMap's list,
+   Deck's `sr-only` tables, OrgChart's list view). Never suggest removing
+   those to "clean up" the UI.
+5. **Match the skill's troubleshooting table**, then report root cause,
+   evidence, and the smallest fix. Offer **Apply Fixes** for the edit.
+
+## Redirects
+
+- "Which component should I use?" across families → **MIE UI Design Agent**;
+  you own selection *within* the visualization family.
+- Grids, NITRO sources/columns, and `DataVisNitroGraph` configuration →
+  **MIE UI Grids Agent** (Graph is a renderer over a NITRO source).
+- Install plumbing beyond the chart peers (Tailwind setup, `styles.css`,
+  main-entry peer errors) → **MIE UI Install Agent**.
+- Token/Tailwind/brand theming of surrounding UI → **MIE UI Styling Agent**
+  (you keep the canvas-specific cases: Globe's host-resolved `theme` prop,
+  `--xy-*` mapping, `--mieweb-chart-*` palette).
+- Accessibility audits → **MIE UI A11y Agent** — with the canvas caveat
+  carried by you.
+- Deck slide *content* authoring beyond the schema (copy, markdown) → the
+  orchestrator/catalog.
+
+## Rules
+
+1. Never invent props, slide types, or capabilities — verify against the
+   `mieweb-ui-charts` skill or the installed types; these components wrap
+   third-party libraries behind deliberately curated surfaces.
+2. Never route dataset-exploration charting here-and-away from NITRO: a
+   fetched dataset the user wants to slice belongs to
+   `DataVisNitroSource` + `DataVisNitroGraph` (Grids Agent).
+3. `YChart` is not a shipped component — never recommend importing it from
+   `@mieweb/ui`; offer `OrgChart`, `DataVisNitroGraph`, or direct
+   `@mieweb/ychart` adoption.
+4. Chart peers stay out of shared barrels: never advise re-exporting
+   Globe/PointMap/OrgChart from a module that non-visualization pages
+   import — the optional peers would break every consumer of that barrel.
+5. Production maps need a licensed tile service — flag default-OSM usage in
+   anything beyond a demo.
+6. Prefer the smallest change that fixes the root cause; no visualization
+   rewrites.
+7. The installed `mieweb-ui.instructions.md` rules apply to any code you
+   recommend.

package/agent/agents/mieweb-ui-design.agent.md

@@ -31,6 +31,14 @@ handoffs:
     agent: MIE UI Grids Agent
     prompt: Handle the grid/eSheet question above (DataVis NITRO sources, columns, features, operations, eSheet Builder/Renderer) and report the minimal fix.
     send: false
+  - label: Charts & maps
+    agent: MIE UI DataVis Agent
+    prompt: Handle the visualization question above (Sparkline, Deck, Globe, PointMap, OrgChart, report sections — peers, CSS, SSR boundaries, data shapes) and report the minimal fix.
+    send: false
+  - label: Views & layout
+    agent: MIE UI Views Agent
+    prompt: Handle the views/layout question above (ViewSet, ListView/BoardView/CalendarView/GanttView, dashboards, DockablePanel/FloatingWindow, app shell — accessors, stages, persistence, dates) and report the minimal fix.
+    send: false
 ---
 
 # MIE UI Design Agent (orchestrator)
@@ -63,16 +71,17 @@ comparison tables) and `mieweb-ui-icons` (icon aliases and conventions):
 | Question is about…                                   | Delegate to            |
 | ---------------------------------------------------- | ---------------------- |
 | install / peer deps / preset / safelist / `@source`  | MIE UI Install Agent   |
-| wiring headless modules (ViewSet, SuperChat) to data | MIE UI Install Agent   |
+| wiring headless modules (SuperChat) to data          | MIE UI Install Agent   |
 | tokens, CSS vars, Tailwind classes, brands, dark     | MIE UI Styling Agent   |
 | ARIA, keyboard nav, screen readers, contrast         | MIE UI A11y Agent      |
 | translations, locale bundles, Intl formats, RTL      | MIE UI i18n Agent      |
 | migrating code to @mieweb/ui, raw-HTML compliance    | MIE UI Migration Agent |
 | rich text editors (RichEditor, TextAreaRich, EmailEditor), Kerebron peers/WASM/patches, collab, Markdown rendering | MIE UI Rich Text Agent |
 | DataVis NITRO config (sources, columns, features, operations), eSheet Builder/Renderer, grid debugging | MIE UI Grids Agent |
+| charts, maps, globes, decks, org charts (Sparkline, Deck, Globe, PointMap, OrgChart, report sections) | MIE UI DataVis Agent |
+| views & layout (ViewSet, ListView/BoardView/CalendarView/GanttView, ViewSwitcher), dashboards, DockablePanel/FloatingWindow, app shell (Sidebar, AppHeader, PageHeader) | MIE UI Views Agent |
 
-More specialists (DataVis, Views,
-SuperChat) land in later phases; until one ships, answer its domain
+More specialists (SuperChat) land in later phases; until one ships, answer its domain
 from the skills and the component docs, or defer (below).
 
 **Tie-breakers:**

package/agent/agents/mieweb-ui-grids.agent.md

@@ -65,9 +65,8 @@ you do not edit files (offer the **Apply Fixes** handoff instead).
 - Grid accessibility audits → **MIE UI A11y Agent** — but always carry the
   caveat yourself: the engine's DOM is not screen-reader friendly; keep
   critical actions reachable outside the grid.
-- Charts beyond the NITRO Graph (YChart, Deck, Globe, maps) → the DataVis
-  specialist once it ships; until then the orchestrator answers from the
-  catalog skill.
+- Charts beyond the NITRO Graph (Sparkline, Deck, Globe, maps, OrgChart,
+  report sections) → **MIE UI DataVis Agent**.
 
 ## Rules
 

package/agent/agents/mieweb-ui-install.agent.md

@@ -1,6 +1,6 @@
 ---
 name: MIE UI Install Agent
-description: Installation & setup diagnostician for the @mieweb/ui design system — peer dependencies, Tailwind 4 `@source` vs the Tailwind 3 preset/safelist, PostCSS config, CSS entry wiring, dark-mode plumbing, pnpm resolution quirks, and headless module adapters. Invoke for broken/unstyled components after install, peer-dep errors, dark mode or brand CSS not applying, or wiring ViewSet/SuperChat-style modules to app data.
+description: Installation & setup diagnostician for the @mieweb/ui design system — peer dependencies, Tailwind 4 `@source` vs the Tailwind 3 preset/safelist, PostCSS config, CSS entry wiring, dark-mode plumbing, pnpm resolution quirks, and headless module adapters. Invoke for broken/unstyled components after install, peer-dep errors, dark mode or brand CSS not applying, or wiring SuperChat-style headless modules to app data.
 tools: ['search', 'codebase', 'fetch', 'runInTerminal']
 handoffs:
   - label: Apply Fixes
@@ -63,6 +63,9 @@ hoisted; required peers belong in the app's own `package.json`.
 
 - "Which component should I use?" → **MIE UI Design Agent** (selection is the
   orchestrator's domain).
+- Wiring `ViewSet` and the other views to app data (accessors, stages,
+  `onMove`) → **MIE UI Views Agent** — you own getting the package installed;
+  the Views Agent owns the adapter.
 - Token choices, hardcoded-color audits, creating/modifying brands →
   **MIE UI Styling Agent**. You own getting brand CSS _loaded_; Styling owns
   what's _in_ it.

package/agent/agents/mieweb-ui-views.agent.md

@@ -0,0 +1,93 @@
+---
+name: MIE UI Views Agent
+description: Views & layout architect for the @mieweb/ui design system — the ViewSet system (ListView, BoardView, CalendarView, GanttView, ViewSwitcher), dashboards (DashboardWidget, CustomizableDashboard), panels (DockablePanel, FloatingWindow) and the app shell (Sidebar, AppHeader, PageHeader). Invoke for composing a page from views over shared data, wiring accessors and stages, view switching and persistence, dashboard customization, panel/window behavior, and app-shell layout questions.
+tools: ['search', 'codebase', 'fetch', 'runInTerminal']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the views/layout integration fixes identified above to the codebase.
+    send: false
+---
+
+# MIE UI Views Agent
+
+You are the views & layout architect for the **@mieweb/ui** design system:
+one collection rendered as list, board, calendar or Gantt; the dashboards
+and panels around it; and the app shell it all sits in. You help consumers
+model their page on the views-over-shared-data contract, then wire it, and
+debug state/persistence/date problems. You diagnose from evidence and
+report a minimal fix — you do not edit files (offer the **Apply Fixes**
+handoff instead).
+
+## Your sources of truth (never inline-duplicate them)
+
+- **`mieweb-ui-views` skill** — the domain bible: the which-layout guide,
+  the accessor contract, ViewSet's shared-props boundary, per-view
+  requirements and traps, dashboard persistence keys, panel modality, the
+  shell's three-headers split, and the symptom→fix troubleshooting table.
+  Start every answer here.
+- **`mieweb-ui-catalog` skill** — component inventory and selection
+  guidance across the whole system.
+- The consumer's installed package — verify props against the `.d.ts` when
+  in doubt; never guess.
+
+## Workflow
+
+1. **Model before markup.** The family's unit is *one collection, one
+   adapter, several views*: a single `ViewAccessors<T>` serves every view,
+   `stages` names the statuses, and `ViewSet` owns the shared props. If the
+   consumer is about to write per-view data massaging, that's the finding.
+2. **Check the boundaries.** Sorting/filtering/paging/export is a grid, not
+   a view; a roadmap is `GanttView` at month/quarter cadence, not a
+   component; timed day/week slots are `ScheduleCalendar`; two unrelated
+   pages are `Tabs`, not a `ViewSwitcher`.
+3. **Know who owns each piece of state.** `ViewSet.storageKey` only works
+   uncontrolled — never both; URL-driven pages own the view in the router.
+   `CustomizableDashboard` decides *per concern*: each of
+   `order`/`layout`/`hiddenIds` is independently controlled or restored
+   from `storageKey`, so mixing is supported. `FloatingWindow` and
+   `DockablePanel` never persist — the host does.
+4. **Dates are wall dates.** Items keep raw date strings; views convert via
+   `toDateTime` with a single shared `timeZone`. Any `new Date()` on a
+   date-only string in the adapter is a bug.
+5. **Carry the a11y posture.** Keyboard moves are Ctrl/Cmd+Arrow with live
+   announcements; `getHref` cards stay anchors; the calendar's
+   `role="table"` is deliberate; collapsed sidebar groups unmount. Don't
+   trade these away for visual tweaks.
+6. **Match the skill's troubleshooting table**, then report root cause,
+   evidence, and the smallest fix. Offer **Apply Fixes** for the edit.
+
+## Redirects
+
+- "Which component should I use?" across families → **MIE UI Design
+  Agent**; you own selection *within* views, dashboards, panels and shell.
+- Tables, grids, sorting/filtering/paging/export, NITRO sources →
+  **MIE UI Grids Agent** (including the grid in `ViewSet`'s `table` slot).
+- Charts/maps inside dashboard widgets or overview slots →
+  **MIE UI DataVis Agent**; you own the slot, they own the visual.
+- Marketing-site chrome (`SiteHeader`, `SiteFooter`, Hero/CTA sections) →
+  the orchestrator/catalog (marketing domain; full page templates live in
+  `/templates`).
+- Token/Tailwind/brand theming → **MIE UI Styling Agent** (you keep the
+  accent-token contract: wash + marker, never text color).
+- Accessibility and i18n/RTL audits → **MIE UI A11y Agent** / **MIE UI i18n
+  Agent** — with the structural posture above carried by you.
+
+## Rules
+
+1. Never invent props, view ids, or exports — verify against the
+   `mieweb-ui-views` skill or the installed types. There is no
+   `RoadmapView`.
+2. Never put fetching, routing, or mutation inside a view: `items` in,
+   `onOpen`/`getHref`/`onMove` out. Optimistic move handling is built into
+   the board — don't re-implement it.
+3. No view virtualizes. Thousands of rows is a `DataVisNitroGrid` problem —
+   route it, don't tune it.
+4. Keep the shared-props boundary: `items`, `accessors`, `stages`,
+   `onMove`, `timeZone`, `locale` live on `ViewSet`, never duplicated into
+   per-view overrides.
+5. Accent tokens never color text; the class strings are safelisted —
+   don't synthesize new ones.
+6. Prefer the smallest change that fixes the root cause; no page rewrites.
+7. The installed `mieweb-ui.instructions.md` rules apply to any code you
+   recommend.

package/agent/evals/README.md

@@ -22,6 +22,8 @@ These files are maintainer-side quality tooling. They are **not** shipped by
 | [migration.md](./migration.md) | Migration / compliance (incl. icons) | MIE UI Migration Agent |
 | [richtext.md](./richtext.md)   | Rich text / Kerebron editors         | MIE UI Rich Text Agent |
 | [grids.md](./grids.md)         | DataVis NITRO + eSheet grids         | MIE UI Grids Agent     |
+| [datavis.md](./datavis.md)     | Charts / maps / decks / org charts   | MIE UI DataVis Agent   |
+| [views.md](./views.md)         | Views / dashboards / panels / shell  | MIE UI Views Agent     |
 
 ## Entry format
 

package/agent/evals/datavis.md

@@ -0,0 +1,224 @@
+# Evals — Charts / maps / decks / org charts
+
+Primary agent: **MIE UI DataVis Agent**. See [README.md](./README.md) for
+format and scoring. The #606 done-when: the agent routes correctly vs the
+Grids agent (charts ≠ grids) and answers these without inventing API.
+
+### DV-1 — Chart vs grid routing (the boundary)
+
+- **Ask:** "I fetched a dataset and want a chart the user can regroup and change axes on."
+- **Expect:** That's `DataVisNitroGraph` over a `DataVisNitroSource` — the
+  Grids domain (route/defer to the Grids Agent, cite the datavis-api skill).
+  The charts family is for presentation visuals, not dataset exploration.
+- **Agent:** MIE UI Grids Agent (via the DataVis Agent's redirect)
+- **Source:** mieweb-ui-charts skill — Which visual?; grids.md GRD-14
+
+### DV-2 — Inline trend
+
+- **Ask:** "I need a tiny trend indicator inside a table cell / stat card."
+- **Expect:** `Sparkline` from the **main** entry — pure HTML, no chart
+  library, no peers. `data: SparklinePoint[]` is pre-bucketed
+  (`{ key, label?, value }`); it does not aggregate. `onSelect` makes bars
+  clickable toggles; without it the bars are read-only.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** src/components/Sparkline/Sparkline.tsx
+
+### DV-3 — Globe won't build
+
+- **Ask:** "Importing `@mieweb/ui/globe` fails to resolve `react-globe.gl`."
+- **Expect:** `/globe` needs the optional peers `react-globe.gl>=2.30.0` +
+  `three>=0.160.0` (~700KB, deliberately out of the main bundle). Optional
+  peers don't warn at install — the entry just fails without them.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** src/globe.ts header; package.json peerDependencies
+
+### DV-4 — Broken map tiles
+
+- **Ask:** "PointMap shows markers but the map looks like an unstyled tile mosaic."
+- **Expect:** Missing `import 'leaflet/dist/leaflet.css'` — the one required
+  CSS import for `/maps` (plus `leaflet>=1.9.0` as peer).
+- **Agent:** MIE UI DataVis Agent
+- **Source:** src/maps.ts header; PointMap.stories.tsx
+
+### DV-5 — SSR crash
+
+- **Ask:** "Globe/OrgChart throws `window is not defined` in my Next.js build."
+- **Expect:** Only **Globe** needs a dynamic import with `ssr: false` —
+  `react-globe.gl` touches `window` at module scope, so a Client Component
+  boundary alone still prerenders and crashes. OrgChart/Deck just need a
+  client boundary, and PointMap prerenders safely (Leaflet is
+  dynamic-imported in an effect — keep its accessible point list in the
+  initial HTML). Sparkline and the report sections are server-safe.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Globe MAINTAINERS.md; PointMap MAINTAINERS.md; entry headers
+  src/org-chart.ts, src/deck.ts
+
+### DV-6 — OrgChart missing styles
+
+- **Ask:** "OrgChart renders nodes but edges and the canvas look unstyled."
+- **Expect:** Import `@xyflow/react/dist/style.css` once; `/org-chart` also
+  needs peers `@xyflow/react>=12.0.0` + `elkjs>=0.9.0` (elkjs ~1.6MB,
+  lazy-loaded on first layout from its bundled build).
+- **Agent:** MIE UI DataVis Agent
+- **Source:** src/org-chart.ts header; OrgChart MAINTAINERS.md
+
+### DV-7 — Deck slide wants a callback
+
+- **Ask:** "How do I put an onClick handler / custom React element inside a Deck slide?"
+- **Expect:** You don't — slides are **JSON-only** (no functions, elements,
+  closures). Behavior and custom rendering come through the registries:
+  `renderers` (slide types), `graphics` (named components for
+  `{ type: 'custom', component: 'name' }`), `components` (framework
+  image/link), `labels`, `onSlideChange`.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Deck MAINTAINERS.md; Deck.tsx props
+
+### DV-8 — Map inside a deck
+
+- **Ask:** "A slide in my Deck needs a geographic map."
+- **Expect:** Register PointMap in the `graphics` map
+  (`<Deck graphics={{ map: PointMap }} />`) and reference it from a slide's
+  `graphic` field — e.g. a `chart` slide with
+  `graphic: { type: 'custom', component: 'map', props }`. A top-level
+  `{ type: 'custom' }` **slide** resolves through `renderers` instead and
+  renders nothing without one.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Deck.tsx slide resolution; Deck graphics.tsx custom lookup
+
+### DV-9 — Globe stuck in light mode
+
+- **Ask:** "After toggling dark mode, the Globe keeps its old colors."
+- **Expect:** Globe never reads CSS tokens — a fixed hex default palette
+  merges with the `theme` prop on every render, so remounting alone changes
+  nothing. Resolve brand tokens host-side and pass/update an explicit
+  `theme: GlobeTheme`.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Globe.tsx DEFAULT_THEME merge
+
+### DV-10 — Globe with no land
+
+- **Ask:** "On our locked-down network the Globe renders ocean but no continents."
+- **Expect:** Continent outlines come from the runtime `geoUrl` fetch (not
+  bundled). Pass a self-hosted GeoJSON URL, or `null` to skip land hexes.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Globe MAINTAINERS.md; Globe.tsx geoUrl
+
+### DV-11 — Custom tooltip XSS
+
+- **Ask:** "Can I put rich HTML in Globe point tooltips?"
+- **Expect:** Yes via `pointLabel`, but it returns **raw HTML** — the caller
+  owns sanitization (the default label HTML-escapes). Flag the XSS risk for
+  user-derived names.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Globe MAINTAINERS.md — tooltip HTML
+
+### DV-12 — Production tiles
+
+- **Ask:** "We're shipping PointMap to all customers — anything to change from the demo?"
+- **Expect:** The default `tileUrl` is OpenStreetMap — production/heavy use
+  must configure a licensed tile service and matching `attribution`.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** PointMap.tsx tileUrl/attribution docs
+
+### DV-13 — Map accessibility
+
+- **Ask:** "Can I set `hideList` to clean up the UI under the PointMap?"
+- **Expect:** Caution — the text list **is** the accessible data (the map is
+  `role="group"`, not an image; Leaflet canvas has no accessible tree). Only
+  hide it if the same data is rendered elsewhere on the page.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** PointMap MAINTAINERS.md — a11y model
+
+### DV-14 — Regional shading
+
+- **Ask:** "I want a US map where every state is shaded by a metric bucket and small states stay visible."
+- **Expect:** `TileCartogramSection` (`/templates`, server-safe) — every
+  region equal size, shaded by bucket. `PointMap` is for real geographic
+  positions/bubbles instead.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Reports.mdx; charts skill matrix
+
+### DV-15 — YChart import
+
+- **Ask:** "How do I import YChart from @mieweb/ui?"
+- **Expect:** You can't — YChart is a Storybook-only evaluation of the
+  `packages/ychart` submodule, **not exported from any entry**. Use
+  `OrgChart` (hierarchy) or `DataVisNitroGraph` (charting), or install
+  `@mieweb/ychart` directly and own the integration. Inventing an import
+  path FAILS.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** YChart MAINTAINERS.md; DataDisplay.mdx
+
+### DV-16 — OrgChart data hygiene
+
+- **Ask:** "My org data has a cycle and some employees point at managers that don't exist — will OrgChart crash?"
+- **Expect:** No — input is normalized to a forest: first duplicate id wins,
+  unknown-parent nodes become roots, cycles are broken. But fix the data;
+  and reason about the normalized tree, not raw `parentId`.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** OrgChart MAINTAINERS.md — buildOrgForest
+
+### DV-17 — OrgChart keyboard path
+
+- **Ask:** "Is the OrgChart canvas keyboard accessible?"
+- **Expect:** The canvas is pointer-first; the **list view** is the
+  keyboard/screen-reader path (WAI-ARIA tree pattern, default view under
+  640px). Keep it reachable; detail panel is a non-modal dialog. Full audit
+  → A11y agent.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** OrgChart MAINTAINERS.md — a11y
+
+### DV-18 — OrgChart theming
+
+- **Ask:** "How do I give each department its own color in OrgChart?"
+- **Expect:** `getGroupAccent(group, index)` returning **token names**
+  (drawn as wash + marker, never as text color); React Flow chrome themes
+  via `--xy-*` variables mapped from `--mieweb-*`. No raw hex.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** OrgChart.tsx getGroupAccent; MAINTAINERS.md theming
+
+### DV-19 — Shared barrel trap
+
+- **Ask:** "Can I re-export PointMap and Globe from our app's shared components barrel?"
+- **Expect:** No — their optional peers would hard-break every page that
+  imports the barrel without leaflet/three installed. Keep chart imports at
+  the subpath entry, inside the pages that use them.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Globe/PointMap MAINTAINERS.md — main-entry warnings
+
+### DV-20 — Deck i18n
+
+- **Ask:** "How do I localize a Deck — numbers and the chrome labels?"
+- **Expect:** `locale` (BCP-47) drives number formatting; `labels` overrides
+  the chrome strings; slide content is the host's data. There's an RTL
+  story. String audits → i18n agent.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Deck.tsx props; Deck.stories.tsx RTL
+
+### DV-21 — Chart a11y posture
+
+- **Ask:** "Are the Deck charts screen-reader accessible?"
+- **Expect:** Yes by design: every built-in chart ships an `sr-only` value
+  table and the drawing is `aria-hidden`; count-ups respect
+  `prefers-reduced-motion`. Custom `graphics` must carry the same posture.
+- **Agent:** MIE UI DataVis Agent
+- **Source:** Deck MAINTAINERS.md — a11y
+
+### DV-22 — Testing the map
+
+- **Ask:** "My vitest unit test for the PointMap page explodes inside Leaflet."
+- **Expect:** Leaflet can't run in jsdom — don't unit-test the map itself;
+  cover it in Storybook/Playwright. (Similarly: Globe has no visual
+  regression — WebGL isn't pixel-deterministic.)
+- **Agent:** MIE UI DataVis Agent
+- **Source:** PointMap MAINTAINERS.md; Globe MAINTAINERS.md
+
+### DV-23 — Canned reports
+
+- **Ask:** "We need to render existing WebChart reports with a date-range picker — which component family?"
+- **Expect:** `WebChartReportViewer` + `ReportTimeRange`/`ReportDatePicker`
+  (main entry) for canned backend reports; `ReportDashboard` for the KPI +
+  bar-chart analytics page. For report *pages*, compose the `/templates`
+  sections (Methodology, Byline, Legend, MetricStatusBadge…).
+- **Agent:** MIE UI DataVis Agent
+- **Source:** WebChartReportViewer/index.ts; Dashboards.mdx; Reports.mdx

package/agent/evals/install.md

@@ -160,14 +160,14 @@ format and scoring.
 
 ### INS-17 — Wiring headless modules
 
-- **Ask:** "How do I connect `ViewSet` (or SuperChat-style modules) to my app
+- **Ask:** "How do I connect SuperChat-style headless modules to my app
   data?"
 - **Expect:** Write an adapter in the app — the module never fetches,
-  subscribes, or navigates. Two distinct contracts: **ViewSet** (collection
-  views) takes `items`/`loading`/`error`, accessor props, promise-returning
-  `on*` callbacks (built-in optimistic UI + revert), and `onOpen` + `getHref`;
-  **SuperChatInbox** has its own props (`conversations`, `onMessageSent`,
-  `onConversationOpened`) — never hand it collection-view props.
+  subscribes, or navigates. `SuperChatInbox` has its own props
+  (`conversations`, `onMessageSent`, `onConversationOpened`) — never hand it
+  collection-view props. `ViewSet` wiring (items, accessors,
+  promise-returning `on*` callbacks) is the Views Agent's domain — redirect
+  it there.
 - **Agent:** MIE UI Install Agent
 - **Source:** agent/skills/mieweb-ui-tailwind4/SKILL.md — Wiring headless modules; lessons/wiring-headless-modules.md
 

package/agent/evals/views.md

@@ -0,0 +1,215 @@
+# Evals — Views / dashboards / panels / shell
+
+Primary agent: **MIE UI Views Agent**. See [README.md](./README.md) for
+format and scoring. The #588 done-when: the agent explains the
+views-over-shared-data model and answers these without inventing API.
+
+### VW-1 — The model
+
+- **Ask:** "My tickets page needs a list, a kanban board, and a calendar the user can switch between."
+- **Expect:** One `ViewSet` over one collection: a single
+  `ViewAccessors<WorkItem>` adapter (`getId`/`getTitle`/`getStatus`/
+  `getStart`…), `stages` naming the statuses, shared `items`/`onMove`/
+  `timeZone` on the set. Not three components with three data massages.
+- **Agent:** MIE UI Views Agent
+- **Source:** src/views/MAINTAINERS.md; Views.mdx
+
+### VW-2 — View vs grid
+
+- **Ask:** "Users want to sort, filter, and export the list view."
+- **Expect:** That's a grid, not a view — `DataVisNitroGrid` (Grids
+  domain); `ViewSet` renders it in the `table` slot rather than wrapping
+  it. `ListView` stays for the lightweight grouped list.
+- **Agent:** MIE UI Grids Agent (via the Views Agent's redirect)
+- **Source:** Views.mdx — "Tables are not a view"; mieweb-ui-views skill
+
+### VW-3 — Roadmap trap
+
+- **Ask:** "How do I import RoadmapView?"
+- **Expect:** There is no `RoadmapView` — a roadmap is `GanttView` at
+  `cadence="month" | "quarter"` with `groupByLane`; the `roadmap` view id
+  exists only to label a switcher option. Inventing the import FAILS.
+  (Editorial hand-authored year → `YearTimeline`.)
+- **Agent:** MIE UI Views Agent
+- **Source:** Views.mdx — roadmap callout; src/views/MAINTAINERS.md
+
+### VW-4 — Dates shift a day
+
+- **Ask:** "Items due 2026-03-01 show on Feb 28 for our Los Angeles users."
+- **Expect:** A `new Date('YYYY-MM-DD')` somewhere in the adapter — that
+  parses as UTC midnight, which is still Feb 28 in zones behind UTC. Keep
+  date-only strings raw in accessors (views convert via `toDateTime` as
+  wall dates) and set one shared `timeZone` on `ViewSet`.
+- **Agent:** MIE UI Views Agent
+- **Source:** src/views/types.ts toDateTime; src/views/MAINTAINERS.md
+
+### VW-5 — Empty board
+
+- **Ask:** "BoardView renders but shows no columns."
+- **Expect:** Board columns come from `stages` and require the `getStatus`
+  accessor; provide both — `stages` also orders and pins the columns.
+- **Agent:** MIE UI Views Agent
+- **Source:** BoardView.tsx; Views.mdx accessor contract
+
+### VW-6 — Keyboard drag
+
+- **Ask:** "How do keyboard users move cards on the board? dnd-kit's keyboard sensor doesn't seem wired."
+- **Expect:** By design: the board owns Ctrl/Cmd+Arrow moves directly
+  (announced via a live region); dnd-kit contributes pointer listeners
+  only, and its role attributes are suppressed so `getHref` cards stay
+  real anchors.
+- **Agent:** MIE UI Views Agent
+- **Source:** src/views/MAINTAINERS.md — board keyboard; BoardView.tsx
+
+### VW-7 — Optimistic moves
+
+- **Ask:** "Should I update my store optimistically when a card is dragged, then roll back on API failure?"
+- **Expect:** Don't re-implement it — return your mutation promise from
+  `onMove`: the board shows pending state and reverts on rejection.
+- **Agent:** MIE UI Views Agent
+- **Source:** BoardView.tsx onMove; lessons/wiring-headless-modules.md
+
+### VW-8 — View persistence
+
+- **Ask:** "I pass `view` from my router and also set `storageKey`, but the stored choice never applies."
+- **Expect:** By design — `storageKey` is ignored when `view` is
+  controlled (no double source of truth). URL-driven pages persist the
+  view in the router; drop `storageKey`. Stored reads happen post-mount so
+  SSR hydration matches.
+- **Agent:** MIE UI Views Agent
+- **Source:** ViewSet.tsx storageKey doc + mount effect
+
+### VW-9 — Overview slot
+
+- **Ask:** "The first tab of our ViewSet should be KPI tiles and quick links, not a view of the items."
+- **Expect:** That's the `overview` slot — domain content the library has
+  no opinion on; fill it with `CustomizableDashboard` + `DashboardWidget`
+  (and `QuickLinksCard`).
+- **Agent:** MIE UI Views Agent
+- **Source:** Views.mdx — "Overview is not a view"; Dashboards.mdx
+
+### VW-10 — Dashboard persistence
+
+- **Ask:** "Where does CustomizableDashboard store the user's layout, and why did it reset after we renamed the page?"
+- **Expect:** Under `storageKey`-derived keys — `{key}-portlet-order`,
+  `{key}-dashboard-layout`, `{key}-dashboard-hidden` — so changing the key
+  orphans saved state. Restore happens in a mount effect (SSR hydration
+  matches); fully controlled `order`/`layout`/`hiddenIds` is the
+  alternative.
+- **Agent:** MIE UI Views Agent
+- **Source:** CustomizableDashboard MAINTAINERS.md — persistence
+
+### VW-11 — Drag handle
+
+- **Ask:** "Where did this floating grip button in the corner of my custom dashboard widget come from?"
+- **Expect:** Nothing matched `dragHandleSelector` (default
+  `[data-slot="dashboard-widget-header"]`), so the dashboard injected a
+  floating handle — dragging always works; the selector only controls
+  handle *placement*. Add the slot attribute (or a matching selector) to
+  portal the handle into the widget's own chrome.
+- **Agent:** MIE UI Views Agent
+- **Source:** CustomizableDashboard MAINTAINERS.md — drag handles
+
+### VW-12 — Tablet drop bug
+
+- **Ask:** "On tablets, users can't drop a widget into an empty dashboard column."
+- **Expect:** Known limitation: below `lg` in 3-column mode the columns
+  flatten with `display: contents`, so an empty column has no drop box.
+  Not a consumer bug — work around via another column or wider viewport.
+- **Agent:** MIE UI Views Agent
+- **Source:** CustomizableDashboard MAINTAINERS.md — responsive edge case
+
+### VW-13 — Panel modality
+
+- **Ask:** "Users should be able to keep working on the page while the detail panel is docked, but the full-screen version should trap focus."
+- **Expect:** Exactly `DockablePanel`'s two modes: `full` is modal (focus
+  trap, `aria-modal`, background `inert`), `docked` is a non-modal
+  bottom-right strip. Host owns `mode`/`onModeChange` (and any
+  persistence). Docked content is clipped, not resized.
+- **Agent:** MIE UI Views Agent
+- **Source:** DockablePanel.tsx modality docs
+
+### VW-14 — FloatingWindow state
+
+- **Ask:** "FloatingWindow closes/forgets its minimized state when my component re-renders — where's its internal state?"
+- **Expect:** There is none for `open`/`minimized` — it's fully
+  controlled; only transient drag size/position is internal. Own the state
+  in the host, wire `MinimizedWindow` yourself; min size clamps to
+  600×400; pass `aria-label` when the title isn't plain text.
+- **Agent:** MIE UI Views Agent
+- **Source:** FloatingWindow MAINTAINERS.md
+
+### VW-15 — Three headers
+
+- **Ask:** "AppHeader, PageHeader, SiteHeader — which goes where?"
+- **Expect:** `AppHeader` = sticky top bar of the signed-in app (beside
+  `Sidebar`, slot children); `PageHeader` = the `<h1>` block inside a page
+  (not a `<header>` landmark); `SiteHeader` = marketing chrome (main-entry
+  export; the `/templates` marketing pages are its home turf).
+- **Agent:** MIE UI Views Agent
+- **Source:** Layout.mdx — "Three headers, three jobs"
+
+### VW-16 — Sidebar collapse a11y
+
+- **Ask:** "Collapsed sidebar sections unmount their items — shouldn't we just hide them with CSS to keep DOM stable?"
+- **Expect:** No — unmounting is deliberate: keyboard users must not tab
+  into invisible items, and animation height measurement depends on it.
+- **Agent:** MIE UI Views Agent
+- **Source:** Sidebar MAINTAINERS.md
+
+### VW-17 — Calendar role
+
+- **Ask:** "Axe-minded reviewer says the month view should be role=\"grid\"."
+- **Expect:** `role="table"` is deliberate — `grid` promises roving focus
+  the view doesn't implement; switching the role without adding that focus
+  model makes a11y worse. Full audit → A11y agent.
+- **Agent:** MIE UI Views Agent
+- **Source:** src/views/MAINTAINERS.md — calendar semantics
+
+### VW-18 — Scale
+
+- **Ask:** "GanttView gets sluggish with ~5,000 items."
+- **Expect:** No view virtualizes — every item renders by design.
+  Page/filter upstream, or that scale of tabular data belongs to
+  `DataVisNitroGrid` (Grids domain).
+- **Agent:** MIE UI Views Agent
+- **Source:** src/views/MAINTAINERS.md — no virtualization; Views.mdx
+
+### VW-19 — Calendar boundaries
+
+- **Ask:** "We need a week view with 30-minute appointment slots — CalendarView?"
+- **Expect:** No — `CalendarView` is a month grid over day-granularity
+  items; timed day/week slots are `ScheduleCalendar` (Date & Time family).
+- **Agent:** MIE UI Views Agent
+- **Source:** Views.mdx — "Which one?" table
+
+### VW-20 — i18n posture
+
+- **Ask:** "How do I localize the views, and is the dashboard fully translatable?"
+- **Expect:** Views: `labels` objects (English defaults) + `locale`/
+  `timeZone` shared via `ViewSet`. Dashboards have documented gaps
+  (hard-coded English strings, English-only drag announcements) — audit →
+  i18n agent.
+- **Agent:** MIE UI Views Agent
+- **Source:** src/views/types.ts ViewLabels; Dashboards.mdx limitations
+
+### VW-21 — Accent colors
+
+- **Ask:** "Can I set each stage's accent to our brand hex and color the card titles to match?"
+- **Expect:** Accents are tokens (`primary`/`success`/…), applied as wash +
+  border + marker and **never text color** (declared colours fail WCAG AA
+  on text); the class strings are safelisted — don't synthesize new ones.
+- **Agent:** MIE UI Views Agent
+- **Source:** src/views/types.ts accentClasses; src/views/MAINTAINERS.md
+
+### VW-22 — Plumbing
+
+- **Ask:** "Does the views family need peer installs, CSS imports, or ssr:false like the charts?"
+- **Expect:** No — everything exports from the main entry; `@dnd-kit/*`
+  and `luxon` are bundled regular deps; all `'use client'`, so a client
+  boundary suffices and prerender is safe; `localStorage` access is
+  try/catch-guarded. One caveat: `AppHeaderSearch`'s ⌘/Ctrl shortcut hint
+  is computed from `navigator` at module scope — server renders Ctrl, Mac
+  clients ⌘ (hydration mismatch on that hint only).
+- **Agent:** MIE UI Views Agent
+- **Source:** src/index.ts; package.json; ViewSet.tsx readStored

package/agent/skills/mieweb-ui-charts/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: mieweb-ui-charts
+description: Chart, map, globe and presentation components of @mieweb/ui — Sparkline, DataVisNitroGraph pointer, Deck slide decks, Globe, PointMap, OrgChart, TileCartogramSection and the report-template sections. Entry points, optional peers, required CSS imports, client-only constraints, data shapes, theming and a11y paths. USE WHEN selecting, configuring or debugging a chart/map/globe/deck/org-chart, resolving their peer or CSS errors, or deciding chart vs grid.
+---
+
+# @mieweb/ui charts, maps & presentation visuals
+
+Sourced from the entry-file headers (`src/deck.ts`, `src/globe.ts`,
+`src/maps.ts`, `src/org-chart.ts`), component MAINTAINERS notes, and the
+catalog pages (Presentations, Reports, Dashboards, Records, Data Display).
+
+> **Which visual?** Exploring a fetched dataset (axes the user can change)
+> → **DataVisNitroGraph** beside its grid — that's the Grids domain (see the
+> **mieweb-ui-datavis-api** skill). Tiny inline trend in a card/table row →
+> **Sparkline** (main entry, dependency-free). Full-screen narrative →
+> **Deck**. Real geographic locations → **PointMap**; equal-area regional
+> shading (every state same size) → **TileCartogramSection**; global
+> network showcase → **Globe**. Reporting lines / location hierarchy →
+> **OrgChart**. Canned backend reports → **WebChartReportViewer** /
+> **ReportDashboard** (main entry). **YChart is not a component** — it's a
+> Storybook-only evaluation of the `@mieweb/ychart` submodule; point
+> consumers at OrgChart or DataVisNitroGraph.
+
+## Entry / peers / CSS matrix
+
+| Component | Entry | Optional peers | Required CSS | Client-only? |
+| --- | --- | --- | --- | --- |
+| `Sparkline` | main `@mieweb/ui` | none | none | SSR-safe |
+| `DataVisNitroGraph` | `/datavis` | none (engine bundled) | base styles.css | yes |
+| `Deck` | `/deck` | none beyond main | built into `@mieweb/ui/styles.css` | yes (scroll/keys/fullscreen) |
+| `Globe` | `/globe` | `react-globe.gl>=2.30.0`, `three>=0.160.0` (~700KB) | none (WebGL canvas) | yes — `ssr: false` boundary |
+| `PointMap` | `/maps` | `leaflet>=1.9.0` | **`leaflet/dist/leaflet.css`** | client boundary; prerenders safely (Leaflet dynamic-imported in an effect) |
+| `OrgChart` | `/org-chart` | `@xyflow/react>=12.0.0`, `elkjs>=0.9.0` | **`@xyflow/react/dist/style.css`** | client boundary |
+| Report sections (`TileCartogramSection`, `BenchmarkTableSection`, `RankedListSection`, `MetricListSection`, `ReportMethodology`, `ReportByline`, `ReportLegend`, `MetricStatusBadge`, `LinkGroupsSection`, `PdfEmbedSection`) | `/templates` | none | base styles.css | server-safe |
+| `WebChartReportViewer`, `ReportDashboard` | main | none | base styles.css | SSR-safe |
+
+The chart peers are **optional**: installs don't warn when absent, but the
+subpath entry hard-fails to resolve without them. They are kept out of the
+main bundle deliberately — never re-export these components from your own
+shared barrel that non-map/globe pages import.
+
+## Sparkline (main entry)
+
+Pure-HTML bars, no chart library. `data: SparklinePoint[]`
+(`{ key, label?, value }` — pre-bucketed; it does not aggregate),
+`selectedKey`/`onSelect` (bars become toggle buttons; read-only without
+`onSelect`), `label`, `height` (px, default 32), `formatValue(point)` for the
+tooltip, `ariaLabel`. A11y: `role="group"` + labels; it is a glanceable
+summary, not a data-exploration surface.
+
+## Deck (`@mieweb/ui/deck`)
+
+Full-screen slide deck rendered from **JSON slides** — no functions,
+elements or closures in the slide array; site behavior arrives through
+props: `renderers` (override/add slide types; top-level `{ type: 'custom' }`
+**slides** resolve here and render nothing without one), `graphics`
+(components for a slide's `graphic: { type: 'custom', component: '<name>',
+props }` — e.g. `<Deck graphics={{ map: PointMap }} />` with a `chart`
+slide), `components` (framework
+image/link), `icons`, `labels` (chrome strings), `locale` (BCP-47 number
+formatting), `syncHash` (default true — slide deep-links in
+`location.hash`), `home`, `onSlideChange`. ~24 built-in slide types plus
+built-in graphic renderers `bar`, `horizontal-bar`, `multi-line`,
+`kpi-row`, `spark`. Fills the viewport (`h-dvh`) — hide site chrome on deck
+routes. A11y: every chart ships an `sr-only` value table, drawings are
+`aria-hidden`, count-ups respect `prefers-reduced-motion`; reveal is
+CSS-only (reduced-motion and print show everything). The window key handler
+skips typing targets and `role="tab"` elements.
+
+## Globe (`@mieweb/ui/globe`)
+
+`react-globe.gl` + three.js showcase globe. `points: GlobePoint[]`
+(`{ id, lat, lng, name, sub?, hub?, color?, timeZone?, flag?, href? }`),
+`arcs` (`kind: 'backbone' | 'spoke'`), `connectHubs`, `hexResolution` (2–4),
+`pointOfView`, `autoRotateSpeed` (respects `prefers-reduced-motion`),
+`selectedId`/`onSelect`/`onPointHover`, `callout`, `height` (default
+`clamp(360px, 54vw, 560px)`). Traps:
+
+- Globe never reads CSS tokens: a fixed hex default palette merges with the
+  `theme` prop on every render, so remounting alone changes nothing. Resolve
+  `--mieweb-*` tokens host-side and pass/update an explicit `GlobeTheme` for
+  brand or dark-mode colors.
+- `geoUrl` (continent outlines) is **fetched at runtime**, not bundled —
+  offline/locked-down hosts pass `null` (skip land hexes) or a self-hosted
+  GeoJSON URL.
+- The default `pointLabel` HTML-escapes names; a custom `pointLabel` returns
+  **raw HTML** — the caller owns sanitization.
+- Visual showcase only: the WebGL canvas has no accessible tree; put the
+  real data in accompanying text/table content.
+
+## PointMap (`@mieweb/ui/maps`)
+
+Leaflet dots/bubbles map. `points: MapPoint[]`
+(`{ lat, lng, label, value?, detail? }`), required `label` (accessible map
+name), `center`/`zoom` (seed initial state only — not reactive deps),
+`tileUrl` + `attribution` (**default is OpenStreetMap; production/heavy use
+must configure a licensed tile service**), `outlineUrl` (runtime-fetched
+GeoJSON overlays), `sizeBy: 'value' | 'none'`, `showValues`, `hideList`.
+A11y model: the map is `role="group"` with `aria-roledescription="map"`;
+**the text list under the map is the accessible data** — `hideList` opts out
+of it, so keep it unless the same data is rendered elsewhere. Colors come
+from runtime `--mieweb-*` tokens (Leaflet paints outside Tailwind). Leaflet
+cannot run in jsdom — verify map behavior in Storybook/Playwright, not unit
+tests. In a Deck, register it in `graphics` and reference it from a slide's
+`graphic: { type: 'custom', component: 'map', props }` (e.g. a `chart` slide).
+
+## OrgChart (`@mieweb/ui/org-chart`)
+
+React Flow canvas + elkjs layered layout over a **flat node list**:
+`nodes: OrgChartNode[]` (`{ id, parentId, name, title?, subtitle?, group?,
+avatarUrl?, meta? }`). The input is normalized to a forest (`buildOrgForest`
+keeps the first duplicate id, promotes unknown-parent nodes to roots, breaks
+cycles) — reason about the normalized tree, not raw `parentId`. Key props:
+`nodeVariant: 'person' | 'location'`, `direction: 'DOWN' | 'RIGHT'` (RTL
+mirrors the x-axis), `initialDepth`, `focusId`/`highlightedId`,
+`view`/`defaultView: 'chart' | 'list'` (list is the default under 640px),
+`defaultQuery`/`defaultGroup`, `getGroupAccent` (returns token names, never
+raw colors), `onSelect`/`onOpen`/`getHref`, `renderDetail`, `labels` (every
+string localizable, some are count functions), `classNames`. elkjs
+(~1.6MB) is lazy-loaded on first layout from its **bundled** build. A11y:
+the canvas is pointer-first; **the list view is the keyboard/screen-reader
+path** (full WAI-ARIA tree pattern), the detail panel is a non-modal dialog.
+Custom node content must not exceed the fixed card size (layout measures
+nothing from the DOM).
+
+## YChart (not shipped)
+
+`src/components/YChart/` is a Storybook-only evaluation wrapper around the
+`packages/ychart` git submodule (published separately as `@mieweb/ychart` —
+vanilla D3 + YAML editor with its own `--yc-color-*` theming). It is **not
+exported from any entry**. For app use: `OrgChart` (hierarchy) or
+`DataVisNitroGraph` (charting); if a consumer truly wants the YAML editor,
+they install `@mieweb/ychart` directly and own the integration.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Build fails resolving `react-globe.gl`/`three` or `@xyflow/react`/`elkjs` | Optional peers of `/globe` / `/org-chart` not installed (no install-time warning) | Install the pair listed in the matrix |
+| Map renders as a broken/unstyled tile mosaic | `leaflet/dist/leaflet.css` not imported | Import it once where `PointMap` is used |
+| OrgChart nodes float without edges/handles styling | `@xyflow/react/dist/style.css` missing | Import it once where `OrgChart` is used |
+| Globe crashes during SSR (`window is not defined`) | `react-globe.gl` touches `window` at module scope — a Client Component boundary alone still prerenders | Dynamic import with `ssr: false` (Globe only — PointMap/OrgChart/Deck need just a client boundary; PointMap prerenders its accessible point list) |
+| Globe colors stale after dark-mode toggle | Globe never reads CSS tokens — fixed hex defaults merge with `theme` each render | Resolve tokens host-side and update the `theme` prop (remount alone does nothing) |
+| Globe renders ocean but no land | `geoUrl` runtime fetch blocked (offline/CSP) | Pass `null` or a self-hosted GeoJSON URL |
+| Tile requests throttled / licensing concern | Default `tileUrl` is OpenStreetMap | Configure a licensed tile service + matching `attribution` |
+| Deck slide "needs" a callback or JSX | Slides are JSON-only by design | Move behavior into `renderers`/`graphics`/`components` registries |
+| `YChart` import not found | Not exported — Storybook-only submodule demo | Use `OrgChart` or `DataVisNitroGraph`; or install `@mieweb/ychart` directly |
+| OrgChart drops/duplicates people | Duplicate ids, unknown `parentId`, or cycles in input | Input is normalized (first-id wins, orphans become roots, cycles broken) — fix the data |
+| PointMap unit tests fail in jsdom | Leaflet can't run in jsdom | Cover with Storybook/Playwright instead |
+| Screen reader gets nothing from the map/globe | Canvas has no accessible tree | Keep PointMap's list (`hideList` off) / pair Globe with text content |

package/agent/skills/mieweb-ui-views/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: mieweb-ui-views
+description: Views & layout components of @mieweb/ui — the ViewSet system (ListView, BoardView, CalendarView, GanttView, ViewSwitcher), dashboards (DashboardWidget, CustomizableDashboard), panels (DockablePanel, FloatingWindow) and the app shell (Sidebar, AppHeader, PageHeader). The views-over-shared-data model, accessor contract, controlled/persisted state, drag-and-drop, and a11y/i18n posture. USE WHEN selecting, configuring or debugging a view/dashboard/panel/shell component, wiring views to app data, or deciding view vs grid vs tabs.
+---
+
+# @mieweb/ui views & layout
+
+Sourced from `src/views/MAINTAINERS.md` (the family's design contract),
+component source/MAINTAINERS, and `src/catalog/Views.mdx` / `Dashboards.mdx`
+/ `Layout.mdx`. Verify props against the installed `.d.ts` — never invent.
+
+## Which layout?
+
+> Most pages want **`ViewSet`** and nothing else: it renders the switcher,
+> the enabled views, and shared slots. Reach for an individual view only
+> when a page draws exactly one layout forever.
+
+- **ViewSwitcher** — users pick between layouts of *one collection*. Two
+  unrelated pages → `Tabs` instead.
+- **ListView** — scannable vertical list, optional grouping, row slot you
+  own. Rows need sorting/filtering/paging/export → DataVis NITRO (Grids
+  domain).
+- **BoardView** — items move between named stages and the stage is the
+  primary fact. Stages fixed, items never move → ListView grouped by status.
+- **CalendarView** — items land on/span calendar days; month grid is the
+  point. Timed appointments in day/week slots → `ScheduleCalendar`.
+- **GanttView** — items have start+end and overlap matters across a range.
+  One record's progress through steps → `Timeline`.
+- **A roadmap is not a component.** It is `GanttView` at
+  `cadence="month" | "quarter"` with `groupByLane`; the `roadmap` view id
+  exists only so a switcher can label it. There is no `RoadmapView` export.
+  Editorial hand-authored year → `YearTimeline`.
+- **Tables are not views.** A tabular layout of the collection is
+  `DataVisNitroGrid`, rendered in `ViewSet`'s `table` slot.
+- **Overview is not a view.** It's domain content — fill the `overview`
+  slot with `CustomizableDashboard` + `DashboardWidget`.
+
+## Entries, deps, SSR
+
+Everything in this family exports from the **main** entry — no subpath, no
+optional peers, no extra CSS (`@dnd-kit/*` and `luxon` are bundled regular
+dependencies). All are `'use client'` components; a client boundary is
+enough and prerender is safe. One caveat: `AppHeaderSearch` computes a
+guarded `isMac` from `window.navigator` at module scope, so the server
+renders the Ctrl shortcut hint and Mac clients render ⌘ — expect that
+hydration mismatch if you prerender it.
+`localStorage` access (ViewSet, CustomizableDashboard) is try/catch-guarded
+— Safari private browsing throws on *access*, optional chaining alone is
+insufficient.
+
+## The views-over-shared-data model
+
+One collection, several layouts, one adapter:
+
+- **Accessors, not records.** Views read through `ViewAccessors<T>`
+  (`getId`, `getTitle`, `getSubtitle`, `getStatus`, `getStart`, `getEnd`,
+  `getGroup`, `getAccent`) and never assume item shape. Write one adapter
+  per entity; each view uses only the accessors it needs — `BoardView`
+  requires `getStatus`, `GanttView`/`CalendarView` require `getStart`.
+- **Nothing fetches, routes, or mutates.** Views take `items` / `loading` /
+  `error` and hand changes back through `onOpen`, `getHref`, `onMove`.
+- **Dates go through `toDateTime`, never `new Date()`.** Date-only strings
+  stay wall dates; `new Date('2026-03-01')` is UTC midnight and shifts a
+  day for half the world.
+- **Accent tokens carry no text color** (`primary`/`success`/`warning`/
+  `destructive`/`info`/`neutral`) — wash + border + marker only; labels use
+  foreground tokens. The class strings are safelisted in both Tailwind
+  presets.
+- **`stages` name statuses.** They order and pin board columns and
+  `groupBy="status"` lists — and must not seed groups under other groupings.
+- **`ViewSet` owns the shared props** — `items`, `accessors`, `stages`,
+  `onMove`, `timeZone`, `locale`, load state. Per-view escape hatches
+  (`listProps` etc.) exclude them by type: one collection shows the same
+  data in every view.
+
+## ViewSet
+
+`view`/`defaultView`/`onViewChange`; `storageKey` remembers the choice but
+is **ignored when `view` is controlled** — a page with URL state owns it in
+the router. Stored value is read in a post-mount effect so server and first
+client render agree. Slots: `toolbar`, `filters`, `overview`, `table`,
+`detail` (list-plus-detail). `ViewSetLabels` is the union of every view's
+labels — not the same type as a single view's `labels` prop.
+
+## BoardView
+
+Columns come from `stages`; drag-and-drop is `@dnd-kit` **pointer listeners
+only** — dnd-kit's role attributes are deliberately suppressed so cards with
+`getHref` stay real anchors. Keyboard moves are the board's own
+Ctrl/Cmd+Arrow handling (not dnd-kit's sensor), announced via a live region;
+the selected card carries `aria-current`. `onMove` may return a promise:
+the board shows pending state and reverts on rejection — optimistic updates
+are built in, don't re-implement them.
+
+## CalendarView
+
+Month grid over Luxon. `timeZone` (IANA) sets day boundaries, `locale`
+formats month/weekday names, `weekStartsOn` is 1 (Monday) … 7 (Sunday);
+controlled `month`/`defaultMonth`; `maxPerDay` collapses overflow into a
+"+N more" row. The grid is `role="table"` **on purpose** — `role="grid"`
+promises roving focus the view doesn't implement; don't "fix" axe output by
+switching roles.
+
+## GanttView
+
+`cadence: 'day' | 'week' | 'month' | 'quarter'`; bars are visual only — no
+dependency links. Range auto-computes from item min/max when
+`rangeStart`/`rangeEnd` are omitted. The scroll region is focusable
+(`tabIndex={0}` + accessible name) — keep it that way.
+
+## Dashboards
+
+- **`DashboardWidget`** is the portlet tile (title bar, count badge, body
+  variants). It knows nothing about position.
+- **`CustomizableDashboard`** adds user drag/hide/show. Persistence:
+  `storageKey` writes **three** keys — `{key}-portlet-order`,
+  `{key}-dashboard-layout`, `{key}-dashboard-hidden` — restored in a mount
+  effect so SSR hydration matches; each of `order`/`layout`/`hiddenIds` is
+  independently controlled or persisted — mixing is supported. The drag
+  handle portals into the first element matching `dragHandleSelector`
+  (default `[data-slot="dashboard-widget-header"]`); when nothing matches,
+  a floating handle is injected in the portlet's corner — the selector
+  controls *placement*, not drag ability.
+  Known trap: below `lg` in 3-column mode the columns flatten with
+  `display: contents`, so dropping into an *empty* column has no drop box.
+
+## Panels
+
+- **`DockablePanel`** — two modes via `mode`/`onModeChange` (host persists):
+  `full` is modal (focus trap, `aria-modal`, background `inert`); `docked`
+  is a non-modal bottom-right strip you can work behind. Docked content is
+  clipped (`overflow: hidden`), not resized — embedded ResizeObservers don't
+  remeasure. Portals into `container` (default `document.body`).
+- **`FloatingWindow`** — fully controlled (`open`/`minimized` are the
+  host's); hand-rolled pointer drag/resize clamped to 600×400 minimum;
+  fixed `z-index: 50` (inline) — `--mieweb-dockable-panel-z` is
+  DockablePanel-only. Forwards a dialog
+  role — pass `aria-label` when the title isn't plain text.
+  `MinimizedWindow` is a separate export; wiring the pair is the host's job.
+
+## App shell — three headers, three jobs
+
+- **`AppHeader`** — sticky top bar of the signed-in app, beside `Sidebar`;
+  slot children (`AppHeaderBrand`/`Title`/`Search`/`IconButton`/`UserMenu`),
+  no nav opinions of its own.
+- **`PageHeader`** — the `<h1>` block inside a page (title, subtitle, icon,
+  actions, Breadcrumb/Tabs children). Not a `<header>` landmark.
+- **`SiteHeader`/`SiteFooter`** are *marketing* chrome — main-entry exports,
+  but their domain is the marketing pages (`/templates` holds the full page
+  templates that use them).
+- **`Sidebar`** — mobile drawer uses `100dvh`; collapsed nav groups
+  **unmount** rather than CSS-hide (keyboard users must not tab into
+  invisible items). Record-banner headers (`PatientHeader` etc.) are
+  clinical components, not shell.
+
+## Performance
+
+**No view virtualizes.** Every item renders; fetching/paging stays upstream.
+Hundreds of items are fine; thousands are not — that's a
+`DataVisNitroGrid` problem (Grids domain).
+
+## i18n & a11y posture
+
+Every view takes a `labels` object (English defaults); date views take
+`locale` + `timeZone` (shared via ViewSet so all views agree on day
+boundaries). Known catalog-documented gaps: dashboard strings are
+hard-coded English, drag announcements English-only, some `DashboardWidget`
+styling is physical-direction (RTL gaps). String/RTL audits belong to the
+i18n agent; views carry the structural a11y themselves.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Items land a day early for some users | `new Date('YYYY-MM-DD')` parses as UTC midnight | Keep date-only strings raw in accessors; views convert via `toDateTime` as wall dates |
+| Board renders no columns | Missing `getStatus` accessor or `stages` | Provide both; `stages` orders and pins the columns |
+| Can't drag cards with the keyboard | Expecting dnd-kit's keyboard sensor | Use Ctrl/Cmd+Arrow — the board's own handling, announced via live region |
+| Card loses link semantics when draggable | Assuming dnd-kit role attributes | They're suppressed by design; `getHref` cards stay anchors |
+| Chosen view doesn't persist | `view` is controlled, so `storageKey` is ignored | Persist in your URL/router state, or go uncontrolled |
+| Calendar/Gantt disagree on an item's day | Views given different zones | Set one `timeZone` on `ViewSet` — it's shared on purpose |
+| Dashboard order lost after refactor | `storageKey` prefix changed | It writes `-portlet-order` / `-dashboard-layout` / `-dashboard-hidden` under the key |
+| Can't drop into an empty dashboard column on tablet | `display: contents` flattening below `lg` in 3-col mode | Known limitation; move via another column or wider viewport |
+| Axe/reviewer wants calendar `role="grid"` | Grid implies roving focus the view doesn't implement | `role="table"` is deliberate — don't switch roles without adding the focus model |
+| Gantt/list sluggish with thousands of rows | No view virtualizes | Page/filter upstream, or use `DataVisNitroGrid` |
+| FloatingWindow won't stay open/minimized | It's fully controlled | Own `open`/`minimized` in host state; wire `MinimizedWindow` yourself |
+| `RoadmapView` import fails | It doesn't exist | `GanttView` with `cadence="month"|"quarter"` + `groupByLane` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mieweb/ui",
-  "version": "0.11.0-dev.56",
+  "version": "0.11.0-dev.58",
   "description": "A themeable, accessible React component library built with Tailwind CSS",
   "author": "Medical Informatics Engineering, Inc.",
   "license": "SEE LICENSE IN LICENSE",