@pie-players/pie-theme 0.3.65 → 0.3.67

package/dist/theme-element.d.ts

@@ -8,7 +8,11 @@ export declare class PieThemeElement extends HTMLElementBase {
     private mediaQuery;
     private readonly onMediaChange;
     private previousKeys;
+    private previousTarget;
     private variablesOverride;
+    private promoteDocumentOwnership;
+    private stopObservingSchemes;
+    private stopObservingProviders;
     get theme(): ThemeMode;
     set theme(value: ThemeMode);
     get scope(): ThemeScope;
@@ -25,6 +29,7 @@ export declare class PieThemeElement extends HTMLElementBase {
     protected getTarget(): HTMLElement;
     protected applyTheme(): void;
     private resolveThemeState;
+    private clearPreviousTarget;
     private clearPreviousKeys;
     private setupAutoThemeListener;
 }

package/dist/theme-element.js

@@ -1,6 +1,5 @@
-import { resolvePieColorSchemeVariables } from "./color-schemes.js";
-import { DARK_THEME_VARS, LIGHT_THEME_VARS } from "./theme-defaults.js";
-import { resolveProviderVariables } from "./providers.js";
+import { observePieColorSchemes, resolvePieTheme } from "./color-schemes.js";
+import { observePieThemeProviders, resolveProviderVariables, } from "./providers.js";
 import { isThemeMode, isThemeScope, } from "./theme-types.js";
 const HTMLElementBase = typeof HTMLElement === "undefined"
     ? class {
@@ -40,15 +39,82 @@ function parseVariableOverrides(value) {
         if (!key.startsWith("--")) {
             continue;
         }
-        if (typeof rawValue === "string") {
-            output[key] = rawValue;
+        if (typeof rawValue === "string" && rawValue.trim()) {
+            output[key] = rawValue.trim();
         }
-        else if (typeof rawValue === "number") {
+        else if (typeof rawValue === "number" && Number.isFinite(rawValue)) {
             output[key] = String(rawValue);
         }
     }
     return output;
 }
+const documentThemeOwners = new Map();
+let documentThemeBaseline = null;
+let documentThemeAppliedKeys = new Set();
+function ensureDocumentThemeBaseline(target, tokens) {
+    documentThemeBaseline ??= {
+        dataTheme: target.getAttribute("data-theme"),
+        dataColorScheme: target.getAttribute("data-color-scheme"),
+        variables: new Map(),
+    };
+    for (const token of tokens) {
+        if (documentThemeBaseline.variables.has(token))
+            continue;
+        const value = target.style.getPropertyValue(token);
+        documentThemeBaseline.variables.set(token, value
+            ? { value, priority: target.style.getPropertyPriority(token) }
+            : null);
+    }
+}
+function restoreDocumentThemeVariables(target) {
+    for (const token of documentThemeAppliedKeys) {
+        target.style.removeProperty(token);
+    }
+    const baseline = documentThemeBaseline;
+    if (!baseline)
+        return;
+    for (const [token, original] of baseline.variables) {
+        if (original) {
+            target.style.setProperty(token, original.value, original.priority);
+        }
+        else {
+            target.style.removeProperty(token);
+        }
+    }
+}
+function applyDocumentThemeState(target, state) {
+    ensureDocumentThemeBaseline(target, Object.keys(state.variables));
+    restoreDocumentThemeVariables(target);
+    target.setAttribute("data-theme", state.dataTheme);
+    if (state.dataColorScheme) {
+        target.setAttribute("data-color-scheme", state.dataColorScheme);
+    }
+    else {
+        target.removeAttribute("data-color-scheme");
+    }
+    for (const [token, value] of Object.entries(state.variables)) {
+        target.style.setProperty(token, value);
+    }
+    documentThemeAppliedKeys = new Set(Object.keys(state.variables));
+}
+function restoreDocumentThemeBaseline(target) {
+    const baseline = documentThemeBaseline;
+    if (!baseline)
+        return;
+    if (baseline.dataTheme === null)
+        target.removeAttribute("data-theme");
+    else
+        target.setAttribute("data-theme", baseline.dataTheme);
+    if (baseline.dataColorScheme === null) {
+        target.removeAttribute("data-color-scheme");
+    }
+    else {
+        target.setAttribute("data-color-scheme", baseline.dataColorScheme);
+    }
+    restoreDocumentThemeVariables(target);
+    documentThemeBaseline = null;
+    documentThemeAppliedKeys.clear();
+}
 export class PieThemeElement extends HTMLElementBase {
     static get observedAttributes() {
         return ["theme", "scope", "provider", "scheme", "variables"];
@@ -56,7 +122,11 @@ export class PieThemeElement extends HTMLElementBase {
     mediaQuery = null;
     onMediaChange = () => this.applyTheme();
     previousKeys = new Set();
+    previousTarget = null;
     variablesOverride = {};
+    promoteDocumentOwnership = false;
+    stopObservingSchemes = null;
+    stopObservingProviders = null;
     get theme() {
         const value = this.getAttribute("theme");
         return isThemeMode(value) ? value : "light";
@@ -77,7 +147,6 @@ export class PieThemeElement extends HTMLElementBase {
     set variables(value) {
         this.variablesOverride = parseVariableOverrides(value);
         this.setAttribute("variables", JSON.stringify(this.variablesOverride));
-        this.applyTheme();
     }
     get provider() {
         return this.getAttribute("provider")?.trim() || "auto";
@@ -96,18 +165,19 @@ export class PieThemeElement extends HTMLElementBase {
             this.style.display = "contents";
         }
         this.setupAutoThemeListener();
-        this.applyTheme();
+        this.stopObservingProviders ??= observePieThemeProviders(() => this.applyTheme());
+        this.stopObservingSchemes ??= observePieColorSchemes(() => this.applyTheme());
     }
     disconnectedCallback() {
         if (this.mediaQuery) {
             this.mediaQuery.removeEventListener("change", this.onMediaChange);
         }
         this.mediaQuery = null;
-        if (this.scope === "self") {
-            this.clearPreviousKeys(this);
-            this.removeAttribute("data-theme");
-            this.removeAttribute("data-color-scheme");
-        }
+        this.stopObservingSchemes?.();
+        this.stopObservingSchemes = null;
+        this.stopObservingProviders?.();
+        this.stopObservingProviders = null;
+        this.clearPreviousTarget();
     }
     attributeChangedCallback(name, oldValue, newValue) {
         if (oldValue === newValue) {
@@ -119,6 +189,7 @@ export class PieThemeElement extends HTMLElementBase {
         if (name === "theme") {
             this.setupAutoThemeListener();
         }
+        this.promoteDocumentOwnership = true;
         this.applyTheme();
     }
     getTarget() {
@@ -128,35 +199,59 @@ export class PieThemeElement extends HTMLElementBase {
         return this;
     }
     applyTheme() {
-        if (typeof document === "undefined" || typeof window === "undefined") {
+        if (!this.isConnected ||
+            typeof document === "undefined" ||
+            typeof window === "undefined") {
             return;
         }
         const { effectiveTheme, dataTheme } = this.resolveThemeState();
         const target = this.getTarget();
-        target.setAttribute("data-theme", dataTheme);
-        if (this.scheme && this.scheme !== "default") {
-            target.setAttribute("data-color-scheme", this.scheme);
-        }
-        else {
-            target.removeAttribute("data-color-scheme");
+        if (this.previousTarget && this.previousTarget !== target) {
+            this.clearPreviousTarget();
         }
-        const themeVars = effectiveTheme === "dark" ? DARK_THEME_VARS : LIGHT_THEME_VARS;
-        const providerVars = resolveProviderVariables({
+        const providerVariables = resolveProviderVariables({
             target,
             provider: this.provider,
         });
-        const schemeVars = resolvePieColorSchemeVariables(this.scheme);
-        const vars = {
-            ...themeVars,
-            ...providerVars,
-            ...schemeVars,
-            ...this.variablesOverride,
-        };
-        this.clearPreviousKeys(target);
-        for (const [key, value] of Object.entries(vars)) {
-            target.style.setProperty(key, value);
-        }
-        this.previousKeys = new Set(Object.keys(vars));
+        const resolution = resolvePieTheme({
+            baseTheme: effectiveTheme,
+            providerVariables,
+            requestedScheme: this.scheme,
+            variables: this.variablesOverride,
+        });
+        const state = Object.freeze({
+            dataTheme,
+            dataColorScheme: this.scheme === "default" ? null : this.scheme,
+            variables: resolution.variables,
+        });
+        if (this.scope === "document") {
+            if (this.promoteDocumentOwnership && documentThemeOwners.has(this)) {
+                documentThemeOwners.delete(this);
+            }
+            // Observer-driven re-resolution updates state in place, while a direct
+            // attribute/property mutation deliberately makes this the latest owner.
+            documentThemeOwners.set(this, state);
+            this.promoteDocumentOwnership = false;
+            const activeOwner = [...documentThemeOwners.entries()].at(-1);
+            if (activeOwner?.[0] === this) {
+                applyDocumentThemeState(target, state);
+            }
+        }
+        else {
+            target.setAttribute("data-theme", dataTheme);
+            if (state.dataColorScheme) {
+                target.setAttribute("data-color-scheme", state.dataColorScheme);
+            }
+            else {
+                target.removeAttribute("data-color-scheme");
+            }
+            this.clearPreviousKeys(target);
+            for (const [key, value] of Object.entries(resolution.variables)) {
+                target.style.setProperty(key, value);
+            }
+        }
+        this.previousTarget = target;
+        this.previousKeys = new Set(Object.keys(resolution.variables));
     }
     resolveThemeState() {
         const rawTheme = this.getAttribute("theme")?.trim();
@@ -168,13 +263,33 @@ export class PieThemeElement extends HTMLElementBase {
         if (rawTheme === "dark" || rawTheme === "light") {
             return { effectiveTheme: rawTheme, dataTheme: rawTheme };
         }
-        // Non-standard theme ids (for example DaisyUI theme names) map to
-        // light base defaults while still driving provider resolution.
+        // Non-standard ids (for example DaisyUI theme names) keep their provider
+        // selector while resolving from PIE's light Base Theme.
         if (rawTheme) {
             return { effectiveTheme: "light", dataTheme: rawTheme };
         }
         return { effectiveTheme: "light", dataTheme: "light" };
     }
+    clearPreviousTarget() {
+        if (!this.previousTarget)
+            return;
+        const target = this.previousTarget;
+        if (target === document.documentElement && documentThemeOwners.has(this)) {
+            documentThemeOwners.delete(this);
+            const survivingOwner = [...documentThemeOwners.values()].at(-1);
+            if (survivingOwner)
+                applyDocumentThemeState(target, survivingOwner);
+            else
+                restoreDocumentThemeBaseline(target);
+        }
+        else {
+            this.clearPreviousKeys(target);
+            target.removeAttribute("data-theme");
+            target.removeAttribute("data-color-scheme");
+        }
+        this.previousTarget = null;
+        this.previousKeys.clear();
+    }
     clearPreviousKeys(target) {
         for (const key of this.previousKeys) {
             target.style.removeProperty(key);
@@ -188,6 +303,9 @@ export class PieThemeElement extends HTMLElementBase {
             this.mediaQuery.removeEventListener("change", this.onMediaChange);
             this.mediaQuery = null;
         }
+        if (!this.isConnected) {
+            return;
+        }
         if (this.getAttribute("theme")?.trim() === "auto") {
             this.mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
             this.mediaQuery.addEventListener("change", this.onMediaChange);

package/dist/theme-types.d.ts

@@ -1,6 +1,60 @@
 export type ThemeMode = "light" | "dark" | "auto";
 export type ThemeScope = "self" | "document";
+export type ThemeTokenName = `--pie-${string}`;
 export type ThemeVariables = Record<string, string>;
+export type PieThemeResolutionStatus = "default" | "built-in" | "custom" | "unavailable";
+export type PieColorSchemePreview = Readonly<{
+    bg: string;
+    text: string;
+    primary: string;
+}>;
+export type PieColorSchemeDescriptor = Readonly<{
+    id: string;
+    name: string;
+    description?: string;
+    kind: "default" | "built-in" | "custom";
+    preview: PieColorSchemePreview;
+}>;
+export type ColorSchemeSnapshot = Readonly<{
+    generation: number;
+    schemes: readonly PieColorSchemeDescriptor[];
+}>;
+export type PieThemeObserver = (snapshot: ColorSchemeSnapshot) => void;
+export type PieThemeDiagnosticCode = "unknown-scheme" | "invalid-registration" | "invalid-scheme-id" | "reserved-scheme-id" | "empty-scheme" | "invalid-token-name" | "excluded-token" | "invalid-token-value" | "custom-scheme-replaced" | "contrast-too-low" | "contrast-unmeasurable" | "observer-error";
+export type PieThemeDiagnostic = Readonly<{
+    code: PieThemeDiagnosticCode;
+    severity: "warning" | "error";
+    message: string;
+    index?: number;
+    schemeId?: string;
+    token?: string;
+}>;
+export type ResolvePieThemeInput = Readonly<{
+    baseTheme?: "light" | "dark";
+    requestedScheme?: string | null;
+    providerVariables?: Readonly<ThemeVariables>;
+    variables?: Readonly<ThemeVariables>;
+}>;
+export type ThemeResolution = Readonly<{
+    baseTheme: "light" | "dark";
+    requestedScheme: string;
+    resolvedScheme: PieColorSchemeDescriptor | null;
+    status: PieThemeResolutionStatus;
+    variables: Readonly<ThemeVariables>;
+    diagnostics: readonly PieThemeDiagnostic[];
+}>;
+export type RegisteredPieColorScheme = Readonly<{
+    id: string;
+    name?: string;
+    description?: string;
+    variables: Readonly<Record<string, string | number>>;
+}>;
+export type RegistrationReceipt = Readonly<{
+    acceptedSchemeIds: readonly string[];
+    diagnostics: readonly PieThemeDiagnostic[];
+    unregister(): void;
+}>;
+export type Unsubscribe = () => void;
 export declare function isThemeMode(value: string | null): value is ThemeMode;
 export declare function isThemeScope(value: string | null): value is ThemeScope;
 export declare function normalizePieThemeVariables(value: unknown): ThemeVariables;

package/dist/token-registry-types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Types for `token-registry.json`, which this package publishes as
+ * `@pie-players/pie-theme/token-registry.json`.
+ *
+ * The registry is the answer to "what is this token for, and who owns it" for
+ * every `--pie-*` name in the repo. `check:theme-tokens` and the registry
+ * contract test read it to hold source and registry in agreement; it is exported
+ * so a host can render the same answer to a person, rather than maintaining its
+ * own list of tokens that drifts the moment one is added here.
+ *
+ * The JSON is the single source of truth and is emitted to `dist` unchanged.
+ * These types describe it; they do not restate it, so there is nothing to keep
+ * in sync beyond the unions below, which the contract test pins.
+ */
+/**
+ * How widely a token may be set.
+ *
+ * `canonical-semantic` is the themeable contract: a host sets these. Everything
+ * else narrows — `component-public` is a per-component hook falling back through
+ * a canonical token, `package-private` is internal, and `unsupported` and
+ * `legacy` name tokens that exist but must not be adopted.
+ */
+export type PieThemeTokenScope = "canonical-semantic" | "component-public" | "package-private" | "unsupported" | "legacy";
+/** Whether the token is live. Non-`active` entries document a decision. */
+export type PieThemeTokenStatus = "active" | "deprecated" | "intentional-gap" | "planned";
+/**
+ * Whether a color scheme must, may, or must not set a token.
+ *
+ * Built-in schemes are complete for `required` tokens. Registered custom
+ * schemes may set `required` and `optional` tokens, while `excluded` tokens stay
+ * under their existing owner or fallback chain.
+ */
+export type PieThemeSchemeParticipation = "required" | "optional" | "excluded";
+export interface PieThemeTokenRegistryEntry {
+    /** The custom property, including the leading `--`. */
+    name: string;
+    /** Package that owns the token's meaning and may change it. */
+    owner: string;
+    scope: PieThemeTokenScope;
+    /**
+     * What the token is for — `surface`, `button`, `feedback`, `focus` and so on.
+     * Deliberately a plain string rather than a union: a new component category
+     * arrives with the component, and pinning the set here would make adding one a
+     * change to this file.
+     */
+    category: string;
+    status: PieThemeTokenStatus;
+    /** The token's role in built-in and registered custom color schemes. */
+    schemeParticipation: PieThemeSchemeParticipation;
+    /** Repo-relative paths that define the token. */
+    definedIn: string[];
+    /** Repo-relative paths that document it. */
+    documentedIn?: string[];
+    /** Why the token exists and what it must fall back through. */
+    fallbackPolicy?: string;
+}
+export type PieThemeTokenRegistry = PieThemeTokenRegistryEntry[];

package/dist/token-registry-types.js

@@ -0,0 +1,15 @@
+/**
+ * Types for `token-registry.json`, which this package publishes as
+ * `@pie-players/pie-theme/token-registry.json`.
+ *
+ * The registry is the answer to "what is this token for, and who owns it" for
+ * every `--pie-*` name in the repo. `check:theme-tokens` and the registry
+ * contract test read it to hold source and registry in agreement; it is exported
+ * so a host can render the same answer to a person, rather than maintaining its
+ * own list of tokens that drifts the moment one is added here.
+ *
+ * The JSON is the single source of truth and is emitted to `dist` unchanged.
+ * These types describe it; they do not restate it, so there is nothing to keep
+ * in sync beyond the unions below, which the contract test pins.
+ */
+export {};