@mieweb/ui 0.11.0-dev.55 → 0.11.0-dev.57

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`. 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` (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`. 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` (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

@@ -27,6 +27,14 @@ handoffs:
     agent: MIE UI Rich Text Agent
     prompt: Handle the rich-text question above (Kerebron editors, install legs, WASM/patches, collaboration, markdown round-trip, EmailEditor) and report the minimal fix.
     send: false
+  - label: Grids & eSheet
+    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
 ---
 
 # MIE UI Design Agent (orchestrator)
@@ -65,8 +73,10 @@ comparison tables) and `mieweb-ui-icons` (icon aliases and conventions):
 | 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 |
 
-More specialists (Grids, DataVis, Views,
+More specialists (Views,
 SuperChat) land in later phases; until one ships, answer its domain
 from the skills and the component docs, or defer (below).
 

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

@@ -0,0 +1,86 @@
+---
+name: MIE UI Grids Agent
+description: Grids specialist for the @mieweb/ui design system — DataVis NITRO (DataVisNitroSource/Grid/Graph, column API, feature flags, grouping/aggregates, operations palette, perspectives) and the eSheet form pair (Builder/Renderer, clinical fields, EncounterVisit). Invoke for configuring or debugging a NITRO grid or graph, source/column/feature questions, row selection and mass operations, grid performance with large datasets, AGGrid deprecation questions, and eSheet Builder/Renderer integration.
+tools: ['search', 'codebase', 'fetch', 'runInTerminal']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the grid/eSheet integration fixes identified above to the codebase.
+    send: false
+---
+
+# MIE UI Grids Agent
+
+You are the grids specialist for the **@mieweb/ui** design system. Consumers
+come to you after they have a grid (or know they need one) — to configure
+columns, sources and features, to wire selection and mass operations, to
+debug an empty or misbehaving grid, and to integrate the eSheet
+Builder/Renderer pair. 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-datavis-api` skill** — the domain bible: the grid policy,
+  Source/Grid/Graph architecture and context coupling, source types
+  (`http`/`local`/`file`) and declarative `groupBy`/`aggregates`, the curated
+  grid props (chrome, columns, features, operations, perspectives), the
+  no-virtualization reality, orders-grid composition patterns, the eSheet
+  pair and clinical fields, and the symptom→fix troubleshooting table. Start
+  every answer here.
+- **`mieweb-ui-catalog` skill** — entry points, the Grids family "Which one?"
+  table, and per-entry peer requirements.
+- **`mieweb-ui-kerebron` skill** — when EncounterVisit's RichEdit mode or
+  eSheet narrative fields drag in the Kerebron editor stack.
+
+## Workflow
+
+1. **Enforce the policy before configuring.** Any plain `<table>` growing
+   sort/filter/page/export features, any new `AGGrid` usage, or `Pagination`
+   bolted onto a NITRO grid is the real finding — redirect to NITRO first,
+   then configure.
+2. **Check the coupling before the props.** An empty or dead grid is usually
+   structural: Grid/Graph not nested inside a `DataVisNitroSource`, a
+   `local` source whose global isn't set at mount, or `datavis-ace` failing
+   to resolve.
+3. **Prefer declarative configuration.** `groupBy`/`aggregates` on the
+   Source, `features`/`columns`/`operations` on the Grid. Imperative
+   `setGroup`/`setAggregate` through `DataVisNitroContext` is library-internal
+   composition, not consumer API.
+4. **Be honest about limits.** There is no row virtualization and no
+   server-side row model — all operations run client-side over the fetched
+   dataset. For very large data, the fix is upstream (serve less, group,
+   aggregate), not a grid prop. Treat genuine capability gaps as NITRO
+   feature requests, never as a reason to reach for AGGrid.
+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?" → **MIE UI Design Agent** (selection is the
+  orchestrator's domain; you own configuration, APIs and debugging of a
+  chosen grid).
+- Install plumbing — Tailwind setup, `styles.css`, peer errors outside
+  `datavis-ace`/`@esheet/*` → **MIE UI Install Agent**.
+- Token/Tailwind/brand theming of surrounding UI → **MIE UI Styling Agent**.
+- 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 (Sparkline, Deck, Globe, maps, OrgChart,
+  report sections) → **MIE UI DataVis Agent**.
+
+## Rules
+
+1. Never invent grid props, feature flags, or engine capabilities — the grid
+   surface is deliberately curated; verify against the skill or the installed
+   types before recommending a prop.
+2. `AGGrid` is deprecated: never recommend it for new work; when NITRO lacks
+   a capability, say so and point to filing a NITRO feature request.
+3. Never tell a consumer to call `setGroup`/`setAggregate` on
+   `DataVisNitroContext` — declarative props only.
+4. eSheet Builder/Renderer never persist — storage always lives with the
+   host. Submission is either the Renderer's opt-in `onSubmit` button or a
+   host-driven `getValidResponse()` read (which returns
+   `{ response, errors }`, not a bare `FormResponse`) — never both.
+5. Prefer the smallest change that fixes the root cause; no grid rewrites.
+6. The installed `mieweb-ui.instructions.md` rules apply to any code you
+   recommend.

package/agent/evals/README.md

@@ -21,6 +21,8 @@ These files are maintainer-side quality tooling. They are **not** shipped by
 | [i18n.md](./i18n.md)           | Internationalization / RTL           | MIE UI i18n Agent      |
 | [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   |
 
 ## 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/grids.md

@@ -0,0 +1,241 @@
+# Evals — DataVis NITRO + eSheet grids
+
+Primary agent: **MIE UI Grids Agent**. See [README.md](./README.md) for
+format and scoring. Selection-level grid questions (Table vs NITRO) live in
+[selection.md](./selection.md); these cover configuration, APIs and
+debugging of a chosen grid.
+
+### GRD-1 — Minimal NITRO setup
+
+- **Ask:** "What's the minimal code to show a sortable, filterable grid over a JSON endpoint?"
+- **Expect:** `DataVisNitroGrid` nested inside
+  `<DataVisNitroSource type="http" url="…">` from `@mieweb/ui/datavis`;
+  parsing/type-inference automatic; sort/filter/group/export come from the
+  engine. No extra installs (`@mieweb/datavis` is bundled, `datavis-ace`
+  arrives as a dependency) and no extra CSS (base stylesheet already imports
+  the datavis styles).
+- **Agent:** MIE UI Grids Agent
+- **Source:** agent/skills/mieweb-ui-datavis-api/SKILL.md — Architecture/Source; DataVisNITRO MAINTAINERS.md
+
+### GRD-2 — Empty grid, no error
+
+- **Ask:** "My DataVisNitroGrid renders nothing and the console is clean."
+- **Expect:** Structural first: the Grid must render **inside** a
+  `DataVisNitroSource` (they're coupled through `DataVisNitroContext`); for
+  `type="local"`, `window[varName]` must be set (shaped `{ typeInfo, data }`)
+  before mount.
+- **Agent:** MIE UI Grids Agent
+- **Source:** datavis-api skill — troubleshooting; DataVisNitro.tsx
+
+### GRD-3 — Source is not a constructor
+
+- **Ask:** "I get `datavis_ace.Source is not a constructor` at runtime."
+- **Expect:** `datavis-ace` is a hard runtime requirement of
+  `DataVisNitroSource`, shipped as a regular dependency of `@mieweb/ui`
+  (external in the bundle) — it's missing or mis-resolved. Reinstall / check
+  `pnpm why datavis-ace`; never import it directly or add it manually as a
+  workaround.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataVisNITRO MAINTAINERS.md — Dependencies
+
+### GRD-4 — Local data without a server
+
+- **Ask:** "How do I feed an in-memory array of rows to a NITRO grid?"
+- **Expect:** `type="local"` + `varName`: set
+  `window[varName] = { typeInfo, data }` before mounting and delete it on
+  unmount; the engine reads the global. Changing `varName` rebuilds the
+  source.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataVisNitro.tsx — LocalDataVisNitroSourceProps; demo stories LocalDataset
+
+### GRD-5 — Column API
+
+- **Ask:** "How do I pin a column, set a header label, and render HTML in cells?"
+- **Expect:** `columns` on the grid: string = bare field name; object form
+  `{ field, header, pinned, allowHtml, … }` (plus
+  width/minWidth/maxWidth, visible, align, className,
+  typeInfo/sortable/filterable).
+- **Agent:** MIE UI Grids Agent
+- **Source:** nitro-columns.ts — DataVisNitroColumn; table/types.ts — TableColumn
+
+### GRD-6 — Grouping declaratively
+
+- **Ask:** "I'm calling `view.setGroup(…)` through DataVisNitroContext to group my grid — is that right?"
+- **Expect:** No — configure declaratively via the Source's
+  `groupBy={[ 'status' ]}` (or `{ field, functionName }`) and `aggregates`
+  (`{ functionName, fields }`). Imperative context calls are
+  library-internal composition (e.g. `OrdersGroupPresets`), not consumer
+  API, and fight the declarative props.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataVisNITRO MAINTAINERS.md — gotchas; datavis-api skill — Source
+
+### GRD-7 — Checkbox selection + bulk actions
+
+- **Ask:** "Users need to select multiple rows and run a bulk delete."
+- **Expect:** `features={{ rowSelection: 'checkbox' }}` (tri-state select-all
+  over the currently filtered rows) + an `operations` array —
+  `{ label, icon?, category?, callback(ctx) }` with `ctx.rows` as the
+  selection; surfaces in the operations palette. `onSelectionChange` for
+  host-side tracking.
+- **Agent:** MIE UI Grids Agent
+- **Source:** table/types.ts — TableFeatures; DataVisNITRO.stories.tsx — Operations
+
+### GRD-8 — Feature flags inventory
+
+- **Ask:** "What built-in behaviours can I toggle on the grid without custom code?"
+- **Expect:** `features`: columnResize, columnReorder, stickyHeaders,
+  rowSelection (true | 'checkbox'), headerContextMenu, zebraStripe,
+  keyboardNav (j/k), drillDown, showMore, rowMode ('wrapped' | 'clipped').
+  Not an invented list — anything else needs verification against the types.
+- **Agent:** MIE UI Grids Agent
+- **Source:** table/types.ts — TableFeatures
+
+### GRD-9 — Virtualization
+
+- **Ask:** "How do I turn on row virtualization for my 50k-row grid?"
+- **Expect:** You can't — the engine has **no row virtualization**; `height`
+  + show-more/limit is the scrolling story. For very large data, fix it
+  upstream: serve a narrower dataset at the http `url`, group/aggregate, or
+  page before the grid. Honest-limit answers pass; invented virtualization
+  props FAIL.
+- **Agent:** MIE UI Grids Agent
+- **Source:** datavis-api skill — Grid chrome/troubleshooting (verified: no virtualization in packages/datavis)
+
+### GRD-10 — Server-side rows?
+
+- **Ask:** "Does NITRO support a server-side row model like AG Grid Enterprise?"
+- **Expect:** No — `type="http"` fetches the dataset and **all operations run
+  client-side** over it. The server-side pattern is serving the right
+  dataset at `url`. No new AGGrid usage either (deprecated); a genuine gap
+  is a NITRO feature request.
+- **Agent:** MIE UI Grids Agent
+- **Source:** datavis-api skill — Source; MAINTAINERS.md — Prefer NITRO over AGGrid
+
+### GRD-11 — Detail rows
+
+- **Ask:** "Can a row expand to show a full-width detail panel?"
+- **Expect:** `renderDetailRow` (adds a disclosure toggle per plain-mode row)
+  + `detailRowsExpanded` to expand/collapse all; leave undefined for per-row
+  control.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataGrid.tsx — renderDetailRow/detailRowsExpanded
+
+### GRD-12 — Minimal chrome
+
+- **Ask:** "I want the grid without the title bar — just the table with a floating menu."
+- **Expect:** `mode="minimal"` (floating hamburger over the table);
+  `minimalMode` is deprecated in its favor. `'full'` restores the classic
+  title bar with row count and inline buttons; `titleActions` adds custom
+  title-bar controls (hidden in minimal mode).
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataGrid.tsx — mode/minimalMode/titleActions
+
+### GRD-13 — Perspectives on shared devices
+
+- **Ask:** "We deploy on shared kiosk machines — users' pinned grid views are leaking between logins."
+- **Expect:** Pinned-perspective names persist to localStorage by default;
+  set `persistPinnedPerspectives={false}` so pins stay in memory for the
+  session.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataGrid.tsx — persistPinnedPerspectives
+
+### GRD-14 — Grid + chart over one fetch
+
+- **Ask:** "A dashboard needs the same records as a grid and a chart the user can reconfigure — do I fetch twice?"
+- **Expect:** No — Grid and Graph are two renderers over the same
+  `DataVisNitroSource`/view; render `DataVisNitroGraph`
+  (`config`/`onConfigChange` for user-changed axes/chart type) beside the
+  grid inside one Source. Tiny inline trend → `Sparkline` instead.
+- **Agent:** MIE UI Grids Agent
+- **Source:** Grids.mdx — How they fit together; DataVisNitroGraph.tsx
+
+### GRD-15 — i18n of the grid
+
+- **Ask:** "How do I localize the grid's labels and number/date formats?"
+- **Expect:** `locale` (BCP-47) drives number/date formatting;
+  `DataVisNitroLanguageSelector` switches the engine's own UI language
+  (toolbar/table strings). `trans` only customizes built-in
+  grouping-function labels — answers presenting it as a general grid
+  translator FAIL. Deeper string audits → i18n agent.
+- **Agent:** MIE UI Grids Agent
+- **Source:** DataVisNitro.tsx — trans/locale; stories LocalizedGrid
+
+### GRD-16 — Grid accessibility
+
+- **Ask:** "Is the NITRO grid screen-reader accessible?"
+- **Expect:** Honest caveat: the engine's DOM is **not** screen-reader
+  friendly and automated a11y checks are disabled on the NITRO pages. Keep
+  critical actions reachable outside the grid; provide textual summaries for
+  charts. Full audit → A11y agent.
+- **Agent:** MIE UI Grids Agent
+- **Source:** Grids.mdx — Shared limitations
+
+### GRD-17 — Hover row actions
+
+- **Ask:** "I need per-row edit/delete buttons that appear on hover, consistent with our Table rows."
+- **Expect:** `RowActionToolbar` (main barrel) with `group="grid"` composes
+  with NITRO cells — same component as `Table` rows use.
+- **Agent:** MIE UI Grids Agent
+- **Source:** Grids.mdx — How they fit together
+
+### GRD-18 — Pagination on a NITRO grid
+
+- **Ask:** "Which component adds page controls under my NITRO grid?"
+- **Expect:** None — `Pagination` is for server-paged `Table`/card lists;
+  rows already in a NITRO grid never need it (filter/group/show-more replace
+  paging).
+- **Agent:** MIE UI Grids Agent
+- **Source:** Grids.mdx — Which one? (Pagination row)
+
+### GRD-19 — eSheet pair contract
+
+- **Ask:** "How do Builder and Renderer hand data to each other, and where's the submit button?"
+- **Expect:** Builder `onChange` emits a `FormDefinition`; Renderer takes it
+  as `formDataInput`. Reading answers: the ref's `getValidResponse()`
+  returns `{ response: FormResponse | null, errors }` (store `response`, not
+  the wrapper), or opt into the built-in submit button via
+  `onSubmit`/`submitLabel`. Persistence is host-owned either way. Entry
+  `@mieweb/ui/esheet` needs **all four** matching `@esheet/*` peers
+  (`core`/`fields`/`builder`/`renderer`, `>=0.0.6-17`) even for
+  renderer-only use.
+- **Agent:** MIE UI Grids Agent
+- **Source:** CompositeForms.mdx — the eSheet pair; src/esheet.ts
+
+### GRD-20 — Clinical fields unknown
+
+- **Ask:** "My eSheet definition uses `medicationList` but the Renderer shows an unknown field type."
+- **Expect:** Call `registerMieEsheetFields()` once before rendering
+  definitions that use the Healthcare list fields (`medicationList`,
+  `allergyList`, …) — it plugs them into both Builder and Renderer.
+- **Agent:** MIE UI Grids Agent
+- **Source:** src/esheet.ts; CompositeForms.mdx — two install surfaces
+
+### GRD-21 — EncounterVisit RichEdit stack
+
+- **Ask:** "EncounterVisit's RichEdit mode won't load in my app — what does it need beyond @esheet?"
+- **Expect:** RichEdit rides the Kerebron editor: the `@kerebron/*` peers at
+  exactly 0.8.12 + ProseMirror overrides, `@mieweb/ui/kerebron.css`, and the
+  WASM assets at `/kerebron-wasm` — the full kerebron-skill install legs
+  (route depth to the Rich Text agent / kerebron skill).
+- **Agent:** MIE UI Grids Agent
+- **Source:** src/esheet.ts header; MIGRATION.md — eSheet and EncounterVisit
+
+### GRD-22 — AGGrid escape hatch
+
+- **Ask:** "NITRO doesn't do X that AG Grid does — can I use `@mieweb/ui/ag-grid` for this one grid?"
+- **Expect:** No — `AGGrid` is deprecated, never for new work. Treat the gap
+  as a NITRO feature request (file an issue) so usages can move back; the
+  maintainers' stated policy is to close gaps in NITRO, not fall back.
+- **Agent:** MIE UI Grids Agent
+- **Source:** MAINTAINERS.md — Prefer NITRO over AGGrid; Grids.mdx policy
+
+### GRD-23 — Orders grids as the pattern
+
+- **Ask:** "We're building an order-history grid with group-by chips and bulk status updates — is there prior art?"
+- **Expect:** `ChartOrdersGrid`/`EncounterOrdersGrid` (datavis entry) over
+  the HealthSurveillance order history, with `OrdersGroupPresets` chips and
+  native NITRO `rowSelection: 'checkbox'` + `operations` for mass updates;
+  pure row builders (`buildChartOrderRows`/`buildEncounterOrderRows`) in the
+  main entry. Copy the composition, don't re-implement it.
+- **Agent:** MIE UI Grids Agent
+- **Source:** src/datavis.ts; ordersGridShared.tsx

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-datavis-api/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: mieweb-ui-datavis-api
+description: Deep API reference for @mieweb/ui grids — DataVis NITRO (DataVisNitroSource/Grid/Graph, column API, feature flags, grouping/aggregates, operations palette, perspectives) and the eSheet form pair (Builder/Renderer, registerMieEsheetFields, EncounterVisit). USE WHEN configuring or debugging a NITRO grid or graph, choosing columns/features/sources, wiring row selection and mass operations, grouping or aggregating, or integrating eSheet Builder/Renderer and its clinical fields.
+---
+
+# DataVis NITRO + eSheet in @mieweb/ui
+
+Sourced from `src/catalog/Grids.mdx`, `CompositeForms.mdx`, the DataVisNITRO
+MAINTAINERS notes, `packages/datavis` source and `MIGRATION.md`. Grid
+*selection* policy lives in the catalog skill; this is the configuration/API
+layer.
+
+## Policy (non-negotiable)
+
+> **Tables and data grids start with DataVis NITRO.** Use `Table` only for a
+> few static rows the user will not sort, filter, page or export. Never
+> hand-roll grid features on a plain table; `AGGrid` is deprecated.
+
+`Pagination` is for server-paged `Table`/card lists only — rows already in a
+NITRO grid never need it.
+
+## Architecture
+
+- Entry: **`@mieweb/ui/datavis`** — exports `DataVisNitroSource`,
+  `DataVisNitroGrid`, `DataVisNitroGraph`, `DataVisNitroContext`,
+  `DataVisNitroLanguageSelector`, plus `ChartOrdersGrid`/`EncounterOrdersGrid`
+  and `OrdersGroupPresets`.
+- **Two moving parts, zero consumer installs:** `@mieweb/datavis` (the
+  engine's React surface) is **bundled into** the entry; `datavis-ace` (the
+  data engine: fetch/parse/type-inference/aggregation) is a regular
+  **dependency** of `@mieweb/ui` — consumers never install or import either.
+- **Source and Grid are coupled through React context:** a `DataVisNitroGrid`
+  must render inside a `DataVisNitroSource` (which creates the source/view
+  pair and publishes it through `DataVisNitroContext`). **Grid** and
+  **Graph** are two renderers over the same source — a dashboard flips
+  between rows and a chart without refetching.
+- Styles: the base `@mieweb/ui/styles.css` already imports
+  `@mieweb/datavis/styles.css` — no extra CSS wiring.
+
+## DataVisNitroSource
+
+```tsx
+<DataVisNitroSource type="http" url="/api/orders.json" groupBy={['status']}>
+  <DataVisNitroGrid title="Orders" />
+</DataVisNitroSource>
+```
+
+- `type: 'http'` — `url` is fetched by the engine; parsing and type inference
+  are automatic. **All grid operations (sort/filter/group/aggregate) run
+  client-side** over the fetched dataset — there is no server-side row model;
+  the "server-side pattern" is serving the right dataset at `url`.
+- `type: 'local'` — `varName` names a global: set
+  `window[varName] = { typeInfo, data }` **before** mounting (the engine
+  reads it from `globalThis`); clean it up on unmount.
+- `type: 'file'` — user-supplied file (the engine's file picker/parse path).
+- `groupBy?: Array<string | { field, functionName? }>` and
+  `aggregates?: Array<{ functionName, fields }>` configure grouped/aggregated
+  views **declaratively**. Do not reach into `DataVisNitroContext` to call
+  `setGroup`/`setAggregate` — that context is for the library's own
+  composition (e.g. `OrdersGroupPresets`), not the consumer API.
+- Changing `type`/`url`/`varName` rebuilds the source; changing
+  `groupBy`/`aggregates` reconfigures the live view.
+
+## DataVisNitroGrid
+
+A curated surface over the engine's `DataGrid` (the maintainers deliberately
+`Omit` `view`/`children`/`allColumns` and re-add a vetted set — do not assume
+an upstream `DataGrid` prop exists here without checking the types):
+
+- **Chrome:** `title`, `helpText`, `titleActions` (title-bar React nodes),
+  `mode: 'default' | 'full' | 'minimal'` (`minimalMode` is deprecated — use
+  `mode="minimal"`), `showToolbar`, `showControls`, `height` (CSS value —
+  this plus the engine's show-more/limit is the scrolling story; **there is
+  no row virtualization**, so cap very large result sets at the source).
+- **Columns:** `columns?: Array<string | TableColumn>` — a bare string is a
+  field name; the object form is
+  `{ field, header, width/minWidth/maxWidth, visible, pinned, align,
+  className, allowHtml, typeInfo: { type, format }, sortable, filterable }`.
+  Column menus, pinning, resize/reorder persistence and saved
+  **perspectives** come from the engine (`prefs`,
+  `persistPinnedPerspectives={false}` for shared/public devices).
+- **Features** (`features?: TableFeatures`): `columnResize`, `columnReorder`,
+  `stickyHeaders`, `rowSelection: true | 'checkbox'` (checkbox mode adds a
+  tri-state select-all over the currently *filtered* rows),
+  `headerContextMenu`, `zebraStripe`, `keyboardNav` (j/k), `drillDown`,
+  `showMore`, `rowMode: 'wrapped' | 'clipped'`.
+- **Rows:** `formatCell`, `onRowClick`, `onRowDoubleClick`,
+  `onSelectionChange`, `renderDetailRow` + `detailRowsExpanded` (disclosure
+  rows), `onColumnReorder`/`onColumnResize`/`onHeaderContextMenu`.
+- **Mass operations:** `operations?: Operation[]` — each
+  `{ label, icon?, category?, callback(ctx) }` surfaces in the operations
+  palette; `ctx.rows` is the current selection. Pair with
+  `features.rowSelection: 'checkbox'` for bulk edit/delete/export flows.
+- **i18n/formatting:** `locale` (BCP-47) drives number/date formatting.
+  `DataVisNitroLanguageSelector` is the UI-language mechanism — it switches
+  the engine's own i18next language (toolbar/table strings). `trans` is
+  narrower than it looks: it only customizes the built-in grouping-function
+  labels; it does **not** translate the general grid UI.
+- **Hover row actions:** `RowActionToolbar` with `group="grid"` (main
+  barrel) composes with NITRO cells, same as with `Table` rows.
+
+## DataVisNitroGraph
+
+Same source, chart renderer: `columns`, `config?: Partial<GraphConfig>` +
+`onConfigChange` (users may change axes/chart type), `locale`, `height`,
+`className`. For a tiny inline dependency-free trend use `Sparkline` (main
+barrel) instead.
+
+## Real-world composition (orders grids)
+
+`ChartOrdersGrid` / `EncounterOrdersGrid` (this entry) are NITRO grids over
+HealthSurveillance order history; the pure row builders
+(`buildChartOrderRows`/`buildEncounterOrderRows`) live in the **main** entry.
+`OrdersGroupPresets` renders one-click group-by chips. Row selection and mass
+operations there are native NITRO features — the pattern to copy, not
+re-implement.
+
+## Accessibility caveat
+
+The DataVis engine's DOM is **not screen-reader friendly** and automated a11y
+checks are disabled on the NITRO pages. Keep critical actions reachable
+outside the grid and provide textual summaries for charts. Route full audits
+to the A11y agent.
+
+## eSheet (Builder/Renderer)
+
+- Entry: **`@mieweb/ui/esheet`**; optional peers are **all four** `@esheet/*`
+  packages — `@esheet/core`, `@esheet/fields`, `@esheet/builder`,
+  `@esheet/renderer` — at matching versions (`>=0.0.6-17`), even for
+  renderer-only use: the shared entry exports the builder too, so all four
+  must resolve. Styles: Builder and Renderer import their
+  `@esheet/styles` dependency automatically (explicit entry
+  `@esheet/styles/styles.css`); keep loading `@mieweb/ui/styles.css` for
+  composed UI components.
+- **The pair:** `EsheetBuilder` (`definition`/`onChange`) emits a
+  `FormDefinition`; `EsheetRenderer` takes that object as `formDataInput`.
+  Answers come back two ways: imperatively via the ref's
+  `getValidResponse()`, which returns `{ response: FormResponse | null,
+  errors: ValidationError[] }` (`response` is `null` while invalid — store
+  `response`, not the wrapper), or via the opt-in built-in submit button —
+  pass `onSubmit` (+ `submitLabel`) and the Renderer renders it and calls
+  back with the validated `FormResponse`; don't build a duplicate submit
+  flow next to it. **Persistence is host-owned either way** — no autosave,
+  no `name`, no server calls; the host stores definition and response.
+- **Clinical fields:** `registerMieEsheetFields()` plugs the Healthcare list
+  fields (`medicationList`, `allergyList`, …) into both Builder and
+  Renderer — call it once before rendering definitions that use them.
+- **EncounterVisit** (same entry) is the coded clinical visit document; its
+  RichEdit mode rides the Kerebron editor — the `@kerebron/*` peers, WASM
+  assets and `kerebron.css` from the **mieweb-ui-kerebron** skill apply.
+- Known gaps: upstream axe failures (contrast, unlabeled landmarks, role-less
+  drag handles) tracked in the mieweb/eSheet repo; no locale/translation
+  hooks — built-in strings are English — but layout **does** mirror under an
+  inherited `dir="rtl"` (panels swap, toolbar flips), with a handful of
+  physical-direction styling gaps tracked as an upstream eSheet RTL
+  enhancement; it themes via its own `--msprimary` tokens + `dark`
+  class, independent of `ThemeProvider`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `datavis_ace.Source is not a constructor` | `datavis-ace` missing/unresolved — it is a hard runtime requirement of `DataVisNitroSource` (ships as a regular dependency of `@mieweb/ui`, external in the bundle) | Reinstall; check the host's resolution (`pnpm why datavis-ace`) — never add it as a direct import |
+| Grid renders nothing, no error | `DataVisNitroGrid` not inside a `DataVisNitroSource` (context is null) | Nest Grid/Graph inside the Source |
+| `type="local"` grid is empty | `window[varName]` unset at mount, or not shaped `{ typeInfo, data }` | Set the global before mounting; delete it on unmount |
+| Grouping/aggregation "doesn't stick" | Imperative `setGroup`/`setAggregate` calls on the context fight the declarative props | Use the Source's `groupBy`/`aggregates` props only |
+| Huge dataset scrolls poorly | No virtualization in the engine — `height` + show-more/limit is the mechanism | Reduce the served dataset (http source), group/aggregate, or page upstream |
+| "How do I turn on pagination?" | NITRO has no page controls; `Pagination` is for server-paged `Table`/card lists | Filtering/grouping/show-more replace paging in NITRO |
+| Rows selectable but bulk action missing | `rowSelection` without `operations` | Add `operations` entries — `callback(ctx)` receives `ctx.rows` |
+| Pinned perspectives leak across users on a kiosk | Pins persist to localStorage by default | `persistPinnedPerspectives={false}` |
+| eSheet fields for meds/allergies render as unknown type | `registerMieEsheetFields()` not called | Call it once at startup before rendering such definitions |
+| eSheet looks unstyled | Very old `@esheet/*` versions required manual CSS copying | Upgrade — current Builder/Renderer import `@esheet/styles` automatically |
+| Grid needed AG Grid feature X | `@mieweb/ui/ag-grid` is deprecated | Treat the gap as a NITRO feature request (file an issue); don't start new AGGrid usage |

package/package.json

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