@pie-players/pie-theme 0.3.67 → 0.3.68

package/README.md

@@ -2,6 +2,11 @@
 
 Shared PIE theming primitives and the `pie-theme` custom element.
 
+This file is the reference. For how the pieces fit — why a host stylesheet
+cannot override a mounted element, what the provider choice actually decides, and
+how a host carries an accommodation into its own chrome — see
+[`docs/theming/how-theming-works.md`](../../docs/theming/how-theming-works.md).
+
 `pie-theme` resolves PIE theme tokens (`--pie-*`) with this precedence:
 
 1. Base PIE theme (`theme=light|dark|auto`)
@@ -177,6 +182,59 @@ 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`.
 
+## SchoolCity scheme parity
+
+SchoolCity offers 15 schemes. Four are built in here — Black on White, White on
+Black, Black on Rose, Yellow on Blue — and the other eleven are host palettes a
+programme registers itself, from these values:
+
+| SchoolCity token | Value |
+| --- | --- |
+| blue | `#0028a1` |
+| red | `#bf0d00` |
+| green | `#008272` |
+| yellow | `#ffe072` |
+| light gray | `#c0c3cf` |
+| dark gray | `#9297a6` |
+| rose | `#f8d1ce` |
+
+All 15 clear 4.5:1 for ordinary text; Green on White is the tightest at 4.73:1.
+Ordinary text is not the whole cost, though, because the light base chose every
+semantic colour against white. What an overlay has to carry scales with how far
+its background sits from white:
+
+| Background | Tokens | Why |
+| --- | --- | --- |
+| white | 2 | ink and page; every base colour already holds |
+| white, with a mid-tone ink | 4 | the ink misses the tinted recessed surfaces |
+| `#000000` | 10 | inverted page; borrow the dark base theme's inks |
+| mid-tone (blue, red, green, dark gray) | ~18 | neither light nor dark inks hold, so icons, boundaries and focus rings are re-chosen too |
+
+```ts
+registerPieColorSchemes([
+  {
+    id: "sc-blue-on-white",
+    name: "Blue on White",
+    variables: { "--pie-text": "#0028a1", "--pie-background": "#ffffff" },
+  },
+]);
+```
+
+`packages/theme/tests/schoolcity-scheme-registration.test.ts` carries a validated
+palette for one scheme of each cost class and is the place to copy from.
+
+Read the receipt. Contrast diagnostics are warnings, not errors, because the
+palette is host-owned — a two-token White on Blue registers successfully and
+returns fourteen warnings, and a host that filters on `severity === "error"`
+ships cyan links on a mid-blue page. `registerPieColorSchemes` checks only the
+relationships whose tokens the overlay touches, so covering a flagged token is
+what clears its relationship.
+
+These are host palettes rather than built-ins on purpose. A built-in is a full
+48-token palette, since a two-colour scheme is a promise the whole surface has to
+keep, and which schemes a programme wants is still open on
+[PIE-472](https://illuminate.atlassian.net/browse/PIE-472).
+
 ## Fixed hues
 
 Some components paint a hue the palette does not own: a data encoding, like the
@@ -201,6 +259,59 @@ accessible name.
 - 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.
+- The adapter is the whole integration. `DAISYUI_PIE_TOKEN_MAP` is its sole source, and it corrects a slot that would land illegible because it reads resolved colours — which a stylesheet cannot do. The separate `pie-theme-daisyui` package that shipped the same table as static CSS was removed: `<pie-theme scope="document">` writes `--pie-*` as inline styles, so a stylesheet declaring them lost to it and the import did nothing.
+- A host on some other token vocabulary aliases its own names to `--pie-*` in its own stylesheet, which is what a non-DaisyUI design system needs anyway. Do that under `[data-color-scheme]` to make an accommodation reach host chrome, since `<pie-theme>` never writes `--color-*` or any other host prefix.
+
+## Font size scaling
+
+`font-sizes.css` carries four presets on `--pie-font-scale` — `normal` (1),
+`large` (1.25), `xlarge` (1.5), `xxlarge` (1.75). They are Learnosity's steps,
+which K-12 accommodation profiles are already written against, so the numbers are
+a contract: changing one changes what `large` means for every learner assigned it.
+
+A host selects a preset with `data-font-size` on any ancestor of the player, or
+on a player element itself:
+
+```html
+<html data-font-size="large">
+<div data-font-size="xlarge"><pie-section-player></pie-section-player></div>
+```
+
+A host already driving `<pie-theme>` sets the token instead and needs nothing
+from the stylesheet:
+
+```html
+<pie-theme variables='{"--pie-font-scale":"1.25"}'>
+```
+
+The content path scales completely. The rules set `font-size` on the content
+hosts — `pie-item-shell`, `pie-passage-shell`, `pie-item-player` and the
+externally loaded `pie-player` wrapper — and `font-size` inheritance crosses
+shadow boundaries, so text that inherits its size follows. Every font size in
+`components.css`, which styles item content, is relative (`em`, `%`,
+`larger`/`smaller`) and follows too. The learner-facing text that declares its
+own size and therefore cannot inherit the scale — the item and passage card
+titles, the formative status line, the tabbed layout's labels, the item player's
+build warning — reads `--pie-font-scale` directly, because a card wraps the shell
+that gets scaled rather than sitting inside it.
+
+Tool and debug chrome does not scale, deliberately: an accommodation applies to
+what the learner reads, and a calculator keypad growing with the passage is a
+layout problem rather than an accommodation.
+
+A rule elsewhere that sizes text in `rem` or `px` still will not follow — `rem`
+resolves against the document root and `px` against nothing, and no rule inside a
+subtree can change what either means — so a host adding its own content chrome
+either sizes it relatively or reads the token as these rules do. Browser zoom is
+unaffected throughout, so WCAG 2.2 1.4.4 does not depend on this feature.
+
+The scale is applied as `calc(1rem * var(--pie-font-scale))` rather than an `em`
+factor because the content hosts nest — an `em` factor would compound, turning a
+requested 1.25 into 1.56 wherever an item shell sits inside a themed region.
+
+There is no student-facing control here. The picker is host chrome, which in the
+Renaissance context is Quiz Engine's surface; this package owns the token, the
+presets, and the rules that consume them.
 
 ## Token registry
 

package/dist/apply-color-scheme.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Find the nearest `<pie-theme>` that owns `from`'s scheme, walking out
+ * across shadow-root boundaries. `Element.closest()` alone stops at a
+ * shadow root: a caller mounted inside its own `shadow: "open"` root would
+ * never find a `<pie-theme>` ancestor that lives in the light DOM outside
+ * it, so this repeats the search from each shadow root's host until it
+ * either finds one or reaches the document.
+ *
+ * Falls back to a document-scoped `<pie-theme>` anywhere in the page, then
+ * any `<pie-theme>` at all, matching how a page with exactly one theme host
+ * is normally set up.
+ */
+export declare function resolvePieThemeHost(from?: Node | null): HTMLElement | null;
+export interface ApplyPieColorSchemeOptions {
+    /** Search from this node outward for the nearest `<pie-theme>` ancestor. */
+    from?: Node | null;
+    /** localStorage key to persist the requested scheme under. Pass `null` to skip persistence. */
+    persistenceKey?: string | null;
+}
+/**
+ * Apply a requested color scheme and persist it, the one canonical way —
+ * shared by every caller that offers scheme selection outside `<pie-theme>`
+ * itself (a picker tool, a demo host's own theme controls).
+ */
+export declare function applyPieColorScheme(schemeId: string, options?: ApplyPieColorSchemeOptions): void;

package/dist/apply-color-scheme.js

@@ -0,0 +1,65 @@
+const DEFAULT_COLOR_SCHEME_STORAGE_KEY = "pie-color-scheme";
+/**
+ * Find the nearest `<pie-theme>` that owns `from`'s scheme, walking out
+ * across shadow-root boundaries. `Element.closest()` alone stops at a
+ * shadow root: a caller mounted inside its own `shadow: "open"` root would
+ * never find a `<pie-theme>` ancestor that lives in the light DOM outside
+ * it, so this repeats the search from each shadow root's host until it
+ * either finds one or reaches the document.
+ *
+ * Falls back to a document-scoped `<pie-theme>` anywhere in the page, then
+ * any `<pie-theme>` at all, matching how a page with exactly one theme host
+ * is normally set up.
+ */
+export function resolvePieThemeHost(from) {
+    if (typeof document === "undefined")
+        return null;
+    let current = from instanceof Element ? from : null;
+    while (current) {
+        const found = current.closest("pie-theme");
+        if (found)
+            return found;
+        const root = current.getRootNode();
+        current = root instanceof ShadowRoot ? root.host : null;
+    }
+    return (document.querySelector('pie-theme[scope="document"]') ||
+        document.querySelector("pie-theme"));
+}
+/**
+ * Apply a requested color scheme and persist it, the one canonical way —
+ * shared by every caller that offers scheme selection outside `<pie-theme>`
+ * itself (a picker tool, a demo host's own theme controls).
+ */
+export function applyPieColorScheme(schemeId, options = {}) {
+    if (typeof document === "undefined")
+        return;
+    const nextScheme = (schemeId || "default").trim() || "default";
+    const themeHost = resolvePieThemeHost(options.from);
+    if (themeHost) {
+        if (themeHost.getAttribute("scheme") !== nextScheme) {
+            themeHost.setAttribute("scheme", nextScheme);
+        }
+    }
+    else {
+        // No <pie-theme> owns `data-color-scheme` on this document, so this is
+        // the only way the shared color-scheme CSS can still pick up the
+        // requested scheme. A scope="document" <pie-theme> that mounts later
+        // captures whatever is already on `documentElement` as its restore
+        // baseline rather than silently discarding this write.
+        const root = document.documentElement;
+        if (nextScheme === "default")
+            root.removeAttribute("data-color-scheme");
+        else
+            root.setAttribute("data-color-scheme", nextScheme);
+    }
+    if (options.persistenceKey === null)
+        return;
+    try {
+        if (typeof localStorage === "undefined")
+            return;
+        localStorage.setItem(options.persistenceKey ?? DEFAULT_COLOR_SCHEME_STORAGE_KEY, nextScheme);
+    }
+    catch {
+        // Storage may be unavailable (privacy mode, quota); the scheme still applies this session.
+    }
+}

package/dist/color-schemes.js

@@ -1,4 +1,4 @@
-import { createBuiltInColorSchemeDescriptor, createPieColorSchemePreview, diagnoseThemeContrast, getBaseThemeVariables, getBuiltInColorSchemeDefinition, getDefaultColorSchemeDescriptor, getSchemeParticipation, listBuiltInColorSchemeDefinitions, } from "./theme-definitions.js";
+import { createBuiltInColorSchemeDescriptor, createPieColorSchemePreview, diagnoseThemeContrast, getBaseThemeVariables, getBuiltInColorSchemeDefinition, getDefaultColorSchemeDescriptor, getSchemeParticipation, listBuiltInColorSchemeDefinitions, resolvePaletteColorScheme, } from "./theme-definitions.js";
 import { normalizePieThemeVariables, } from "./theme-types.js";
 const customSchemes = new Map();
 const observers = new Set();
@@ -455,12 +455,20 @@ export function resolvePieTheme(input = {}) {
     }
     for (const item of diagnostics)
         warnDiagnostic(item);
+    // Only a resolved scheme decides polarity. Without one -- including a requested
+    // scheme that turned out unavailable -- the host's theme still owns
+    // `color-scheme`, and deciding it from the base palette would take that
+    // ownership away from every host that never asked for an accommodation.
+    const colorScheme = status === "built-in" || status === "custom"
+        ? resolvePaletteColorScheme(variables)
+        : null;
     return Object.freeze({
         baseTheme,
         requestedScheme,
         resolvedScheme,
         status,
         variables: freezeVariables(variables),
+        colorScheme,
         diagnostics: freezeDiagnostics(diagnostics),
     });
 }

