themelia-react-ui 2.0.6 → 3.0.0

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

@@ -74,11 +74,12 @@ 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
@@ -279,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.
 
@@ -367,7 +368,7 @@ At shipped roots, rich display padding is 24px and compact collection shell padd
 
 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.
 
@@ -487,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
@@ -505,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,
@@ -598,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).

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

@@ -34,7 +34,7 @@ popover surfaces still pair their own background/foreground roles.
 
 ## Resolve the installed package
 
-Themelia 2.0.6 requires the official `@base-ui/react ^1.9.0` npm peer alongside
+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
@@ -135,7 +135,13 @@ node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs
 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
 
@@ -170,9 +176,9 @@ node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs
 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. Combined copies preflight both destinations before writing; a conflict leaves the other destination untouched. Use the same destination/opt-out flags for `--check` that you used for copying.
+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

@@ -119,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.
@@ -135,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`.
 
@@ -172,6 +172,6 @@ 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 still work. Use
+`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