@pie-players/pie-theme 0.3.64 → 0.3.66

package/README.md

@@ -2,14 +2,21 @@
 
 Shared PIE theming primitives and the `pie-theme` custom element.
 
-`pie-theme` resolves canonical PIE variables (`--pie-*`) with this precedence:
+`pie-theme` resolves PIE theme tokens (`--pie-*`) with this precedence:
 
 1. Base PIE theme (`theme=light|dark|auto`)
 2. Provider adapter output (for example DaisyUI tokens)
-3. Selected color scheme (`scheme`)
+3. Resolved registered color scheme (`scheme`)
 4. Explicit `variables` overrides
 
-## Usage
+Base themes and built-in color schemes are authored once in TypeScript. The
+runtime resolver and the checked-in CSS adapters use those same definitions, so
+the managed custom-element path and the stylesheet-only path cannot carry
+different palettes.
+
+## Entrypoints and styles
+
+Importing the package root registers `<pie-theme>`:
 
 ```ts
 import "@pie-players/pie-theme";
@@ -18,19 +25,59 @@ import "@pie-players/pie-theme/color-schemes.css";
 import "@pie-players/pie-theme/font-sizes.css";
 ```
 
+The lower-level element entrypoint is intentionally side-effect-free:
+
+```ts
+import { definePieTheme } from "@pie-players/pie-theme/theme-element";
+
+definePieTheme();
+```
+
+Keep that distinction when integrating or bundling the package. Existing hosts
+depend on the root entrypoint registering the element and on `theme-element`
+waiting for an explicit call.
+
+The four stylesheet artifacts remain available at both their package export and
+literal `dist` paths:
+
+- `tokens.css`
+- `color-schemes.css`
+- `font-sizes.css`
+- `components.css`
+
+They are unlayered deliberately. In stylesheet-only delivery, a host may
+continue to override public tokens through normal source order, specificity, or
+`!important`.
+The element-name portion of the base-theme adapter uses `:where(...)`, keeping
+its specificity below a later `[data-color-scheme]` rule. In a stylesheet-only
+integration, that lets a host scheme override the generated base theme through
+the normal cascade without `!important`.
+
 ```html
 <pie-theme theme="auto" scope="document">
   <pie-section-player></pie-section-player>
 </pie-theme>
 ```
 
-## Custom element API
+## Custom element interface
 
 - `theme`: `light | dark | auto`
 - `scope`: `self | document`
-- `provider`: provider id or `auto` (default)
-- `scheme`: color scheme id (`default` by default)
-- `variables`: JSON object of CSS variable overrides
+- `provider`: provider id, `auto` (default), or `none`
+- `scheme`: requested color-scheme id (`default` by default)
+- `variables`: JSON object of CSS custom-property overrides
+
+`default` means no named color scheme; the base theme and provider still apply.
+For any other value, requested and resolved scheme are separate states. If the
+id is unavailable, `<pie-theme>` keeps it in both `scheme` and
+`data-color-scheme`, renders the safe base/provider result plus any explicit
+`variables`, and automatically uses it if a matching custom scheme is registered
+later. Retaining `data-color-scheme` preserves a selector hook, but does not give
+an unregistered scheme managed precedence. A mounted `<pie-theme>` writes its
+resolved tokens inline, so a competing host selector must use `!important`; use
+a Registered Custom Scheme when the scheme needs normal managed precedence. A
+stylesheet-only integration without a mounted `<pie-theme>` continues to use
+the normal cascade.
 
 ## Provider Adapter API
 