package/dist/daisyui-mapping.d.ts

@@ -1,16 +1,17 @@
 /**
  * The one table that says which DaisyUI slot each `--pie-*` token comes from,
- * and one renderer that turns it into variables.
+ * and one renderer that turns it into variables. Sole source: the `daisyui`
+ * provider adapter is the only thing that reads it, and a host reaches it by
+ * mounting `<pie-theme provider="daisyui">` or leaving `provider` on `auto`.
  *
- * It exists because the same 47-row table was written out four times — the
- * provider adapter here, two mappers in `@pie-players/pie-theme-daisyui`, and
- * that package's `bridge.css` — and copies drift. Two defects lived in the drift:
- * `--pie-missing` was corrected to `--color-warning` in one copy while three kept
- * it on `--color-error`, and the parity test that was supposed to catch this
- * compared only the token names, never the slot each one derived from.
- *
- * CSS cannot import a table, so `bridge.css` stays hand-written and is held to
- * this one by `tests/daisyui-mapping-parity.test.mjs` instead.
+ * It was consolidated here after the same table had been written out four
+ * times — this adapter, two mappers in a separate `pie-theme-daisyui` package, and
+ * that package's static `bridge.css` — and copies drift. Two defects lived in the
+ * drift: `--pie-missing` was corrected to `--color-warning` in one copy while three
+ * kept it on `--color-error`, and the parity test meant to catch that compared only
+ * the token names, never the slot each one derived from. The copies are gone; the
+ * package was removed once its CSS turned out to be outranked by the inline
+ * variables `<pie-theme>` writes, leaving it inert wherever it was imported.
  */
 import { type ColorMeasure } from "./contrast.js";
 /** The DaisyUI slots this mapping reads. Not all of DaisyUI's palette. */

