themelia-react-ui 2.0.5 → 3.0.0

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

@@ -42,7 +42,10 @@ just name components or repeat an archetype.
 
 These criteria allow different product layouts. Do not impose a universal card
 count, row-line limit or one-column form rule. Emphasis is the exception: keep
-one solid primary command per page or surface, so the next action stays obvious.
+one leading primary command per task/surface, so the next action stays obvious.
+Independent forms can each own a primary submit. Fix a warning by reviewing its
+scope and owner; a DOM-lookup submit handler or flattening every FormSection
+does not establish a better composition.
 
 ## Done means
 
@@ -104,25 +107,51 @@ disabled 50% treatment remain valid; component disabled props keep that dimming
 with its owner.
 
 Standalone compact Cards and Page gutter removal also produce review warnings.
-`uncontained-table-in-card` flags a table in a padded Card: place DataTable in
-the layout, or deliberately use Card padding="none" and a flat table.
+`uncontained-table-in-card` follows tables through passive wrappers and known
+slots in padded Card/FormSection/explicit ChartCard surfaces. It also warns on
+tables in card/chart footers: place substantial tables in a body or peer layout
+region, or deliberately use Card padding="none" and a flat table.
+`form-actions-bar-placement` reviews a FormActionsBar under a padded surface or
+in a footer that already owns geometry; put action nodes directly in the footer
+or use an edge-to-edge bar in a zero-padding host. Both remain warnings because
+custom hosts need contextual review.
 `detached-filter-layout` recommends DataTable topbarContent for a sibling filter
 strip, or DataView for the complete workflow. `wide-single-column-form` suggests
-Page narrow for a simple form lacking explicit width or aside. These contextual
+Page narrow for a simple form lacking explicit width or aside. On mixed/tabbed
+routes, constrain only a form panel with Container maxWidth="md" gutter="none";
+`dynamic-page-measure` warns about expressions that can resize the route header
+along with the body. Deliberate responsive sizing remains valid. These contextual
 warnings follow qualified import bindings; unrelated same-name components are
-not evidence. Deprecated resource shells use the existing deprecated-owner
-warning and direct new routes to Page.
-Buttons placed in a Page or PageHeader `actions` region warn as well: pass
+not evidence. The resource shells were removed in 3.0: importing one is an
+unknown-symbol error, and new routes use Page.
+Buttons placed in a header's `actions` region (AsideNavShell,
+WorkspaceRecordHeader or PageHeading) warn as well: pass
 commands as `primaryAction` and ordered `secondaryActions` so the header owns
-their emphasis, size and overflow. Non-command controls stay valid there.
+their emphasis, size and overflow. Non-command controls stay valid there; Page
+takes them in `toolbar`.
 For PageHeader's `slots.actions`, wrapping or returning the callback's
 `defaultContent` retains that command behavior; a full replacement owns its
 keyboard, overflow and action semantics. Inspect the compact menu below 40rem of
 header width, including in a narrow parent on desktop: every command, including
 primary, belongs in one More actions menu.
-A Page with more than one solid primary command, counting `header.primaryAction`
-and every Button with `tone="primary"` and no other style, warns as well. Overlays own
-their own primary command and are not counted. Raw palette classes such as
+A Page with more than one solid primary command in the same task scope warns,
+counting `header.primaryAction`, solid Button tone="primary", and
+SubmitStateButton's default primary. Native forms (including a public owner's
+native form `render`) and overlays own separate command scopes; exclusive
+conditional branches use their maximum count. Local submits stay with their
+form. `remote-header-form-submit` reviews header handlers that call
+document.getElementById and requestSubmit, including same-file callback values;
+a deliberate single full-page editor can keep its header submit with native
+validation and appropriate form association.
+
+`heavy-cell-disclosure` reviews Accordion, SmartAccordion, DataTable and CodeBlock
+inside statically visible DataTable `columns.cell` renderers, separately from
+column headers and portaled record details. Prefer a summary plus rowActions
+opening an overlay or detail route; intentional accessible inline disclosure is
+valid. `single-option-choice-group` suggests boolean controls for one static
+choice, without banning two-option sets or filtered real choice domains.
+
+Raw palette classes such as
 `bg-blue-500`, `text-gray-600` or `border-white` warn on any element; use a
 semantic surface/foreground pair or a status tone. A Card title icon and an icon on
 more than one MetadataList fact warn as decoration; keep a glyph only when it
