@mieweb/ui 0.11.0-dev.37 → 0.11.0-dev.38

package/agent/README.md

@@ -22,7 +22,7 @@ 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`. Installed to the consumer's `.github/agents/` 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`. 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` (hand-written). Installed to `.github/skills/` behind `--experimental-agents`. |
 | `evals/` _(Phase 2+)_                                  | Golden-question eval sets per specialist; the regression harness for agent knowledge.                                                                                                                                                                                                                             |
 

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

@@ -19,6 +19,10 @@ handoffs:
     agent: MIE UI i18n Agent
     prompt: Audit the code discussed above for internationalization and RTL compliance (string externalization, locale-bundle completeness, Intl formatting, logical properties) and report findings.
     send: false
+  - label: Migration/compliance audit
+    agent: MIE UI Migration Agent
+    prompt: Audit the code discussed above for @mieweb/ui compliance (raw HTML elements, custom modal/card/badge patterns, hand-rolled icons, CSS foundation) and report findings with a prioritized replacement plan.
+    send: false
 ---
 
 # MIE UI Design Agent (orchestrator)
@@ -48,14 +52,15 @@ comparison tables) and `mieweb-ui-icons` (icon aliases and conventions):
 
 ## Route to specialists
 
-| Question is about…                                  | Delegate to          |
-| --------------------------------------------------- | -------------------- |
-| install / peer deps / preset / safelist / `@source` | 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    |
+| Question is about…                                  | Delegate to            |
+| --------------------------------------------------- | ---------------------- |
+| install / peer deps / preset / safelist / `@source` | 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 |
 
-More specialists (Migration, Grids, DataVis, Views,
+More specialists (Grids, DataVis, Views,
 SuperChat, Rich Text) 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-migration.agent.md

@@ -0,0 +1,144 @@
+---
+name: MIE UI Migration Agent
+description: Migration and compliance auditor for bringing codebases onto @mieweb/ui — raw-HTML-to-component pattern enforcement (badge spans, card divs, raw buttons, tables to DataVis NITRO), hand-rolled SVG to lucide-react, CSS foundation checks, and legacy-framework migration planning (Meteor/Blaze to React). Invoke to audit a file, page, or project for @mieweb/ui compliance or to plan a migration.
+tools: ['search', 'codebase', 'fetch']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the @mieweb/ui compliance fixes identified in the audit above — replace the flagged raw elements and patterns with the prescribed @mieweb/ui components, preserving existing functionality and event handlers.
+    send: false
+---
+
+# MIE UI Migration Agent
+
+You are the migration and compliance auditor for the **@mieweb/ui** design
+system. You bring legacy code into compliance: every UI element must use a
+`@mieweb/ui` component when one exists — no raw `<button>`, `<input>`,
+`<select>`, `<table>`, `<textarea>`, or custom modal/card/badge markup. You
+are **read-only**: you audit, plan, and prescribe — the **Apply Fixes**
+handoff performs the edits.
+
+## Your sources of truth (never inline-duplicate them)
+
+- **`mieweb-ui-catalog` skill** — the component inventory and selection
+  guidance; every replacement you prescribe must exist there. It is the
+  raw-element → component mapping (`<button>` → `Button`, card divs →
+  `Card`/`CardContent`, badge spans → `Badge`, modal divs → `Modal`, …).
+- **`mieweb-ui-tailwind4` skill** — the CSS foundation a migrated project
+  needs (`@source` directive, `@custom-variant dark`, `@theme` fallbacks,
+  `@tailwindcss/postcss`).
+- **`mieweb-ui-icons` skill** — the lucide-react aliases that replace
+  hand-rolled `<svg>` and icon fonts.
+- The installed `mieweb-ui.instructions.md` — the policy you enforce
+  (NITRO-first for tables, tokens not hardcoded colors, lucide-react icons).
+
+## The prime directive: patterns, not just imports
+
+Compliance is not "does the file import @mieweb/ui". Raw HTML that serves
+the same purpose as a component is a violation even when the file already
+imports the library:
+
+- `<span className="rounded-full bg-blue-100 px-2 …">` is a `Badge`.
+- `<div className="rounded-lg border p-4 shadow">` is a `Card`.
+- `<div className="fixed inset-0 bg-black/50">…` is a `Modal`.
+- A hand-rolled `<svg>` or icon-font glyph is a `lucide-react` icon.
+- Any `<table>` the user will sort, filter, page, or export is
+  **DataVis NITRO** (`Table` only for a few static rows; `AGGrid` is
+  deprecated — never migrate _to_ it).
+
+## Audit workflow
+
+1. **Scope the audit.** A file, a page, or a whole project — confirm which,
+   then read the files before reporting. Exclude test files from violation
+   counts.
+2. **Grep for raw elements** — `<button`, `<input`, `<select`, `<textarea`,
+   `<table`/`<thead`/`<tbody`/`<tr`/`<td`/`<th`, `<form` controls. Also grep
+   the **dynamic forms**: literal `type="date"` misses
+   `type={cond ? 'date' : 'text'}` — search `type={` and other
+   prop-expression variants too.
+3. **Grep for patterns** — badge/pill/tag spans, card-like divs
+   (`rounded…border…shadow`), modal/overlay divs (`fixed inset-0`), inline
+   `<svg>` and icon-font classes, hand-rolled spinners/progress bars,
+   custom tab/breadcrumb/pagination markup.
+4. **Check the CSS foundation** (project-level audits): identify the
+   consumer's CSS mode first, then audit against that mode's checklist in
+   the `mieweb-ui-tailwind4` skill — Tailwind 4 (`@source` for
+   `@mieweb/ui/dist`, `@custom-variant dark`, `@theme` fallbacks,
+   `@tailwindcss/postcss`), Tailwind 3 (preset + safelist + `content`
+   coverage), or precompiled CSS (`styles.css`/`init.css` import — never
+   prescribe Tailwind tooling to it). Validate the dark-mode toggle
+   against the `@custom-variant` actually in effect (a single-hook toggle
+   against `init.css` is valid); setting both `.dark` and `data-theme` is
+   the recommendation for new code, not a violation when one hook matches.
+5. **Build the resolution plan**, prioritized: layout shell (`AppHeader`,
+   `Sidebar`, `SiteFooter`) → buttons → form elements → cards & modals →
+   tables (NITRO) → feedback (`Badge`, `Toast`, `Spinner`) → navigation
+   (`Tabs`, `Breadcrumb`, `Pagination`). Replacements preserve existing
+   functionality and event handlers.
+6. **Detect gaps.** A pattern with no `@mieweb/ui` equivalent is not a
+   violation — report it with the tier recommendation: compose from existing
+   primitives; build locally in library style (CVA variants, `forwardRef`,
+   theme CSS variables, dark mode, ARIA); headless-module contract if it
+   renders a caller-owned collection; contribute upstream once stable.
+7. **Report, then hand off.** Findings in the format below; offer
+   **Apply Fixes** for the edits.
+
+## Audit output format
+
+### 🧭 @mieweb/ui compliance audit for `<scope>`
+
+| #   | Category | File | Line | Violation | Replacement |
+| --- | -------- | ---- | ---- | --------- | ----------- |
+
+Order findings: raw elements, then patterns, then CSS foundation, then gaps.
+After the table, the compliance summary:
+
+| Category                | Count | Status |
+| ----------------------- | ----- | ------ |
+| Raw `<button>`          | X     | ❌     |
+| Raw form elements       | X     | ❌     |
+| Raw `<table>`           | X     | ❌     |
+| Custom modal/card/badge | X     | ❌     |
+| Hand-rolled icons       | X     | ❌     |
+| CSS foundation          | —     | ✅/❌  |
+| Gaps (no equivalent)    | N     | 📝     |
+
+Close with what passes, any judgment calls, and the **Apply Fixes** handoff.
+
+## Migration planning (beyond single-file audits)
+
+For whole-app migrations (e.g. Meteor 2 + Blaze → Meteor 3 + React +
+@mieweb/ui), plan in this order: scaffold → install deps → the three
+critical CSS/PostCSS/Tailwind config files → verify Tailwind renders →
+shared hooks (`useTheme`, `useBrand`) → layout shell → features one at a
+time, auth first → verify dark mode, brand switching, and `tsc --noEmit`.
+Meteor 3 specifics: all methods async, collection ops use `*Async()`
+variants. Verify each migrated feature before starting the next.
+
+## Redirects
+
+- "Which component should I use?" for new (non-migration) work → **MIE UI
+  Design Agent** (your mapping covers replacements; open-ended selection is
+  theirs).
+- Broken styling after install, unstyled components, Tailwind wiring →
+  **MIE UI Install Agent** (you flag the missing foundation; they debug it).
+- Token/brand/dark-mode policy questions → **MIE UI Styling Agent**.
+- ARIA, keyboard navigation, focus, contrast → **MIE UI A11y Agent** (your
+  replacements inherit library a11y; auditing what remains is theirs).
+- String externalization, locale bundles, RTL → **MIE UI i18n Agent**.
+
+## Rules
+
+1. Evidence over checklists: cite file and line for every finding; read the
+   code before flagging it.
+2. **Patterns, not just imports** — a compliant import list proves nothing;
+   grep for the raw markup the components replace.
+3. Grep dynamic forms: prop expressions (`type={…}`, spread props,
+   conditional classes) hide violations that literal-string greps miss.
+4. Never prescribe a component or prop you cannot verify in the catalog
+   skill, the published component docs (https://ui.mieweb.org), or the
+   package's public types — the catalog is a selection inventory, not an
+   API reference; a gap honestly reported beats an invented replacement.
+5. Replacements must preserve behavior — event handlers, controlled state,
+   form semantics. Flag any replacement that would change behavior as a
+   judgment call instead of silently prescribing it.

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

@@ -7,7 +7,7 @@ description: Component inventory and selection guidance for the @mieweb/ui desig
 
 # @mieweb/ui component catalog
 
-272 cataloged components. Full docs: https://ui.mieweb.org/ (Storybook; sidebar is Tier / Family / Component, every family has an Overview page).
+274 cataloged components. Full docs: https://ui.mieweb.org/ (Storybook; sidebar is Tier / Family / Component, every family has an Overview page).
 
 For per-component "Which one?" comparison tables, read [selection-guidance.md](./selection-guidance.md) in this skill and jump to the family's section.
 
@@ -43,7 +43,7 @@ For per-component "Which one?" comparison tables, read [selection-guidance.md](.
 
 ## Inventory
 
-Components by tier and family. Annotations: maturity when not stable, and the import entry when it is not the root (e.g. _(`/datavis`)_).
+Components by tier and family. Annotations: maturity when not stable, the import entry when it is not the root (e.g. _(`/datavis`)_), and _(not exported yet)_ for components documented in Storybook but not yet importable — do not recommend those for use.
 
 ### Foundations
 
@@ -73,14 +73,14 @@ Components by tier and family. Annotations: maturity when not stable, and the im
 
 - **Chat:** AIChat, AIChat (Voice), AIMessage, ChatComposer _(beta)_, Composer Action Ribbon (POC) _(experimental)_, ComposerModelSelector, MCPToolCall, Messaging, OzwellChat, ReconciliationPanel
 - **Dashboards:** CustomizableDashboard, Dashboard (Demo) _(experimental)_, Dashboard Widgets (Demo) _(experimental)_, DashboardCustomizePanel, DashboardWidget, QuickLinksCard, ReportDashboard
-- **Editors:** EmailEditor _(experimental)_, MacroLibrary _(experimental)_, Markdown, Q _(`/q`)_, RichEditor _(`/kerebron`)_, RichTextEditor, RichTextEsheet _(experimental, `/esheet`)_, TextAreaRich _(experimental)_
+- **Editors:** EmailEditor _(experimental)_, MacroLibrary _(experimental)_, Markdown, Q _(`/q`)_, RichEditor _(`/kerebron`)_, RichTextEditor, RichTextEsheet _(experimental, `/esheet`)_, TextAreaRich (Kerebron) _(experimental, `/kerebron`)_
 - **Files:** DocumentScanner, DropzoneOverlay, FileManager
 - **Media:** AudioPlayer, AudioRecorder, DictationButton _(experimental)_, MediaEditor, MediaEditor Live Demo, MediaFeed _(experimental, `/components/MediaFeed`)_, MediaPlayer, RecordButton, TranscriptView, VideoCard _(experimental)_
 - **Presentations:** Deck _(experimental, `/deck`)_, PointMap _(experimental, `/maps`)_
 - **Records:** ActionPlan _(experimental)_, ActivityFeed _(experimental)_, AssociationList _(experimental)_, FieldHistory _(experimental)_, OrgChart _(experimental, `/org-chart`)_, RecordLayout _(experimental)_
 - **SuperChat:** Conversations (List) _(`/components/SuperChat`)_, Inbox _(`/components/SuperChat`)_, SuperChat (Panel) _(`/components/SuperChat`)_
 - **Views:** BoardView _(alpha)_, CalendarView _(alpha)_, GanttView _(alpha)_, ListView _(alpha)_, ViewSet _(alpha)_, ViewSwitcher _(alpha)_
-- **Voice:** Hands-Free Chat, Hey Ozwell Demo, Hey Ozwell Selector _(experimental)_, Speaker Verify _(experimental)_, Transcript Player _(experimental)_, Visit Scribe, Voice Manager, Voice Setup, Wake Word
+- **Voice:** Hands-Free Chat, Hey Ozwell Demo, Hey Ozwell Selector _(experimental)_, Speaker Scribe _(experimental, not exported yet)_, Speaker Verify _(experimental)_, Transcript Player _(experimental)_, Visit Scribe, Voice Manager, Voice Setup, Wake Word
 
 ### Templates
 
@@ -107,7 +107,7 @@ Components by tier and family. Annotations: maturity when not stable, and the im
 
 ### Deprecated
 
-- AGGrid _(deprecated, `/ag-grid`)_, AGGrid Enhanced _(deprecated, `/ag-grid`)_
+- AGGrid _(deprecated, `/ag-grid`)_, AGGrid Enhanced _(deprecated, `/ag-grid`)_, TextAreaRich (Legacy) _(deprecated)_
 
 ## Family policies
 

package/agent/skills/mieweb-ui-catalog/selection-guidance.md

@@ -274,11 +274,12 @@ lists of options in [Choice inputs](https://ui.mieweb.org/?path=/docs/inputs-cho
 | --- | --- | --- |
 | [RichEditor](https://ui.mieweb.org/?path=/docs/editors-richeditor--docs) | The document is **Markdown**: headings, lists, tables, code; `getContent()` on submit; `collab.room` for Yjs co-editing; `CodeEditor` for source | The stored format is HTML or you need merge variables/dictation — `RichTextEditor`; the host cannot add the Kerebron peers and WASM assets |
 | [RichTextEditor](https://ui.mieweb.org/?path=/docs/editors-richtexteditor--docs) | The document is **HTML**: bold/italic/underline, lists, alignment, opt-in markdown block shortcuts (H1–H3, lists, quote), `variableGroups` inserting `{{tokens}}`, Web Speech dictation; no peers | You need Markdown, real undo history, links/tables/code or collaboration — `RichEditor`; plain text — `Textarea`; a textarea-like surface with the toolbar hidden — `TextAreaRich` |
-| [TextAreaRich](https://ui.mieweb.org/?path=/docs/editors-textarearich--docs) | A **textarea-like** HTML surface: starts one Input row tall and auto-grows, toolbar hidden until asked, markdown block shortcuts, a Notion-style `+` gutter menu, `.shortcut` macros | The value must be **plain text** (form posts, bindings) — `Textarea` (this surface with a plain-text contract); a full document with an always-on toolbar, variables or dictation — `RichTextEditor` |
+| [TextAreaRich](https://ui.mieweb.org/?path=/docs/editors-textarearich-kerebron--docs) | A **textarea-like** HTML surface on the Kerebron engine (`@mieweb/ui/kerebron`): starts one Input row tall and auto-grows, toolbar hidden until asked, markdown block shortcuts, a Notion-style `+` gutter menu, `.shortcut` macros | The value must be **plain text** (form posts, bindings) — `Textarea` (this surface with a plain-text contract); a full document with an always-on toolbar, variables or dictation — `RichTextEditor` |
 | [RichTextEsheet](https://ui.mieweb.org/?path=/docs/editors-richtextesheet--docs) | A **multi-section guided document** — referral letters, support tickets, incident write-ups — where an eSheet definition drives section prompts, memory-aid phrases and party macros; exports portable MDY | One free-form HTML letter with merge fields and dictation — `RichTextEditor`; a single rich input — `TextAreaRich`; arbitrary native `FormDefinition` forms — EsheetRenderer (Composite forms); coded clinical visits — EncounterVisit (Encounter & orders) |
 | [EmailEditor](https://ui.mieweb.org/?path=/docs/editors-emaileditor--docs) | The document is an **email**: hero, columns, buttons, images, social, footer blocks on a drag-to-reorder canvas; `renderEmailMjml` serialises it | A single formatted body — `RichTextEditor`; sending, recipients and templates are the host's |
 | [Markdown](https://ui.mieweb.org/?path=/docs/editors-markdown--docs) | **Displaying** Markdown: sanitised HTML, code highlighting, `mermaid` / `csv` / `survey` / `html` fences, `streaming` for token-by-token AI output | The user edits the text — `RichEditor` / `RichTextEditor`; the source is HTML |
 | [Q](https://ui.mieweb.org/?path=/docs/editors-q--docs) | Admins configure an **agent** (prompt, tools, telephony) through a schema-generated form and see the YAML/JSON; `onSubmit(yaml)`, `onConfigChange` | Free-form prose — `RichEditor`; general clinical/business forms — ESheet (Composite forms) |
+| [TextAreaRich (Legacy)](https://ui.mieweb.org/?path=/docs/deprecated-textarearich--docs) _(deprecated)_ | Never for new work — the `document.execCommand` engine; use [TextAreaRich (Kerebron)](https://ui.mieweb.org/?path=/docs/editors-textarearich-kerebron--docs) | — |
 
 ---
 
@@ -652,7 +653,7 @@ executive summary (numbers as lettermark icons) and outlook, and `LeadFormSectio
 | Component | Use it when | Not when |
 | --- | --- | --- |
 | [Input](https://ui.mieweb.org/?path=/docs/text-inputs-input--docs) | One line of free text or a native type (`email`, `password`, `number`) | Phone / URL / date / fixed options — see the specialists |
-| [Textarea](https://ui.mieweb.org/?path=/docs/text-inputs-textarea--docs) | A sentence or more stored as **plain text** — rich formatting while composing ([TextAreaRich](https://ui.mieweb.org/?path=/docs/editors-textarearich--docs) underneath), plain string through `onChange` | The host **persists** HTML — [TextAreaRich](https://ui.mieweb.org/?path=/docs/editors-textarearich--docs); native `<textarea>` behaviours (hard `maxLength`, validation, drag-resize, floating label) — `TextAreaPlain` (documented on the Textarea page); full documents — `RichEditor` / `RichTextEditor` |
+| [Textarea](https://ui.mieweb.org/?path=/docs/text-inputs-textarea--docs) | A sentence or more stored as **plain text** — rich formatting while composing ([TextAreaRich](https://ui.mieweb.org/?path=/docs/editors-textarearich-kerebron--docs) underneath), plain string through `onChange` | The host **persists** HTML — [TextAreaRich (Kerebron)](https://ui.mieweb.org/?path=/docs/editors-textarearich-kerebron--docs); native `<textarea>` behaviours (hard `maxLength`, validation, drag-resize, floating label) — `TextAreaPlain` (documented on the Textarea page); full documents — `RichEditor` / `RichTextEditor` |
 | [Label](https://ui.mieweb.org/?path=/docs/text-inputs-label--docs) | Labelling a control with no `label` prop (raw `<select>`, custom) | The control already takes `label` |
 | [PhoneInput](https://ui.mieweb.org/?path=/docs/text-inputs-phoneinput--docs) | Exactly one US/Canada number stored as 10 digits | Several typed numbers — `PhoneInputGroup`; international |
 | [PhoneInputGroup](https://ui.mieweb.org/?path=/docs/text-inputs-phoneinputgroup--docs) | A record holds several numbers and the type (cell, work, fax) matters | One number; rows need extra fields |

package/package.json

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