themelia-react-ui 2.0.5 → 3.0.0

package/docs/consumer-skill/references/composition.md

@@ -74,13 +74,21 @@ role in Page's header: `primaryAction` is the route's one main command, and
 their treatment and order: outline secondary buttons, the solid primary button,
 then a More actions menu for overflow, destructive commands and narrow screens,
 which always ends the desktop row. Below 40rem of actual header width, every
-command, including primary, moves into one More actions menu. WorkspaceRecordHeader, ResourceHeader, the resource
-shells and SettingsShell take the same props and render the same row. Choosing which
+command, including primary, moves into one More actions menu. WorkspaceRecordHeader
+and AsideNavShell take the same props and render the same row. Choosing which
 command is primary, which are `destructive`, and which are `visible` remains an
-application decision; confirm destructive commands in their handler. Use
-the compatible direct `actions` prop for non-command controls such as a period select. A back link,
+application decision; confirm destructive commands in their handler. Put
+non-command controls such as a period select in Page's `toolbar`;
+WorkspaceRecordHeader and AsideNavShell keep `actions` for them. A back link,
 export and destructive command should not all inherit the same visual emphasis.
 
+Scope this hierarchy to route commands. A local lookup or independently saved
+settings form keeps its primary submit beside its fields or in its own footer;
+it does not compete with the route's primary action. A whole-page editor can
+deliberately expose one submit in its header. Preserve native form association
+and validation instead of moving local saves to header DOM-lookup handlers just
+to silence a primary-command warning.
+
 ```tsx
 <Page header={{
   title: 'Contacts',
@@ -272,7 +280,7 @@ Overlays rule their regions the same way: `ActionDialog`, `ActionDrawer` and `Co
 draw one rule between header, body and footer (one rule when there is no body),
 owned by the overlay; do not add borders to their content.
 
-Use titleSuffix for status/count/version badges. Long titles/suffixes wrap through the shared owner; no literal spaces/local margins to manufacture gaps. headerAction/actions are trailing controls, headerStart pre-title context. footerSlot/footer definitions own card-level actions; footerDivider owns the rule and inset. Do not simulate a footer inside children. SmartCard and ContentBlock are deprecated migration names; use Card in new code.
+Use titleSuffix for status/count/version badges. Long titles/suffixes wrap through the shared owner; no literal spaces/local margins to manufacture gaps. headerAction/actions are trailing controls, headerStart pre-title context. footerSlot/footer definitions own card-level actions; footerDivider owns the rule and inset. Do not simulate a footer inside children. SmartCard and ContentBlock were removed in 3.0; use Card.
 
 Reusable blocks/features stay card-free unless their explicit purpose is a card. Frame them at the composition boundary.
 
@@ -346,8 +354,9 @@ PopoverContent type="display" owns substantive-content padding; type="menu" comp
 | size="sm" / "md" / "lg" | Supported control's scale; consult its declaration and provider precedence |
 
 Input, Button, Select, filter-facet triggers and badges share the default
-`rounded-radius` corner and corresponding heights; Card and popup shells use the
-larger `rounded-surface`. Omitted sizes inherit the provider; explicit sizes win.
+`rounded-radius` corner; Card and popup shells use the larger `rounded-surface`.
+Fields and actions use their corresponding height scales; badges remain content-sized.
+Omitted sizes inherit the provider; explicit sizes win.
 Keep action/control roots equal when those controls adjoin. Compact menu rows,
 surface insets and control sizes remain independent; density does not change
 the corner.
@@ -355,11 +364,11 @@ Inset segmented children use the supported compound owner's same-height frame.
 
 PopoverContent defaults to display/default; Command defaults to compact. An explicit PopoverContent type controls anatomy; explicit inset controls padding and takes precedence over the type's inferred inset. Without type, compact implies menu, other insets imply display. Put type="menu" inset="flush" on PopoverContent for a headed searchable picker. Popover is the interaction root and receives no surface props. PopoverMenu already assembles that picker anatomy; use its declared selection/search props. ComboboxPopup is flush because ComboboxList owns its inset. Do not add another wrapper inset around a normal collection list.
 