@@ -133,7 +162,9 @@ native button passed as a package owner's `render`, such as an Item row
 rendered as a button, is that owner's root and does not warn.
 Verified Card-owning Metric/card-grid, UsageCard and TaskCard compositions also
 participate in nested-surface and peer-gap review. Metric without its card variant,
-compact MetricGrid, flat TaskCard, ChartCard and Receipt do not establish a frame.
+compact MetricGrid, flat TaskCard, default ChartCard and Receipt do not establish
+a frame. FormSection has a Card by default; ChartCard establishes one only with
+an explicit non-flat surface. Unknown surface values/spreads are not proof of a frame.
 Direct framed/default Card peers, including GridCell-wrapped peers, in a statically
 small Stack/Grid gap also warn; omitted gaps use the actual component defaults.
 Review visible ring clearance and the application's ordinary surface policy.
@@ -148,9 +179,20 @@ Use existing app lint/typechecking for wider language, utility and accessibility
 coverage. The script is deliberately small and does not replace them.
 
 Coverage is limited to direct public imports, aliases/namespaces, native paragraph/
-heading copy and same-file static classes/styles/props. Dynamic expressions are reported as unresolved;
-cross-file wrappers, external CSS, render functions and runtime values require
-review. Do not treat an empty report as proof of complete compliance or taste.
+heading copy and same-file static classes/styles/props/JSX slot values. Paired
+and self-closing elements retain their slot owner; opaque app components and
+known portals form separate regions. Inline cell renderers are inspected when
+their JSX is available, without executing application code. Dynamic geometry,
+classes and spread values are disclosed as unresolved where inspected;
+cross-file wrappers, external CSS and runtime composition require review. Do not
+treat an empty report as proof of complete compliance or taste. Test source
+rules through analyzer findings, and UI behavior through executed outcomes;
+regex assertions over app JSX cannot establish either visual quality or callbacks.
+Local helpers invoked to produce JSX (for example `footerSlot={renderFooter()}`)
+are not evaluated. Dynamically constructed whole header objects are disclosed
+as unresolved; review their action scopes separately. Native ReactDOM
+createPortal calls retain their lexical binding and start a separate rendered
+region, like the supported public overlay owners.
 
 ## Rendered and interaction evidence
 

package/docs/consumer-skill/references/rhf-workflows.md

@@ -17,6 +17,27 @@ The complete [order edit page](../examples/rhf-edit-page.tsx) composes:
 
 Page owns the route title/gutters and TwoColumnLayout owns peer rhythm. FormSection owns its surface and field gaps; do not wrap a framed FormSection in another Card. Inside an already padded boundary, use `surface="flat" padding="none"`. Inside an unpadded boundary, a flat FormSection keeps its ordinary inset; flat surface alone does not remove padding. `handleSubmit` validates and awaits persistence. `isSubmitting` drives the submit button and disabled fields; `isDirty` drives dirty feedback and pristine submit protection. An in-flight ref also blocks duplicate same-tick requests. Native form validation is disabled in these RHF examples so the schema/rules produce one consistent error source.
 
