themelia-react-ui 2.0.1 → 2.0.2

package/CHANGELOG.md

@@ -1,5 +1,311 @@
 # Changelog
 
+## 2.0.2 — 2026-10-21
+
+Card dividers on by default, one rule per overlay region boundary, the
+appointment calendar, and the fixes and shared recipes that followed 2.0.1. No
+public export or prop is removed. Base UI is now the patched
+`@base-ui/react@1.8.0-kpo.2` archive (see "Upgrading from 2.0.1"). Additions:
+`align` on ConfirmDialog and ActionDialog with UIProvider overlay defaults;
+`selecting`, `defaultSelecting`, `onSelectingChange`, `onItemOpen` and
+`bulkActions` on MediaLibrary; `useRichTextImages` and `images` on RichTextEditor
+and RichText; `bodyHeight` on RichTextEditor; the
+`themelia-react-ui/base/metadata-list`, `themelia-react-ui/base/batch-action-bar`
+and `themelia-react-ui/features/appointment-calendar` entrypoints; an optional
+`fontFamily` on `signaturePadToSVG`; the order blocks, `SummaryPanel` and
+`AmountRow` in `blocks/commerce`; `valueAlign` on MetadataList; `defaultValue`,
+`name` and ARIA props on TagsInput; `density` on Table; `variant="chips"` on
+TabsList; `valueWeight` on InlineStat and `size` on AiShimmer; screen-reader
+label strings on Combobox, AsyncResourceCombobox, DataTable and MediaLibrary.
+`features/sync`, the standalone product region cards, the `blocks/data-display`
+MetadataList exports and `ActivityRow` `moreLabel` are deprecated.
+
+### Audit update — 2026-10-24
+
+- Layouts, blocks and features pair painted surfaces with their foregrounds;
+  owned primary copy inherits those roles while secondary, status and custom
+  content keep their intended colors. Existing sizing, spacing and radius
+  defaults remain unchanged.
+- Bordered auth/workspace, metric, media/chat and event frames preserve their
+  geometry without a consumer CSS reset. Rich editor controls dim once, and a
+  disabled AI prompt suspends staged and custom actions as well as its input.
+- Narrow checklist titles stay beside their status markers. Media detail regions
+  retain their content height and scroll in order without overlap. Flat Card
+  sections inherit their containing surface; search previews pair canvas ink.
+- Owned field labels follow their containing surface across forms, helper fields,
+  repeaters, filters and questionnaires; the public Label defaults are preserved.
+- MetadataList labels and primary values follow their containing surface in all
+  layouts; explicit secondary, link, status and custom content retain their roles.
+  Product catalogue viewports preserve native keyboard focus clearance.
+- Compact table pagination resolves one size across its anatomy. Muted values
+  use the shared secondary role without an extra opacity tier; source and
+  consumer composition checks reject faded typography and primitive copy.
+- Generated brand palettes retain the centralized input and focus roles instead
+  of replacing their contrast with a weak brand wash.
+- Base composition now consistently follows the foreground of its card or
+  popover surface, including owned titles, values, upload copy and chart
+  tooltips. Native hosts retain their geometry without a consumer CSS reset.
+- Card keeps full-width pre-title context, omits empty body regions, and reveals
+  clipped actions when keyboard focus enters them. CardSkeleton follows the
+  provider surface and accepts an optional `surface` override.
+- Pagination resolves one shared size for links, previous/next and ellipsis;
+  PaginationEllipsis also accepts an optional `size`. Attachment focus corners
+  match their Item shell, and Empty media follows the existing media roots.
+- Nested disabled content dims once; compound field affordances respect pending
+  and read-only state, including PhoneInput blur normalization. Carousel
+  preserves descendant editing keys, uncontrolled SliderField values stay
+  synchronized, and overflow links retain native href and keyboard behavior.
+- Resting control boundaries now meet the shared 3:1 contrast floor, including
+  filled fields on supported surfaces. Divider and focus roles remain separate.
+- Nested light/dark state utilities follow the nearest explicit mode boundary.
+  ThemeScope rebinds default aliases for explicitly supplied source roots while
+  preserving deliberate CSS/inline role overrides. This behavior uses container
+  style queries: Chromium 111+, Safari 18.1+ and Firefox 151+.
+- Chart series and scoped theme exports follow the same mode boundary. Scoped
+  selector helpers add optional `modeScope` metadata while retaining their
+  existing selector strings. Package defaults use the theme cascade layer so
+  explicit utility classes can override them on a mode boundary.
+- Enlarged editable typography can grow its shared field frame and reduce spare
+  vertical padding. Default control sizes and radius roles remain unchanged.
+- Fullscreen table menus and dialogs retain keyboard ownership; sorted headers
+  expose direction/precedence; nested cell controls no longer activate the row.
+  Row callbacks also support Enter and Space with visible keyboard focus.
+- Maintainer and packaged consumer guidance now cover surface inheritance at
+  owned text/label/value leaves, semantic text roles without extra opacity,
+  once-only disabled treatment, and stable post-interaction visual evidence.
+  The MetadataList evaluation uses its current base entrypoint.
+
+### Upgrading from 2.0.1
+
+- **Patched Base UI peer.** The `@base-ui/react` peer is pinned to
+  `1.8.0-kpo.2`, a patched build that adds `Combobox.Root.dismissLabel` and keeps
+  focus restored inside a parent popup when a nested popup closes. It is not on
+  the public registry: install the companion `base-ui-react-1.8.0-kpo.2.tgz`
+  beside this package, as the README describes.
+- **MetadataList moved to base.** Import `MetadataList`, its item types and
+  default strings from `themelia-react-ui/base/metadata-list`. The
+  `themelia-react-ui/blocks/data-display` re-exports keep working and are
+  deprecated. Labels render semibold.
+- **MediaLibrary opens before it selects.** Activating an asset (click, Enter,
+  Space) calls `onItemOpen` or shows the details panel. Selection is an explicit
+  mode: `selecting`, `defaultSelecting` and `onSelectingChange`. Picker dialogs
+  start selecting; pass `defaultSelecting` where a library relied on selecting
+  by default.
+- **ConfirmDialog is centred.** ConfirmDialog and ActionDialog accept
+  `align: 'start' | 'center'`, resolved from the prop, then the UIProvider
+  `overlay.defaultConfirmAlign` / `overlay.defaultDialogAlign` defaults, then
+  center for ConfirmDialog and start for ActionDialog.
+- **Deprecated: `themelia-react-ui/features/sync`.** `SyncRangeDialogForm` is
+  application-specific; use `SchemaForm` with `radio-cards` and
+  `checkbox-cards` fields. The entrypoint still ships.
+- **Deprecated: standalone product region cards and row menus.** Render them
+  through `ProductOverview` slots and the `renderOptionActions` /
+  `renderVariantActions` options. They stay exported.
+- **Deprecated: `ActivityRow` `moreLabel`.** The collapsed metadata preview it
+  labelled is gone; secondary detail opens with the details disclosure.
+- **Selection bars are a `BatchActionBar`.** DataTable's default selection
+  toolbar now docks to the bottom of the viewport (`floating`); pass
+  `selectionToolbarPlacement="inline"` to keep it in the table. Its summary and
+  the new `totalRowCount` prop default to `pagination.total`, so server-paginated
+  tables count the whole result. Product variant tables show an inline bar only
+  while variants are selected; `renderBulkActions` now replaces the default
+  commands, as documented (return `null` to keep them), and Delete no longer
+  repeats the count.
+- **MetadataList rows.** `layout="rows"` draws rules only with `itemSeparator`,
+  and values start their column on `2fr/3fr` tracks. Pass `valueAlign="end"` for
+  the previous right-aligned figures, such as money columns.
+- **TagsInput.** Chips sit inside the field, before the text input in Tab order;
+  the count and clear-all move to a footer under the field, and the placeholder
+  shows only while the field is empty. The input stays enabled at `maxTags`.
+- **Commerce DOM hooks.** RefundStatusCard, CartSummaryCard,
+  DiscountStackPreview, TaxBreakdownCard and ShipmentTracking render on `Card`
+  and lose the `content-block--*` classes and `data-component="content-block"`;
+  their own `--component` classes stay. ShipmentTracking and InvoiceHeader show
+  a visible title with the status chip in its suffix.
+- **Shell width utilities.** `shell-sidebar-icon-current` and
+  `shell-sidebar-offcanvas-current` read their widths from `shell-sidebar-vars`;
+  apply them together on the same element, as the library's shells do.
+- **Card dividers are on by default.** `card.defaultHeaderDivider` and
+  `card.defaultFooterDivider` now default to `true`, so framed cards rule their
+  header and footer apart. Flat, card-free structure (`surface="flat"`) and a
+  `headerPlacement="frame"` header still draw no rule unless asked, and
+  explicit per-card booleans still win. For the previous spacing-only look, set
+  both provider defaults to `false`, or pass `headerDivider={false}` /
+  `footerDivider={false}` on a card.
+
+### Changes
+
+- **Accessibility strings.** Combobox, AsyncResourceCombobox, DataTable and
+  MediaLibrary take strings for their screen-reader-only labels, including both
+  Combobox dismissal controls. Closing a nested popup no longer moves focus that
+  was already restored inside its parent popup.
+- **Overlays draw one rule per region boundary.** ActionDialog, ActionDrawer
+  and ConfirmDialog separate header, body and footer with a rule, and a dialog
+  without a body shows a single rule.
+- **Rich text images.** RichTextEditor and RichText support images through
+  `useRichTextImages`: the consumer owns `upload(file, { signal })`; the library
+  owns toolbar, paste and drop insertion, the upload placeholder, cancel, retry
+  and remove, type and size limits, alt text and the http/https/blob/relative
+  source policy. `renderImage` draws read-only images with the consumer's
+  component.
+- **RichTextEditor runs Tiptap.** Its runtime check required `EditorContent`
+  to be a function, but Tiptap 3 exports it as `React.memo`, so every editor
+  (rich text, comment, activity and email composers) silently rendered the
+  contenteditable fallback with formatting disabled. Picking a mention in Tiptap
+  now replaces its `@query` instead of appending after it, and the editor chip
+  keeps the `.rsc-mention` hook, so mention-chip.css draws it in both engines.
+- **Mentions insert as atomic badge chips** removed by one Backspace. The
+  suggestion list and picker are more compact, and kind filters use the shared
+  toggle style.
+- **Global search** builds its field on the public `InputGroup` and lays out
+  results, group headings and the footer with the compact Command recipe.
+- **Activities open compact.** Rich rows show the headline and description;
+  metadata, changes, details, resource chips and inline actions appear together
+  behind "Show details".
+- **Comments** no longer leave an empty band under each comment's action row.
+- **Choice inputs centre on the label line.** Checkbox, radio, switch and
+  selected-card checks share one label-line track (questionnaire,
+  ApiTokenManager, card groups).
+- **One plain X clears fields.** Input, Textarea, Cascader, Combobox and global
+  search clear actions, and TagsInput and Combobox chip removes, draw a plain X
+  instead of a circled X.
+- **Cascader** draws Input's field frame and the shared Combobox affordance
+  track; its clear sits beside a chevron aligned with Select's.
+- **Visual: Badge `sm` and `md` are 2px taller** (20px and 23px) at the same
+  type size; inline badges are unchanged, and TagsInput chips follow.
+- **NavigationTabs** keeps the current tab lifted under hover and press;
+  inactive tabs change colour only.
+- **SignaturePad** draws, exports and previews typed names in the pad's font
+  (theme sans by default) instead of `cursive`, and fits long names by font
+  size; `signaturePadToSVG` accepts an optional `fontFamily`.
+- **Fixes:** Dropzone centres both copy lines; IconBadge sizes child glyphs with
+  its icon role (SmartAccordion medallions render at 16px); Alert's icon and
+  action columns use Toast's 8px gap; content typography fits images to the
+  column.
+- **Catalogue:** the deprecated Sheet page, the products main-column, actions
+  and support-rail pages and the sync page are retired; their URLs redirect to
+  the overlays, product overview and SchemaForm pages.
+- **BatchActionBar** (`themelia-react-ui/base/batch-action-bar`): one selection
+  bar with a count, bulk actions and Clear, `floating` (docked, lifted, opaque)
+  or `inline`. The count is a polite live region, Escape inside the bar clears,
+  and focus returns to the list (or `returnFocusRef`) when the bar goes away.
+  DataTable, product variants and MediaLibrary's new `bulkActions` use it; the
+  old sticky selection toolbar and its overlap with the sticky topbar are gone.
+- **Order blocks** in `blocks/commerce`: `OrderHeader` (payment and fulfilment
+  status axes), `FulfillmentGroup`, `OrderLineItem`, `OrderSummary`,
+  `OrderTransactions` and `OrderCustomer`, with an Orders catalogue group and an
+  Order detail composition. The shared money ledger `SummaryPanel` and
+  `AmountRow` now draw CartSummaryCard, TaxBreakdownCard, DiscountStackPreview,
+  InvoiceHeader and OrderSummary: no tinted box, one rule above a grand total.
+- **Commerce blocks follow the source kit.** ShipmentTracking has a copyable
+  tracking number (`onCopyTracking`) and a timestamped checkpoint rail whose
+  current step is `aria-current="step"`; RefundStatusCard is an ordered list of
+  stages; PaymentMethod gains `variant="row"` and speaks `strings.formatCard`
+  ("Visa ending 4242"); CartSummaryCard falls back to initials on a failed image
+  and adds `strings.formatQuantity`; DiscountStackPreview takes an optional
+  `kind` and `id`. Blocks pass native attributes to their root. `CartSummary`,
+  `DiscountStack`, `RefundStatus` and `PaymentMethodCard` are added as the source
+  kit's names for the same components. `Timeline` items expose `data-status` and
+  mark the current item `aria-current="step"`.
+- **MetadataList** labels wrap in every layout and stay semibold; inline
+  `itemSeparator` is a middle dot hidden from screen readers; `render` output
+  takes the value style; the info trigger no longer grows its line; `icon` takes
+  any `ComponentType<{ className?: string }>`.
+- **TagsInput fixes.** Multi-tag paste commits every tag, `sortTags` removes the
+  right tag, object tags are created from an empty value, a refused entry no
+  longer traps Tab, IME composition no longer commits, a typed delimiter splits,
+  single-token paste is native, and focus moves to the neighbouring chip after a
+  removal. Refused entries stay in the draft and are announced
+  (`strings.notAdded`). New `defaultValue`, `name` (hidden `name[]` inputs) and
+  ARIA pass-through; `TagsInputStrings` and `defaultTagsInputStrings` are
+  exported.
+- **Order and commerce block fixes.** ShipmentTracking marks no checkpoint
+  current before the parcel reaches the first one. FulfillmentGroup keeps its
+  `items` rows when a conditional `children` renders nothing, takes Card's
+  default rules instead of forcing them, and accepts `headerDivider` /
+  `footerDivider`. OrderTransactions signs only money that moved (a failed
+  refund shows no minus), spells each kind out without a glyph tile or tinted
+  row, and draws no frame of its own inside a card. PaymentMethod's `row`
+  variant drops the credit-card tile, which misnamed wallets. Order status chips
+  match the rest of the library (no dot), and InvoiceHeader shows its dates as
+  facts rather than money rows.
+- **Item as a button or link.** An `Item` given `render` renders its media,
+  content, title, description, actions, header and footer as spans, so a
+  button row holds valid phrasing content. Layout and `data-slot` hooks are
+  unchanged.
+- **Theme fixes.** Light `--sidebar-primary` and its foreground follow
+  `--primary`, as dark already did, so a brand theme colours the sidebar
+  selection in both modes (the default theme is unchanged). `themes/green.css`
+  drops its `--chart-1` override, which restated the default. Theme Studio's
+  light warning accent matches the shipped token again.
+- **Filter pill focus.** Active filter segments draw the inset focus recipe
+  instead of clearing the ring, so keyboard focus no longer looks like hover.
+- **Icons follow `--icon`.** Sidebar, tabs, breadcrumb, item media, pagination,
+  avatar-group, toaster and chart-legend icons use the `size-icon*` roles
+  instead of fixed sizes; at the default `--icon` nothing moves.
+- **Design checks.** Design lint judges every `*ClassName` slot prop like
+  `className`, adds an `icon-size` rule, and rejects a cleared focus ring with
+  no replacement edge. `check:contract` adds theme-mode checks: one value per
+  mode, mode-dependent aliases restated in `.dark`, no role that follows another
+  in one mode while copying its value in the other, and no brand-theme no-ops.
+- **One owner for shared geometry.** The clear-target size, the action and
+  control size steps and the corner formulas that fields, the sidebar, toasts,
+  calendars, the key-value editor and MetadataList each wrote by hand now come
+  from the generated `affordanceGeometry` recipes, and `check:contract` keeps
+  the rich-content corners on the same formulas as the radius tokens. The
+  sidebar's collapsed and off-canvas widths are defined once by
+  `shell-sidebar-vars`; Workspace's sidebar column reads `--shell-sidebar-width`;
+  the mobile range-calendar cell follows density; the toaster's corner is the
+  shell radius role. BatchActionBar's dock offset and MetadataList's info target
+  no longer read `:root`-resolved aliases, so a scoped `ThemeScope` spacing or
+  density reaches them, and a new `root-alias` design-lint rule keeps such reads
+  out.
+- **Shared components instead of hand-built copies.** AI, metric, giftcard and
+  checklist blocks frame with `Card` instead of hand-built shells; progress bars
+  across blocks and features are `Progress`; avatar, step and status discs are
+  `IconBadge`, `Avatar` or Badge `dot`; count pills and resource chips are
+  `Badge`; the media facts list is `MetadataList`; spacing chains are `Stack`
+  gaps; the map card uses the popover surface recipe and the AI prompt frame the
+  shared field-state recipes. MetricComparison drops its nested tiles.
+- **Table density.** Base `Table` takes `density` (`compact`, `default`,
+  `comfortable`; also `data-density` on the table) and owns head and cell
+  insets; DataTable passes its `size` through it instead of overriding cells,
+  and headers lose the fixed `h-12`, so they follow density. Consumer
+  `cellClassName` padding now wins.
+- **Typography through props.** `InlineStat` takes `valueWeight` and renders its
+  value in the provider text size; `AiShimmer` takes `size`; field labels share
+  one line box (`formLabelLineClass`); link-styled text shares the 0.2em
+  underline offset; library components set size, weight and leading through
+  `Text`/`Heading` props, and `no-restyle` now enforces that in library code.
+- **Shared recipes for repeated choices.** Anchored surfaces (popovers, menus,
+  Select, Combobox, map and chart popups) take their viewport bound from the
+  shared surface recipe, and their widths from one `popoverWidthRecipes` scale;
+  the kanban card menu widens from 11rem to 12rem, the default filter popover
+  from 16rem to 18rem and ActionMenu's minimum from 9rem to 10rem. Status dots
+  use `dotRecipes` (6px beside text, 8px as a marker). The unread and stale
+  `theme` section of the token contract is removed.
+- **Tabs chips.** `TabsList` takes `variant="chips"`: wrapping, trackless toggle
+  chips with the muted hover and accent pressed fill. Saved views and filter
+  presets use it instead of overriding the default track.
+- **Smaller shared pieces.** AI source and citation numbers sit in `IconBadge`
+  (24px, up from a 20px hand-built disc). Native buttons that draw their own
+  shape start from `interactionRecipes.nativeButtonReset`.
+- **Appointment calendar.** New `features/appointment-calendar` entrypoint:
+  `AppointmentCalendar` puts a month with category dots beside the day or week
+  agenda, with category and staff filters, booked and conflict counts and a
+  dismissible double-booking alert. Overlaps are found per staff member across
+  every category. `onAppointmentClick` opens a row, `appointmentActions` adds a
+  per-row commands menu, `onRangeChange` reports the days on screen for loading,
+  and `loading`, `error` and `onRetry` cover the agenda's states.
+  `renderAppointment` renders custom rows from a context with the category
+  colour, conflict, status, time, `open`, actions, a ready actions menu and
+  `defaultRender`; the calendar is generic over the app's appointment type.
+  `appointmentsOn`, `filterAppointments` and `findConflicts` are exported for
+  apps that pre-compute their own view.
+- **Editor body height.** RichTextEditor takes `bodyHeight` (`control`, `field`
+  or `document`); `minHeight` still wins. The comment composer uses `field`, so
+  its empty editor is one textarea tall, 1rem taller than before.
+
 ## 2.0.1 — 2026-10-18
 
 One shared recipe and design-lint rule for each visual state, the fixes the new
