themelia-react-ui 2.0.5 → 3.0.0

package/MIGRATION.md

@@ -0,0 +1,858 @@
+# Migration guide
+
+`themelia-react-ui` is the Base UI and Tailwind port of the Themelia package
+`admin-ui-starter-kit`. The package names have independent version histories.
+This file covers two moves:
+
+- [Upgrading from 2.x to 3.0](#upgrading-from-2x-to-30), for applications
+  already on `themelia-react-ui` 2.x.
+- [From admin-ui-starter-kit 3.x](#from-admin-ui-starter-kit-3x), for
+  applications moving from the earlier package.
+
+## Upgrading from 2.x to 3.0
+
+3.0 removes the deprecated and legacy API that 2.x kept for compatibility:
+second names for one component, re-exports from an old path, props and string
+keys that had no effect, and the `asChild` composition form. It also removes
+props that duplicated another prop: a label prop beside a `strings` key, a
+flat prop beside a `slots` key, a boolean beside the option that already
+implies it. Each such row names the one form that remains. Two package
+entries are gone, the chart blocks have their own entry, a few types are
+narrower, and the default control size and table edge inset changed.
+
+Work in this order:
+
+1. Install `themelia-react-ui` 3.0.0.
+2. Update imports of moved and removed entries: the
+   [chart blocks](#chart-blocks-moved) and the two
+   [removed entries](#removed-entries).
+3. Replace removed API layer by layer, using the tables in
+   [Removed API](#removed-api): base and lower layers first, then layouts and
+   templates, blocks, data features and content features.
+4. Convert `asChild` to `render` ([Composition form](#composition-form)).
+5. Fix the narrower types listed under [Breaking changes](#breaking-changes).
+6. Review the [changed defaults](#changed-defaults) and the
+   [changed behaviour](#changed-behaviour).
+
+Removed exports, types and props are type errors, so a type check after each
+step shows what is left. A few removals are not reported by the compiler and
+need a search of your own code: the snake case `content_type` field on
+comments, a RANGE filter URL that carries one bare value, and CSS or test
+selectors that target ContentBlock or PageHeader hooks. Their rows say what
+changed.
+
+### Breaking changes
+
+- **Chart blocks moved.** `Metric`, `MetricBar`, `MetricGrid`,
+  `MetricMicroGrid`, `MetricGradient`, `MetricSparkline` and `ChartCard` (with
+  their types) are now imported from
+  `themelia-react-ui/blocks/analytics/charts`.
+  `themelia-react-ui/blocks/analytics` no longer loads the optional `recharts`
+  peer. The symbol table is in [Chart blocks moved](#chart-blocks-moved).
+- **Variant props no longer accept `null`.** Affects `variant`, `size`, `tone`
+  and `align` on Alert, EmptyMedia, SidebarMenuButton, SidebarTrigger,
+  TabsList, Toggle, ToggleGroup, InputGroupAddon, InputGroupButton, Item and
+  ItemMedia. Pass `undefined` or omit the prop.
+- **Cascader and Accordion value types are narrower.** Cascader is typed by
+  mode: single takes `string | null`, `multiple` takes and emits string arrays
+  (`CascaderSingleProps`, `CascaderMultipleProps`). `Accordion` is generic over
+  its value type instead of `any[]`.
+- **Deprecated and legacy API removed.** Two entries
+  ([Removed entries](#removed-entries)) and the exports, types, props, string
+  keys and values listed in [Removed API](#removed-api).
+
+#### Changed defaults
+
+**Control sizes.** `--height-action` and `--height-control` default to
+2.125rem (were 2rem) and `--control-x` to 0.875rem (was 0.75rem), so default
+buttons and fields are 34px tall with a 14px inline inset.
+
+| Root | 2.x default | 3.0 default |
+| --- | --- | --- |
+| `--height-action` | 2rem | 2.125rem |
+| `--height-control` | 2rem | 2.125rem |
+| `--control-x` | 0.75rem | 0.875rem |
+
+To keep the previous sizes, set the three roots back to the old values at the
+root or at a scoped theme boundary:
+
+```css
+:root {
+  --height-action: 2rem;
+  --height-control: 2rem;
+  --control-x: 0.75rem;
+}
+```
+
+**Table edges.** The first and last columns of every table use the default
+surface inset (24px, following `--surface-x` and `--space-scale`) instead of
+16px, so a table lines up with the card title, toolbar and footer around it. A
+table inside a padded Card body sits flush with that body. DataTable and
+DataView regions (topbar, selection bar, filter bar, footer, pagination) share
+the same edge, and row checkboxes start on it. The table edge has no root of
+its own: it follows `--surface-x` and `--space-scale`, which also set the
+inset of the surfaces around the table, so changing those roots moves every
+surface inset with it.
+
+### Removed entries
+
+| Removed entry | Use instead |
+| --- | --- |
+| `themelia-react-ui/features/sync` | `SchemaForm` from `themelia-react-ui/features/schema-form`, with a `radio-cards` field for the window and a `checkbox-cards` field for the options. Wrap it in `ActionDialog` from `themelia-react-ui/features/overlays` for a dialog. The symbol rows are under [`features/sync`](#featuressync). |
+| `themelia-react-ui/base/sheet` | `ActionDrawer` from `themelia-react-ui/features/overlays`; for an external control use `useOverlayVisibility` from the same entry. The part-by-part mapping is under [`base/sheet`](#basesheet). |
+
+### Removed API
+
+Every table has the same columns. "Kind" is `export`, `type`, `prop`,
+`string` (a key of a strings object) or `value` (a prop value, a data field or
+a call shape). Import paths are the public package entries.
+
+#### Base and lower layers
+
+##### `base/upload`
+
+These names were re-exports. They moved to their own entries.
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `MediaGallery` | export | `themelia-react-ui/base/upload` | `MediaGallery` from `themelia-react-ui/base/media-gallery` | Same component; only the import path changes. |
+| `defaultMediaGalleryStrings` | export | `themelia-react-ui/base/upload` | `defaultMediaGalleryStrings` from `themelia-react-ui/base/media-gallery` | |
+| `MediaGalleryProps` | type | `themelia-react-ui/base/upload` | `MediaGalleryProps` from `themelia-react-ui/base/media-gallery` | |
+| `MediaGalleryStrings` | type | `themelia-react-ui/base/upload` | `MediaGalleryStrings` from `themelia-react-ui/base/media-gallery` | |
+| `UploadProgressList` | export | `themelia-react-ui/base/upload` | `UploadProgressList` from `themelia-react-ui/base/upload-queue` | Same component; only the import path changes. |
+| `defaultUploadProgressListStrings` | export | `themelia-react-ui/base/upload` | `defaultUploadProgressListStrings` from `themelia-react-ui/base/upload-queue` | |
+| `UploadProgressListProps` | type | `themelia-react-ui/base/upload` | `UploadProgressListProps` from `themelia-react-ui/base/upload-queue` | |
+| `UploadProgressListStrings` | type | `themelia-react-ui/base/upload` | `UploadProgressListStrings` from `themelia-react-ui/base/upload-queue` | |
+| `UploadItem` | type | `themelia-react-ui/base/upload` | `UploadItem` from `themelia-react-ui/base/upload-queue` | |
+| `UploadStatus` | type | `themelia-react-ui/base/upload` | `UploadStatus` from `themelia-react-ui/base/upload-queue` | |
+| `UploadTray` | export | `themelia-react-ui/base/upload` | `UploadTray` from `themelia-react-ui/base/upload-queue` | Same component; only the import path changes. |
+| `defaultUploadTrayStrings` | export | `themelia-react-ui/base/upload` | `defaultUploadTrayStrings` from `themelia-react-ui/base/upload-queue` | |
+| `UploadTrayProps` | type | `themelia-react-ui/base/upload` | `UploadTrayProps` from `themelia-react-ui/base/upload-queue` | |
+| `UploadTrayStrings` | type | `themelia-react-ui/base/upload` | `UploadTrayStrings` from `themelia-react-ui/base/upload-queue` | |
+
+##### `base/sheet`
+
+The `themelia-react-ui/base/sheet` entry no longer exists. Nothing public is
+left in it. `ActionDrawer` and `useOverlayVisibility` come from
+`themelia-react-ui/features/overlays`.
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `Sheet` | export | `themelia-react-ui/base/sheet` | `ActionDrawer` from `themelia-react-ui/features/overlays` | Open state: `open`/`onOpenChange`, or the `trigger` prop. |
+| `SheetTrigger` | export | `themelia-react-ui/base/sheet` | `ActionDrawer trigger={…}` | For an external control use `useOverlayVisibility` from `themelia-react-ui/features/overlays`. |
+| `SheetClose` | export | `themelia-react-ui/base/sheet` | `ActionDrawer showCloseButton` and its cancel action | ActionDrawer renders its own dismiss control. |
+| `SheetContent` | export | `themelia-react-ui/base/sheet` | `ActionDrawer` (`direction`, `width`, `modal`) | |
+| `SheetHeader` | export | `themelia-react-ui/base/sheet` | `ActionDrawer title` / `description` | |
+| `SheetBody` | export | `themelia-react-ui/base/sheet` | `children` of `ActionDrawer` | ActionDrawer owns the scrolling body. |
+| `SheetFooter` | export | `themelia-react-ui/base/sheet` | The generated actions or the `footer` prop of `ActionDrawer` | |
+| `SheetTitle` | export | `themelia-react-ui/base/sheet` | `ActionDrawer title` | |
+| `SheetDescription` | export | `themelia-react-ui/base/sheet` | `ActionDrawer description` | |
+
+##### `base/cards`
+
+The `SmartCard*` names were second names for `Card`.
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `SmartCard` | export | `themelia-react-ui/base/cards` | `Card` | Same component and props; rename only. |
+| `SmartCardSkeleton` | export | `themelia-react-ui/base/cards` | `CardSkeleton` | Rename only. |
+| `defaultSmartCardStrings` | export | `themelia-react-ui/base/cards` | `defaultCardStrings` | Rename only. |
+| `SmartCardProps` | type | `themelia-react-ui/base/cards` | `CardProps` | Rename only. |
+| `SmartCardSkeletonProps` | type | `themelia-react-ui/base/cards` | `CardSkeletonProps` | Rename only. |
+| `SmartCardAction` | type | `themelia-react-ui/base/cards` | `CardAction` | Rename only. |
+| `SmartCardStrings` | type | `themelia-react-ui/base/cards` | `CardStrings` | Rename only. |
+| `SmartCardSurface` | type | `themelia-react-ui/base/cards` | `CardSurface` | Rename only. |
+| `Card` `tooltipAriaLabel` | prop | `themelia-react-ui/base/cards` | `strings={{ tooltipLabel: '…' }}` | Same accessible name on the info trigger. |
+| `Card` `actionsLabel` | prop | `themelia-react-ui/base/cards` | `strings={{ actionsLabel: '…' }}` | Same accessible name on the overflow trigger. An `undefined` value keeps the default. |
+| `Card` `footerText` | prop | `themelia-react-ui/base/cards` | `footerSlot` | A string or number in `footerSlot` is now the footnote: small, secondary, at the end of the footer, exactly as `footerText` drew it. A node fills the footer width, as before. For a footnote above a command, pass both in one `footerSlot` node. |
+
+##### `base/display`
+
+The ContentBlock adapter is removed. The `asChild` rows are explained in
+[Composition form](#composition-form).
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `ContentBlock` | export | `themelia-react-ui/base/display` | `Card` from `themelia-react-ui/base/cards` with `surface="flat" padding="none"` | Every ContentBlock prop exists on Card under the same name. ContentBlock defaulted to `surface="flat"`; its `padding` defaulted to `none`, or to `md` when a `surface` other than `flat` was given. Pass those two props explicitly. Card no longer adds `content-block--component`, `content-block--header`, `content-block--content`, `content-block--footer`, `data-component="content-block"`, `data-slot="content-block"` or `data-padding` on the root; if your CSS or tests select them, add the classes through `className`, `headerClassName`, `contentClassName` and `footerClassName`, or select `card--component`, `card--header`, `card--content`, `card--footer`. |
+| `ContentBlockProps` | type | `themelia-react-ui/base/display` | `CardProps` from `themelia-react-ui/base/cards` | |
+| `ContentBlockPadding` | type | `themelia-react-ui/base/display` | `CardProps['padding']` | ContentBlock accepted `sm`, `md`, `lg`; Card also accepts `none`. |
+| `ContentBlockSurface` | type | `themelia-react-ui/base/display` | `CardSurface` from `themelia-react-ui/base/cards` | |
+| `ContentBlockTitleSize` | type | `themelia-react-ui/base/display` | `CardProps['titleSize']` | |
+| `ContentBlockStrings` | type | `themelia-react-ui/base/display` | `CardStrings` from `themelia-react-ui/base/cards` | Same keys: `actionsLabel`, `tooltipLabel`. |
+| `defaultContentBlockStrings` | export | `themelia-react-ui/base/display` | `defaultCardStrings` from `themelia-react-ui/base/cards` | |
+| `TooltipTrigger` `asChild` | prop | `themelia-react-ui/base/display` | `render={<Button … />}` | |
+| `CollapsibleTrigger` `asChild` | prop | `themelia-react-ui/base/display` | `render={<Button … />}` | `nativeButton` is now inferred from the `render` element (a `button`, or a component without `href`, is native). Pass `nativeButton` to override. |
+
+##### `base/popover`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `PopoverTrigger` `asChild` | prop | `themelia-react-ui/base/popover` | `render={<Button … />}` | Same `nativeButton` inference as `CollapsibleTrigger`: it is inferred from the `render` element (a `button`, or a component without `href`, is native). Pass `nativeButton` to override. |
+| `PopoverAnchor` `asChild` | prop | `themelia-react-ui/base/popover` | `render={<div … />}` | Without `render` it is still a `span`. |
+
+##### `base/command`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `Command` `asChild` | prop | `themelia-react-ui/base/command` | `render={<section />}` with the content as `children` | `render` takes an element. |
+| `CommandInput` `asChild` | prop | `themelia-react-ui/base/command` | `render={<input … />}` | Without `render` the shared `Input` is used, as before. |
+| `CommandList` `asChild` | prop | `themelia-react-ui/base/command` | `render={<ul />}` with items as `children` | |
+| `CommandGroup` `asChild` | prop | `themelia-react-ui/base/command` | `render={<section />}` with items as `children` | The `heading` is rendered inside the composed element, before the children. |
+| `CommandItem` `asChild` | prop | `themelia-react-ui/base/command` | `render={<a href="…" />}` with the label as `children` | The item's `id` is still applied to the composed element. |
+| `CommandSeparator` `asChild` | prop | `themelia-react-ui/base/command` | `render={<hr />}` | |
+
+##### `base/sidebar`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `useSidebar` | export | `themelia-react-ui/base/sidebar` | `useLayoutSidebar` from `themelia-react-ui/layout/sidebar` | |
+| `SidebarTrigger` `variant` | prop | `themelia-react-ui/base/sidebar` | Nothing; the trigger is always the ghost icon button | It exposed the raw primitive's variants (`default`, `destructive`, `ghost`, `link`, `outline`, `secondary`). Style a different trigger through `className`, or render your own button and drive `SidebarProvider` through `open` / `onOpenChange`. |
+| `SidebarTrigger` `size` values `default`, `xs`, `icon`, `icon-xs`, `icon-sm`, `icon-lg` | value | `themelia-react-ui/base/sidebar` | `size="sm" \| "md" \| "lg"` | `icon-sm` → `sm`, `icon` or `default` → `md`, `icon-lg` → `lg`; `xs` and `icon-xs` have no equivalent. `sm` and `lg` now name the icon-button scale (they were the raw text-button sizes). Default is `md`. |
+
+##### `base/navigation`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `PaginationPrimitive` | export | `themelia-react-ui/base/navigation` | `PaginationRoot` | Same component; rename only. |
+| `PaginationPrevious` `children` | prop | `themelia-react-ui/base/navigation` | `text` | The children were accepted and ignored. |
+| `PaginationNext` `children` | prop | `themelia-react-ui/base/navigation` | `text` | The children were accepted and ignored. |
+| `LanguageSwitcher` `onRenderLabel` | prop | `themelia-react-ui/base/navigation` | `renderLabel` | Same signature: `(locale: LocaleOption) => string`. |
+| `LanguageSwitcher` `onSelect` | prop | `themelia-react-ui/base/navigation` | `onValueChange` | Same payload: the chosen locale's `value`. `onSelect` is now a type error rather than the native text-selection event. |
+| `PageHeading` `badge` | prop | `themelia-react-ui/base/navigation` | `titleSuffix={<Badge tone="secondary">Beta</Badge>}` with `Badge` from `base/badge` | Same position, directly after the title on the title line. |
+| `PageHeading` `badges` | prop | `themelia-react-ui/base/navigation` | `titleSuffix` with one `Badge` per entry; wrap several in `<Stack direction="horizontal" gap="sm" wrap>` | The separate `page-header--badges` row is no longer rendered; status, count and version badges sit after the title. |
+| `PageHeading` `moreActionsLabel` | prop | `themelia-react-ui/base/navigation` | `strings={{ moreActions: '…' }}` | New `PageHeadingStrings` / `defaultPageHeadingStrings`. Same accessible name on the More actions trigger. |
+
+##### `base/action-menu`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `ActionMenu` `density="table"` (`ActionMenuDensity` member `'table'`) | value | `themelia-react-ui/base/action-menu` | `density="compact"` | `table` gave menu rows a `min-height` one step below compact; the popup already rendered compact rows for it. |
+
+##### `primitives`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `formatFileSize(value, 'en-US')` (locale as a string second argument) | value | `themelia-react-ui/primitives` | `formatFileSize(value, { locale: 'en-US' })` | The second argument is `FileSizeFormatOptions` only: `{ from, locale, unitLabels }`. |
+
+##### `services/actions`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `toPageAction` | export | `themelia-react-ui/services/actions` | `toButtonAction` for `ActionButtons`; `toPageHeaderAction` for a page header's `primaryAction` and `secondaryActions` | Renamed: it adapted a resolved action for the removed `PageActions` ribbon. The returned shape is unchanged. |
+
+##### `base/forms-numeric`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `DimensionsInput` `widthLabel` | prop | `themelia-react-ui/base/forms-numeric` | `strings={{ width: '…' }}` | |
+| `DimensionsInput` `heightLabel` | prop | `themelia-react-ui/base/forms-numeric` | `strings={{ height: '…' }}` | |
+| `DimensionsInput` `depthLabel` | prop | `themelia-react-ui/base/forms-numeric` | `strings={{ depth: '…' }}` | |
+| `DimensionsInput` `unitLabel` | prop | `themelia-react-ui/base/forms-numeric` | `strings={{ unitLabel: '…' }}` | New string key, empty by default. As before, a non-empty value shows the unit sub-label in the vertical layout and names the unit selector. Same key as `WeightInput`. |
+| `DimensionsInput` `unitPlaceholder` | prop | `themelia-react-ui/base/forms-numeric` | `strings={{ unitPlaceholder: '…' }}` | New string key, empty by default; empty falls back to `strings.unit`, as before. |
+| `DimensionsInput` `widthPlaceholder` | prop | `themelia-react-ui/base/forms-numeric` | `strings={{ widthPlaceholder: '…' }}` | |
+| `DimensionsInput` `heightPlaceholder` | prop | `themelia-react-ui/base/forms-numeric` | `strings={{ heightPlaceholder: '…' }}` | |
+| `DimensionsInput` `depthPlaceholder` | prop | `themelia-react-ui/base/forms-numeric` | `strings={{ depthPlaceholder: '…' }}` | |
+
+##### `base/date-pickers`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `DatePicker` `enableYearDropdown` | prop | `themelia-react-ui/base/date-pickers` | `yearSelection={{ enabled: true }}` | Same dropdown caption; `fromYear`/`toYear` bound it. |
+
+#### Layouts and templates
+
+Every layout import path below is also re-exported from the aggregate
+`themelia-react-ui/layout`, so each removal applies to both paths.
+
+##### `layout/page`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `PageActions` | export (component) | `themelia-react-ui/layout/page` | Pass page commands as `primaryAction` and `secondaryActions` on `Page` `header` or `PageHeader`. For a row of commands that is not a page header, use `ActionButtons` (and `ActionMenu` for overflow) from `themelia-react-ui/base/action-menu`. | The header owns treatment, overflow and narrow-width collapse, so `display`, `breakpoint`, `maxInlineActions`, `renderAction` and per-action `placement` have no replacement. `display="auto"` is gone with it: PageHeader collapses commands into More actions below 40rem of its own width. |
+| `PageActionsProps` | type | `themelia-react-ui/layout/page` | `PageHeaderProps` (`primaryAction`, `secondaryActions`, `maxVisibleSecondaryActions`) | |
+| `PageAction` | type | `themelia-react-ui/layout/page` | `PageHeaderAction` | `tone`, `buttonStyle`, `size`, `group`, `placement` and `element` have no equivalent: a command states its role (`primaryAction`, an ordered secondary action, or `destructive: true`). `visible`, `disabled`, `loading`, `icon`, `href`, `target`, `rel`, `external` and `onClick` carry over. |
+| `PageActionsDisplay` | type | `themelia-react-ui/layout/page` | Nothing | Only typed `PageActions` `display`. |
+| `PageActionContext` | type | `themelia-react-ui/layout/page` | Nothing | Only typed `PageActions` `renderAction`. |
+| `PageActionsStrings` | type | `themelia-react-ui/layout/page` | `PageHeaderStrings` (`moreActions`) | |
+| `defaultPageActionsStrings` | export | `themelia-react-ui/layout/page` | `defaultPageHeaderStrings` | `menuLabel` becomes `moreActions`. |
+| `titleBadges` on `PageHeaderProps` (and `Page` `header`) | prop | `themelia-react-ui/layout/page` | `slots.titleSuffix` with `Badge` from `themelia-react-ui/base/badge`: `slots: { titleSuffix: <Badge tone="success">Paid</Badge> }`. Wrap several in `<Stack direction="horizontal" gap="sm" wrap>`. | A badge that set no `tone` rendered `secondary`; pass `tone="secondary"` to keep it. The `page-header--badges` wrapper is no longer rendered. |
+| `PageTitleBadge` | type | `themelia-react-ui/layout/page` (declared, not exported by name) | `BadgeProps` from `themelia-react-ui/base/badge` | Only typed `titleBadges`. |
+| `titleIcon` on `PageHeaderProps` | prop | `themelia-react-ui/layout/page` | Put the glyph in a React-node `title`, or in `slots.beforeTitle` / `slots.titleSuffix`. | Title icons were decorative by default; ordinary titles need none. The `page-header--title-icon` element is no longer rendered. |
+| `titleIconHref` on `PageHeaderProps` | prop | `themelia-react-ui/layout/page` | A link composed in a slot callback through its `renderLink` argument: `slots: { titleSuffix: ({ renderLink }) => renderLink({ href, children }) }`. | The `page-header--title-icon-link` element is no longer rendered. |
+| `onTitleIconClick` on `PageHeaderProps` | prop | `themelia-react-ui/layout/page` | A command: `primaryAction` or an entry in `secondaryActions`; or a control in `slots.actions`. | The `page-header--title-icon-button` element is no longer rendered. |
+| `titleIconLabel` on `PageHeaderProps` | prop | `themelia-react-ui/layout/page` | Nothing | Named the removed title-icon control. |
+| `titleIconClassName` on `PageHeaderProps` | prop | `themelia-react-ui/layout/page` | Nothing | Styled the removed title-icon control. |
+| `actions` on `PageHeaderProps` (and `Page` `header`) | prop | `themelia-react-ui/layout/page` | Controls that are not commands (a period select, a scope switcher): the `Page` `toolbar` prop. To add something beside the command row: `slots.actions` as a callback, `({ defaultContent }) => <>{control}{defaultContent}</>`. | With a callback the region is yours: the header no longer end-aligns it for you. `actions` on `AsideNavShell` and `WorkspaceRecordHeader` is unchanged. |
+| `back` on `PageHeaderSlots` | prop | `themelia-react-ui/layout/page` | `backHref` (a link through `renderLink`) or `onBack` (a button), with `strings.back` for its name. | A fully custom back control can go in `slots.beforeTitle`. |
+| `afterHeader` on `PageProps` | prop | `themelia-react-ui/layout/page` | `toolbar` | Same region and position; it was only read when `toolbar` was absent. |
+| `PageHeader` `backLabel` (and `Page` `header.backLabel`) | prop | `themelia-react-ui/layout/page` | `strings={{ back: '…' }}` (`header: { strings: { back: '…' } }` on `Page`) | Same accessible name on the back link or button. |
+| `PageHeader` `moreActionsLabel` | prop | `themelia-react-ui/layout/page` | `strings={{ moreActions: '…' }}` | — |
+| `PageHeaderTabs` `label` (`tabs.label`) | prop | `themelia-react-ui/layout/page` | `strings={{ sections: '…' }}` on the header | Names the tab list. `strings` sits beside `tabs`, not inside it. |
+| `PageHeaderTabs` `moreLabel` (`tabs.moreLabel`) | prop | `themelia-react-ui/layout/page` | `strings={{ moreSections: '…' }}` on the header | Names the More menu that holds tabs that do not fit. |
+| `Page` `slots.aside` | prop | `themelia-react-ui/layout/page` | `aside` | The slot only took precedence over the prop; same region. |
+| `Page` `slots.toolbar` | prop | `themelia-react-ui/layout/page` | `toolbar` | Same region, above the body and aside. |
+| `Page` `slots.empty` | prop | `themelia-react-ui/layout/page` | `emptySlot` | Same replacement of the default empty state. |
+
+##### `layout/settings`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `SettingsShell` | export (component) | `themelia-react-ui/layout/settings` | `AsideNavShell` | The same component under its one name; props, strings and the `aside-nav-shell--*` hooks are unchanged. |
+| `SettingsShellProps` | type | `themelia-react-ui/layout/settings` | `AsideNavShellProps` | |
+
+##### `layout/workspace`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `ariaLabel` on `WorkspaceLayoutProps` | prop | `themelia-react-ui/layout/workspace` | The native `aria-label` attribute | Same effect: it names the workspace as a group, or the content region when `mainAs="section"`. |
+| Rendered elements as `secondaryActions` on `WorkspaceRecordHeaderProps` | value | `themelia-react-ui/layout/workspace` | Command objects: `secondaryActions={[{ label: 'Preview', onClick }]}` (`readonly PageHeaderAction[]`). For controls that are not commands, use `actions`. | The prop type is now `readonly PageHeaderAction[]` only. The separate "Secondary actions" cluster is no longer rendered. |
+| `secondaryActionsLabel` in `WorkspaceRecordHeaderStrings` (and `defaultWorkspaceRecordHeaderStrings`) | string | `themelia-react-ui/layout/workspace` | Nothing | Named the removed element cluster. `actionsLabel` still names the `actions` cluster. |
+| `currentLabel` in `WorkspaceNavStrings` (and `defaultWorkspaceNavStrings`) | string | `themelia-react-ui/layout/workspace` | Nothing | The current entry carries `aria-current` (`page` on a link, `true` on a callback row), which assistive technology announces in the reader's language. Delete the key from any `strings` override. |
+
+##### `layout/sidebar`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `handle` as the identity of a `SidebarNavigationRailItem` | value | `themelia-react-ui/layout/sidebar` | `id` on every rail item | `id` is required. `value` and `onValueChange` on `SidebarNavigationRail` report it. An item that had only `handle` needs `id` set to the same string. |
+| `showBadges` on `AppSidebar`, `SidebarNavigation`, `SidebarGroupedNavigation`, `SidebarNavigationFooter` | prop | `themelia-react-ui/layout/sidebar` | Leave `badge` off the items and omit `liveBadges` | Counts come from the navigation data only. |
+| `AppSidebar` `logoClassName` | prop | `themelia-react-ui/layout/sidebar` | Style the node passed as `logo` / `collapsedLogo`; for the wrapper itself, compose `<SidebarLogo className="…" />` in `slots.header` | It only reached the wrapper around that node. No caller in the repository. |
+
+##### Templates
+
+The templates are source assets shipped in the package's `templates` folder,
+not an import entry.
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `UserPermissionsAdminTemplate` | export (alias) | `templates/index.ts` in `themelia-react-ui/templates` | `UserPermissionsTemplate` | Same component. |
+| `AnalyticsOperationsAdminTemplate` | export (alias) | `templates/index.ts` in `themelia-react-ui/templates` | `AnalyticsOperationsTemplate` | Same component. The props type in the template file keeps its name. |
+
+The templates themselves changed to the current API, so a copy taken from 2.x
+needs the same edits: `useLayoutSidebar` from
+`themelia-react-ui/layout/sidebar` replaces `useSidebar` from
+`themelia-react-ui/base/sidebar`; title badges are `Badge`s in
+`slots.titleSuffix`; the analytics period select moved from the header's
+`actions` to the Page `toolbar`.
+
+##### `layout/app-shell`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `TopbarSidebarLayout` / `AppLayout` `slots.logo`, `slots.sidebar`, `slots.sidebarTrigger`, `slots.headerActions` | prop | `themelia-react-ui/layout/app-shell` | The direct props `logo`, `sidebar`, `sidebarTrigger`, `headerActions` | `slots` keeps the regions with no direct prop: `header`, `headerStart`, `headerCenter`, `headerEnd`, `secondarySidebar`, `aside`. |
+| `SidebarInsetLayout` / `AppLayout` (`sidebar`, `inset`) `slots.sidebar`, `slots.sidebarTrigger` | prop | `themelia-react-ui/layout/app-shell` | `sidebar`, `sidebarTrigger` | `slots` keeps `toolbar`, `toolbarStart`, `toolbarEnd`, `secondarySidebar`, `aside`. |
+| `StackedLayout` / `AppLayout` (`stacked`) `slots.logo`, `slots.nav` | prop | `themelia-react-ui/layout/app-shell` | `logo`, `nav` | `slots` keeps `header`, `headerEnd`, `subheader`, `aside`. |
+| `slots.content` on all three shells | prop | `themelia-react-ui/layout/app-shell` | `children` | It only replaced `children`. |
+| `TopbarSidebarLayout` / `StackedLayout` `headerHeight` | prop | `themelia-react-ui/layout/app-shell` | `style={{ '--shell-header-height': '5rem' }}` | The prop only set this root on the shell. Set it at `:root` or a theme scope to size every shell. |
+| `TopbarSidebarLayout` / `SidebarInsetLayout` `sidebarWidth` | prop | `themelia-react-ui/layout/app-shell` | `style={{ '--shell-sidebar-width': '18rem' }}` | The prop only set this root on the shell. `secondarySidebarWidth` and `asideWidth` stay: no root sizes those regions alone. |
+
+##### `layout/auth`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `AuthShell` `socialDivider` | prop | `themelia-react-ui/layout/auth` | `strings={{ socialDivider: '…' }}` | Text only; the divider is a label between two rules. |
+| `AuthShell` `cardClassName`, `cardContentClassName`, `footerClassName` | prop | `themelia-react-ui/layout/auth` | `variant` for the card surface; style the content passed as `children`, `cardFooter` and `postCard` | They reached the card's own frame and inset and the row under the card. No caller in the repository. `AuthCard` keeps its class slots for a composed layout. |
+
+##### `layout/settings`, `layout/workspace`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `AsideNavShell` `moreActionsLabel` | prop | `themelia-react-ui/layout/settings` | `strings={{ moreActionsLabel: '…' }}` | Same accessible name. |
+| `WorkspaceRecordHeader` `moreActionsLabel` | prop | `themelia-react-ui/layout/workspace` | `strings={{ moreActionsLabel: '…' }}` | Same accessible name. |
+
+#### Blocks
+
+##### `blocks/data-display`
+
+The metadata names were re-exports of the base family.
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `MetadataList` | export | `themelia-react-ui/blocks/data-display` | `MetadataList` from `themelia-react-ui/base/metadata-list` | Same component; only the import path changes. |
+| `MetadataValue` | export | `themelia-react-ui/blocks/data-display` | `MetadataValue` from `themelia-react-ui/base/metadata-list` | Same component; only the import path changes. |
+| `MetadataDensity` | type | `themelia-react-ui/blocks/data-display` | `MetadataDensity` from `themelia-react-ui/base/metadata-list` | |
+| `MetadataInlineListItem` | type | `themelia-react-ui/blocks/data-display` | `MetadataInlineListItem` from `themelia-react-ui/base/metadata-list` | |
+| `MetadataLayout` | type | `themelia-react-ui/blocks/data-display` | `MetadataLayout` from `themelia-react-ui/base/metadata-list` | |
+| `MetadataListItem` | type | `themelia-react-ui/blocks/data-display` | `MetadataListItem` from `themelia-react-ui/base/metadata-list` | |
+| `MetadataListProps` | type | `themelia-react-ui/blocks/data-display` | `MetadataListProps` from `themelia-react-ui/base/metadata-list` | |
+| `MetadataValueDescriptor` | type | `themelia-react-ui/blocks/data-display` | `MetadataValueDescriptor` from `themelia-react-ui/base/metadata-list` | |
+| `MetadataValueKind` | type | `themelia-react-ui/blocks/data-display` | `MetadataValueKind` from `themelia-react-ui/base/metadata-list` | |
+| `MetadataValueProps` | type | `themelia-react-ui/blocks/data-display` | `MetadataValueProps` from `themelia-react-ui/base/metadata-list` | |
+
+##### `blocks/analytics` and `blocks/analytics/charts`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `Metric` prop `colorScheme` | prop | `themelia-react-ui/blocks/analytics/charts` | `tone` | Map the value: `default` → omit the prop (or `tone="neutral"`), `primary` → `primary`, `success` → `success`, `warning` → `warning`, `info` → `info`, `danger` → `destructive`. Without `tone`, bordered metrics stay neutral and the `colored` variant keeps primary progress, as before. |
+| `MetricGrid` prop `colorScheme` | prop | `themelia-react-ui/blocks/analytics/charts` | `tone` | Same value mapping as `Metric`. |
+| `MetricColorScheme` | type | `themelia-react-ui/blocks/analytics` and `themelia-react-ui/blocks/analytics/charts` | `SemanticTone` from `themelia-react-ui/component-vocabulary` | `danger` is spelled `destructive` in `SemanticTone`; `default` is `neutral`. |
+
+##### `blocks/commerce`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `CartSummary` | export | `themelia-react-ui/blocks/commerce` | `CartSummaryCard` | Alias of the same component. |
+| `CartSummaryProps` | type | `themelia-react-ui/blocks/commerce` | `CartSummaryCardProps` | Alias of the same type. |
+| `DiscountStack` | export | `themelia-react-ui/blocks/commerce` | `DiscountStackPreview` | Alias of the same component. |
+| `DiscountStackProps` | type | `themelia-react-ui/blocks/commerce` | `DiscountStackPreviewProps` | Alias of the same type. |
+| `RefundStatus` | export | `themelia-react-ui/blocks/commerce` | `RefundStatusCard` | Alias of the same component. |
+| `RefundStatusProps` | type | `themelia-react-ui/blocks/commerce` | `RefundStatusCardProps` | Alias of the same type. |
+| `PaymentMethodCard` | export | `themelia-react-ui/blocks/commerce` | `<PaymentMethod variant="row" … />` | It was `PaymentMethod` with `variant` defaulting to `row`. Pass `variant="row"` explicitly; an explicit `variant="card"` on the old name becomes plain `PaymentMethod`. |
+| `PaymentMethodCardProps` | type | `themelia-react-ui/blocks/commerce` | `PaymentMethodProps` | Alias of the same type. |
+| `Discount.type` | value | `themelia-react-ui/blocks/commerce` (`DiscountStackPreview` `discounts[]`) | `kind` | `kind` takes the same text (or a node). `badge` still draws it as a chip. The fallback row key is now the label and position. |
+| `CartLineItem.name` | value | `themelia-react-ui/blocks/commerce` (`CartSummaryCard` `items[]`) | `title` | `title` is now required. A line without any name used to show its `id`; pass the text you want. |
+| `CartLineItem.productTitle` | value | `themelia-react-ui/blocks/commerce` (`CartSummaryCard` `items[]`) | `title` | It used to win over `title` and `name` when several were set. |
+| `CartLineItem.imageUrl` | value | `themelia-react-ui/blocks/commerce` (`CartSummaryCard` `items[]`) | `imageSrc` | |
+| `CartLineItem.src` | value | `themelia-react-ui/blocks/commerce` (`CartSummaryCard` `items[]`) | `imageSrc` | |
+| `CartLineItem.url` | value | `themelia-react-ui/blocks/commerce` (`CartSummaryCard` `items[]`) | `imageSrc` | |
+| `InventorySectionMetric.tone` | value | `themelia-react-ui/blocks/commerce` | Nothing: delete it | It was never rendered. The title badge states the stock status. |
+| `OrderStatusStrings.statusLabel` | string | `themelia-react-ui/blocks/commerce` (`OrderStatusCard` `strings`) | Nothing: delete it | Not rendered; the title badge states the status (`strings.status`). |
+| `OrderStatusStrings.latestEvent` | string | `themelia-react-ui/blocks/commerce` (`OrderStatusCard` `strings`) | Nothing: delete it | Not rendered; the timeline lists the events. |
+| `OrderStatusStrings.currentStep` | string | `themelia-react-ui/blocks/commerce` (`OrderStatusCard` `strings`) | Nothing: delete it | Not rendered; the current step is marked with `aria-current`. Completed and upcoming steps use `completedStep` and `upcomingStep`. |
+| `LoyaltyPointsStrings.tier` | string | `themelia-react-ui/blocks/commerce` (`LoyaltyPoints` `strings`) | The `tier` prop | `<LoyaltyPoints tier="Gold" />`. No tier, no chip. |
+| `AddressCard` `name` | prop | `themelia-react-ui/blocks/commerce` | `address={{ name, … }}` | `address` is the exported `OrderAddress`, the shape `OrderCustomer` takes. `name` is optional there. |
+| `AddressCard` `line1` | prop | `themelia-react-ui/blocks/commerce` | `address={{ line1, … }}` | |
+| `AddressCard` `line2` | prop | `themelia-react-ui/blocks/commerce` | `address={{ line2, … }}` | |
+| `AddressCard` `city` | prop | `themelia-react-ui/blocks/commerce` | `address={{ city, … }}` | |
+| `AddressCard` `region` | prop | `themelia-react-ui/blocks/commerce` | `address={{ region, … }}` | |
+| `AddressCard` `postalCode` | prop | `themelia-react-ui/blocks/commerce` | `address={{ postalCode, … }}` | |
+| `AddressCard` `country` | prop | `themelia-react-ui/blocks/commerce` | `address={{ country, … }}` | |
+| `AddressCard` `phone` | prop | `themelia-react-ui/blocks/commerce` | `address={{ phone, … }}` | Still one click-to-call link under the lines. |
+
+##### `blocks/timelines`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `ChangelogTimelineStrings.title` | string | `themelia-react-ui/blocks/timelines` (`ChangelogTimeline` `strings`) | Nothing: delete it | Not rendered; the composing surface supplies the title. |
+| `MilestonesTimelineStrings.title` | string | `themelia-react-ui/blocks/timelines` (`MilestonesTimeline` `strings`) | Nothing: delete it | Not rendered; the composing surface supplies the title. |
+
+##### `blocks/ai`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `AiArtifactStrings.expandAria` | string | `themelia-react-ui/blocks/ai` (`AiArtifact` `strings`) | Nothing: delete it | Not rendered; the artifact header has no expand control. |
+| `AiSourcesStrings.title` | string | `themelia-react-ui/blocks/ai` (`AiSources` `strings`) | `formatTitle: (count) => string` | The `'{{count}} sources'` template becomes a function, for example `` formatTitle: (count) => `${count} fuentes` ``. The default writes "1 source" and "N sources". |
+
+#### Data features
+
+##### `features/table`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `DataTable` `enablePagination` | prop | `themelia-react-ui/features/table` | Delete the prop | It had no effect. The pagination footer renders when `pagination` reports more than one page. |
+| `DataTable` `manualPagination` | prop | `themelia-react-ui/features/table` | Delete the prop; pass `pagination` and `onPageChange` | It had no effect. The table never slices `data`; paging is always the app's. |
+| `DataTable` `debugMode` | prop | `themelia-react-ui/features/table` | Delete the prop | It had no effect. |
+| `DataTable` `initialState.pagination` | prop | `themelia-react-ui/features/table` | Delete the key; pass `pagination` | It had no effect. `initialState.sorting`, `rowSelection`, `columnVisibility` and `columnFilters` are unchanged. |
+| `DataTableHeader` `headerClassName` | prop | `themelia-react-ui/features/table` | `className` | Only on the standalone `DataTableHeader` part. `DataTable`'s own `headerClassName` slot prop is unchanged. |
+| `DataTable` `defaultSorting` | prop | `themelia-react-ui/features/table` | `initialState={{ sorting: [...] }}` | Same value, read once on mount. A controlled `sorting` prop still wins. |
+| `DataTable` `defaultColumnVisibility` | prop | `themelia-react-ui/features/table` | `initialState={{ columnVisibility: {...} }}` | Same value. With `storageKey`, `columnVisibilityPrecedence` now compares the stored value against `initialState.columnVisibility`. |
+| `DataTable` `enableFiltering` | prop | `themelia-react-ui/features/table` | `filterColumn` | Naming the column shows the search input and filters the loaded rows. Delete `enableFiltering`. Without `filterColumn` the table filters nothing itself, so `initialState.columnFilters` only takes effect once `filterColumn` is set. |
+| `DataTable` `filterPlaceholder` | prop | `themelia-react-ui/features/table` | `strings={{ filter: { searchPlaceholder: '…' } }}` | The same string also names the input for assistive technology. |
+| `DataTableFilterBar` `filterPlaceholder` | prop | `themelia-react-ui/features/table` | `strings.filter.searchPlaceholder` | `DataTableFilterBar` takes a complete `DataTableStrings` object: spread `defaultDataTableStrings` and override `filter.searchPlaceholder`. |
+| `DataTable` `emptyStateMessage` | prop | `themelia-react-ui/features/table` | `strings={{ emptyState: { message: '…' } }}` | `emptyStateAction` is unchanged. In `DataView`, pass it inside `table={{ strings: { emptyState: { message } } }}`. |
+| `DataTableBody` `emptyStateMessage` | prop | `themelia-react-ui/features/table` | `strings.emptyState.message` | Only for apps that compose `DataTableBody` themselves. |
+| `DataTable` `rowActionsMenuLabel` as a string | value | `themelia-react-ui/features/table` | `strings={{ actions: { menuLabel: '…' } }}` | The function form stays: `rowActionsMenuLabel={(row) => \`Actions for ${row.name}\`}` names each row's menu from its record, which a single string cannot. |
+| `DataTable` `enableSubRowSelection` | prop | `themelia-react-ui/features/table` | Delete the prop | `DataTable` has no sub-row or expansion props, so nothing acted on it. |
+
+##### `features/filters`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `FilterStrings.calendar.dateSelected` | string | `themelia-react-ui/features/filters` | Delete the key | No reader. A complete `FilterStrings` object that still sets it is a type error. |
+| `FilterStrings.calendar.selectedEndDate` | string | `themelia-react-ui/features/filters` | Delete the key | No reader. |
+| `FilterStrings.calendar.customRange` | string | `themelia-react-ui/features/filters` | Delete the key | No reader. |
+| `FilterConfig.datePickerConfig.fullWidth` | prop | `themelia-react-ui/features/filters` | Delete the key | It had no effect; the date editor always fills its region. |
+| `FilterOperatorSelect` `segmentResetClass` | prop | `themelia-react-ui/features/filters` | `segmentResetClassName` | Same value, new name. |
+| RANGE filter: a single query value read as an exact match | value | `themelia-react-ui/features/filters` (`parseFiltersFromQuery`) | Send both bounds (`?price=150&price=150`), or add the operator (`?price=150&price__op=equals`) | `?price=150` on a RANGE filter with no configured operator used to parse as `{ operator: 'equals', value: ['150', '150'] }`. It now parses as the lower bound of the filter's own operator: `{ operator: 'between', value: ['150', ''] }`. Saved URLs with one bare value change meaning. |
+
+##### `features/combobox`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `Combobox` `selectedValue` | prop | `themelia-react-ui/features/combobox` | `value` | Same type (`T \| null`). `defaultValue` seeds an uncontrolled field. |
+| `Combobox` `onSelectedValueChange` | prop | `themelia-react-ui/features/combobox` | `onValueChange` | Same signature. |
+| `MultiCombobox` `selectedValues` | prop | `themelia-react-ui/features/combobox` | `values` | Same type (`T[]`). `defaultValues` seeds an uncontrolled field. |
+| `MultiCombobox` `onSelectedValuesChange` | prop | `themelia-react-ui/features/combobox` | `onValuesChange` | Same signature. With `applyButton` it still fires on Apply only. |
+| `AsyncResourceCombobox` `hasMore` | prop | `themelia-react-ui/features/combobox` | Raise `limit`; or use `Combobox` with your own `items`, `hasMore` and `onLoadMore` | The component owns its list and replaces it on each request, so a page could never be appended. |
+| `AsyncResourceCombobox` `onLoadMore` | prop | `themelia-react-ui/features/combobox` | As for `hasMore`: raise `limit`; or use `Combobox` with your own `items`, `hasMore` and `onLoadMore` | |
+| `AsyncResourceCombobox` `loadingMore` | prop | `themelia-react-ui/features/combobox` | As for `hasMore`: raise `limit`; or use `Combobox` with your own `items`, `hasMore` and `onLoadMore` | `Combobox` and `MultiCombobox` keep all three props. |
+| `Combobox` / `AsyncResourceCombobox` `closeOnSelect` | prop | `themelia-react-ui/features/combobox` | Delete the prop | The single combobox never read it; it always closes on selection. `MultiCombobox` keeps `closeOnSelect`. |
+| `Combobox` / `AsyncResourceCombobox` `applyButton`, `onApply`, `onCancel` | prop | `themelia-react-ui/features/combobox` | Delete the props | Only `MultiCombobox` renders the Apply and Cancel footer; the props are now on `MultiComboboxProps` only. |
+| `MultiCombobox` `clearable` | prop | `themelia-react-ui/features/combobox` | Delete the prop | `MultiCombobox` ignored it; each chip has its own remove control. `Combobox` and `AsyncResourceCombobox` keep `clearable`. |
+| `Combobox` / `MultiCombobox` `showListContent` | prop | `themelia-react-ui/features/combobox` | Nothing for the components; `useComboboxCore({ showListContent })` for a headless build | It was a seam for this package's async wrappers. `AsyncResourceCombobox` and `SuggestionsCombobox` still use it internally. |
+| `closeOnSelect`, `applyButton`, `onApply`, `onCancel`, `clearable`, `showListContent` on `ComboboxSharedProps` | type | `themelia-react-ui/features/combobox` | `MultiComboboxProps` for the first four, `ComboboxProps` for `clearable`, `ComboboxListControl` for `showListContent` | `ComboboxSharedProps` now holds only what both components and the headless hook share. `UseComboboxCoreOptions` extends `ComboboxSharedProps` and the new `ComboboxListControl`. |
+
+##### `features/questionnaire`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `Questionnaire` `onQuestionChange` | prop | `themelia-react-ui/features/questionnaire` | `onQuestionIdChange` | Same signature (`(id: string) => void`). |
+
+##### `features/products`
+
+The eight overview regions and the two row menus are no longer exported;
+`ProductOverview` and the variant and option surfaces render them. Their props
+types (`ProductDetailsCardProps`, `ProductVariantActionMenuStrings` and so on)
+are still exported, because the public props are typed with them.
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `ProductContractOverview` | export | `themelia-react-ui/features/products` | `<ProductOverview contract={…} />` | Pass the same props object. Add custom content through `ProductOverview` `slots`. |
+| `ProductDetailsCard` | export | `themelia-react-ui/features/products` | `<ProductOverview details={…} />` | |
+| `ProductOperationsCard` | export | `themelia-react-ui/features/products` | `<ProductOverview operations={…} />` | |
+| `ProductOptionsSummary` | export | `themelia-react-ui/features/products` | `<ProductOverview options={…} />` | |
+| `ProductPoliciesCard` | export | `themelia-react-ui/features/products` | `<ProductOverview policies={…} />` | |
+| `ProductQuotePreviewCard` | export | `themelia-react-ui/features/products` | `<ProductOverview quote={…} />` | |
+| `ProductReadinessCard` | export | `themelia-react-ui/features/products` | `<ProductOverview readiness={…} />` | |
+| `ProductStructureCard` | export | `themelia-react-ui/features/products` | `<ProductOverview structure={…} />` | |
+| `ProductOptionActionMenu` | export | `themelia-react-ui/features/products` | `renderOptionActions` on `ProductOptionsMatrix`, or on `ProductOverview` `options`, composing `ActionMenu` from `themelia-react-ui/base/action-menu` | The default menu still renders when `renderOptionActions` is not set. |
+| `ProductVariantActionMenu` | export | `themelia-react-ui/features/products` | `renderVariantActions` on `ProductVariantsTable`, `ProductVariantsBulkTable`, `ProductVariantsManager` or `ProductVariantDetails`, composing `ActionMenu` from `themelia-react-ui/base/action-menu` | The default menu still renders when `renderVariantActions` is not set. |
+| `ProductVariantOptionField.value` | prop | `themelia-react-ui/features/products` | `defaultValue.options` or `value.options` on `ProductVariantEditor` | `optionFields={[{ id: 'size', label: 'Size', value: 'M' }]}` becomes `optionFields={[{ id: 'size', label: 'Size' }]}` with `defaultValue={{ options: { size: 'M' } }}`. The field value is no longer added to the submitted value. |
+
+##### `features/resource`
+
+Route shells are `Page` from `themelia-react-ui/layout/page`. The family keeps
+`ResourceActionBar`, `ResourceDetailsSection` and `ResourceEmptyState`.
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `ResourceHeader` | export | `themelia-react-ui/features/resource` | `Page` `header` (`PageHeaderProps`), or `PageHeader` for an embedded header, from `themelia-react-ui/layout/page` | `title`, `description`, `primaryAction`, `secondaryActions`, `maxVisibleSecondaryActions`, `moreActionsLabel` keep their names. `badges` moves to `header.slots.titleSuffix`; `metadata` to `header.slots.afterDescription`; `eyebrow` to `header.slots.beforeTitle`. |
+| `ResourceIndexShell` | export | `themelia-react-ui/features/resource` | `Page` from `themelia-react-ui/layout/page` | `title`, `description` and commands move into `header`. `toolbar`, `loading`, `error`, `onRetry`, `emptySlot` and `slots.loading` / `empty` / `error` have the same names on `Page`. |
+| `ResourceShowShell` | export | `themelia-react-ui/features/resource` | `Page` from `themelia-react-ui/layout/page` with `aside` | `slots.aside` becomes the `aside` prop. |
+| `TabbedResourceShell` | export | `themelia-react-ui/features/resource` | `Page` from `themelia-react-ui/layout/page` with `header.tabs` | `tabs`, `activeTab`, `defaultActiveTab` and `onTabChange` move into `header.tabs`; check `PageHeaderTabs` for the exact field names. |
+| `ResourceHeaderProps` | type | `themelia-react-ui/features/resource` | `PageHeaderProps` from `themelia-react-ui/layout/page` | |
+| `ResourceIndexShellProps` | type | `themelia-react-ui/features/resource` | `PageProps` from `themelia-react-ui/layout/page` | |
+| `ResourceShowShellProps` | type | `themelia-react-ui/features/resource` | `PageProps` from `themelia-react-ui/layout/page` | |
+| `TabbedResourceShellProps` | type | `themelia-react-ui/features/resource` | `PageProps` from `themelia-react-ui/layout/page` with `PageHeaderTabs` | |
+| `ResourceHeaderCommandProps` | type | `themelia-react-ui/features/resource` | The command fields of `PageHeaderProps` | Existed only for the removed header and shells. |
+| `ResourceShellSlots` | type | `themelia-react-ui/features/resource` | `PageSlots` from `themelia-react-ui/layout/page` | Existed only for the removed shells. |
+| `defaultResourceStrings` | export | `themelia-react-ui/features/resource` | `Page` `strings` | Loading, empty, error, retry and tab copy now belongs to `Page`. |
+| `ResourceStrings` | type | `themelia-react-ui/features/resource` | `PageStrings` from `themelia-react-ui/layout/page` | |
+| `ResourceEmptyState` `ariaLabel` | prop | `themelia-react-ui/features/resource` | `aria-label` | Same value, native attribute name. |
+
+##### `features/resource-assignment`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `SharedResourceCardStrings.changeAction` | string | `themelia-react-ui/features/resource-assignment` | `assignAction` for the empty-state action; `selector.actionLabel` for the action on an assigned resource | An overridden `changeAction` used to name the empty-state action when `assignAction` was not set. That fallback is gone, and nothing else read the key. |
+
+##### `features/sync`
+
+The `themelia-react-ui/features/sync` entry no longer exists.
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `SyncRangeDialogForm` | export | `themelia-react-ui/features/sync` | `SchemaForm` from `themelia-react-ui/features/schema-form`, with a `radio-cards` field for the window and a `checkbox-cards` field for the options | Map the values in `onSubmit`, for example `{ hours: Number(values.hours), options: values.options }`. Wrap it in `ActionDialog` for a dialog. The schema-form catalogue page has the full schema. |
+| `SyncRangeDialogFormProps` | type | `themelia-react-ui/features/sync` | `SchemaFormProps` from `themelia-react-ui/features/schema-form` | |
+| `SyncRangeDialogFormSubmit` | type | `themelia-react-ui/features/sync` | Your own payload type, built in `onSubmit` | |
+| `SyncRangeDialogFormValues` | type | `themelia-react-ui/features/sync` | `SchemaFormValues` from `themelia-react-ui/features/schema-form` | |
+| `defaultSyncRangeDialogFormStrings` | export | `themelia-react-ui/features/sync` | Labels and descriptions on the `SchemaForm` field definitions | |
+| `SyncRangeDialogFormStrings` | type | `themelia-react-ui/features/sync` | Labels and descriptions on the `SchemaForm` field definitions | |
+
+##### `features/schema-form`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `SchemaForm` `submitLabel` | prop | `themelia-react-ui/features/schema-form` | `strings={{ submitLabel: '…' }}` | Same key name inside `strings`. |
+| `SchemaForm` `resetLabel` | prop | `themelia-react-ui/features/schema-form` | `strings={{ resetLabel: '…' }}` | Same key name inside `strings`. |
+
+#### Content features
+
+Type-level effect of the string removals: a dictionary typed as the full
+strings interface (not `strings={{ … }}` inline) that still carries a removed
+key fails to compile with an excess-property error. Delete the key.
+
+##### `features/overlays`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `defaultAlertDialogStrings` | export | `themelia-react-ui/features/overlays` | `defaultConfirmDialogStrings` | Same object, renamed to the `default<Component>Strings` convention. |
+| `ConfirmDialogProps.closeOnBackdropClick` | prop | `themelia-react-ui/features/overlays` | Nothing; delete the prop | It never had an effect: a confirmation ignores outside presses. Passing it is now a type error. `ActionDialog` and `ActionDrawer` keep it. |
+| `ConfirmDialogProps.showCloseButton` | prop | `themelia-react-ui/features/overlays` | Nothing; delete the prop | It never had an effect: a confirmation has no corner close control. `ActionDialog` and `ActionDrawer` keep it. |
+
+##### `features/mentions`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `splitHtmlByMentions` | export | `themelia-react-ui/features/mentions` | `MentionContent` to render HTML with mentions; `parseMentionsFromHtml` to read the mentions out of HTML | The splitter cut serialized HTML with a regex and broke paragraphs and lists around a mention. `MentionContent` renders the sanitized tree and keeps each chip inside its paragraph. |
+| `MentionHtmlSegment` | type | `themelia-react-ui/features/mentions` | Nothing | Return type of `splitHtmlByMentions`. |
+
+##### `features/comments`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `CommentData.content_type` (snake case, read as a fallback) | value | `themelia-react-ui/features/comments` | `contentType` | The field was never in the type; it was read at runtime when `contentType` was absent. A comment that only sets `content_type` now renders as plain text. Map it when you build `CommentData`. Also applies to comments passed to `ActivityLog`. |
+| `CommentsProps.avatarComponent` (declared on `CommentsSlots`) | prop | `themelia-react-ui/features/comments` | Nothing; for a custom avatar use `renderItem` | Declared but never read: it had no effect. |
+| `CommentsStrings.moreActionsLabel` | string | `themelia-react-ui/features/comments` | Nothing; delete the key | Never rendered. |
+| `CommentsStrings.showRepliesLabel` | string | `themelia-react-ui/features/comments` | Nothing; delete the key | Never rendered. |
+| `CommentsStrings.hideRepliesLabel` | string | `themelia-react-ui/features/comments` | Nothing; delete the key | Never rendered. |
+| `CommentsProps.maxAttachments` | prop | `themelia-react-ui/features/comments` | `attachments={{ onUpload, maxFiles: n }}` | Same cap on the draft. The default stays 5 when `maxFiles` is unset. `attachments.maxFiles` already won when both were set. |
+| `CommentsProps.allowAttachments` | prop | `themelia-react-ui/features/comments` | `attachments={{ onUpload, disabled: true }}` to turn uploads off; nothing to turn them on | The attach control only ever appeared with `attachments.onUpload`; `allowAttachments={false}` did what `attachments.disabled` does. Without `attachments` there is no control, so a read-only thread just drops the prop. |
+| `CommentComposerProps.maxAttachments` | prop | `themelia-react-ui/features/comments` | `attachments={{ onUpload, maxFiles: n }}` | Same as on `Comments`. |
+| `CommentComposerProps.allowAttachments` | prop | `themelia-react-ui/features/comments` | `attachments={{ onUpload, disabled: true }}` | Same as on `Comments`. |
+| `CommentsProps.bare` | prop | `themelia-react-ui/features/comments` | `title={false}` | Renders the thread with no heading. Two differences from `bare`, both intended: the root `section` (`comments--component`, `className`) stays around the thread, and the delete confirmation works (with `bare` the confirmation dialog was never mounted, so a confirmed delete did nothing unless `confirmDelete={false}`). |
+
+##### `features/activities`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `ActivityLogProps.avatarComponent` | prop | `themelia-react-ui/features/activities` | Nothing; for custom rows use `renderers` | Declared but never read: it had no effect. |
+| `ActivityRowProps.moreLabel` | prop | `themelia-react-ui/features/activities` | Nothing; delete the prop | It was a required prop with no effect since collapsed rows stopped previewing metadata. Code that renders `ActivityRow` directly must stop passing it. |
+| `ActivitiesStrings.moreLabel` | string | `themelia-react-ui/features/activities` | Nothing; delete the key | Fed the `ActivityRowProps.moreLabel` prop. Applies to `ActivityFeed strings` and `ActivityLog activityStrings`. |
+| `ActivityLogProps.bare` | prop | `themelia-react-ui/features/activities` | `title={false}` | Renders the log with no heading, for a log inside a titled Card or section. The root `section` (`activity-log--component`, `data-slot="activity-log"`) now stays around the feed, and `className` lands on that section instead of on the feed. A missing `title` still shows `activityStrings.title` ("Activity"), as before. With `bare`, a `title` passed alongside was ignored; remove it or keep it and drop `title={false}`. |
+| `ActivityRowProps.youLabel` | prop | `themelia-react-ui/features/activities` | `strings={{ you: '…' }}` | One optional `strings` prop (`StringsProp<ActivitiesStrings>`) replaces the four label props; unset keys take the `defaultActivitiesStrings` values. |
+| `ActivityRowProps.showChangesLabel` | prop | `themelia-react-ui/features/activities` | `strings={{ showChanges: '…' }}` | As above. |
+| `ActivityRowProps.hideChangesLabel` | prop | `themelia-react-ui/features/activities` | `strings={{ hideChanges: '…' }}` | As above. |
+| `ActivityRowProps.actionsLabel` | prop | `themelia-react-ui/features/activities` | `strings={{ actionsLabel: '…' }}` | As above. All four were required; code that renders `ActivityRow` directly can now omit them. `ActivityFeed` and `ActivityLog` callers are unaffected: they already pass `strings` / `activityStrings`. |
+
+##### `features/email-composer`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `EmailComposerProps.onChange` | prop | `themelia-react-ui/features/email-composer` | `onValueChange` | Same payload (a detached draft proposal). `onChange` was only called when `onValueChange` was missing. |
+
+##### `features/appointment-calendar`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `AppointmentCalendarProps.onStaffChange` | prop | `themelia-react-ui/features/appointment-calendar` | `onStaffIdChange` | Same payload (the staff id, or `'all'`). |
+
+##### `features/ai-chat`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `AiChatPromptInputStrings.modelPickerAria` | string | `themelia-react-ui/features/ai-chat` | Nothing; delete the key | Never rendered: the prompt has no model picker. Applies to `AiChat strings.prompt` too. |
+
+##### `features/media-library`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `MediaLibraryStrings.privateLabel` | string | `themelia-react-ui/features/media-library` | Nothing; delete the key | Never rendered. Visibility copy is `strings.detail.*` and `strings.upload.*`. |
+| `MediaLibraryStrings.publicLabel` | string | `themelia-react-ui/features/media-library` | Nothing; delete the key | Never rendered. |
+| `MediaLibraryState.error` (returned by `useMediaLibrary`) | value | `themelia-react-ui/features/media-library` | `loadError` for a failed fetch, `mutationError` for a failed update or delete (`{ itemId, operation, cause }`), `uploadError` for a failed upload request, `loadMoreError` for a failed next page | The single field mixed every failure. The `MediaLibrary` component already used the specific fields. |
+
+##### `features/theme-tweaker`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `ThemeTweakerStrings.groupNavigationTitle` | string | `themelia-react-ui/features/theme-tweaker` | Nothing; delete the key | Never rendered. |
+| `ThemeTweakerStrings.groupNavigationDescription` | string | `themelia-react-ui/features/theme-tweaker` | Nothing; delete the key | Never rendered. |
+| `ThemeTweakerStrings.copyOverrides` | string | `themelia-react-ui/features/theme-tweaker` | Nothing; delete the key | Never rendered: the export dialog has one CSS output. |
+| `ThemeTweakerStrings.exportProvider` | string | `themelia-react-ui/features/theme-tweaker` | Nothing; delete the key | Never rendered. |
+| `ThemeTweakerStrings.exportOptions` | string | `themelia-react-ui/features/theme-tweaker` | Nothing; delete the key | Never rendered. |
+| `ThemeTweakerStrings.overrideOutputLabel` | string | `themelia-react-ui/features/theme-tweaker` | Nothing; delete the key | Never rendered. |
+| `ThemeTweakerStrings.overrideOutputDescription` | string | `themelia-react-ui/features/theme-tweaker` | Nothing; delete the key | Never rendered. |
+
+##### `features/event-calendar`
+
+| Removed | Kind | Import path | Use instead | Notes |
+| --- | --- | --- | --- | --- |
+| `EventCalendarProps.emptyStateMessage` | prop | `themelia-react-ui/features/event-calendar` | `strings={{ emptyState: '…' }}` | New optional key `EventCalendarStrings.emptyState`. Same behaviour: it is opt-in (no default), and when set it replaces the day grid while the visible period has no events after the category and runtime filters. Merge it into an existing `strings` object rather than passing `strings` twice. |
+
+### Composition form
+
+There is one composition form: `render`. Every part below took `asChild` and
+rendered its single child in place of its own element. Pass that element to
+`render` instead.
+
+```tsx
+// 2.x
+<PopoverTrigger asChild>
+  <Button>Open</Button>
+</PopoverTrigger>
+
+// 3.0
+<PopoverTrigger render={<Button>Open</Button>} />
+```
+
+A function form is also accepted where the part is a Base UI primitive:
+`render={(props) => <Button {...props}>Open</Button>}`. The Command parts take
+an element in `render` and keep their content as `children`, for example
+`<CommandList render={<ul />}>{items}</CommandList>`.
+
+`asChild` is removed from these parts:
+
+- `themelia-react-ui/base/display`: `TooltipTrigger`, `CollapsibleTrigger`
+- `themelia-react-ui/base/popover`: `PopoverTrigger`, `PopoverAnchor`
+- `themelia-react-ui/base/command`: `Command`, `CommandInput`, `CommandList`,
+  `CommandGroup`, `CommandItem`, `CommandSeparator`
+
+`CollapsibleTrigger` and `PopoverTrigger` now infer `nativeButton` from the
+`render` element: a `button`, or a component without `href`, is native. Pass
+`nativeButton` to override. The per-part replacement element and notes are in
+the [`base/display`](#basedisplay), [`base/popover`](#basepopover) and
+[`base/command`](#basecommand) tables.
+
+### Changed behaviour
+
+Some behaviour changed without an API change: value formatting, focus and
+keyboard handling, default copy, ARIA roles and shared geometry. These are
+listed under "Changed behaviour" in the 3.0.0 entry of the
+[changelog](CHANGELOG.md#changed-behaviour). Review that list after the code
+compiles, and check tests that match rendered text, roles or element names.
+
+Three changes follow from the removed props:
+
+- **Card footers.** `footerText` is gone, so a string or number passed to
+  `footerSlot` renders as the footnote (small, secondary, end-aligned); a node
+  still fills the footer width. OrderTimeline, StepsCard and
+  SharedResourceCard keep their own `footerText`: a string renders as before,
+  a node now fills the width.
+- **ActivityLog without a title.** `title={false}` drops the heading and keeps
+  the root section, so `className` lands on the section rather than on the
+  feed.
+- **DataTable search.** The built-in search input appears when `filterColumn`
+  is set. `initialState.columnFilters` without `filterColumn` no longer
+  filters invisibly.
+
+## From admin-ui-starter-kit 3.x
+
+The `themelia-react-ui` 2.x line is the migration destination for
+`admin-ui-starter-kit` 3.x applications. This section describes that move and
+was written for 2.x. When you install 3.0, the names it calls deprecated
+(`SmartCard`, `ContentBlock`, base `Sheet`, the resource shells and the sync
+form) no longer exist: use their replacements directly, then follow
+[Upgrading from 2.x to 3.0](#upgrading-from-2x-to-30).
+
+### Imports and installation
+
+1. Use the [consumer setup](README.md#consumer-setup) to install the new package
+   and its required peers. React and React DOM use 19.x, Lucide uses 1.x, and
+   `@base-ui/react` is required. The old `cmdk`, Tailwind, Tailwind Vite plugin,
+   `tw-animate-css` and Inter font peers can be removed if the application has
+   no independent use for them. Keep the optional peers used by your families.
+2. Replace `admin-ui-starter-kit/<family>` with `themelia-react-ui/<family>`.
+   For `composed/admin`, `ai`, `analytics`, `commerce`, `data-display`,
+   `onboarding` and `timelines`, use `themelia-react-ui/blocks/<family>`.
+   For example, `admin-ui-starter-kit/composed/commerce` becomes
+   `themelia-react-ui/blocks/commerce`. Move CommonJS `require()` consumers to
+   ESM imports or asynchronous `import()`.
+3. Import `themelia-react-ui/style.css` once. Add
+   `themelia-react-ui/features/map/style.css` when using the map family.
+   The [theme guide](docs/consumer-skill/references/theming.md) covers the
+   optional green brand, structural roots and scoped portals.
+
+#### Host CSS
+
+The compiled stylesheet leaves global preflight and the page canvas to the app.
+If the previous stylesheet supplied these values, put them in your app's lower
+priority base layer. Keep an app-owned reset for native margins, lists and form
+controls where you used Tailwind preflight.
+
+```css
+@layer base {
+  * {
+    border-color: var(--border);
+    outline-color: color-mix(in oklab, var(--ring) 50%, transparent);
+  }
+  html { font-family: var(--font-sans); }
+  body { background-color: var(--background); color: var(--foreground); }
+  code, kbd, samp, pre { font-family: var(--font-mono); }
+}
+```
+
+For app-generated Tailwind utilities, follow the [Tailwind setup](docs/consumer-skill/references/installation.md).
+The editable `theme.css` entry is processed by the application's Tailwind v4
+build. The compiled `style.css` already includes package utilities.
+
+#### Tools
+
+| Former bin | Workflow in this package |
+| --- | --- |
+| `admin-ui-starter-kit-audit` | Run `node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs src`. Pass explicit file or directory paths. Its output is JSON. Replace the old `--fix` and `--strict` automation with your own review or CI step. |
+| `admin-ui-starter-kit-install-skill` | Use the shipped `setup-skills.mjs --copy` or `--check` commands in the [installed setup guide](docs/consumer-skill/references/installation.md). |
+| `admin-ui-starter-kit-publish-theme` | Import the published theme CSS or export a custom theme from Theme Studio and apply it in the app. |
+| `admin-ui-starter-kit-showcase` | Use the component catalogue or render the shipped examples in your application. |
+
+### Defaults to review
+
+| Owner | Earlier default | Current default or migration |
+| --- | --- | --- |
+| Untoned Button | Primary solid | Secondary outline. Set provider button defaults or make the primary command explicit. |
+| Badge | Primary | Neutral. Set an explicit status tone where relevant. |
+| Card and SmartCard | Framed, footer divider off | Card surface, header divider off, footer divider on. Explicit props win over provider booleans. |
+| PageHeader | `h3` | `h1` for route titles. Use `headingTag="h3"` when the page already owns its heading, or supply a custom title element. |
+| PageHeading | Separator on | Pass `withSeparator` to restore it. |
+| ConfirmDialog | Start-aligned with an icon | Centered. Set `overlay.defaultConfirmAlign: 'start'` and pass `showIcon` on dialogs that need the icon. |
+| DateCell and DateMetaCell | Icon on | Pass `showIcon` for the date glyph. |
+| LoyaltyPoints | Warning tier | Neutral. Set `tierTone="warning"` where it conveys meaning. |
+| Command | Default inset | Compact. Pass `inset="default"` for the wider inset. |
+| Page | Large measure, no inset | Owns page gutters and block inset. Use explicit `maxWidth="lg"`, `gutter="none"` and `padding="none"` inside a shell that supplies them. |
+| DataTable | Inline selection bar | Floating selection bar. Use `selectionToolbarPlacement="inline"` for inline placement. |
+| MediaLibrary | Activation selects | Activation opens details. Use `defaultSelecting` to start in selection mode. |
+| Metric money and signed values | Prefix currency code and ASCII hyphen | Default output can place the currency code after the amount and use the Unicode minus. Review text matching in tests. |
+| Date range presets | Title case | Sentence case, such as “This week” and “Last 30 days”. |
+
+To keep the earlier button, badge and card choices while moving the
+imports, supply the old defaults explicitly.
+
+```tsx
+import { UIProvider } from 'themelia-react-ui/ui-provider';
+
+<UIProvider config={{
+  button: { defaultTone: 'primary', defaultButtonStyle: 'solid' },
+  badge: { defaultTone: 'primary' },
+  card: { defaultSurface: 'framed', defaultHeaderDivider: false, defaultFooterDivider: false },
+  overlay: { defaultConfirmAlign: 'start' },
+}}>
+  <App />
+</UIProvider>
+```
+
+### Behavior, selectors and deprecated entry points
+
+- Check the query policy of async filters. Options are cached within a mounted
+  editor and refetch after a remount. Chip labels stay within their filter
+  provider. Reuse stable fetcher and mapper references. If the app needs caching
+  across editor mounts, keep it inside an app-owned fetcher keyed by the complete
+  query and authorization scope.
+- For selectors targeting legacy ContentBlock element hooks, move styling and
+  queries to the owning Card regions, slots and accessible names. The
+  ContentBlock adapter keeps its root, header, content and footer hooks.
+  DataTable still exposes the selection-toolbar root class, and
+  `batch-action-bar--summary` and `batch-action-bar--actions` identify the new
+  bar regions. Query the actual status or action for ShipmentTracking and
+  product option rows whose decorative dot and drag hooks were removed.
+  Tree owns AiFileTree rows through `tree--item` and `tree--group`.
+- For new code, use Card in place of SmartCard and ContentBlock,
+  `ActionDrawer` from `features/overlays` in place of base Sheet,
+  `Page` from `layout/page` in place of the resource shell, and
+  `SchemaForm` from `features/schema-form` for the sync form. Pass standalone
+  product-card content to `ProductOverview` through its typed region props.
+- Check Command compositions that used inherited cmdk props. Base UI owns
+  Command's keyboard and filtering behavior. Supply an explicit `filter`
+  for application-specific ranking and use the current public parts when
+  composing empty and group content.
+
+## Chart blocks moved
+
+`recharts` is an optional peer. The analytics blocks that draw with it now
+have their own exact entry, so `themelia-react-ui/blocks/analytics` no longer
+loads it. Change the import path of each moved symbol; names, props and
+behaviour are unchanged. `Metric`, `MetricBar` and `MetricGrid` move with the
+chart blocks because every `Metric` can draw a sparkline.
+
+| Symbol | Before | After |
+| --- | --- | --- |
+| `Metric`, `MetricProps` | `themelia-react-ui/blocks/analytics` | `themelia-react-ui/blocks/analytics/charts` |
+| `MetricBar`, `MetricBarProps`, `MetricBarVariant` | `themelia-react-ui/blocks/analytics` | `themelia-react-ui/blocks/analytics/charts` |
+| `MetricGrid`, `MetricGridProps` | `themelia-react-ui/blocks/analytics` | `themelia-react-ui/blocks/analytics/charts` |
+| `MetricMicroGrid`, `MetricMicroGridProps`, `MicroChartKind`, `MicroMetricCell` | `themelia-react-ui/blocks/analytics` | `themelia-react-ui/blocks/analytics/charts` |
+| `MetricGradient`, `MetricGradientProps`, `MetricGradientTheme` | `themelia-react-ui/blocks/analytics` | `themelia-react-ui/blocks/analytics/charts` |
+| `MetricSparkline`, `MetricSparklineProps` | `themelia-react-ui/blocks/analytics` | `themelia-react-ui/blocks/analytics/charts` |
+| `ChartCard`, `ChartCardProps` | `themelia-react-ui/blocks/analytics` | `themelia-react-ui/blocks/analytics/charts` |
+
+```diff
+- import { MetricGrid, ChartCard, type MetricData } from 'themelia-react-ui/blocks/analytics';
++ import { MetricGrid, ChartCard, type MetricData } from 'themelia-react-ui/blocks/analytics/charts';
+```
+
+Nothing else moves. `MetricComparison`, `ActivityHeatmap`,
+`TimeDistributionRuler`, `MetricTrendChip`, `MetricSkeleton`, `UsageCard`,
+`formatMetricValue`, `resolveTrend` and the analytics strings stay in
+`themelia-react-ui/blocks/analytics`. The shared metric types (`MetricData`,
+`MetricChange`, `MetricSize`, `MetricVariant` and the rest) stay there too and
+are also exported from the charts entry, so one import covers a metric and its
+data.
+
+The [changelog](CHANGELOG.md) and [consumer composition guide](docs/consumer-skill/references/composition.md)
+describe the current roles and the version-specific changes.