themelia-react-ui 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -1,5 +1,532 @@
 # 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
+drift checks found, and one command row and record-page recipe for every page
+header. No public export or prop is removed. Additions: `header.tabs` on Page
+(`PageHeaderTabs`); `primaryAction`, `secondaryActions`, `moreActionsLabel` and
+`renderLink` on PageHeading, ResourceHeader, the resource shells and
+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. `PageActions`, `PageAction` and `toPageAction` are deprecated.
+
+### Upgrading from 2.0.0
+
+- **Focus and control borders.** Library controls draw the soft `--input`
+  boundary and one shared focus indicator. Drop `ring-2`, `ring-offset-*` or
+  full-strength `ring-ring` focus classes passed to library controls; the
+  consumer checker reports them as `focus-ring-recipe`. Themes that override
+  `--ring` should keep it at 3:1 against their surfaces.
+- **Page commands.** Replace a `PageActions` ribbon or hand-built buttons in a
+  header's `actions` with `primaryAction` (one) and ordered `secondaryActions`;
+  mark irreversible commands `destructive: true` and confirm them in the
+  handler. `actions` stays for non-command controls such as a period select.
+  Move section tabs placed at the top of a Page body into `header.tabs`. The
+  consumer checker reports the old shapes as `page-command-roles`.
+- **Overflow trigger names.** Overflow triggers are named "More actions" by
+  default. This replaces "Open menu" (`ActionMenu` `strings.openMenuLabel`),
+  "Card actions" (Card `actionsLabel`), "Actions" (ContentBlock and DataTable
+  row menus) and "Page actions" (`PageActions` `strings.menuLabel`). Update
+  tests or automation that find these buttons by name, or pass the old copy
+  through those strings. The DataTable actions column header stays "Actions"
+  (`strings.actions.triggerLabel`); the row trigger's name moves to the new
+  `strings.actions.menuLabel`. Copy that sets only `triggerLabel`, as localized
+  tables did before, keeps naming the trigger with it.
+- **Overflow trigger size and glyph.** An icon-only `ActionMenu` trigger now
+  follows `UIProvider.density.defaultScale` instead of always rendering at
+  `md`; pass `buttonProps.size` to match the controls beside it. The default
+  glyph is the horizontal ellipsis (`MoreHorizontal`) rather than
+  `MoreVertical`; `icon` still overrides it.
+- **State styling.** Hover, selection, pressed, status-tint, divider, disabled,
+  motion, corner and stacking classes passed to library rows and tiles should
+  follow the shared roles below. Pressed toggles, including AI feedback votes,
+  editor formatting buttons and the editor's source view, show the accent fill
+  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.
+
+### Changes
+
+- **Visual: the More actions menu ends the page header's command row.** Page
+  commands render as the secondary commands, then the primary command, then the
+  More actions menu (`[secondary…] [primary] [⋯]`); 2.0.0 placed the menu
+  between the secondary and primary commands. The menu trigger takes the
+  secondary treatment, an outline square at the commands' own height, including
+  under a compact `UIProvider` scale; it was a ghost glyph at the default size.
+- **Visual: one overflow trigger.** Every overflow menu shares one `ActionMenu`
+  trigger recipe (`action-menu.recipes.ts`). It draws the `⋯` glyph, is named
+  "More actions", and is a square at the size of the controls beside it, or at
+  the provider scale when nothing sits beside it. `context="inline"`, the
+  default, is a quiet ghost square with a muted glyph for rows, cards and
+  footers. `context="commands"` is the outline square beside outline commands,
+  which the page header's More actions trigger now takes from the recipe.
+  Card headers, DataTable rows, Kanban items and the EmailComposer footer
+  follow the provider scale. Activity rows and ApiKeyList match their own
+  compact expand and add controls. `PageActions` uses the outline treatment at
+  its inline `size`. The library no longer hand-sets trigger sizes, styles or
+  glyphs.
+- **The menu ends any row with a primary command.** The EmailComposer footer
+  renders `[Discard] … [Send] [⋯]`, where 2.0.0 placed the menu before Send.
+  Send and the menu wrap together, so the menu never sits alone on a narrow
+  line.
+- **One menu per header, destructive commands last.** `ProductVariantDetails`
+  merges its default variant commands (Open, Edit, Duplicate, Delete) into the
+  card's own `actions` menu. Its header no longer shows a second, differently
+  sized `⋯`, and Delete sorts last. A custom `renderActions` still renders in
+  the header. The product variants bulk bar places Delete after Apply and any
+  `renderBulkActions` content.
+- **Overflow trigger enforcement.** The `overflow-trigger` rule in
+  `check:contract` rejects overflow glyph imports outside the ActionMenu owner,
+  raw UI, pagination and the OverflowTabBar More tab. It also rejects icon-only
+  `ActionMenu` triggers that set `tone`, `buttonStyle`, `iconOnly` or
+  action-size classes through `buttonProps`.
+  `tests/browser/overflow-trigger.spec.ts` checks order, heights and every
+  opened menu at 390px and 1440px in light and dark.
+- **One command row for every header.** PageHeading owns the role-based row,
+  and `PageHeaderAction` moves to `base/navigation` (still exported from
+  `layout/page`). Page and PageHeader pass their commands to it; ResourceHeader,
+  ResourceIndexShell, ResourceShowShell and TabbedResourceShell
+  (`ResourceHeaderCommandProps`), SettingsShell and WorkspaceRecordHeader take
+  the same `primaryAction` and `secondaryActions` and render the same row after
+  their custom `actions`. WorkspaceRecordHeader's `secondaryActions` accepts
+  command objects; rendered elements keep their previous cluster.
+- **Section tabs in the page header.** `header.tabs` renders a record's
+  sections under the header's copy and commands with the shared OverflowTabBar:
+  `badge` shows a count, tabs that do not fit move into a More menu, the active
+  tab stays visible, and `onValueChange` switches the section or routes.
+- **Deprecated `PageActions`.** Its ribbon defaulted inline commands to solid
+  secondary buttons beside a larger ghost menu trigger and collapsed by viewport
+  width. Pass commands by role instead, or use ActionButtons for a toolbar.
+  `toPageHeaderAction` adapts a resolved action to a role-based command, with a
+  destructive tone marking it destructive.
+- **One record-page recipe.** The detail recipe, the resource-detail build
+  recipe and a new Page example show a record with one status badge,
+  role-based commands, a confirmed destructive command and section tabs with
+  counts. Catalogue examples for PageHeading, resources, workspaces, settings,
+  app shells and tables use role-based commands; the consumer docs no longer
+  recommend card dividers, footer command rows or decorative title icons.
+- **Consumer checker.** `page-command-roles` also flags PageActions,
+  ActionButtons and ActionMenu in a header's `actions`, and covers PageHeading,
+  the resource shells, WorkspaceRecordHeader and SettingsShell.
+  `decorative-icon` flags a page `titleIcon` without a link or handler, and an
+  icon on more than one page command. `raw-button` no longer flags a native
+  button passed as a package owner's `render`, such as an Item row rendered as
+  a button; the owner keeps that root's focus edge and row anatomy. Local
+  components passing a native button are still reviewed.
+- **Teaching material follows the house rules.** Catalogue examples, templates
+  and the shipped consumer examples use an untoned Button for neutral commands
+  (a `tone="secondary"` Button without `buttonStyle` renders solid), spell
+  neutral badges `tone="neutral"`, space siblings with Stack, Grid and
+  AdaptiveGrid instead of flex/grid gap divs or `space-y` margins, and drop
+  decorative title tiles. The order, product, customer, staff and overview
+  templates keep Page's default measure; the order template's fulfillment is
+  its `header.primaryAction`, the staff template's suspension is a
+  `destructive: true` secondary action confirmed by ConfirmDialog, and neither
+  repeats the header's status badge in a card or fact list.
+- **Agent guidance closes the loop.** The consumer skill ships a project
+  instructions block (`references/agents-md.md`) to paste into an app's
+  `AGENTS.md`: under 2,000 characters, version-stamped in its start marker,
+  generated and verified by `check:skill`, and naming only scripts that ship
+  with the skill. The installed identity recipe reports the block as missing,
+  current or stale. SKILL.md and the review guide now make the composition
+  checker the agent's done condition (no errors on changed files, at most three
+  fix rounds, then the app's typecheck, lint and tests) with a five-line
+  hand-back, instead of calling it optional.
+- **Consumer-skill evals.** `evals/consumer-skill` holds eight admin tasks,
+  five of them temptations such as a red Delete button or hand-made KPI cards,
+  each with a reference and a naive solution. `scripts/consumer-evals.mjs`
+  scores agent outputs with the shipped checker, imports and source patterns,
+  and `check:agent` proves every reference passes and every naive version fails.
+- **Fix: destructive activity actions.** ActivityFeed row menus passed the
+  action tone as an unknown `variant` field, so a destructive action lost its
+  destructive treatment and its place at the end of the menu.
+- **Visual: one control boundary and one focus indicator.** `--input` is the
+  single control boundary: fields, select and date triggers, checkboxes, radios,
+  switch tracks, upload targets and outline buttons all draw it, so adjoining
+  controls read as one family. It is now soft and translucent
+  (`oklch(0.28 0 0 / 15%)` in light, white at 15% in dark) and reads the same on
+  every surface, replacing the 3:1 gray of 2.0.0 (`oklch(0.62 0 0)`, white at
+  40% in dark) that made fields and selects read darker than the outline buttons
+  beside them; `--border` stays the divider color, and the repeater's empty
+  placeholder uses it. Every focused element draws one indicator from
+  `src/lib/focus-recipes.ts`: a 1px `--ring` edge at full strength (the
+  control's own border, an inset edge on borderless rows and regions, or an
+  outline just outside link and text-button glyphs) inside a soft 3px halo of
+  `--ring` at 50%. It replaces the 2px full-strength and offset rings, which
+  read as a heavier border. The edge carries the 3:1 contrast. An invalid field
+  keeps its destructive border at rest and while focused, where the halo turns
+  destructive; there is no resting halo. Focus on a MediaGallery tile is drawn
+  inside the tile, where its overflow clipping had hidden it. Design lint's
+  `focus-ring-recipe` rule (replacing `focus-ring-contrast`) rejects other focus
+  ring widths, offsets and halo strengths in library source and on imported
+  consumer controls. The contrast contract keeps `--ring` and `--sidebar-ring`
+  at 3:1 and checks `--input` against a 1.3:1 visibility floor on background,
+  card, popover, muted, accent and secondary surfaces.
+- **Visual: one recipe per state family.** Each family that had several local
+  spellings now has one owner and a design-lint rule that cannot acquire
+  migration debt.
+  - Rows (navigation, lists, trees, results, menus) hover and select with
+    `--accent`, and the current location adds medium weight, so a hover never
+    reads as current. Ghost and outline buttons hover with the same fill and its
+    `--accent-foreground`; a component's own hover colour still wins.
+  - Toggles hover with `--muted` and press with `--accent`. Tables keep a
+    quieter `muted` ladder for stripes, hover and selection. Segmented tracks
+    lift the active segment to `--card`.
+  - Text never takes opacity: faded secondary text, which fell under 4.5:1, uses
+    the typography roles.
+  - Dividers are `--border` at full strength on surface edges and at 60% between
+    rows.
+  - Disabled content dims once, to 50%.
+  - Status and emphasis tints use one scale per tone
+    (`src/lib/tone-recipes.ts`): a wash for large surfaces, a tint for chips,
+    badges and icon tiles, and an edge, halo and line strength. The contrast
+    contract tests each tone's ink on its tint. Badges, alerts, avatars, icon
+    tiles, activity, search, calendar, timeline, commerce and AI blocks share
+    it. Search matches and edit diffs use one inline mark, and the heatmap and
+    distribution ruler keep their data ramps.
+  - Colour, border and shadow state changes keep the default 150ms transition.
+  - Corners derive from `--radius`: the fixed 4px `rounded` and the t-shirt
+    steps in raw UI, skeletons and chips are gone.
+  - Stacking uses one scale: raised, sticky, sticky over sticky, chrome and
+    overlay.
+  - SectionNav links gain the shared focus indicator, borderless Item rows draw
+    the focus edge inset, and the column-resize handle marks focus in the ring
+    colour.
+  - Neutral fills use one strength per role: a wash for quiet regions, a band
+    for header, toolbar and footer strips, a solid track, a neutral chip and
+    neutral markers. Twenty strengths become five. Table heads, toolbars, empty
+    states, AI panels, auth and workspace regions, tab tracks, meters and
+    carousel dots share them.
+  - Elevation uses one theme shadow per role: resting, card, raised, lifted and
+    modal. The command palette's 2xl shadow, two custom table-frame shadows
+    (which glowed in dark mode) and a shadow colour override are gone.
+  - Keyboard-shortcut hints in the header search trigger and the global search
+    footer share one key-cap style.
+  - Floating chips over media, lifted panels over the auth art and the chat
+    composer band are opaque.
+  - A drift census budgets each family's vocabulary in `check:design-lint`, and
+    a rendered role-parity browser check measures hover, current, disabled and
+    focus in light and dark.
+- Rich-text toolbar toggles announce their state. Built-in format buttons and
+  the source view expose `aria-pressed`; undo and redo do not.
+  `ToolbarButtonConfig` and `RichTextEditorToolbarItem` gain an optional
+  `toggle` flag; an extra toolbar item with `isActive` is a toggle unless it
+  sets `toggle: false`.
+- Item titles that cannot fit end in an ellipsis on their text. The title row is
+  a flex container, where `text-overflow` has no effect, so a long token was
+  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`.
+
 ## 2.0.0 — 2026-10-16
 
 A major release. Untouched defaults now give a screen one deliberate primary

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.0`** · 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`, `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,28 +220,42 @@ 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. Put card-level actions in `footerSlot` with `footerDivider`; 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.
 