-At shipped roots, rich display padding is 24px and compact collection shell padding is 8px; row inline padding is 12px; default row block padding is 8px and minimum height 32px. Compact/comfortable rows use 6/10px block padding and 32/40px minimum heights. Content can grow when it wraps. These are token-derived measurements, not app constants. Flush compact header/footer shell padding matches the list (4px inline). Header text and footer captions add a small xs step (4px) to the md band inset (8px), rather than the full row inset. Actions keep the 4px shell edge. Nested public slots do not repeat these insets.
+At shipped roots, rich display padding is 24px and compact collection shell padding is 8px; row inline padding is 12px. Anchored collection rows use 6px block padding and a 32px minimum height by default. Compact/comfortable rows use 2/8px block padding and 28/36px minimum heights. These differ from Item/table row density recipes; content can grow when it wraps. These are token-derived measurements, not app constants. Flush compact header/footer bands match the list's 8px inset. Plain header text and footer captions add a small xs step (4px) to that md band inset, rather than the full row inset; leading controls and actions stay on the band edge. Nested public slots do not repeat these insets.
 
 Input frames and outline buttons share the input semantic token; collection dividers use border/60; focus uses ring separately and draws one indicator everywhere (a full-strength edge inside a soft halo). Equal responsibilities share recipes, while different semantic roles retain their own treatment. CommandInput keeps its existing onValueChange search contract and native refs; use the actual public Input through its default composition rather than restyling an unframed native field.
 
-ActionMenu density="table" remains a legacy table/overflow adapter. AsyncPreview padding="lg" owns a compatibility content boundary. Neither expands the default/compact surface vocabulary.
+ActionMenu density="table" was removed in 3.0; use density="compact". AsyncPreview padding="lg" owns a compatibility content boundary; it does not expand the default/compact surface vocabulary.
 
 Button separates tone from buttonStyle (solid, outline, ghost). ActionButtons renders the same definitions as ActionMenu. Badge tones describe actual states, not a decorative palette.
 
@@ -367,7 +376,10 @@ Overflow menus use ActionMenu's own trigger: the ⋯ glyph named "More actions",
 
 ## Migration
 
-Use exact themelia-react-ui paths. Presentation imports use blocks/<family>, replacing composed/<family>. Raw UI, Radix, cmdk and routers are not consumer foundations. Read installed types instead of assuming historical CSS-kit props.
+Use exact `themelia-react-ui` paths. Presentation imports move from
+`admin-ui-starter-kit/composed/<family>` to `themelia-react-ui/blocks/<family>`.
+Read `MIGRATION.md` in the installed package for setup, tools and changed
+defaults. Check the installed types when migrating a composition.
 
 
 ## Copy rhythm
@@ -476,10 +488,11 @@ The shared global header-height root defaults to 4rem. Use the playground's
 full-viewport `?page=shells&layout=header|sidebar|inset` views to inspect
 the composition, optionally with `&theme=dark`.
 
-Sidebar shells accept `slots.sidebar` (primary) and `slots.secondarySidebar`
-(contextual navigation). Each missing region removes its track. `sidebarWidth`
-and `secondarySidebarWidth` size their own expanded region, with the
-shared shell width as fallback. `sidebarPresentation="rail"` selects dedicated
+Sidebar shells accept `sidebar` (primary) and `slots.secondarySidebar`
+(contextual navigation). Each missing region removes its track. The
+`--shell-sidebar-width` root, set through `style`, sizes the primary region and
+`secondarySidebarWidth` the contextual one, with the shared shell width as
+fallback. `sidebarPresentation="rail"` selects dedicated
 primary navigation geometry independently of full-sidebar icon collapse. Use SidebarNavigationRail from
 layout/sidebar for area navigation with items, value/onValueChange and
 renderLink; it preserves accessible labels/tooltips and defaults to
@@ -494,8 +507,8 @@ before/after content scrolls with its navigation.
 The shell owns one PageViewport and framing. Give the root a constrained height
 (`h-svh min-h-0` for full-screen apps). Page owns width, page gutters and
 header/body rhythm, Card owns its insets, and Stack/Grid owns peer gaps. With
-stacked/contained content, use Page gutter="none" to avoid repeating the shell's
-Container gutter. Metric card size changes copy/media scale, keeping the default
+stacked/contained content, Page drops its inline gutter by default because the
+shell's Container owns it; pass `gutter` explicitly to add one back. Metric card size changes copy/media scale, keeping the default
 surface inset in ready, loading and error states.
 
 Keep the dual area rail docked on the left beside the full navigation panel,
