themelia-react-ui 1.0.2 → 2.0.1

package/CHANGELOG.md

@@ -1,6 +1,637 @@
 # Changelog
 
-## Unreleased
+## 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; `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.
+
+### 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.
+- **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
+
+- **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`.
+- **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
+
+A major release. Untouched defaults now give a screen one deliberate primary
+command, neutral surfaces where colour only states status, and the overlay
+family for every dialog-like surface. Public exports and props are retained (the
+contract check keeps every public symbol); what changes is defaults, appearance,
+a few DOM hooks and some semantics.
+
+### Upgrading from 1.x
+
+- **Buttons.** An untoned `Button` is the neutral outline. Give each screen's
+  main command `tone="primary"`, run
+  `docs/consumer-skill/scripts/pin-button-defaults.mjs` (dry run by default,
+  `--write` to apply) to keep existing screens' look, or restore the old default
+  app-wide with `UIProvider` `button: { defaultTone: 'primary',
+  defaultButtonStyle: 'solid' }`.
+- **Brand colour.** The default primary is near-black. Import
+  `themelia-react-ui/themes/green.css` after `style.css` to keep the green brand.
+- **Badges.** An untoned `Badge` is neutral; `UIProvider`
+  `badge.defaultTone: 'primary'` restores the old default.
+- **Page titles** are the route's `h1` at 20px; pass `headingTag="h2"` for a page
+  nested inside another titled page.
+- **Overlays.** Replace the deprecated base `Sheet` exports with `ActionDrawer`
+  from `features/overlays`. `ConfirmDialog` shows its tone icon only with
+  `showIcon`. Scrims no longer blur, and dialog regions draw no header or footer
+  rules.
+- **Formatted text.** Negative numbers print with a true minus (U+2212) instead
+  of a hyphen; update tests, snapshots or parsers that match formatted output.
+- **Decorative icons and dividers** are gone from the library's own blocks,
+  features and templates. Public `icon`/media props and Card `headerDivider`/
+  `footerDivider` remain for products that need them; `adminStarterUIDefaults`
+  no longer turns card dividers on.
+- **DOM hooks.** `InventorySectionCard` exposes card hooks instead of
+  `content-block--*`, and `seo-listing-card--score-icon` is removed.
+
+### Changes
+
+- **Breaking (visual): overlays have no blur and no static rules, and they are
+  the only dialog API.** The modal scrim is a plain `--overlay-backdrop` tint.
+  Dialog, alert-dialog and drawer regions draw no header/footer rules or tinted
+  footer: the shell owns a 20px outer inset and 16px between regions, and a
+  scrolling body shows a rule only on an edge that hides content. Surfaces use
+  one border on `bg-popover`; drawers draw one rule on their open edge. The
+  close button is centred on the first title line and comes last in the DOM, so
+  opening focuses the first field or action. `ConfirmDialog` matches
+  `ActionDialog` widths, supports `surfaceStyle` and shows no tone icon unless
+  `showIcon`; emphasis no longer tints the border; a non-modal `ActionDrawer`
+  stays open on page presses; `initialFocusRef` accepts nullable React 19 refs;
+  a string `trigger` renders a Button. The base `Sheet` exports are deprecated
+  in favour of `ActionDrawer`. DataTable's in-place `fullscreen` mode stays the
+  one modal surface outside the overlays: the table's own region is maximised,
+  so its scroll position, focus and column state survive, and the contract
+  check (`modal-owner`) rejects any other hand-built modal or borrowed
+  Dialog/Sheet in library source. The consumer skill (house rule 9 and a dialogs
+  section) and the checker (`raw-overlay-primitive` for `role="dialog"`,
+  `aria-modal`, `fixed inset-0` layers and modal libraries; `deprecated-owner`
+  from the public index) enforce the overlay owners. Nothing in the library uses
+  `backdrop-filter` any more: sticky table headers and toolbars, the form
+  actions bar, carousel controls and upload overlays are opaque.
+- **Inline values follow running text.** Inside `Text`, `Heading`, `Label`,
+  `TextLink`, `ItemTitle`/`ItemDescription` and `CardDescription`, value
+  primitives (`Value`, `MonoValue`, `Money`, `Number`, `Percent`, `Duration`,
+  `FileSize`, `Dimensions`, dates, links) take the sentence's size, colour,
+  weight and leading unless a prop says otherwise; standalone use is unchanged.
+  `Initials` inherits by default. Text `type`/`weight`/`lineHeight` accept
+  `'inherit'`. Empty values share the `EmptyValue` treatment.
+- Negative numbers print with a true minus (U+2212) in every formatter and
+  number primitive (`formatWithMinusSign` in `lib/format`).
+- Form controls share one geometry and state contract: every field and
+  field-shaped trigger is the same height, radius, `--input` border, text size
+  (16px on touch) and 2px focus ring; a keyboard-focused invalid field shows a
+  full-strength destructive ring; select-like chevrons share
+  `selectToggleRecipes` (16px glyph centred where the Select draws it);
+  Textarea's first line aligns with an Input's text; field triggers no longer
+  take a button hover fill; disabled inputs lose the read-only fill. Checkbox
+  shows a dash when indeterminate; choice cards mark selection with the border
+  only; pill radios get roving arrow-key focus; DecimalInput steps with arrow
+  keys and keeps uncontrolled values; DatePicker gains `id`/`invalid` and no
+  longer reddens its label; DateTimeInput passes `stepMinutes` correctly;
+  Cascader gets an inline clear; Combobox Escape on a closed field keeps the
+  value and reaches the surrounding overlay. A Combobox reserves its whole
+  toggle (and clear) target plus the copy gap, so a long value never runs under
+  a target at any density. A one-line text button is exactly its action height
+  at every spacing and density (its block inset is capped); wrapped labels
+  still grow the button.
+- Display and navigation: Badge follows its parent's alignment (no
+  `self-center`); flat/`padding="none"` Cards use the 16px header-to-body gap;
+  the default outline button border is visible in dark; `TextButton` md is
+  `text-sm`; ButtonGroup seams and corners are fixed; untoned ActionButtons are
+  neutral; menu group captions use the xs secondary role; OverflowTabBar gets
+  arrow/Home/End keys and the shared 36px recipe; active tabs read above the
+  track in dark; pagination links are 36px squares; accordion focus is inset
+  with no open tint; toaster status icons reach 5:1; code diffs use tints;
+  StackedAvatars fallbacks are neutral; tables render rules without preflight
+  and are a tab stop only while they overflow. `PageHeading` `withSeparator`
+  defaults to `false`.
+- Typography: Heading `tracking-tight` from xl and `leading-tight` from 2xl;
+  link focus rings hug the text and follow wrapped lines; text, headings and
+  money align with logical start/end so they mirror in RTL.
+- Scoped density: arbitrary values no longer read derived `--spacing-*` aliases
+  (resolved once on `:root`), so tracks, insets and offsets follow a
+  `data-density` scope.
+
+- **Breaking (visual): visual restraint pass.** Icons now carry information
+  or are omitted, colour only states status, and spacing, not rules, separates
+  sections. Public `icon`/media props remain for consumers; the library's own
+  compositions stop passing decorative ones.
+  - Rows: a plain `Item` (default variant, no inline padding) in an `ItemGroup`
+    sits flush with the group's top and bottom edges, plain rows touch so their
+    density padding is the row spacing, and the default variant drops its
+    transparent 1px border so row text aligns with headings and labels above
+    it. Boxed `outline`/`muted` rows keep their gap. This fixes uneven space
+    around dividers and at card bottoms (8px above a rule against 17px below
+    it, 30px at a card's bottom against 20px at its top on the order page).
+  - Blocks and features no longer hard-code decorative icons on card titles
+    (address, payment method, order/refund status, tax breakdown, subscription,
+    voucher, coupon, cart, inventory, SEO listing, every product section, sensitive
+    actions, AI confirmation/tool call/package info/citation), on metadata and
+    list rows, inside inputs and badges, or on ordinary text buttons. Kept:
+    icon-only buttons, menu and navigation icons, affordances, search glyphs,
+    `+` on add commands, state glyphs, event-type markers and real media.
+  - Colour states status: kinds, categories and counts are neutral; live and
+    in-progress states use `info` instead of the near-black primary;
+    `LoyaltyPoints` `tierTone` defaults to `neutral` (was `warning`); activity
+    events without a status tone are neutral; product rows render
+    `tone="primary"` neutral; micro-grid single-series charts use `--chart-1`.
+  - No boxes inside cards and no section rules: tinted or bordered inset panels,
+    stat tiles and per-section dividers are gone across commerce, data-display,
+    AI, admin, product, activity, resource-assignment, schema-form, sync and
+    media-library compositions. One rule stays above financial grand totals.
+    Status chips sit beside their title (`titleSuffix`).
+  - Amounts and dates use the UI font with tabular figures; monospace stays for
+    identifiers and codes.
+  - Sentence-case default strings across commerce, admin, AI and dense-info
+    blocks (for example `Refund status`, `Tax breakdown`, `Redeem points`,
+    `View details`, `Edit role`, `Next step`). `DenseInfoStrings` gains an
+    optional `priority`.
+  - `ActivityLog` shows a category chip only when an entry passes `label` (it no
+    longer falls back to the raw `kind`), and date groups read `Yesterday` and
+    `October 14, 2026` instead of uppercase eyebrows with ordinals.
+  - `DateCell` and `DateMetaCell` `showIcon` default to `false`;
+    `GlobalSearchIdleState` headings have no default icons; `PageHeader` has no
+    separator after the back button; `AppSidebar` groups are separated by space
+    instead of rules; navigation count badges stay neutral when active.
+  - `OrderStatus` drops the facts that repeated its badge and timeline;
+    `LoyaltyPoints` shows Redeem only with `onRedeem`; vouchers show a balance
+    only when one is given; `InventorySectionCard` renders through `Card`, so its
+    `content-block--*` hooks become card hooks, and `seo-listing-card--score-icon`
+    is removed.
+  - Base fixes: `ActionMenu`'s icon-only trigger follows `buttonProps.size`;
+    Card `contentTop`/`contentBottom` share the content gap (`lg`, or
+    `contentGap`) instead of touching the body.
+  - Templates: `adminStarterUIDefaults` no longer turns on card header/footer
+    dividers; facts, line items, KPIs and commands lose decorative icons;
+    count/kind badges, repeated identity rows and repeated facts are removed.
+  - Guidance: house rule 7 and the Card anatomy reference cover decorative
+    icons and dividers; the composition checker warns (`decorative-icon`) on a
+    Card title icon or an icon on more than one MetadataList fact; AGENTS.md
+    records the visual restraint rules.
+
+- **Breaking (visual): an untoned Button is now the neutral outline**
+  (`tone="secondary"`, `buttonStyle="outline"`), so a screen gets one deliberate
+  primary instead of a primary on every button. Give the main command
+  `tone="primary"`. A Button with a `tone` and no `buttonStyle` is now always
+  solid: `UIProvider` `button.defaultButtonStyle` applies only to buttons without
+  a tone. Run `docs/consumer-skill/scripts/pin-button-defaults.mjs` (dry run by
+  default, `--write` to apply, `--solid-only` to let untoned outline and ghost
+  buttons turn neutral) to keep existing screens' look, or restore the previous
+  default app-wide with `button: { defaultTone: 'primary', defaultButtonStyle:
+  'solid' }`. The library's own components keep their primary commands
+  explicitly; their untoned outline and ghost buttons (cascader, signature pad,
+  questionnaire navigation) are now neutral instead of brand-colored, and
+  `SubmitStateButton` keeps the primary role for submit.
+- Add a 32px `3xl` structural gap step (`gap-space-3xl`, `gap-x-space-3xl`,
+  `gap-y-space-3xl`; `--spacing-space-3xl` scales with `--space-scale`) for page
+  rhythm. Page now separates its header from its body with `3xl` (was 24px), and
+  Stack/Grid/Section accept `gap="3xl"` between major sections. The utility
+  budget grows from 393 to 396 spellings for this one shared responsibility.
+- **Breaking (visual): the default primary is neutral.** `--primary` is
+  near-black in light (`oklch(0.205 0 0)`) and near-white in dark, so the brand
+  no longer sits next to the success green (they were ΔE_OK 0.074 apart). The
+  previous green is the opt-in brand theme `themelia-react-ui/themes/green.css`:
+  import it after `style.css` to keep the old look. It sets primary, its
+  foreground, the dark primary accent and the first chart series, and passes
+  the same contrast contract. `--primary-accent` now follows `--primary` in
+  dark too.
+- Form-control boundaries reach 3:1 contrast (WCAG 1.4.11): `--input` is
+  `oklch(0.62 0 0)` in light (was the divider color, 1.26:1) and white at 40% in
+  dark (was 15%), so inputs, selects, checkboxes, radios and switch tracks are
+  visible on every surface. `--border` stays the lighter divider color. The
+  contrast contract now checks `--input` at 3:1 on background, card, popover,
+  muted, accent and secondary surfaces. The repeater's empty placeholder uses
+  the divider border.
+- Button labels wrap inside the available width instead of overflowing: the
+  action height is now a minimum for text buttons (icon-only buttons stay fixed
+  squares), and buttons cap at their container's width. Pass `truncate` to keep
+  one line with an ellipsis where a button cannot grow, such as a joined group
+  or dense toolbar. Components that size a button themselves (`h-auto`,
+  `h-full`) now also reset the minimum height, and the header search trigger
+  uses `size="sm"` instead of a height override.
+- Add role-based page commands to PageHeader and `Page header`:
+  `primaryAction` (one solid primary command, trailing and always visible) and
+  ordered `secondaryActions` (two outline buttons, then a More actions menu).
+  Destructive secondary commands always move into that menu; below `sm` every
+  secondary command collapses into it through CSS. Commands carry no tone or
+  button style. `moreActionsLabel` names the menu; the new `PageHeaderAction`
+  type is exported from `layout/page` and `layout`. Existing `actions` and
+  `slots.actions` are unchanged: `actions` renders before the commands, and
+  `slots.actions` still replaces the whole region.
+- Move the admin templates, consumer recipes and Page catalogue examples to the
+  role-based commands. Header buttons now share one size, and the stacked shell
+  recipe no longer repeats the page's Create record command in its navigation.
+- The optional consumer checker warns (`page-command-roles`) when Page or
+  PageHeader `actions` hold command buttons, pointing to `primaryAction` and
+  `secondaryActions`. The analytics template's period filter is now a labelled
+  Select instead of a toggle button.
+- Nested `UIProvider`s no longer throw. A nested provider inherits the nearest
+  provider's resolved defaults and overrides only the keys it sets, so
+  `AdminUIThemeProvider` works inside an application's root provider.
+- Metric surfaces format currency, numbers and percentages with the same
+  formatter and UIProvider policy as `Money` (locale, default currency and
+  `formatMode`). A currency metric without a currency now uses the provider
+  default (`USD` by default) instead of EUR, and prints like Money
+  (`1,840.00 USD` by default) instead of `USD 1,840.00`. `formatMetricValue`
+  accepts optional `FormatMetricValueOptions`.
+- Add `useMoneyFormatter()` to `primitives` for money in strings (labels,
+  toasts, activity text) with the Money rules; the templates use it instead of
+  hand-built `$x.xx USD` strings, and their tables use the Date primitive.
+- `toTableAction` keeps running actions disabled and hidden actions hidden in
+  DataTable rows; `toMenuAction` carries `id`, `visible` and `group`.
+- Themes declare `color-scheme`, so native scrollbars and form controls follow
+  dark mode. Light `--primary-accent` now follows `--primary`, so a rebrand
+  needs one root.
+- Unit tests resolve the package's own imports from source, so `npm test` no
+  longer needs (or silently uses) a previous build.
+- Page titles are the route's `h1` by default (was `h3`) and use the 20px
+  `text-xl` role (was 18px), so page and card titles (16px) read as distinct
+  levels. Pass `headingTag="h2"` for a page nested inside another titled page.
+- Card and MediaLibrary plain-text titles are exposed as level-2 headings, so
+  assistive technology can move between surfaces. Title-suffix badges stay out
+  of the heading's name; custom title nodes keep their own semantics.
+- An untoned Badge is now neutral (was primary), so only a deliberate tone
+  signals state. Set `UIProvider` `badge.defaultTone: 'primary'` to keep the
+  previous look. The Default address and payment-method badges are neutral too.
+- `useMoneyFormatter(defaults)` binds screen defaults such as `currency` once;
+  each call can still override them. `MoneyFormatterOptions` is exported.
+- The consumer skill opens with eight house rules (provider, Page, command
+  roles, Stack/Grid, typography and value primitives, semantic color, neutral
+  badges, Card slots). The checker adds review warnings for raw palette color
+  classes, native `<button>` and `<h1>`–`<h6>` elements, and pages with more
+  than one solid primary command. The orders and staff templates now have one
+  primary command each.
+- The consumer skill's public index lists each family's deprecated names with
+  their replacements (`SmartCard`: "Use Card.", `SmartCardProps`: "Use
+  CardProps."), derived from `@deprecated` JSDoc. The finder leaves them out of
+  task recommendations and flags them when a query names one.
+- Event calendar markers in narrow day cells keep the compact action height
+  (28px), so they meet the WCAG 2.2 24px target size instead of a 12px sliver.
+- Regenerate `package-lock.json`: it pinned lightningcss 1.32.0 where the
+  package and Vite require `^1.33.0`, so `npm ci`, and with it CI, failed
+  before running any check.
+
+## 1.0.3 — 2026-10-15
+
+- Document layout-block ownership, horizontal Stack rows, responsive tracks and
+  parent adaptation; ship a typed region-composition recipe and route common
+  layout queries to the corresponding owners and focused guidance.
+
+- Align template peer Card stacks with Page/TwoColumnLayout’s existing `2xl`
+  rhythm: 24px in both axes at default scale, including stacked mobile regions.
+
+- Let AddressCard, PaymentMethod, SeoListingCard and ProductVariantsManager own
+  their framed Card anatomy through existing surface/padding/divider props.
+  Preserve unframed defaults and suppress inherited embedded header rules;
+  replace redundant template wrappers with one full-width Card boundary.
+- Audit the admin templates: isolate overlay drafts, preserve staff save/discard
+  baselines, close mobile navigation, honor shell presets/density and repair
+  variant duplication/options persistence. Include templates in design lint and
+  installed-package typechecks; correct their documented scope and discovery.
+- Keep long MetadataList row labels from squeezing monetary values out of narrow
+  panels, and use the semantic copy-gap recipe for label/value rhythm.
 
 - Increase the shared surface-x/y defaults to 1.25rem: ordinary Card insets are
   20px, compact surfaces 10px and large surfaces/page gutters 36px at default