themelia-react-ui 2.0.4 → 2.0.6

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.4 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 2.0.6 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,19 +126,54 @@ each page or surface keeps one.
 
 ## Copy the complete skill bundle
 
-The package ships three focused capabilities and one compatibility/shared root. 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. 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 .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.
+
+### Copy the designer agent
+
+`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
+```
 
-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:
+An agent-only copy remains supported:
 
 ```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 --agents .claude/agents
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/setup-skills.mjs --check --agents .claude/agents
 ```
 
-It copies `themelia-components`, `themelia-tokenization`, `themelia-composition`, 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.
+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.
 
 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.
 
-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 three skill paths to their copied siblings. Invoke `$themelia-components` for setup, discovery and typed APIs/forms; `$themelia-tokenization` for themes and shared visual roles; and `$themelia-composition` for screen hierarchy, workflows and visual repair. The compatibility `$themelia-react-ui-consumer` entrypoint remains available.
+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.
 
 Copying into an agent's global skill directory requires a user request. The npm package does not perform installation automatically. Run the consuming app's own type/lint/test/build scripts after integration; repository maintainer commands are not installed consumer commands.

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

@@ -33,6 +33,53 @@ the installed contract. Fix that app policy through its own review rather than
 compensating with card or field padding. Bounded AppSidebar instances use h-full
 inside the shell's constrained column; standalone sidebars may use viewport height.
 
