@mieweb/ui 0.11.0-dev.31 → 0.11.0-dev.32

package/agent/README.md

@@ -18,13 +18,13 @@ governing spec: later tickets cite it instead of re-deciding.
 
 ## Files
 
-| File                                                   | Purpose                                                                                                                                                                                                                                                                               |
-| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [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`. 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` (hand-written). Installed to `.github/skills/` behind `--experimental-agents`. |
-| `evals/` _(Phase 2+)_                                  | Golden-question eval sets per specialist; the regression harness for agent knowledge.                                                                                                                                                                                                 |
+| File                                                   | Purpose                                                                                                                                                                                                                                                                                                           |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [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`.                                                                                               |
+| [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.                                                                                                                                                                                                                             |
 
 Rule content is sourced from [lessons/component-policy.md](../lessons/component-policy.md);
 keep the two in sync when policy changes.

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

@@ -15,6 +15,10 @@ handoffs:
     agent: MIE UI A11y Agent
     prompt: Audit the code discussed above for accessibility (ARIA naming, keyboard navigation, focus management, live regions, contrast) and report findings.
     send: false
+  - label: i18n/RTL audit
+    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
 ---
 
 # MIE UI Design Agent (orchestrator)
@@ -49,8 +53,9 @@ comparison tables) and `mieweb-ui-icons` (icon aliases and conventions):
 | 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    |
 
-More specialists (i18n, Migration, Grids, DataVis, Views,
+More specialists (Migration, 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).
 
@@ -66,8 +71,8 @@ from the skills and the component docs, or defer (below).
 - _Styling a specialist's component:_ generic token/Tailwind/brand questions go
   to the Styling Agent; component-specific theming APIs stay with that
   component's specialist (or with you while none exists).
-- _Cross-cutting audits win:_ a11y/i18n questions route to those auditors once
-  they ship, no matter which component they concern.
+- _Cross-cutting audits win:_ a11y/i18n questions route to those auditors, no
+  matter which component they concern.
 
 ## Rules
 

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

@@ -0,0 +1,91 @@
+---
+name: MIE UI i18n Agent
+description: Internationalization and RTL auditor for apps built with @mieweb/ui — string externalization, locale-bundle completeness, Intl formatting with the active locale, and right-to-left layout. Invoke to audit a component, page, or diff for i18n/RTL compliance, review a new locale, or plan an RTL pass using the library's direction toolkit.
+tools: ['search', 'codebase', 'fetch']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the i18n/RTL fixes identified in the audit above to the codebase.
+    send: false
+---
+
+# MIE UI i18n Agent
+
+You are the internationalization and RTL auditor for apps built with the
+**@mieweb/ui** design system. You are **read-only**: you audit, explain, and
+prescribe — the **Apply Fixes** handoff performs the edits.
+
+## Your sources of truth (never inline-duplicate them)
+
+- **`mieweb-ui-i18n-checklist` skill** — the four-category audit procedure
+  (string externalization, bundle completeness, `Intl` with the active
+  locale, RTL layout), the library direction toolkit (`useDirection`,
+  `isRtl`, `isRtlLocale`, `cn()`), the add-a-locale recipe, and the testing
+  guidance. Follow it for every audit.
+- **`mieweb-ui-catalog` skill** — component props when prescribing a
+  library-backed fix (e.g. components with `start`/`end` placement aliases).
+- The installed `mieweb-ui.instructions.md` — Rule 10 is the policy you
+  enforce.
+
+## Audit workflow
+
+1. **Scope the audit.** A component, a page, a diff, or a locale bundle —
+   confirm which files; read them fully before reporting.
+2. **Run the checklist in order** (strings → bundles → `Intl`/locale → RTL).
+   Grep targets: quoted JSX text and string `label`/`title`/`placeholder`/
+   `aria-label` props without `t()`, string arguments to toast/alert calls,
+   hardcoded BCP-47 tags in `toLocale*`/`Intl.*` calls, `+` or template
+   interpolation around `t()`, physical-direction classes
+   (`ml-`/`mr-`/`pl-`/`pr-`/`left-`/`right-`/`text-left`/`text-right`) and
+   physical inline-style props (`marginLeft`, `left:`, `textAlign: 'left'`).
+3. **Diff the bundles.** For any touched `t()` keys, compare every locale
+   bundle against the canonical bundle by **logical** key — strip only the
+   trailing i18next plural suffix, keeping context variants (`invite_admin`
+   vs `invite_guest`) distinct, since required plural forms differ per
+   locale but each context is its own message (the checklist skill details
+   this) — new strings must be localized in the **same commit**, in **all**
+   bundles; flag missing and orphaned logical keys per bundle, and
+   pluralized keys lacking the forms that locale requires.
+4. **Prefer library fixes.** Direction-dependent JS gets `useDirection`/
+   `isRtl` (reactive hook when direction drives rendering); locale→direction
+   mapping uses `isRtlLocale`; physical classes become their logical
+   equivalents. Never invent props — verify in the catalog skill.
+5. **Report, then hand off.** Findings first, in the format below; offer
+   **Apply Fixes** for the edits.
+
+## Audit output format
+
+### 🌐 i18n/RTL audit for `<scope>`
+
+| #   | Category | File | Line | Issue | Fix |
+| --- | -------- | ---- | ---- | ----- | --- |
+
+Order findings by category (strings, bundles, Intl/locale, RTL). After the
+table: what passes, counts by category, and any judgment calls (e.g.
+dev-only strings left unexternalized, deliberately physical geometry).
+Close by offering the **Apply Fixes** handoff.
+
+## Redirects
+
+- "Which component should I use?" → **MIE UI Design Agent**.
+- Token/brand/dark-mode questions beyond direction → **MIE UI Styling
+  Agent** (physical-vs-logical class findings are yours; palette policy is
+  theirs).
+- ARIA, keyboard-reachability, focus, contrast → **MIE UI A11y Agent**
+  (localizing an `aria-label`'s _text_ is yours; whether it exists is
+  theirs).
+- Install/setup problems (unstyled components, missing styles) →
+  **MIE UI Install Agent**.
+
+## Rules
+
+1. Evidence over checklists: cite file and line for every finding; read the
+   code before flagging it.
+2. Missing bundle keys fail silently (i18next falls back to the canonical
+   language) — never trust a passing render as proof of completeness; diff
+   the key sets.
+3. Genuinely physical UI (viewport pins, resize math, LTR data islands) is
+   exempt but must be deliberate — an uncommented physical class is a
+   finding even when it might be intentional.
+4. Flag concatenation around `t()` even when the English output looks right
+   — word order is the first thing other languages break.

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

@@ -46,7 +46,7 @@ first.
    component-scoped styles.
 6. **Physical direction classes** — `ml-*`/`pl-*`/`left-*`/`text-left` in new
    code; prefer logical `ms-*`/`ps-*`/`start-*`/`text-start` (RTL rule). Flag
-   it, and route deeper i18n/RTL audits to that specialist once it ships.
+   it, and route deeper i18n/RTL audits to the **MIE UI i18n Agent**.
 7. **Hand-rolled animation** — bespoke keyframes or transition soup where a
    library `animate-*` class or motion preset exists.
 

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
 
-266 cataloged components. Full docs: https://ui.mieweb.org/ (Storybook; sidebar is Tier / Family / Component, every family has an Overview page).
+271 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.
 
@@ -71,16 +71,16 @@ Components by tier and family. Annotations: maturity when not stable, and the im
 
 ### Modules
 
-- **Chat:** AIChat, AIChat (Voice), AIMessage, ChatComposer _(beta)_, ComposerModelSelector, MCPToolCall, Messaging, OzwellChat, ReconciliationPanel
+- **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)_, Markdown, Q _(`/q`)_, RichEditor _(`/kerebron`)_, RichTextEditor
+- **Editors:** EmailEditor _(experimental)_, MacroLibrary _(experimental)_, Markdown, Q _(`/q`)_, RichEditor _(`/kerebron`)_, RichTextEditor, TextAreaRich _(experimental)_
 - **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)_, Visit Scribe, Voice Manager, Voice Setup, Wake Word
+- **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
 
 ### Templates
 
@@ -93,7 +93,7 @@ Components by tier and family. Annotations: maturity when not stable, and the im
 ### Healthcare
 
 - **Clinical lists:** AllergyList, AllergyListField (eSheet) _(`/esheet`)_, CodeLookup, ConditionEditor, MedicationList, MedicationListField (eSheet) _(`/esheet`)_, PresentingProblems, ProblemList
-- **Encounter & orders:** Assessment, CaseManagementHeader, HealthSurveillance, OrderEditor, PatientHeader, WebChartReportViewer
+- **Encounter & orders:** Assessment, CaseManagementHeader, EncounterVisit _(experimental, `/esheet`)_, HealthSurveillance, OrderEditor, PatientHeader, WebChartReportViewer
 
 ### BlueHive
 
@@ -198,14 +198,18 @@ The one-line rule that governs each family. When a task touches a family, read i
 
 > **What is the stored format, and who edits it?** Markdown that people write (and maybe
 > co-write) → `RichEditor`. HTML for templated letters with merge fields and dictation →
-> `RichTextEditor`. An **email** laid out from blocks and compiled to MJML → `EmailEditor`.
+> `RichTextEditor`. HTML in a surface that should look like a plain textarea until asked →
+> `TextAreaRich`. An **email** laid out from blocks and compiled to MJML → `EmailEditor`.
 > Markdown that is only **read** → `MarkdownRenderer`. A structured agent
-> configuration with a YAML/JSON pane → `Q`. Plain text → [Textarea](https://ui.mieweb.org/?path=/docs/text-inputs-textarea--docs)
-> (Text inputs).
+> configuration with a YAML/JSON pane → `Q`. Plain text storage with rich composing →
+> [Textarea](https://ui.mieweb.org/?path=/docs/text-inputs-textarea--docs) (Text inputs) — it renders `TextAreaRich`
+> but keeps a plain-text `value`.
 
 **Encounter & orders** (Healthcare):
 
-> **What does the page lead with, and what data does it get?** Today's conclusions and the
+> **What does the page lead with, and what data does it get?** A whole visit document with
+> narrative, observations, coordinated vitals and MCP tools → `EncounterVisit` (eSheet-backed).
+> Today's conclusions and the
 > orders placed for each problem → `Assessment` (plain props: concerns, items, orders). One
 > order in full → `OrderEditor` (morphs by type). What is _due_ from surveillance programs
 > and quality measures → `HealthSurveillance` (`PatientHistory` + `programs.json`). The banner
@@ -321,7 +325,8 @@ The one-line rule that governs each family. When a task touches a family, read i
 
 **Text inputs** (Inputs):
 
-> **What is the value?** Free text on one line → `Input`; several lines → `Textarea`. A phone
+> **What is the value?** Free text on one line → `Input`; several lines → `Textarea` (a rich
+> surface that keeps a plain-text value — `TextAreaPlain` for the native element). A phone
 > number → `PhoneInput` (or `PhoneInputGroup` for a typed list); a URL → `WebsiteInput` (or
 > `WebsiteInputGroup`) — never a raw `type="tel"` / `type="url"`. A postal address → `AddressForm`
 > to edit, `Address` to show. Every field gets an associated label: the `label` prop where the

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

@@ -259,17 +259,20 @@ lists of options in [Choice inputs](https://ui.mieweb.org/?path=/docs/inputs-cho
 
 > **What is the stored format, and who edits it?** Markdown that people write (and maybe
 > co-write) → `RichEditor`. HTML for templated letters with merge fields and dictation →
-> `RichTextEditor`. An **email** laid out from blocks and compiled to MJML → `EmailEditor`.
+> `RichTextEditor`. HTML in a surface that should look like a plain textarea until asked →
+> `TextAreaRich`. An **email** laid out from blocks and compiled to MJML → `EmailEditor`.
 > Markdown that is only **read** → `MarkdownRenderer`. A structured agent
-> configuration with a YAML/JSON pane → `Q`. Plain text → [Textarea](https://ui.mieweb.org/?path=/docs/text-inputs-textarea--docs)
-> (Text inputs).
+> configuration with a YAML/JSON pane → `Q`. Plain text storage with rich composing →
+> [Textarea](https://ui.mieweb.org/?path=/docs/text-inputs-textarea--docs) (Text inputs) — it renders `TextAreaRich`
+> but keeps a plain-text `value`.
 
 ## Which one?
 
 | Component | Use it when | Not when |
 | --- | --- | --- |
 | [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, `variableGroups` inserting `{{tokens}}`, Web Speech dictation; no peers | You need Markdown, real undo history, headings/tables or collaboration — `RichEditor`; plain text — `Textarea` |
+| [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` |
 | [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) |
@@ -279,7 +282,9 @@ lists of options in [Choice inputs](https://ui.mieweb.org/?path=/docs/inputs-cho
 <!-- source: src/catalog/EncounterOrders.mdx (Healthcare) -->
 # Encounter & orders
 
-> **What does the page lead with, and what data does it get?** Today's conclusions and the
+> **What does the page lead with, and what data does it get?** A whole visit document with
+> narrative, observations, coordinated vitals and MCP tools → `EncounterVisit` (eSheet-backed).
+> Today's conclusions and the
 > orders placed for each problem → `Assessment` (plain props: concerns, items, orders). One
 > order in full → `OrderEditor` (morphs by type). What is _due_ from surveillance programs
 > and quality measures → `HealthSurveillance` (`PatientHistory` + `programs.json`). The banner
@@ -291,6 +296,7 @@ lists of options in [Choice inputs](https://ui.mieweb.org/?path=/docs/inputs-cho
 
 | Component | Use it when | Not when |
 | --- | --- | --- |
+| [EncounterVisit](https://ui.mieweb.org/?path=/docs/encounter-orders-encountervisit--docs) | A mobile-friendly anonymous visit document with configurable narrative / observation sections, repeated BP and other vitals, clinical lists, assessment and MCP tools sharing native eSheet responses | A single list or order panel; backend scheduling, signed records or clinical decision support |
 | [Assessment](https://ui.mieweb.org/?path=/docs/encounter-orders-assessment--docs) | The visit's **A&P**: `items` point at today's assertion of each concern; `orders` nest under problems via `concernId` (the durable IndicationLink); unified coded add row; unlinked bucket; drag to re-link | The chart problem list — `ProblemList`; relevance tagging — `PresentingProblems`; full order edits — `OrderEditor`; a due list — `HealthSurveillance` |
 | [OrderEditor](https://ui.mieweb.org/?path=/docs/encounter-orders-ordereditor--docs) | Editing one `AssessmentOrder` in full. Morphs: `medication` → `MedicationEditor` (NCPDP); `lab` / `imaging` / `procedure` / `referral` → typed editors with coded search, priority, timing, body site / refer-to | The inline display / detail edit Assessment already offers; reconciling presenting meds — `MedicationReconciliation` |
 | [HealthSurveillance](https://ui.mieweb.org/?path=/docs/encounter-orders-healthsurveillance--docs) | Showing what is **overdue / due / pending / done** for OSHA / DOT programs (`enrolledKeys`) and CMS eCQMs, from `evaluateDue(history, programs)`; each item is a picklist of satisfying orders → `onOrderMany` | You need the plan itself — `Assessment`; an order-history grid — the story-only `ChartOrdersGrid` demo on NITRO; rules beyond periodicity + age / sex gates |
@@ -631,7 +637,8 @@ executive summary (numbers as lettermark icons) and outlook, and `LeadFormSectio
 <!-- source: src/catalog/TextInputs.mdx (Inputs) -->
 # Text inputs
 
-> **What is the value?** Free text on one line → `Input`; several lines → `Textarea`. A phone
+> **What is the value?** Free text on one line → `Input`; several lines → `Textarea` (a rich
+> surface that keeps a plain-text value — `TextAreaPlain` for the native element). A phone
 > number → `PhoneInput` (or `PhoneInputGroup` for a typed list); a URL → `WebsiteInput` (or
 > `WebsiteInputGroup`) — never a raw `type="tel"` / `type="url"`. A postal address → `AddressForm`
 > to edit, `Address` to show. Every field gets an associated label: the `label` prop where the
@@ -642,7 +649,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; a visible character budget (`showCount`) | Formatted or collaborative text — `RichEditor` |
+| [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` |
 | [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/agent/skills/mieweb-ui-i18n-checklist/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: mieweb-ui-i18n-checklist
+description: Internationalization and RTL audit procedure for apps built with @mieweb/ui — string externalization, locale-bundle completeness, Intl formatting with the active locale, and RTL-safe layout (logical properties, direction-aware JS), plus the library's direction toolkit (useDirection, isRtl, isRtlLocale) and known RTL layout gotchas. USE WHEN auditing a component, page, or diff for i18n/RTL compliance, adding a new locale, fixing hardcoded strings or locales, or making a layout work right-to-left.
+---
+
+# i18n & RTL auditing with @mieweb/ui
+
+Policy baseline is Rule 10 of the installed `mieweb-ui.instructions.md`
+(externalize all user-facing text; RTL-safe logical classes; `Intl` APIs for
+dates/numbers/currency). The reference implementation of the org's i18n
+pattern is `@mieweb/ui/datavis` (`packages/datavis/src/i18n/` in the library
+repo): i18next + react-i18next with a canonical `en-US.json` plus one JSON
+bundle per locale, and a `LocaleProvider`/`useLocale()` context that feeds
+`Intl`/`toLocale*` formatting.
+
+## Audit procedure
+
+Work through the four categories in order; for each finding record file,
+line, issue, and fix.
+
+1. **String externalization.** Every user-facing string in JSX or in values
+   handed to the UI (toast/alert messages, `aria-label`s, placeholders,
+   button labels, empty-state text, error messages) must go through the
+   project's translation function (`t('…')` from `useTranslation()`).
+   Grep targets: quoted text in JSX children, string props named
+   `label`/`title`/`placeholder`/`aria-label`/`alt`, string arguments to
+   toast/alert/announce calls. Dev-only output (`console.*`, thrown `Error`
+   messages not shown to users) is exempt — note it as a judgment call, not
+   a finding.
+2. **Localized in the same commit + bundle completeness.** New `t()` keys
+   must land with entries in **every** locale bundle in the same commit —
+   not just `en-US`. A key present in the canonical bundle but missing from
+   any sibling bundle is a finding (i18next silently falls back to
+   `fallbackLng`, so the gap ships invisibly). Audit by diffing **logical**
+   keys: strip only the trailing i18next plural suffix (`_zero`, `_one`,
+   `_two`, `_few`, `_many`, `_other`) before comparing, because the
+   required plural forms differ per locale (English needs `items_one`/
+   `items_other`; Arabic needs all six) — a raw key-set diff would flag
+   Arabic's extra forms as orphaned and pass an Arabic bundle that only has
+   the English two. **Keep context suffixes** (`invite_admin`,
+   `invite_guest`) — each context variant is a distinct message, so
+   stripping them would hide a locale that's missing `invite_guest`; a
+   combined key like `invite_admin_one` normalizes to `invite_admin`. Flag
+   missing and orphaned logical keys, and separately verify each pluralized
+   key (per context variant) carries the plural forms **that locale's**
+   CLDR rules require.
+3. **Formatting via `Intl` with the active locale.** Dates, numbers, and
+   currency go through `Intl.*` / `toLocale*` APIs with the locale flowing
+   from the active language — `useLocale()` where the datavis-style
+   `LocaleProvider` is in scope, otherwise `i18n.language`. Findings:
+   - a hardcoded BCP-47 tag (`toLocaleDateString('en-US', …)`) — pins every
+     user to one locale;
+   - manual string formatting (`` `${month}/${day}/${year}` ``, `+ '%'`,
+     `'$' + amount`) where an `Intl` formatter belongs;
+   - **string concatenation or interpolation around `t()`** —
+     `t('greeting') + name` or `` `${t('count.prefix')} ${n}` `` breaks
+     word-order in other languages. Use i18next interpolation and plurals:
+     `t('greeting', { name })`, `t('items', { count })`.
+4. **RTL layout and direction-aware JS.** Everything below.
+
+## RTL checklist
+
+The library is logical-properties-first; its CI ratchet
+(`pnpm rtl:scan` against `scripts/rtl-baseline.json`, currently zero debt)
+blocks new physical-direction styling in library code. Apps should hold the
+same line:
+
+- **Classes:** `ms-*`/`me-*`, `ps-*`/`pe-*`, `start-*`/`end-*`,
+  `text-start`/`text-end`, `border-s-*`/`border-e-*`, `rounded-s-*`/`rounded-e-*`
+  — never `ml-*`/`mr-*`, `pl-*`/`pr-*`, `left-*`/`right-*`,
+  `text-left`/`text-right`. `rtl:` variants only for true exceptions.
+- **Inline styles evade class greps** — also check `style={{ … }}` for
+  `marginLeft`, `paddingRight`, `left`, `right`, `textAlign: 'left'`,
+  `float`; use `marginInlineStart`, `insetInlineStart`, `textAlign: 'start'`.
+- **Directional icons** (chevrons, back/forward arrows) flip with
+  `rtl:-scale-x-100`; checkmarks, media controls, and up/down arrows do not.
+- **Keyboard handlers:** ArrowLeft/ArrowRight must follow *visual*
+  direction. Use `isRtl(event.currentTarget)` inside handlers; use
+  `useDirection(ref)` (reactive) whenever direction drives rendering or
+  positioning math. Content rendered through a portal must read direction
+  from a non-portaled ref — the portal escapes local `dir` overrides.
+- **Genuinely physical UI stays physical** — viewport-pinned toasts, resize
+  handles, geometry math tied to screen coordinates, LTR data islands
+  (code, phone numbers, URLs — wrap in `dir="ltr"`). Deliberate exceptions
+  deserve a comment, not a silent physical class.
+
+## Library direction toolkit
+
+| Export (root entry) | Use for | Caveats |
+| --- | --- | --- |
+| `useDirection(ref?)` | Reactive `'ltr' \| 'rtl'` from the nearest `dir` attribute | Prefer it over `isRtl()` whenever direction drives rendering; pass a ref to respect local `dir` overrides |
+| `isRtl(element?)` | One-shot check in event handlers | Snapshot, not reactive — stale if stored across renders; never call with a portaled element |
+| `isRtlLocale(locale)` / `RTL_LOCALES` | Mapping a locale choice to `dir` (`ar`, `he`, `fa`, `ur`) | Checks the language subtag only |
+| `cn()` (from `@mieweb/ui`) | Class merging where physical ⇄ logical pairs conflict correctly | Consumer `className="ml-2"` overrides still win over `ms-2` |
+
+Set direction at the root: `<html dir="rtl">` (or a scoped
+`dir` attribute), typically derived from the active language via
+`isRtlLocale(i18n.language)`.
+
+## Adding a locale (datavis-style setup)
+
+1. Add `<locale>.json` next to the existing bundles covering every
+   **logical** key of the canonical bundle, with the plural forms the new
+   locale's CLDR rules require (not a copy of the canonical bundle's
+   suffixes).
+2. Register it in the i18next `resources` map where `ensureI18nInit()` (or
+   the app's equivalent init) builds the instance.
+3. Expose it in the app's language selector; on change call
+   `i18n.changeLanguage(code)` and set `dir` on **every** change —
+   `document.documentElement.dir = isRtlLocale(code) ? 'rtl' : 'ltr'` —
+   never only when the new locale is RTL, or switching back to an LTR
+   language leaves the UI mirrored.
+4. Verify `Intl` output (dates, numbers) in the new locale — no code changes
+   should be needed if locales were never hardcoded.
+
+## Testing
+
+- Pseudo-check by switching language at runtime: untranslated strings stay
+  English (missing keys fall back silently — category 2).
+- Flip `dir="rtl"` (the library Storybook has a direction toolbar;
+  `ar`/`he`/`fa`/`ur` locales imply it) and walk the layout: alignment,
+  icon direction, horizontal arrow keys, popover/tooltip anchoring.
+- Long-text expansion: German/Russian strings run ~30% longer — look for
+  truncation and overflow at realistic lengths.
+
+## Verification checklist
+
+- [ ] No hardcoded user-facing strings — all text through `t()`
+- [ ] Every locale bundle covers the canonical bundle's logical keys (plural suffixes stripped, context variants kept distinct), with each locale's own required plural forms; new keys added to all bundles in the same commit
+- [ ] No hardcoded locale tags — `Intl`/`toLocale*` driven by the active language
+- [ ] No concatenation around `t()` — interpolation and `count` plurals
+- [ ] No new physical-direction classes or inline styles; directional icons flip; arrow keys follow visual direction
+- [ ] Layout verified in `dir="rtl"` and with a long-text locale

package/package.json

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