themelia-react-ui 2.0.4 → 2.0.6

package/CHANGELOG.md

@@ -1,5 +1,216 @@
 # Changelog
 
+## 2.0.6 — 2026-11-04
+
+- AI disclosure and source controls use their visible text for accessible
+  names. Disclosure copy overrides remain available as descriptions.
+- OrderStatusCard accepts translated status labels and a formatter for the
+  displayed order reference.
+- Default layout navigation renders callback-only entries as buttons and
+  keeps disabled entries inert. Custom settings link renderers receive
+  selection through `onClick`.
+- SideNav accepts a `renderLink` adapter. Pass your app's pathname as
+  `currentPath` to preserve active-route highlighting when upgrading from
+  the implicit browser URL default.
+- AppSidebar and SidebarNavigationRail close an open drawer after app
+  navigation. Use `closeDrawerOnNavigate={false}` to keep it open.
+- Header and HeaderBreadcrumbs render in standalone and stacked layouts.
+  The built-in sidebar trigger appears only inside a sidebar provider.
+- FormField labels, hints and errors reach time, dimension, coordinate,
+  image, avatar, key/value and rich-text controls. RichTextEditor also accepts
+  `invalid` and preserves the field association in source mode.
+- A blank optional TimePicker allows native form submission.
+- AvatarUpload honors MIME types and wildcards in its file accept rules.
+- FormRichTextEditor binds React Hook Form touch, focus, invalid and disabled
+  state. Named editors include committed HTML in native submissions.
+- Combobox and MultiCombobox accept selection defaults and new value props
+  alongside their legacy bindings. All three selectors accept search and
+  open defaults.
+- WeightInput, DimensionsInput and CoordinatesInput expose direct value
+  callbacks, field blur and native form names, plus required and read-only
+  behavior.
+- TimePicker supports initial times, controlled or default popup visibility,
+  and named native values with required validation in both modes.
+- PillRadioGroup supports uncontrolled defaults and submits the selected
+  enabled option when named. Clearing still emits `null`.
+- AppointmentCalendar, Questionnaire, LanguageSwitcher and EmailComposer
+  add consistent value callbacks. TabbedResourceShell adds an initial tab.
+- Metric and MetricGrid accept a shared semantic `tone`. The legacy
+  `colorScheme` remains supported. Colored metrics keep primary progress
+  by default and accept an explicit neutral tone.
+- MediaLibrary keeps failed edits and uploads in their own panels so browsing
+  stays available. `useMediaLibrary` exposes `loadError`, `mutationError` and
+  `uploadError` alongside the existing `error` field.
+- MediaLibrary requires explicit callbacks for edits and deletes, including
+  in-memory collections and the headless mutation methods. Its Delete action
+  opens a confirmation and returns focus to the results after removal.
+- MediaLibrary keeps previous results mounted during refresh. Inline fetcher
+  and error callbacks no longer trigger reloads. Change `refreshKey` to
+  reload the current remote query explicitly.
+- MediaLibrary server pickers return selected records from earlier searches
+  and uploads. Uploads refresh the remote results and stay selected across
+  filters.
+- MediaLibrary uploads keep queued files and individual failures available
+  for the next request. Upload helpers expose the current batch's file IDs.
+- Native submissions from `Combobox`, `MultiCombobox` and
+  `AsyncResourceCombobox` now use the selected item's key, or its label
+  when no key is supplied. To keep submitting JSON objects, pass
+  `getItemValue={(item) => JSON.stringify(item)}`.
+- Async filter option freshness and retention apply within one mounted editor.
+  Chip labels are isolated to their filter provider. Applications that need
+  reuse across editor mounts can cache in their own scoped fetcher.
+- DataTable bulk-action counts include selected IDs from other server pages.
+  Use `rowSelection` for those IDs and `selectedRows` for loaded records.
+- Numeric filters use `between` and store two positional bounds, with an
+  empty string for an open end. The URL helpers still read older scalar
+  values as exact matches. Date ranges retain both calendar days on reload.
+- Inline product option editing preserves rich value labels. Options with
+  rich names can use the `onEditOption` callback for app-owned editing.
+- Money treats a single dot as a decimal separator in
+  serialized amounts, including three-decimal currencies.
+- Controlled overlays report each dismissal request through `onOpenChange`.
+  `onClose` now follows the committed visibility change.
+- RichTextEditor source edits stay in a draft until switching back to rich
+  text. The editor emits the normalized document HTML. An external value
+  change replaces the open source draft.
+- `useActivityResources` reseeds when resource values change. Equivalent
+  inline resources preserve local edits, and each mutation emits once.
+
+## 2.0.5 — 2026-10-31
+
+- Modal scrims render again under `SidebarProvider`/`AppSidebar`. The sidebar
+  drawer owner is a Dialog root around the app, so Base UI treated every dialog
+  inside as nested and skipped its backdrop. A modal now draws its backdrop
+  unless it opens from inside another modal's content.
+- Collection rows (menus, Command, Select, Combobox, cascader, global search) are
+  sized by their height role: block padding steps one tier below Item's, so a
+  single line is exactly 32/28/36px at default/compact/comfortable instead of
+  1.5px taller. DataTable menus, kanban and activities drop the legacy 24px
+  `density="table"` rows.
+- Skeletons use the translucent neutral chip fill, so they keep one contrast on
+  every surface, including a `--muted` sidebar where they used to disappear.
+- `StackedLayout`, `TopbarSidebarLayout` and `AppLayout` with no variant follow
+  the active theme; `headerTheme`/`light-header`/`dark-header` still scope the
+  header. Header controls (sidebar trigger, search, tools, notifications, a
+  one-line user trigger) share the 32px action height.
+- The dual navigation cluster docks its contextual panel from 768px beside a
+  primary rail and opens it as a drawer below that; `mobileSidebarMode="inline"`
+  keeps the previous docked cluster.
+- `GlobalSearch` input is a combobox with `aria-activedescendant`; results are
+  options reached with the arrow keys rather than Tab.
+- Filter editors focus their primary input when opened and share one editor
+  header; selection captions read "2 status selected" in running text.
+- Additive: `CardShell surface`, `FormSection titleSize`, CoordinatesInput
+  latitude/longitude accessible-label strings, MetricComparison `pointsUnit`,
+  UsageCard average-unavailable string, AI tool-call `elapsedLabel`, AI summary
+  `confidenceLabel`, ActivityRow `reserveDisclosure`/`reserveMenu`,
+  MediaLibraryToolbar `summary`/`disabled`, `useMediaLibrary().retry` and
+  `strings.retry`.
+- Alert places its action beside the copy only when the alert itself is wide
+  enough (container query), otherwise below it. PageHeader wraps its commands
+  below the copy before the copy column gets cramped.
+
+- `--height-action` and `--height-control` default to 2rem (32px) instead of
+  2.25rem. Their size steps are eighths of the root (¾, ⅞, 9⁄8), so the scale is
+  24/28/32/36px in whole pixels; it was 28/32/36/40px in ninths. Set the roots
+  back to 2.25rem to restore the previous heights (steps become 27/31.5/36/40.5px).
+- Corner roles: `rounded-radius` (`--radius`, 12px by default) is now the
+  default corner for buttons, inputs, select and facet triggers, badges,
+  collection and navigation rows and nested bodies. The new `rounded-surface`
+  (4/3 × `--radius`, 16px) is the larger corner of cards, popups, dialogs,
+  command shells and other outer surfaces. `rounded-inner` and its bounded
+  formula are removed. Migration: replace an app's `rounded-radius` on outer
+  shells with `rounded-surface`, and `rounded-inner` with `rounded-radius`.
+- `Alert` and the `Toaster` toast take Item's row geometry: the row insets
+  (`px-row-x`, `py-row-y`, 12px and 8px by default) and Item's 12px
+  media/actions gap, instead of the 24px card surface inset. A two-line notice
+  is about 60px tall instead of 94px. Overlay tone notices, which are Alerts,
+  follow the same row roles.
+- `PopoverTitle` and `PopoverDescription` no longer wrap plain text in the
+  popover's inherited line box, and `Cascader` keeps "Select current" beside
+  its title and path instead of inside the title row. A drilled level's title
+  and parent path now sit 4px apart instead of 11px.
+- Menu surfaces (popover menus and their header and footer bands, dropdown
+  menus, Select and Combobox lists, Command and its search row, global search,
+  mentions and the cascader) inset by md (8px) on both axes instead of xs
+  (4px) inline, so rows and the search field sit further from the edge, and
+  header and footer copy sit one small xs step (4px) inside that edge instead
+  of adding the full row inset (shared `popoverRecipes.menuCopyInset`).
+- Filters support nested options. `FilterOption.children` was declared but
+  ignored; `SELECT` and `MULTI_SELECT` editors now show nested options one level
+  at a time through the Cascader's panel (path search, Back, multi-select across
+  levels, `closeOnSelect`), and `SelectFacet` uses the `Cascader` field. A chosen
+  nested option reads as its path ("Europe / Greece / Athens") in chips and
+  facets. `FilterConfig.selectableOptions: 'any'` lets a branch be chosen, and
+  the filter strings add `previousLevel` and `selectCurrentLevel`. The panel is
+  a private part shared by `Cascader` and filters; `Cascader` behaviour is
+  unchanged.
+- `Cascader` moves between levels with motion: a drilled level or a new column
+  enters from the side it was reached from (shared `motionRecipes.level`,
+  `@starting-style`, reduced-motion aware). Opening and searching do not
+  animate the list.
+- `LayoutSidebarProvider` (and so `AppSidebar`) defaults to
+  `menuDensity="default"`: 28px primary rows and 24px nested rows on a 4px gap
+  (with the 2rem action height below), instead of comfortable 36px and 32px
+  rows. Pass `menuDensity="comfortable"` for 32px rows. Sidebar navigation
+  labels are medium weight throughout; the current entry is marked by its fill.
+  An unscoped base `SidebarMenuButton` falls back to the default density like
+  the rest of the menu, and a collapsed icon-rail row is the square of its own
+  height.
+- Remove the leftover `active:translate-y-0!` press overrides from Collapsible
+  and Tooltip triggers, dialog and sheet close buttons, popover buttons and the
+  sidebar trigger. Nothing translates on press any more, and the overrides made
+  triggers centred with a translate, such as the sidebar disclosure chevron,
+  jump down while pressed.
+- Add a fourth consumer skill, `themelia-design`, for the designer's part of a
+  view: a data brief read from real records, a view spec with ranked
+  information, wireframes and encodings, and a scored critique rubric with a
+  browser census for rendered screens. A `themelia-ui-designer` agent
+  definition applies it to whole views (design mode builds, renders and fixes;
+  review mode critiques read-only). `setup-skills.mjs --agents <directory>`
+  copies the agent without overwriting an existing file, and `--check`
+  compares it. The project-instructions block lists the new skill.
+- `ResourceCell` draws its media circle only when `imageUrl`, `icon` or
+  `fallback` is passed, and no longer falls back to a decorative mail glyph, so
+  order and invoice identifiers read as plain text. To keep a monogram for a
+  person or organization, pass `fallback={<Initials value={name} />}` (on every
+  row of a column where only some rows have a photo). An explicit `fallback`
+  still wins over `icon`, and `icon` now wins over title initials.
+- `InvoiceLineItems` states quantity and unit price once per narrow row instead
+  of repeating column labels, aligns header and rows on one subgrid with
+  content-sized numeric tracks, top-aligns custom cells, scrolls custom columns
+  horizontally (or drops columns marked `wideOnly` below its `@lg` width), and
+  adds `surface="flat"` for use inside a Card. Header and
+  rows now sit in `.invoice-line-items--body`, which carries the grid template
+  that each row used to repeat. The family
+  index now exports `InvoiceColumn`, `InvoiceLineItemsFooterRow`,
+  `InvoiceLineItemsStrings` and `defaultInvoiceLineItemsStrings`.
+- Commerce owners that hard-coded their frame accept `surface`/`padding`:
+  `FulfillmentGroup` (framed by default) and `InvoiceHeader`,
+  `DiscountStackPreview`, `TaxBreakdownCard`, `RefundStatusCard`,
+  `CartSummaryCard`, `ShipmentTracking` and `InventorySectionCard` (unframed by
+  default). Defaults are unchanged.
+- Add `maxVisibleSecondaryActions` to page, record, settings, workspace and
+  resource headers (default 2), `visibleFields` and `children` to
+  `ProductVariantEditor`, and `showGroupBy` to `ProductVariantsManager`
+  (default true).
+- Consumer gaps from the round-2 rebuilds: `InvoiceStatus` adds `draft` and
+  `disputed`; `InvoiceHeader.status` is optional and parties take `details`;
+  `OrderCustomer` adds `shippingMethod` and `showShippingAddress`;
+  `FulfillmentGroup` adds `count`; `MetricComparison` honours `current.trend`;
+  `ChartTooltipContent` adds `valueFormatter`; `ProductVariantEditor` adds
+  `errors`, `formId` and `showHeader`; `ResourceCell` adds `mediaShape` and a
+  full-title hover; `MediaResourceGallery` grid shows whole images and omits a
+  missing file size; an explicit DataTable column `size` sets its width without
+  resizing; `base/toaster` re-exports `toast`; `blocks/commerce` exports its
+  status tone maps and invoice strings. `ProductOptionsMatrix` focuses a value
+  added in its option editor so it can be typed at once.
+- Discovery resolves near-miss import paths with `importResolution`, the mapper
+  knows 139 roles across commerce, products, media, charts and analytics and
+  suggests nearby roles for unmatched phrases, and the inspector reads several
+  props at once and points hooks to their declaration. A new order and invoice
+  composition reference ships with executable recipes.
+
 ## 2.0.4 — 2026-10-28
 
 Shared composition roles, stronger consumer guidance and executable component

