Add RTL (right-to-left) language support across the component library

[garrity-miepub]

Add RTL (right-to-left) language support across the component library

Summary

Support RTL languages (Arabic, Hebrew, Farsi, Urdu) at the component level.
Components should be direction-agnostic by default using CSS logical
properties, with a Storybook toolbar switch (alongside brand / theme / density /
language) to preview RTL.

PR series status (updated 2026-09-10, supersedes #320)

Work lands as a series of small targeted PRs. Each merge cuts a 0.7.2-dev.x
release for in-the-wild validation; full release after the series completes.

• 1. Infrastructure — feat(rtl): RTL infrastructure — scan guard, codemod, useDirection, Storybook direction toolbar #356
• 2. Primitives (Badge, Input, Label, Text, Switch) — feat(rtl): migrate primitives to logical properties — Badge, Input, Label, Text, Switch #357
• 3. Layout + nav (AppHeader, Card, Sheet, Sidebar, Table) — feat(rtl): migrate layout + nav to logical properties — AppHeader, Card, Sheet, Sidebar, Table #358
• 4. Messaging + AI — feat(rtl): migrate Messaging + AI to logical properties #380
• 5. DocumentScanner + media (MediaEditor, TranscriptView) — feat(rtl): migrate DocumentScanner, MediaEditor, TranscriptView to logical properties #425
• 6. Billing/invoices — feat(rtl): migrate billing/invoice components to logical properties #426
• 7. Services/employer — feat(rtl): migrate services/employer components to logical properties #427
• 8. Scheduling + clinical — feat(rtl): migrate scheduling and clinical components to logical properties #428
• 9. Shell/misc (SiteHeader, CommandPalette, CookieConsent, …) — feat(rtl): migrate shell and misc components to logical properties #429

Phase 1 codemod series complete.

Phase 2 batch 1 — #430 (merged): Toast logical positions (physical values
kept as deprecated aliases) + FloatingWindow. The ratchet baseline is now
zero — any new physical-direction class in src/components fails CI unless
annotated with // rtl-ignore -- <reason>. The scanner now prints per-offense
logical-equivalent suggestions and inline PR annotations on failure. #430 also
fixed missing Tailwind 4 --animate-* theme tokens (the Toast slide-in
animations never fired under TW4; remaining animation-token gaps are a
candidate follow-up issue).

Phase 2 batch 2 — #438 (merged): Directional navigation icons mirror in RTL
via rtl:-scale-x-100 across 16 components — pagination/breadcrumb chevrons,
back buttons (SiteHeader, PatientHeader, CaseManagementHeader,
ProviderDetailHeader, CodeLookup, ComposerModelSelector), calendar month nav
(DateRangePicker, DateInput), submenu/drill/expand chevrons (Dropdown, Sidebar,
HealthSurveillance, PermissionsEditor), and link arrows (GlossaryTooltip,
SectionSpyNav). Per Material bidirectionality guidance, checkmarks, media
controls, and up/down chevrons deliberately do not flip. Also fixed a
physical inline marginLeft in HealthSurveillance (inline styles evade the
scanner) and rewrote 11 stale story RTL notes that predated Phase 1.

Remaining Phase 2 work (keyboard nav, JS positioning remainder, LTR islands,
transforms remainder, third-party RTL flags) continues below.

Current state (measured 2026-07-21)

• ~206 component .tsx files; 137 contain physical-direction Tailwind classes
  (ml-, pr-, left-, text-left, rounded-l, border-l, space-x-, …)
• Only 3 logical-property usages exist today
• Tailwind 4 — native logical utilities (ms-/me-/ps-/pe-/start-/end-/
  text-start/rounded-s) and rtl:/ltr: variants are available
• Storybook toolbar globals (brand/theme/density/locale) live in
  .storybook/preview.tsx with a shared applyGlobalTheme() — the right place
  to also set dir
• No dir/direction infrastructure exists anywhere yet

Guiding principle

Logical properties first, rtl: variants last. Make components
direction-agnostic so RTL "just works" from dir="rtl". Reserve rtl:
overrides for true exceptions (icon flips, transforms). Avoid doubling the
class surface with per-direction overrides.

Phase 0 — Infrastructure (one PR, do first) — ✅ shipped in #356

• Add direction Storybook global (ltr / rtl / auto) next to theme/density/locale
  • auto derives direction from the locale global (rtl for ar, he, fa, ur)
  • Wire into applyGlobalTheme() to set dir on document.documentElement (works on docs-only MDX pages, same pattern as dark mode)
  • Add an RTL sample locale (e.g. العربية (sample)) to the locale toolbar for real RTL text
• Runtime direction API: useDirection() hook + isRtlLocale/RTL_LOCALES for JS-level direction logic (keyboard arrows, popover placement, drag math). Default: read from closest dir attribute — zero setup for consumers who set ``
• Enforcement: CI script (scripts/rtl-scan.mjs ratchet, like ccme-scan.mjs) that fails on new physical-direction classes in src/components — prevents regression while migration is in flight

