themelia-ui 1.0.0

package/README.md

@@ -0,0 +1,543 @@
+# Themelia UI
+
+**Foundations for every theme.**
+
+Themelia UI is a production-ready React component system built for applications that need
+more than a collection of isolated controls. It combines accessible components, composable
+features and layouts, and a compact CSS-variable contract that lets one theme control the
+whole interface.
+
+The package uses CSS Modules over [Base UI](https://base-ui.com) internally. It has no
+Tailwind dependency, but it provides a first-class Tailwind CSS v4 bridge for applications
+that use Tailwind. The result is a library that works with any styling stack while still
+giving Tailwind consumers token-aware utilities and predictable `className` overrides.
+
+- **Theme globally:** change colors, radius, spacing, density, type, motion, and elevation
+  through shared custom properties.
+- **Compose product UI:** build from formatted primitives, generic controls, interaction
+  features, layouts, and domain-neutral patterns without copying library source.
+- **Override locally:** use Tailwind utilities, ordinary CSS, stable BEM hooks, and documented
+  `data-*` states.
+- **Import narrowly:** every family has an exact JavaScript and CSS subpath; optional peers
+  stay outside applications that do not use them.
+- **Ship confidently:** accessibility, interaction, visual, token, package, SSR, CSP, and
+  consumer-fixture checks are part of the release gate.
+
+## Contents
+
+- [Quick start](#quick-start)
+- [Choose how much CSS to load](#choose-how-much-css-to-load)
+- [Tailwind CSS v4](#tailwind-css-v4)
+- [Override without fighting the library](#override-without-fighting-the-library)
+- [Theming](#theming)
+- [Composition](#composition)
+- [Why CSS instead of Tailwind internally?](#why-css-instead-of-tailwind-internally)
+- [Choose and discover components](#choose-and-discover-components)
+- [Documentation](#documentation)
+
+## Quick start
+
+Install the package:
+
+```bash
+npm install themelia-ui
+```
+
+React 19 and `react-dom` are required peer dependencies. Import the complete stylesheet for
+the simplest setup, put `UIProvider` at the application boundary, and use exact component
+subpaths:
+
+```tsx compile
+import { Button } from "themelia-ui/base/buttons"
+import { UIProvider } from "themelia-ui/ui-provider"
+import "themelia-ui/style.css"
+
+export function App() {
+  return (
+    <UIProvider config={{ colorScheme: "system", density: "default" }}>
+      <Button tone="primary" buttonStyle="solid">
+        Save changes
+      </Button>
+    </UIProvider>
+  )
+}
+```
+
+The package owns presentation, accessible behavior, responsive geometry, and display
+defaults. Your application keeps routing, fetching, persistence, permissions, translations,
+and business state.
+
+## Choose how much CSS to load
+
+Themelia never injects component styles from JavaScript. Choose one loading strategy and keep
+it consistent:
+
+| Strategy | Import | Use when |
+| --- | --- | --- |
+| Complete catalogue | `themelia-ui/style.css` | The application uses much of the library and values one root import. |
+| Family styles | `themelia-ui/<family>.css` | The application uses a smaller set and wants CSS to follow exact JS imports. |
+| Tokens only | `themelia-ui/core.css` | Application CSS needs the token contract before any component family is loaded. |
+
+For narrow loading, keep each family stylesheet beside its JavaScript import:
+
+```tsx compile
+import { Button } from "themelia-ui/base/buttons"
+import "themelia-ui/base/buttons.css"
+import { Page } from "themelia-ui/layout/page"
+import "themelia-ui/layout/page.css"
+
+export function SavePage() {
+  return (
+    <Page header={{ title: "Workspace" }}>
+      <Button>Save</Button>
+    </Page>
+  )
+}
+```
+
+Every family stylesheet already imports `core.css`. Do not import both unless application
+CSS itself needs the tokens before the family stylesheet loads. The generated
+[import table](./docs/generated/imports.md) is the authority for every JavaScript path, CSS
+path, and optional peer.
+
+## Tailwind CSS v4
+
+Themelia is **Tailwind-friendly, not Tailwind-dependent**. Tailwind remains excellent for
+application layout and one-off composition. Themelia keeps its component implementation in
+precompiled CSS so the package works in Vite, Next.js, Remix, an existing Tailwind app, or a
+project with no utility framework at all.
+
+### Install the bridge
+
+In the CSS entry that loads Tailwind and the complete catalogue, use this order:
+
+```css
+@import "tailwindcss";
+@import "themelia-ui/style.css";
+@import "themelia-ui/tailwind.css";
+```
+
+If component styles are imported by family from TypeScript, use `core.css` in the CSS entry
+instead:
+
+```css
+@import "tailwindcss";
+@import "themelia-ui/core.css";
+@import "themelia-ui/tailwind.css";
+```
+
+Then import each family stylesheet beside the component as shown above.
+
+The bridge is a generated Tailwind v4 `@theme inline` declaration. It does two jobs:
+
+1. It exposes Themelia tokens as utilities: `bg-primary`, `text-muted-foreground`,
+   `rounded-surface`, `rounded-control`, `p-md`, and the rest resolve to the active Themelia
+   theme.
+2. It prevents Tailwind defaults from silently replacing shared shadcn-shaped names such as
+   the radius, type, shadow, font, leading, easing, and animation variables.
+
+### Tailwind overrides work without `!important`
+
+Themelia establishes an explicit cascade order:
+
+```css
+@layer tokens, theming, base, components, utilities;
+```
+
+Its CSS Module rules compile into `components`; Tailwind classes compile into `utilities`.
+A declaration in a later layer wins regardless of selector specificity, so a utility passed
+through `className` overrides the component naturally. You do not need `!important`, a
+specificity hack, or `tailwind-merge`. Ordinary unlayered application CSS sits above every
+named layer when an app-level stylesheet needs the final say.
+
+Because every bridged utility reads `var(...)` at the element, it follows dark mode, nested
+providers, density scopes, and live theme changes:
+
+```tsx compile
+import { Button } from "themelia-ui/base/buttons"
+import "themelia-ui/base/buttons.css"
+
+export function TailwindActions() {
+  return (
+    <div className="grid gap-lg sm:grid-cols-2">
+      <Button className="rounded-pill px-lg shadow-lg">Approve</Button>
+      <Button tone="neutral" className="justify-self-start">
+        Review later
+      </Button>
+    </div>
+  )
+}
+```
+
+`rounded-pill`, `px-lg`, and `shadow-lg` use Themelia's live radius, spacing, and elevation
+values. Responsive layout utilities such as `sm:grid-cols-2` remain ordinary Tailwind.
+
+## Override without fighting the library
+
+Use the narrowest override that matches the decision you are making.
+
+### 1. Change a product-wide decision with a variable
+
+Load application CSS after Themelia, then override the public contract:
+
+```css
+:root {
+  --primary: oklch(0.52 0.16 255);
+  --primary-foreground: oklch(0.985 0 0);
+  --radius: 0.75rem;
+  --space-scale: 0.95;
+  --density-scale: 0.95;
+}
+```
+
+Buttons, fields, menus, cards, overlays, layouts, and Tailwind bridge utilities all follow
+the same values. Prefer this over repeating equivalent utility classes across the app.
+
+### 2. Change one instance with `className`
+
+Public components pass `className` to their root element. Tailwind utilities live in the
+utilities layer, after Themelia's component layer, so they can override one instance without
+`!important`, selector escalation, `tailwind-merge`, or runtime class rewriting:
+
+```tsx compile
+import { Button } from "themelia-ui/base/buttons"
+import "themelia-ui/base/buttons.css"
+
+export function CheckoutButton() {
+  return (
+    <Button fullWidth className="rounded-pill shadow-xl sm:w-auto">
+      Continue to payment
+    </Button>
+  )
+}
+```
+
+Use local utilities for a real local exception. If the same override appears repeatedly,
+move the decision into a theme variable or an application-owned wrapper.
+
+### 3. Customize a region with stable CSS hooks
+
+Every public component exposes a `{component-name}--component` root class. Named regions use
+`--header`, `--body`, `--footer`, and similar BEM hooks. Documented `data-slot` and
+`data-state` attributes expose anatomy and state:
+
+```css
+.billing-actions .button--component {
+  min-inline-size: 10rem;
+}
+
+.billing-actions [data-state="open"] {
+  box-shadow: var(--shadow-lg);
+}
+```
+
+Application CSS is unlayered and therefore wins over Themelia's named cascade layers. These
+public hooks are safer than reaching into hashed CSS Module names or package internals.
+
+## Theming
+
+The theme is a contract, not a parallel stylesheet for every component. Most rebrands change
+the shadcn-shaped color, radius, shadow, chart, and sidebar seeds. Shared type, spacing,
+density, controls, focus, motion, media, and shell variables handle broader system choices.
+Component-owned variables remain implementation details unless a reference explicitly calls
+one an extension seam.
+
+The exhaustive public contract is documented in [`src/styles/TOKENS.md`](src/styles/TOKENS.md).
+[`FACTORS.md`](src/styles/FACTORS.md) explains the four global scale factors, and
+[`SCOPES.md`](src/styles/SCOPES.md) explains how derived variables stay live inside nested
+themes.
+
+### Theme from React
+
+Use `UIProvider` when theme choices and display defaults come from application state:
+
+```tsx fragment — App and Toolbar are supplied by the consuming application
+import { UIProvider } from "themelia-ui/ui-provider"
+
+<UIProvider
+  config={{
+    colorScheme: "dark",
+    density: "compact",
+    scale: 1,
+    theme: {
+      colors: {
+        primary: "oklch(0.7 0.14 165)",
+      },
+    },
+  }}
+>
+  <App />
+  <UIProvider config={{ density: "comfortable" }}>
+    <Toolbar />
+  </UIProvider>
+</UIProvider>
+```
+
+A nested provider creates a nested theme/config scope. Values it does not name inherit from
+the parent.
+
+For new integrations, use the more precise boundaries when useful:
+
+- `UIRoot` applies application-wide React defaults without rendering a layout element.
+- `UIScope` changes theme and configuration for one subtree.
+- `Scope` applies CSS variables only and creates the boundary derived tokens need.
+- `UIPortalHost` keeps menus, tooltips, selects, and other portals inside a nested scope.
+
+See [Provider and scoping](./docs/learn/provider-and-scoping.md) for portal behavior, multiple
+React roots, SSR, and strict CSP configuration.
+
+### Light and dark themes
+
+The default theme responds to all supported signals:
+
+```html
+<html class="dark">
+<html data-theme="dark">
+<!-- With colorScheme="system", prefers-color-scheme is honored automatically. -->
+```
+
+When authoring theme overrides, define both the light and dark values your brand changes.
+Setting `colorScheme` on `UIProvider`, `UIRoot`, or `UIScope` manages the corresponding scope
+for you.
+
+### CSS, generated palettes, and interactive themes
+
+- Write a small application override file for the common case.
+- Use `deriveThemePalette` from `themelia-ui/theming` to derive coherent CSS variables from
+  a brand seed.
+- Use `features/theme-tweaker` when users need to edit, preview, and serialize a complete
+  theme at runtime; persistence stays in consumer-owned state.
+- Use the published `tokens.json` DTCG artifact to share the token contract with design tools.
+
+The full guide covers all four paths in [Theming](./docs/learn/theming.md).
+
+## Composition
+
+Themelia is meant to produce application-specific components without absorbing application
+policy. Start with the highest-level family that already owns the interaction, then move down
+only when you need more control.
+
+| Layer | Owns | Typical consumer use |
+| --- | --- | --- |
+| `typography/` | Text roles | Consistent hierarchy, semantics, truncation, and color. |
+| `primitives/` | One formatted value | Money, dates, names, dimensions, contact values. |
+| `base/` | One generic UI concept | Buttons, fields, menus, cards, tables, feedback, structure. |
+| `layout/` | Page and application geometry | Route shells without owning routing or data. |
+| `features/` | An interaction lifecycle | Controlled state, callbacks, accessors, slots, parts, hooks. |
+| `patterns/` | A subject-shaped arrangement | Analytics, timelines, onboarding, and similar compositions. |
+| `admin/patterns/` | Terminal admin presentation | Admin-specific arrangements built only from general families. |
+
+The composition ladder is:
+
+1. Ordinary props.
+2. Controlled state and callbacks.
+3. Accessors that adapt application records.
+4. Named slots and render props.
+5. Exported parts.
+6. Headless hooks.
+7. Documented multi-family recipes.
+
+Not every family needs every rung. A passive badge needs props; a data view or editor needs
+several controlled seams.
+
+### Build a business-specific component
+
+This component understands invoices. The package does not. The application owns the record,
+permissions, mutation, route, analytics, and product copy; Themelia owns the page geometry,
+metadata structure, action semantics, focus behavior, and theme:
+
+```tsx fragment — Invoice and application policy belong to the consumer
+import { Button } from "themelia-ui/base/buttons"
+import "themelia-ui/base/buttons.css"
+import { MetadataList } from "themelia-ui/base/display"
+import "themelia-ui/base/display.css"
+import { Page } from "themelia-ui/layout/page"
+import "themelia-ui/layout/page.css"
+
+function InvoiceDetail({ invoice, onCollectPayment }) {
+  return (
+    <Page
+      header={{
+        title: `Invoice ${invoice.number}`,
+        description: invoice.customerName,
+        actions: (
+          <Button onClick={() => onCollectPayment(invoice.id)}>
+            Collect payment
+          </Button>
+        ),
+      }}
+    >
+      <MetadataList
+        columns={2}
+        items={[
+          { id: "status", label: "Status", value: invoice.status },
+          { id: "due", label: "Due", value: invoice.dueLabel },
+        ]}
+      />
+    </Page>
+  )
+}
+```
+
+Wrap a family when your product needs a stable local name or defaults. Compose several public
+families when they form a product concept. Use exported parts or a headless hook when the
+lifecycle is correct but the presentation is not. Contribute a new package abstraction only
+when the concept is domain-neutral, repeats across products, and keeps application policy at
+the boundary.
+
+Read the complete [composition guide](./docs/learn/composition.md) for dashboards, resource
+indexes, forms, settings areas, and the wrap/compose/contribute decision.
+
+## Why CSS instead of Tailwind internally?
+
+Tailwind is optimized for styling code an application owns. A distributed component library
+has a different job: it needs stable implementation styles, live runtime themes, scoped
+inheritance, and predictable overrides in applications that may use any build stack.
+
+| Library concern | Themelia's CSS-first answer |
+| --- | --- |
+| Work without consumer tooling | Precompiled family CSS; no Tailwind plugin, content scan, preset, or PostCSS setup is required. |
+| Change a whole product consistently | Shared custom properties let one decision reach every component. |
+| Theme a subtree at runtime | CSS inheritance and scope boundaries update descendants without rebuilding classes or remounting components. |
+| Avoid class conflicts | CSS Modules isolate implementation classes; public BEM and state hooks remain deliberate. |
+| Make consumer overrides predictable | Named cascade layers establish precedence instead of runtime class-string surgery. |
+| Keep variants typed | `cvm()` provides `cva`-shaped typed variants that resolve to CSS Module class maps. |
+| Load only what is used | Each exact component family publishes its own stylesheet and optional peer boundary. |
+
+This is not a rejection of Tailwind. It is a separation of responsibilities:
+
+- **Themelia CSS** owns reusable component presentation and the global design contract.
+- **Tailwind in your app** owns route layout, responsive composition, and genuine local
+  exceptions.
+- **The bridge** makes both systems read the same live tokens.
+
+The cascade replaces `tailwind-merge` inside the package. Component rules compile into the
+`components` layer, Tailwind utilities remain in the `utilities` layer, and ordinary
+unlayered application CSS wins over both. There is no runtime parsing or merging of class
+strings.
+
+## Imports and optional peers
+
+Every component family is published on an exact subpath. Shipping code should prefer those
+subpaths so optional features never leak into unrelated bundles:
+
+```ts compile
+import { Money } from "themelia-ui/primitives"
+import { Button } from "themelia-ui/base/buttons"
+import { DataTable } from "themelia-ui/features/table"
+import { Page } from "themelia-ui/layout/page"
+import { MetricGrid } from "themelia-ui/patterns/analytics"
+import { UIProvider } from "themelia-ui/ui-provider"
+
+void [Money, Button, DataTable, Page, MetricGrid, UIProvider]
+```
+
+The root `themelia-ui` export is optional-peer-free and convenient for prototypes. Exact
+subpaths are the production default. Heavier capabilities such as tables, charts, maps,
+drag-and-drop, rich text, and React Hook Form declare optional peers only on the families
+that use them.
+
+## Choose and discover components
+
+Search by the job you need, not by guessing a component name:
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs "key value facts"
+```
+
+The command searches public symbols, family identifiers, selection guidance, preview routes,
+and recipes. It prints exact JavaScript and CSS imports plus “choose when” and “avoid when”
+guidance. Use `--layer=base`, `--family=`, `--profile=`, `--peer=`, `--route=`, `--symbol=`,
+or `--json` for precise queries.
+
+The package also ships an offline agent skill with the same generated component catalogue:
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/install-skill.mjs --project=.
+```
+
+It installs into `.agents/skills/` and `.claude/skills/` without overwriting a skill the
+package did not create.
+
+## Architecture
+
+Layers compose downward and the package statically rejects reverse dependencies. Layout and
+features are siblings; a pattern may compose both. Routing, fetching, persistence,
+translation, and application-domain state never enter `src/components/**`.
+
+Components that own visible or accessible copy expose typed default strings and partial
+overrides. Public components expose stable root and region hooks. Modal surfaces use the
+native `<dialog>` top layer; anchored surfaces use Base UI's collision-aware positioning.
+
+## Verification
+
+<!-- GENERATED:verification by scripts/gen-status-docs.mjs — do not edit. -->
+
+`npm run verify` runs 51 steps: 29 static gates over the source, 20 suites testing the gates themselves, the type-checker and the unit runner. The browser suites run separately under `npm test`, over every preview route; the repository test inventory is generated from those suites.
+
+<!-- /GENERATED:verification -->
+
+```bash
+npm run verify          # architecture, tokens, exports, docs, types, lint, unit tests
+npm test                # Playwright interactions, accessibility, visuals, themes, geometry
+npm run verify:release  # commit-bound publishing verdict and consumer fixtures
+npm run dev             # local component and documentation preview
+```
+
+Every release verdict is tied to one exact commit and a clean working tree. The gates cover
+CSS composition and scoping, token budgets, Tailwind bridge behavior, package exports,
+optional-peer boundaries, accessibility, visual parity, SSR, CSP, and disposable consumer
+applications.
+
+## Status
+
+<!-- GENERATED:status by scripts/gen-status-docs.mjs — do not edit. -->
+
+`1.0.0`. 98 component families across 8 layers — admin 2, base 53, features 25, foundation 4, layout 9, patterns 3, primitives 1, typography 1.
+
+The package publishes 100 exact JavaScript entrypoints and 94 exact CSS entrypoints. There are no broad aggregate barrels: a consumer imports the family it uses.
+
+Profiles are a dependency ceiling rather than a product taxonomy — admin 2, general 96. 1 family is marked experimental.
+
+Oxlint: 0 warnings. Stylesheet and bundle measurements are recorded by the repository baseline report, including which values were measured.
+
+Whether a given tree may publish is not stated here. Run `npm run verify:release`; it
+writes a verdict bound to one commit and one clean tree.
+
+<!-- /GENERATED:status -->
+
+## Documentation
+
+[Documentation home](docs/README.md) routes content by audience: Learn, Components, Build,
+and maintainer diagnostics.
+
+- [Installation and CSS loading](docs/learn/installation.md)
+- [Theming and Tailwind v4](docs/learn/theming.md)
+- [Provider and scoping](docs/learn/provider-and-scoping.md)
+- [Composition model](docs/learn/composition.md)
+- [Framework wiring](docs/learn/framework-wiring.md)
+- [Forms](docs/learn/forms.md)
+- [Localization](docs/learn/i18n.md)
+- [Troubleshooting](docs/learn/troubleshooting.md)
+- [Public API index](docs/generated/public-api.md)
+- [Component catalogue](docs/generated/components/INDEX.md)
+- [Exact JavaScript, CSS, and peer imports](docs/generated/imports.md)
+- [Complete token contract](src/styles/TOKENS.md)
+
+## Development
+
+```bash
+npm run dev
+npm run build:lib
+npm run find <term>
+npm run docs:sync-skill
+npm run verify
+```
+
+Generated files identify their owner in a header. Regenerate barrels, exports, CSS types,
+themes, indexes, references, and status sections through their scripts rather than editing
+them by hand.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,79 @@
+# Security
+
+## Supported versions
+
+| version | supported |
+|---|---|
+| 1.x | ✅ |
+| 0.x | ❌ — pre-release, superseded by 1.0 |
+
+## Reporting
+
+Report a suspected vulnerability privately, through GitHub's **Report a vulnerability**
+button on the repository's Security tab. Please do not open a public issue first.
+
+Include what you did, what happened, and which version you were on. A reply should come
+within a week; a fix or a documented mitigation within thirty days for anything that reaches
+a consumer's users.
+
+## What this package does and does not do with untrusted input
+
+This is a presentation library. It renders what it is given, and it holds no data of its own
+— no network calls, no storage, no authentication. That makes the trust boundary the
+consumer's, and there is one place where that matters more than the rest.
+
+### HTML trust boundaries
+
+`RichTextEditor` produces **HTML** and does not sanitize the draft. The package's `RichText`
+renderer does sanitize stored HTML through an allow-list before it reaches the DOM:
+
+- **On the way in**, an editor's output is whatever the browser's editing engine produced
+  from what the user typed or pasted. A paste can carry markup and attributes the user never
+  saw.
+- **On the way out**, rendering stored HTML through application-owned
+  `dangerouslySetInnerHTML` is the classic stored-XSS shape. Render it with `RichText`, or
+  apply the application's own sanitizer before any other HTML sink.
+
+Sanitize at the application's trust boundary before storage when its allowed tags, embeds,
+or author policy are stricter than `RichText`'s display allow-list. `RichText` provides the
+non-bypassable rendering safeguard; it does not replace server-side validation or policy.
+
+`RichTextEditor` is marked **experimental** for a related reason: its editing engine is
+`document.execCommand`, which is deprecated. It works in every current browser and has no
+standard replacement, but it is not a foundation to freeze a stable API on. Expect its
+internals to change within 1.x; `RichTextEditorHandle` is the seam intended to survive that.
+
+### Everything else
+
+Text goes through the typography components, which render it as text. Values go through the
+primitives, which format them. Neither interprets markup. `Value` and its relatives escape
+by construction because React does.
+
+If you pass `dangerouslySetInnerHTML` to a component that accepts arbitrary children, that
+is your call and your sanitizer's job.
+
+## Rich text: where sanitisation happens
+
+The editor and the renderer sit on opposite sides of this line, on purpose.
+
+**`RichTextEditor` and every `RichTextEngine` hold what the writer typed, unsanitised.** An
+editor that quietly removed part of a draft mid-keystroke would be a worse failure than the
+one it was trying to prevent, and it would not make the content safe anyway — the value
+goes to a server and comes back through some other path.
+
+**`RichText` is where the allow-list runs.** It is the component for rendering stored
+content, it sanitises before anything reaches the DOM, and there is no way to skip that: the
+`sanitizer` prop replaces the allow-list, it does not disable it.
+
+So: store what the editor gives you, and render it through `RichText`. Do not render editor
+output with `dangerouslySetInnerHTML` of your own.
+
+`src/components/features/rich-text-editor/rich-text-security.test.tsx` asserts both halves —
+that an engine keeps a `<script>` tag it was given, and that `RichText` removes both the
+script and an `onerror` attribute while keeping the surrounding text.
+
+## Dependencies
+
+Runtime dependencies are kept few and the optional peers are genuinely optional — a family
+that does not need `recharts` never loads it, which `verify:package` proves across 1164
+containment checks on every release.