@@ -51,14 +98,50 @@ const myProvider: ThemeProviderAdapter = {
 registerPieThemeProvider(myProvider);
 ```
 
-## Custom Color Schemes
+## Runtime theme interface
+
+The package exposes four operations:
+
+```ts
+resolvePieTheme(input): ThemeResolution
+listPieColorSchemes(): ColorSchemeSnapshot
+observePieColorSchemes(listener): Unsubscribe
+registerPieColorSchemes(entries): RegistrationReceipt
+```
+
+`resolvePieTheme()` accepts `baseTheme` (`light` or `dark`),
+`requestedScheme`, `providerVariables`, and final `variables`. Its result
+contains `baseTheme`, `requestedScheme`, `resolvedScheme`, `status` (`default`,
+`built-in`, `custom`, or `unavailable`), final `variables`, and `diagnostics`.
+
+`resolvePieTheme()` returns the requested id, resolution status, resolved
+descriptor when available, final immutable token values, and diagnostics.
+`listPieColorSchemes()` returns an immutable snapshot whose `schemes` list keeps
+the built-in order and starts with the `default` descriptor. Catalog previews
+resolve each scheme over PIE's canonical light base, then project
+`--pie-background`, `--pie-text`, and `--pie-primary`; they are not separately
+authored swatches or a promise to mirror a host-specific provider. Projection
+preserves a deterministic opaque subset: named colors, three- or six-digit hex,
+non-alpha `rgb()`, `hsl()`, `hwb()`, `lab()`, `lch()`, `oklab()`, `oklch()`,
+and standard CSS Color 4 `color()` spaces. Transparent, explicit-alpha,
+relative, nested, context-dependent, malformed, or unsupported forms fall back
+to the canonical opaque preview swatch, so a preview never inherits accidental
+colors from the picker itself. The authored theme variable is not changed by
+that fallback.
+
+`observePieColorSchemes()` calls the listener immediately with the current
+snapshot, then once after each successful catalog-changing registration or
+unregistration. Listener failures are isolated, and reentrant mutations produce
+later coherent snapshots rather than interrupting the current notification.
+
+## Registered custom schemes
 
 Register consumer-defined schemes without modifying framework source:
 
 ```ts
 import { registerPieColorSchemes } from "@pie-players/pie-theme";
 
-registerPieColorSchemes([
+const registration = registerPieColorSchemes([
   {
     id: "district-high-contrast",
     name: "District High Contrast",
@@ -68,21 +151,84 @@ registerPieColorSchemes([
       "--pie-text": "#ffffff",
       "--pie-primary": "#00ffff",
     },
-    preview: {
-      bg: "#000000",
-      text: "#ffffff",
-      primary: "#00ffff",
-    },
   },
 ]);
+
+// Removes only this registration. Safe to call more than once.
+registration.unregister();
 ```
 
 Then activate with `scheme="district-high-contrast"` on `pie-theme`.
 
+Registered custom schemes are partial overlays. Each entry validates atomically
+against the token registry's scheme-participation metadata; an invalid entry is
+rejected without dropping valid sibling entries. Built-in ids, `default`,
+unknown tokens, and excluded/private/legacy tokens cannot be registered. The
+latest valid registration for a custom id wins, and an older receipt cannot
+remove that newer definition. Validation returns structured diagnostics and
+warns concisely by default; it does not throw for ordinary invalid input.
+Contrast diagnostics inspect affected semantic relationships in the fully
+resolved custom palette and remain non-blocking because that palette is
+host-owned.
+
+Use the final `variables` property for deliberate per-instance overrides. Use a
+CSS selector keyed by `data-color-scheme` only when a CSS-only scheme and its
+cascade requirements are intentional. Such a selector follows the normal
+cascade in a stylesheet-only integration; when it competes with a mounted
+`<pie-theme>`'s inline tokens, it needs `!important`.
+
+## Fixed hues
+
+Some components paint a hue the palette does not own: a data encoding, like the
+periodic table's category fills. `--pie-fixed-hue-collapse` is the share by
+which such a hue folds into the palette — the component mixes its own value
+towards `--pie-background-dark` and `--pie-text` by this share, so `0%` renders
+the authored hue exactly and `100%` removes it.
+
+Base Themes set `0%`, because a full palette leaves a hue encoding readable.
+Every colour scheme sets `100%`: a two-colour palette is a promise, and a hue
+that survives it is a colour the learner did not choose. A registered custom
+scheme collapses without declaring anything, and keeps its encodings by setting
+`--pie-fixed-hue-collapse: 0%` itself.
+
+Both ends of the mix are exact, so this costs nothing under a Base Theme. What
+it costs under a scheme is the encoding: a component collapsing hues has to
+carry category, state or series somewhere else — a label, a filter, or the
+accessible name.
+
 ## DaisyUI Integration
 
 - If DaisyUI tokens are present on the target scope, `pie-theme` uses the built-in `daisyui` provider adapter.
 - Override precedence is: base PIE -> provider output -> scheme -> `variables`.
+- `provider="none"` (`PIE_THEME_PROVIDER_NONE`) resolves no provider at all, leaving this package's shipped defaults. It is how a host reproduces the palette it had before adopting a provider, which is the first thing to check when colours differ between two environments.
+
+## Token registry
+
+`@pie-players/pie-theme/token-registry.json` lists every `--pie-*` token with its
+owner, scope, category, status, fallback policy, and scheme participation
+(`required`, `optional`, or `excluded`). `PieThemeTokenRegistryEntry` types it.
+
+It is published so a host can show a person what a token is for and who owns it. Read the registry rather than deriving grouping from token names or keeping a local copy: both drift as soon as a token is added here, and `check:theme-tokens` holds the registry against source on every commit.
+
+## Generated CSS
+
+`tokens.css` and `color-schemes.css` are checked-in output adapters. Generation
+is explicit so builds and releases never rewrite tracked source:
+
+```sh
+bun --cwd packages/theme run generate:css
+bun --cwd packages/theme run check:generated-css
+```
+
+The writer is `packages/theme/scripts/generate-theme-css.ts --write`; `--check`
+performs the non-mutating comparison. `bun run check:theme-tokens` also rejects
+stale generated CSS, and the theme package build runs the stale check before it
+copies the existing files to `dist`.
+
+The package-internal `renderPieThemeCss()` implementation lives in
+`src/theme-css.ts`; it is not a public export. Generated `color-schemes.css`
+contains one unlayered `[data-color-scheme="..."]` rule per built-in scheme and
+no base-theme or grouped exception rules.
 
 ## Light DOM and Shadow DOM
 
@@ -95,10 +241,11 @@ Then activate with `scheme="district-high-contrast"` on `pie-theme`.
 
 Use `@pie-players/pie-theme/components.css` for shared visual styles that are intentionally reused across multiple PIE custom elements.
 
-**Players install this stylesheet themselves; hosts do not import it.** Mounting
-`<pie-theme>` does not load it either — that element only writes `--pie-*` custom
-properties. `@pie-players/pie-item-player` bundles the stylesheet as text and
-installs it once per document at import time; see
+`@pie-players/pie-item-player` installs this stylesheet itself, so new hosts do
+not need a second copy. Existing hosts may still own the exported stylesheet;
+that published path remains supported. Mounting `<pie-theme>` does not load it —
+the element only writes `--pie-*` custom properties. The item player bundles the
+stylesheet as text and installs it once per document at import time; see
 [content styles](../item-player/README.md#content-styles) for the host-ownership
 opt-out.