themelia-react-ui 2.0.5 → 3.0.0

package/docs/consumer-skill/references/catalogue.md

@@ -0,0 +1,617 @@
+# Catalogue
+
+Everything themelia-react-ui 3.0.0 publishes, in the order to reach for it.
+Generated by `npm run docs:sync-skill` from the package exports and component
+guidance; do not edit. Read the layers you need, then inspect what you chose:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs <Symbol> --import <exact import>
+```
+
+[Building views](building-views.md) explains the reach order and the custom part.
+
+## Features
+
+Complete workflows with their own state, loading, empty and error handling.
+
+### `themelia-react-ui/features/activities`
+
+- **Activity and timeline**: Present mixed operational activity beside a read-only milestone rail.
+- **Activity log** (`ActivityLog`): Mixed comments, audit/domain/system events, adapters, metadata, details, and row actions share one log.
+
+### `themelia-react-ui/features/ai-chat`
+
+- **AI chat** (`AiChat`, `AiChatConversation`, `AiChatMessage`, `AiChatPromptInput`, `AiChatEmptyState`, `AiChatQueue`, `AiChatSuggestionsRow`, `AiChatAttachmentsStrip`): Callback-driven AI conversation shell with streaming, queue, attachment, suggestion, empty, and headless composition seams.
+
+### `themelia-react-ui/features/appointment-calendar`
+
+- **Appointment calendar** (`AppointmentCalendar`): Bookings need a month beside a day or week agenda with category and staff filters and double-booking alerts.
+
+### `themelia-react-ui/features/async-preview`
+
+- **Async preview** (`AsyncPreviewRoot`, `AsyncPreviewTrigger`, `AsyncPreviewContent`, `AsyncPreviewState`, `AsyncPreviewBody`, `AsyncPreviewLoading`, `AsyncPreviewError`, `AsyncPreviewEmpty`): A lazy or preloaded hover preview is needed inline or from a table cell trigger.
+
+### `themelia-react-ui/features/combobox`
+
+- **Async selection**: Load remote options with package-owned query, retry, abort, stale-response, and portal behavior.
+- **Combobox** (`Combobox`, `MultiCombobox`, `AsyncResourceCombobox`): A field needs searchable single/multiple selection, async resource lookup, or headless combobox composition.
+- **Async resource combobox** (`AsyncResourceCombobox`): Callback-driven resource search with debouncing, loading states, rich option metadata, and no data-fetching framework dependency.
+
+### `themelia-react-ui/features/comments`
+
+- **Comments** (`Comments`): Generic, framework-agnostic comments with rich-text composer (TipTap-backed), inline resource references (mentions, links, badges), attachment uploads with progress, and reactions. Every callback / registry flows as a direct prop — no provider.
+
+### `themelia-react-ui/features/data-view`
+
+- **Operational index**: Coordinate filters, saved views, table behavior, selection, and pagination around app-owned records.
+- **Data view** (`DataView`, `DataViewShell`, `DataViewToolbar`, `DataViewTableFrame`, `DataViewPagination`, `SavedViewTabs`): A standard filtered customer, booking, product, or resource index coordinates rows, columns, saved views, and named toolbar/footer slots.
+
+### `themelia-react-ui/features/email-composer`
+
+- **Email composer** (`EmailComposer`): Named recipients, structured rich documents, atomic variables, reusable templates and prepared email delivery using our public components.
+
+### `themelia-react-ui/features/email-composer/engine`
+
+- Pure email rendering, validation, variable resolution and optional HTTP delivery for server or client code. No React/editor runtime or client boundary; rich document declarations reference Tiptap types. The application owns delivery and server policy.
+
+### `themelia-react-ui/features/event-calendar`
+
+- **Event calendar** (`EventCalendar`): Events need month/week/agenda browsing, categories, day rendering, and callback-driven actions.
+- **Event card** (`EventCalendarEventCard`): A detailed event summary for agenda lists and popovers, with optional callback-driven interaction.
+- **Event calendar header** (`EventCalendarHeader`): Reusable calendar navigation, month/year selection, view switching, and consumer-owned actions.
+- **Event calendar legend** (`EventCalendarLegend`): Static or interactive category chips with canonical calendar color tokens.
+
+### `themelia-react-ui/features/filters`
+
+- **Filters** (`FilterProvider`, `FilterLayout`): Controlled facets, operators, active-filter chrome, validation, or query serialization are the primary job.
+
+### `themelia-react-ui/features/global-search`
+
+- **Global search** (`GlobalSearch`): Async search palette with slots, render-props, and a headless useGlobalSearch hook.
+
+### `themelia-react-ui/features/kanban`
+
+- **Kanban** (`Kanban`, `KanbanBoard`, `KanbanColumn`, `KanbanColumnContent`, `KanbanItem`, `KanbanItemActions`, `KanbanOverlay`): Drag-and-drop board, generic in T. Pass `itemActions` (static array or per-item factory) for the ⋯ menu, `onItemClick` for whole-card click. Headless via `useKanban`; slots: KanbanBoard / KanbanColumn / KanbanColumnContent / KanbanItem / KanbanItemHandle / KanbanItemActions / KanbanOverlay.
+
+### `themelia-react-ui/features/map`
+
+- **Map** (`Map`, `MapMarker`, `MapZoomControl`, `MapFullscreenControl`, `MapLocateControl`, `MapLayersControl`): A Leaflet map needs package controls, layers, markers, drawing, localization, or place search.
+- **Place autocomplete** (`PlaceAutocomplete`): Debounced Photon place search with controlled input, location bias, result callbacks, and overridable strings.
+
+### `themelia-react-ui/features/media-library`
+
+- **Media workflow**: Compose browsing, selection, upload entry, and deterministic asset actions.
+- **Media library** (`MediaLibrary`, `MediaLibraryDialog`, `MediaLibraryCard`, `MediaResourceGallery`): MediaResourceGallery manages existing product media gallery attachments with typed accessors, primaryId, remove/reorder/primary callbacks, optional add and read-only presentation.
+
+### `themelia-react-ui/features/mentions`
+
+- **Mentions** (`MentionInlineSuggestions`, `MentionPicker`, `MentionChip`, `MentionContent`): Inline resource references for editors, comments, and event logs. Consumers provide resource registries and search callbacks; the package provides chips, picker UI, inline suggestions, parsing helpers, and headless hooks.
+
+### `themelia-react-ui/features/overlays`
+
+- **Action overlays** (`ConfirmDialog`, `ActionDialog`, `ActionDrawer`): A modal, drawer, or confirmation needs standardized confirm/cancel, async loading, error, strings, and tone behavior.
+
+### `themelia-react-ui/features/products`
+
+- **Products**: Product workspace/editor state, options, variants, tables, support rails, and callbacks must compose together.
+- **Product overview** (`ProductOverview`): ProductOverview composes product identity, media, facts, options, variants and selected supporting regions. Media enters through details.media; named slots insert separate app subjects.
+- **Variant details** (`ProductVariantDetails`, `ProductVariantEditor`): ProductVariantDetails presents one selected SKU with chosen options, media, metadata and commands; renderMetadata and footerSlot can add domain-specific inventory or costing context.
+- **Variant management** (`ProductOptionsMatrix`, `ProductVariantsBulkTable`, `ProductVariantsManager`, `ProductVariantsTable`): ProductVariantsManager combines optionGroups with sellable variants and coordinates option editing, grouping and variant commands through app callbacks.
+
+### `themelia-react-ui/features/questionnaire`
+
+- **Questionnaire**: Guided questions using library controls with validation and asynchronous application submission.
+
+### `themelia-react-ui/features/resource`
+
+- **Resource workspaces** (`ResourceActionBar`, `ResourceDetailsSection`, `ResourceEmptyState`): A resource route needs ResourceDetailsSection for a framed facts subject, ResourceEmptyState for an empty region, or ResourceActionBar for a row of record commands.
+
+### `themelia-react-ui/features/resource-assignment`
+
+- **Resource assignment** (`SharedResourceCard`): A stateful relationship-assignment workflow with consumer-owned resources, picker data, persistence, routing, and translations.
+
+### `themelia-react-ui/features/rich-text-editor`
+
+- **Rich text editor** (`RichTextEditor`, `FormRichTextEditor`): Tiptap-backed editor with bold / italic / strike / lists / quote / undo-redo. Falls back to a non-editable preview when @tiptap/react is not bundled. Strings overridable via the `strings` prop.
+
+### `themelia-react-ui/features/schema-form`
+
+- **Schema form** (`SchemaForm`): Schema-driven form renderer built from the package form fields. Supports one cohesive form, section cards, controlled values, validation callbacks, and render-prop overrides.
+
+### `themelia-react-ui/features/suggestions`
+
+- **Suggestions** (`SuggestionsCombobox`): Framework-agnostic typeahead suggestions with a drop-in combobox and a headless hook. Consumers own fetching, selected-value persistence, telemetry, and result rendering.
+
+### `themelia-react-ui/features/table`
+
+- **Data table** (`DataTable`, `Pagination`, `CellValue`, `CellStack`, `ResourceCell`, `StatusClusterCell`, `DateMetaCell`): Comparison columns, identity cells, sorting, selection or row actions are needed with app-owned query coordination and native toolbar/pagination seams.
+
+### `themelia-react-ui/features/theme-tweaker`
+
+- **Tenant theme**: Apply one portal-safe tenant theme with typed display defaults and exportable CSS.
+- **Theme tweaker** (`ThemeTweaker`, `ThemeScope`, `AdminUIThemeProvider`): A consumer needs an interactive theme studio, derived brand/type/elevation recipes, scoped or document-level live preview, a combined root theme/config boundary, complete or compact CSS export, or a typed UIProvider recipe.
+
+## Blocks
+
+Ready-made domain subjects. Card-free unless the name says card; frame them with Card where they are placed.
+
+### `themelia-react-ui/blocks/admin`
+
+- **Admin overview**: Console screens need permission matrices, API-key and token management, or confirmation-gated destructive actions.
+- **Action surfaces** (`SensitiveActionCard`, `CopyableSecretAlert`, `ApiTokenManager`): SensitiveActionCard, CopyableSecretAlert, and ApiTokenManager frame destructive admin actions, one-time secret reveals, and the full token create-and-revoke workflow.
+- **API keys** (`ApiKeyList`): ApiKeyList is a collapsible list of named secrets with a per-row copy/delete menu and an optional add action in the header.
+- **Role permissions** (`RolePermission`): RolePermission presents one role's grouped permission matrix — name, description, member count, and per-section granted/denied states — with an optional edit affordance.
+
+### `themelia-react-ui/blocks/ai`
+
+- **AI overview**: Model output needs a presentation block — summary, reasoning, citation, tool call, artifact — inside a surface the app already owns.
+- **Agent** (`AiAgent`): Identity chip or tile for an agent: name, model subtitle, tone-washed avatar, and a live status pill.
+- **Artifact** (`AiArtifact`): Framed container for a generated file or document: titled header, copy and download actions, body preview.
+- **Attachment** (`AiAttachment`): Chip for one file attached to a message: kind icon or thumbnail, meta line, upload progress, and remove.
+- **Chain of thought** (`AiChainOfThought`): Ordered step rail for an agent's plan, with pending, active, completed, and failed markers.
+- **Citation** (`AiCitation`): Expandable source list with snippets, publisher, date, and relevance behind a generated answer.
+- **Classification panel** (`AiClassificationPanel`): Reads an inbound request's type, urgency, tone, flags, complexity score, and suggested next action in one block.
+- **Code block** (`AiCodeBlock`): Read-only code surface with a language and filename header, copy action, line numbers, and line highlights.
+- **Confidence card** (`AiConfidence`): Circular confidence dial with a banded level badge and the weighted factors that produced the score.
+- **Confirmation** (`AiConfirmation`): In-stream approval prompt for a side-effecting agent action, collapsing into a status pill once resolved.
+- **Feedback** (`AiFeedback`): Thumbs up and down voter with an optional follow-up comment for model-improvement loops.
+- **File tree** (`AiFileTree`): Collapsible file tree with diff status pills for the files an agent created, changed, or removed.
+- **Inline citation** (`AiInlineCitation`): Numbered citation pill placed inline in generated prose, linking or dispatching to its source.
+- **Message bubble** (`AiMessageBubble`): Role-aware chat bubble with avatar, author and timestamp meta, and copy plus regenerate actions.
+- **Package info** (`AiPackageInfo`): Package manifest card: version, license, publish date, downloads, repository links, and keyword chips.
+- **Prompt suggestions** (`AiPromptSuggestions`): Grid of curated starter prompts that seed an assistant input when one is picked.
+- **Reasoning** (`AiReasoning`): Collapsible reasoning trace with a live thinking header and a thought-for duration once the stream ends.
+- **Shimmer** (`AiShimmer`): Animated gradient text for in-flight generation labels, pausable when the stream stalls.
+- **Sources** (`AiSources`): Compact provenance strip for a generated answer — a favicon list or a stacked avatar row with overflow.
+- **Summary block** (`AiSummaryBlock`): Renders a generated summary with entity chips, a three-bar confidence read, and a metadata plus actions footer.
+- **Task list** (`AiTask`): Nested task tree with per-node status markers, right-slot durations, and collapsible subtasks.
+- **Token usage** (`AiTokenUsage`): Input, output, and total token tiles with a context-window bar and an estimated cost row.
+- **Tool call** (`AiToolCall`): Collapsible row for one agent tool invocation: name, status, duration, arguments, and result or error.
+
+### `themelia-react-ui/blocks/analytics`
+
+- **Analytics overview**: The view needs the chart-free analytics blocks: MetricComparison, ActivityHeatmap, TimeDistributionRuler, MetricTrendChip, MetricSkeleton, or the shared metric types and formatters. This entry needs no optional peer.
+- **Comparison** (`MetricComparison`): MetricComparison presents one metric for the current and previous period with the signed change.
+- **Activity heatmap** (`ActivityHeatmap`): ActivityHeatmap presents daily activity counts as a Monday-aligned calendar grid with month labels and a legend.
+- **Metric parts** (`MetricTrendChip`, `MetricSkeleton`): A custom metric layout needs the parts on their own: MetricTrendChip and MetricSkeleton from blocks/analytics (no optional peer).
+- **Time distribution** (`TimeDistributionRuler`): TimeDistributionRuler presents counts across the hours of a day with the current hour marked.
+
+### `themelia-react-ui/blocks/analytics/charts`
+
+- **Analytics bar** (`MetricBar`, `MetricGrid`): MetricGrid renders peer KPI cards from MetricData with parent-width columns; MetricBar renders the same metrics as one strip with optional period/footer. Import both from blocks/analytics/charts, which needs the recharts peer.
+- **Chart card** (`ChartCard`): A custom chart needs shared title, description, action and footer regions. Import ChartCard from blocks/analytics/charts, which needs the recharts peer.
+- **Gradient cards** (`MetricGradient`): MetricGradient presents one hero metric over an embedded area chart. Import it from blocks/analytics/charts, which needs the recharts peer.
+- **Micro chart grid** (`MetricMicroGrid`): MetricMicroGrid packs six label/value cells, each with a small bars, line, dots, progress, area or pie visual, as a dense dashboard summary. Import it from blocks/analytics/charts, which needs the recharts peer.
+- **Stat cards** (`Metric`): Metric renders one KPI with formatting, trend, sparkline and loading/error presentation; variant="card" owns its Card surface. Import it from blocks/analytics/charts, which needs the recharts peer.
+
+### `themelia-react-ui/blocks/analytics/usage-card`
+
+- **Usage card** (`UsageCard`): Quota summaries, category shares, daily analytics and resource limits with app-owned period data.
+
+### `themelia-react-ui/blocks/collaboration`
+
+- **Message** (`Message`, `MessageBubble`, `MessageContent`, `MessageHeader`, `MessageActions`, `MessageStatus`): Message and MessageBubble present chat messages, author, delivery state, rich content and actions.
+
+### `themelia-react-ui/blocks/commerce`
+
+- **Commerce overview**: A screen renders a recognisable commerce subject — order, invoice, cart, shipment, giftcard, booking, vendor — as read-mostly display.
+- **Address card** (`AddressCard`): AddressCard presents one saved postal address with its kind, default marker and edit/remove/make-default callbacks.
+- **Booking event details** (`BookingCalendarEventCard`): A stateless booking summary for reservation facts, status, and one consumer-owned action.
+- **Cart summary** (`CartSummaryCard`): CartSummaryCard presents cart lines, subtotal, discount, shipping, tax and total with an optional checkout callback.
+- **Coupon input** (`CouponInputCard`): Coupon input card with empty and applied states plus apply/remove callbacks.
+- **Discount stack** (`DiscountStackPreview`): DiscountStackPreview lists the discounts applied to an order in stacking order, each a deduction, with the total saved.
+- **Giftcard** (`GiftcardCard`): Five visual variants — gradient, compact, minimal, dark, illustrated.
+- **Inventory level** (`InventoryLevel`): InventoryLevel presents one product stock snapshot: units in stock against capacity, reorder level and a critical/low/in-stock status.
+- **Inventory section** (`InventorySectionCard`): InventorySectionCard edits one SKU inventory record: identity, tracked quantities, policy, location, shipping, customs and tags through a controlled value.
+- **Invoice header** (`InvoiceHeader`): InvoiceHeader opens an invoice document: title and status, invoice number, bill-from and bill-to parties, issue and due dates and the amount due.
+- **Invoice line items** (`InvoiceLineItems`): InvoiceLineItems presents invoice descriptions, quantities, unit prices and line totals with a financial footer; typed columns and footerRows support a different invoice shape.
+- **Invoice mini** (`InvoiceMini`): InvoiceMini summarises one invoice in a list or dashboard: number, status, customer, item count, due date and total.
+- **Loyalty points** (`LoyaltyPoints`): Loyalty balance with a tier chip, history rows, and a redeem callback.
+- **Order status** (`OrderStatusCard`): OrderStatusCard presents one order status with its ETA and event list for a customer-facing order view.
+- **Order timeline** (`OrderTimeline`): Fulfillment progress for one order, drawn as a marker rail: placed, paid, prepared, shipped, delivered.
+- **Payment method** (`PaymentMethod`): PaymentMethod presents one saved payment instrument as a card face or a compact row, with default marker and change callback.
+- **Payment timeline** (`PaymentTimeline`): Collection history for one invoice, drawn as a marker rail: sent, reminded, received, receipted.
+- **Refund status** (`RefundStatusCard`): RefundStatusCard presents one refund moving through requested, approved, processing and completed stages with amount, method, reason and ETA.
+- **SEO listing** (`SeoListingCard`): Search result preview with product SEO scoring for title length, meta description, permalink, URL quality, slug format, and focus keyword coverage.
+- **Shipment tracking** (`ShipmentTracking`): ShipmentTracking presents one parcel: carrier, tracking number, delivery status and its checkpoint rail.
+- **Subscription summary** (`SubscriptionSummaryCard`): Subscription plan summary with price, billing date, perks, and manage/upgrade callbacks.
+- **Tax breakdown** (`TaxBreakdownCard`): TaxBreakdownCard presents a subtotal, each tax line and the taxed total as one ledger.
+- **Upcoming booking** (`UpcomingBookingRow`): Upcoming booking rows for compact commerce dashboards and operational schedules.
+- **Vendor profile** (`VendorProfileCard`): A decision-ready vendor dossier with controlled performance views and callback-driven engagement actions.
+- **Voucher entry** (`VoucherEntry`): Voucher lookup with controlled applied state and a remove callback.
+- **Summary panel** (`AmountRow`, `SummaryPanel`): SummaryPanel groups financial AmountRow entries such as subtotal, shipping, tax and a grand total inside an app-owned surface.
+- **Order header** (`OrderHeader`): OrderHeader is an order route title row: the order number as the heading, separate payment and fulfillment status chips, placement facts and one actions menu.
+- **Fulfillment group** (`FulfillmentGroup`): FulfillmentGroup presents one shipment worth of order goods that share a fulfillment status and ship-from location, as OrderLineItem rows with the commands that move them on.
+- **Order line item** (`OrderLineItem`): OrderLineItem presents purchased order items: one sold product with selected options, variant, SKU, quantity, unit price and passed line total in an order, refund or packing slip.
+- **Order summary** (`OrderSummary`): One order needs goods, total and payment ledgers with status and an optional balance note.
+- **Order transactions** (`OrderTransactions`): OrderTransactions lists every payment attempt of an order (authorizations, captures, refunds, failures) with amount, status and reference.
+- **Order customer** (`OrderCustomer`): OrderCustomer presents the buyer of one order: name, contact, order count and shipping/billing addresses with edit callbacks.
+
+### `themelia-react-ui/blocks/commerce/receipt`
+
+- **Receipt** (`Receipt`, `ReceiptItems`): Receipt renders a printable paper receipt with header, ReceiptItems content, footer and optional QR code.
+
+### `themelia-react-ui/blocks/data-display`
+
+- **Data display overview**: Entity facts, relationships, dense readouts, or empty regions need the package recipe instead of an app-local one.
+- **Dense info** (`DenseInfoDashboard`, `DenseInfoClassification`, `DenseInfoFinancial`, `DenseInfoProjectCard`, `DenseInfoScoreCard`): A dashboard, classification, financial, project, or score readout needs many facts in one tight card.
+- **Empty state** (`EmptyState`): No-data, no-results, or first-run content needs the standard media, title, description, and actions recipe.
+- **Inline stat** (`InlineStat`): One compact label/value pair needs inline emphasis without trend or chart semantics.
+- **Relationship card frame** (`RelationshipCardFrame`): App-owned relationship content needs title, badge, alert, selector, metadata, actions, and details regions.
+
+### `themelia-react-ui/blocks/onboarding`
+
+- **Onboarding checklist** (`OnboardingChecklist`): Step-list accordion with completed / in-progress / pending status indicators. Auto-opens the next non-completed step. Strings + status ARIA fully overridable. Composes base/accordion.
+
+### `themelia-react-ui/blocks/planning`
+
+- **Task card** (`TaskCard`): Compact task summaries with accessible expansion, controlled subtasks and assignment.
+
+### `themelia-react-ui/blocks/timelines`
+
+- **Timelines overview**: Read-only milestones, steps, or changelogs need marker-rail presentation, or a new rail needs the shared Timeline engine.
+- **Changelog** (`ChangelogTimeline`): ChangelogTimeline renders release history as a marker rail, mapping added, removed, modified, and fixed to neutral kind chips and marker icons with version, author, and timestamp.
+- **Milestones** (`MilestonesTimeline`): MilestonesTimeline renders dated project goals as a marker rail with status tone, a due-date line, and an inline progress bar for in-flight work.
+- **Steps card** (`StepsCard`, `StepsHorizontal`): StepsCard and StepsHorizontal render a finite, ordered progression whose entries are completed, current, or upcoming.
+- **Timeline engine** (`Timeline`): Timeline is the shared dot-and-line rail primitive every timeline surface is built on; drive it directly with TimelineItems to build a rail the package does not ship.
+
+## Layouts
+
+Application shells, pages, headers, sidebars and navigation regions.
+
+### `themelia-react-ui/layout`
+
+- Framework-neutral layout aggregate and shared layout types; exact layout family subpaths keep selection focused.
+
+### `themelia-react-ui/layout/app-shell`
+
+- **Application shell**: Compose responsive application chrome around app-owned navigation and routes.
+- **App shell** (`TopbarSidebarLayout`, `SidebarInsetLayout`, `StackedLayout`, `AppLayout`): Compose a Header, App sidebar or Inset shell with single or dual navigation and one PageViewport.
+
+### `themelia-react-ui/layout/auth`
+
+- **Auth shell** (`AuthShell`, `AuthCard`, `AuthSplitPanel`, `AuthFooterLinks`, `AuthMethodSwitch`, `AuthSocialProviders`, `AuthSocialProviderButton`): An authentication page needs its main landmark, title, form card and anonymous navigation composed by AuthShell.
+
+### `themelia-react-ui/layout/containers`
+
+- **Containers** (`Container`, `PageViewport`, `Section`, `TwoColumnLayout`): Compose content-led pages and public websites with explicit width, gutters, semantic section rhythm, scrolling and main/aside owners.
+
+### `themelia-react-ui/layout/header`
+
+- **Header** (`HeaderToolButton`, `HeaderToolPopover`, `HeaderGlobalSearchTrigger`, `HeaderUserMenu`, `Header`): Use Header for application chrome: compose brand, primary navigation and tools through its typed regions. Use OverflowTabBar when route navigation must preserve the active item and disclose overflow.
+
+### `themelia-react-ui/layout/hooks`
+
+- **Hooks**: Small framework-neutral helpers for active paths, link rendering, and command shortcuts inside layout composition.
+
+### `themelia-react-ui/layout/navigation`
+
+- **Navigation regions**: A vertical route rail, in-page anchor nav, category browse rail, or multi-step progress trail needs to frame content it does not own.
+- **Navigation patterns** (`CategoryNav`, `BreadcrumbProgress`): Semantic category navigation and wizard progress built from canonical Button, Item, Badge, typography, and value primitives.
+- **Section navigation** (`SectionNav`): Intersection-observer-backed navigation for anchored sections within a long settings or detail page.
+- **Side navigation** (`SideNav`): Canonical vertical route navigation with a short flat-list default and optional grouped, collapsible sections.
+
+### `themelia-react-ui/layout/page`
+
+- **Resource detail**: Compose page chrome, metadata, relationships, activity, and actions for one resource.
+- **Page shell** (`Page`, `PageHeader`): A route needs a title, composed context, back navigation, commands, tabs, toolbar, aside or loading/empty/error states.
+
+### `themelia-react-ui/layout/settings`
+
+- **Settings shell** (`AsideNavShell`): Several settings sections need persistent side navigation and a content region.
+
+### `themelia-react-ui/layout/sidebar`
+
+- **Sidebar** (`AppSidebar`, `SidebarNavigation`, `SidebarGroupedNavigation`, `SidebarWorkspaceDropdown`, `SidebarNavigationFooter`, `SidebarNavigationUser`, `LayoutSidebarProvider`, `SidebarNavigationRail`): Use AppSidebar for ordered/grouped navigation, contextual render slots, workspace partials and account footer composition.
+
+### `themelia-react-ui/layout/workspace`
+
+- **Workspace regions** (`WorkspaceLayout`, `WorkspaceRecordHeader`, `WorkspaceNav`, `WorkspaceLocaleStrip`): A bounded record workspace needs independently composed header, sidebar, main and rail regions.
+
+## Base components
+
+Controls, surfaces, structure and feedback: the parts every custom subject is made from.
+
+### `themelia-react-ui/base/accordion`
+
+- **Accordion** (`SmartAccordion`, `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`): Labeled disclosure or expandable form sections need coordinated state, custom validation badges or multiple open panels.
+
+### `themelia-react-ui/base/action-menu`
+
+- **Action menu** (`ActionMenu`): Edit, archive, delete, and other repeated action definitions need an overflow action menu.
+- **Action buttons** (`ActionButtons`): Inline rendering for the same shared action definitions used by ActionMenu, cards, and tables.
+- **Actions and overlays**: Reuse one action definition across inline, overflow, drawer, and confirmation surfaces.
+
+### `themelia-react-ui/base/attachment`
+
+- **Attachment**: Shared file presentation for upload queues, messages and document lists.
+
+### `themelia-react-ui/base/avatar`
+
+- **Avatar overview**: A person or entity needs image, initials fallback, status, badge, or grouped identity media.
+- **Avatar** (`Avatar`): The single identity image with its initials fallback, sized from the avatar token scale.
+- **Avatar group** (`AvatarGroup`, `AvatarGroupCount`, `AvatarBadge`): Manual compound control over each Avatar, badge, and overflow node is required.
+- **Stacked avatars** (`StackedAvatars`): A data array needs the standard overlapping avatar recipe, initials fallback, and overflow count.
+
+### `themelia-react-ui/base/badge`
+
+- **Badge** (`Badge`): A compact semantic status, category, count, or resource chip is needed, including replacement of a local display-only status pill.
+
+### `themelia-react-ui/base/batch-action-bar`
+
+- **Batch action bar** (`BatchActionBar`): A list, grid or table selection needs a count, bulk actions and Clear, docked to the viewport or inline.
+
+### `themelia-react-ui/base/buttons`
+
+- **Buttons overview** (`Button`, `TextButton`): An action needs a canonical button or a prose-like text action.
+- **Button** (`Button`): An action or native navigation link needs the canonical provider-aware button, with optional loading and tooltip behavior.
+- **Text button** (`TextButton`): A low-emphasis action should read like inline text while retaining button semantics.
+
+### `themelia-react-ui/base/cards`
+
+- **Card** (`CardPrimaryAction`, `CardActionStrip`, `CardSkeleton`, `Card`): A call site owns visible card chrome, card actions, or a card loading state.
+
+### `themelia-react-ui/base/carousel`
+
+- **Carousel** (`Carousel`, `CarouselPrevious`, `CarouselNext`, `CarouselNavigation`, `CarouselDots`, `CarouselDot`): A bounded ordered set genuinely needs horizontal/vertical slide navigation.
+
+### `themelia-react-ui/base/cascader`
+
+- **Cascader**: A form field chooses one or several nodes from a nested hierarchy, such as categories, locations or org units, with path search and optional async branches.
+
+### `themelia-react-ui/base/chart`
+
+- **Chart** (`ChartContainer`, `ChartStyle`, `ChartTooltipContent`, `ChartLegendContent`): Recharts output needs package theme tokens, tooltip, legend, and accessible chart scaffolding: compose Recharts AreaChart, BarChart, LineChart or PieChart inside ChartContainer with a ChartConfig.
+
+### `themelia-react-ui/base/choice-inputs`
+
+- **Choice inputs overview**: The user picks from a known set of options, including a binary on/off.
+- **Card checkbox group** (`CardCheckboxGroup`): CardCheckboxGroup selects multiple values from comparable options whose labels and descriptions benefit from card targets, including a small two-option set.
+- **Card radio group** (`CardRadioGroup`): Mutually exclusive visual choices rendered as cards.
+- **Checkbox** (`Checkbox`): Base checkbox wrapper for independent boolean choices.
+- **List radio group** (`ListRadioGroup`): Vertically scannable radio choices with descriptions.
+- **Pill radio group** (`PillRadioGroup`): Compact mutually exclusive choices rendered as a pill group.
+- **Select** (`Select`): The canonical finite-option form control, from compact status fields to descriptive selectors.
+- **Switch** (`Switch`): Canonical boolean control with native form semantics and a value-first callback.
+- **Switch card** (`SwitchCard`): SwitchCard gives one boolean setting a label, supporting description and clickable card-shaped target.
+- **Toggle field** (`ToggleField`): Label, description, and switch or checkbox blocks as one form row.
+
+### `themelia-react-ui/base/code-block`
+
+- **Code block**: Code display with copy feedback, line numbers, focused/highlighted lines and caller-provided syntax rendering.
+
+### `themelia-react-ui/base/combobox`
+
+- **Combobox anatomy**: Base UI-backed combobox anatomy with shared field, popup, list and item recipes: root, input, trigger, groups, chips and filtering.
+
+### `themelia-react-ui/base/command`
+
+- **Command** (`Command`, `CommandInput`, `CommandItem`): A custom keyboard-searchable command list needs low-level compound anatomy.
+
+### `themelia-react-ui/base/copyable`
+
+- **Copyable** (`Copyable`): A displayed scalar or semantic value needs an explicit adjacent clipboard action.
+
+### `themelia-react-ui/base/date-pickers`
+
+- **Date pickers overview** (`DatePicker`, `MonthYearPicker`): A form needs single, multiple, range, month/year, or segmented-time date selection.
+- **Date picker** (`DatePicker`): The unified single, range, and multiple calendar control with locale, year selection, and optional time editing.
+- **Month/year picker** (`MonthYearPicker`): A compact month and year selector for reporting periods, filters, and recurring settings.
+- **Time picker** (`TimePicker`): Segmented time-of-day input — inline, or behind a field-shaped popover trigger.
+
+### `themelia-react-ui/base/display`
+
+- **Boolean indicator** (`BooleanIndicator`): A read-only boolean field needs a compact icon and localized yes/no label.
+- **Collapsible** (`Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`): One custom trigger/content region needs low-level controlled or uncontrolled disclosure.
+- **Date block** (`DateBlock`): A date needs a calendar-like month/day visual block rather than inline formatting.
+- **Icon badge** (`IconBadge`): An icon needs a consistent framed circular or rounded visual container.
+- **Placeholder pattern** (`PlaceholderPattern`): An empty media, map, or generated-preview region needs a quiet decorative fill.
+- **Scroll area** (`ScrollArea`): A bounded region needs styled horizontal or vertical overflow and package scrollbar chrome.
+- **Separator** (`Separator`): Adjacent groups need a semantic visual divider in horizontal or vertical orientation.
+- **Tooltip** (`Tooltip`, `TooltipProvider`, `TooltipTrigger`, `TooltipContent`): Brief supplementary text should appear on hover and keyboard focus.
+- **Visually hidden** (`VisuallyHidden`): Meaningful text must remain available to assistive technology without visual layout.
+
+### `themelia-react-ui/base/feedback`
+
+- **Alert** (`Alert`, `AlertTitle`, `AlertDescription`, `AlertMetadata`, `AlertMetadataItem`, `AlertAction`): Contextual feedback needs alert semantics plus optional title, description, metadata, or action regions.
+- **Empty state** (`Empty`): Custom empty-state anatomy must be assembled from low-level media, header, title, description, and content parts.
+- **Feedback overview**: A region must report its own status: an inline notice, task progress, or a standard loading or recoverable-error presentation.
+- **Error state** (`ErrorState`): Consistent embedded and self-framed recovery presentations with retry or custom-action seams.
+- **Loading state** (`LoadingState`): Compact embedded loading feedback or a self-framed panel with progress and content skeletons.
+- **Progress** (`Progress`, `ProgressTrack`, `ProgressIndicator`, `ProgressLabel`, `ProgressValue`): Known completion progress must be represented as a determinate bar.
+
+### `themelia-react-ui/base/forms`
+
+- **Forms overview**: Editable values need canonical field controls, field chrome, grouped choices, uploads, or form-state recipes.
+- **Controlled form field** (`ControlledFormField`): React Hook Form binding with canonical validation and field chrome.
+- **Dirty state banner** (`DirtyStateBanner`): Reusable warning surface for unsaved form changes.
+- **Error summary** (`ErrorSummary`): Accessible destructive summary for form-level validation failures.
+- **Form actions bar** (`FormActionsBar`): FormActionsBar gives a multi-section form a full-width footer with leading status and trailing actions, optionally sticky to its scrolling ancestor.
+- **Form field** (`FormField`): A label, editable control, and hint or error form one accessible field row.
+- **Form section** (`FormSection`): Related form fields need one titled section with optional actions and footer.
+- **Operation password form** (`OperationPasswordForm`): Password confirmation form for protected operations.
+- **Submit state button** (`SubmitStateButton`): SubmitStateButton submits a form with a pending state and optional pristine protection through submitting, dirty and disableWhenPristine.
+- **Validated form**: Compose accessible fields, validation, dirty state, and submit lifecycle without moving the schema into the package.
+
+### `themelia-react-ui/base/forms-numeric`
+
+- **Numeric fields overview**: An editable value is a number carrying a unit, a currency, or a rounding policy.
+- **Coordinates input** (`CoordinatesInput`): Latitude and longitude control supporting coherent value shapes.
+- **Currency input** (`CurrencyInput`): The lower-level amount-and-currency control for integrations that keep the raw decimal and the currency in separate state channels.
+- **Decimal input** (`DecimalInput`): Numeric input for decimal precision, steppers, bounds, and signed values.
+- **Dimensions input** (`DimensionsInput`): Coherent two- or three-dimensional measurement input.
+- **Money input** (`MoneyInput`): The canonical amount-and-currency editor with form chrome, combined value callbacks, validation, and conversion context.
+- **Percentage input** (`PercentageInput`): Percentage-specific numeric input with a consistent suffix and step controls.
+- **Rounding mode select** (`RoundingModeSelect`): Purpose-built selector for supported monetary rounding strategies.
+- **Weight input** (`WeightInput`): Weight value and unit control for shipping and inventory forms.
+
+### `themelia-react-ui/base/inline-edit`
+
+- **Inline edit** (`InlineEdit`): Readable fields with keyboard editing, validation, async save and cancellation.
+
+### `themelia-react-ui/base/item`
+
+- **Item** (`Item`): Each row has its own identity, media/title stack, target, trailing value, or actions.
+
+### `themelia-react-ui/base/media-gallery`
+
+- **Media gallery** (`MediaGallery`): MediaGallery edits a product media gallery of local File[] images before upload: add files, preview, remove, sort by drag or keyboard, and use the first image as cover.
+
+### `themelia-react-ui/base/metadata-list`
+
+- **Metadata list** (`MetadataList`): Customer, order, account, or record label/value facts need a grid, rows, or inline summary.
+
+### `themelia-react-ui/base/navigation`
+
+- **Navigation overview** (`PageHeading`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `Breadcrumbs`, `OverflowTabBar`, `LanguageSwitcher`): Page headings, breadcrumbs, pagination, tabs, or a language switcher need canonical navigation anatomy.
+- **Breadcrumbs** (`Breadcrumbs`): Consumer-routed breadcrumb trails with package-controlled scale and an overridable link renderer.
+- **Dropdown menu** (`DropdownMenuContent`): Low-level menu composition for checkbox, radio, submenu, and bespoke content that does not fit ActionMenu.
+- **Language switcher** (`LanguageSwitcher`): Callback-driven locale selection in button and compact inline presentations.
+- **Navigation tabs** (`NavigationTabs`, `TabsList`): A small, always-visible set of sibling application routes needs compact or prominent tab navigation.
+- **Overflow tab bar** (`OverflowTabBar`): Responsive controlled tabs that move excess items into a shared overflow menu.
+- **Page heading** (`PageHeading`): An existing shell needs only a visual title, description, badges, and actions block.
+- **Pagination** (`PaginationPrevious`, `PaginationNext`, `PaginationEllipsis`, `PaginationRoot`): Styled pagination primitives for consumer-owned page state and routing.
+
+### `themelia-react-ui/base/popover`
+
+- **Popover** (`Popover`, `PopoverContent`): A trigger needs a small anchored custom content surface with explicit compound control.
+
+### `themelia-react-ui/base/popover-menu`
+
+- **Popover menu** (`PopoverMenu`): A trigger opens the recurring optional-header, search, list, and footer menu pattern.
+
+### `themelia-react-ui/base/qr-code`
+
+- **QR code**: A string must be rendered as a QR code with an accessible label and optional logo.
+
+### `themelia-react-ui/base/repeaters`
+
+- **Repeaters overview**: A field edits a list of rows the person adds, removes, and reorders, or a value keyed by locale.
+- **Key-value editor** (`KeyValueEditor`): Controlled editor for reusable string key and value pairs.
+- **Localized object field** (`LocalizedObjectField`): React Hook Form editor for locale-keyed structured values.
+- **Localized string field** (`LocalizedStringField`): React Hook Form text field for locale-keyed string values.
+- **Localized string repeater** (`LocalizedStringRepeater`): React Hook Form repeater for locale-keyed string arrays.
+- **Object repeater** (`ObjectRepeater`): React Hook Form list editor for repeated structured objects.
+- **Repeater** (`Repeater`): Headless list-field chrome with consumer-owned rows, addition, removal, and sorting.
+- **String repeater** (`StringRepeater`): React Hook Form adapter for string arrays, powered by the controlled Repeater chrome.
+
+### `themelia-react-ui/base/sidebar`
+
+- **Sidebar primitives** (`SidebarMenuButton`, `SidebarProvider`, `Sidebar`, `SidebarInput`, `SidebarGroupLabel`, `SidebarMenuBadge`, `SidebarMenuSkeleton`, `SidebarMenuSubButton`): A shell implementation needs the low-level responsive/collapsible sidebar compound.
+
+### `themelia-react-ui/base/signature-pad`
+
+- **Signature pad**: Structured signature capture, accessible typed signatures, history and application-owned export.
+
+### `themelia-react-ui/base/skeleton`
+
+- **Skeleton overview**: Loading should preserve the approximate geometry of content, cards, tables, or pages.
+- **Skeleton block** (`Skeleton`): The raw shimmer block that every other skeleton composes — shape it with utility classes when no ready-made scaffold fits.
+- **Content skeleton** (`ContentSkeleton`): Reusable loading placeholders for common media, text-line, and trailing-action content rows.
+- **Page skeleton** (`PageSkeleton`): A full-page loading scaffold with summary statistics and configurable content sections.
+- **Table skeleton** (`TableSkeleton`): A configurable table-shaped loading scaffold for dense data indexes.
+- **Two-column page skeleton** (`TwoColumnPageSkeleton`): Loading geometry for operational detail pages with a main column and supporting sidebar.
+
+### `themelia-react-ui/base/spinner`
+
+- **Spinner** (`Spinner`): A compact control or bounded area needs an indeterminate activity indicator.
+
+### `themelia-react-ui/base/structure`
+
+- **Structural composition** (`Stack`, `Grid`, `GridCell`, `AdaptiveGrid`): Compose passive layout blocks with Stack rows, responsive Grid tracks, GridCell spans and available-width AdaptiveGrid.
+
+### `themelia-react-ui/base/table`
+
+- **Table primitives** (`Table`): Custom semantic table markup only needs package-styled HTML table parts.
+
+### `themelia-react-ui/base/text-inputs`
+
+- **Text inputs overview**: The value is free-form text the user types.
+- **Input** (`Input`): Tokenized text input with icons, addons, loading, clearing, and invalid states.
+- **Password input** (`PasswordInput`): Password field with a built-in accessible visibility control.
+- **Slug field** (`SlugField`): Generated, read-only slug input derived from a source value.
+- **Textarea** (`Textarea`): Tokenized multiline input with character counting and invalid states.
+
+### `themelia-react-ui/base/toaster`
+
+- **Toaster** (`Toaster`): Application-level transient feedback should be rendered through the package Sonner host.
+
+### `themelia-react-ui/base/tree`
+
+- **Tree**: Keyboard-navigable hierarchical selection with controlled expansion and optional multiple selection.
+
+### `themelia-react-ui/base/upload`
+
+- **Upload overview**: A surface selects, validates, previews, or reports progress for files the consumer will transfer.
+- **Avatar upload** (`AvatarUpload`): Compact profile image picker with preview and initials fallback.
+- **Dropzone** (`Dropzone`): Callback-driven drag-and-drop file selection surface.
+- **File upload** (`FileUpload`): Controlled or uncontrolled local-file selection with single and multiple modes, validation, and selected-file presentation.
+- **Image upload** (`ImageUpload`): Preview-first image picker with configurable aspect ratio and layout.
+
+### `themelia-react-ui/base/upload-queue`
+
+- **Upload progress list** (`UploadProgressList`): Render-only upload rows for queued, active, completed, and failed transfers.
+- **Upload tray** (`UploadTray`): Drag-drop area + per-file progress rows + summary toolbar. Composes Dropzone and UploadProgressList. Framework-agnostic — the consumer drives the actual transfer.
+
+### `themelia-react-ui/base/value-inputs`
+
+- **Value inputs overview**: One structured value needs its own editing affordance — tags, phone, colour, range, date-time.
+- **Color input** (`ColorInput`): A form needs exact CSS-color entry and an accessible visual color picker on one value channel.
+- **Date and time input** (`DateTimeInput`): Combined date and time value input with a consumer-owned value.
+- **Phone input** (`PhoneInput`): Phone-number control with consumer-configurable country prefixes.
+- **Slider field** (`SliderField`): Tokenized numeric range control with form-compatible value callbacks.
+- **Tags input** (`TagsInput`): Multi-value text input with recommendations and keyboard entry.
+
+## Foundations
+
+Typography, value primitives, provider, strings and utilities.
+
+### `themelia-react-ui`
+
+- Optional-peer-free root: UIProvider display defaults, basic portal-safe ThemeScope, shared vocabulary, action presentation, strings and class merging. Component families use exact subpaths.
+
+### `themelia-react-ui/action-presentation`
+
+- Shared action presentation types and button-style vocabulary; action rendering belongs to public control families.
+
+### `themelia-react-ui/component-vocabulary`
+
+- Shared scale, semantic tone, card surface and disclosure surface constants and types.
+
+### `themelia-react-ui/lib/strings`
+
+- Typed strings merging, interpolation and React resolution helpers for application-supplied translations.
+
+### `themelia-react-ui/lib/utils`
+
+- Token-aware Tailwind class merging through cn, preserving public DOM hooks.
+
+### `themelia-react-ui/primitives`
+
+- **Primitives overview**: Displayed data has money, date, contact, identity, code, numeric, duration, or empty-value semantics.
+- **Date** (`Date`, `Time`, `DateTime`, `DateRange`, `RelativeTime`): The date family — Date, Time, DateTime, DateRange, and RelativeTime — formatting instants from any of the shapes an API returns.
+- **Dimensions** (`Dimensions`): A width × height (× depth) reading with localized numbers and a consumer-owned unit, for media assets and physical parcels alike.
+- **Duration** (`Duration`): An elapsed span written in localized units, from a millisecond round trip to a retention window measured in days.
+- **File size** (`FileSize`): A byte count rendered in the largest unit that keeps it readable, so attachment rows, upload trays, and quota readouts all agree.
+- **Initials** (`Initials`): Identity initials derived from a person, organization, or resource name, with a shared strategy so every avatar fallback in the app agrees.
+- **Link** (`Link`, `Email`, `Phone`, `Url`): Link-coloured inline values — a plain anchor plus Email, Phone, and Url, which each generate the correct href from the raw value.
+- **Money** (`Money`): One monetary display primitive for major or minor units, empty values, dual pricing, and explicit conversions.
+- **Name** (`Name`): A person or organization name, title-cased only when the incoming value clearly was not cased on purpose.
+- **Number** (`Number`, `Percent`): Locale-formatted counts and percentages that render right-aligned and tabular so columns of them line up.
+- **Value** (`Value`, `SecondaryValue`, `MutedValue`, `MonoValue`, `EmptyValue`): The five general-purpose value spans — ordinary, secondary, muted, monospaced, and intentionally empty — that every metadata row, card fact, and table cell is built from.
+
+### `themelia-react-ui/services/actions`
+
+- **Runtime actions**: Define framework-neutral actions once and reuse their behavior across package surfaces.
+
+### `themelia-react-ui/typography`
+
+- **Typography** (`Heading`, `Text`, `DisplayLabel`, `Label`, `TextLink`): Library-owned prose, headings, labels, or text links need a typography role.
+
+### `themelia-react-ui/typography/rich-text`
+
+- **Rich HTML display** (`RichText`): Sanitized rich HTML display with scoped reading rhythm and opt-in images drawn by a consumer renderImage; editing belongs to the rich-text-editor feature.
+
+### `themelia-react-ui/ui-provider`
+
+- **UIProvider**: Configure one React-root boundary for stable application-wide display defaults.