Phase 1 — Mechanical codemod (bulk of the 137 files) — ✅ complete (#357–#429)

Scripted, reviewable find/replace over className strings, run per component
batch (small PRs — see PR series status above):

Physical	Logical
ml-* / mr-*	ms-* / me-*
pl-* / pr-*	ps-* / pe-*
left-* / right-*	start-* / end-*
text-left / text-right	text-start / text-end
rounded-l* / rounded-r* / corners	rounded-s* / rounded-e* / rounded-ss …
border-l* / border-r*	border-s* / border-e*
space-x-*	prefer flex gap-*; else rtl:space-x-reverse
divide-x-*	rtl:divide-x-reverse

• Write codemod script (scripts/rtl-codemod.mjs, shipped in feat(rtl): RTL infrastructure — scan guard, codemod, useDirection, Storybook direction toolbar #356); it also flags dynamic class construction it can't safely rewrite (cond ? 'ml-2' : …, cn() calls, class maps) → produces the Phase 2 worklist

Phase 2 — Manual/semantic pass (needs judgment, per component)

• Icons & chevrons — ✅ feat(rtl): mirror directional navigation icons in RTL (Phase 2 batch 2) #438: back/forward arrows, breadcrumb/pagination chevrons, month nav, submenu/drill/expand indicators flip (rtl:-scale-x-100); checkmarks, media buttons, logos, up/down chevrons do NOT flip. (Send/Reply/Undo/Redo-type action icons not yet audited — most grep hits were identifiers, not JSX.)
• Keyboard navigation — ArrowLeft/ArrowRight invert in RTL: Tabs, Dropdown, Slider, DateRangePicker, ScheduleCalendar (via useDirection())
• Transforms & animations — translate-x-*, slide-in-from-left, Switch thumb travel, Sheet/Sidebar slide directions (Toast slide-in done in feat(rtl): logical Toast positions, FloatingWindow cleanup, zero the ratchet baseline #430)
• JS positioning — Tooltip, Dropdown remain. Toast ✅ done in feat(rtl): logical Toast positions, FloatingWindow cleanup, zero the ratchet baseline #430 (logical top/bottom-start/center/end, physical values kept as deprecated aliases); FloatingWindow ✅ resolved in feat(rtl): logical Toast positions, FloatingWindow cleanup, zero the ratchet baseline #430 (resize/drag math is deliberately physical, exempted via rtl-ignore; minimized-bar classes made logical)
• LTR islands — phone numbers, dates, codes, URLs stay LTR inside RTL: PhoneInput, DateInput, WebsiteInput, CountryCodeDropdown, numeric table cells get explicit dir="ltr"
• Third-party integrations (each may become its own ticket): AG Grid (enableRtl), DataVis/charts, RichTextEditor/Kerebron, ESheet renderer, YChart

Phase 3 — Rollout order

1. Primitives: Button, Input, Badge, Checkbox, Radio, Switch, Select, Label, Text, Tooltip, … (feat(rtl): migrate primitives to logical properties — Badge, Input, Label, Text, Switch #357; components without physical classes needed no changes)
2. Layout & navigation: Card, Modal, Sheet, Sidebar, Tabs, Breadcrumb, Pagination, Table, AppHeader, … (feat(rtl): migrate layout + nav to logical properties — AppHeader, Card, Sheet, Sidebar, Table #358; Modal/Tabs/Breadcrumb/Pagination had no physical classes — Sheet/Sidebar slide transforms handled with rtl: mirrors)
3. Composite/feature modules: OrderEditor, ScheduleCalendar, Messaging, Dashboard, FileManager, … (Messaging + AI done in feat(rtl): migrate Messaging + AI to logical properties #380; DocumentScanner + MediaEditor + TranscriptView done in feat(rtl): migrate DocumentScanner, MediaEditor, TranscriptView to logical properties #425; billing/invoices done in feat(rtl): migrate billing/invoice components to logical properties #426; services/employer done in feat(rtl): migrate services/employer components to logical properties #427; scheduling + clinical + orders done in feat(rtl): migrate scheduling and clinical components to logical properties #428; shell/misc — SiteHeader, CommandPalette, CookieConsent, SuperChat, FileManager, dialogs, and everything else — done in feat(rtl): migrate shell and misc components to logical properties #429; Toast + FloatingWindow done in feat(rtl): logical Toast positions, FloatingWindow cleanup, zero the ratchet baseline #430; directional icon mirroring done in feat(rtl): mirror directional navigation icons in RTL (Phase 2 batch 2) #438)
4. Third-party wrappers: AGGrid, DataVis, ESheet, RichEditor, YChart (individually, last)

Phase 4 — Verification & guardrails

• Extend Playwright visual suite: snapshot a curated story set in both dir values (2× matrix only for direction-sensitive components)
• Per-component RTL checklist in PR template: mirrored layout / icons flip correctly / keyboard inverted / LTR islands preserved / no horizontal scrollbar leaks
• Docs: add "direction-agnostic styling" section to copilot-instructions / lessons so future components are born RTL-safe

First milestone

Phase 0 + codemod on ~10 primitives, verified with the new toolbar switch.
Proves the full pipeline (switch → logical classes → visual check → lint guard)

[garrity-miepub]

RTL work is now landing as a series of small PRs (supersedes #320):

• 1. Infrastructure — feat(rtl): RTL infrastructure — scan guard, codemod, useDirection, Storybook direction toolbar #356
• 2. Primitives (Badge, Input, Label, Text, Switch)
• 3. Layout + nav (AppHeader, Card, Sheet, Sidebar, Table)
• 4. Messaging + AI
• 5. DocumentScanner + media (MediaEditor, TranscriptView)
• 6. Billing/invoices
• 7. Services/employer
• 8. Scheduling + clinical
• 9. Shell/misc (SiteHeader, CommandPalette, CookieConsent, …)

Each merge cuts a 0.7.2-dev.x release for in-the-wild validation; full release after the series completes. Then Phase 2 (icon flips, JS positioning, LTR islands, third-party RTL flags) as follow-ups.