@@ -11,17 +317,7 @@ SettingsShell, and `primaryAction` on WorkspaceRecordHeader;
 `toPageHeaderAction` in `services/actions`; an optional `toggle` flag on
 `ToolbarButtonConfig` and `RichTextEditorToolbarItem`; `context` on
 `ActionMenu` (`ActionMenuContext`); an optional `actions.menuLabel` in DataTable
-strings; `align` on ConfirmDialog and ActionDialog with UIProvider overlay
-defaults; `selecting`, `defaultSelecting`, `onSelectingChange` and `onItemOpen`
-on MediaLibrary; `useRichTextImages` and `images` on RichTextEditor and
-RichText; the `themelia-react-ui/base/metadata-list` entrypoint; an optional
-`fontFamily` on `signaturePadToSVG`; the `themelia-react-ui/base/batch-action-bar`
-entrypoint; the order blocks, `SummaryPanel` and `AmountRow` in `blocks/commerce`;
-`valueAlign` on MetadataList; `defaultValue`, `name` and ARIA props on TagsInput.
-`PageActions`, `PageAction`,
-`toPageAction`, `features/sync`, the standalone product region cards, the
-`blocks/data-display` MetadataList exports and `ActivityRow` `moreLabel` are
-deprecated.
+strings. `PageActions`, `PageAction` and `toPageAction` are deprecated.
 
 ### Upgrading from 2.0.0
 