package/MIGRATION.md

@@ -0,0 +1,119 @@
+# From admin-ui-starter-kit 3.x
+
+`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.
+The `themelia-react-ui` 2.x line is the migration destination for
+`admin-ui-starter-kit` 3.x applications.
+
+## 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.
+
+The [changelog](CHANGELOG.md) and [consumer composition guide](docs/consumer-skill/references/composition.md)
+describe the current roles and the version-specific changes.

package/README.md

@@ -2,7 +2,7 @@
 
 A publishable React UI package built on Base UI and Tailwind, with shadcn-compatible themes and Themelia's public APIs. Routing, persistence, permissions and translations remain consumer-owned.
 
-Package: **`themelia-react-ui`** · current version: **`2.0.4`** · MIT licensed.
+Package: **`themelia-react-ui`** · current version: **`2.0.6`** · MIT licensed.
 The GitHub repository is `themelia-react-ui`; npm imports use `themelia-react-ui`.
 
 Consuming apps start with [consumer setup](#consumer-setup) and the packaged
@@ -25,6 +25,14 @@ npm run check:all
 
 The Vite React playground has foundations, a complete searchable catalogue, and an interactive products workspace. The catalogue groups Foundations (including semantic primitives and composition structures), Base components, Layouts, Blocks, and domain Features. Layouts includes five composed AppLayout presets (light header, dark header, sidebar, inset canvas and stacked navigation), plus a responsive composition guide for viewport grids, parent-driven grids, wrapping actions and stable content order. Navigation uses actual package families, static domain headings above Features, padded disclosures and a single Skeletons family page. Expansion persists across page changes and mobile drawer closure; search shows the same group context. `/` opens the full catalogue with preview-only hash navigation (`/?page=catalog` also works); `/?page=products` exercises options, generation, validation, async save/retry and bulk actions. React Router is not a dependency.
 
+For the application shell at its actual viewport size, open
+`/?page=shells&layout=header`, `/?page=shells&layout=sidebar` or
+`/?page=shells&layout=inset`; append `&theme=dark`
+for the dark theme. This preview-only mode removes catalogue chrome from the
+composition. The [shell architecture verification report](docs/verification/2026-10-29-shell-architecture-catalogue.md)
+records source ownership, rendered measurements and executed interactions for
+the three catalogue structures.
+
 `build` emits ESM entrypoints, TypeScript declarations, compiled component CSS, editable Tailwind theme source and optional map styles. Playground files stay outside the tarball. `check:contract` enforces exact exports, retained source symbols, component layers, dependencies and token ownership. `check:preview` verifies ready routes, example files, exact current public symbols, published imports and public family coverage. `check:docs` verifies local props for source-origin-qualified public callable owners, including all static displayed PropsTables. `check:package` requires a fresh `npm run build`. It installs the tarball into an isolated consumer, checks strict declarations for every family and matches installed declaration exports to the source-backed skill index. Its installed basic fixture checks SSR/hydration and executes provider defaults, controlled Input/Select/Checkbox state, form submission/validation/reset, scoped overlay portals and async confirmation/retry. Native links retain a separate strict typecheck and Vite-build smoke. The optional fixture exercises controlled table sorting/selection/visibility and client module initialization for specialist peers. Initialization does not establish specialist workflow or server-rendering support. It uses the configured npm cache, or `THEMELIA_NPM_CACHE`; a fresh `npm ci` cache may lack fixture registry metadata. Use `THEMELIA_FIXTURE_INSTALL=online` explicitly for cold temporary consumers, or supply a prepared cache for the default offline install. See [release readiness](docs/releasing.md).
 
 `lint` runs development-only `@shadcn/lint` through Oxlint: semantic colors across components, shared recipes and preview TSX and fixed typography contracts in preview examples. `check:design-lint` proves rule recognition, package stylesheet discovery and permitted customization. Both run inside `check`; `.oxlintrc.json` owns the staged policy. See [typography and lint guidance](docs/typography-and-design-lint.md).
@@ -41,6 +49,8 @@ Browser verification requires Playwright Chromium. An existing executable can be
 
 ## Consumer setup
 
+Moving an existing Themelia app from `admin-ui-starter-kit`? See the [3.x migration guide](MIGRATION.md).
+
 Install a built tarball; use a registry release when available. React 19, React DOM 19, the declared Base UI peer and Lucide React 1 are required peers. Import exact family paths; there is no aggregate component barrel or public raw UI entrypoint.
 
 Nested light/dark utilities use custom-property container style queries. Use
@@ -48,14 +58,14 @@ Chromium 111+, Safari 18.1+ or Firefox 151+ for this theme behavior. The nearest
 mode class governs nested components and their scoped portals; see the
 [theme guide](docs/consumer-skill/references/theming.md) for partial overrides.
 
-Version 2.0.4 uses official `@base-ui/react ^1.9.0` from npm. Themelia's
+Version 2.0.6 uses official `@base-ui/react ^1.9.0` from npm. Themelia's
 `ComboboxRoot.dismissLabel` and feature `strings.dismiss` name both screen-reader
 dismissal controls. Shared popup owners preserve focus restored to a child
 trigger during deferred parent recovery. These behaviors are library-owned;
 consumers install the unmodified official Base UI package.
 
 ```sh