@@ -587,14 +600,16 @@ there is no automatic metadata item shape or avatar column. Title, description a
 actions occupy a separate right column aligned to the top. beforeTitle spans
 above the columns, and tabs sit below. An actions renderer
 can wrap or return `defaultContent` to retain the responsive command row; replacing
-it owns its own command semantics. Legacy `slots.back`, `titleBadges`, `titleIcon`
-and direct `actions` remain compatible. Direct toolbar, aside and lifecycle props compose at that
+it owns its own command semantics. `slots.back`, `titleBadges`, `titleIcon`
+and the direct header `actions` prop were removed in 3.0: use `backHref`/`onBack`,
+a Badge in `slots.titleSuffix` and Page `toolbar` for non-command controls.
+Direct toolbar, aside and lifecycle props compose at that
 same boundary; explicit slots override matching direct regions. beforeHeader
-precedes the header; afterHeader is the compatible toolbar fallback. Loading
+precedes the header; `toolbar` replaces the removed afterHeader. Loading
 precedes error, then empty, replacing only the main body while the header,
 toolbar and aside remain mounted. Customize state strings or loading/error/empty
-slots and wire onRetry. ResourceHeader/ResourceIndexShell/ResourceShowShell/
-TabbedResourceShell retain legacy embedding behavior for migration.
+slots and wire onRetry. ResourceHeader, ResourceIndexShell, ResourceShowShell and
+TabbedResourceShell were removed in 3.0; use Page.
 
 Select width from the task: a single focused resource/form can use `narrow`;
 a record with supporting context uses Page `aside` and infers `xl` (80rem).
@@ -607,6 +622,12 @@ narrow record measure, a status badge, route-level commands and section tabs in
 the header, and MetadataList facts in one framed Card, with no duplicated subject
 header or gutter.
 
+Page's measure contains both header and body. On a mixed route with wide tables
+and focused settings panels, keep Page's width stable across tabs. Constrain
+only the focused panel with `Container maxWidth="md" gutter="none"`; Container
+uses `gutter`, not a `padding` prop. An intentional responsive route width is
+different from changing the header's width on every section selection.
+
 Compose HeaderUserMenu in topbar `slots.headerEnd` or a local toolbar, and
 SidebarNavigationUser in AppSidebar `slots.footer` when account access belongs
 in navigation. Use SidebarWorkspaceDropdown for workspace links, or add a

package/docs/consumer-skill/references/design-contract.md

@@ -68,6 +68,7 @@ These base measurements use the shipped roots; spacing scales once through
 | Independent subject regions | `2xl`, 24px | Page body, TwoColumnLayout, resource, workspace and settings subjects |
 | Page header/body separation | `3xl`, 32px | Page composition |
 | Surface header/body/footer | Surface-derived regional gap | Card or overlay anatomy, independent of peer gaps |
+| Live table outer / interior cell insets | Small surface / row inline tiers, 16 / 12px | Table head, body and footer cells; row density changes only block rhythm |
 
 Generic Stack and Grid keep their existing defaults; choose their semantic gap
 for the relationship they host. A Card's regional gap derives from its surface

package/docs/consumer-skill/references/discovery.md

@@ -56,7 +56,9 @@ When the same symbol is re-exported by an aggregate family, its documented
 component owner ranks first. For example, `UsageCard` selects
 `themelia-react-ui/blocks/analytics/usage-card` with no optional chart peer;
 requesting the exact `themelia-react-ui/blocks/analytics` import still selects
-that broader family. Read the reported peers and declaration for your selection.
+that broader, peer-free family. KPI queries such as `kpi`, `metric` or
+`kpi dashboard` select `themelia-react-ui/blocks/analytics/charts`, which
+reports the `recharts` peer. Read the reported peers and declaration for your selection.
 
 Exact curated intent aliases rank below exact imports/symbols and above generic
 description matches. Start with responsibilities such as `record directory`,
@@ -99,10 +101,11 @@ kind, exact `matchedSymbols`, `relevantSymbols`, `nextReads` and up to three
 relevant guidance entries. Exact symbol queries keep that symbol; intent queries
 derive relevantSymbols from selected catalogue API sections and current public
 exports. An exact family import retains the complete public symbol vocabulary.