package/dist/daisyui-mapping.js

@@ -1,16 +1,17 @@
 /**
  * The one table that says which DaisyUI slot each `--pie-*` token comes from,
- * and one renderer that turns it into variables.
+ * and one renderer that turns it into variables. Sole source: the `daisyui`
+ * provider adapter is the only thing that reads it, and a host reaches it by
+ * mounting `<pie-theme provider="daisyui">` or leaving `provider` on `auto`.
  *
- * It exists because the same 47-row table was written out four times — the
- * provider adapter here, two mappers in `@pie-players/pie-theme-daisyui`, and
- * that package's `bridge.css` — and copies drift. Two defects lived in the drift:
- * `--pie-missing` was corrected to `--color-warning` in one copy while three kept
- * it on `--color-error`, and the parity test that was supposed to catch this
- * compared only the token names, never the slot each one derived from.
- *
- * CSS cannot import a table, so `bridge.css` stays hand-written and is held to
- * this one by `tests/daisyui-mapping-parity.test.mjs` instead.
+ * It was consolidated here after the same table had been written out four
+ * times — this adapter, two mappers in a separate `pie-theme-daisyui` package, and
+ * that package's static `bridge.css` — and copies drift. Two defects lived in the
+ * drift: `--pie-missing` was corrected to `--color-warning` in one copy while three
+ * kept it on `--color-error`, and the parity test meant to catch that compared only
+ * the token names, never the slot each one derived from. The copies are gone; the
+ * package was removed once its CSS turned out to be outranked by the inline
+ * variables `<pie-theme>` writes, leaving it inert wherever it was imported.
  */
 import { LEGIBLE_NON_TEXT_MINIMUM, LEGIBLE_TEXT_MINIMUM, UNMEASURED_HUE_WEIGHT, UNMEASURED_NON_TEXT_HUE_WEIGHT, legibleColorAgainst, } from "./contrast.js";
 export const DAISY_SLOT_CSS_VARIABLES = {

package/dist/daisyui-theme-catalog.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The full set of built-in DaisyUI theme ids. `<pie-theme>`'s DaisyUI
+ * provider adapter maps any of these onto the `--pie-*` token contract, so
+ * every demo host offering a DaisyUI theme picker draws from this one list
+ * instead of each hand-typing its own copy.
+ */
+export declare const DAISYUI_THEME_CATALOG: readonly ["light", "dark", "cupcake", "bumblebee", "emerald", "corporate", "synthwave", "retro", "cyberpunk", "valentine", "halloween", "garden", "forest", "aqua", "lofi", "pastel", "fantasy", "wireframe", "black", "luxury", "dracula", "cmyk", "autumn", "business", "acid", "lemonade", "night", "coffee", "winter", "dim", "nord", "sunset", "caramellatte", "abyss", "silk"];
+export type DaisyUIThemeId = (typeof DAISYUI_THEME_CATALOG)[number];

package/dist/daisyui-theme-catalog.js

@@ -0,0 +1,43 @@
+/**
+ * The full set of built-in DaisyUI theme ids. `<pie-theme>`'s DaisyUI
+ * provider adapter maps any of these onto the `--pie-*` token contract, so
+ * every demo host offering a DaisyUI theme picker draws from this one list
+ * instead of each hand-typing its own copy.
+ */
+export const DAISYUI_THEME_CATALOG = [
+    "light",
+    "dark",
+    "cupcake",
+    "bumblebee",
+    "emerald",
+    "corporate",
+    "synthwave",
+    "retro",
+    "cyberpunk",
+    "valentine",
+    "halloween",
+    "garden",
+    "forest",
+    "aqua",
+    "lofi",
+    "pastel",
+    "fantasy",
+    "wireframe",
+    "black",
+    "luxury",
+    "dracula",
+    "cmyk",
+    "autumn",
+    "business",
+    "acid",
+    "lemonade",
+    "night",
+    "coffee",
+    "winter",
+    "dim",
+    "nord",
+    "sunset",
+    "caramellatte",
+    "abyss",
+    "silk",
+];

package/dist/font-sizes.css

@@ -1,141 +1,94 @@
-/* PIE Font Size System - Learnosity-compatible font scaling for K-12 assessments
+/* PIE font size scaling.
  *
- * Based on Learnosity's font size accommodation feature which provides 4 preset sizes:
- * - Normal (100% - default)
- * - Large (125% - 1.25x scale)
- * - Extra Large (150% - 1.5x scale)
- * - Extra Extra Large (175% - 1.75x scale)
+ * Four presets on `--pie-font-scale`, selected by `data-font-size` on any
+ * ancestor of the player — matching Learnosity's font-size accommodation
+ * (100/125/150/175%), which is the scale K-12 programs already specify against.
  *
- * All sizes meet WCAG 2.2 Level AA requirements for text sizing:
- * - Users can scale text up to 200% without assistive technology
- * - Text remains readable and functional at all scale levels
- * - No horizontal scrolling required in scaled states
+ *   <html data-font-size="large">          host owns the whole page
+ *   <div data-font-size="large">           host scopes it to a region
  *
- * Usage: Apply data-font-size attribute to document root or pie-player element
- * Example: <html data-font-size="large">
+ * A host that drives theming through `<pie-theme>` sets the token directly
+ * instead, and needs nothing from this file:
  *
- * Implementation Note: Uses CSS custom property (--pie-font-scale) to scale all
- * typography consistently. Base font sizes are defined in the PIE player components.
+ *   <pie-theme variables='{"--pie-font-scale":"1.25"}'>
+ *
+ * WHAT SCALES. Text that inherits its size scales, because the rules below set
+ * `font-size` on the content hosts and inheritance crosses shadow boundaries.
+ * Text whose own rule names `rem` or `px` does not: `rem` resolves against the
+ * document root and `px` against nothing, and no rule inside a subtree can
+ * change what either means. A host that needs those to follow as well has to
+ * scale the root font size itself, which is a page-wide decision this package
+ * does not make on its behalf. WCAG 2.2 1.4.4 is satisfied either way — browser
+ * zoom remains available and unaffected — so this is a comfort accommodation
+ * layered over that, not a substitute for it.
+ *
+ * `calc(1rem * var(--pie-font-scale))` is deliberately root-relative rather than
+ * `em`-relative: the hosts nest (an item shell inside a section player inside a
+ * themed region), and an `em` factor would compound at each level and multiply
+ * 1.25 into 1.95.
  */
 
-/* Default font size (100% - no scaling) */
+/* The unset default. Also declared by the base theme, so the token resolves
+ * whether a host loads this file, `tokens.css`, or drives `<pie-theme>`. */
 :root {
 	--pie-font-scale: 1;
 }
 
-/* Normal (100% - explicit setting) */
 [data-font-size="normal"] {
 	--pie-font-scale: 1;
 }
 
-/* Large (125%) - Learnosity "large" preset */
 [data-font-size="large"] {
 	--pie-font-scale: 1.25;
 }
 
-/* Extra Large (150%) - Learnosity "xlarge" preset */
 [data-font-size="xlarge"] {
 	--pie-font-scale: 1.5;
 }
 
-/* Extra Extra Large (175%) - Learnosity "xxlarge" preset */
 [data-font-size="xxlarge"] {
 	--pie-font-scale: 1.75;
 }
 
-/* Apply font scaling to assessment content
- * Target PIE player elements and assessment content
- * Exclude tool UIs (calculator, graph, etc.) which should remain at normal size
+/* Content hosts.
  *
- * Using !important to override PIE's inline styles and component-specific styles
+ * `pie-item-shell` and `pie-passage-shell` are this repo's section-player
+ * content hosts and `pie-item-player` its standalone one; each renders PIE
+ * elements directly into its own shadow tree. `pie-player` is the externally
+ * loaded item wrapper some hosts render items through instead, so both delivery
+ * paths are covered — targeting only the wrapper, as this file previously did,
+ * missed every item this repo renders itself.
+ *
+ * Scoped under `[data-font-size]` so the declaration only exists once a host has
+ * opted in, and so a host's own rules keep the upper hand at equal specificity.
  */
-
-/* Apply to pie-player root element */
+[data-font-size] pie-item-shell,
+[data-font-size] pie-passage-shell,
+[data-font-size] pie-item-player,
+[data-font-size] pie-player,
+pie-item-shell[data-font-size],
+pie-passage-shell[data-font-size],
+pie-item-player[data-font-size],
 pie-player[data-font-size] {
-	font-size: calc(1rem * var(--pie-font-scale)) !important;
-}
-
-/* Apply to all text elements within pie-player - using inherit to cascade from root */
-pie-player[data-font-size] *,
-pie-player[data-font-size] p,
-pie-player[data-font-size] span,
-pie-player[data-font-size] div,
-pie-player[data-font-size] li,
-pie-player[data-font-size] label,
-pie-player[data-font-size] input,
-pie-player[data-font-size] textarea,
-pie-player[data-font-size] select,
-pie-player[data-font-size] button,
-pie-player[data-font-size] h1,
-pie-player[data-font-size] h2,
-pie-player[data-font-size] h3,
-pie-player[data-font-size] h4,
-pie-player[data-font-size] h5,
-pie-player[data-font-size] h6,
-pie-player[data-font-size] td,
-pie-player[data-font-size] th,
-pie-player[data-font-size] option {
-	font-size: inherit !important;
-}
+	font-size: calc(1rem * var(--pie-font-scale, 1));
 
-/* Also apply to parent container if data-font-size is on document root */
-[data-font-size] pie-player {
-	font-size: calc(1rem * var(--pie-font-scale)) !important;
-}
-
-[data-font-size] pie-player *,
-[data-font-size] pie-player p,
-[data-font-size] pie-player span,
-[data-font-size] pie-player div,
-[data-font-size] pie-player li,
-[data-font-size] pie-player label,
-[data-font-size] pie-player input,
-[data-font-size] pie-player textarea,
-[data-font-size] pie-player select,
-[data-font-size] pie-player button,
-[data-font-size] pie-player h1,
-[data-font-size] pie-player h2,
-[data-font-size] pie-player h3,
-[data-font-size] pie-player h4,
-[data-font-size] pie-player h5,
-[data-font-size] pie-player h6,
-[data-font-size] pie-player td,
-[data-font-size] pie-player th,
-[data-font-size] pie-player option {
-	font-size: inherit !important;
-}
-
-/* Preserve normal size for tool UIs and controls */
-[data-font-size] .pie-tool-toolbar,
-[data-font-size] .pie-tool-toolbar *,
-[data-font-size] .pie-tool-calculator,
-[data-font-size] .pie-tool-calculator *,
-[data-font-size] .tool-settings-panel,
-[data-font-size] .tool-settings-panel *,
-[data-font-size] [class*="pie-tool-"],
-[data-font-size] [class*="pie-tool-"] *,
-[data-font-size] header,
-[data-font-size] header *,
-[data-font-size] footer,
-[data-font-size] footer *,
-[data-font-size] nav,
-[data-font-size] nav *,
-[data-font-size] button:not(.pie-button),
-[data-font-size] .btn,
-[data-font-size] .btn * {
-	font-size: 1rem !important;
+	/* Long words at 175% overflow a column that fits them at 100%. */
+	overflow-wrap: break-word;
 }
 
-/* Ensure proper line-height scaling for readability */
+/* Line height has to open up with the type or the block tightens as it grows.
+ * A ratio, so a host that sets its own line-height still wins. */
+[data-font-size="large"] pie-item-shell,
+[data-font-size="large"] pie-passage-shell,
+[data-font-size="large"] pie-item-player,
 [data-font-size="large"] pie-player,
+[data-font-size="xlarge"] pie-item-shell,
+[data-font-size="xlarge"] pie-passage-shell,
+[data-font-size="xlarge"] pie-item-player,
 [data-font-size="xlarge"] pie-player,
+[data-font-size="xxlarge"] pie-item-shell,
+[data-font-size="xxlarge"] pie-passage-shell,
+[data-font-size="xxlarge"] pie-item-player,
 [data-font-size="xxlarge"] pie-player {
 	line-height: 1.6;
 }
-
-/* Prevent layout issues with scaled text */
-[data-font-size] pie-player {
-	overflow-wrap: break-word;
-	word-wrap: break-word;
-	hyphens: auto;
-}

package/dist/index.d.ts

@@ -2,7 +2,9 @@ import { PieThemeElement, definePieTheme } from "./theme-element.js";
 export { PieThemeElement, definePieTheme };
 export { DAISYUI_THEME_PROVIDER_ADAPTER, getPieThemeProvider, PIE_THEME_PROVIDER_NONE, listPieThemeProviders, registerPieThemeProvider, resolveProviderVariables, unregisterPieThemeProvider, type ThemeProviderAdapter, } from "./providers.js";
 export { DAISY_SLOT_CSS_VARIABLES, DAISYUI_PIE_TOKEN_MAP, resolveDaisyPieVariables, type DaisyMappingEntry, type DaisySlot, } from "./daisyui-mapping.js";
+export { DAISYUI_THEME_CATALOG, type DaisyUIThemeId, } from "./daisyui-theme-catalog.js";
 export { createCanvasColorMeasure, type ColorMeasure, } from "./contrast.js";
 export { isThemeMode, isThemeScope, normalizePieThemeVariables, type ColorSchemeSnapshot, type PieColorSchemeDescriptor, type PieColorSchemePreview, type PieThemeDiagnostic, type PieThemeDiagnosticCode, type PieThemeObserver, type PieThemeResolutionStatus, type RegisteredPieColorScheme, type RegistrationReceipt, type ResolvePieThemeInput, type ThemeResolution, type ThemeMode, type ThemeScope, type ThemeTokenName, type ThemeVariables, type Unsubscribe, } from "./theme-types.js";
 export type { PieThemeSchemeParticipation, PieThemeTokenRegistry, PieThemeTokenRegistryEntry, PieThemeTokenScope, PieThemeTokenStatus, } from "./token-registry-types.js";
 export { listPieColorSchemes, observePieColorSchemes, registerPieColorSchemes, resolvePieTheme, } from "./color-schemes.js";
+export { applyPieColorScheme, resolvePieThemeHost, type ApplyPieColorSchemeOptions, } from "./apply-color-scheme.js";

package/dist/index.js

@@ -2,7 +2,9 @@ import { PieThemeElement, definePieTheme } from "./theme-element.js";
 export { PieThemeElement, definePieTheme };
 export { DAISYUI_THEME_PROVIDER_ADAPTER, getPieThemeProvider, PIE_THEME_PROVIDER_NONE, listPieThemeProviders, registerPieThemeProvider, resolveProviderVariables, unregisterPieThemeProvider, } from "./providers.js";
 export { DAISY_SLOT_CSS_VARIABLES, DAISYUI_PIE_TOKEN_MAP, resolveDaisyPieVariables, } from "./daisyui-mapping.js";
+export { DAISYUI_THEME_CATALOG, } from "./daisyui-theme-catalog.js";
 export { createCanvasColorMeasure, } from "./contrast.js";
 export { isThemeMode, isThemeScope, normalizePieThemeVariables, } from "./theme-types.js";
 export { listPieColorSchemes, observePieColorSchemes, registerPieColorSchemes, resolvePieTheme, } from "./color-schemes.js";
+export { applyPieColorScheme, resolvePieThemeHost, } from "./apply-color-scheme.js";
 definePieTheme();

package/dist/theme-definitions.d.ts

@@ -6,6 +6,23 @@ type BuiltInColorSchemeDefinition = Readonly<{
     description?: string;
     variables: Readonly<ThemeVariables>;
 }>;
+/**
+ * The CSS `color-scheme` keyword a palette implies, or `null` when the token
+ * values cannot decide it.
+ *
+ * A scheme replaces every colour, but nothing in CSS infers polarity from custom
+ * properties, so UA-styled controls -- `input`, `select`, scrollbars, native form
+ * widgets -- keep whatever polarity the host's theme declared. A dark
+ * accommodation on a light host therefore renders their text in the light-mode
+ * system colour: measured at roughly 1.1:1 against `yellow-on-blue`.
+ *
+ * Decided by whether black or white contrasts better against the resolved
+ * background, which is the same test that picks a legible foreground. `null` for
+ * a background `parseOpaqueColor` rejects -- a translucent value, a `var()`
+ * reference out to a host property, the transparent light base -- because
+ * polarity then depends on the host's backdrop and is the host's to declare.
+ */
+export declare function resolvePaletteColorScheme(variables: Readonly<ThemeVariables>): "light" | "dark" | null;
 export declare function diagnoseThemeContrast(variables: Readonly<ThemeVariables>, schemeId?: string, relevantTokens?: ReadonlySet<string>): readonly PieThemeDiagnostic[];
 export declare function getBaseThemeVariables(baseTheme: "light" | "dark"): Readonly<ThemeVariables>;
 export declare function listBuiltInColorSchemeDefinitions(): readonly BuiltInColorSchemeDefinition[];

package/dist/theme-definitions.js

@@ -807,6 +807,17 @@ const PIE_THEME_CONTRAST_RELATIONSHIPS = deepFreeze([
         minimum: 3,
         role: "incorrect feedback icon",
     },
+    {
+        // The error-surface pair. `--pie-incorrect-secondary` is a tint of the
+        // page, about 1.1:1 against it in most schemes, so a banner painted with
+        // it reads as a banner only by its `--pie-incorrect` edge -- and the ink
+        // on it is the page's own, not the error hue: `--pie-incorrect` against
+        // this tint falls to 4.14:1 under Black on White.
+        foreground: "--pie-text",
+        background: "--pie-incorrect-secondary",
+        minimum: 4.5,
+        role: "incorrect feedback surface text",
+    },
     {
         foreground: "--pie-missing-icon",
         background: "--pie-background",
@@ -958,6 +969,31 @@ function resolveColor(variables, token, seen = new Set()) {
         ? resolveColor(variables, reference[1], seen)
         : value;
 }
+/**
+ * The CSS `color-scheme` keyword a palette implies, or `null` when the token
+ * values cannot decide it.
+ *
+ * A scheme replaces every colour, but nothing in CSS infers polarity from custom
+ * properties, so UA-styled controls -- `input`, `select`, scrollbars, native form
+ * widgets -- keep whatever polarity the host's theme declared. A dark
+ * accommodation on a light host therefore renders their text in the light-mode
+ * system colour: measured at roughly 1.1:1 against `yellow-on-blue`.
+ *
+ * Decided by whether black or white contrasts better against the resolved
+ * background, which is the same test that picks a legible foreground. `null` for
+ * a background `parseOpaqueColor` rejects -- a translucent value, a `var()`
+ * reference out to a host property, the transparent light base -- because
+ * polarity then depends on the host's backdrop and is the host's to declare.
+ */
+export function resolvePaletteColorScheme(variables) {
+    const value = resolveColor(variables, "--pie-background");
+    const background = value ? parseOpaqueColor(value) : null;
+    if (!background)
+        return null;
+    const againstWhite = contrastRatio({ r: 255, g: 255, b: 255 }, background);
+    const againstBlack = contrastRatio({ r: 0, g: 0, b: 0 }, background);
+    return againstWhite > againstBlack ? "dark" : "light";
+}
 export function diagnoseThemeContrast(variables, schemeId, relevantTokens) {
     const diagnostics = [];
     for (const relationship of PIE_THEME_CONTRAST_RELATIONSHIPS) {

package/dist/theme-element.d.ts

@@ -28,6 +28,22 @@ export declare class PieThemeElement extends HTMLElementBase {
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     protected getTarget(): HTMLElement;
     protected applyTheme(): void;
+    /**
+     * Provider adapters resolve by reading custom properties off the target, and
+     * those are selected by the target's own `data-theme` -- daisyUI's `--color-*`
+     * are the case that matters. So the target has to be carrying the incoming
+     * theme before the read: resolving first resolves the palette of the theme
+     * being replaced and leaves every `--pie-*` value one selection behind, with
+     * nothing to re-resolve it until some other attribute changes.
+     *
+     * The attributes are restored rather than left in place. For
+     * `scope="document"` the ownership arbitration in `applyTheme` decides whether
+     * this element may stamp them at all, and `ensureDocumentThemeBaseline` has to
+     * see the host's pre-existing value to have something to restore on
+     * disconnect. Stamp and restore happen in one synchronous pass, so the
+     * transient state is never painted.
+     */
+    private resolveProviderVariablesForState;
     private resolveThemeState;
     private clearPreviousTarget;
     private clearPreviousKeys;

package/dist/theme-element.js

@@ -48,6 +48,31 @@ function parseVariableOverrides(value) {
     }
     return output;
 }
+/**
+ * `color-scheme` decides how UA-styled controls paint -- `input` and `select`
+ * text, scrollbars, native form widgets -- and no amount of custom properties
+ * reaches them. A scheme that replaces the palette without it leaves those
+ * controls on the host theme's polarity, which under a dark accommodation on a
+ * light host means dark-on-dark.
+ *
+ * `null` restores rather than removes. Clearing a scheme has to undo this
+ * element's keyword, and the thing to return to is whatever the host declared --
+ * removing outright would take a host's own `color-scheme` away the first time a
+ * document-scoped element resolved without a scheme, which is most of the time.
+ * A self-scoped target has no host declaration to preserve, so its caller passes
+ * no baseline and `null` does remove.
+ */
+function applyColorScheme(target, colorScheme, baseline) {
+    if (colorScheme) {
+        target.style.setProperty("color-scheme", colorScheme);
+    }
+    else if (baseline) {
+        target.style.setProperty("color-scheme", baseline.value, baseline.priority);
+    }
+    else {
+        target.style.removeProperty("color-scheme");
+    }
+}
 const documentThemeOwners = new Map();
 let documentThemeBaseline = null;
 let documentThemeAppliedKeys = new Set();
@@ -55,6 +80,12 @@ function ensureDocumentThemeBaseline(target, tokens) {
     documentThemeBaseline ??= {
         dataTheme: target.getAttribute("data-theme"),
         dataColorScheme: target.getAttribute("data-color-scheme"),
+        colorScheme: target.style.getPropertyValue("color-scheme")
+            ? {
+                value: target.style.getPropertyValue("color-scheme"),
+                priority: target.style.getPropertyPriority("color-scheme"),
+            }
+            : null,
         variables: new Map(),
     };
     for (const token of tokens) {
@@ -92,6 +123,7 @@ function applyDocumentThemeState(target, state) {
     else {
         target.removeAttribute("data-color-scheme");
     }
+    applyColorScheme(target, state.colorScheme, documentThemeBaseline?.colorScheme ?? null);
     for (const [token, value] of Object.entries(state.variables)) {
         target.style.setProperty(token, value);
     }
@@ -111,6 +143,12 @@ function restoreDocumentThemeBaseline(target) {
     else {
         target.setAttribute("data-color-scheme", baseline.dataColorScheme);
     }
+    if (baseline.colorScheme) {
+        target.style.setProperty("color-scheme", baseline.colorScheme.value, baseline.colorScheme.priority);
+    }
+    else {
+        target.style.removeProperty("color-scheme");
+    }
     restoreDocumentThemeVariables(target);
     documentThemeBaseline = null;
     documentThemeAppliedKeys.clear();
@@ -209,10 +247,8 @@ export class PieThemeElement extends HTMLElementBase {
         if (this.previousTarget && this.previousTarget !== target) {
             this.clearPreviousTarget();
         }
-        const providerVariables = resolveProviderVariables({
-            target,
-            provider: this.provider,
-        });
+        const dataColorScheme = this.scheme === "default" ? null : this.scheme;
+        const providerVariables = this.resolveProviderVariablesForState(target, dataTheme, dataColorScheme);
         const resolution = resolvePieTheme({
             baseTheme: effectiveTheme,
             providerVariables,
@@ -221,7 +257,8 @@ export class PieThemeElement extends HTMLElementBase {
         });
         const state = Object.freeze({
             dataTheme,
-            dataColorScheme: this.scheme === "default" ? null : this.scheme,
+            dataColorScheme,
+            colorScheme: resolution.colorScheme,
             variables: resolution.variables,
         });
         if (this.scope === "document") {
@@ -245,6 +282,7 @@ export class PieThemeElement extends HTMLElementBase {
             else {
                 target.removeAttribute("data-color-scheme");
             }
+            applyColorScheme(target, state.colorScheme, null);
             this.clearPreviousKeys(target);
             for (const [key, value] of Object.entries(resolution.variables)) {
                 target.style.setProperty(key, value);
@@ -253,6 +291,40 @@ export class PieThemeElement extends HTMLElementBase {
         this.previousTarget = target;
         this.previousKeys = new Set(Object.keys(resolution.variables));
     }
+    /**
+     * Provider adapters resolve by reading custom properties off the target, and
+     * those are selected by the target's own `data-theme` -- daisyUI's `--color-*`
+     * are the case that matters. So the target has to be carrying the incoming
+     * theme before the read: resolving first resolves the palette of the theme
+     * being replaced and leaves every `--pie-*` value one selection behind, with
+     * nothing to re-resolve it until some other attribute changes.
+     *
+     * The attributes are restored rather than left in place. For
+     * `scope="document"` the ownership arbitration in `applyTheme` decides whether
+     * this element may stamp them at all, and `ensureDocumentThemeBaseline` has to
+     * see the host's pre-existing value to have something to restore on
+     * disconnect. Stamp and restore happen in one synchronous pass, so the
+     * transient state is never painted.
+     */
+    resolveProviderVariablesForState(target, dataTheme, dataColorScheme) {
+        const setOrRemove = (name, value) => {
+            if (value === null)
+                target.removeAttribute(name);
+            else
+                target.setAttribute(name, value);
+        };
+        const previousTheme = target.getAttribute("data-theme");
+        const previousColorScheme = target.getAttribute("data-color-scheme");
+        setOrRemove("data-theme", dataTheme);
+        setOrRemove("data-color-scheme", dataColorScheme);
+        try {
+            return resolveProviderVariables({ target, provider: this.provider });
+        }
+        finally {
+            setOrRemove("data-theme", previousTheme);
+            setOrRemove("data-color-scheme", previousColorScheme);
+        }
+    }
     resolveThemeState() {
         const rawTheme = this.getAttribute("theme")?.trim();
         if (rawTheme === "auto") {
@@ -286,6 +358,9 @@ export class PieThemeElement extends HTMLElementBase {
             this.clearPreviousKeys(target);
             target.removeAttribute("data-theme");
             target.removeAttribute("data-color-scheme");
+            // Self-scoped targets are the element itself, so anything written here
+            // was written by this element -- no host baseline to preserve.
+            target.style.removeProperty("color-scheme");
         }
         this.previousTarget = null;
         this.previousKeys.clear();

package/dist/theme-types.d.ts

@@ -41,6 +41,11 @@ export type ThemeResolution = Readonly<{
     resolvedScheme: PieColorSchemeDescriptor | null;
     status: PieThemeResolutionStatus;
     variables: Readonly<ThemeVariables>;
+    /**
+     * The CSS `color-scheme` keyword this resolution implies, or `null` when the
+     * host keeps ownership of it -- which is every resolution without a scheme.
+     */
+    colorScheme: "light" | "dark" | null;
     diagnostics: readonly PieThemeDiagnostic[];
 }>;
 export type RegisteredPieColorScheme = Readonly<{

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pie-players/pie-theme",
-	"version": "0.3.67",
+	"version": "0.3.68",
 	"type": "module",
 	"description": "Shared PIE theme tokens, css variables, and theme custom element",
 	"license": "MIT",
@@ -46,7 +46,7 @@
 		"test": "bun test --dom tests"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.7",
+		"@biomejs/biome": "^2.5.8",
 		"@happy-dom/global-registrator": "^20.11.1",
 		"typescript": "^5.9.3"
 	},