@@ -57,46 +353,6 @@ deprecated.
   instead of a status colour or a solid primary fill. `HighlightedText`'s
   default `highlightClassName` is the shared match mark: foreground text on the
   warning tint.
-- **MetadataList moved to base.** Import `MetadataList`, its item types and
-  default strings from `themelia-react-ui/base/metadata-list`. The
-  `themelia-react-ui/blocks/data-display` re-exports keep working and are
-  deprecated. Labels render semibold.
-- **MediaLibrary opens before it selects.** Activating an asset (click, Enter,
-  Space) calls `onItemOpen` or shows the details panel. Selection is an explicit
-  mode: `selecting`, `defaultSelecting` and `onSelectingChange`. Picker dialogs
-  start selecting; pass `defaultSelecting` where a library relied on selecting
-  by default.
-- **ConfirmDialog is centred.** ConfirmDialog and ActionDialog accept
-  `align: 'start' | 'center'`, resolved from the prop, then the UIProvider
-  `overlay.defaultConfirmAlign` / `overlay.defaultDialogAlign` defaults, then
-  center for ConfirmDialog and start for ActionDialog.
-- **Deprecated: `themelia-react-ui/features/sync`.** `SyncRangeDialogForm` is
-  application-specific; use `SchemaForm` with `radio-cards` and
-  `checkbox-cards` fields. The entrypoint still ships.
-- **Deprecated: standalone product region cards and row menus.** Render them
-  through `ProductOverview` slots and the `renderOptionActions` /
-  `renderVariantActions` options. They stay exported.
-- **Deprecated: `ActivityRow` `moreLabel`.** The collapsed metadata preview it
-  labelled is gone; secondary detail opens with the details disclosure.
-- **Selection bars are a `BatchActionBar`.** DataTable's default selection
-  toolbar now docks to the bottom of the viewport (`floating`); pass
-  `selectionToolbarPlacement="inline"` to keep it in the table. Its summary and
-  the new `totalRowCount` prop default to `pagination.total`, so server-paginated
-  tables count the whole result. Product variant tables show an inline bar only
-  while variants are selected; `renderBulkActions` now replaces the default
-  commands, as documented (return `null` to keep them), and Delete no longer
-  repeats the count.
-- **MetadataList rows.** `layout="rows"` draws rules only with `itemSeparator`,
-  and values start their column on `2fr/3fr` tracks. Pass `valueAlign="end"` for
-  the previous right-aligned figures, such as money columns.
-- **TagsInput.** Chips sit inside the field, before the text input in Tab order;
-  the count and clear-all move to a footer under the field, and the placeholder
-  shows only while the field is empty. The input stays enabled at `maxTags`.
-- **Commerce DOM hooks.** RefundStatusCard, CartSummaryCard,
-  DiscountStackPreview, TaxBreakdownCard and ShipmentTracking render on `Card`
-  and lose the `content-block--*` classes and `data-component="content-block"`;
-  their own `--component` classes stay. ShipmentTracking and InvoiceHeader show
-  a visible title with the status chip in its suffix.
 
 ### Changes
 