-Deprecated migration names such as `SmartCard` or `ContentBlockProps` never
-appear in intent recommendations. When a result touches one, its `deprecated`
-map names the replacement, for example `{ "SmartCard": "Use Card." }`; write
-new code with the replacement. The public index carries the same map per family.
+Symbols the public index marks deprecated never appear in intent
+recommendations. When a result touches one, its `deprecated` map names the
+replacement; write new code with the replacement. The public index carries the
+same map per family. 3.0 removed the names it had marked, such as `SmartCard`
+and `ContentBlockProps`.
 Exact guide aliases precede generic overlap, and unrelated family pages
 do not fill the result merely to reach three entries.
 

package/docs/consumer-skill/references/installation.md

@@ -2,7 +2,7 @@
 
 ## Choose the CSS path
 
-**Standalone compiled CSS:** import `themelia-react-ui/style.css` once in the app entry. It includes component styles and the documented public utility vocabulary; components work without a host reset, Tailwind processing or private-source scanning. It deliberately omits global preflight. This path does not generate arbitrary utility classes written in app source.
+**Standalone compiled CSS:** import `themelia-react-ui/style.css` once in the app entry. It includes component styles, the documented public utility vocabulary, and static utility classes used by catalogue examples and shipped recipes/templates; components work without a host reset, Tailwind processing or private-source scanning. It deliberately omits global preflight. This path does not generate arbitrary utility classes written in app source.
 
 **Tailwind v4 application utilities:** when the app authors Tailwind classes, process this application stylesheet through its Tailwind v4 build integration:
 
@@ -14,8 +14,27 @@
 
 Tailwind supplies app-generated utilities and its layered preflight; theme.css makes the semantic and structural vocabulary available to that compilation. No package-private source scan is required. The default layer order is `theme, base, components, utilities`. Keep app resets inside `@layer base`; unlayered universal/tag resets outrank layered package styles regardless of import order. Do not blanket-reset `[data-slot]`, which also belongs to third-party and app markup. Put intentional scoped app overrides after these imports. See [integration](integration.md) for an optional app-owned reset and provider setup.
 
+## Set the application canvas
 
-Themelia 2.0.5 requires the official `@base-ui/react ^1.9.0` npm peer alongside
+The host owns the document font, page background and inherited text color.
+After importing package styles, set them in the application's stylesheet:
+
+```css
+@layer base {
+  html { font-family: var(--font-sans); }
+  body { margin: 0; background: var(--background); color: var(--foreground); }
+}
+```
+
+These roles follow the active light/dark theme. They also give app markup and
+intentionally inherited copy a page foreground. Components keep their own
+essential fonts and box model; this host setup is independent of a reset or
+Tailwind build and adds no stylesheet entry or dependency. Painted card and
+popover surfaces still pair their own background/foreground roles.
+
+## Resolve the installed package
+
+Themelia 3.0.0 requires the official `@base-ui/react ^1.9.0` npm peer alongside
 React, React DOM and Lucide. An app already using `^1.9.0` can retain that range.
 Remove any older private Base UI archive pin or override before refreshing the
 lockfile; dismissal translations and nested popup focus belong to Themelia's
@@ -107,29 +126,59 @@ each page or surface keeps one.
 
 ## Copy the complete skill bundle
 
-The package ships four focused capabilities, one compatibility/shared root and one agent definition. One copy of API/token/contract metadata, scripts and examples is shared by all three. Do not copy only an individual SKILL.md or duplicate the generated indexes into each skill.
+The package ships four focused capabilities, one compatibility/shared root and one agent definition. One copy of API/token/contract metadata, scripts and examples is shared by all four. Do not copy only an individual SKILL.md or duplicate the generated indexes into each skill.
 
-When the user requests installation, run the bundled copy helper with their configured agent skills directory. For Codex the usual destination is `~/.codex/skills`; honor a configured alternative:
+When the user requests installation, run the bundled copy helper with their configured agent skills directory. Codex supports project `.agents/skills` and user `~/.agents/skills`; honor an existing configured alternative:
 
 ```sh
-node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination "$HOME/.codex/skills"
-node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination "$HOME/.codex/skills"
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination .agents/skills
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination .agents/skills
 ```
 
