@taprootio/espalier 2.0.0

package/dist/shared/theme.d.ts

@@ -0,0 +1,402 @@
+/**
+ * @module theme
+ *
+ * Data-layer for the Espalier theming system.
+ *
+ * Defines the {@link EspalierTheme} interface, default light and dark
+ * themes, and utilities for encoding, decoding, merging, and
+ * validating theme objects.
+ *
+ * A theme encapsulates **every** tuneable parameter of the design
+ * system — from the OKLCH seed color to spacing ratios, lightness
+ * curves, chroma clamps, and semantic color mappings.  Two theme
+ * objects (`light-theme` and `dark-theme`) are passed to `<esp-root>`
+ * as Base64-encoded JSON attributes; the active `scheme` attribute
+ * selects which one is applied.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   DEFAULT_LIGHT_THEME,
+ *   mergeTheme,
+ *   parseTheme,
+ *   validateTheme,
+ * } from './theme.js';
+ *
+ * const result = validateTheme(atob(JSON.stringify({ seedColor: 'oklch(0.6 0.2 30)' })));
+ * if (result.valid) {
+ *   const partial = parseTheme(myBase64String)!;
+ *   const theme   = mergeTheme(DEFAULT_LIGHT_THEME, partial);
+ * }
+ * ```
+ */
+/** A key in the lightness ramp.  Each maps to a perceptual role. */
+export type LightnessKey = "surface" | "raised1" | "raised2" | "raised3" | "raised4" | "accent" | "muted" | "text" | "border" | "ink" | "shadow";
+/** Lightness values (0–1) for every ramp position. */
+export type LightnessMap = Record<LightnessKey, number>;
+/**
+ * A geometric color-theory variant **or** a fixed semantic hue.
+ *
+ * Geometric variants are derived by rotating the seed hue; semantic
+ * hues (`danger`, `success`, `warning`) use fixed angles defined
+ * in `semanticHues`.
+ */
+export type ColorSource = "primary" | "analogous-left" | "analogous-right" | "complementary" | "split-complementary-left" | "split-complementary-right" | "triadic-left" | "triadic-right" | "danger" | "success" | "warning";
+/**
+ * Non-primary color sources — the ten variants that can carry
+ * independent chroma overrides.
+ *
+ * Primary is excluded because its chroma is always the seed
+ * color's chroma.
+ */
+export type VariantColorSource = Exclude<ColorSource, "primary">;
+/** Every semantic color token the system computes. */
+export type SemanticColorName = "background" | "layer1" | "layer2" | "layer3" | "layer4" | "actionBackground" | "actionText" | "border" | "shadow" | "text" | "dangerText" | "headings" | "headingsHover" | "link" | "linkHover" | "linkHoverBg" | "inputCaret" | "inputSelection" | "inputSelectionBg";
+/** Chroma range enforced on a semantic token before gamut mapping. */
+export interface ChromaRange {
+    /** Minimum chroma (≥ 0). */
+    min: number;
+    /** Maximum chroma (≤ 0.4). */
+    max: number;
+}
+/**
+ * Describes how a single semantic color is derived:
+ * which color source provides the hue + chroma, and which
+ * lightness ramp position sets the perceived brightness.
+ */
+export interface SemanticMapping {
+    /** The color variant or semantic hue to sample. */
+    source: ColorSource;
+    /** The lightness ramp position to apply. */
+    lightness: LightnessKey;
+}
+/** Full mapping table — one entry per semantic color token. */
+export type SemanticMappings = Record<SemanticColorName, SemanticMapping>;
+/** The complete, resolved Espalier theme. */
+export interface EspalierTheme {
+    /** OKLCH seed color string — drives the entire palette. */
+    seedColor: string;
+    /** CSS `font-family` for body / UI text. */
+    fontBody: string;
+    /** CSS `font-family` for headings. */
+    fontHeadings: string;
+    /** CSS `font-family` for brand marks and product names. */
+    fontBrand: string;
+    /** CSS `font-family` for code / monospace text. */
+    fontMonospace: string;
+    /**
+     * CSS `font-weight` for body / UI text.
+     *
+     * Accepts any valid CSS font-weight value: numeric (`"400"`,
+     * `"700"`, range 1–1000), keyword (`"normal"`, `"bold"`,
+     * `"lighter"`, `"bolder"`), or CSS-wide keyword (`"inherit"`,
+     * `"initial"`, `"unset"`, `"revert"`, `"revert-layer"`).
+     *
+     * Emitted as `--esp-font-weight-body`.
+     *
+     * @default "normal"
+     */
+    fontWeightBody: string;
+    /**
+     * CSS `font-weight` for headings.
+     *
+     * Accepts the same values as {@link fontWeightBody}.
+     *
+     * Emitted as `--esp-font-weight-headings`.
+     *
+     * @default "bold"
+     */
+    fontWeightHeadings: string;
+    /**
+     * CSS `font-weight` for brand marks and product names.
+     *
+     * Accepts the same values as {@link fontWeightBody}.
+     *
+     * Emitted as `--esp-font-weight-brand`.
+     *
+     * @default "bold"
+     */
+    fontWeightBrand: string;
+    /**
+     * CSS `font-weight` for code / monospace text.
+     *
+     * Accepts the same values as {@link fontWeightBody}.
+     *
+     * Emitted as `--esp-font-weight-monospace`.
+     *
+     * @default "normal"
+     */
+    fontWeightMonospace: string;
+    /** External stylesheets injected into `document.head`. */
+    stylesheets: string[];
+    /** Root font size in px (sets the HTML root `font-size`). */
+    rootFontSize: number;
+    /** Modular ratio for the type scale (Major Third = 1.25). */
+    typeRatio: number;
+    /** Modular ratio for the spacing scale (Golden Ratio ≈ 1.618). */
+    spaceRatio: number;
+    /** Global border-radius in rem. */
+    borderRadius: number;
+    /** Minimum viewport width (px) for fluid interpolation. */
+    viewportMin: number;
+    /** Maximum viewport width (px) for fluid interpolation. */
+    viewportMax: number;
+    /** Hue-rotation angles for geometric color variants. */
+    angles: {
+        /** Analogous offset from seed (default 30). */
+        analogous: number;
+        /** Complementary offset from seed (default 180). */
+        complementary: number;
+        /**
+         * Split-complementary offset **from the complement**.
+         * The mirror is computed automatically (default 30).
+         */
+        splitComplementary: number;
+        /** Triadic offset from seed (default 120). */
+        triadic: number;
+    };
+    /** Fixed hue angles for danger / success / warning colors. */
+    semanticHues: {
+        /** Danger hue angle (default 27, red-orange). */
+        danger: number;
+        /** Success hue angle (default 150, green). */
+        success: number;
+        /** Warning hue angle (default 90, yellow-green). */
+        warning: number;
+    };
+    /**
+     * Per-variant chroma overrides (OKLCH chroma, 0–0.4).
+     *
+     * Each entry sets the **base chroma** for the corresponding
+     * color variant, overriding the seed color's chroma for that
+     * variant only.  Omitted entries inherit the seed color's
+     * chroma at compute time.
+     *
+     * This is independent of the per-semantic-token `chroma` ranges
+     * which clamp chroma *after* derivation.  `variantChroma` controls
+     * the input chroma of the variant itself, while `chroma` controls
+     * the output range of each semantic token.
+     *
+     * @example
+     * ```ts
+     * // Make complementary colors more vivid, mute triadic colors
+     * variantChroma: {
+     *   "complementary": 0.22,
+     *   "triadic-left": 0.06,
+     *   "triadic-right": 0.06,
+     * }
+     * ```
+     */
+    variantChroma: Partial<Record<VariantColorSource, number>>;
+    /** Lightness values (0–1) for the eleven ramp positions. */
+    lightness: LightnessMap;
+    /** Per-semantic-token chroma min / max. */
+    chroma: Record<SemanticColorName, ChromaRange>;
+    /** Maps each semantic token to its color source + lightness. */
+    semanticMappings: SemanticMappings;
+    /** Optional CSS `background-image` for the page surface. */
+    pageBackgroundImage?: string;
+    /** Opacity (0–1) for the page background image. */
+    pageBackgroundImageOpacity?: number;
+    /** Optional CSS `background-image` for `esp-box` surfaces. */
+    boxBackgroundImage?: string;
+    /** Opacity (0–1) for the box background image. */
+    boxBackgroundImageOpacity?: number;
+    /** Opacity (0–1) for the vellum (modal overlay) backdrop. */
+    vellumOpacity?: number;
+    /** Optional CSS `background-image` for vellum overlays. */
+    vellumBackgroundImage?: string;
+    /** Opacity (0–1) for the vellum background image layer. */
+    vellumBackgroundImageOpacity?: number;
+}
+/** Recursively-partial version of {@link EspalierTheme}. */
+export type PartialTheme = DeepPartial<EspalierTheme>;
+/** Validation result returned by {@link validateTheme}. */
+export interface ThemeValidationResult {
+    /** `true` when there are zero errors (warnings are allowed). */
+    valid: boolean;
+    /** Hard failures — the theme should not be applied. */
+    errors: string[];
+    /** Soft issues — the theme will work but values are unusual. */
+    warnings: string[];
+}
+/** Ordered list of all semantic color token names. */
+export declare const SEMANTIC_COLOR_NAMES: readonly SemanticColorName[];
+/** Valid color-source identifiers for {@link SemanticMapping.source}. */
+export declare const COLOR_SOURCES: readonly ColorSource[];
+/**
+ * Non-primary color sources that support independent chroma overrides.
+ *
+ * Matches the ten entries in {@link VariantColorSource}.
+ */
+export declare const VARIANT_COLOR_SOURCES: readonly VariantColorSource[];
+/** Valid keys for the lightness ramp. */
+export declare const LIGHTNESS_KEYS: readonly LightnessKey[];
+/**
+ * Default lightness ramp for the **light** scheme.
+ *
+ * High values for surfaces → low values for text, following the
+ * natural top-to-bottom contrast gradient of a printed page.
+ */
+export declare const DEFAULT_LIGHT_LIGHTNESS: Readonly<LightnessMap>;
+/**
+ * Default lightness ramp for the **dark** scheme.
+ *
+ * Inverted: low values for surfaces, high values for text.
+ */
+export declare const DEFAULT_DARK_LIGHTNESS: Readonly<LightnessMap>;
+/**
+ * Default semantic color mappings that match the existing CSS.
+ *
+ * Each entry tells the color engine which variant supplies the
+ * hue and which lightness key sets the perceived brightness.
+ */
+export declare const DEFAULT_SEMANTIC_MAPPINGS: Readonly<SemanticMappings>;
+/**
+ * The built-in **light** theme.
+ *
+ * Identical to the dark theme in every field except `lightness`,
+ * which uses a high-surface / low-text ramp suited for bright
+ * backgrounds.
+ */
+export declare const DEFAULT_LIGHT_THEME: Readonly<EspalierTheme>;
+/**
+ * The built-in **dark** theme.
+ *
+ * Identical to the light theme in every field except `lightness`,
+ * which uses a low-surface / high-text ramp suited for dark
+ * backgrounds.
+ */
+export declare const DEFAULT_DARK_THEME: Readonly<EspalierTheme>;
+/**
+ * Recursively-partial utility type.
+ *
+ * Arrays are left as-is (a partial array is still an array),
+ * while plain objects are made deeply optional.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? U[] : T[P] extends Record<string, unknown> ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Convert a {@link SemanticColorName} (camelCase) to its CSS
+ * custom-property name (kebab-case with `--esp-color-` prefix).
+ *
+ * ```
+ * linkHoverBg → --esp-color-link-hover-bg
+ * layer1      → --esp-color-layer-1
+ * ```
+ */
+export declare function semanticToCSS(name: SemanticColorName): string;
+/**
+ * Decode a Base64-encoded JSON string into a {@link PartialTheme}.
+ *
+ * Returns `null` if decoding or JSON parsing fails — never throws.
+ *
+ * Unsafe property names (`__proto__`, `constructor`, `prototype`)
+ * are stripped during parsing via a JSON reviver to prevent
+ * prototype pollution from untrusted encoded themes.
+ *
+ * @param base64 A Base64-encoded JSON string.
+ * @returns The decoded partial theme, or `null` on failure.
+ */
+export declare function parseTheme(base64: string): PartialTheme | null;
+/**
+ * Encode a {@link PartialTheme} as a Base64 JSON string.
+ *
+ * The inverse of {@link parseTheme}.
+ *
+ * @param partial The partial theme to encode.
+ * @returns A Base64-encoded JSON string.
+ */
+export declare function encodeTheme(partial: PartialTheme): string;
+/**
+ * Deep-merge a {@link PartialTheme} over a set of defaults.
+ *
+ * Primitive fields are replaced; nested objects (`angles`,
+ * `semanticHues`, `lightness`, `chroma`, `semanticMappings`)
+ * are merged key-by-key.  Arrays (`stylesheets`) are replaced
+ * wholesale.
+ *
+ * @param defaults The fully-resolved base theme.
+ * @param overrides User-supplied partial overrides.
+ * @returns A new fully-resolved {@link EspalierTheme}.
+ */
+export declare function mergeTheme(defaults: EspalierTheme, overrides: PartialTheme): EspalierTheme;
+/**
+ * Validate a Base64-encoded theme string.
+ *
+ * Checks structure, types, and value ranges.  The function is
+ * intentionally lenient on unknown keys (future-proofing) but
+ * strict on the keys it recognises.
+ *
+ * @param base64 A Base64-encoded JSON string representing a
+ *   partial or full theme.
+ * @returns A {@link ThemeValidationResult} with `valid`, `errors`,
+ *   and `warnings`.
+ */
+export declare function validateTheme(base64: string): ThemeValidationResult;
+/**
+ * Keys of {@link EspalierTheme} whose values are nested objects
+ * and therefore need key-by-key merging instead of wholesale
+ * replacement when combining two {@link PartialTheme} objects.
+ */
+export declare const NESTED_THEME_KEYS: readonly ["angles", "chroma", "lightness", "semanticHues", "semanticMappings", "variantChroma"];
+/**
+ * Deep-merge two {@link PartialTheme} objects.
+ *
+ * Top-level primitive fields are replaced by the override when the
+ * override value is not `undefined`.  Override keys that are
+ * explicitly `undefined` are skipped so they don't erase
+ * previously-layered values.
+ *
+ * Nested-object fields listed in {@link NESTED_THEME_KEYS} are
+ * merged key-by-key (also skipping `undefined` inner values) so
+ * that the override adds to (rather than replaces) the base.
+ *
+ * This differs from {@link mergeTheme}, which merges a
+ * {@link PartialTheme} over a fully-resolved {@link EspalierTheme}.
+ * `mergePartials` keeps the result partial — useful when layering
+ * multiple partial overrides before resolving against defaults.
+ *
+ * @param base   The base partial theme.
+ * @param override Partial overrides to apply on top.
+ * @returns A new {@link PartialTheme} with merged values.
+ */
+export declare function mergePartials(base: PartialTheme, override: PartialTheme): PartialTheme;
+/**
+ * Layer multiple encoded theme strings into a single encoded result.
+ *
+ * Each argument is a Base64-encoded JSON {@link PartialTheme} (as
+ * produced by {@link encodeTheme}).  They are parsed, merged left
+ * to right via {@link mergePartials}, and re-encoded.
+ *
+ * Entries that are `null`, `undefined`, empty strings, or strings
+ * that fail to decode/parse are silently skipped, making it safe
+ * to pass optional or potentially-invalid theme overrides without
+ * conditional logic.
+ *
+ * @param encodedThemes Variadic encoded theme strings.
+ * @returns A single Base64-encoded merged theme.
+ */
+export declare function layerThemes(...encodedThemes: Array<string | undefined | null>): string;
+/**
+ * Build the Taproot **light** default theme as an encoded string.
+ *
+ * @param backgroundImageUrl URL of the page background image
+ *   (e.g. a manifest-hashed asset path or a static path).
+ *   Wrapped in `url("…")` automatically — the URL is escaped
+ *   so special characters cannot break the CSS context.
+ * @returns A Base64-encoded {@link PartialTheme}.
+ */
+export declare function buildTaprootLightTheme(backgroundImageUrl: string): string;
+/**
+ * Build the Taproot **dark** default theme as an encoded string.
+ *
+ * @param backgroundImageUrl URL of the page background image
+ *   (e.g. a manifest-hashed asset path or a static path).
+ *   Wrapped in `url("…")` automatically — the URL is escaped
+ *   so special characters cannot break the CSS context.
+ * @returns A Base64-encoded {@link PartialTheme}.
+ */
+export declare function buildTaprootDarkTheme(backgroundImageUrl: string): string;
+export {};