+Choose each section's frame from its actual parent. Independent FormSections on
+the page can keep their default card surface; flattening a section whose content
+already consists of Cards does not require flattening unrelated sibling forms.
+
+`FormActionsBar` owns a top divider, opaque background and surface inset. Use
+`leading` for status and `trailing` (or `children`) for action nodes. In
+`Card padding="none"`, flat FormSections keep their body inset and the bar sits
+edge-to-edge after them. In an ordinary Card's `footerSlot` or FormSection's
+`footer`, place the buttons directly: the host already owns the footer geometry.
+`SubmitStateButton` defaults to `type="submit"` and primary tone; pass
+`submitting`, `dirty` and `disableWhenPristine` for pending/pristine behavior.
+
+Independent forms own independent submit commands. Keep a lookup beside its
+input and settings saves with their edited fields; page command guidance does
+not require moving these into `Page.header`. For a single full-page editor, a
+deliberate header submit can use native form association (`type="submit"` and
+`form` on a Button in a supported slot). Preserve browser validation and one
+submit lifecycle; routine `document.getElementById(...).requestSubmit()` handlers
+add unnecessary coupling. Tests should execute validation, pending, error/draft
+retention and accepted persistence rather than assert a particular source string.
+
 Page forwards `render` to its existing Container, so rendering it as the form preserves one width, gutter and query-boundary owner. Its body already spaces direct subjects; no extra Container or Stack is needed around the layout and action bar. `TwoColumnLayout adaptTo="container"` adapts to that Page width. A standalone form outside Page needs its own deliberate query boundary when it selects container adaptation.
 
 Use `useFieldArray`'s stable `field.id` as the React key, preserve names such as `lines.${index}.quantity`, and set complete append defaults. Derive totals from `useWatch`; do not persist a second total that can drift. Collect nested client/server errors into ErrorSummary while keeping each field's local message. Use `setFocus` or summary links for focusable controls when the app's error-summary design requires it.
@@ -40,12 +61,63 @@ Mount an editor with `key={record.id}` when switching records. `defaultValues` e
 | SliderField (public slider name) | scalar `value: number` | `onValueChange(value)`; `inputRef`, `onBlur` |
 | ColorInput | `value: string` | `onValueChange(value)`; input `ref`, `onBlur` |
 
+Set DatePicker's `mode` explicitly when binding its callback. `mode="single"`
+narrows the output to `DateOutput`; range and multiple modes have their own
+value/output shapes. The runtime's single-mode default does not narrow the
+unified callback's contextual TypeScript type.
+
+Bind an empty controlled date field with `value={field.value ?? undefined}`.
+An external reset to that empty value clears single, multiple, range and
+month/year selections. Do not also pass `defaultValue` unless restoring that
+fallback is intentional; RHF's `defaultValues` owns the saved form baseline.
+
 For numeric Input fields normalize `event.target.valueAsNumber` according to the schema (an empty field is NaN); keep numeric validation explicit. Date-only fields need an application serialization policy; do not turn a local calendar date into a UTC instant accidentally. DateTimeInput uses ISO instants. Use `modal={false}` on pickers inside modal forms to avoid competing focus traps.
 
 ControlledFormField accepts a ReactNode error override or a name-based error getter, falling back to RHF validation. Its render callback's error argument remains string/undefined for compatibility. A direct supported control receives the generated label/control ID and supporting-text association automatically; omit routine `htmlFor`/`id` pairs. Each mount stays unique even when forms share field names. ToggleField and SwitchCard own their visible labels and forward the automatic supporting description to their editable control; omit an outer duplicate label.
 