-npm install ./themelia-react-ui-2.0.4.tgz '@base-ui/react@^1.9.0' lucide-react
+npm install ./themelia-react-ui-2.0.6.tgz '@base-ui/react@^1.9.0' lucide-react
 ```
 
 For a registry release, install into a React 19 application with:
@@ -93,22 +103,32 @@ export function Example() {
 The default primary is near-black, so status colors never compete with it. For the Themelia green brand, also import `themelia-react-ui/themes/green.css` after `style.css`. For your own brand, set `--primary` and `--primary-foreground` (light and `.dark`) at the root or a `ThemeScope`; `--primary-accent` follows `--primary`.
 
 Compiled `style.css` requires no source scanning and includes no global preflight.
+It includes static utility classes used by documented catalogue examples and
+shipped recipes/templates. Arbitrary app classes still need app CSS or Tailwind.
 Components own their essential font and box model; the host may supply a reset
 for its own markup. Keep resets in a lower-priority CSS layer and load deliberate
-app overrides after library CSS. A Tailwind v4 application can additionally
+app overrides after library CSS. The application owns the page canvas and inherited
+copy: set the document font to `var(--font-sans)` and the body background/color to
+`var(--background)` / `var(--foreground)`. See the [host CSS setup](docs/consumer-skill/references/installation.md#set-the-application-canvas).
+A Tailwind v4 application can additionally
 import `theme.css` after Tailwind to generate app-owned utilities from the same
 mappings; this editable file contains Tailwind directives and needs processing.
 
-The package ships three focused agent capabilities:
+The package ships four focused agent capabilities:
 [components](docs/consumer-skills/themelia-components/SKILL.md) for installed setup,
 search and typed component/form integration;
-[tokenization](docs/consumer-skills/themelia-tokenization/SKILL.md) for semantic
-themes, typography and shared geometry; and
+[tokenization](docs/consumer-skills/themelia-tokenization/SKILL.md) for domain
+structures combining public parts with semantic JSX and token-backed Tailwind,
+plus shared themes, typography and geometry;
 [composition](docs/consumer-skills/themelia-composition/SKILL.md) for business
-hierarchy, responsive screens and visual repair. Their shared assets and
+hierarchy, responsive screens and visual repair; and
+[design](docs/consumer-skills/themelia-design/SKILL.md) for reading records into
+view specs and scoring rendered views against a critique rubric. A
+[designer agent](docs/consumer-skill/agents/themelia-ui-designer.md) applies the
+design skill to whole views. Their shared assets and
 the compatible original entrypoint remain in `docs/consumer-skill`. The previous
 foundation/forms paths remain package compatibility routes; fresh skill copying
-installs the three canonical capabilities. Follow the
+installs the four canonical capabilities. Follow the
 [installed setup and copying guide](docs/consumer-skill/references/installation.md)
 to preserve all references; npm installation does not modify global agent skills.
 
@@ -163,7 +183,8 @@ defines application freedom and library-owned anatomy; the
 and verification gate. Shipped consumer examples receive the same design lint as
 library compositions. Those repository checks do not run automatically in apps.
 Popover display/menu anatomy and default/compact insets are separate from collection
-row density and control size. Flush delegates padding to owned regions. Command
+row density and control size. Rich display surfaces keep 24px default insets;
+compact menu/list shells use 4px around their already-padded rows. Flush delegates padding to owned regions. Command
 search composes the public Input; features inherit these base recipes rather than
 rebuilding menu chrome or passing local padding overrides.
 
@@ -227,7 +248,7 @@ Consumer callbacks own feature data and backend effects. The examples demonstrat
 
 ### Blocks import migration
 
-The presentation layer is now named `blocks`. Replace `themelia-react-ui/composed/<family>` with `themelia-react-ui/blocks/<family>` for admin, AI, analytics, commerce, data-display, onboarding, and timelines. Component names and props are unchanged. The source folder and catalogue routes follow the same rename.
+The presentation layer is now named `blocks`. Replace `admin-ui-starter-kit/composed/<family>` with `themelia-react-ui/blocks/<family>` for admin, AI, analytics, commerce, data-display, onboarding, and timelines. The source folder and catalogue routes follow the same rename.
 
 The default development URL opens the full component catalogue. The focused foundation playground remains at `/?page=foundations`, and the products workspace remains at `/?page=products`.
 
@@ -240,9 +261,10 @@ Use `titleSuffix` for card status, count and version badges. `headerStart` is fu
 Application drawers use `ActionDrawer` and `useOverlayVisibility` from `themelia-react-ui/features/overlays`. Sheet is the structural foundation and remains available for lower-layer infrastructure and compatibility.
 
 Header commands are role-based: one `primaryAction` and ordered
-`secondaryActions` render as `[secondary…] [primary] [⋯]`, with overflow,
-destructive commands and narrow widths moved into the More actions menu that
-ends the row. Page, PageHeader, PageHeading, the resource shells,
+`secondaryActions` render as `[secondary…] [primary] [⋯]`, with overflow
+and destructive commands moved into the More actions menu that ends the row.
+Below 40rem of actual header width, one More actions trigger contains all commands,
+including primary. Page, PageHeader, PageHeading, the resource shells,
 WorkspaceRecordHeader and SettingsShell share that row; keep `actions` for
 non-command controls. Use `header.tabs` for separately selected or routed record
 sections, with counts when useful. Continuous detail documents keep their
@@ -256,7 +278,18 @@ scale. The menu comes after any primary command in its row, and destructive
 entries stay last.
 Page owns inline and block padding, defaulting to the large surface role;
 PageViewport owns scrolling and supplies no inset. Use `Page narrow` for a
-centered single resource; explicit `maxWidth` wins. Page headers use dense copy
+centered single resource. An `aside` selects the `xl` (80rem) measure unless
+`narrow` or an explicit `maxWidth` wins. Page owns `toolbar`, body lifecycle
+states (`loading`, `error`, `empty`, `onRetry`) and the route header.
+Its four header content slots are `beforeTitle`, `titleSuffix`, `afterDescription`
+and `actions`: pass React content or a callback receiving `{ renderLink, defaultContent }`.
+Compose Badge or MetadataList in those slots; the header adds no avatar or automatic
+metadata shape. `slots.actions` can wrap or return its default responsive command
+row through `defaultContent`; replacing it makes command behavior caller-owned.
+Legacy `slots.back`, `titleBadges`, `titleIcon` and direct `actions` remain supported.
+ResourceHeader, ResourceIndexShell, ResourceShowShell and TabbedResourceShell
+are deprecated; replace them with Page rather than nesting route owners. Their
+existing embedded geometry remains supported. Page headers use dense copy
 gaps. Ordinary cards default to `surface="card"` and `md` padding (24px), with
 an unruled header and a ruled footer. Explicit divider props override provider
 defaults. Use `surface="framed"` for grouped emphasis and `surface="flat"`
@@ -264,10 +297,73 @@ inside an existing boundary. Card padding supports `none`, `sm` (12px), `md`
 (24px) and `lg` (32px); its default regional gap follows the same surface tier
 (`none` retains the 24px gap). The general surface scale also includes 16px. All
 are scaled once by `--space-scale`; control heights and corners remain separate.
+
+AppLayout keeps its five variant choices. The shared header-height root now
+defaults to `4rem`. Header-first
+`light-header`/`dark-header` layouts can opt into `contentSurface="inset"`: a
+quiet secondary canvas around the card-colored main surface. Sidebar-first
+`sidebar`/`inset` presets keep their existing flush/inset behavior. Shells own
+one PageViewport; Page supplies the page padding, and header partials occupy the
+shell's single header owner.
+
+The catalogue leads with three structures: a global Header shell, the shared
+App sidebar shell and a shadcn-style Inset shell. Single/dual navigation,
+attached/floating framing and collapse behavior configure these structures.
+They reuse the five presets. Full-size previews use
+`?page=shells&layout=header`, `sidebar` or `inset`, optionally with `&theme=dark`.
+The focused `grouped`, `dual`, `dual-inset`, `floating` and `stacked` views remain
+available for comparison.
+
+The featured layouts use grouped left navigation or a static left area rail
+beside a full navigation panel. Collapse is a caller choice on
+`AppSidebar`/`LayoutSidebar`, independent of the shell or sidebar skin:
+`collapsible="icon"` minimizes the full panel to icons, `"offcanvas"` hides it,
+and `"none"` keeps it expanded. Current examples default to `icon` and expose
+a preview selector for these modes. In a dual layout the primary area rail
+remains static: icon mode leaves a second compact column, while offcanvas
+leaves only the original rail. One explicit trigger controls the contextual
+panel; selecting an area opens it. Keep the primary rail's `collapsible="none"`
+policy independent of the adjacent panel's policy.
+At narrow widths the inline cluster pans a minimum page canvas while its area
+rail stays pinned; resizing does not silently minimize navigation.
+Both header-first and sidebar-first shells expose `mobileSidebarMode`; choose
+`inline` for this persistent cluster, or retain the default drawer policy.
+Sidebar shells accept
+`slots.sidebar` (primary) and `slots.secondarySidebar` (contextual), with named
+state inherited under one LayoutSidebarProvider. `openPanels` controls expansion and
+`mobilePanel` selects one shared undocked drawer while preserving desktop state.
+`navigationPanel` selects the untargeted trigger/shortcut destination. Existing
+primary `open`/`onOpenChange` remain supported; controlled `openPanels` takes
+precedence. Independent width props and `sidebarPresentation="rail"` use existing
+shell geometry, with no new public theme roots. SidebarNavigationRail supplies
+area navigation on its own background surface with one divider. Its dedicated
+width is 52px at the default roots (a 36px action plus 8px on each side); the
+existing full-sidebar icon-collapse width remains 60px. These are derived
+recipes, not new public settings. SidebarRail remains the collapse affordance.
+
 AppSidebar offers pinned `slots.headerStart`/`headerEnd` around its workspace
-region, compact navigation and a separated footer. The
+region, grouped navigation and a separated footer. The four `header`,
+`beforeNavigation`, `afterNavigation` and `footer` slots accept content or a
+callback with named state, renderLink and defaultContent. A header node preserves
+its legacy full replacement behavior; callback header content and either footer
+form retain library-owned insets. Before/after navigation content scrolls.
+Ordered `{ id, label?, items }` groups supplement the existing Record form, and
+`renderItemContent` customizes label content inside the accessible row. Use
+`currentUrl` for most-specific destination matching; render contexts distinguish
+the current item from its `ancestor`. In icon mode, searchable sidebars retain
+their search band as an icon that expands and focuses the field. Compact rows
+keep a small gap; default and comfortable density share a roomier row gap,
+with separate caption and group spacing. SidebarNavigationRail also exposes
+`header`, `beforeNavigation`, `afterNavigation` and `footer` slots: header/footer
+stay pinned and before/after content scrolls with navigation. Use
+`surface="transparent"` for navigation that shares a docked shell canvas;
+drawers remain opaque. `adaptTo="container"` keeps an embedded drawer and its
+backdrop inside the provider for compositions that use drawers. Omit a contextual
+group label when its header already supplies that same label. KPI peers use MetricGrid. The
 [complete shell recipe](docs/consumer-skill/examples/app-layout.tsx) demonstrates
-public workspace/account controls and hosts route children directly. Its separate
+single- and multiple-region composition with public workspace/account controls
+and hosts route children directly. Its `contextualCollapsible` option defaults
+to `icon`; a supplied `secondarySidebar` can choose its own collapse mode. Its separate
 `WorkspaceExamplePage` owns the illustrative title, Create callback and narrow
 measure; a real route such as `AccountDetailPage` replaces that example.
 
@@ -276,7 +372,13 @@ surfaces win. Leave Card's `icon` slot for a glyph that carries state or a
 brand; titles name the subject. `headerPlacement` chooses inside/frame
 composition independently. Independent framed peers use `gap="2xl"`, matching
 Page and TwoColumnLayout's rhythm, since outer rings consume a smaller DOM gap.
-MetadataList (`themelia-react-ui/base/metadata-list`) keeps semibold labels and normal primary values in both densities.
+Card body children use the related (`xl`, 16px) gap by default; explicit
+`contentGap` remains authoritative. SettingsShell spaces direct sections by the
+subjects (`2xl`, 24px) role. MetadataList (`themelia-react-ui/base/metadata-list`)
+keeps semibold labels and normal primary values in both densities. It now adapts
+to its own container by default, with 22/28/38/52/64rem thresholds; pass
+`adaptTo="viewport"` to retain viewport breakpoints. DataTable owns its surface
+and topbar insets; place compact FilterLayout in `topbarContent`, or use DataView.
 Dashboard KPIs use Metric/MetricGrid/MetricBar; quotas use the focused UsageCard
 owner. See [analytics selection](docs/consumer-skill/references/analytics.md) and
 the [resource page recipe](docs/consumer-skill/examples/detail.tsx).
@@ -293,7 +395,7 @@ and ordinary Card subjects without app chrome. The packaged
 offers and real navigation links using the same theme and inset owners.
 
 
-Popover content uses `type="display"` for substantive content and `type="menu"` for collections. Mixed searchable menus use flush shells and compact region insets. `--radius` defaults to 12px. Cards and popup/command shells use `rounded-radius`; controls, collection/navigation rows and nested bodies use the shared, height-bounded `rounded-inner` role (normally 9px). Both derive from the same public root. Consumers inherit these recipes; see the [theme contract](docs/consumer-skill/references/theming.md) for scaling and custom roots. No separate surface/control radius setting is introduced.
+Popover content uses `type="display"` for substantive content and `type="menu"` for collections. Mixed searchable menus use flush shells and compact region insets. `--radius` defaults to 12px. Cards and popup/command shells use `rounded-surface`; controls, collection/navigation rows and nested bodies use the shared, height-bounded `rounded-radius` role (normally 9px). Both derive from the same public root. Consumers inherit these recipes; see the [theme contract](docs/consumer-skill/references/theming.md) for scaling and custom roots. No separate surface/control radius setting is introduced.
 
 
 ## Agent skill and consumer references
@@ -342,7 +444,7 @@ visual review remain separate.
 
 Maintainers run `npm run docs:sync-skill` after changes to exports, types, selection guidance, peers or tokens. `npm run check:skill` requires a fresh library build and rejects stale source-backed references, built declaration exports and broken reference links. `prepack` checks source-backed references without rebuilding; `prepublishOnly` builds fresh assets and verifies built guidance. `check:package` verifies the complete shipped skill, strictly compiles the basic recipes without optional peers and every recipe with its required peers, and executes installed shell/resource-page and workflow checks.
 
-Build portable consumer documentation with `npm run build` followed by `npm run build:docs`. The generated [static entry](dist-docs/index.html) links to `dist-docs/2.0.4/` for the current version. Each version preserves the complete skill and all declaration files, supports search with the same finder, and uses relative links under any hosting subdirectory. Serve the entire artifact over HTTP; it needs no external CDN. Run `npm run check:static-docs` to check generated asset paths. The future hosting destination remains pending.
+Build portable consumer documentation with `npm run build` followed by `npm run build:docs`. The generated [static entry](dist-docs/index.html) links to `dist-docs/2.0.6/` for the current version. Each version preserves the complete skill and all declaration files, supports search with the same finder, and uses relative links under any hosting subdirectory. Serve the entire artifact over HTTP; it needs no external CDN. Run `npm run check:static-docs` to check generated asset paths. The future hosting destination remains pending.
 
 `npm run check:agent` runs focused agent-consumption fixtures and built skill alignment. `npm run check:release` performs the real serial local build/package/browser/agent/static-documentation gate; it does not publish or deploy. `npm run check:quick` runs the everyday core (contract, lint, design lint, typecheck, unit tests, build). See the [release guide](docs/releasing.md) and [draft changelog](CHANGELOG.md). There is no hosted CI; every check runs locally, when you choose. These commands verify locally; publication and deployment remain separate actions.