@mieweb/ui 0.11.0-dev.17 → 0.11.0-dev.19

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

@@ -0,0 +1,709 @@
+<!-- GENERATED by scripts/build-agent-skills.mjs — do not edit by hand. Regenerate with `pnpm agent:skills`. -->
+
+# @mieweb/ui selection guidance by family
+
+Extracted from the catalog family pages (`src/catalog/*.mdx`): the family policy and the "Which one?" comparison. Each family's Storybook Overview page has the full version (how the pieces fit together, shared limitations).
+
+<!-- source: src/catalog/Actions.mdx (Inputs) -->
+# Actions
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [Button](https://ui.mieweb.org/?path=/docs/actions-button--docs) | The user triggers an action: submit, open, save, delete | The control keeps an on/off state |
+| [ButtonGroup](https://ui.mieweb.org/?path=/docs/actions-buttongroup--docs) | Laying out any set of Buttons (dialog footers, form actions, card CTAs) | Children are not Buttons |
+| [Toggle](https://ui.mieweb.org/?path=/docs/actions-toggle--docs) | A pressed/unpressed option that applies immediately (toolbar, view filter) | The setting is saved with a form — use `Switch` |
+| [CopyButton](https://ui.mieweb.org/?path=/docs/actions-copybutton--docs) | Copying a value (ID, email, key) to the clipboard, even inside clickable rows | Anything other than plain-text copy |
+| [QuickAction](https://ui.mieweb.org/?path=/docs/actions-quickaction--docs) | A large, explained shortcut tile on a dashboard | Inline in content or forms |
+| [RowActionToolbar](https://ui.mieweb.org/?path=/docs/actions-rowactiontoolbar--docs) | Per-row icon actions revealed on hover/focus in lists and NITRO grids | Labelled actions in a footer — use `ButtonGroup` |
+
+---
+
+<!-- source: src/catalog/Chat.mdx (Modules) -->
+# Chat
+
+> **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`.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [AIChat](https://ui.mieweb.org/?path=/docs/chat-aichat--docs) | One user ↔ one assistant; you own transport and push `AIMessage[]` with `status`, `isGenerating`; suggestions chips; `FloatingAIChat` / `AIChatModal` for a corner popup | Multiple participants or a conversation list — `SuperChatInbox`; human-to-human messaging — `Messaging`; Markdown out of the box — pass `renderTextContent` |
+| [AIChat (Voice)](https://ui.mieweb.org/?path=/docs/chat-aichat-voice--docs) | Reference wiring of `AIChat talkToText` → `transcribeBlob` (on-device Whisper) → send, with a streamed reply when a backend is configured | Hands-free wake words, speaker gating or diarization — `HandsFreeChat`; server ASR — `transcribeServer` |
+| [AIMessage](https://ui.mieweb.org/?path=/docs/chat-aimessage--docs) | Rendering one `AIMessage` (text / tool_use / thinking / code / image / file / audio / video blocks) inside your own thread layout; `ChatBubble` shell; `renderTextContent` seam | You need the whole chat — `AIChat`; human messages with receipts — Messaging's `MessageBubble` |
+| [ChatComposer](https://ui.mieweb.org/?path=/docs/chat-chatcomposer--docs) | The standardized chat input for new work: textarea on top, quiet icon toolbar (`+` menu, mic, send⇄stop), optional agent + model selector rows, @mention autocomplete, reply-to preview, attachments via picker/paste/drag-drop/`addFiles` | A single-line command input — `Input` / `CommandPalette` |
+| [MCPToolCall](https://ui.mieweb.org/?path=/docs/chat-mcptoolcall--docs) | Showing a tool invocation as a status pill that expands into result, links, error and parameters; `compact` for dense logs | Approving/cancelling calls (display-only); large `result.data` (only `summary`/links render) |
+| [OzwellChat](https://ui.mieweb.org/?path=/docs/chat-ozwellchat--docs) | You are the Ozwell application: thinking-mode menu, message jump list, warning strip, model picker, queued follow-up editing, "Powered by Ozwell" footer | A generic assistant in your own product — `AIChat`; multi-participant — `SuperChat` |
+| [ComposerModelSelector](https://ui.mieweb.org/?path=/docs/chat-composermodelselector--docs) | Picking an LLM per message from a short provider-grouped list inside a composer; menu opens upward within `boundaryRef`; optional effort drill-down | A normal form field — `Select` / `Dropdown`; options are not provider/model pairs; hundreds of options — `Autocomplete` |
+| [ReconciliationPanel](https://ui.mieweb.org/?path=/docs/chat-reconciliationpanel--docs) | A person must confirm AI-extracted values (OCR, parsed intake, agent output) before they overwrite data on file; confidence-aware defaults; `onApply(accepted)` | No existing record to compare (use a form); a single yes/no — `AlertDialog`; long-text diffs |
+| [Messaging](https://ui.mieweb.org/?path=/docs/chat-messaging--docs) | Human-to-human messaging primitives — `MessageBubble`, `MessageList` (live `role="log"`), `MessageThread` (mounts `ChatComposer`), `MessagingSplitView`; the legacy `MessageComposer` was retired in 0.10.0 (superseded by `ChatComposer`, see `MIGRATION.md#chat-composer`) | The other party is an AI with tool calls — `AIChat`; a finished multi-participant inbox — `SuperChatInbox`; real-time transport (bring your own) |
+
+---
+
+<!-- source: src/catalog/ChoiceInputs.mdx (Inputs) -->
+# Choice 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`.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [Checkbox](https://ui.mieweb.org/?path=/docs/choice-inputs-checkbox--docs) | Zero or more independent options, saved with the form; a "select all" with `indeterminate` | It takes effect immediately — `Switch`; exactly one option — `Radio` |
+| [Radio](https://ui.mieweb.org/?path=/docs/choice-inputs-radio--docs) | Exactly one of 2–7 options, all visible, inside a `RadioGroup` | More options or search — `Select`; toolbar space — `PillSelect` |
+| [Switch](https://ui.mieweb.org/?path=/docs/choice-inputs-switch--docs) | An on/off setting that applies at once (`role="switch"`) | The value is submitted with a form — `Checkbox`; a toolbar pressed state — [Toggle](https://ui.mieweb.org/?path=/docs/actions-toggle--docs) |
+| [Select](https://ui.mieweb.org/?path=/docs/choice-inputs-select--docs) | Picking a value (or several with `multiple`) from a known list of ~8+ options in a form; groups; local search | The items are actions — `Dropdown`; the list is huge or remote — `Autocomplete` |
+| [Dropdown](https://ui.mieweb.org/?path=/docs/choice-inputs-dropdown--docs) | A menu of actions or links (`role="menu"`), row "⋯" menus, tick-box filters (`multiSelect`) | Choosing a form value — `Select`; app-wide command search — [CommandPalette](https://ui.mieweb.org/?path=/docs/navigation-commandpalette--docs) |
+| [Autocomplete](https://ui.mieweb.org/?path=/docs/choice-inputs-autocomplete--docs) | Typing to find an item in a large, remote or creatable list (patients, drugs, articles) | A short known list — `Select`; the value must stay in the field with validation — `Select` / `Input` |
+| [PillSelect](https://ui.mieweb.org/?path=/docs/choice-inputs-pillselect--docs) | A compact "Label: Value" pill for a one-of-N view/sort/period choice in a toolbar | A validated form field — `Select`; options should all be visible — `Radio` |
+| [Slider](https://ui.mieweb.org/?path=/docs/choice-inputs-slider--docs) | An approximate number in a bounded range with live feedback (volume, opacity, pain score) | Exact digits matter — `Input type="number"`; two thumbs (not supported) |
+| [CountryDropdown](https://ui.mieweb.org/?path=/docs/choice-inputs-countrydropdown--docs) | A country for an address or nationality — the list, flags and localized names are built in | It accompanies a phone number — `CountryCodeDropdown`; a curated subset — `Select` |
+| [CountryCodeDropdown](https://ui.mieweb.org/?path=/docs/choice-inputs-countrycodedropdown--docs) | A dial-code picker beside an `Input` for international phone numbers (`validatePhoneNumber`, `formatE164`) | US/Canada only — [PhoneInput](https://ui.mieweb.org/?path=/docs/text-inputs-phoneinput--docs); the country itself — `CountryDropdown` |
+
+Free text, phones and URLs live in [Text inputs](https://ui.mieweb.org/?path=/docs/inputs-text-inputs-overview--docs);
+dates go to [DateInput](https://ui.mieweb.org/?path=/docs/date-time-dateinput--docs).
+
+---
+
+<!-- source: src/catalog/ClinicalLists.mdx (Healthcare) -->
+# Clinical lists
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [ProblemList](https://ui.mieweb.org/?path=/docs/clinical-lists-problemlist--docs) | The **chart-scope** problem list: `ConditionConcern[]` with clinical status groups, assertion history, coding chips, relationships, observations; `onAction` / `onAddProblem` / `onReorder` | You need this visit's relevance — `PresentingProblems`; today's A&P — `Assessment`; to edit codes — `ConditionEditor` |
+| [PresentingProblems](https://ui.mieweb.org/?path=/docs/clinical-lists-presentingproblems--docs) | The **encounter-scope** view: pick chart concerns relevant this visit and tag **Addressed / Relevant Hx / Noted** on the encounter reference; `scope` gates the _no known problems_ negative assertion | You are maintaining the chart list — `ProblemList`; you need orders under problems — `Assessment` |
+| [ConditionEditor](https://ui.mieweb.org/?path=/docs/clinical-lists-conditioneditor--docs) | A row action needs a **form**: `add` / `refine` / `revise` / `relate` / `observe`, capture-first with three-state uncertainty; returns a `ConditionAssertionDraft` the host appends; `renderCodeSearch` injects `CodeLookup` | Editing a medication or an order — `MedicationEditor` / `OrderEditor`; you only display conditions |
+| [MedicationList](https://ui.mieweb.org/?path=/docs/clinical-lists-medicationlist--docs) | **Presenting medications** grouped by reconciliation status. `MedicationReconciliation` = batteries included (NCPDP `MedicationEditor`, dialogs, quick-add, `inlineAddSearch`); `MedicationList` = presentational, you own the dialogs | Allergies — `AllergyList`; placing a new order in the plan — `Assessment` + `OrderEditor`; a header summary — `PatientHeader` medication banner |
+| [AllergyList](https://ui.mieweb.org/?path=/docs/clinical-lists-allergylist--docs) | Allergy / intolerance list grouped by category with severity and **tri-state NKA** ("not recorded" until _Confirm: no known allergies_). `AllergyManager` = batteries included; `AllergyList` = presentational | Medications — `MedicationList`; a red pill banner only — `PatientHeader`; drug–allergy checking (nothing here cross-references) |
+| [CodeLookup](https://ui.mieweb.org/?path=/docs/clinical-lists-codelookup--docs) | Any **coded pick** — diagnosis, drug, lab, procedure, vaccine, surveillance program — searched offline in a Web Worker over pre-built shards; embed `bare` or inject app-wide via `CodeLookupProvider` | Your own data or an API — `Autocomplete`; you cannot serve the shards or run a worker — every consumer falls back to plain text |
+| [MedicationListField (eSheet)](https://ui.mieweb.org/?path=/docs/clinical-lists-medicationlistfield-esheet--docs) | The medication list is a **question in an eSheet form**; `registerMedicationListFieldType({ codeLookup })` once, answer stored as `{ medications }` JSON | The page is not an eSheet form — use `MedicationReconciliation` directly |
+| [AllergyListField (eSheet)](https://ui.mieweb.org/?path=/docs/clinical-lists-allergylistfield-esheet--docs) | The allergy question in an eSheet form, storing `{ allergies, noKnownAllergies }`; `registerAllergyListFieldType({ codeLookup })` (or `registerMieEsheetFields` for both) | The page is not an eSheet form — use `AllergyManager` directly |
+
+---
+
+<!-- source: src/catalog/CompositeForms.mdx (Inputs) -->
+# Composite forms
+
+> **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`.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [AdditionalFields](https://ui.mieweb.org/?path=/docs/composite-forms-additionalfields--docs) | A collapsible "extras" block where the person filling the form adds free name/value rows (`KeyValueEntry[]`, `maxEntries`) | Fields should be typed, validated and reused — `ESheet Builder`; keys are a known vocabulary — per-key `Input` / `Select` |
+| [CSVColumnMapper](https://ui.mieweb.org/?path=/docs/composite-forms-csvcolumnmapper--docs) | The mapping step of a CSV import: one card per column with a `Select` of your fields, sub-fields, ignore/include and bulk actions; `CSVFileUpload` drop zone | You need parsing or validation (bring `papaparse` and your own rules); users are adding attributes, not mapping — `AdditionalFields` |
+| [PermissionsEditor](https://ui.mieweb.org/?path=/docs/composite-forms-permissionseditor--docs) | Assigning a hierarchy of permissions (groups › permission › child) plus optional employer scope to a user, with a summary | One role from a list — `Select` / `RadioGroup`; a flat handful of flags — `CheckboxGroup`; a roles × permissions matrix (not provided) |
+| [LanguageSelector](https://ui.mieweb.org/?path=/docs/composite-forms-languageselector--docs) | A header/settings UI-language switcher with a built-in list, flags and native names; `LanguageSelectorNative` for mobile, `LanguageSelectorInline` for 2–5 | A country — `CountryDropdown`; a validated form value with label/error — `Select` |
+| [ESheet Builder](https://ui.mieweb.org/?path=/docs/composite-forms-esheet-builder--docs) | An administrator designs or edits a form template (`FormDefinition` JSON) with a palette, properties and drag-and-drop | You only need to display/fill a template — `ESheet Renderer`; the schema is fixed at build time — compose primitives directly |
+| [UserPicker](https://ui.mieweb.org/?path=/docs/composite-forms-userpicker--docs) | Assigning an owner or assignees from a list of people, with avatars and search | Choosing from non-people options — `Select` / `Autocomplete` |
+| [LogoUploader](https://ui.mieweb.org/?path=/docs/composite-forms-logouploader--docs) | Setting one image for a record (logo, photo) with preview, size check and remove | Several files or documents — `FileManager` / `DocumentScanner` |
+| [ESheet Renderer](https://ui.mieweb.org/?path=/docs/composite-forms-esheet-renderer--docs) | Rendering an eSheet / SurveyJS / MCP definition as live fields and reading validated answers through `getValidResponse()` | Editing the definition — `ESheet Builder`; you expect a submit button or persistence (host provides both) |
+
+Single fields live in [Text inputs](https://ui.mieweb.org/?path=/docs/inputs-text-inputs-overview--docs),
+[Choice inputs](https://ui.mieweb.org/?path=/docs/inputs-choice-inputs-overview--docs) and
+[Date & time](https://ui.mieweb.org/?path=/docs/inputs-date-time-overview--docs). The eSheet clinical field types
+(`medicationList`, `allergyList`) are documented under Healthcare › Clinical lists.
+
+---
+
+<!-- source: src/catalog/Content.mdx (Templates) -->
+# Content
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [FeatureGridSection](https://ui.mieweb.org/?path=/docs/content-featuregridsection--docs) | Three to eight parallel capabilities or benefits, one line each | One idea needs an image and an argument — [SplitContentSection](https://ui.mieweb.org/?path=/docs/content-splitcontentsection--docs) |
+| [SplitContentSection](https://ui.mieweb.org/?path=/docs/content-splitcontentsection--docs) | One argument made beside an image, with proof points | Several parallel points — [FeatureGridSection](https://ui.mieweb.org/?path=/docs/content-featuregridsection--docs) |
+| [ProcessStepsSection](https://ui.mieweb.org/?path=/docs/content-processstepssection--docs) | Two to four ordered steps: "how it works", "get started" | A record's progress over time in an app — [Timeline](https://ui.mieweb.org/?path=/docs/data-display-timeline--docs) |
+| [ComparisonSection](https://ui.mieweb.org/?path=/docs/content-comparisonsection--docs) | Your product against an alternative or the status quo, by row | Users sort or filter the rows — [DataVis NITRO](https://ui.mieweb.org/?path=/docs/grids-datavis-nitro--docs) |
+| [FaqSection](https://ui.mieweb.org/?path=/docs/content-faqsection--docs) | Plain-text questions and answers that should be in the HTML | Rich or single-open panels in an app — [Accordion](https://ui.mieweb.org/?path=/docs/layout-accordion--docs) |
+| [ResourceCardsSection](https://ui.mieweb.org/?path=/docs/content-resourcecardssection--docs) | Linked cards to guides, articles, case studies, reports | Video cards with previews — [VideoCard](https://ui.mieweb.org/?path=/docs/media-videocard--docs) |
+| [VideoSection](https://ui.mieweb.org/?path=/docs/content-videosection--docs) | One walkthrough or explainer embedded in place | Several videos to choose from — [VideoCard](https://ui.mieweb.org/?path=/docs/media-videocard--docs) |
+
+---
+
+<!-- source: src/catalog/Conversion.mdx (Templates) -->
+# Conversion
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [HeroSection](https://ui.mieweb.org/?path=/docs/conversion-herosection--docs) | The first screen of a public page: the `h1`, the pitch, two CTAs | A screen inside an app — [PageHeader](https://ui.mieweb.org/?path=/docs/layout-pageheader--docs) |
+| [CtaSection](https://ui.mieweb.org/?path=/docs/conversion-ctasection--docs) | The next step is another page (demo booking, pricing, contact) | Visitors should convert here — [LeadFormSection](https://ui.mieweb.org/?path=/docs/conversion-leadformsection--docs) |
+| [LeadFormSection](https://ui.mieweb.org/?path=/docs/conversion-leadformsection--docs) | Campaign, ABM and lead-magnet pages that capture the lead in place | App forms with steps, drafts or rich validation — the Inputs tier |
+| [PricingSection](https://ui.mieweb.org/?path=/docs/conversion-pricingsection--docs) | Two to four plans a buyer chooses between | A monthly/annual toggle — needs client state; render one section per period |
+
+---
+
+<!-- source: src/catalog/Dashboards.mdx (Modules) -->
+# Dashboards
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [DashboardWidget](https://ui.mieweb.org/?path=/docs/dashboards-dashboardwidget--docs) | A portlet tile: `title`, `icon`, `count`, `onAdd` / `headerAction`, `loading`, `accent`, `headingLevel`; body is `DashboardWidgetInfo`, `DashboardWidgetTable`, `DashboardWidgetActions` or `DashboardWidgetDataCards` | Free-form surface, media or selection — [Card](https://ui.mieweb.org/?path=/docs/layout-card--docs); a long sortable list — [Table](https://ui.mieweb.org/?path=/docs/grids-table--docs) / `DataVisNitroGrid` in a Card |
+| [CustomizableDashboard](https://ui.mieweb.org/?path=/docs/dashboards-customizabledashboard--docs) | Users drag portlets between 3 / 2 / 1 columns, hide widgets, and have it remembered (`storageKey` or controlled `order` / `layout` / `hiddenIds`); `toolbarSlot` portals the toolbar into a `PageHeader` | The layout is fixed — CSS grid of `DashboardWidget`; a flat single list — `useDragReorder`; widgets must resize or span columns |
+| [DashboardCustomizePanel](https://ui.mieweb.org/?path=/docs/dashboards-dashboardcustomizepanel--docs) | You render your own dashboard shell but want the same show/hide `Sheet` (`widgets`, `hiddenIds`, `onToggleWidget`, `onReset`) | You already pass `widgets` to `CustomizableDashboard` (it renders this itself); users must reorder or configure widgets in the panel |
+| [QuickLinksCard](https://ui.mieweb.org/?path=/docs/dashboards-quicklinkscard--docs) | A titled `Card` of ≤ ~8 shortcut rows with icon, `description`, `badge`; `layout="grid"` for icon tiles | Large explained tiles — [QuickAction](https://ui.mieweb.org/?path=/docs/actions-quickaction--docs); shortcuts inside a portlet — `DashboardWidgetActions`; real `<a href>` links for routing / crawlers |
+| [ReportDashboard](https://ui.mieweb.org/?path=/docs/dashboards-reportdashboard--docs) | The provider / employer analytics page exactly as shipped: KPI `metrics`, an "Order Volume" bar chart, `topServices` / `topEmployers`, date-range `Select`, Export | Users arrange widgets — `CustomizableDashboard`; real charts — [DataVisNitroGraph](https://ui.mieweb.org/?path=/docs/grids-datavis-nitro-graph--docs), [Sparkline](https://ui.mieweb.org/?path=/docs/grids-sparkline--docs); non-USD / non-English; different sections |
+| [Dashboard (Demo)](https://ui.mieweb.org/?path=/docs/dashboards-dashboard-demo--docs) | You want to see a whole signed-in shell (`Sidebar`, header, routed pages, forms, grids) composed from library parts | You need an importable component — it is not exported; a real top bar — [AppHeader](https://ui.mieweb.org/?path=/docs/layout-appheader--docs) |
+| [Dashboard Widgets (Demo)](https://ui.mieweb.org/?path=/docs/dashboards-dashboard-widgets-demo--docs) | You want a page-scale reference of `DashboardWidget` bodies (business stats + orders; patient summary under a `PatientHeader`) | You need an importable component — it is not exported; a spec for a widget prop — the `DashboardWidget` docs |
+
+---
+
+<!-- source: src/catalog/DataDisplay.mdx (Components) -->
+# Data display
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [Badge](https://ui.mieweb.org/?path=/docs/data-display-badge--docs) | A label for a state or category you map to a `variant` (`success`, `warning`, `danger`, …); optional `icon`; `onRemove` makes it a removable chip | It shows a count and opens something — `CountBadge`; the colour depends on a date — `FreshnessBadge`; it must toggle a pressed state — `Toggle` / `Button` |
+| [CountBadge](https://ui.mieweb.org/?path=/docs/data-display-countbadge--docs) | A clickable "Label N" pill for queues and shortcuts; `items` opens a popover table with per-row View / Edit / Delete | A label without a count — `Badge`; rows need real columns or sorting — a grid in your own `Modal`; a notification history — `NotificationCenter` |
+| [FreshnessBadge](https://ui.mieweb.org/?path=/docs/data-display-freshnessbadge--docs) | "Reviewed 12d ago" bucketed into fresh / aging / stale by `thresholds`; `FreshnessDot` for tight cells; `freshnessLevel` / `daysSince` for sorting | The state is a category, not an age — `Badge`; you need the full date or a future date — render the date with `Text` |
+| [Avatar](https://ui.mieweb.org/?path=/docs/data-display-avatar--docs) | A person's image with initials / glyph fallback; overlapping sets of people are [AvatarGroup](https://ui.mieweb.org/?path=/docs/record-details-avatargroup--docs) | It is not a person or needs a non-circle shape — `<img>`; it should open a menu — wrap in a `Dropdown` trigger; you need a status dot — compose a `Badge` |
+| [ClampedText](https://ui.mieweb.org/?path=/docs/data-display-clampedtext--docs) | Free-text notes/messages clamped to `lines` with a Show more toggle; short text stays inline | One line with an ellipsis — [Text](https://ui.mieweb.org/?path=/docs/foundations-text--docs) `truncate`; rich content — clamp your own container; the whole section should collapse — `Collapsible` |
+| [Timeline](https://ui.mieweb.org/?path=/docs/data-display-timeline--docs) | `TimelineProgress` for a process the user watches; `TimelineEventList` for a record's activity feed; `OrderConfirmation` for the fixed success overlay | The user drives the steps — [StepIndicator](https://ui.mieweb.org/?path=/docs/navigation-stepindicator--docs); a percentage — `Progress`; a custom dialog — `Modal` |
+| [FilterSummaryBar](https://ui.mieweb.org/?path=/docs/data-display-filtersummarybar--docs) | "1,204 of 8,911 records — 3 filters active · Clear all" above a host-filtered `DataVisNITRO` / `Table` | You need removable filter chips — `Badge` with `onRemove`; there are no filters — a plain count in `PageHeader`; the count is a shortcut — `CountBadge` |
+| [YChart](https://ui.mieweb.org/?path=/docs/data-display-ychart--docs) | Evaluating the `ychart` submodule's YAML org-chart editor inside Storybook | Anything in an application — it is **not exported**; an org chart in an app — [OrgChart](https://ui.mieweb.org/?path=/docs/records-orgchart--docs); charts — [DataVisNitroGraph](https://ui.mieweb.org/?path=/docs/grids-datavis-nitro-graph--docs) |
+| [CalendarHeatmap](https://ui.mieweb.org/?path=/docs/data-display-calendarheatmap--docs) | Daily activity over weeks or months as a contribution-style grid (engagement, logins, visits) | Exact values matter or there are few data points — `Table` or a chart; a schedule — `CalendarView` |
+
+BlueHive-specific badges live in their own families and are not alternatives here:
+[ServiceBadge](https://ui.mieweb.org/?path=/docs/services-servicebadge--docs) (service types) and
+[StripeBadge](https://ui.mieweb.org/?path=/docs/billing-stripebadge--docs) (payment provider).
+
+---
+
+<!-- source: src/catalog/DateTime.mdx (Inputs) -->
+# Date & time
+
+> **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).
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [DateInput](https://ui.mieweb.org/?path=/docs/date-time-dateinput--docs) | One date, time, month or year in a form (`inputType`); typed `MM/DD/YYYY` with auto-format, optional calendar (`showCalendar`), built-in `mode` / `minDate` / `maxDate` checks | A start/end pair or "Last 30 days" — `DateRangePicker`; the user must pick from open slots — `SchedulePicker` |
+| [DateRangePicker](https://ui.mieweb.org/?path=/docs/date-time-daterangepicker--docs) | Filtering a list or report by a period: presets plus a two-month custom range; `DateRangeFilter` when presets alone will do | A single validated date — `DateInput`; the range must be constrained or carry an error message (not supported) |
+| [SchedulePicker](https://ui.mieweb.org/?path=/docs/date-time-schedulepicker--docs) | Booking: the host supplies available `dates` and `times`, the user picks one of each (`DatePicker`, `TimePicker`, `RadioOption` building blocks) | Any date may be entered — `DateInput`; you need to _see_ existing appointments — `ScheduleCalendar` |
+| [ScheduleCalendar](https://ui.mieweb.org/?path=/docs/date-time-schedulecalendar--docs) | Staff view of appointments on an hourly day/week grid, colour-coded by `status`, with click-to-open and click-empty-hour-to-add (`onAddAppointment`) | The patient is choosing a slot — `SchedulePicker`; recurring opening hours — `BusinessHours`; you need month view, drag-reschedule or overlap layout |
+| [BusinessHours](https://ui.mieweb.org/?path=/docs/date-time-businesshours--docs) | Displaying weekly opening hours with an Open/Closed badge — full week, `CompactHours` one-liner, or `HoursSummary` expandable | The hours are being edited — `BusinessHoursEditor`; open/closed must be exact for a location in another time zone (computed from the viewer's clock) |
+| [BusinessHoursEditor](https://ui.mieweb.org/?path=/docs/date-time-businesshourseditor--docs) | Admin settings to define weekly hours, split shifts and notes; `variant="rules"` when several days share hours | Read-only display — `BusinessHours`; dated exceptions, holidays or time-zone selection (not modelled) |
+
+Free text, phones and URLs live in [Text inputs](https://ui.mieweb.org/?path=/docs/inputs-text-inputs-overview--docs);
+lists of options in [Choice inputs](https://ui.mieweb.org/?path=/docs/inputs-choice-inputs-overview--docs).
+
+---
+
+<!-- source: src/catalog/Editors.mdx (Modules) -->
+# Editors
+
+> **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).
+
+## 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` |
+| [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) |
+
+---
+
+<!-- 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
+> 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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [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 |
+| [PatientHeader](https://ui.mieweb.org/?path=/docs/encounter-orders-patientheader--docs) | The page **is the patient**: demographics, status dot, allergy / medication / alert / provider rows, flag ribbon, `CountBadge` actions, ⋮ menu with built-in Contact / Add / Edit Patient modals | The page is a case — `CaseManagementHeader`; a generic titled page — `PageHeader`; you need the full editable lists — `AllergyList` / `MedicationList` |
+| [CaseManagementHeader](https://ui.mieweb.org/?path=/docs/encounter-orders-casemanagementheader--docs) | The page **is a case**: `CaseContextBar` (case #, status, type, editing users, `collabStatus` slot) over the patient identity row, Add Case Note / Close Case, collapsible details grid with Days Open, `alert` slot, fully translatable `labels` | The page is the patient's chart — `PatientHeader`; a generic titled page — `PageHeader` |
+| [WebChartReportViewer](https://ui.mieweb.org/?path=/docs/encounter-orders-webchartreportviewer--docs) | Browsing **canned system reports** (grid of cards) and viewing one in a modal with a date range; result rendered by shape — HTML string, rows → `Table`, object → key/value | Interactive analysis of rows — DataVis NITRO; a single fixed dataset — `Table`; untrusted HTML results (rendered unsanitised) |
+
+---
+
+<!-- source: src/catalog/Feedback.mdx (Components) -->
+# Feedback
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [Alert](https://ui.mieweb.org/?path=/docs/feedback-alert--docs) | An inline, persistent message tied to nearby content | Confirming an action — `Toast` |
+| [Toast](https://ui.mieweb.org/?path=/docs/feedback-toast--docs) | A transient confirmation or heads-up, optionally with Undo | The text must be re-read or is essential |
+| [AlertDialog](https://ui.mieweb.org/?path=/docs/feedback-alertdialog--docs) | A yes/no decision the user cannot skip (delete, discard) | The dialog holds a form — `Modal` |
+| [NotificationCenter](https://ui.mieweb.org/?path=/docs/feedback-notificationcenter--docs) | A readable history with read state (bell menu, inbox) | The message is about the current action |
+| [ConnectionStatus](https://ui.mieweb.org/?path=/docs/feedback-connectionstatus--docs) | The app cannot work until the connection returns or an update is applied | Loss of connection is tolerable |
+| [CollabStatus](https://ui.mieweb.org/?path=/docs/feedback-collabstatus--docs) | Presence and sync state of a collaborative document, in a header chip | There is no shared document |
+| [ErrorPage](https://ui.mieweb.org/?path=/docs/feedback-errorpage--docs) | A route cannot render at all (404, 500, offline, maintenance) | Part of the page failed — `Alert` |
+
+Loading states are their own family: [Loading](https://ui.mieweb.org/?path=/docs/components-loading-overview--docs).
+
+---
+
+<!-- source: src/catalog/Files.mdx (Modules) -->
+# Files
+
+> **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`.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [DropzoneOverlay](https://ui.mieweb.org/?path=/docs/files-dropzoneoverlay--docs) | An existing panel should accept drops; `useDropzone` gives `isDragging`, `getRootProps`, `getInputProps`, `open()` and you render the list/progress yourself | You need a visible upload area and a file table — `FileManager`; files need validation, preview or camera — `DocumentScanner` |
+| [FileManager](https://ui.mieweb.org/?path=/docs/files-filemanager--docs) | A record's attachment list: drop/click card, `Progress` while `isUploading`, storage used/limit, table with Preview / Download / Delete via `onPreview` etc. | Only a drag target — `DropzoneOverlay`; scanned documents with extraction — `DocumentScanner`; sortable/multi-column lists — `Table` |
+| [DocumentScanner](https://ui.mieweb.org/?path=/docs/files-documentscanner--docs) | Intake of an ID/card/form: MIME + size validation, `FilePreview`, mobile camera or desktop `WebcamModal` with auto-capture, `onScan` → `onResult` | Plain attachments with no server extraction step — `FileManager` / `DropzoneOverlay`; multi-page capture, cropping or client-side OCR |
+
+---
+
+<!-- source: src/catalog/Grids.mdx (Components) -->
+# Grids
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when | Entry |
+| --- | --- | --- | --- |
+| [DataVis NITRO](https://ui.mieweb.org/?path=/docs/grids-datavis-nitro--docs) | Users browse, sort, filter, group or export records — any list that may grow | The data is a handful of static rows | `@mieweb/ui/datavis` |
+| [DataVis NITRO Graph](https://ui.mieweb.org/?path=/docs/grids-datavis-nitro-graph--docs) | The same records as an interactive chart; users may change axes or chart type | You need a tiny inline trend | `@mieweb/ui/datavis` |
+| [Table](https://ui.mieweb.org/?path=/docs/grids-table--docs) | A few known rows shown for reading (line items, a summary block) | Anything interactive beyond a link or a row action | `@mieweb/ui` |
+| [Pagination](https://ui.mieweb.org/?path=/docs/grids-pagination--docs) | A server-paged `Table` or card list needs page controls | The rows are already in a NITRO grid | `@mieweb/ui` |
+| [Sparkline](https://ui.mieweb.org/?path=/docs/grids-sparkline--docs) | A glanceable, dependency-free trend strip over pre-bucketed points | Exact values or axes must be read | `@mieweb/ui` |
+| [AGGrid](https://ui.mieweb.org/?path=/docs/deprecated-aggrid--docs) _(deprecated)_ | Never for new work | — | `@mieweb/ui/ag-grid` |
+
+---
+
+<!-- source: src/catalog/Layout.mdx (Components) -->
+# Layout
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [Card](https://ui.mieweb.org/?path=/docs/layout-card--docs) | A bordered surface you lay out yourself with `CardHeader` / `CardContent` / `CardFooter` / `CardActions`, `CardMedia`, `CardStat`; `interactive` + `selected` tiles | A titled portlet with count and "+" — [DashboardWidget](https://ui.mieweb.org/?path=/docs/dashboards-dashboardwidget--docs); a titled list of shortcuts — [QuickLinksCard](https://ui.mieweb.org/?path=/docs/dashboards-quicklinkscard--docs) |
+| [Accordion](https://ui.mieweb.org/?path=/docs/layout-accordion--docs) | 3+ labelled sections in one stack from an `items` array; `type="single"` / `"multiple"`; `headingLevel`; animated, styled, `aria-hidden` + `inert` when closed | One toggle or custom trigger/panel styling — `Collapsible`; peer views the user switches between — [Tabs](https://ui.mieweb.org/?path=/docs/navigation-tabs--docs) |
+| [Collapsible](https://ui.mieweb.org/?path=/docs/layout-collapsible--docs) | One headless `CollapsibleTrigger` + `CollapsibleContent`; content unmounts when closed (or `forceMount`); you bring every class | A styled stack with single/multiple rules — `Accordion`; a "Show more" tail inside a Card — `CardCollapsible` |
+| [ScrollArea](https://ui.mieweb.org/?path=/docs/layout-scrollarea--docs) | A nested region with a fixed height/width that should scroll with thin themed scrollbars; `orientation` vertical / horizontal / both | The document should scroll; you need virtualisation, scroll shadows or custom thumbs |
+| [Separator](https://ui.mieweb.org/?path=/docs/layout-separator--docs) | A 1px rule between blocks or inline items; `decorative={false}` for a semantic `role="separator"` | Inside a Card edge-to-edge — `CardDivider`; in a header rail — `AppHeaderDivider`; between menu items — `DropdownSeparator` |
+| [AppHeader](https://ui.mieweb.org/?path=/docs/layout-appheader--docs) | The sticky top bar of the **signed-in app** beside a `Sidebar`: `AppHeaderBrand`, `AppHeaderTitle`, `AppHeaderSearch` (⌘K trigger), `AppHeaderIconButton`, `AppHeaderUserMenu` | A public page with nav links and Log In / Sign Up — `SiteHeader`; the title block inside the page — `PageHeader`; you need the dropdowns themselves — wrap the triggers in `Dropdown` / `NotificationCenter` |
+| [SiteHeader](https://ui.mieweb.org/?path=/docs/layout-siteheader--docs) | The **fixed, brand-coloured public-site bar**: logo, `links`, `AuthButtons` ↔ `UserMenu` on `user`, built-in mobile menu; `CompactHeader` for back-button sub-pages | The app shell with search and account triggers — `AppHeader`; router links or active-route styling — [Sidebar](https://ui.mieweb.org/?path=/docs/overlays-sidebar--docs) |
+| [PageHeader](https://ui.mieweb.org/?path=/docs/layout-pageheader--docs) | The **`<h1>` title block inside a page**: `title`, `subtitle`, `icon`, `actions`, and `children` for a `Breadcrumb` or `TabsList` | The app-wide bar — `AppHeader`; a record banner — [PatientHeader](https://ui.mieweb.org/?path=/docs/encounter-orders-patientheader--docs), [CaseManagementHeader](https://ui.mieweb.org/?path=/docs/encounter-orders-casemanagementheader--docs), [ProviderDetailHeader](https://ui.mieweb.org/?path=/docs/providers-providerdetailheader--docs); a tile title — `CardTitle` |
+| [SiteFooter](https://ui.mieweb.org/?path=/docs/layout-sitefooter--docs) | The public `<footer>`: brand, `linkGroups`, social icons, newsletter, `LegalLinks`, disclaimers; `SimpleFooter` for a one-line © strip | Only a version line — `ProductVersion`; router links — every link is a plain `<a>` |
+| [ProductVersion](https://ui.mieweb.org/?path=/docs/layout-productversion--docs) | "Name vX.Y.Z (build) · © year author" for footers and About pages, optionally linking to a changelog; `ProductVersionBadge` for a tiny env chip | A generic status label — [Badge](https://ui.mieweb.org/?path=/docs/data-display-badge--docs); the whole footer — `SiteFooter` |
+
+---
+
+<!-- source: src/catalog/Loading.mdx (Components) -->
+# Loading
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [Spinner](https://ui.mieweb.org/?path=/docs/loading-spinner--docs) | A short wait whose result has no predictable layout (submit, search) | The layout is known — `Skeleton` |
+| [Skeleton](https://ui.mieweb.org/?path=/docs/loading-skeleton--docs) | The loaded view's shape is known and layout shift must be avoided | The wait is a fraction of a second |
+| [Progress](https://ui.mieweb.org/?path=/docs/loading-progress--docs) | You can report a real percentage (upload, import, quota) | Progress cannot be measured |
+| [LoadingPage](https://ui.mieweb.org/?path=/docs/loading-loadingpage--docs) | A whole route or panel has nothing to show yet; `LoadingOverlay` to block a region | Only one region is pending |
+
+Related, in other families: `Button isLoading` (inline spinner), `ReadingProgressBar`
+(scroll position, Navigation), `StepIndicator` (steps, Navigation), `ErrorPage` (Feedback).
+
+---
+
+<!-- source: src/catalog/Media.mdx (Modules) -->
+# Media
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [AudioPlayer](https://ui.mieweb.org/?path=/docs/media-audioplayer--docs) | A small, themed player for one audio clip: `inline` / `compact` / `waveform` variants, `AudioPlayerRef` in **seconds**, `preload={false}` for lists | The source may be video or you want native controls and captions — `MediaPlayer`; you are capturing — `AudioRecorder` / `RecordButton` |
+| [MediaPlayer](https://ui.mieweb.org/?path=/docs/media-mediaplayer--docs) | Native `<audio>`/`<video>` with `controls`, `kind` inferred from the extension, `MediaPlayerRef` in **milliseconds** to sync a transcript | You want a compact styled audio control or a waveform — `AudioPlayer`; the words are edited — `MediaEditor` |
+| [MediaFeed](https://ui.mieweb.org/?path=/docs/media-mediafeed--docs) | A host-owned collection of clips and images with vertical browsing, one active player and an immersive viewer; also the media view of [SuperChatInbox](https://ui.mieweb.org/?path=/docs/superchat-inbox--docs) | A single clip — `MediaPlayer`; a linked video thumbnail — `VideoCard`; text discussion — the normal SuperChat thread |
+| [TranscriptView](https://ui.mieweb.org/?path=/docs/media-transcriptview--docs) | Read-only word- or segment-level transcript that highlights `currentTimeMs` and reports `onSeek(ms)`; speaker rows via `speakerLabels` / `mergeSameSpeaker` | The user changes words or the cut — `MediaEditor`; you have no media position to follow |
+| [MediaEditor](https://ui.mieweb.org/?path=/docs/media-mediaeditor--docs) | Word-timestamped `Transcript` the user tightens: delete/cut/paste words, split silences, filler removal, speed markers; state persisted via `onEditorStateChange` | Read-only playback — `TranscriptView` + `MediaPlayer`; segment-only timestamps (no per-word times) |
+| [MediaEditor Live Demo](https://ui.mieweb.org/?path=/docs/media-mediaeditor-live-demo--docs) | Trying `MediaEditor` on your own file: on-device Whisper transcription, then the editor with the Script panel | Anything you ship — use `MediaEditor` with your own transcription source |
+| [AudioRecorder](https://ui.mieweb.org/?path=/docs/media-audiorecorder--docs) | A deliberate take with pause/resume, `maxDuration`, waveform playback and delete before the host receives the `Blob` (`onRecordingComplete`) | A single mic icon in a composer — `RecordButton`; you cannot ship `wavesurfer.js`; a speaker-labelled visit transcript — [VisitScribe](https://ui.mieweb.org/?path=/docs/voice-visit-scribe--docs) |
+| [RecordButton](https://ui.mieweb.org/?path=/docs/media-recordbutton--docs) | One round button for talk-to-text / voice messages: six visual states, `transcriptionState` overlay, controlled `state` when you own the recorder | The user should review the take first — `AudioRecorder`; you want a real waveform (its bars are a CSS animation) |
+| [DictationButton](https://ui.mieweb.org/?path=/docs/media-dictationbutton--docs) | Voice typing: records one speaker, transcribes (on-device Whisper by default, or a host `transcribe`) and returns **editable text** via `onText` — never sends | The host needs the audio `Blob` — `RecordButton`; several speakers — [VisitScribe](https://ui.mieweb.org/?path=/docs/voice-visit-scribe--docs) |
+
+---
+
+<!-- source: src/catalog/Navigation.mdx (Components) -->
+# Navigation
+
+> **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).
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [Tabs](https://ui.mieweb.org/?path=/docs/navigation-tabs--docs) | 2–7 sibling views of one record/page; selection is local state (`value` / `defaultValue`); `tablist` / `tab` / `tabpanel` semantics | App navigation between routes — [Sidebar](https://ui.mieweb.org/?path=/docs/overlays-sidebar--docs); a compact toolbar filter — `PillSelect`; readable stacked sections — `Accordion`; ordered steps — `StepIndicator` |
+| [Breadcrumb](https://ui.mieweb.org/?path=/docs/navigation-breadcrumb--docs) | The page is ≥ 2 levels deep in a tree the user climbs back up; `maxItems` bounds long paths; `renderLink` for your router | Peer views — `Tabs`; primary navigation — `Sidebar` / `AppHeader`; one level deep — a Back `Button` |
+| [TableOfContents](https://ui.mieweb.org/?path=/docs/navigation-tableofcontents--docs) | A two-column long page with a sticky **nested** outline; auto-discovers `h2, h3` with ids inside `contentRef`, or takes `items` | Single-column with a few flat sections — `SectionSpyNav`; progress only — `ReadingProgressBar`; items are pages — `Sidebar` |
+| [SectionSpyNav](https://ui.mieweb.org/?path=/docs/navigation-sectionspynav--docs) | A sticky horizontal band under the header for 3–8 **flat** sections, optional tiered `cta` | Nested headings with a sidebar — `TableOfContents`; content scrolls in a container (viewport-only spy); links leave the page — `AppHeader` |
+| [ReadingProgressBar](https://ui.mieweb.org/?path=/docs/navigation-readingprogressbar--docs) | A decorative top-of-viewport bar for how far the reader has scrolled the document | A value the host owns (upload, task) — [Progress](https://ui.mieweb.org/?path=/docs/loading-progress--docs); the reader needs to jump — add a TOC or `SectionSpyNav`; content scrolls in a container |
+| [StepIndicator](https://ui.mieweb.org/?path=/docs/navigation-stepindicator--docs) | The numbered rail of a wizard **you** build; `currentStep` + `onStepClick`, `orientation`, `hasError` / `optional` per step | You want the whole flow — `OnboardingWizard`; the user only watches — [TimelineProgress](https://ui.mieweb.org/?path=/docs/data-display-timeline--docs); a percentage — `Progress` |
+| [OnboardingWizard](https://ui.mieweb.org/?path=/docs/navigation-onboardingwizard--docs) | A full-screen setup takeover with header, Back / Next / Skip / Finish, `Progress`, `loading` and `error` states; controlled by `currentStep` | Steps live inside a page — `StepIndicator`; a dialog — `Modal` + `StepIndicator`; not BlueHive — override the branding and `OnboardingCompletion` copy |
+| [CommandPalette](https://ui.mieweb.org/?path=/docs/navigation-commandpalette--docs) | ⌘K / Ctrl+K search-and-run across the app; features register items through `useCommandPalette` | Actions for one element — `Dropdown`; a form value — `Autocomplete`; showing shortcuts — `KeyboardShortcutsOverlay` |
+
+---
+
+<!-- source: src/catalog/Overlays.mdx (Components) -->
+# Overlays
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when | Modal? |
+| --- | --- | --- | --- |
+| [Modal](https://ui.mieweb.org/?path=/docs/overlays-modal--docs) | A focused task interrupts the page: edit, pick, view details | A yes/no decision — `AlertDialog` | yes |
+| [Sheet](https://ui.mieweb.org/?path=/docs/overlays-sheet--docs) | Secondary detail or filters slide in from an edge; mobile menus | The task should fully take over | yes |
+| [DockablePanel](https://ui.mieweb.org/?path=/docs/overlays-dockablepanel--docs) | A long form/editor the user parks as a strip and resumes, dirty-guarded | A quick task | full only |
+| [FloatingWindow](https://ui.mieweb.org/?path=/docs/overlays-floatingwindow--docs) | A draggable, resizable tool window kept open while reading the page | Touch / small screens | no |
+| [Sidebar](https://ui.mieweb.org/?path=/docs/overlays-sidebar--docs) | Persistent app navigation; becomes a drawer on small screens | Transient panels — `Sheet` | drawer only |
+| [Tooltip](https://ui.mieweb.org/?path=/docs/overlays-tooltip--docs) | A few words describing a control on hover/focus | Links or structure inside | no |
+| [GlossaryTooltip](https://ui.mieweb.org/?path=/docs/overlays-glossarytooltip--docs) | A pinnable definition card for domain terms in prose | Citing where a value comes from | no |
+| [SourceTip](https://ui.mieweb.org/?path=/docs/overlays-sourcetip--docs) | A pinnable provenance card: what backs this number/claim | Defining a term | no |
+| [KeyboardShortcutsOverlay](https://ui.mieweb.org/?path=/docs/overlays-keyboardshortcutsoverlay--docs) | The `?` help dialog listing shortcuts (`Kbd` chips) | Running commands — `CommandPalette` | yes |
+| [CookieConsent](https://ui.mieweb.org/?path=/docs/overlays-cookieconsent--docs) | A fixed consent banner with accept/decline and policy links | Any other message — `Alert` / `Toast` | no |
+
+`AlertDialog` lives in [Feedback](https://ui.mieweb.org/?path=/docs/components-feedback-overview--docs) but is built on
+`Modal`.
+
+---
+
+<!-- source: src/catalog/Pages.mdx (Templates) -->
+# Pages
+
+> **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`.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [LandingPage](https://ui.mieweb.org/?path=/docs/pages-landingpage--docs) | A page is a stack of standard sections and you want to describe it as data | The page is mostly bespoke layout — compose the sections, or build one with `SectionShell` |
+
+---
+
+<!-- source: src/catalog/Presentations.mdx (Modules) -->
+# Presentations
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [Deck](https://ui.mieweb.org/?path=/docs/presentations-deck--docs) | A full-screen slide deck from JSON slides (`@mieweb/ui/deck`) | A report people scan and search — the [Reports](https://ui.mieweb.org/?path=/docs/templates-reports-overview--docs) sections |
+| [PointMap](https://ui.mieweb.org/?path=/docs/presentations-pointmap--docs) | Points or regional bubbles on a real map (`@mieweb/ui/maps`) | Comparing every state equally — TileCartogramSection |
+
+---
+
+<!-- source: src/catalog/RecordDetails.mdx (Components) -->
+# Record details
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [RecordHeader](https://ui.mieweb.org/?path=/docs/record-details-recordheader--docs) | The top of a record page: avatar or logo, name, status badges, meta, actions | A page that isn't about one record — `PageHeader`; a patient — `PatientHeader` |
+| [PropertyList](https://ui.mieweb.org/?path=/docs/record-details-propertylist--docs) | Label/value fields, optionally editable in place, copyable or grouped | Rows the user sorts or filters — DataVis NITRO; a form submitted at once — form inputs |
+| [AvatarGroup](https://ui.mieweb.org/?path=/docs/record-details-avatargroup--docs) | Several people at once — owners, participants, who is viewing or editing | One person — `Avatar` |
+| [PhiMask](https://ui.mieweb.org/?path=/docs/record-details-phimask--docs) | A sensitive value (SSN, DOB, member ID) that stays hidden until revealed | Access control — masking is display only; the server must not send what the user may not see |
+| [CompletenessMeter](https://ui.mieweb.org/?path=/docs/record-details-completenessmeter--docs) | Showing how much of a record is filled in and what's missing | Task progress over time — `Progress` / `ActionPlan` |
+| [Rating](https://ui.mieweb.org/?path=/docs/record-details-rating--docs) | A star score, read-only or as an input | A numeric metric — `Badge` or a stat |
+| [ReviewCard](https://ui.mieweb.org/?path=/docs/record-details-reviewcard--docs) | One review with author, date, rating, body and an optional reply | A feed of mixed events — `ActivityFeed` |
+
+---
+
+<!-- source: src/catalog/Records.mdx (Modules) -->
+# Records
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [RecordLayout](https://ui.mieweb.org/?path=/docs/records-recordlayout--docs) | A record page: header, fields sidebar, tabbed main column, optional aside | A dashboard the user rearranges — `CustomizableDashboard` |
+| [ActivityFeed](https://ui.mieweb.org/?path=/docs/records-activityfeed--docs) | Mixed events (calls, notes, emails, meetings) grouped by day, with filters and pins | Steps in a fixed process — `Timeline`; field-level changes — `FieldHistory` |
+| [FieldHistory](https://ui.mieweb.org/?path=/docs/records-fieldhistory--docs) | Who changed which field, from what to what, and when | Business events — `ActivityFeed` |
+| [AssociationList](https://ui.mieweb.org/?path=/docs/records-associationlist--docs) | Related records (contacts at a company, deals for a contact) with add/remove | Many rows the user sorts or filters — DataVis NITRO |
+| [ActionPlan](https://ui.mieweb.org/?path=/docs/records-actionplan--docs) | A shared checklist with owners, due dates and overdue flags | A project board — `BoardView`; a dated schedule — `GanttView` |
+| [OrgChart](https://ui.mieweb.org/?path=/docs/records-orgchart--docs) | Reporting lines or a location hierarchy, with search, filter and a list view | A flat list of people — `AssociationList` |
+
+---
+
+<!-- source: src/catalog/Reports.mdx (Templates) -->
+# Reports
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [MetricStatusBadge](https://ui.mieweb.org/?path=/docs/reports-metricstatusbadge--docs) | Tagging a figure or section live / modeled / maturing | The label is a workflow state — [Badge](https://ui.mieweb.org/?path=/docs/data-display-badge--docs) |
+| [ReportLegend](https://ui.mieweb.org/?path=/docs/reports-reportlegend--docs) | Explaining those tags near the top of the report | Every figure has one source — say so in the methodology |
+| [BenchmarkTableSection](https://ui.mieweb.org/?path=/docs/reports-benchmarktablesection--docs) | Several measures across many items | Readers must sort or filter — DataVis NITRO |
+| [RankedListSection](https://ui.mieweb.org/?path=/docs/reports-rankedlistsection--docs) | A ranking where order matters more than exact values | Each item has several measures — BenchmarkTableSection |
+| [TileCartogramSection](https://ui.mieweb.org/?path=/docs/reports-tilecartogramsection--docs) | A figure by state where small states matter | Real location matters — [PointMap](https://ui.mieweb.org/?path=/docs/presentations-pointmap--docs) |
+| [MetricListSection](https://ui.mieweb.org/?path=/docs/reports-metriclistsection--docs) | Metrics you define now and measure later | All values are known — StatsSection `cards` |
+| [ReportMethodology](https://ui.mieweb.org/?path=/docs/reports-reportmethodology--docs) | Sources, how to cite, cadence and data downloads | Per-sentence citations — the site's footnote system |
+| [ReportByline](https://ui.mieweb.org/?path=/docs/reports-reportbyline--docs) | Authors and publish/update dates | A blog post with its own byline |
+| [LinkGroupsSection](https://ui.mieweb.org/?path=/docs/reports-linkgroupssection--docs) | Linking out to the pages behind the numbers | Each link needs an image — ResourceCardsSection |
+| [PdfEmbedSection](https://ui.mieweb.org/?path=/docs/reports-pdfembedsection--docs) | An inline PDF edition with download | The PDF is gated — LeadFormSection with `highlights` |
+
+The rest of a report comes from the other families: `HeroSection` with `meta` for the dateline,
+`StatsSection variant="ruled"` on the brand tone for key findings, `FeatureGridSection` for the
+executive summary (numbers as lettermark icons) and outlook, and `LeadFormSection` with
+`highlights` as the gate for a downloadable edition.
+
+---
+
+<!-- source: src/catalog/Showcase.mdx (Components) -->
+# Showcase
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [Globe](https://ui.mieweb.org/?path=/docs/showcase-globe--docs) | A hero shows a **global footprint** — offices, customers, deployments — with hub arcs | Values must be read or compared — chart it with the DataVis components |
+| [OrbitRing](https://ui.mieweb.org/?path=/docs/showcase-orbitring--docs) | Partner/integration logos should **orbit** your product mark as a living ecosystem | The items carry data or must be browsed — a logo wall or `Card` grid |
+| [RadialExplorer](https://ui.mieweb.org/?path=/docs/showcase-radialexplorer--docs) | Visitors **preview each module** in place: tiles around a core, media + CTA per pick | Users navigate to the sections rather than preview them — `MegaMenu` or links |
+
+---
+
+<!-- source: src/catalog/SocialProof.mdx (Templates) -->
+# Social proof
+
+> **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.
+
+## Which one?
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [StatsSection](https://ui.mieweb.org/?path=/docs/social-proof-statssection--docs) | Two to four headline figures back the pitch | Figures must count up on scroll — render `AnimatedNumber` from a client component |
+| [LogoCloudSection](https://ui.mieweb.org/?path=/docs/social-proof-logocloudsection--docs) | A quick "trusted by" or "connects to" strip | Logos orbiting your mark as a hero visual — [OrbitRing](https://ui.mieweb.org/?path=/docs/showcase-orbitring--docs) |
+| [TestimonialSection](https://ui.mieweb.org/?path=/docs/social-proof-testimonialsection--docs) | Quotes from customers in the buyer's position | A rotating carousel — keep that client-side in the app |
+
+---
+
+<!-- source: src/catalog/TextInputs.mdx (Inputs) -->
+# Text 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.
+
+## Which one?
+
+| 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` |
+| [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 |
+| [WebsiteInput](https://ui.mieweb.org/?path=/docs/text-inputs-websiteinput--docs) | A website or social link, syntax-checked on blur (`WebsiteInputGroup` for a typed list) | Anything that is not a URL |
+| [Address](https://ui.mieweb.org/?path=/docs/text-inputs-address--docs) | Showing a stored address (`block` / `inline` / `compact`, maps link) | Editing it — `AddressForm` |
+| [AddressForm](https://ui.mieweb.org/?path=/docs/text-inputs-addressform--docs) | Collecting a full US address, optionally filled by Google Places | One field, non-US layouts, a state picker |
+| [InlineEdit](https://ui.mieweb.org/?path=/docs/text-inputs-inlineedit--docs) | Editing one saved value in place on a record page (click, edit, Enter to save) | A form the user submits as a whole — `Input` in a form |
+| [TagEditor](https://ui.mieweb.org/?path=/docs/text-inputs-tageditor--docs) | Free-form tags the user types, with optional suggestions | A fixed set of choices — `PillSelect` |
+
+Dates go to [DateInput](https://ui.mieweb.org/?path=/docs/date-time-dateinput--docs); fixed option sets to
+[Select](https://ui.mieweb.org/?path=/docs/choice-inputs-select--docs) or
+[Autocomplete](https://ui.mieweb.org/?path=/docs/choice-inputs-autocomplete--docs).
+
+---
+
+<!-- source: src/catalog/Views.mdx (Modules) -->
+# Views
+
+> **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.
+
+## Which one?
+
+Members land incrementally. [ViewSwitcher](https://ui.mieweb.org/?path=/docs/views-viewswitcher--docs),
+[ListView](https://ui.mieweb.org/?path=/docs/views-listview--docs), [BoardView](https://ui.mieweb.org/?path=/docs/views-boardview--docs),
+[CalendarView](https://ui.mieweb.org/?path=/docs/views-calendarview--docs),
+[GanttView](https://ui.mieweb.org/?path=/docs/views-ganttview--docs) and
+[ViewSet](https://ui.mieweb.org/?path=/docs/views-viewset--docs) have all shipped.
+
+Most pages want `ViewSet` and nothing else from this table: it renders the switcher and the
+views, and leaves you the slots. Reach for an individual view when a page draws exactly one
+layout forever.
+
+| Component | Use it when | Not when |
+| --- | --- | --- |
+| [ViewSwitcher](https://ui.mieweb.org/?path=/docs/views-viewswitcher--docs) | Users pick between the layouts below; persisted per user or driven by a URL param | Two unrelated pages, not two views of one collection — [Tabs](https://ui.mieweb.org/?path=/docs/navigation-tabs--docs) |
+| [ListView](https://ui.mieweb.org/?path=/docs/views-listview--docs) | A scannable vertical list, optionally grouped by status or group, with a row slot you own | Rows need sorting, filtering, paging or export — [DataVis NITRO](https://ui.mieweb.org/?path=/docs/grids-datavis-nitro--docs) |
+| [BoardView](https://ui.mieweb.org/?path=/docs/views-boardview--docs) | Items move between named stages and the stage is the primary fact | Stages are fixed and items never move — [ListView](https://ui.mieweb.org/?path=/docs/views-listview--docs) grouped by status |
+| [CalendarView](https://ui.mieweb.org/?path=/docs/views-calendarview--docs) | Items land on, or span, calendar days and the month grid is the point | Timed appointments in day/week slots — [ScheduleCalendar](https://ui.mieweb.org/?path=/docs/date-time-schedulecalendar--docs) |
+| [GanttView](https://ui.mieweb.org/?path=/docs/views-ganttview--docs) | Items have a start and an end and overlap matters across a date range — including as a roadmap | One record's progress through steps — [Timeline](https://ui.mieweb.org/?path=/docs/data-display-timeline--docs) |
+| [ViewSet](https://ui.mieweb.org/?path=/docs/views-viewset--docs) | A whole page: switcher, the enabled views, and shared filter / overview / detail / toolbar slots | You render exactly one layout forever — use that view directly |
+
+**A roadmap is not its own component.** It is
+[GanttView](https://ui.mieweb.org/?path=/docs/views-ganttview--docs) at `cadence="month"` or `"quarter"` with
+`groupByLane`. A `RoadmapView` was planned and dropped: it would have been the same chart
+with wider columns, and two near-identical timeline components is exactly the duplication
+this family exists to remove. The `roadmap` view id remains, so a switcher can still offer
+"Roadmap" as a labelled option. For an editorial, hand-authored calendar year — a
+compliance calendar on a marketing page — reach for
+[YearTimeline](https://ui.mieweb.org/?path=/docs/data-display-yeartimeline--docs) instead: it is
+authored a year at a time rather than driven from records through accessors.
+
+**Tables are not a view here.** A tabular layout of the same collection is
+`DataVisNitroGrid` (see [Grids](https://ui.mieweb.org/?path=/docs/components-grids-overview--docs)); `ViewSet`
+renders it in the `table` slot rather than wrapping it. Tables and data grids start with
+DataVis NITRO.
+
+**Overview is not a view either.** It is domain content — KPI tiles, charts, next actions —
+so `ViewSet` exposes an `overview` slot that a page fills with
+[CustomizableDashboard](https://ui.mieweb.org/?path=/docs/dashboards-customizabledashboard--docs) and
+[DashboardWidget](https://ui.mieweb.org/?path=/docs/dashboards-dashboardwidget--docs).