+Use `FormRichTextEditor` from `themelia-react-ui/features/rich-text-editor`
+inside an RHF `FormProvider`. Pass its field name and wrap it in `FormField`
+with the field's validation message. The binding handles touch, focus,
+invalid and disabled state. Both editor modes use the same field association.
+Native form data includes the committed HTML for enabled, named editors.
+Switch from HTML source to rich text to commit a source draft.
+
+WeightInput, DimensionsInput and CoordinatesInput can bind `field.onChange`
+through `onValueChange` and `field.onBlur` through `onBlur`. Their legacy
+event-shaped callbacks still receive the same value. Native `name` submits
+one numeric string, using `widthxheightxdepth` for dimensions and
+`latitude,longitude` for coordinates. The React callback retains the
+selected string or object format.
+
+TimePicker accepts the same direct `value` and `onValueChange` binding
+and submits a named 24-hour value in either mode. Bind `field.onBlur`
+to report leaving the complete picker, including its open popover.
+
+### Empty selections
+
+| Owner | Empty value |
+| --- | --- |
+| PillRadioGroup with `allowClear` | `null` |
+| Combobox and AsyncResourceCombobox | `null` |
+| MultiCombobox | An empty array |
+| Select and RoundingModeSelect with `allowClear` | `undefined` |
+| DateTimeInput | `undefined` |
+| TimePicker | A controlled `null` shows an empty time. Editing emits aligned strings. |
+
+Normalize nullable callbacks at the form boundary when the app uses one
+empty value. An explicit `value={undefined}` keeps PillRadioGroup controlled.
+Omit `value` to use its `defaultValue`. A shared clear sentinel would require
+a major release.
+
 Compound children own their nested association. SliderField's `id` and forwarded `ref` name its group, while `inputRef` names the native range. The binding recipe uses visible copy with an ID, `aria-labelledby` on SliderField and `supportingTextId`/`aria-describedby` for its hint or error. Keep explicit IDs per mount when a passive wrapper separates chrome from the editable control; do not point `htmlFor` at a group or infer one common ref target across control families.
 
+FormField honors an explicit `htmlFor` target already declared in descendant JSX,
+including arrays/fragments, without copying its ID or name onto the outer wrapper.
+It does not inspect custom component bodies. If a compound creates its nested
+controls internally, put it inside Stack or a native container and assign the
+target ID and supporting-text attributes to the actual control. Direct controls
+without an ID retain automatic association.
+
 ## Transport lifecycle
 
 The app owns transport. RHF's submit callback must return a Promise spanning the complete request; otherwise `isSubmitting` drops early and repeated submissions become possible. The [callback bridge](../examples/rhf-transport.tsx) records success/errors/cancellation, then settles only from `onFinish`. It has no framework import or runtime dependency.

package/docs/consumer-skill/references/screen-archetypes.md

@@ -25,10 +25,10 @@ a simple facts subject does not require a custom component.
 | User access / permissions | Page → profile and role context → editable permission groups → save/discard feedback | [User permissions](../../../templates/user-permissions-template.tsx) | Role presets, permission draft, permitted commands, accepted-save/discard baseline and server enforcement |
 | Analytics overview | Page period control → numeric MetricBar/MetricGrid → ChartCard with Recharts series and comparison Cards → operations/usage regions | [Operations analytics](../../../templates/analytics-operations-template.tsx), [analytics states](../examples/analytics.tsx) | Period/query, metric formatting, accepted series, independent loading/error/retry states |
 
-Page uses explicit maxWidth first, then narrow md (48rem), aside xl (80rem), otherwise lg (64rem). Settings navigation uses Page → SettingsShell → FormSection. Page owns its h1, gutters and direct-child rhythm; TwoColumnLayout owns the column split and peer-region rhythm. Stack/Grid own nested sibling gaps. Card owns framing and aligned header/body/footer insets. Authentication uses [AuthShell](authentication.md), and content sites use [Container/Section](../examples/website.tsx).
+Page uses explicit maxWidth first, then narrow md (48rem), aside xl (80rem), otherwise lg (64rem). Settings navigation uses Page → AsideNavShell → FormSection. Page owns its h1, gutters and direct-child rhythm; TwoColumnLayout owns the column split and peer-region rhythm. Stack/Grid own nested sibling gaps. Card owns framing and aligned header/body/footer insets. Authentication uses [AuthShell](authentication.md), and content sites use [Container/Section](../examples/website.tsx).
 
 Keep FilterLayout inside DataTable topbarContent with variant="compact" and showClearFilters, under FilterProvider; DataView is the complete alternative. Table owns its frame/topbar/header band and sits directly in the layout. A deliberate Card host uses padding="none" and a flat table. Fixed scope belongs in page context or tabs, independently of removable criteria.
 