+Use one LayoutSidebarProvider for AppLayout's primary and secondarySidebar
+slots. Named scopes infer each AppSidebar/LayoutSidebar panel ID. Keep
+desktop openPanels separate from mobilePanel, the single active undocked drawer;
+update controlled props from their matching callbacks. Controlled openPanels
+takes precedence over legacy primary open. Target essential supporting panels
+with SidebarTrigger panelId, and use navigationPanel for the ordinary navigation
+trigger/shortcut. The WorkspaceRegionsLayout recipe accepts primaryNavigation
+and sidebarPresentation="rail" for a SidebarNavigationRail beside contextual
+navigation, with grouped primary navigation as an alternative. It demonstrates
+named state without a router dependency or another UIProvider. Inset framing
+does not supply Page padding, and shell header slots take Header partials.
+An embedded provider with adaptTo="container" contains its drawer and backdrop.
+Use one explicit trigger for the inline full navigation beside the static left
+area rail. Choose the contextual AppSidebar/LayoutSidebar `collapsible`
+independently of the shell preset or sidebar skin: `icon` retains a second
+compact column, `offcanvas` hides that panel and leaves only the primary rail,
+and `none` keeps it expanded. Keep the static primary rail on its own `none`
+policy. Current examples default to `icon` with a preview selector, and
+standalone sidebars support the same choices. The copied
+WorkspaceRegionsLayout recipe exposes `contextualCollapsible` with an `icon`
+default; a secondarySidebar replacement owns its own mode. The app's
+area-selection callback opens the corresponding contextual panel.
+At narrow widths the inline cluster pans a minimum
+page canvas, with its area rail pinned, and preserves expansion state. Shared
+header, navigation and Page owners supply spacing. Dedicated area rails use the
+background surface and an adjacent divider; their width is independent of
+full-sidebar icon collapse.
+
+SidebarNavigationRail shares AppSidebar's header, beforeNavigation,
+afterNavigation and footer render slots. Header/footer stay pinned and
+before/after content scrolls. Searchable AppSidebar retains its search band in
+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`.
@@ -116,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 still work. Use
+`defaultSearchValue` and `defaultOpen` for initial state, or pass
+`searchValue` and `open` to control it.

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

@@ -0,0 +1,94 @@
+# Product composition capability map
+
+Compare the product's actual tasks with these public contracts before writing
+JSX. A product view may combine existing owners and custom domain content; a new
+wrapper name or a similar screenshot does not establish a missing capability.
+Inspect exact types through `inspect-component.mjs`, including the prop/slot you
+intend to use. The app owns authoritative data, permissions and persistence.
+
+## Product view responsibilities
+
+| Task and input contract | Existing owner and supported seam | App responsibility / reason to extend |
+| --- | --- | --- |
+| Product identity, facts and optional supporting regions | `ProductOverview` from `themelia-react-ui/features/products`: `details`, `options`, `variants`, `readiness` and named `slots` | Choose only relevant regions. Page still owns route identity/commands/gutters. Add a domain subject through a region slot when its relationships need a different structure. |
+| Product imagery within identity | `ProductOverview.details.media`; a standalone region can use `slots.mainTop` | There is no top-level `ProductOverview.media` prop. `details.media` also supports a media-only subject; no dummy facts are required. |
+| Color/size definitions and their values, independently from a table | `ProductOptionsMatrix`: `optionGroups`, editing/collapse state, awaited `onSaveEditingOption`, `onError`, cancellation, `renderValue`, `renderOptionActions` | Preserve IDs, reconcile accepted changes with sellable variants and historical orders, and apply validation/transport. Do not replace this editor with custom buttons just to rename/remove values. |
+| Definitions and variant rows in one coordinated subject | `ProductVariantsManager`: `optionGroups`, `variants`, editing/grouping/selection state, row/bulk callbacks and render seams; `showGroupBy={false}` drops the Group by control for a short list. Each option's summary row is its edit button; `renderOptionActions` adds explicit commands | Its convenience arrangement is a choice. Supply accepted rows and real commands; it does not invent combinations or warehouse policy. Use separate matrix/table owners when placement needs to differ. |
+| Compare sellable SKUs, prices, availability and status | `ProductVariantsBulkTable`: `visibleColumns`, `groupByOptionId`, `cellDisplay`, `renderCell`, row and bulk callbacks. `ProductVariantsTable` supplies a simpler variant list. | Pass meaningful values and stable IDs. For one stock figure the inventory cell may suffice; keep per-location reservations or shortages as a richer related subject. |
+| Inspect the selected SKU and its chosen options | `ProductVariantDetails`: `variant`, `metadata`, `media`, `renderMetadata`, `renderOption`, `footerSlot` and action callbacks | Keep its identity/actions while adding warehouse, costing or allocation evidence through an appropriate slot or sibling region. A custom fact does not require rebuilding the whole variant subject. |
+| Edit ordinary variant fields and selected option choices | `ProductVariantEditor`: controlled/default values, `optionFields`, `statusOptions`, `visibleFields`, per-field `errors`, app-owned `children` fields, awaited `onSubmit`, `submitting`, `onError`, cancel and footer. Inside `ActionDrawer`, share one `formId` and set `showHeader={false}` so the drawer owns the title and commands | App validates and returns accepted state. Its inventory field is one string; hide it with `visibleFields={{ inventory: false }}` and add per-warehouse balances or unit cost as `children`, which render inside the form before its commands. |
+| Upload new local product images | `MediaGallery` from `themelia-react-ui/base/media-gallery`: controlled `File[]`, `onValueChange`, MIME/extension acceptance, file limit, previews, removal and keyboard/drag sorting | Transfer and persistence remain app-owned. The first file is the cover. This is not a persisted URL-record gallery. |
+| Existing images attached to a product | `MediaResourceGallery` from `themelia-react-ui/features/media-library`: `items`, typed `accessors`, `primaryId`, primary/remove/reorder callbacks, `onAdd`, `readOnly` and `renderItem` | Adapt existing IDs/URLs; accept attachment changes through app state/transport. Do not fetch remote URLs merely to manufacture `File` objects. |
+| Search/select reusable assets or upload into an asset catalogue | `MediaLibrary` or `MediaLibraryDialog`: item accessors, controlled selection, fetch/upload handlers and picker callbacks | The app owns catalogue requests and attachment persistence. A simple local file field does not require this complete workflow. |
+
+For a simple single-SKU product, omit option-definition/combination work that the
+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.
+
+## Media identity and lifecycle
+
+Ask whether the input is a new browser `File[]` or already stored asset records.
+Both can belong to a product gallery. The finder query `product media gallery`
+therefore exposes both owners; `local product images` and `existing product
+images` narrow the decision. Inspect their value and callback types before
+choosing one.
+
+MediaResourceGallery's accessors can read the app's own keys, filenames, image
+URLs and alt text. It owns its frame, title and insets; use it as the region
+surface instead of nesting it inside another Card. Choose `layout="grid"` or `"list"` to expose primary and
+move commands; the compact `"field"` layout focuses on attachment/removal.
+`onReorder` proposes IDs and records in the next order; these move controls differ
+from MediaGallery's drag/keyboard file sorting. `onAdd`
+usually opens the app's existing MediaLibraryDialog flow. Read-only presentation
+needs no attachment commands.
+
+`renderItem` replaces a complete gallery item, including its default controls.
+Use it for an actual media-representation requirement, such as a supplied sprite
+crop, while retaining the gallery's collection ownership. Reuse public buttons
+and the render context's permitted primary/remove/move actions if the custom
+item remains editable. A regular image URL needs no custom tile implementation.
+
+## Existing owners and domain-specific structure
+
+The comparison above is not a rule to force every product into ProductOverview
+or to forbid custom components. Record the required task, candidate, inspected
+prop/callback/render seam and remaining mismatch. For example, a warehouse
+comparison may extend ProductVariantDetails.renderMetadata or sit beside it;
+option name/value editing already has ProductOptionsMatrix. Keep controls,
+focus, action states and ordinary text roles with their public owners.
+
+Return the actual save Promise from ProductOptionsMatrix/Manager's
+`onSaveEditingOption`. The owner keeps the editor pending, retains a rejected
+draft with retry feedback, and requests closure through
+`onEditingOptionIdChange` after acceptance or cancellation. `onError` can report
+the failure to the app. Do not close/reset before the Promise settles or swallow
+the rejection in a fire-and-forget wrapper.
+
+Stock reservation arithmetic, option-to-variant reconciliation, unique SKU
+validation, accepted prices and publication policy belong to the app. Changing
+today's catalogue never rewrites a purchased order's selected options or prices.
+A thumbnail, a file picker, an attached-asset gallery and a selected variant's
+media slot have different contracts even if they show the same photograph.
+
+## Executable product parts
+
+The [product parts recipes](../examples/product-parts.tsx) show real option IDs,
+save/cancel editing, a variant comparison with SKU/price/availability values,
+the coordinated manager and a details/editor flow that retains a failed draft
+until the caller returns accepted values. The option-only example edits local
+definitions; it deliberately does not claim to reconcile a complete catalogue.
+
+The [product media recipes](../examples/product-media.tsx) contrast caller-owned
+File[] with typed persisted-asset accessors and attachment callbacks.
+`MediaOnlyProductOverview` uses the actual details.media slot without dummy
+metadata. No recipe changes a URL record into a File or imports private source.
+
+Verify the chosen configuration: edit then cancel/save an option, preserve its
+ID, select a different variant, inspect its media/stock, reject and retry a
+variant save, change a cover/remove/reorder assets when supported, and inspect
+narrow/wide light/dark output. Source typechecks, a retrieved symbol and the
+presence of a callback do not prove those interactions or useful composition.