@mieweb/ui 0.11.0-dev.16 → 0.11.0-dev.18

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

@@ -0,0 +1,336 @@
+---
+name: mieweb-ui-catalog
+description: Component inventory and selection guidance for the @mieweb/ui design system. USE WHEN choosing a component ("which component for X?", "Card or Panel?", "which table?"), checking whether a component exists, finding the import entry point, or linking to its docs.
+---
+
+<!-- GENERATED by scripts/build-agent-skills.mjs — do not edit by hand. Regenerate with `pnpm agent:skills`. -->
+
+# @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).
+
+For per-component "Which one?" comparison tables, read [selection-guidance.md](./selection-guidance.md) in this skill and jump to the family's section.
+
+**Selection ground rules** (from the installed `mieweb-ui.instructions.md` — they always apply):
+
+1. Tables and data grids start with **DataVis NITRO**; `Table` only for a few static rows. `AGGrid` is deprecated.
+2. Two or more adjacent buttons, or one with a long/unpredictable label → `ButtonGroup`.
+3. Use an existing component before writing your own — raw HTML that duplicates a component is a violation.
+4. Use composition slots and variant/size props, not custom markup or className hacks.
+
+## Entry points
+
+| Entry | Use for |
+| ----- | ------- |
+| `@mieweb/ui` | General-purpose components — the default when the inventory shows no entry annotation |
+| `@mieweb/ui/datavis` | DataVis NITRO grid + graph — the default for all tables (deps bundled) |
+| `@mieweb/ui/esheet` | eSheet form-field adapters |
+| `@mieweb/ui/kerebron` | RichEditor / CodeEditor (keeps Kerebron WASM optional) |
+| `@mieweb/ui/hooks` | Shared React hooks |
+| `@mieweb/ui/utils` | Utility functions |
+| `@mieweb/ui/tailwind-preset` | Tailwind preset (design tokens) |
+| `@mieweb/ui/brands` | Brand CSS + presets (bluehive, mieweb, webchart, …) |
+| `@mieweb/ui/templates` | Landing-page sections + LandingPage renderer (Server Component safe) |
+| `@mieweb/ui/deck` | Full-screen slide decks from JSON slides (client-only) |
+| `@mieweb/ui/maps` | Leaflet maps (PointMap; peer: leaflet) |
+| `@mieweb/ui/globe` | Globe showcase (peers: react-globe.gl, three) |
+| `@mieweb/ui/org-chart` | OrgChart (peers: @xyflow/react, elkjs) |
+| `@mieweb/ui/motion` | MotionProvider (keeps the motion dependency optional) |
+| `@mieweb/ui/q` | Q editor (peer: @mieweb/q) |
+| `@mieweb/ui/components/SuperChat` | SuperChat, SuperChatInbox, SuperChatConversations — not exported from the root; plugins at `/components/SuperChat/plugins` |
+| `@mieweb/ui/components/<Name>` | Any single component, when the inventory annotates it with a `/components/…` entry |
+| `@mieweb/ui/ag-grid` | **Deprecated** — never in new code; use `/datavis` |
+
+## Inventory
+
+Components by tier and family. Annotations: maturity when not stable, and the import entry when it is not the root (e.g. _(`/datavis`)_).
+
+### Foundations
+
+- Colors, Icons, Motion _(experimental, `/motion`)_, Text, ThemeProvider, VisuallyHidden
+
+### Inputs
+
+- **Actions:** Button, ButtonGroup, CopyButton, QuickAction, RowActionToolbar, Toggle
+- **Choice inputs:** Autocomplete, Checkbox, CountryCodeDropdown, CountryDropdown, Dropdown, PillSelect, Radio, Select, Slider, Switch
+- **Composite forms:** AdditionalFields, CSVColumnMapper, ESheet Builder _(`/esheet`)_, ESheet Renderer _(`/esheet`)_, LanguageSelector, LogoUploader _(experimental)_, PermissionsEditor, SliderCalculator _(experimental)_, UserPicker _(experimental)_
+- **Date & time:** BusinessHours, BusinessHoursEditor, DateInput, DateRangePicker, ScheduleCalendar, SchedulePicker
+- **Text inputs:** Address, AddressForm, InlineEdit _(experimental)_, Input, Label, PhoneInput, PhoneInputGroup, TagEditor _(experimental)_, Textarea, WebsiteInput
+
+### Components
+
+- **Data display:** Avatar, Badge, CalendarHeatmap _(experimental)_, ClampedText, CountBadge, FilterSummaryBar, FreshnessBadge, Timeline, YChart _(experimental)_, YearTimeline _(experimental)_
+- **Feedback:** Alert, AlertDialog, CollabStatus, ConnectionStatus, ErrorPage, NotificationCenter, Toast
+- **Grids:** DataVis NITRO _(`/datavis`)_, DataVis NITRO Demos, DataVis NITRO Graph _(`/datavis`)_, Pagination, Sparkline, Table
+- **Layout:** Accordion, AppHeader, Card, Collapsible, PageHeader, ProductVersion, ScrollArea, Separator, SiteFooter, SiteHeader
+- **Loading:** LoadingPage, Progress, Skeleton, Spinner
+- **Navigation:** Breadcrumb, CommandPalette, MegaMenu _(experimental)_, OnboardingWizard, ReadingProgressBar, SectionSpyNav, StepIndicator, TableOfContents, Tabs
+- **Overlays:** CookieConsent, DockablePanel, FloatingWindow, GlossaryTooltip, KeyboardShortcutsOverlay, Modal, Sheet, Sidebar, SourceTip, Tooltip
+- **Record details:** AvatarGroup _(experimental)_, CompletenessMeter _(experimental)_, PhiMask _(experimental)_, PropertyList _(experimental)_, Rating _(experimental)_, RecordHeader _(experimental)_, ReviewCard _(experimental)_
+- **Showcase:** Globe _(experimental, `/globe`)_, OrbitRing _(experimental)_, RadialExplorer _(experimental)_
+
+### Modules
+
+- **Chat:** AIChat, AIChat (Voice), AIMessage, ChatComposer _(beta)_, 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
+- **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
+
+### Templates
+
+- **Content:** ComparisonSection _(experimental, `/templates`)_, FaqSection _(experimental, `/templates`)_, FeatureGridSection _(experimental, `/templates`)_, ProcessStepsSection _(experimental, `/templates`)_, ResourceCardsSection _(experimental, `/templates`)_, SplitContentSection _(experimental, `/templates`)_, VideoSection _(experimental, `/templates`)_
+- **Conversion:** CtaSection _(experimental, `/templates`)_, HeroSection _(experimental, `/templates`)_, LeadFormSection _(experimental, `/templates`)_, PricingSection _(experimental, `/templates`)_
+- **Pages:** LandingPage _(experimental, `/templates`)_
+- **Reports:** BenchmarkTableSection _(experimental, `/templates`)_, LinkGroupsSection _(experimental, `/templates`)_, MetricListSection _(experimental, `/templates`)_, MetricStatusBadge _(experimental, `/templates`)_, PdfEmbedSection _(experimental, `/templates`)_, RankedListSection _(experimental, `/templates`)_, ReportByline _(experimental, `/templates`)_, ReportLegend _(experimental, `/templates`)_, ReportMethodology _(experimental, `/templates`)_, TileCartogramSection _(experimental, `/templates`)_
+- **Social proof:** LogoCloudSection _(experimental, `/templates`)_, StatsSection _(experimental, `/templates`)_, TestimonialSection _(experimental, `/templates`)_
+
+### Healthcare
+
+- **Clinical lists:** AllergyList, AllergyListField (eSheet) _(`/esheet`)_, CodeLookup, ConditionEditor, MedicationList, MedicationListField (eSheet) _(`/esheet`)_, PresentingProblems, ProblemList
+- **Encounter & orders:** Assessment, CaseManagementHeader, HealthSurveillance, OrderEditor, PatientHeader, WebChartReportViewer
+
+### BlueHive
+
+- **Billing:** CreateInvoiceModal, InvoiceList, InvoicePaymentPage, InvoiceView, PaymentHistoryTable, PaymentMethod, PendingClaimsTable, StripeBadge
+- **Employers:** EmployeeForm, EmployeeProfile, EmployerContactCard, EmployerList, EmployerPricingCard, EmployerServiceModal, EmployerView
+- **Operations:** HelpSupportPanel, InventoryManager, ResultsEntryForm
+- **Orders:** Order Inbox (Demo) _(experimental)_, OrderCard, OrderConfirmationWizard, OrderList, OrderLookupForm, OrderSidebar
+- **Providers:** ClaimProviderForm, ProviderCard, ProviderDetailHeader, ProviderOverview, ProviderSearchBar, ProviderSearchFilters, ProviderSelector, ProviderSettings, ProviderUsersTable
+- **Services:** RecurringServiceCard, ServiceAccordion, ServiceBadge, ServiceCard, ServiceGeneralSettings, ServiceGrid, ServicePicker, ServicePricingManager, ServiceShippingSettings, SetupServiceModal
+- **Users & integrations:** AddContactModal, AuthDialog, BookingDialog, CheckrIntegration, CreateReferralModal, EditUserRoleModal, HRISProviderSelector, InviteUserModal, RejectionModal, SSOConfigForm
+
+### Deprecated
+
+- AGGrid _(deprecated, `/ag-grid`)_, AGGrid Enhanced _(deprecated, `/ag-grid`)_
+
+## Family policies
+
+The one-line rule that governs each family. When a task touches a family, read its full "Which one?" table in [selection-guidance.md](./selection-guidance.md).
+
+**Actions** (Inputs):
+
+> **Two or more buttons, or one button with a long, translated or user-supplied label, always go
+> in a `ButtonGroup`.** Its default `orientation="auto"` stacks before any label truncates.
+
+**Chat** (Modules):
+
+> **Who is talking, and what do the messages contain?** One user and one assistant, messages
+> may carry tool calls / thinking / code blocks → `AIChat` (or the Ozwell-branded shell around it,
+> `OzwellChat`). Several humans and/or several agents in one thread, Markdown with plugins, a
+> conversation list → [SuperChat](https://ui.mieweb.org/?path=/docs/modules-superchat-overview--docs). Humans messaging
+> humans with delivery status, read receipts and attachments → the `Messaging` primitives. Talking
+> instead of typing → [Voice](https://ui.mieweb.org/?path=/docs/modules-voice-overview--docs). Reviewing AI-proposed
+> field changes rather than chatting → `AIReconciliationPanel`.
+
+**Choice inputs** (Inputs):
+
+> **Is the user picking a value, or running an action?** A value the form will save → `Select`
+> (or `Radio` when all options fit on screen, `Checkbox` when several may be on). An action or
+> menu → `Dropdown`. A value found by typing into a large or remote list → `Autocomplete`. A
+> setting that applies the instant it flips → `Switch`; a pressed toolbar button →
+> [Toggle](https://ui.mieweb.org/?path=/docs/actions-toggle--docs). A one-of-N view switch in a toolbar → `PillSelect`.
+
+**Clinical lists** (Healthcare):
+
+> **Whose list is it, and what scope?** The **chart** owns problems, medications and allergies
+> as durable records; an **encounter** only references them. Chart-scope problems →
+> `ProblemList`; this visit's relevance → `PresentingProblems`; the write side of a problem →
+> `ConditionEditor`. Medications to reconcile → `MedicationList` (start with
+> `MedicationReconciliation`); allergies with an explicit NKA → `AllergyList` (start with
+> `AllergyManager`). Every coded pick goes through `CodeLookup`, dependency-injected. The two
+> `…Field (eSheet)` entries are the same lists as eSheet form questions.
+
+**Composite forms** (Inputs):
+
+> **These are whole form sections and tools assembled from the primitives — the host still owns
+> submission and persistence.** Every component here is controlled (`value` + `onChange`, or a
+> ref you read), has no `name`, and never talks to a server. Pick by _who defines the fields and
+> when_: an author designing a reusable template → `ESheet Builder`; someone filling that template
+> → `ESheet Renderer`; the end user inventing a few extra key/value pairs → `AdditionalFields`;
+> matching a spreadsheet's columns to fields you already have → `CSVColumnMapper`; assigning a
+> user's capabilities → `PermissionsEditor`; switching the UI language → `LanguageSelector`.
+
+**Content** (Templates):
+
+> **The body of a marketing page.** What the product does, how it works, how it compares, what
+> people ask, and where to read more — each as a heading plus plain-data items.
+
+**Conversion** (Templates):
+
+> **Where a marketing page asks for something.** The hero makes the first ask, the call-to-action
+> band makes the last, and the lead form converts without leaving the page. All three render real
+> anchors or a real `<form>` — no client state.
+
+**Dashboards** (Modules):
+
+> **Widget or container?** The tile is `DashboardWidget` (a `Card` with a fixed title bar and
+> four body shapes). The thing that arranges tiles is `CustomizableDashboard` (user-draggable,
+> hide/show, persisted) — or plain CSS grid when the layout is fixed by design.
+> `ReportDashboard` is a finished analytics _page_, not a container. `QuickLinksCard` is a
+> titled list of shortcuts; `DashboardCustomizePanel` is the show/hide sheet, exported
+> standalone. The two **(Demo)** entries are Storybook-only compositions to copy from, not
+> exports.
+
+**Data display** (Components):
+
+> **Who decides what the chip means?** If the host already knows the state ("Active", "Draft")
+> → `Badge`. If the number is a count the user can click into → `CountBadge`. If the colour
+> should follow how old a date is → `FreshnessBadge`. A person → `Avatar`; long prose →
+> `ClampedText`; a process or its history → `Timeline`; the "N of M records" line above a
+> filtered grid → `FilterSummaryBar`. `YChart` is a Storybook-only demo and is not exported.
+
+**Date & time** (Inputs):
+
+> **Dates go through `DateInput` (one date) or `DateRangePicker` (start/end) — never a raw
+> `<input type="date">`.** Keep dates as Luxon `DateTime` with an explicit IANA zone in
+> application code and ISO-8601 on the wire; the components below hand you strings or local
+> `Date`s, so convert at the boundary. Picking from _available_ slots is `SchedulePicker`;
+> showing booked appointments is `ScheduleCalendar`; recurring weekly hours are `BusinessHours`
+> (show) and `BusinessHoursEditor` (edit).
+
+**Editors** (Modules):
+
+> **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`.
+> 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).
+
+**Encounter & orders** (Healthcare):
+
+> **What does the page lead with, and what data does it get?** 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
+> at the top of a **patient** page → `PatientHeader`; of a **case** page → `CaseManagementHeader`.
+> Canned reports from a WebChart-style backend → `WebChartReportViewer`. None of them talks to a
+> server — every backend contract is props in, callbacks out.
+
+**Feedback** (Components):
+
+> **Use `Toast` for what the user just did, `Alert` for what they need to keep seeing, and
+> `AlertDialog` for what they must decide.** `Toast` (polite live region), `Alert`
+> (`role="alert"`, announces on mount) and `ConnectionStatus` (assertive) announce themselves —
+> never wrap them in extra live regions, and avoid mounting several announcing components at once.
+
+**Files** (Modules):
+
+> **Same task — get a file from the user — three shapes.** A drag target over content you
+> already render, invisible until a drag starts → `DropzoneOverlay` + `useDropzone`. A standing
+> "files on this record" card with a table, storage meter and per-row actions → `FileManager`.
+> One document that must be validated, previewed, possibly photographed, and sent to an
+> extraction endpoint → `DocumentScanner`.
+
+**Grids** (Components):
+
+> **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.
+
+**Layout** (Components):
+
+> **What are you framing?** A block of related content → `Card`. Content that hides behind a
+> heading → `Accordion` (a styled stack) or `Collapsible` (one headless toggle). A region that
+> must scroll inside a fixed box → `ScrollArea`. A rule between things → `Separator`. The bar
+> across the top → `AppHeader` for the signed-in app, `SiteHeader` for the public site,
+> `PageHeader` for the title block _inside_ a page. The bottom of a public page → `SiteFooter`
+> (or `SimpleFooter`), with `ProductVersion` for the deployed version line.
+
+**Loading** (Components):
+
+> **Known shape → `Skeleton`. Unknown shape, short wait → `Spinner`. Measurable → `Progress`.
+> Whole route → `LoadingPage`.** Skeletons are hidden from screen readers, so announce loading
+> elsewhere when you use them.
+
+**Media** (Modules):
+
+> **Is the user recording, playing, or reading along?** Capturing a take → `AudioRecorder`
+> (a panel with review) or `RecordButton` (one button that hands off a `Blob`). Playing a clip
+> → `AudioPlayer` (styled, audio-only, seconds) or `MediaPlayer` (native `<audio>`/`<video>`,
+> milliseconds). Reading along → `TranscriptView` (read-only, click-to-seek). Editing the
+> words of a recording → `MediaEditor`, which already contains a `MediaPlayer`. The
+> **MediaEditor Live Demo** is a Storybook page, not a component.
+
+**Navigation** (Components):
+
+> **Where is the user going?** Between peer views of one page → `Tabs`. Up a hierarchy →
+> `Breadcrumb`. Between sections of the page they are on → `TableOfContents` (sidebar
+> outline) or `SectionSpyNav` (sticky band), with `ReadingProgressBar` for how far they've
+> read. Through an ordered flow → `StepIndicator` (just the rail) or `OnboardingWizard` (the
+> whole takeover). Anywhere, by typing → `CommandPalette`. Between routes with a persistent
+> rail → [Sidebar](https://ui.mieweb.org/?path=/docs/overlays-sidebar--docs) (Overlays).
+
+**Overlays** (Components):
+
+> **Does the user have to deal with it now?** Yes → `Modal` (or `AlertDialog` for a decision).
+> Beside the page → `Sheet`. Set it aside and come back → `DockablePanel`. Move it around →
+> `FloatingWindow`. Just a hint → one of the three tips.
+
+**Pages** (Templates):
+
+> **A marketing page is data.** `LandingPage` renders an array of `blocks` — each a section's
+> props tagged with a `type` — so an industry hub, a service page or a campaign page is a content
+> file, not a component. Everything in the Templates tier is plain data in, static HTML out, and
+> safe to render from a React Server Component via `@mieweb/ui/templates`.
+
+**Presentations** (Modules):
+
+> **One idea per screen, read in order, shared as a link.** Board updates, growth reviews and
+> talks published as pages. Both live on optional entries so their weight stays out of apps
+> that don't present.
+
+**Record details** (Components):
+
+> **The pieces that describe one record** — a contact, company, clinic, patient or deal.
+> `RecordHeader` names it, `PropertyList` lists its fields, and the rest add the details a
+> record page keeps needing: who's here, what's hidden, how complete it is, how it's rated.
+
+**Records** (Modules):
+
+> **The collections around one record, and the frame that holds them.** `RecordLayout` places
+> the header, fields and tabs; the modules fill the tabs and side columns with what happened
+> (`ActivityFeed`), what changed (`FieldHistory`), what's related (`AssociationList`), what's
+> next (`ActionPlan`) and who's who (`OrgChart`). Each renders data you pass in and reports
+> changes through callbacks — none of them fetches.
+
+**Reports** (Templates):
+
+> **Published data a reader can check.** A report is only as credible as its provenance: label
+> every figure live, modeled or maturing, cite its source, and say who wrote it. These sections
+> are `LandingPage` blocks, so a report is a content file — see the `benchmark-report` preset.
+
+**Showcase** (Components):
+
+> **Hero and front-door set pieces.** These components exist to make a first
+> impression — a global footprint, an orbiting ecosystem, an explorable product
+> ring. They are self-running, motion-driven and decorative by design: if the
+> visitor must _read, compare or navigate_ the content, reach for Data display,
+> Navigation or a plain layout instead.
+
+**Social proof** (Templates):
+
+> **Evidence that other people chose this.** Numbers, names and quotes — each a claim the page has
+> to stand behind, so cite figures and only publish quotes and logos you have permission to use.
+
+**Text inputs** (Inputs):
+
+> **What is the value?** Free text on one line → `Input`; several lines → `Textarea`. 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
+> component has one, `Label` + `htmlFor` where it does not.
+
+**Views** (Modules):
+
+> **One set of accessors, every view.** A page that shows a collection of things describes
+> that collection once — `getId`, `getTitle`, `getStatus`, `getStart`, `getEnd`, `getGroup` —
+> and every view in this family reads through it. Switching from a list to a board to a Gantt
+> is a prop, not another component to build. The views are **headless**: they never fetch,
+> subscribe, or navigate. Data arrives as `items`; changes leave through `on*` callbacks.