themelia-react-ui 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+## 1.0.1 — 2026-10-12
+
+- Consumer guidance now assigns task, scope, information priority and command
+  ownership before composition, with focused decision tables and review criteria.
+- Expand the consumer entrypoint with explicit typography/content, responsive
+  layout, localization/RTL, controlled-state and verification routing. Document
+  RichText's block container and sanitization boundaries in composition guidance.
+- Add a scoped directory recipe using Page, ResourceCell, native table query
+  slots and fixed-scope callbacks; detail facts use MetadataList.
+- Curated responsibility discovery ranks exact intent aliases beneath explicit
+  symbols/imports. Authored catalogue guidance refreshes into shipped metadata
+  and is checked for drift.
+- Ship an opt-in, read-only composition checker using the app's TypeScript dev
+  dependency. Known import/anatomy errors fail; contextual warnings and unresolved
+  dynamic values remain review evidence. Popup policy is shared with repo lint.
+- Copied-skill setup compares every installed guidance asset, including prose.
+  Installed-package checks exercise the checker and scoped directory; maintainers
+  have a separate rubric for authorized independent agent evaluations.
+- No public component APIs, theme roots or runtime dependencies change.
+- Container and DataTable explicitly own border-box sizing so page gutters and
+  framed tables stay within narrow parents without consumer preflight.
+
+## 1.0.0 — initial release
+
+### Added compositions and controls
+
+- `TaskCard` (`blocks/planning`): compact and expanded task summaries, segmented
+  animated completion, tightly spaced checked/struck-through subtasks, assignees
+  and application-owned saving/errors. Passive header clicks and the native
+  keyboard caret share controlled/uncontrolled expansion; subtask and footer
+  actions remain independent.
+- `UsageCard` (`blocks/analytics/usage-card`): quota, category, daily and resource
+  analytics, controlled periods, loading/error/retry/empty presentation and
+  explicit missing/unlimited/over-limit states. Its leaf import isolates
+  unrelated analytics peers.
+- `InlineEdit` (`base/inline-edit`): native Input/Textarea editing with shared
+  control styling and state props, typed native editor options, validation,
+  cancellable async persistence and committed native-form values. Small centered
+  actions and the persistent width/fade transition honor reduced motion.
+
+### Shared refinements
+
+- Card gains an additive semantic `gap` prop for its regions, preserving default
+  insets and spacing. Normal/dense supporting-copy rhythm remains independent.
+- Avatar sizes and overlap follow scoped avatar/space roots in all sizes and
+  RTL, including overflow-only counts.
+- Field-shaped triggers share Input's focus offset and transparent hover recipe.
+- Public entrypoints, catalogue examples, packaged discovery, consumer recipes
+  and installed-runtime coverage include the new owners. Existing typography,
+  control, row and surface recipes are reused; no dependencies or public theme
+  roots are added.
+
+### Initial release scope
+
+The npm package and all consumer imports use `themelia-react-ui`, branded
+Themelia React UI. The GitHub repository remains `themelia-react-ui`. The
+former development package names were corrected before this initial release.
+Version `1.0.0` aligns the package, lockfile, preview and consumer guidance.
+Publication builds fresh ESM, CSS and declarations and checks
+the packaged consumer guidance before packing.
+
+Five AppLayout presets share existing shell, header, sidebar and page owners.
+Parent-driven sidebar/header adaptation supports embedded and full-screen
+layouts, stable focus order and scoped dark-header menus. Metric cards retain
+Card insets, normal copy gaps and responsive maximum column counts.
+
+The source-entrypoint contract now verifies every exact TypeScript preview
+alias, including Receipt, so a prior local dist build cannot hide a missing
+alias on a clean CI checkout.
+
+Tree defaults to single-line compact navigation rows, sharing Sidebar row
+heights, insets and density recipes. Supporting copy/wrapping requires explicit
+`rowLayout="rich"`; string descriptions remain available to hover and accessibility. AiFileTree
+uses Tree for keyboard navigation and independent controlled expansion, with
+semantic Badge statuses and inherited disability. It no longer adds its own
+frame or row tint: compose Card around it where a frame is required. Explicit
+indentation and file-selection APIs remain supported. Sidebar custom renderers
+gain effective disability and a library-owned children seam; logical guides and
+centered sibling disclosure controls work in both directions.
+
+Add focused Tree, Cascader, SignaturePad, Questionnaire, CodeBlock, Attachment
+and Message families with public examples and installed consumer recipes. They
+add no dependencies or public token roots. Existing AI and upload APIs reuse
+the shared presentation owners; AppSidebar gains search and controlled branch
+disclosures independent of navigation.
+
+Production auditing hardens controlled hierarchy focus, async source replacement,
+clipboard feedback, native signature/questionnaire resets, validation and status
+announcements. Tree sibling labels and RTL code actions share the correct geometry;
+dark secondary copy meets the text contrast contract on accent surfaces. Inverse
+gift-card copy actions retain their paired foreground on hover.
+
+Initial standalone Themelia React package using Base UI, Tailwind and shadcn-compatible semantic themes. Exact family entrypoints preserve the public typography, values, controls, layouts, blocks and callback-driven feature contracts. Optional feature peers remain isolated from basic imports.
+
+Receipt and ReceiptItems add a themed, composable paper surface to Commerce blocks, with Card insets, resize-aware perforated edges, shared Money formatting and optional QR composition. Authoritative line totals preserve application accounting; QR dependencies remain optional.
+
+EmailComposer provides ordinary messages, templates, structured variable documents,
+application-owned asynchronous data and callback-driven delivery. A separate
+`features/email-composer/engine` entrypoint supports server preparation without
+the editor runtime. Draft proposals and delivery callbacks receive detached
+payloads; resolved subjects must remain nonempty and single-line.
+
+The complete packaged consumer skill provides version-matched public imports, declarations, responsibility and selection guidance, a portable Node finder, token metadata and progressive workflow recipes. The recipes cover collection/navigation, detail, validated editing and asynchronous destructive confirmation with application-owned effects.
+
+Current guidance uses Card for headed/flat composition, PopoverContent for custom
+surface anatomy, independent density/size/inset/copy-gap choices and shared private
+geometry recipes. ContentBlock and SmartCard remain migration exports. Installed
+setup resolves ESM-only exports from nested app directories and compares copied
+metadata with the installation; package checks execute that shipped recipe and
+reject mixed-release metadata or deprecated composition imports in new examples.
+
+Portable static documentation is generated into `dist-docs/` with a version directory containing the same skill assets and published declarations. Local agent/release checks and a GitHub Actions template verify build, tarball consumption, browser behavior and documentation. Registry publication and hosting are pending; this draft is not a claim that a remote release or CI run has occurred.
+
+See [README migration notes](README.md#deliberate-migration-changes) and the [release guide](docs/releasing.md) before upgrading or publishing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicolas Vlachos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,283 @@
-# Temporary Holding Version
+# Themelia React UI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A publishable React UI package built on Base UI and Tailwind, with shadcn-compatible themes and Themelia's public APIs. Routing, persistence, permissions and translations remain consumer-owned.
+
+Package: **`themelia-react-ui`** · current version: **`1.0.1`** · MIT licensed.
+The GitHub repository is `themelia-react-ui`; npm imports use `themelia-react-ui`.
+
+Consuming apps start with [consumer setup](#consumer-setup) and the packaged
+[consumer skill](docs/consumer-skill/SKILL.md). The Development section and
+repository check commands below apply to this checkout.
+
+The source port covers typography, semantic value primitives, 41 base families, 10 layout families, nine block families and 25 feature families. Products include option matrices, option editing, variant generation, managers, detail/editor surfaces, bulk selection/actions, readiness, policies and quote previews. Features contain their actual callback-driven implementations; the playground uses the same public entrypoints.
+
+Commerce blocks include `Receipt` and `ReceiptItems` from `themelia-react-ui/blocks/commerce/receipt`. Receipt owns the paper surface and delegates insets to Card; compose MetadataList, Money, separators and an optional QRCode slot. Currency/locale follow the shared formatter contract; accounting totals and verification destinations remain app-owned. See the packaged [receipt recipe](docs/consumer-skill/examples/receipt.tsx).
+
+## Development
+
+For repository development and verification, use Node 24.12+ within the Node 24 line, or Node 26, and npm. CI pins 24.12.0; local checks ran on 26.3.1. The package consumer engine contract remains `>=22.12.0`, separate from the verification toolchain:
+
+```sh
+npm ci
+npm run dev
+npm run check:all
+```
+
+The Vite React playground has foundations, a complete searchable catalogue, and an interactive products workspace. The catalogue groups Foundations (including semantic primitives and composition structures), Base components, Layouts, Blocks, and domain Features. Layouts includes five composed AppLayout presets (light header, dark header, sidebar, inset canvas and stacked navigation), plus a responsive composition guide for viewport grids, parent-driven grids, wrapping actions and stable content order. Navigation uses actual package families, static domain headings above Features, padded disclosures and a single Skeletons family page. Expansion persists across page changes and mobile drawer closure; search shows the same group context. `/` opens the full catalogue with preview-only hash navigation (`/?page=catalog` also works); `/?page=products` exercises options, generation, validation, async save/retry and bulk actions. React Router is not a dependency.
+
+`build` emits ESM entrypoints, TypeScript declarations, compiled component CSS, editable Tailwind theme source and optional map styles. Playground files stay outside the tarball. `check:contract` enforces exact exports, retained source symbols, component layers, dependencies and token ownership. `check:preview` verifies ready routes, example files, exact current public symbols, published imports and public family coverage. `check:docs` verifies local props for source-origin-qualified public callable owners, including all static displayed PropsTables. `check:package` requires a fresh `npm run build`. It installs the tarball into an isolated consumer, checks strict declarations for every family and matches installed declaration exports to the source-backed skill index. Its installed basic fixture checks SSR/hydration and executes provider defaults, controlled Input/Select/Checkbox state, form submission/validation/reset, scoped overlay portals and async confirmation/retry. Native links retain a separate strict typecheck and Vite-build smoke. The optional fixture exercises controlled table sorting/selection/visibility and client module initialization for specialist peers. Initialization does not establish specialist workflow or server-rendering support. It uses the configured npm cache, or `THEMELIA_NPM_CACHE`; a fresh `npm ci` cache may lack fixture registry metadata. Use `THEMELIA_FIXTURE_INSTALL=online` explicitly for cold temporary consumers, or supply a prepared cache for the default offline install. See [release readiness](docs/releasing.md).
+
+`lint` runs development-only `@shadcn/lint` through Oxlint: semantic colors across components, shared recipes and preview TSX and fixed typography contracts in preview examples. `check:design-lint` proves rule recognition, package stylesheet discovery and permitted customization. Both run inside `check`; `.oxlintrc.json` owns the staged policy. See [typography and lint guidance](docs/typography-and-design-lint.md).
+
+`check` runs source/documentation checks, lint/design/types/unit checks, one library build, built declaration/skill and source-map checks, the installed package harness, then one preview build, in order. `check:all` adds the curated browser regression suite against that fresh static output, with zero retries. `test:browser` rebuilds the preview and runs those regressions independently. Exactly `deep-visual-audit.spec.ts` and `deep-audit-slices.spec.ts` are evidence collectors: `collect:browser` runs them separately, and their successful collection does not establish visual acceptance. Regression screenshots use per-test Playwright output paths. Set `THEMELIA_EVIDENCE_OUTPUT` to an explicit durable directory only when preserving a review; collectors also accept `AUDIT_OUTPUT`.
+
+Documentation refreshes are explicit: `docs:sync-preview` owns catalogue public symbols and authored literal selection guidance, `docs:sync-props` owns local prop names/types/required flags and branch constraints, and `docs:sync-skill` owns consumer references. Checks never refresh them. Existing props prose and defaults remain reviewed metadata; native fields and undisplayed historical nonpublic records remain imported evidence. Catalog digest fields retain their historical imported scope and are not freshness checks.
+
+Browser verification requires Playwright Chromium. An existing executable can be supplied through `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`.
+
+## Consumer setup
+
+Install a built tarball; use a registry release when available. React 19, React DOM 19, Base UI 1.8+ and Lucide React 1 are required peers. Import exact family paths; there is no aggregate component barrel or public raw UI entrypoint.
+
+After the initial registry release, install into a React 19 application with:
+
+```sh
+npm install themelia-react-ui @base-ui/react lucide-react
+```
+
+```tsx
+import 'themelia-react-ui/style.css'
+import { UIProvider, ThemeScope } from 'themelia-react-ui/ui-provider'
+import { Button } from 'themelia-react-ui/base/buttons'
+import { Input } from 'themelia-react-ui/base/text-inputs'
+import { Card } from 'themelia-react-ui/base/cards'
+import { Stack } from 'themelia-react-ui/base/structure'
+
+export function Example() {
+  return (
+    <UIProvider config={{ typography: { defaultTextSize: 'sm' } }}>
+      <ThemeScope style={{ '--height-action': '2.5rem', '--height-control': '2.5rem' }}>
+        <Card title="Account">
+          <Stack gap="lg">
+            <Input aria-label="Name" />
+            <Button onClick={() => {}}>Save</Button>
+          </Stack>
+        </Card>
+      </ThemeScope>
+    </UIProvider>
+  )
+}
+```
+
+`UIProvider` is isolated and mount-once; configuration resolves explicit prop → provider default → fallback. Use direct props for per-instance state. It supports formatting, money, dates, comments, typography, density, items, buttons, badges, cards, toasts and spinners. `ThemeScope` is a CSS inheritance host; portaled menus, tooltips and overlays stay inside the nearest scope. Explicit Base UI portal containers take precedence.
+
+Compiled `style.css` requires no source scanning and includes no global preflight. Your app supplies its reset. Load library CSS before app overrides. A Tailwind v4 application can additionally import `theme.css` after Tailwind to use the same mappings in its own classes; this editable file contains Tailwind directives and needs processing.
+
+React component chunks preserve `"use client"` boundaries for frameworks such as Next App Router. Pure utilities remain server-usable. Navigation uses native links, callbacks and render composition supplied by the consuming app.
+
+## Motion
+
+Disclosures expand and collapse using Base UI's measured panel height. Dialogs and confirmations fade with a slight scale; drawers slide from their configured edge; menus, popovers, Select, Combobox and tooltips share restrained anchored-surface transitions. The private recipes use 150–250ms entrance durations and shorter popup/modal exits. CSS transitions can reverse during rapid toggles, and expanded disclosures return to natural height so later content changes remain visible.
+
+The shipped stylesheet follows `prefers-reduced-motion` automatically for these transitions and disclosure chevrons. Base UI continues to own presence, keyboard behavior, dismissal and focus restoration. Existing component classes, refs and props remain available; motion introduces no runtime dependency, provider configuration or public theme roots. A Select popup aligned directly over its trigger retains its existing immediate presentation.
+
+## Exact entrypoints
+
+| Layer | Paths |
+| --- | --- |
+| Foundation | `typography`, `typography/rich-text`, `primitives`, `ui-provider`, `component-vocabulary`, `action-presentation`, `services/actions`, `lib/utils`, `lib/strings` |
+| Base | `base/<family>` — controls, forms, buttons, cards, structure, navigation, menus, feedback, display, tables, uploads and specialist controls |
+| Layout | `layout`, `layout/<family>` — application shell, authentication, containers, page, settings, header, navigation, sidebar, workspace and hooks |
+| Blocks | `blocks/admin`, `ai`, `analytics`, `commerce`, `data-display`, `onboarding`, `timelines` (each prefixed `blocks/`) |
+| Features | `features/activities`, `ai-chat`, `async-preview`, `combobox`, `comments`, `data-view`, `email-composer`, `event-calendar`, `filters`, `global-search`, `kanban`, `map`, `media-library`, `mentions`, `overlays`, `products`, `resource`, `resource-assignment`, `rich-text-editor`, `schema-form`, `suggestions`, `sync`, `table`, `theme-tweaker` (each prefixed `features/`) |
+
+The complete machine-readable entry inventory is `scripts/entries.json`. Dialogs and confirmations use `ActionDialog`, `ActionDrawer`, `ConfirmDialog` and visibility/action hooks from `features/overlays`.
+
+## Optional feature peers
+
+Basic typography, structures and buttons do not import specialist dependencies. Install peers for the families you use:
+
+| Family | Peers |
+| --- | --- |
+| Carousel | `embla-carousel-react` |
+| Charts / chart compositions | `recharts` |
+| Date pickers / calendars | `react-day-picker` |
+| Forms / schema forms | `react-hook-form` |
+| Feature tables / data views | `@tanstack/react-table` |
+| Kanban / draggable workflows | `@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities` |
+| Rich text editor | `@tiptap/react`, `@tiptap/pm`, `@tiptap/starter-kit` |
+| QR code | `qrcode`, `culori`, `@types/qrcode`, `@types/culori` |
+| Theme tweaker | `culori`, `@types/culori` |
+| Toasts | `sonner` |
+| Map | `leaflet`, `leaflet-draw`, `leaflet.fullscreen`, `leaflet.markercluster`, `react-leaflet`, `react-leaflet-markercluster`, `@types/leaflet`, `@types/leaflet-draw`, `@types/leaflet.markercluster` |
+
+Import `themelia-react-ui/features/map/style.css` alongside the library stylesheet when using maps. Vendor map CSS and images stay in this optional entry rather than enlarging basic component CSS. Version ranges and optional contracts are declared in `package.json`.
+
+## A small, stable token contract
+
+The [consistency guide](src/preview/catalogue/pages/docs/design-system-consistency.mdx),
+[consumer composition reference](docs/consumer-skill/references/composition.md) and
+[theme reference](docs/consumer-skill/references/theming.md) describe shared spacing ownership.
+The [structural composition contract](docs/consumer-skill/references/design-contract.md)
+defines application freedom and library-owned anatomy; the
+[maintenance guide](docs/design-contract.md) maps each responsibility to its owner
+and verification gate. Shipped consumer examples receive the same design lint as
+library compositions. Those repository checks do not run automatically in apps.
+Popover display/menu anatomy and default/compact insets are separate from collection
+row density and control size. Flush delegates padding to owned regions. Command
+search composes the public Input; features inherit these base recipes rather than
+rebuilding menu chrome or passing local padding overrides.
+
+Shadcn owns semantic colors and radius. The library extends that contract with shared status/inverse foreground pairs, typography and **23 structural root settings**, declared in `src/css/tokens/contract.json`. Utility aliases and size ratios derive from these roots; they are not additional customization knobs.
+
+The common geometry controls are:
+
+```css
+:root {
+  --space-scale: 1;
+  --density-scale: 1;
+  --gap-normal: 0.5rem;
+  --gap-dense: 0.25rem;
+  --height-action: 2.25rem;
+  --height-control: 2.25rem;
+  --control-x: 0.75rem;
+  --row-x: 0.75rem;
+  --row-y: 0.5rem;
+  --surface-x: 1rem;
+  --surface-y: 1rem;
+}
+```
+
+The remaining roots cover icons/avatars, shell dimensions, content widths and adaptive-grid minimums. Override shared typography through `--font-*` and `--text-*`. Use `.dark`/`.light` and `data-density="compact"` or `"comfortable"` at the document root. For ordinary scoped styling, use `ThemeScope` from `themelia-react-ui/ui-provider`; its shared portal host keeps menus and overlays inside the same CSS theme boundary. Use the richer `ThemeScope` from `themelia-react-ui/features/theme-tweaker` when applying that feature's structured theme and mode API. An ordinary nested div does not provide the portal host.
+
+Each default has one owner. There is no legacy token pipeline, JavaScript style engine, underscore prefix, or button-specific palette. Shared action/control, row, surface and text recipes prevent components from acquiring unrelated spacing or color systems.
+
+The additive copy-gap contract replaces scattered title/description gaps with
+`--gap-normal` (8px) and `--gap-dense` (4px), scaled once by `--space-scale`.
+Headed surfaces accept `textGap`, and Stack/Grid accept the same semantic gap
+values. Existing spacing tiers and public roots remain available.
+
+## Deliberate migration changes
+
+Tree defaults to single-line compact navigation rows and shares Sidebar
+insets, action heights and density recipes. Choose `density="default"` or
+`"comfortable"` for more separation, and `rowLayout="rich"` explicitly for
+supporting copy and wrapping. String descriptions in ordinary rows remain
+available as native hover titles and accessible descriptions.
+AiFileTree now composes Tree, with controlled directory expansion separate from
+file selection. Its root hook remains `ai-file-tree--component`; row/group anatomy
+uses Tree's `tree--item` / `tree--group` hooks. It is card-free: add Card at the
+composition boundary for a frame. Status Badges and semantic icons replace the
+previous independent row tint. Existing explicit `indent` values are supported.
+
+- The package is ESM-only. Replace source package imports with the corresponding `themelia-react-ui` subpath.
+- CSS modules, Radix Slot, cmdk and unused Vaul/OTP internals are replaced or removed. Command uses Base UI; numeric custom filter scores control ranking. Its default fuzzy matching scores can differ from cmdk; supply `filter` when exact application-specific ranking matters.
+- Children override `Text.content`, including zero. Inverse text uses the inverse foreground pair across themes; primary text uses the readable brand accent.
+- Primary button labels use the shared `text-sm` role across control sizes. Secondary buttons use the shadcn secondary surface/foreground pair.
+- Filter presets and saved views retain the `FilterTabs`/`SavedViewTabs` APIs but expose pressed buttons rather than tabs without panels. Arrow/Home/End navigation selects presets; use `aria-pressed` instead of `aria-selected` when querying this control.
+- Framed surfaces use their shared semantic border and outer-ring recipe; the `framed` variant and provider defaults remain available. Card header actions stay on the trailing side in wide containers and move below the full-width identity in narrow containers. Translated titles and suffix badges wrap within the leading region.
+- PopoverMenu matches plain labels/descriptions by default, preserves explicit `searchValue` overrides, and accepts `contentLabel`/`contentLabelledBy` for its popup name. Custom rows receive actual highlight state and own their structured markup.
+- AI copy feedback waits for a successful write. `onCopyError` and optional `strings.copyError` expose denied/unavailable writes; `onCopy` fires after success.
+- Card, badge, overlay and form geometry follows canonical shared recipes instead of obsolete source CSS module defaults. Typography has no incidental margins; structures own layout spacing.
+- Input groups follow scoped control sizing and keep inputs/actions inside their borders. Grouped textareas use the same density-scaled 80px minimum as standalone textareas. Native controls own their font, foreground and box model without requiring a global CSS reset.
+- Rich `InlineStat` labels own their typography; scalar labels retain the fixed `DisplayLabel` role. Summary totals use canonical emphasized `Text` instead of modifying that metadata role.
+- `RichText`, rich-text editors, mention bodies and structured comments share the shipped `themelia-content` recipe instead of inactive `prose-*` plugin classes. Body size/leading retain existing props; content flow derives from `--space-scale`. UI typography remains margin-free. Use `tag="div"` for block HTML, and `not-typeset` or `data-not-typeset` on embedded UI inside a React-authored content scope. HTML sanitization and its allowed tags remain unchanged.
+
+Consumer callbacks own feature data and backend effects. The examples demonstrate those integrations without introducing application routing or storage into the library.
+
+### Blocks import migration
+
+The presentation layer is now named `blocks`. Replace `themelia-react-ui/composed/<family>` with `themelia-react-ui/blocks/<family>` for admin, AI, analytics, commerce, data-display, onboarding, and timelines. Component names and props are unchanged. The source folder and catalogue routes follow the same rename.
+
+The default development URL opens the full component catalogue. The focused foundation playground remains at `/?page=foundations`, and the products workspace remains at `/?page=products`.
+
+### Component composition consistency
+
+`Button` separates `tone` from `buttonStyle` (`solid`, `outline`, `ghost`); the catalogue shows their matrix, sizes and loading/disabled states. Icon-only controls may omit children when an accessible label or tooltip is supplied. Badges use compact typography and insets rather than inheriting action geometry.
+
+Use `titleSuffix` for card status, count and version badges. `headerStart` is full-width pre-title context, and `headerAction`/`actions` own controls. Card owns token-spaced title/suffix wrapping for all surface modes. Put card-level actions in `footerSlot` with `footerDivider`; reserve body actions for a specific content step. Card owns aligned card insets, frames and expand/collapse behavior; Use `Card surface="flat" padding="none"` for card-free content hierarchy. ChartCard exposes `titleSuffix` too. Use `headerPlacement="frame"` for a header above an inset body. SmartCard and ContentBlock remain deprecated migration adapters; new code uses Card.
+
+Application drawers use `ActionDrawer` and `useOverlayVisibility` from `themelia-react-ui/features/overlays`. Sheet is the structural foundation and remains available for lower-layer infrastructure and compatibility.
+
+Consumer integration guidance is available in [the package consumer skill](docs/consumer-skill/SKILL.md). The token contract budgets 23 structural roots and 77 package-owned roots; derived utilities are implementation recipes, not additional customization settings.
+
+
+Popover content uses `type="display"` for substantive content and `type="menu"` for collections. Mixed searchable menus use flush shells and compact region insets. `rounded-radius` is the package-wide default for cards, controls and popup shells. `rounded-inner` is opt-in for nested bodies or collection items, using the existing smaller tier. No separate surface radius or new public theme variable is introduced.
+
+
+## Agent skill and consumer references
+
+The npm tarball ships the complete [consumer skill](docs/consumer-skill/SKILL.md), [discovery](docs/consumer-skill/references/discovery.md), [composition](docs/consumer-skill/references/composition.md), [integration](docs/consumer-skill/references/integration.md), [theme extension](docs/consumer-skill/references/theming.md) and [workflow](docs/consumer-skill/references/workflows.md) references. Its generated [public index](docs/consumer-skill/references/public-api.json) records exact imports, symbols, declarations and peer requirements; [the recipe manifest](docs/consumer-skill/examples/manifest.json) identifies all twelve runnable examples and their basic/optional phases. It contains no preview source or maintainer audit screenshots.
+
+After installing the package, find a family using its real portable script:
+
+```sh
+node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs form validation --limit 5
+```
+
+Resolve the installed package and compare copied guidance using the [installed setup reference](docs/consumer-skill/references/installation.md). Copy its `docs/consumer-skill/` folder into your agent's skills directory as `themelia-react-ui-consumer/` to install the skill manually. For Codex, the default destination is `~/.codex/skills/themelia-react-ui-consumer/`. Preserve every subfolder; invoke `$themelia-react-ui-consumer` or let the agent select it. Refresh the copied skill when upgrading. Package installation, skill copying and registry publication are separate actions; none happens globally or automatically.
+
+Repository work uses the scoped [maintainer](docs/maintainer-skills/themelia-cn-maintainer/SKILL.md), [tokens](docs/maintainer-skills/themelia-cn-tokens/SKILL.md) and [quality](docs/maintainer-skills/themelia-cn-quality/SKILL.md) skills routed by [AGENTS.md](AGENTS.md). These repo-owned guides are excluded from the consumer package and do not replace separately installed skills.
+
+There is one packaged consumer skill with eight focused prose references, two
+generated indexes, twelve typed recipes and five helper scripts. Repository
+maintainer skills remain separate. The consumer entrypoint starts from task,
+context, information priority and command ownership and routes typography,
+layouts, theming, state/integration and verification detail to the relevant owner.
+Its [scoped directory recipe](docs/consumer-skill/examples/scoped-directory.tsx)
+shows one route heading, fixed parent context, integrated queries and record
+navigation. [Review and checks](docs/consumer-skill/references/review.md) describes
+the opt-in `check-composition.mjs` source checker and its TypeScript dev requirement.
+It shares popup anatomy policy with repository enforcement; ambiguous composition
+is a warning and dynamic/external styling needs review. `check:agent` verifies
+deterministic guidance infrastructure, not aesthetic judgment or new-task agent
+performance. Keep app-specific policy separate from the versioned package skill.
+
+Maintainers run `npm run docs:sync-skill` after changes to exports, types, selection guidance, peers or tokens. `npm run check:skill` requires a fresh library build and rejects stale source-backed references, built declaration exports and broken reference links. `prepack` checks source-backed references without rebuilding; `prepublishOnly` builds fresh assets and verifies built guidance. `check:package` verifies the complete shipped skill, then strictly compiles the eight basic recipes without optional peers and all twelve with their needed peers, alongside its installed runtime checks.
+
+Build portable consumer documentation with `npm run build` followed by `npm run build:docs`. The generated [static entry](dist-docs/index.html) links to `dist-docs/1.0.1/` for the current version. Each version preserves the complete skill and all declaration files, supports search with the same finder, and uses relative links under any hosting subdirectory. Serve the entire artifact over HTTP; it needs no external CDN. Run `npm run check:static-docs` to check generated asset paths. The future hosting destination remains pending.
+
+`npm run check:agent` runs focused agent-consumption fixtures and built skill alignment. `npm run check:release` performs the real serial local build/package/browser/agent/static-documentation gate; it does not publish or deploy. See the [release guide](docs/releasing.md), [draft changelog](CHANGELOG.md) and [future GitHub Actions template](.github/workflows/ci.yml) for browser installation and explicit cold-cache handling. These commands verify locally; publication and deployment remain separate actions.
+
+This package uses the [MIT license](LICENSE). Adapted shadcn/ui scaffolding retains its MIT attribution in [third-party notices](THIRD_PARTY_NOTICES.md). Package repository and issue metadata follow the configured Git remote. Repository-only links above describe checkout tooling; the complete consumer skill is shipped in the npm payload.
+
+Email composition uses `themelia-react-ui/features/email-composer` with the existing Tiptap optional peers. It preserves structured JSON and atomic variable tokens, resolves live bindings for both preview and prepared delivery, and composes our Card/overlay, form, menu and editor-toolbar components. See the Email composer catalogue page for controlled drafts, templates, placements and delivery ownership.
+
+Server-side rendering, validation and delivery helpers have a separate `themelia-react-ui/features/email-composer/engine` import with no React/editor runtime or client directive. Existing helper exports on the UI family remain compatible. Applications own draft persistence, data fetching, authentication and transport cancellation.
+
+Empty recipient groups show an input immediately, with an inline plus for additional addresses and Cc/Bcc input disclosure. Templates, recipient groups and variable definitions accept application-owned loading, error and retry state. Template loading leaves ordinary composing available; unavailable required recipient/variable data blocks preparation and delivery. The catalogue includes lazy template loading and failure/retry examples.
+
+
+### Task summaries, usage and inline editing
+
+- `themelia-react-ui/blocks/planning`: TaskCard composes Card, an accessible
+  disclosure and controlled checklist, with animated segmented progress, due
+  metadata and assignees. Click the header or use the keyboard caret; completion
+  persistence and Open navigation stay with the app.
+- `themelia-react-ui/blocks/analytics/usage-card`: UsageCard supplies quota,
+  category/daily/resource analytics and controlled period/request states without
+  unrelated chart peers. Missing, unlimited and over-quota data remain distinct.
+- `themelia-react-ui/base/inline-edit`: InlineEdit supplies native Input/Textarea
+  styling and options, validation, async save/cancel, focus restoration and
+  committed form values, with compact actions and reduced-motion transitions.
+
+These additions reuse the existing token roots and public composition owners.
+See the [workflow contracts](docs/consumer-skill/references/workflows.md#task-summaries-usage-and-inline-editing)
+and [typed workspace recipe](docs/consumer-skill/examples/planning-usage-edit.tsx).
+Card also accepts a semantic `gap` between its regions while preserving its
+default insets and independent title/description `textGap`.
+
+### Hierarchies, capture and reusable content
+
+- `themelia-react-ui/base/tree`: data-driven accessible hierarchy selection and expansion.
+- `themelia-react-ui/base/cascader`: drill, columns and tree pickers, including async children.
+- `themelia-react-ui/base/signature-pad`: structured signature capture, typed alternative and PNG/SVG/JSON export.
+- `themelia-react-ui/features/questionnaire`: guided questions, validation and cancellable async submission.
+- `themelia-react-ui/base/code-block`: copy feedback, line numbers/diff/focus/wrapping and caller-prepared highlighting.
+- `themelia-react-ui/base/attachment`: shared file rows/chips/gallery presentation, status/progress and app callbacks.
+- `themelia-react-ui/blocks/collaboration`: generic Message composition; AI and upload owners reuse shared content anatomy.
+
+These families add no runtime dependencies or public token roots. AppSidebar's
+`searchable` option and controlled branch expansion extend the existing sidebar;
+routing and persistence remain consumer-owned. See the catalogue and packaged
+consumer recipes for the exact contracts.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,65 @@
+# Third-party notices
+
+Internal UI scaffolding includes substantial adaptations of shadcn/ui source.
+Upstream license: https://github.com/shadcn-ui/ui/blob/main/LICENSE.md
+
+MIT License
+
+Copyright (c) 2023 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+External dependencies retain their own licenses and notices in their packages.
+
+## Email composer reference
+
+The email composer public types and HTTP adapter adapt the supplied MIT-licensed
+`email-composer` reference. Its notice is retained below. The UI composition,
+controller and rendering engine are implemented for Themelia.
+
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+## ReUI functional inspiration
+
+The Tree, Cascader, SignaturePad, Questionnaire, CodeBlock, Message, Attachment
+and sidebar examples were reviewed against the free ReUI registry at
+https://github.com/keenthemes/reui (MIT, Copyright (c) 2025 Keenthemes Inc.).
+Themelia implementations use this package's existing owners and contracts;
+no ReUI runtime, paid blocks, palettes or styling layer are included.