package/dist/shared/theme.js

@@ -0,0 +1 @@
+import{parseOklch as O}from"./color-engine.js";const h=["background","layer1","layer2","layer3","layer4","actionBackground","actionText","border","shadow","text","dangerText","headings","headingsHover","link","linkHover","linkHoverBg","inputCaret","inputSelection","inputSelectionBg"],$=["primary","analogous-left","analogous-right","complementary","split-complementary-left","split-complementary-right","triadic-left","triadic-right","danger","success","warning"],C=["analogous-left","analogous-right","complementary","split-complementary-left","split-complementary-right","triadic-left","triadic-right","danger","success","warning"],d=["surface","raised1","raised2","raised3","raised4","accent","muted","text","border","ink","shadow"],I={surface:.99,raised1:.97,raised2:.9,raised3:.8,raised4:.72,accent:.5,muted:.45,text:.35,border:.3,ink:.25,shadow:.2},T={surface:.15,raised1:.2,raised2:.3,raised3:.4,raised4:.36,accent:.6,muted:.75,text:.85,border:.7,ink:.95,shadow:.6},y={background:{source:"primary",lightness:"surface"},layer1:{source:"primary",lightness:"raised1"},layer2:{source:"primary",lightness:"raised2"},layer3:{source:"primary",lightness:"raised3"},layer4:{source:"primary",lightness:"raised4"},actionBackground:{source:"primary",lightness:"raised3"},actionText:{source:"primary",lightness:"ink"},border:{source:"primary",lightness:"border"},shadow:{source:"primary",lightness:"shadow"},text:{source:"primary",lightness:"text"},dangerText:{source:"danger",lightness:"text"},headings:{source:"primary",lightness:"muted"},headingsHover:{source:"primary",lightness:"text"},link:{source:"complementary",lightness:"accent"},linkHover:{source:"complementary",lightness:"text"},linkHoverBg:{source:"triadic-left",lightness:"raised2"},inputCaret:{source:"triadic-right",lightness:"ink"},inputSelection:{source:"complementary",lightness:"text"},inputSelectionBg:{source:"triadic-left",lightness:"raised2"}},f=.4;function b(){const i={};for(const e of h)i[e]={min:0,max:f};return i}const B={seedColor:"oklch(0.7 0.125 216)",fontBody:"",fontHeadings:"",fontBrand:"",fontMonospace:"",fontWeightBody:"normal",fontWeightHeadings:"bold",fontWeightBrand:"bold",fontWeightMonospace:"normal",stylesheets:[],rootFontSize:16,typeRatio:1.25,spaceRatio:1.618,borderRadius:.2,viewportMin:320,viewportMax:1200,angles:{analogous:30,complementary:180,splitComplementary:30,triadic:120},semanticHues:{danger:27,success:150,warning:90},variantChroma:{},chroma:b(),semanticMappings:{...y}},_={...B,chroma:b(),semanticMappings:{...y},lightness:{...I}},W={...B,chroma:b(),semanticMappings:{...y},lightness:{...T}},M=new Set(["__proto__","constructor","prototype"]);function l(i){return!M.has(i)}function w(i,e){return M.has(i)?void 0:e}function F(i){return`--esp-color-${i.replace(/([A-Z])/g,"-$1").replace(/(\d)/g,"-$1").toLowerCase()}`}function R(i){try{const e=atob(i),s=JSON.parse(e,w);return typeof s!="object"||s===null||Array.isArray(s)?null:s}catch{return null}}function k(i){return btoa(JSON.stringify(i))}function N(i,e){const s={...i,seedColor:e.seedColor??i.seedColor,fontBody:e.fontBody??i.fontBody,fontHeadings:e.fontHeadings??i.fontHeadings,fontBrand:e.fontBrand??i.fontBrand,fontMonospace:e.fontMonospace??i.fontMonospace,fontWeightBody:String(e.fontWeightBody??i.fontWeightBody),fontWeightHeadings:String(e.fontWeightHeadings??i.fontWeightHeadings),fontWeightBrand:String(e.fontWeightBrand??i.fontWeightBrand),fontWeightMonospace:String(e.fontWeightMonospace??i.fontWeightMonospace),stylesheets:e.stylesheets??[...i.stylesheets],rootFontSize:e.rootFontSize??i.rootFontSize,typeRatio:e.typeRatio??i.typeRatio,spaceRatio:e.spaceRatio??i.spaceRatio,borderRadius:e.borderRadius??i.borderRadius,viewportMin:e.viewportMin??i.viewportMin,viewportMax:e.viewportMax??i.viewportMax,angles:{...i.angles,...e.angles},semanticHues:{...i.semanticHues,...e.semanticHues},variantChroma:{...i.variantChroma,...e.variantChroma},lightness:{...i.lightness,...e.lightness},chroma:S(i.chroma,e.chroma),semanticMappings:S(i.semanticMappings,e.semanticMappings)};return e.pageBackgroundImage!==void 0&&(s.pageBackgroundImage=e.pageBackgroundImage),e.pageBackgroundImageOpacity!==void 0&&(s.pageBackgroundImageOpacity=e.pageBackgroundImageOpacity),e.boxBackgroundImage!==void 0&&(s.boxBackgroundImage=e.boxBackgroundImage),e.boxBackgroundImageOpacity!==void 0&&(s.boxBackgroundImageOpacity=e.boxBackgroundImageOpacity),e.vellumOpacity!==void 0&&(s.vellumOpacity=e.vellumOpacity),e.vellumBackgroundImage!==void 0&&(s.vellumBackgroundImage=e.vellumBackgroundImage),e.vellumBackgroundImageOpacity!==void 0&&(s.vellumBackgroundImageOpacity=e.vellumBackgroundImageOpacity),s}function S(i,e){if(!e)return{...i};const s={...i};for(const c of Object.keys(e)){const u=e[c];u!==void 0&&(s[c]=u)}return s}function L(i){const e=[],s=[];let c;try{c=atob(i)}catch{return e.push("Failed to decode Base64 string."),{valid:!1,errors:e,warnings:s}}let u;try{u=JSON.parse(c)}catch{return e.push("Decoded string is not valid JSON."),{valid:!1,errors:e,warnings:s}}if(typeof u!="object"||u===null||Array.isArray(u))return e.push("Theme must be a JSON object."),{valid:!1,errors:e,warnings:s};const o=u;"seedColor"in o&&(typeof o.seedColor!="string"?e.push("seedColor must be a string."):O(o.seedColor)||e.push(`seedColor is not a valid OKLCH value: "${o.seedColor}".`));for(const t of["fontBody","fontHeadings","fontBrand","fontMonospace"])t in o&&typeof o[t]!="string"&&e.push(`${t} must be a string.`);const g=["normal","bold","lighter","bolder"],p=["inherit","initial","unset","revert","revert-layer"];for(const t of["fontWeightBody","fontWeightHeadings","fontWeightBrand","fontWeightMonospace"])if(t in o){const n=o[t];if(typeof n=="number")(n<1||n>1e3)&&e.push(`${t} numeric value must be 1\u20131000 (got ${n}).`);else if(typeof n=="string"){const a=g.includes(n)||p.includes(n);if(/^\d+$/.test(n)){const x=Number(n);(x<1||x>1e3)&&e.push(`${t} numeric value must be 1\u20131000 (got "${n}").`)}else a||s.push(`${t} = "${n}" is not a standard font-weight value.`)}else e.push(`${t} must be a string or number.`)}"stylesheets"in o&&(Array.isArray(o.stylesheets)?o.stylesheets.some(t=>typeof t!="string")&&e.push("Every entry in stylesheets must be a string."):e.push("stylesheets must be an array of strings."));const m=[["rootFontSize",1,100],["borderRadius",0,10],["viewportMin",100,1e4],["viewportMax",200,1e4]];for(const[t,n,a]of m)if(t in o)if(typeof o[t]!="number"||!isFinite(o[t]))e.push(`${t} must be a finite number.`);else{const r=o[t];n!==void 0&&r<n&&e.push(`${t} must be \u2265 ${n} (got ${r}).`),a!==void 0&&r>a&&s.push(`${t} = ${r} is unusually high (max ${a}).`)}for(const t of["typeRatio","spaceRatio"])if(t in o)if(typeof o[t]!="number"||!isFinite(o[t]))e.push(`${t} must be a finite number.`);else{const n=o[t];n<=1&&e.push(`${t} must be > 1 (got ${n}).`);const a=t==="typeRatio"?1.3:2;n>a&&s.push(`${t} = ${n} is very high (max ${a}); scales may be extreme.`)}if("viewportMin"in o&&"viewportMax"in o){const t=o.viewportMin,n=o.viewportMax;typeof t=="number"&&typeof n=="number"&&t>=n&&e.push(`viewportMin (${t}) must be less than viewportMax (${n}).`)}if("angles"in o)if(typeof o.angles!="object"||o.angles===null)e.push("angles must be an object.");else{const t=o.angles;for(const n of["analogous","complementary","splitComplementary","triadic"])if(n in t)if(typeof t[n]!="number"||!isFinite(t[n]))e.push(`angles.${n} must be a finite number.`);else{const a=t[n];(a<0||a>360)&&s.push(`angles.${n} = ${a} is outside 0\u2013360.`)}}if("semanticHues"in o)if(typeof o.semanticHues!="object"||o.semanticHues===null)e.push("semanticHues must be an object.");else{const t=o.semanticHues;for(const n of["danger","success","warning"])if(n in t)if(typeof t[n]!="number"||!isFinite(t[n]))e.push(`semanticHues.${n} must be a finite number.`);else{const a=t[n];(a<0||a>360)&&s.push(`semanticHues.${n} = ${a} is outside 0\u2013360.`)}}if("variantChroma"in o)if(typeof o.variantChroma!="object"||o.variantChroma===null)e.push("variantChroma must be an object.");else{const t=o.variantChroma;for(const n of C)if(n in t)if(typeof t[n]!="number"||!isFinite(t[n]))e.push(`variantChroma["${n}"] must be a finite number.`);else{const a=t[n];a<0&&e.push(`variantChroma["${n}"] must be \u2265 0 (got ${a}).`),a>f&&s.push(`variantChroma["${n}"] = ${a} exceeds ${f}.`)}}if("lightness"in o)if(typeof o.lightness!="object"||o.lightness===null)e.push("lightness must be an object.");else{const t=o.lightness;for(const n of d)if(n in t)if(typeof t[n]!="number"||!isFinite(t[n]))e.push(`lightness.${n} must be a finite number.`);else{const a=t[n];(a<0||a>1)&&e.push(`lightness.${n} must be 0\u20131 (got ${a}).`)}}if("chroma"in o)if(typeof o.chroma!="object"||o.chroma===null)e.push("chroma must be an object.");else{const t=o.chroma;for(const n of h)if(n in t){const a=t[n];if(typeof a!="object"||a===null){e.push(`chroma.${n} must be { min, max }.`);continue}const r=a;(typeof r.min!="number"||r.min<0)&&e.push(`chroma.${n}.min must be \u2265 0.`),(typeof r.max!="number"||r.max<0||r.max>f)&&e.push(`chroma.${n}.max must be 0\u2013${f}.`),typeof r.min=="number"&&typeof r.max=="number"&&r.min>r.max&&e.push(`chroma.${n}.min (${r.min}) must be \u2264 max (${r.max}).`)}}if("semanticMappings"in o)if(typeof o.semanticMappings!="object"||o.semanticMappings===null)e.push("semanticMappings must be an object.");else{const t=o.semanticMappings;for(const n of h)if(n in t){const a=t[n];if(typeof a!="object"||a===null){e.push(`semanticMappings.${n} must be { source, lightness }.`);continue}const r=a;(typeof r.source!="string"||!$.includes(r.source))&&e.push(`semanticMappings.${n}.source must be one of: ${$.join(", ")}.`),(typeof r.lightness!="string"||!d.includes(r.lightness))&&e.push(`semanticMappings.${n}.lightness must be one of: ${d.join(", ")}.`)}}for(const t of["pageBackgroundImage","boxBackgroundImage","vellumBackgroundImage"])t in o&&typeof o[t]!="string"&&e.push(`${t} must be a string.`);for(const t of["pageBackgroundImageOpacity","boxBackgroundImageOpacity","vellumOpacity","vellumBackgroundImageOpacity"])if(t in o)if(typeof o[t]!="number"||!isFinite(o[t]))e.push(`${t} must be a finite number.`);else{const n=o[t];(n<0||n>1)&&e.push(`${t} must be 0\u20131 (got ${n}).`)}return{valid:e.length===0,errors:e,warnings:s}}const A=["angles","chroma","lightness","semanticHues","semanticMappings","variantChroma"];function E(i,e){const s={};for(const[c,u]of Object.entries(i))l(c)&&(s[c]=u);for(const[c,u]of Object.entries(e))u!==void 0&&l(c)&&(s[c]=u);for(const c of A){const u=i[c],o=e[c];if(u&&typeof u=="object"&&!Array.isArray(u)&&o&&typeof o=="object"&&!Array.isArray(o)){const g={};for(const[p,m]of Object.entries(u))l(p)&&(g[p]=m);for(const[p,m]of Object.entries(o))m!==void 0&&l(p)&&(g[p]=m);s[c]=g}}return s}function D(...i){let e={};for(const s of i){if(!s)continue;const c=R(s);c&&(e=E(e,c))}return k(e)}function v(i){return i.replace(/\\/g,"\\\\").replace(/"/g,'\\"').replace(/\n/g,"\\n").replace(/\r/g,"\\r")}const H={borderRadius:.1,fontBody:'"Noto Sans", sans-serif',fontWeightBody:"normal",fontHeadings:'"Inika", serif',fontWeightHeadings:"normal",fontBrand:'"Inika", serif',fontWeightBrand:"normal",fontMonospace:'"JetBrains Mono", monospace',fontWeightMonospace:"normal",seedColor:"oklch(.07 0.15 216)"};function K(i){return k({...H,pageBackgroundImage:`url("${v(i)}")`,pageBackgroundImageOpacity:.5})}function U(i){return k({...H,pageBackgroundImage:`url("${v(i)}")`,pageBackgroundImageOpacity:.55})}export{$ as COLOR_SOURCES,T as DEFAULT_DARK_LIGHTNESS,W as DEFAULT_DARK_THEME,I as DEFAULT_LIGHT_LIGHTNESS,_ as DEFAULT_LIGHT_THEME,y as DEFAULT_SEMANTIC_MAPPINGS,d as LIGHTNESS_KEYS,A as NESTED_THEME_KEYS,h as SEMANTIC_COLOR_NAMES,C as VARIANT_COLOR_SOURCES,U as buildTaprootDarkTheme,K as buildTaprootLightTheme,k as encodeTheme,D as layerThemes,E as mergePartials,N as mergeTheme,R as parseTheme,F as semanticToCSS,L as validateTheme};

package/dist/shared/toast-events.d.ts

@@ -0,0 +1,60 @@
+import type { EspalierVariant } from "./esp-element-base.js";
+/**
+ * Configuration for a toast notification.
+ *
+ * @docUrl /api/toast-config
+ * @menuGroup Configuration
+ * @menuLabel ToastConfig
+ */
+export type ToastConfig = {
+    /**
+     * The duration, in seconds, to show the toast. 0 if it should
+     * show until the user dismisses it. Defaults to 5 seconds.
+     */
+    duration?: number | undefined;
+    /**
+     * The message to show in the toast.
+     */
+    message: string;
+    /**
+     * Icon name from the configured Espalier SVG sprite.
+     *
+     * Prefer this for icons from the shared sprite; `<esp-toaster>`
+     * resolves it through the nearest `<esp-root icon-sprite-url>`.
+     */
+    icon?: string | undefined;
+    /**
+     * Full SVG href to use as the icon, for example:
+     * "/assets/icons.svg#info-i"
+     *
+     * This remains available for custom sprites or fully controlled
+     * hrefs. When both `icon` and `svgPath` are provided, `svgPath`
+     * takes precedence.
+     */
+    svgPath?: string | undefined;
+    /**
+     * The color variant of the toast.
+     */
+    variant?: EspalierVariant;
+    /**
+     * Callback fired when the toast is closed.
+     */
+    onClosed?: (() => void) | undefined;
+};
+/**
+ * Show a toast notification. Publishes a `"show-toast"` event on
+ * `EspBus` which is picked up by `<esp-toaster>`.
+ *
+ * ```ts
+ * import { showToast } from "@taprootio/espalier";
+ *
+ * showToast({ message: "Saved!", variant: "success" });
+ * showToast({ message: "Error!", variant: "danger", duration: 0 });
+ * ```
+ *
+ * @param config - Toast configuration.
+ * @docUrl /api/show-toast
+ * @menuGroup Functions
+ * @menuLabel showToast
+ */
+export declare function showToast(config: ToastConfig): void;

package/dist/shared/toast-events.js

@@ -0,0 +1 @@
+import{getEspBus as s}from"./bus-events.js";function p(o){s().publish("show-toast",o)}export{p as showToast};

package/dist/shared/utilities.d.ts

@@ -0,0 +1,58 @@
+type SpaceAboveBelow = {
+    spaceAbove: number;
+    spaceBelow: number;
+};
+/**
+ * Calculates the available space above and below an element relative to the viewport.
+ *
+ * @param element - The HTML element to measure
+ * @returns An object containing spaceAbove and spaceBelow in pixels
+ */
+export declare function getSpaceAboveBelow(element: HTMLElement): SpaceAboveBelow;
+/**
+ * Scrolls an element into view within a scrollable container.
+ * Handles scrolling up or down based on the direction flag.
+ *
+ * @param container - The scrollable container element
+ * @param element - The element to scroll into view
+ * @param up - If true, scroll upward; if false, scroll downward
+ */
+export declare function scrollElementIntoView(container: HTMLElement, element: HTMLElement, up: boolean): void;
+/**
+ * Traverses up the DOM tree from a given element to find the closest matching element.
+ * Handles traversal across Shadow DOM boundaries to locate elements in parent scopes.
+ *
+ * @template TElement - The expected type of the returned element
+ * @param fromElement - The element to start the search from
+ * @param selector - The CSS selector to match against
+ * @returns The closest matching element, or null if none found
+ */
+export declare function traverseToClosest<TElement extends HTMLElement>(fromElement: Element, selector: string): TElement | null;
+/**
+ * Checks if an element or any of its ancestors have a fixed position within a Shadow DOM.
+ * Recursively traverses the Shadow DOM tree to detect fixed positioning.
+ *
+ * @param element - The element to check
+ * @returns True if the element or any ancestor is fixed-positioned within Shadow DOM, false otherwise
+ */
+export declare function isFixedInShadowDom(element: HTMLElement): boolean;
+/**
+ * Checks if an element has a fixed position or if any of its ancestors are fixed-positioned.
+ * Traverses up the DOM tree to detect fixed positioning at any level.
+ *
+ * @param element - The element to check
+ * @returns True if the element or any ancestor has position: fixed, false otherwise
+ */
+export declare function isFixedOrAncestorFixed(element: HTMLElement): boolean;
+/**
+ * Compares two arrays to check if they contain the same values for a specific key.
+ * Arrays are compared by extracting values for the given key, sorting them, and checking equality.
+ * Order of elements in the original arrays does not matter.
+ *
+ * @param arr1 - The first array to compare
+ * @param arr2 - The second array to compare
+ * @param key - The object key to extract and compare values
+ * @returns True if both arrays have the same length and matching values for the key, false otherwise
+ */
+export declare const arrayKeysMatch: (arr1: Array<Record<string, unknown>>, arr2: Array<Record<string, unknown>>, key: string) => boolean;
+export {};

package/dist/shared/utilities.js

@@ -0,0 +1 @@
+function c(t){const e=t.getBoundingClientRect(),o=window.innerHeight||document.documentElement.clientHeight,s=e.top,n=o-e.bottom;return{spaceAbove:s,spaceBelow:n}}function d(t,e,o){const s=t.getBoundingClientRect(),n=e.getBoundingClientRect();if(n.top<s.top||n.bottom>s.bottom){const i=n.top-s.top;o||!o&&i<0?t.scrollTop+=i:t.scrollBy({top:n.height})}}function u(t,e){let o=t,s=null;for(;!s&&o&&o.closest;)if(s=o.closest(e),!s){const n=o.getRootNode();n instanceof ShadowRoot?o=n.host:o=void 0}return s}function f(t){let e=t;for(;e;){if(r(e.assignedSlot?.parentNode)||getComputedStyle(e).position==="fixed")return!0;const n=e.assignedSlot?e.assignedSlot.getRootNode():e.getRootNode();if(n instanceof ShadowRoot)e=n.host;else break}return!1}function r(t){if(!t||!(t instanceof HTMLElement))return!1;let e=t;for(;e;){if(getComputedStyle(e).position==="fixed")return!0;e=e.parentElement}return!1}const p=(t,e,o)=>{if(t.length!==e.length)return!1;const s=t.map(i=>i[o]).sort(),n=e.map(i=>i[o]).sort();return s.every((i,l)=>i===n[l])};export{p as arrayKeysMatch,c as getSpaceAboveBelow,f as isFixedInShadowDom,r as isFixedOrAncestorFixed,d as scrollElementIntoView,u as traverseToClosest};

package/dist/shared/validation.d.ts

@@ -0,0 +1,11 @@
+export type ValidationError = {
+    errorMessage: string;
+    fieldName: string;
+};
+/** Event name dispatched by `FormFieldController` on every validation pass. */
+export declare const VALIDITY_CHANGED_EVENT = "validity-changed";
+/** Detail payload for the `validity-changed` custom event. */
+export interface ValidityChangedDetail {
+    valid: boolean;
+    message: string;
+}

package/dist/shared/validation.js

@@ -0,0 +1 @@
+const t="validity-changed";export{t as VALIDITY_CHANGED_EVENT};