-Headers carry one primary command and ordered secondary commands; below 40rem of header width all commands share one More actions trigger. Page header slots beforeTitle/titleSuffix/afterDescription/actions accept content or callbacks with {renderLink, defaultContent}. Compose status and facts with Badge/MetadataList; wrap or return actions defaultContent to retain the command row. Compatible direct actions add non-command controls. Put destructive commands behind ConfirmDialog. Longer create/edit work belongs in ActionDrawer; a short focused form uses ActionDialog. Preserve a snapshot until save succeeds. Templates are copyable application sources, not package component entrypoints.
+Headers carry one primary command and ordered secondary commands; below 40rem of header width all commands share one More actions trigger. Page header slots beforeTitle/titleSuffix/afterDescription/actions accept content or callbacks with {renderLink, defaultContent}. Compose status and facts with Badge/MetadataList; wrap or return actions defaultContent to retain the command row. Non-command controls go in Page toolbar. Put destructive commands behind ConfirmDialog. Longer create/edit work belongs in ActionDrawer; a short focused form uses ActionDialog. Preserve a snapshot until save succeeds. Templates are copyable application sources, not package component entrypoints.
 
 Read only the relevant detail: [composition ownership](composition.md), [workflow states](workflows.md), [RHF transport and bindings](rhf-workflows.md), or [analytics contracts](analytics.md). The [review checklist](review.md) separates static checks from opened-surface and interaction evidence.

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

@@ -4,6 +4,10 @@ The [design contract](design-contract.md) records which geometry changes togethe
 and which variant choices remain independent. Retheme shared responsibilities;
 avoid overriding individual components to imitate another density or inset.
 