-Page header commands are role-based: one `primaryAction` and ordered
-`secondaryActions`, with overflow, destructive commands and narrow widths moved
-into a More actions menu. Keep `actions` for non-command controls.
+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,
+WorkspaceRecordHeader and SettingsShell share that row; keep `actions` for
+non-command controls. `header.tabs` puts a record's section tabs, with counts,
+under its header.
+
+Every overflow menu shares one `ActionMenu` trigger: the `⋯` glyph named "More
+actions", a quiet ghost square in rows and cards (`context="inline"`, the
+default) or an outline square beside outline commands (`context="commands"`),
+at the size of the controls beside it (`buttonProps.size`) or the provider
+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
-gaps. Ordinary cards retain default `md` padding; configure header/footer rules
-through UIProvider's `card.defaultHeaderDivider` and `card.defaultFooterDivider`.
+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
 public workspace/account controls and application-owned callbacks.
 
 Choose one ordinary card surface through `card.defaultSurface`; explicit per-card
-surfaces win. Use Card's `icon` slot for routine header icons and `headerPlacement`
-to choose inside/frame composition independently. Independent framed peers
-usually use `gap="xl"`, since outer rings consume a smaller DOM gap.
-MetadataList retains medium labels and normal primary values in both densities.
+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.
 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).
@@ -276,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.0/` 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.