@@ -270,86 +526,6 @@ deprecated.
   clipped mid-glyph instead: an applied coupon `SPRING2026` read as `SPRING202`.
   Truncating titles in citations, vendor profiles, gift cards and attachments
   benefit too. The applied coupon also carries its full code as a `title`.
-- **Overlays draw one rule per region boundary.** ActionDialog, ActionDrawer
-  and ConfirmDialog separate header, body and footer with a rule, and a dialog
-  without a body shows a single rule.
-- **Rich text images.** RichTextEditor and RichText support images through
-  `useRichTextImages`: the consumer owns `upload(file, { signal })`; the library
-  owns toolbar, paste and drop insertion, the upload placeholder, cancel, retry
-  and remove, type and size limits, alt text and the http/https/blob/relative
-  source policy. `renderImage` draws read-only images with the consumer's
-  component.
-- **RichTextEditor runs Tiptap.** Its runtime check required `EditorContent`
-  to be a function, but Tiptap 3 exports it as `React.memo`, so every editor
-  (rich text, comment, activity and email composers) silently rendered the
-  contenteditable fallback with formatting disabled. Picking a mention in Tiptap
-  now replaces its `@query` instead of appending after it, and the editor chip
-  keeps the `.rsc-mention` hook, so mention-chip.css draws it in both engines.
-- **Mentions insert as atomic badge chips** removed by one Backspace. The
-  suggestion list and picker are more compact, and kind filters use the shared
-  toggle style.
-- **Global search** builds its field on the public `InputGroup` and lays out
-  results, group headings and the footer with the compact Command recipe.
-- **Activities open compact.** Rich rows show the headline and description;
-  metadata, changes, details, resource chips and inline actions appear together
-  behind "Show details".
-- **Comments** no longer leave an empty band under each comment's action row.
-- **Choice inputs centre on the label line.** Checkbox, radio, switch and
-  selected-card checks share one label-line track (questionnaire,
-  ApiTokenManager, card groups).
-- **One plain X clears fields.** Input, Textarea, Cascader, Combobox and global
-  search clear actions, and TagsInput and Combobox chip removes, draw a plain X
-  instead of a circled X.
-- **Cascader** draws Input's field frame and the shared Combobox affordance
-  track; its clear sits beside a chevron aligned with Select's.
-- **Visual: Badge `sm` and `md` are 2px taller** (20px and 23px) at the same
-  type size; inline badges are unchanged, and TagsInput chips follow.
-- **NavigationTabs** keeps the current tab lifted under hover and press;
-  inactive tabs change colour only.
-- **SignaturePad** draws, exports and previews typed names in the pad's font
-  (theme sans by default) instead of `cursive`, and fits long names by font
-  size; `signaturePadToSVG` accepts an optional `fontFamily`.
-- **Fixes:** Dropzone centres both copy lines; IconBadge sizes child glyphs with
-  its icon role (SmartAccordion medallions render at 16px); Alert's icon and
-  action columns use Toast's 8px gap; content typography fits images to the
-  column.
-- **Catalogue:** the deprecated Sheet page, the products main-column, actions
-  and support-rail pages and the sync page are retired; their URLs redirect to
-  the overlays, product overview and SchemaForm pages.
-- **BatchActionBar** (`themelia-react-ui/base/batch-action-bar`): one selection
-  bar with a count, bulk actions and Clear, `floating` (docked, lifted, opaque)
-  or `inline`. The count is a polite live region, Escape inside the bar clears,
-  and focus returns to the list (or `returnFocusRef`) when the bar goes away.
-  DataTable, product variants and MediaLibrary's new `bulkActions` use it; the
-  old sticky selection toolbar and its overlap with the sticky topbar are gone.
-- **Order blocks** in `blocks/commerce`: `OrderHeader` (payment and fulfilment
-  status axes), `FulfillmentGroup`, `OrderLineItem`, `OrderSummary`,
-  `OrderTransactions` and `OrderCustomer`, with an Orders catalogue group and an
-  Order detail composition. The shared money ledger `SummaryPanel` and
-  `AmountRow` now draw CartSummaryCard, TaxBreakdownCard, DiscountStackPreview,
-  InvoiceHeader and OrderSummary: no tinted box, one rule above a grand total.
-- **Commerce blocks follow the source kit.** ShipmentTracking has a copyable
-  tracking number (`onCopyTracking`) and a timestamped checkpoint rail whose
-  current step is `aria-current="step"`; RefundStatusCard is an ordered list of
-  stages; PaymentMethod gains `variant="row"` and speaks `strings.formatCard`
-  ("Visa ending 4242"); CartSummaryCard falls back to initials on a failed image
-  and adds `strings.formatQuantity`; DiscountStackPreview takes an optional
-  `kind` and `id`. Blocks pass native attributes to their root. `CartSummary`,
-  `DiscountStack`, `RefundStatus` and `PaymentMethodCard` are added as the source
-  kit's names for the same components. `Timeline` items expose `data-status` and
-  mark the current item `aria-current="step"`.
-- **MetadataList** labels wrap in every layout and stay semibold; inline
-  `itemSeparator` is a middle dot hidden from screen readers; `render` output
-  takes the value style; the info trigger no longer grows its line; `icon` takes
-  any `ComponentType<{ className?: string }>`.
-- **TagsInput fixes.** Multi-tag paste commits every tag, `sortTags` removes the
-  right tag, object tags are created from an empty value, a refused entry no
-  longer traps Tab, IME composition no longer commits, a typed delimiter splits,
-  single-token paste is native, and focus moves to the neighbouring chip after a
-  removal. Refused entries stay in the draft and are announced
-  (`strings.notAdded`). New `defaultValue`, `name` (hidden `name[]` inputs) and
-  ARIA pass-through; `TagsInputStrings` and `defaultTagsInputStrings` are
-  exported.
 
 ## 2.0.0 — 2026-10-16
 

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.1`** · MIT licensed.
+Package: **`themelia-react-ui`** · current version: **`2.0.2`** · 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
@@ -41,7 +41,26 @@ Browser verification requires Playwright Chromium. An existing executable can be
 
 ## Consumer setup
 
-Install a built tarball; use a registry release when available. React 19, React DOM 19, Base UI 1.8+ and Lucide React 1 are required peers. Import exact family paths; there is no aggregate component barrel or public raw UI entrypoint.
+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
+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.2 requires the companion `base-ui-react-1.8.0-kpo.2.tgz`
+archive. It adds the public `Combobox.Root.dismissLabel` translation seam for both
+screen-reader dismissal controls and preserves focus already restored inside a
+parent popup when a nested popup closes. Install both versioned archives together; no
+public registry release is required. The source checkout keeps the Base UI archive
+beside `package.json` and pins it through the lockfile for reproducible `npm ci`.
+
+```sh
+npm install ./themelia-react-ui-2.0.2.tgz ./base-ui-react-1.8.0-kpo.2.tgz
+```
+
+The source checkout retains `base-ui-react-1.8.0-kpo.2.patch`; its upstream
+provenance and license are recorded in `THIRD_PARTY_NOTICES.md`.
 
 After the initial registry release, install into a React 19 application with:
 
@@ -95,7 +114,7 @@ The shipped stylesheet follows `prefers-reduced-motion` automatically for these
 | Base | `base/<family>` — controls, forms, buttons, cards, structure, navigation, menus, feedback, display, tables, uploads and specialist controls |
 | Layout | `layout`, `layout/<family>` — application shell, authentication, containers, page, settings, header, navigation, sidebar, workspace and hooks |
 | Blocks | `blocks/admin`, `ai`, `analytics`, `commerce`, `data-display`, `onboarding`, `timelines` (each prefixed `blocks/`) |
-| Features | `features/activities`, `ai-chat`, `async-preview`, `combobox`, `comments`, `data-view`, `email-composer`, `event-calendar`, `filters`, `global-search`, `kanban`, `map`, `media-library`, `mentions`, `overlays`, `products`, `resource`, `resource-assignment`, `rich-text-editor`, `schema-form`, `suggestions`, `sync` (deprecated), `table`, `theme-tweaker` (each prefixed `features/`) |
+| Features | `features/activities`, `ai-chat`, `appointment-calendar`, `async-preview`, `combobox`, `comments`, `data-view`, `email-composer`, `event-calendar`, `filters`, `global-search`, `kanban`, `map`, `media-library`, `mentions`, `overlays`, `products`, `resource`, `resource-assignment`, `rich-text-editor`, `schema-form`, `suggestions`, `sync` (deprecated), `table`, `theme-tweaker` (each prefixed `features/`) |
 
 The complete machine-readable entry inventory is `scripts/entries.json`. Dialogs and confirmations use `ActionDialog`, `ActionDrawer`, `ConfirmDialog` and visibility/action hooks from `features/overlays`.
 
@@ -201,7 +220,7 @@ The default development URL opens the full component catalogue. The focused foun
 
 `Button` separates `tone` from `buttonStyle` (`solid`, `outline`, `ghost`); the catalogue shows their matrix, sizes and loading/disabled states. Icon-only controls may omit children when an accessible label or tooltip is supplied. Badges use compact typography and insets rather than inheriting action geometry.
 
-Use `titleSuffix` for card status, count and version badges. `headerStart` is full-width pre-title context, and `headerAction`/`actions` own controls. Card owns token-spaced title/suffix wrapping for all surface modes. Give a card one quick control in `headerAction`, a command list in `actions` (its More actions menu) and the commit action in `footerSlot`; spacing, not a divider, separates the footer. Reserve body actions for a specific content step. Card owns aligned card insets, frames and expand/collapse behavior; Use `Card surface="flat" padding="none"` for card-free content hierarchy. ChartCard exposes `titleSuffix` too. Use `headerPlacement="frame"` for a header above an inset body. SmartCard and ContentBlock remain deprecated migration adapters; new code uses Card.
+Use `titleSuffix` for card status, count and version badges. `headerStart` is full-width pre-title context, and `headerAction`/`actions` own controls. Card owns token-spaced title/suffix wrapping for all surface modes. Give a card one quick control in `headerAction`, a command list in `actions` (its More actions menu) and the commit action in `footerSlot`; a framed card rules the footer off by default. Reserve body actions for a specific content step. Card owns aligned card insets, frames and expand/collapse behavior; Use `Card surface="flat" padding="none"` for card-free content hierarchy. ChartCard exposes `titleSuffix` too. Use `headerPlacement="frame"` for a header above an inset body. SmartCard and ContentBlock remain deprecated migration adapters; new code uses Card.
 
 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.
 
@@ -222,9 +241,10 @@ 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
-gaps. Ordinary cards retain default `md` padding and separate header, body and
-footer by spacing; `card.defaultHeaderDivider` and `card.defaultFooterDivider`
-remain for an app whose design calls for rules.
+gaps. Ordinary framed cards retain default `md` padding and rule header, body and
+footer apart by default; flat, card-free structure draws no rule unless asked. Set
+`card.defaultHeaderDivider` and `card.defaultFooterDivider` to `false` for an app
+that separates card regions by spacing alone.
 AppSidebar offers pinned `slots.headerStart`/`headerEnd` around its workspace
 region, compact navigation and a separated footer. The
 [complete shell recipe](docs/consumer-skill/examples/app-layout.tsx) demonstrates
@@ -289,7 +309,7 @@ purpose from its name or read every document before starting a screen.
 
 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.1/` 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.2/` 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.
 

package/THIRD_PARTY_NOTICES.md

@@ -27,6 +27,19 @@ SOFTWARE.
 
 External dependencies retain their own licenses and notices in their packages.
 
+## Base UI private accessibility build
+
+This private build requires `@base-ui/react@1.8.0-kpo.2`, supplied as the companion
+`base-ui-react-1.8.0-kpo.2.tgz` archive. It derives from the official Base UI v1.8.0
+source at commit `47b40521eab921c2756bf9bdb0b0f07fbfdb8c8c`
+([upstream source](https://github.com/mui/base-ui/tree/47b40521eab921c2756bf9bdb0b0f07fbfdb8c8c)).
+The additive `Combobox.Root.dismissLabel` prop supplies both screen-reader
+dismissal controls. The companion also guards delayed parent-popup focus
+restoration so a nested popup can return focus to its original trigger.
+The library source checkout retains the related patch as
+`base-ui-react-1.8.0-kpo.2.patch`. Base UI's MIT license is retained inside the
+companion archive; its copyright and permission notice remain unchanged.
+
 ## Email composer reference
 
 The email composer public types and HTTP adapter adapt the supplied MIT-licensed

package/dist/{accordion-B6a3vVgA.js → accordion-Cjb6sx0G.js}

@@ -1,13 +1,13 @@
 "use client";
 import { useStrings as e } from "./lib/strings.js";
-import { t } from "./utils-l5LpDw2z.js";
-import { s as n } from "./typography-DTRkE9zL.js";
+import { t } from "./utils-BRhFDwuU.js";
+import { c as n } from "./typography-UTnveOEy.js";
 import { t as r } from "./focus-recipes-B653VaLq.js";
 import { t as i } from "./motion-recipes-ChBg4HBq.js";
-import { t as a } from "./structure-DC2dygdA.js";
-import { t as o } from "./interaction-recipes-CHr0dJUs.js";
+import { t as a } from "./structure-BmisBK-3.js";
+import { t as o } from "./interaction-recipes-XR9ZpVYL.js";
 import { t as s } from "./disclosure-panel-B0HFNZ9x.js";
-import { t as c } from "./icon-badge-CAuKupo9.js";
+import { t as c } from "./icon-badge-DYKIwvOV.js";
 import * as l from "react";
 import { forwardRef as u } from "react";
 import { jsx as d, jsxs as f } from "react/jsx-runtime";
@@ -45,7 +45,7 @@ function _({ className: e, children: n, ...r }) {
 function v({ className: e, children: n, render: r, ...a }) {
 	return /* @__PURE__ */ d(m.Panel, {
 		"data-slot": "accordion-content",
-		className: t("accordion-content--component box-border text-foreground h-(--accordion-panel-height)", i.disclosure, e),
+		className: t("accordion-content--component box-border text-inherit h-(--accordion-panel-height)", i.disclosure, e),
 		...a,
 		render: (e, t) => /* @__PURE__ */ d(s, {
 			props: e,
@@ -61,7 +61,7 @@ function v({ className: e, children: n, render: r, ...a }) {
 var y = l.forwardRef(function({ className: e, ...n }, r) {
 	return /* @__PURE__ */ d(h, {
 		ref: r,
-		className: t("accordion--component rounded-radius border-border bg-card", e),
+		className: t("accordion--component rounded-radius border-border bg-card text-card-foreground", e),
 		...n
 	});
 });
@@ -78,7 +78,7 @@ var x = l.forwardRef(function({ className: e, children: i, ...a }, s) {
 	let c = typeof i == "string" || typeof i == "number" || typeof i == "bigint";
 	return /* @__PURE__ */ d(_, {
 		ref: s,
-		className: t("accordion-trigger--component min-h-action items-center gap-space-lg px-row-x py-row-y", `text-start text-sm font-medium transition-colors ${o.rowHover} hover:no-underline`, `focus-visible:z-10 ${r.inset}`, e),
+		className: t("accordion-trigger--component min-h-action items-center gap-space-lg px-row-x py-row-y", `text-start text-inherit text-sm font-medium transition-colors ${o.rowHover} hover:no-underline`, `focus-visible:z-10 ${r.inset}`, e),
 		...a,
 		children: c ? /* @__PURE__ */ d(n, {
 			tag: "span",
@@ -110,11 +110,11 @@ S.displayName = "AccordionContent";
 //#endregion
 //#region src/components/base/accordion/accordion-variants.ts
 var C = {
-	card: "gap-space-md border-0 rounded-none bg-transparent overflow-visible",
-	bordered: "rounded-radius border border-border bg-card overflow-hidden",
-	flat: "border-0 rounded-none bg-transparent overflow-visible"
+	card: "gap-space-md border-0 rounded-none bg-transparent text-inherit overflow-visible",
+	bordered: "rounded-radius border border-border bg-card text-card-foreground overflow-hidden",
+	flat: "border-0 rounded-none bg-transparent text-inherit overflow-visible"
 }, w = {
-	card: "border border-border bg-card rounded-radius overflow-hidden",
+	card: "border border-border bg-card text-card-foreground rounded-radius overflow-hidden",
 	bordered: "bg-transparent not-last:border-b border-border",
 	flat: "border-0 not-last:border-b-0 bg-transparent rounded-radius overflow-hidden"
 }, T = "items-center gap-space-lg px-row-x py-row-y text-start hover:no-underline", E = {
@@ -153,6 +153,7 @@ var C = {
 							className: "flex min-w-0 flex-wrap items-center gap-x-space-md gap-y-space-xs",
 							children: [k(e.title) ? /* @__PURE__ */ d(n, {
 								tag: "span",
+								type: "inherit",
 								weight: "semibold",
 								className: "smart-accordion--title min-w-0",
 								children: e.title
@@ -204,4 +205,4 @@ function A({ iconStyle: e, icon: n, reserveSpace: r }) {
 //#endregion
 export { C as a, S as c, w as i, b as l, D as n, T as o, E as r, y as s, O as t, x as u };
 
-//# sourceMappingURL=accordion-B6a3vVgA.js.map
+//# sourceMappingURL=accordion-Cjb6sx0G.js.map