+Set the application's document font and page background/foreground through the
+[host CSS setup](installation.md#set-the-application-canvas). Importing package
+styles defines theme roles without painting the document or resetting app markup.
+
 Use shadcn semantic surfaces/foregrounds: background, card, popover, primary, secondary, muted, accent, destructive, border, input, ring, charts and sidebar. Central success/info/warning foreground pairs express states; never overload primary or statuses as decoration. `--input` is the shared resting control boundary: fields, select and date triggers, checkboxes, radios, switch tracks and outline buttons draw it. Its defaults follow shadcn neutral: `oklch(0.922 0 0)` in light mode and `oklch(1 0 0 / 15%)` in dark mode. `--border` remains the surface/divider role, and `--ring` owns the stronger focus indicator. No extra border variable or component opacity is needed. Resting borders have no blanket 3:1 requirement in this palette; focus retains its separate tested 3:1 contract. When rebranding, review resting, focused and invalid states on the actual surfaces; an application requiring stronger boundaries can override the existing `--input` role.
 
 tokens.json distinguishes 23 structural roots, advanced typography/status settings, and derived utility spellings. A utility is not another public variable. Keep overrides in one stylesheet at root or ThemeScope, without copying computed CSS into JavaScript.
@@ -52,7 +56,7 @@ Action and editable-control heights are separate roles; keep roots equal for adj
 Control heights are nominal floors when custom typography needs more room.
 Native fields, Select and InputGroup frames fit their editable line plus the
 border, and cap vertical padding to the space remaining in the nominal height.
-The default 28/32/36px sizes (2rem roots, steps in eighths) and radius roles stay unchanged. Text actions grow
+The default sizes of about 30/34/38px (2.125rem roots, steps in eighths) and radius roles stay unchanged. Text actions grow
 under their intentionally tighter leading, so independently enlarged type can
 produce different fitted heights even with equal action/control roots. Check
 type size, leading and height roots together when exact custom pairing matters.
@@ -66,9 +70,10 @@ control heights and copy gaps keep their independent roots.
 | Actions versus fields | `--height-action` versus `--height-control`; default size uses the root times density-scale |
 | Native field text inset | `--control-x` times space-scale; icons/add-ons use shared derived clearance |
 | Collection inline inset | `--row-x` times space-scale |
-| Collection block inset | `--row-y` times density-scale; compact/comfortable use 0.75/1.25 multipliers |
+| Item/table row block inset | `--row-y` times density-scale; compact/comfortable use 0.75/1.25 multipliers where supported |
+| Anchored collection block inset | Default/comfortable use 0.75/1 × `--row-y` × density-scale; compact uses the spacing-scaled 2xs step |
 | Surface tiers | `--surface-x` / `--surface-y`, times space-scale; xs/sm/md/lg use 1/2, 2/3, 1 and 4/3 |
-| Menu header/footer inline inset | Half surface-x plus row-x, then space-scale; no additional public token |
+| Menu header/footer inline inset | Compact bands use the md spacing step; plain header/footer copy adds the xs step. Leading controls and actions stay on the band edge. |
 
 Rich display popovers use the surface roots (24px by default); compact menu/list shells use the md spacing role (8px), scaled once by --space-scale. Row inline padding and density stay independent.
 

package/docs/consumer-skill/references/tokens.json

@@ -1,6 +1,6 @@
 {
   "package": "themelia-react-ui",
-  "version": "2.0.5",
+  "version": "3.0.0",
   "structural": [
     {
       "name": "--space-scale",
@@ -24,17 +24,17 @@
     },
     {
       "name": "--height-action",
-      "default": "2rem",
+      "default": "2.125rem",
       "purpose": "Default button and action-trigger height."
     },
     {
       "name": "--height-control",
-      "default": "2rem",
+      "default": "2.125rem",
       "purpose": "Default input, select, and field-control height."
     },
     {
       "name": "--control-x",
-      "default": "0.75rem",
+      "default": "0.875rem",
       "purpose": "Default inline padding for buttons and field controls."
     },
     {

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

@@ -130,8 +130,8 @@ slots (`beforeTitle`, `titleSuffix`, `afterDescription`, `actions`) accept conte
 or a callback receiving `{ renderLink, defaultContent }`; an actions callback
 can wrap or return `defaultContent` to retain responsive commands. A replacement
 owns its behavior. Below 40rem of actual header width, all commands, including
-primary, share one More actions trigger. `PageHeader` serves a custom shell; `PageActions` is
-deprecated. The [layout recipe](../examples/app-layout.tsx) demonstrates that
+primary, share one More actions trigger. `PageHeader` serves a custom shell; `PageActions` was
+removed in 3.0. The [layout recipe](../examples/app-layout.tsx) demonstrates that
 route boundary; the [detail recipe](../examples/detail.tsx) demonstrates the
 record route and an independently framed subject with MetadataList and value
 primitives. Decide whether the record needs that independent Card before nesting
@@ -141,11 +141,11 @@ scrolling only. App navigation, record loading/missing/error/retry, permissions,
 edit and delete callbacks remain application responsibilities.
 
 Use `WorkspaceLayout` from `themelia-react-ui/layout/workspace` when independently composed record header,
-sidebar/main/rail regions are needed; inspect `features/resource` for complete
-resource coordination. A single record does not automatically need either.
-Their headers (`WorkspaceRecordHeader`, `ResourceHeader` and the resource shells)
-take the same `primaryAction` and `secondaryActions` as Page; keep their
-`actions` for non-command controls.
+sidebar/main/rail regions are needed; `features/resource` keeps
+`ResourceActionBar`, `ResourceDetailsSection` and `ResourceEmptyState`. A single
+record does not automatically need either.
+`WorkspaceRecordHeader` takes the same `primaryAction` and `secondaryActions` as
+Page; keep its `actions` for non-command controls.
 Read [layout composition](composition.md#application-layouts) for boundary and
 parent-width behavior, then the exact selected declaration for its current props.