-It copies `themelia-components`, `themelia-tokenization`, `themelia-composition`, `themelia-design`, and `themelia-react-ui-consumer` as real sibling directories. Rich templates are copied once under the shared directory. Markdown links are rebased for this installed layout; no symlinks or repository paths are required. Existing canonical/shared destinations are rejected before writing: preserve or move the previous complete bundle before an upgrade, then copy the release together. `--check` compares every expected asset after rebasing, so stale content with an unchanged development version is caught.
+It copies `themelia-components`, `themelia-tokenization`, `themelia-composition`, `themelia-design`, and `themelia-react-ui-consumer` as real sibling directories. Rich templates are copied once under the shared directory. Markdown links are rebased for this installed layout; no symlinks or repository paths are required. Copying replaces: earlier copies of these five directories are deleted and written again, so edits made inside them and files a newer release dropped do not survive, and the retired `themelia-foundation` and `themelia-forms` copies are removed. Skills with other names are left untouched. Run it again after every package upgrade. `--check` compares every expected asset after rebasing and reports leftover files, so stale content with an unchanged development version is caught.
+
+The helper never edits project instructions. Print the block for the app's `AGENTS.md` (or `CLAUDE.md`) and paste it yourself, replacing an earlier block between its markers:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --agents-block
+```
 
 ### Copy the designer agent
 
-`docs/consumer-skill/agents/themelia-ui-designer.md` is a Claude Code agent definition: a product designer that reads the records, writes a view spec, builds with public owners, renders 390 and 1440 wide in light and dark, scores the critique rubric and fixes. Its body reads skills and scripts through `node_modules/themelia-react-ui/...`, so it works wherever the skills were copied; other agents can follow it as a prompt. When the user requests it, copy it into the project's agents directory with the skills or on its own:
+`docs/consumer-skill/agents/themelia-ui-designer.md` is a Markdown agent definition and portable prompt: a product designer that reads records, writes a view spec, builds with public owners, renders 390 and 1440 wide in light and dark, scores the critique rubric and fixes. `review` mode is read-only. Its body reads skills and scripts through `node_modules/themelia-react-ui/...`, so it works wherever the skills were copied. The copy inside the shared skill is a reference; registering a custom agent depends on the host:
+
+| Host | Discoverable custom agent | Installer behavior |
+| --- | --- | --- |
+| Claude Code | `.claude/agents/themelia-ui-designer.md` | A destination ending in `.claude/skills` also copies/checks the sibling agent. `--no-agents` opts out; `--agents <dir>` overrides it. |
+| Antigravity | `.agents/agents/themelia-ui-designer.md` | Pass `--agents .agents/agents` explicitly with `.agents/skills`. |
+| Codex | `.codex/agents/<name>.toml` | The Markdown file remains a prompt/reference; this helper does not generate or register a Codex TOML agent. Follow the prompt directly or pass it to an available subagent. |
+
+`.agents/skills` is shared by multiple hosts, so the installer does not infer a Markdown-agent destination from it. See the official [Claude Code subagent](https://code.claude.com/docs/en/sub-agents), [Antigravity subagent](https://antigravity.google/docs/subagents), [Codex subagent](https://learn.chatgpt.com/docs/agent-configuration/subagents) and [skill metadata](https://learn.chatgpt.com/docs/build-skills) documentation. `agents/openai.yaml` is optional skill metadata, separate from custom agent registration.
+
+For Claude Code, copy the complete bundle and agent together:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination .claude/skills
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination .claude/skills
+```
+
+For Antigravity, choose the agent destination explicitly:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --destination .agents/skills --agents .agents/agents
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --destination .agents/skills --agents .agents/agents
+```
+
+An agent-only copy remains supported:
 
 ```sh
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --copy --agents .claude/agents
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --agents .claude/agents
 ```
 
-An existing `themelia-ui-designer.md` is never overwritten; move it before copying a newer release. Other agent files are left untouched.
+An existing `themelia-ui-designer.md` is replaced; keep app changes in a differently named agent. Other agent files are left untouched. Combined copies validate both destination paths before writing. Use the same destination/opt-out flags for `--check` that you used for copying.
 
-The package retains `docs/consumer-skills/themelia-foundation/SKILL.md` and `themelia-forms/SKILL.md` as compatibility routers. They are not added by fresh copying. Existing legacy or unrelated skills are left untouched; review older agent routing separately when upgrading. Keep app policy outside the copied package bundle.
+The package retains `docs/consumer-skills/themelia-foundation/SKILL.md` and `themelia-forms/SKILL.md` as compatibility routers. They are not added by copying, and copies of them from an earlier release are removed. Unrelated skills are left untouched. Keep app policy outside the copied package bundle.
 
 For the identity recipe above, set `THEMELIA_SKILL_DIR` to the copied shared `themelia-react-ui-consumer` directory. In project instructions, use the generated [AGENTS.md block](agents-md.md) pointing at package skills, or point the four skill paths to their copied siblings. Invoke `$themelia-components` for setup, discovery and typed APIs/forms; `$themelia-tokenization` for themes and shared visual roles; `$themelia-composition` for screen hierarchy, workflows and visual repair; and `$themelia-design` for data briefs, view specs and rubric-scored critique of rendered views. The compatibility `$themelia-react-ui-consumer` entrypoint remains available.
 

package/docs/consumer-skill/references/integration.md

@@ -68,6 +68,18 @@ icon mode; its search button expands and focuses the field. Current
 matching chooses the most-specific href and exposes ancestor state separately
 to custom item renderers.
 
+Pass the committed route as `currentUrl` so an open AppSidebar drawer closes
+after navigation. SidebarNavigationRail falls back to its controlled `value`
+when no URL is supplied. Use `closeDrawerOnNavigate={false}` on either owner
+to keep its drawer open, or handle the proposal through
+`onMobilePanelChange` when the provider's `mobilePanel` is controlled.
+For SideNav, pass the app's pathname as `currentPath` on the server and
+client and forward `aria-current` from its `renderLink` adapter.
+
+`Header` and `HeaderBreadcrumbs` also work in standalone and stacked shells.
+They show the built-in sidebar trigger and divider when a sidebar provider is
+present. `HeaderBreadcrumbs` accepts a custom `triggerSlot` in either layout.
+
 For RTL, pair the native DOM direction with `DirectionProvider` from the same
 entrypoint. Native `dir` owns text flow and logical CSS geometry; the provider
 owns Base UI keyboard navigation and popup positioning. It does not set `dir`.
@@ -107,8 +119,8 @@ confirm button; compose the body with the ordinary Stack, FormField and Card
 anatomy and leave its insets to the overlay.
 
 Do not hand-roll a modal (a `fixed inset-0` scrim, `role="dialog"`,
-`aria-modal`), do not import the lower-level `Dialog`, `AlertDialog` or `Sheet`
-building blocks, and do not add another modal library (Radix Dialog,
+`aria-modal`), do not look for lower-level `Dialog`, `AlertDialog` or `Sheet`
+building blocks (no package entry publishes them), and do not add another modal library (Radix Dialog,
 react-modal, vaul, Headless UI or React Aria dialogs). The optional checker
 warns on each of these. Popovers, menus, selects and tooltips are anchored
 surfaces, not dialogs: use their own owners.
@@ -123,10 +135,10 @@ PlaceAutocomplete from themelia-react-ui/features/map uses Photon by default. Su
 
 Verify callbacks update actual app state. Cover relevant loading, empty, error, invalid/disabled, cancel/retry and success behavior. Check keyboard entry, dismissal and focus return. Inspect opened content in light/dark and narrow/wide layouts; a closed trigger screenshot cannot approve its popup.
 
-EmailComposer from `themelia-react-ui/features/email-composer` requires the Tiptap optional peers and composes our controls, Card/overlays and editor toolbar. Keep the structured draft separate from prepared delivery output: `onChange` persists an immutable draft proposal; `onSend` receives resolved, sanitized HTML/plain text. Supply pure placeholder resolvers and immutable context, and keep delivery/authentication in the app. Imported HTML retains supported email layout in preview until explicit rich-text conversion. See the [typed email recipe](../examples/email-composer.tsx) and the family catalogue for commands, strings and placement examples.
+EmailComposer from `themelia-react-ui/features/email-composer` requires the Tiptap optional peers and composes our controls, Card/overlays and editor toolbar. Keep the structured draft separate from prepared delivery output: `onValueChange` persists an immutable draft proposal; `onSend` receives resolved, sanitized HTML/plain text. Supply pure placeholder resolvers and immutable context, and keep delivery/authentication in the app. Imported HTML retains supported email layout in preview until explicit rich-text conversion. See the [typed email recipe](../examples/email-composer.tsx) and the family catalogue for commands, strings and placement examples.
 Empty recipient groups show our input immediately; the inline plus adds another address, and Cc/Bcc reveal inputs. Template registries, placeholder sets and per-field recipient options accept application-owned `loading`, `error` and `onRetry`; templates additionally expose `onOpenChange` for lazy loading. Loading/error replace stale data. Required recipient/variable resources block preparation and sending until ready; an optional template registry does not block ordinary composing. Preserve the selected template in the supplied registry and let your data client cancel or ignore stale requests.
 
-Keep `value` authoritative and accept `onChange` proposals in the controlled parent. Keep controlled/uncontrolled mode fixed while mounted; remount with a new key for a different message and discard baseline. Callback proposals and delivery payloads are detached from the local draft and from one another. Recipient modes and subject read-only flags constrain user editing; application API commands may still replace these fields. Commit recipient input with Enter, the plus, or blur before an imperative preparation command.
+Keep `value` authoritative and accept `onValueChange` proposals in the controlled parent. Keep controlled/uncontrolled mode fixed while mounted; remount with a new key for a different message and discard baseline. Callback proposals and delivery payloads are detached from the local draft and from one another. Recipient modes and subject read-only flags constrain user editing; application API commands may still replace these fields. Commit recipient input with Enter, the plus, or blur before an imperative preparation command.
 
 `api.prepare()` rejects validation failures. `api.send()` and `api.discard()` report failures through the alert and `onError` and resolve after handling them; use `onSent` to observe delivery success. `onBeforeSend` may cancel with false or transform the payload under your application's validation policy. Success neither closes nor resets the composer. Unmounting during review prevents delivery; once your `onSend` starts, cancellation belongs to your transport. Unmounting suppresses success/reset/close completion, while failures still reach `onError`.
 
@@ -151,4 +163,15 @@ not evidence of an independent agent choosing the same composition.
 
 ## Form transport and router adapters
 
-Use [RHF workflows](rhf-workflows.md#transport-lifecycle) for frontend state with Inertia callback visits or TanStack async mutations. Await the complete transport before resetting dirty state or closing an overlay. The framework stays in the app. `renderLink` on AppSidebar/Page headers adapts the app router: forward href, children, className, accessible/native attributes and onClick; preserve modifier/new-tab behavior and invoke the supplied click handler so mobile navigation can close. Use the [typed shell recipe](../examples/app-layout.tsx) for the exact public renderLink type rather than inventing a router prop. React Router Link, Inertia Link and TanStack Link each need an app adapter matching their own installed version.
+Use [RHF workflows](rhf-workflows.md#transport-lifecycle) for frontend state with Inertia callback visits or TanStack async mutations. Await the complete transport before resetting dirty state or closing an overlay. The framework stays in the app. For a `renderLink` router adapter, forward href, children, className, accessible/native attributes and onClick. Preserve modifier and new-tab behavior. Pass the updated route to AppSidebar after navigation so it can close its open drawer. The [typed shell recipe](../examples/app-layout.tsx) uses the public renderLink type.
+
+Wrap compound controls directly in `FormField` to associate the visible
+caption and supporting text. Inline time, dimension, coordinate and key/value
+fields expose a named group. Popover time and upload fields name the picker
+control. RichTextEditor carries the same association into HTML source mode.
+
+Use `value`, `defaultValue` and `onValueChange` for Combobox and
+AsyncResourceCombobox. MultiCombobox uses the plural forms. The older
+`selectedValue` and `selectedValues` bindings were removed in 3.0. Use
+`defaultSearchValue` and `defaultOpen` for initial state, or pass
+`searchValue` and `open` to control it.

package/docs/consumer-skill/references/product-composition.md

@@ -26,8 +26,8 @@ model does not have. For an optioned product, definitions, sellable combinations
 and a selected variant are different jobs; they need not be three custom cards.
 The [products template](../../../templates/products-template.tsx) demonstrates
 the larger public workflow. Its data and callbacks are examples, not your
-product's business rules. Deprecated standalone product region-card exports are
-compatibility APIs; use ProductOverview regions or the dedicated active owners.
+product's business rules. The standalone product region-card exports were
+removed in 3.0; use ProductOverview regions or the dedicated active owners.
 
 ## Media identity and lifecycle