@skdx/tokens 0.28.0 → 0.30.0

package/dist/utils/foundation.d.ts

@@ -1,42 +1,17 @@
+import { type CssVar } from './cssVars.js';
 import { type ThemeControls, type ThemeControlsCoarse, type ThemeMotion, type ThemeRadii, type ThemeShadows, type ThemeSpace, type ThemeTypography } from './theme.js';
-/**
- * The type system: one font stack, scale, weight set, line-heights and
- * tracking steps, shared by every theme. Only the font stacks are
- * per-theme overridable, via {@link ThemeTypographyDeviation}.
- * @public
- */
+/** The shared type system — font stacks, scale, weights, line-heights, tracking — with only stacks overridable via {@link ThemeTypographyDeviation}. @public */
 export declare const typography: ThemeTypography;
-/**
- * The spacing scale — a 4px base, structural rather than per-brand: gap and
- * padding are rhythm, a property of the system, not the brand on top of it.
- * @public
- */
+/** The spacing scale — a 4px base, structural rather than per-brand. @public */
 export declare const space: ThemeSpace;
-/**
- * The corner-radius scale, structural like {@link space}: a component's
- * silhouette is part of the system's shape language, not the brand's.
- * @public
- */
+/** The corner-radius scale, structural like {@link space} rather than per-brand. @public */
 export declare const radii: ThemeRadii;
-/**
- * The elevation scale — geometry only. Every value defers its color to
- * `var(--skdx-shadow-color)` and scales its alpha by
- * `var(--skdx-shadow-strength)`, both supplied by a theme (see
- * {@link ThemeShadowColor}), so 38 themes share one set of offsets instead of
- * each restating them to vary only the color.
- * @public
- */
+/** The elevation scale (geometry only); color and alpha come from theme-supplied `--skdx-shadow-color`/`-strength` (see {@link ThemeShadowColor}). @public */
 export declare const shadows: ThemeShadows;
-/**
- * The shared animation timing, re-exported from {@link defaultMotion}. See
- * {@link ThemeMotion} for why motion is theme-invariant.
- * @public
- */
+/** The shared animation timing, re-exported from {@link defaultMotion} and invariant per {@link ThemeMotion}. @public */
 export declare const motion: Required<ThemeMotion>;
 /**
- * A structural stacking-order scale for overlay-class UI (dropdowns, sticky
- * headers, dialog/popover backdrops, floating content, toasts) — every theme
- * stacks the same way, so it's exported once rather than duplicated per theme.
+ * Structural stacking-order scale for overlay-class UI (dropdowns, headers, dialogs, toasts), shared by every theme.
  *
  * @example
  * ```css
@@ -63,8 +38,7 @@ export declare const zIndex: {
 /** The shape of the {@link zIndex} scale — a map of named stacking layers (`sticky`, `overlay`, `popover`, `toast`, …) to their numeric `z-index`. @public */
 export type ZIndexScale = typeof zIndex;
 /**
- * Structural focus-ring geometry (width/offset). The ring's *color* is themed
- * per brand ({@link SemanticColors.focusRing}); thickness/offset are shared.
+ * Structural focus-ring geometry (width/offset); color is themed separately via {@link SemanticColors.focusRing}.
  *
  * @example
  * ```css
@@ -79,18 +53,13 @@ export type ZIndexScale = typeof zIndex;
 export declare const focusRing: {
     readonly width: "2px";
     readonly offset: "2px";
-    /**
-     * Offset for clipping containers; moves ring inside border-box so overflow
-     * doesn't clip. Negative ring width, flush inside edge.
-     */
+    /** Offset for clipping containers: moves the ring inside the border-box so overflow doesn't clip it. */
     readonly offsetInset: "calc(-1 * var(--skdx-focus-ring-width))";
 };
 /** The shape of the {@link focusRing} geometry — the structural `width`/`offset` of the focus ring (its color is themed separately). @public */
 export type FocusRingScale = typeof focusRing;
 /**
- * Border thicknesses, structural like {@link focusRing}: a brand changes
- * border *color* ({@link SemanticColors.border}), not hairline width. No `0`
- * step — that's `border: none`, not a token.
+ * Border thicknesses, structural like {@link focusRing}: brand changes border color via {@link SemanticColors.border}, not width; no `0` step exists.
  *
  * @example
  * ```css
@@ -107,14 +76,7 @@ export declare const borderWidth: {
 };
 /** The shape of the {@link borderWidth} scale — `thin`/`thick`/`thicker` border thicknesses. @public */
 export type BorderWidthScale = typeof borderWidth;
-/**
- * The shared control geometry — heights, paddings, icon boxes, row heights
- * and overlay insets. See {@link ThemeControls} for why this is structural
- * rather than per-brand, and for the retuning escape hatch. Values are
- * `var()` references where they equal a {@link space} step, so the two can't
- * drift; the few off-scale exceptions are documented where declared.
- * @public
- */
+/** The shared control geometry (heights, paddings, icon boxes, insets); see {@link ThemeControls} for the retuning escape hatch, and values reference {@link space} steps where they align. @public */
 export declare const controls: ThemeControls;
 /**
  * What a coarse pointer overrides, emitted as a `@media (pointer: coarse)`
@@ -124,9 +86,7 @@ export declare const controls: ThemeControls;
  */
 export declare const controlsCoarse: ThemeControlsCoarse;
 /**
- * The two opacities the system has an opinion about — disabled fade and
- * modal scrim dim — not an arbitrary 0–100 ramp. Scrim *color* is themed
- * ({@link SemanticColors.overlay}); this is the structural dim strength.
+ * The two intentional opacities — disabled fade and modal scrim dim — not an arbitrary ramp; scrim color is themed via {@link SemanticColors.overlay}.
  *
  * @example
  * ```css
@@ -143,9 +103,7 @@ export declare const opacity: {
 /** The shape of the {@link opacity} scale — the `disabled` and `scrim` opacities. @public */
 export type OpacityScale = typeof opacity;
 /**
- * Viewport widths, in pixels, as **TypeScript exports only** — not emitted as
- * CSS custom properties, since `@media (min-width: var(--x))` is invalid CSS.
- * Consume from JS/TS or inline into your own media queries.
+ * Viewport widths in pixels, as TypeScript exports only — `@media (min-width: var(--x))` is invalid CSS.
  *
  * @example
  * ```ts
@@ -165,32 +123,17 @@ export declare const breakpoints: {
 /** The shape of the {@link breakpoints} scale — named viewport widths in pixels. @public */
 export type BreakpointScale = typeof breakpoints;
 /**
- * Flattens every shared token into a map of CSS custom property names to
- * values — the foundation's counterpart to `themeToCssVars`. Together they
- * are the complete `--skdx-*` surface, and never overlap. {@link breakpoints}
- * is excluded, since a breakpoint can't be a CSS custom property.
+ * Flattens every shared token into `--skdx-*` custom property values, the foundation's counterpart to `themeToCssVars`; excludes {@link breakpoints}, which can't be a CSS custom property.
  *
  * @returns A plain object keyed by CSS custom property name (e.g. `'--skdx-space-4'`), unprefixed by any selector.
  * @public
  */
-export declare function foundationToCssVars(): Record<string, string>;
+export declare function foundationToCssVars(): Record<CssVar, string>;
+/** The control metrics a coarse pointer overrides, as a var map — the `@media (pointer: coarse)` counterpart to {@link foundationToCssVars}. @public */
+export declare function coarsePointerToCssVars(): Record<CssVar, string>;
 /**
- * The control metrics a coarse pointer overrides, as a var map — the
- * `@media (pointer: coarse)` counterpart to {@link foundationToCssVars}.
- * Exported so `@skdx/skins` can render its fallback copy from these
- * functions instead of restating the values.
- * @public
- */
-export declare function coarsePointerToCssVars(): Record<string, string>;
-/**
- * Renders every shared token as a `:root`-scoped `--skdx-*` rule block — the
- * theme-invariant counterpart to {@link themeToCss}. **Inject this exactly
- * once**, then `themeToCss(theme)` per theme alongside it.
- *
- * Also emits a `@media (prefers-reduced-motion: reduce)` block zeroing every
- * motion duration/stagger at the definition site (WCAG 2.3.3 for free at every
- * call site, no per-consumer media query), and a `@media (pointer: coarse)`
- * block re-declaring the hit sizes from {@link controlsCoarse} the same way.
+ * Renders every shared token as a `:root`-scoped `--skdx-*` rule block, plus `prefers-reduced-motion` and `pointer: coarse` override blocks.
+ * Inject this exactly once, then {@link themeToCss} per theme.
  *
  * @example
  * ```ts

package/dist/utils/foundation.js

@@ -1,4 +1,4 @@
-import{reducedMotionVarNames as m,sectionsToCssVars as a,varsToDeclarations as s}from"./cssVars.js";import{defaultMotion as p}from"./theme.js";var e="skdx",c={fontFamily:"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",fontFamilyMono:"'SF Mono', SFMono-Regular, ui-monospace, Menlo, Consolas, monospace",fontSize:{xs:"0.75rem",sm:"0.875rem",md:"1rem",lg:"1.125rem",xl:"1.25rem","2xl":"1.5rem","3xl":"1.875rem"},fontWeight:{regular:400,medium:500,semibold:600,bold:700},lineHeight:{tight:"1.25",snug:"1.43",normal:"1.5",relaxed:"1.75"},letterSpacing:{tight:"-0.015em",normal:"0em",wide:"0.025em",wider:"0.05em"}},d={1:"0.25rem",2:"0.5rem",3:"0.75rem",4:"1rem",5:"1.25rem",6:"1.5rem",8:"2rem",10:"2.5rem",12:"3rem",16:"4rem"},l={sm:"0.25rem",inner:"0.375rem",md:"0.5rem",lg:"0.75rem",xl:"1rem",full:"9999px"},g={sm:`0 1px 2px 0 ${n(.05)}`,md:`0 4px 6px -1px ${n(.1)}, 0 2px 4px -2px ${n(.1)}`,lg:`0 10px 15px -3px ${n(.1)}, 0 4px 6px -4px ${n(.1)}`,overlay:`0 25px 50px -12px ${n(.25)}`};function n(r){return`rgb(var(--${e}-shadow-color) / calc(${r} * var(--${e}-shadow-strength)))`}var x=p,u={base:0,dropdown:10,sticky:20,overlay:30,modal:35,popover:40,toast:50,max:9999},h={width:"2px",offset:"2px",offsetInset:"calc(-1 * var(--skdx-focus-ring-width))"},y={thin:"1px",thick:"2px",thicker:"4px"},f={control:{height:{sm:"1.875rem",md:"2.25rem",lg:"2.625rem",compact:"2rem"},padding:{sm:"0.625rem",md:`var(--${e}-space-3)`,lg:`var(--${e}-space-4)`},gap:{sm:`var(--${e}-space-1)`,md:`var(--${e}-space-2)`,lg:`var(--${e}-space-2)`}},iconSize:{sm:"1rem",md:"1.25rem",lg:"1.5rem"},indicatorSize:{sm:"1rem",md:"1.25rem",lg:"1.5rem"},item:{height:{sm:"1.75rem",md:"2.25rem",lg:"2.5rem"},gap:"2px"},overlay:{padding:`var(--${e}-space-1)`,radius:`var(--${e}-radius-lg)`,minWidth:"7.5rem"},field:{gap:`var(--${e}-space-1)`,labelGap:`var(--${e}-space-1)`},target:{min:"24px"}},w={control:{height:{sm:"2.25rem",md:"2.75rem",lg:"3rem",compact:"2.75rem"}},item:{height:{sm:"2.25rem",md:"2.75rem",lg:"3rem"}},target:{min:"44px"}},k={disabled:"0.5",scrim:"0.6"},v={sm:640,md:768,lg:1024,xl:1280};function T(){return a([["font",c],["space",d],["radius",l],["shadow",g],["motion",x],["z-index",u],["focus-ring",h],["border-width",y],["opacity",k],...i(f)])}function i(r){let o=t=>r[t];return[["control",o("control")],["icon-size",o("iconSize")],["indicator-size",o("indicatorSize")],["item",o("item")],["overlay",o("overlay")],["field",o("field")],["target",o("target")]]}function R(){return a(i(w))}function C(){let r=T(),o=m(r).map(t=>`    ${t}: 0ms;`);return`:root {
+import{PREFIX as e,reducedMotionVarNames as i,sectionsToCssVars as a,varsToDeclarations as s}from"./cssVars.js";import{defaultMotion as p}from"./theme.js";var c={fontFamily:"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",fontFamilyMono:"'SF Mono', SFMono-Regular, ui-monospace, Menlo, Consolas, monospace",fontSize:{xs:"0.75rem",sm:"0.875rem",md:"1rem",lg:"1.125rem",xl:"1.25rem","2xl":"1.5rem","3xl":"1.875rem"},fontWeight:{regular:400,medium:500,semibold:600,bold:700},lineHeight:{tight:"1.25",snug:"1.43",normal:"1.5",relaxed:"1.75"},letterSpacing:{tight:"-0.015em",normal:"0em",wide:"0.025em",wider:"0.05em"}},d={1:"0.25rem",2:"0.5rem",3:"0.75rem",4:"1rem",5:"1.25rem",6:"1.5rem",8:"2rem",10:"2.5rem",12:"3rem",16:"4rem"},l={sm:"0.25rem",inner:"0.375rem",md:"0.5rem",lg:"0.75rem",xl:"1rem",full:"9999px"},x={sm:`0 1px 2px 0 ${t(.05)}`,md:`0 4px 6px -1px ${t(.1)}, 0 2px 4px -2px ${t(.1)}`,lg:`0 10px 15px -3px ${t(.1)}, 0 4px 6px -4px ${t(.1)}`,overlay:`0 25px 50px -12px ${t(.25)}`};function t(r){return`rgb(var(--${e}-shadow-color) / calc(${r} * var(--${e}-shadow-strength)))`}var g=p,h={base:0,dropdown:10,sticky:20,overlay:30,modal:35,popover:40,toast:50,max:9999},y={width:"2px",offset:"2px",offsetInset:"calc(-1 * var(--skdx-focus-ring-width))"},f={thin:"1px",thick:"2px",thicker:"4px"},u={control:{height:{sm:"1.875rem",md:"2.25rem",lg:"2.625rem",compact:"2rem"},padding:{sm:"0.625rem",md:`var(--${e}-space-3)`,lg:`var(--${e}-space-4)`},gap:{sm:`var(--${e}-space-1)`,md:`var(--${e}-space-2)`,lg:`var(--${e}-space-2)`}},iconSize:{sm:"1rem",md:"1.25rem",lg:"1.5rem"},indicatorSize:{sm:"1rem",md:"1.25rem",lg:"1.5rem"},item:{height:{sm:"1.75rem",md:"2.25rem",lg:"2.5rem"},gap:"2px"},overlay:{padding:`var(--${e}-space-1)`,radius:`var(--${e}-radius-lg)`,minWidth:"7.5rem"},field:{gap:`var(--${e}-space-1)`,labelGap:`var(--${e}-space-1)`},target:{min:"24px"}},T={control:{height:{sm:"2.25rem",md:"2.75rem",lg:"3rem",compact:"2.75rem"}},item:{height:{sm:"2.25rem",md:"2.75rem",lg:"3rem"}},target:{min:"44px"}},C={disabled:"0.5",scrim:"0.6"},w={sm:640,md:768,lg:1024,xl:1280};function S(){return a([["font",c],["space",d],["radius",l],["shadow",x],["motion",g],["z-index",h],["focus-ring",y],["border-width",f],["opacity",C],...m(u)])}function m(r){let o=n=>r[n];return[["control",o("control")],["icon-size",o("iconSize")],["indicator-size",o("indicatorSize")],["item",o("item")],["overlay",o("overlay")],["field",o("field")],["target",o("target")]]}function $(){return a(m(T))}function R(){let r=S(),o=i(r).map(n=>`    ${n}: 0ms;`);return`:root {
 ${s(r)}
 }
 @media (prefers-reduced-motion: reduce) {
@@ -9,7 +9,7 @@ ${o.join(`
 }
 @media (pointer: coarse) {
   :root {
-${s(R(),"    ")}
+${s($(),"    ")}
   }
 }
-`}export{y as borderWidth,v as breakpoints,R as coarsePointerToCssVars,f as controls,w as controlsCoarse,h as focusRing,C as foundationToCss,T as foundationToCssVars,x as motion,k as opacity,l as radii,g as shadows,d as space,c as typography,u as zIndex};
+`}export{f as borderWidth,w as breakpoints,$ as coarsePointerToCssVars,u as controls,T as controlsCoarse,y as focusRing,R as foundationToCss,S as foundationToCssVars,g as motion,C as opacity,l as radii,x as shadows,d as space,c as typography,h as zIndex};

package/dist/utils/mode.cjs

@@ -1 +1 @@
-"use strict";var d=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var S=Object.getOwnPropertyNames;var b=Object.prototype.hasOwnProperty;var O=(t,e)=>{for(var n in e)d(t,n,{get:e[n],enumerable:!0})},k=(t,e,n,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of S(e))!b.call(t,r)&&r!==n&&d(t,r,{get:()=>e[r],enumerable:!(o=u(e,r))||o.enumerable});return t};var E=t=>k(d({},"__esModule",{value:!0}),t);var M={};O(M,{BRAND_STORAGE_KEY:()=>g,MODE_STORAGE_KEY:()=>c,getThemeInitScript:()=>x,watchSystemMode:()=>v});module.exports=E(M);var a=require("../themes/brands.cjs"),f=require("./toCss.cjs"),c="skdx-mode",g="skdx-brand",y="(prefers-color-scheme: dark)";function v(t={}){let{brand:e,element:n,persist:o=!1,storageKey:r=c}=t,s=(e===void 0?void 0:(0,a.getBrand)(e))??a.defaultBrand,i=window.matchMedia(y),h=m=>{let p=m?"dark":"light";if((0,f.applyTheme)(s.themes[p],n),!!o)try{localStorage.setItem(r,p)}catch{}};h(i.matches);let l=m=>h(m.matches);return i.addEventListener("change",l),()=>i.removeEventListener("change",l)}function x(t={}){let{brandKey:e=g,modeKey:n=c,fallbackBrand:o=a.defaultBrand.name}=t,r=Object.fromEntries(a.brands.map(s=>[s.name,[s.themes.light.name,s.themes.dark.name]]));return`(function(){try{var t=${JSON.stringify(r)},f=${JSON.stringify(o)};var b=localStorage.getItem(${JSON.stringify(e)})||f;var m=localStorage.getItem(${JSON.stringify(n)});if(m!=="light"&&m!=="dark")m=matchMedia(${JSON.stringify(y)}).matches?"dark":"light";var p=t[b]||t[f];if(!p)return;var e=document.documentElement;e.setAttribute("data-skdx-theme",p[m==="dark"?1:0]);e.setAttribute("data-skdx-mode",m);}catch(e){}})();`}0&&(module.exports={BRAND_STORAGE_KEY,MODE_STORAGE_KEY,getThemeInitScript,watchSystemMode});
+"use strict";var l=Object.defineProperty;var O=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var k=Object.prototype.hasOwnProperty;var v=(t,e)=>{for(var n in e)l(t,n,{get:e[n],enumerable:!0})},x=(t,e,n,a)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of E(e))!k.call(t,r)&&r!==n&&l(t,r,{get:()=>e[r],enumerable:!(a=O(e,r))||a.enumerable});return t};var M=t=>x(l({},"__esModule",{value:!0}),t);var I={};v(I,{BRAND_STORAGE_KEY:()=>S,MODE_STORAGE_KEY:()=>h,getThemeInitScript:()=>K,watchSystemMode:()=>T});module.exports=M(I);var o=require("../themes/brands.cjs"),y=require("./toCss.cjs"),h="skdx-mode",S="skdx-brand",b="(prefers-color-scheme: dark)";function T(t={}){let{brand:e,element:n,persist:a=!1,storageKey:r=h}=t,i=(e===void 0?void 0:(0,o.getBrand)(e))??o.defaultBrand,d=window.matchMedia(b),g,p=m=>{let s=null;try{s=localStorage.getItem(r)}catch{}let u=s==="light"||s==="dark"?s:void 0,c=(u!==g?u:void 0)??(m?"dark":"light");if((0,y.applyTheme)(i.themes[c],n),!!a)try{localStorage.setItem(r,c),g=c}catch{}};p(d.matches);let f=m=>p(m.matches);return d.addEventListener("change",f),()=>d.removeEventListener("change",f)}function K(t={}){let{brandKey:e=S,modeKey:n=h,brand:a=o.defaultBrand.name}=t,r=Object.fromEntries(o.brands.map(i=>[i.name,[i.themes.light.name,i.themes.dark.name]]));return`(function(){try{var t=${JSON.stringify(r)},f=${JSON.stringify(a)};var b=localStorage.getItem(${JSON.stringify(e)})||f;var m=localStorage.getItem(${JSON.stringify(n)});if(m!=="light"&&m!=="dark")m=matchMedia(${JSON.stringify(b)}).matches?"dark":"light";var p=t[b]||t[f];if(!p)return;var e=document.documentElement;e.setAttribute("data-skdx-theme",p[m==="dark"?1:0]);e.setAttribute("data-skdx-mode",m);}catch(e){}})();`}0&&(module.exports={BRAND_STORAGE_KEY,MODE_STORAGE_KEY,getThemeInitScript,watchSystemMode});

package/dist/utils/mode.d.cts

@@ -14,9 +14,9 @@ export interface WatchSystemModeOptions {
     storageKey?: string;
 }
 /**
- * Follow OS color-scheme: apply theme, re-apply on preference change (runtime half
- * of "mode: system"). Browser-only; guard behind mounted effect in SSR.
- * Pair with {@link getThemeInitScript} so first paint matches.
+ * Follows OS color-scheme, applying and re-applying the theme on change; browser-only, guard behind a mounted effect in SSR.
+ * Pair with {@link getThemeInitScript} so first paint matches. A persisted explicit `'light'`/`'dark'` under
+ * `storageKey` takes precedence over the OS preference until a `'system'` value is stored again.
  *
  * @returns Unsubscribe function (detaches listener).
  * @example
@@ -26,27 +26,6 @@ export interface WatchSystemModeOptions {
  * stop();
  * ```
  * @public
- *
- * @example Next.js (App Router, `app/layout.tsx`)
- * ```tsx
- * <head>
- *   <script dangerouslySetInnerHTML={{ __html: getThemeInitScript() }} />
- * </head>
- * ```
- *
- * @example Nuxt (`nuxt.config.ts`)
- * ```ts
- * app: { head: { script: [{ innerHTML: getThemeInitScript(), tagPosition: 'head' }] } }
- * ```
- *
- * @example SvelteKit (`src/app.html`) — write the string into the template at
- * build time, e.g. from a Vite plugin replacing a `%skdx.themeInit%` token:
- * ```html
- * <head>
- *   %sveltekit.head%
- *   <script>%skdx.themeInit%</script>
- * </head>
- * ```
  */
 export declare function watchSystemMode(options?: WatchSystemModeOptions): () => void;
 /** Options for {@link getThemeInitScript}. @public */
@@ -55,23 +34,17 @@ export interface ThemeInitScriptOptions {
     brandKey?: string;
     /** `localStorage` key for mode. @default MODE_STORAGE_KEY */
     modeKey?: string;
-    /** Fallback brand when nothing persisted or unknown. @default 'skanda' */
-    fallbackBrand?: string;
+    /** Brand to fall back to when nothing is persisted or the persisted name is unknown. @default 'skanda' */
+    brand?: string;
 }
 /**
- * Blocking snippet that stamps `data-skdx-theme` and `data-skdx-mode` on
- * `<html>` before first paint (prevents dark-mode flash). Resolves `'system'`
- * through `prefers-color-scheme`. Returns bare JS (no `<script>` wrapper);
- * your CSS must have `[data-skdx-theme="…"]` blocks.
+ * Blocking snippet that stamps `data-skdx-theme`/`-mode` on `<html>` before first paint, resolving `'system'` via `prefers-color-scheme`.
+ * Returns bare JS (no `<script>` wrapper); your CSS needs `[data-skdx-theme="…"]` blocks.
  *
  * @example Next.js
  * ```tsx
  * <script dangerouslySetInnerHTML={{ __html: getThemeInitScript() }} />
  * ```
- * @example Astro
- * ```astro
- * <script is:inline set:html={getThemeInitScript()} />
- * ```
  * @public
  */
 export declare function getThemeInitScript(options?: ThemeInitScriptOptions): string;

package/dist/utils/mode.d.ts

@@ -14,9 +14,9 @@ export interface WatchSystemModeOptions {
     storageKey?: string;
 }
 /**
- * Follow OS color-scheme: apply theme, re-apply on preference change (runtime half
- * of "mode: system"). Browser-only; guard behind mounted effect in SSR.
- * Pair with {@link getThemeInitScript} so first paint matches.
+ * Follows OS color-scheme, applying and re-applying the theme on change; browser-only, guard behind a mounted effect in SSR.
+ * Pair with {@link getThemeInitScript} so first paint matches. A persisted explicit `'light'`/`'dark'` under
+ * `storageKey` takes precedence over the OS preference until a `'system'` value is stored again.
  *
  * @returns Unsubscribe function (detaches listener).
  * @example
@@ -26,27 +26,6 @@ export interface WatchSystemModeOptions {
  * stop();
  * ```
  * @public
- *
- * @example Next.js (App Router, `app/layout.tsx`)
- * ```tsx
- * <head>
- *   <script dangerouslySetInnerHTML={{ __html: getThemeInitScript() }} />
- * </head>
- * ```
- *
- * @example Nuxt (`nuxt.config.ts`)
- * ```ts
- * app: { head: { script: [{ innerHTML: getThemeInitScript(), tagPosition: 'head' }] } }
- * ```
- *
- * @example SvelteKit (`src/app.html`) — write the string into the template at
- * build time, e.g. from a Vite plugin replacing a `%skdx.themeInit%` token:
- * ```html
- * <head>
- *   %sveltekit.head%
- *   <script>%skdx.themeInit%</script>
- * </head>
- * ```
  */
 export declare function watchSystemMode(options?: WatchSystemModeOptions): () => void;
 /** Options for {@link getThemeInitScript}. @public */
@@ -55,23 +34,17 @@ export interface ThemeInitScriptOptions {
     brandKey?: string;
     /** `localStorage` key for mode. @default MODE_STORAGE_KEY */
     modeKey?: string;
-    /** Fallback brand when nothing persisted or unknown. @default 'skanda' */
-    fallbackBrand?: string;
+    /** Brand to fall back to when nothing is persisted or the persisted name is unknown. @default 'skanda' */
+    brand?: string;
 }
 /**
- * Blocking snippet that stamps `data-skdx-theme` and `data-skdx-mode` on
- * `<html>` before first paint (prevents dark-mode flash). Resolves `'system'`
- * through `prefers-color-scheme`. Returns bare JS (no `<script>` wrapper);
- * your CSS must have `[data-skdx-theme="…"]` blocks.
+ * Blocking snippet that stamps `data-skdx-theme`/`-mode` on `<html>` before first paint, resolving `'system'` via `prefers-color-scheme`.
+ * Returns bare JS (no `<script>` wrapper); your CSS needs `[data-skdx-theme="…"]` blocks.
  *
  * @example Next.js
  * ```tsx
  * <script dangerouslySetInnerHTML={{ __html: getThemeInitScript() }} />
  * ```
- * @example Astro
- * ```astro
- * <script is:inline set:html={getThemeInitScript()} />
- * ```
  * @public
  */
 export declare function getThemeInitScript(options?: ThemeInitScriptOptions): string;

package/dist/utils/mode.js

@@ -1 +1 @@
-import{brands as f,defaultBrand as h,getBrand as g}from"../themes/brands.js";import{applyTheme as y}from"./toCss.js";var l="skdx-mode",u="skdx-brand",p="(prefers-color-scheme: dark)";function O(r={}){let{brand:t,element:n,persist:a=!1,storageKey:o=l}=r,e=(t===void 0?void 0:g(t))??h,s=window.matchMedia(p),m=i=>{let c=i?"dark":"light";if(y(e.themes[c],n),!!a)try{localStorage.setItem(o,c)}catch{}};m(s.matches);let d=i=>m(i.matches);return s.addEventListener("change",d),()=>s.removeEventListener("change",d)}function k(r={}){let{brandKey:t=u,modeKey:n=l,fallbackBrand:a=h.name}=r,o=Object.fromEntries(f.map(e=>[e.name,[e.themes.light.name,e.themes.dark.name]]));return`(function(){try{var t=${JSON.stringify(o)},f=${JSON.stringify(a)};var b=localStorage.getItem(${JSON.stringify(t)})||f;var m=localStorage.getItem(${JSON.stringify(n)});if(m!=="light"&&m!=="dark")m=matchMedia(${JSON.stringify(p)}).matches?"dark":"light";var p=t[b]||t[f];if(!p)return;var e=document.documentElement;e.setAttribute("data-skdx-theme",p[m==="dark"?1:0]);e.setAttribute("data-skdx-mode",m);}catch(e){}})();`}export{u as BRAND_STORAGE_KEY,l as MODE_STORAGE_KEY,k as getThemeInitScript,O as watchSystemMode};
+import{brands as y,defaultBrand as p,getBrand as S}from"../themes/brands.js";import{applyTheme as b}from"./toCss.js";var f="skdx-mode",O="skdx-brand",u="(prefers-color-scheme: dark)";function x(o={}){let{brand:t,element:a,persist:i=!1,storageKey:r=f}=o,e=(t===void 0?void 0:S(t))??p,s=window.matchMedia(u),c,l=d=>{let n=null;try{n=localStorage.getItem(r)}catch{}let g=n==="light"||n==="dark"?n:void 0,m=(g!==c?g:void 0)??(d?"dark":"light");if(b(e.themes[m],a),!!i)try{localStorage.setItem(r,m),c=m}catch{}};l(s.matches);let h=d=>l(d.matches);return s.addEventListener("change",h),()=>s.removeEventListener("change",h)}function M(o={}){let{brandKey:t=O,modeKey:a=f,brand:i=p.name}=o,r=Object.fromEntries(y.map(e=>[e.name,[e.themes.light.name,e.themes.dark.name]]));return`(function(){try{var t=${JSON.stringify(r)},f=${JSON.stringify(i)};var b=localStorage.getItem(${JSON.stringify(t)})||f;var m=localStorage.getItem(${JSON.stringify(a)});if(m!=="light"&&m!=="dark")m=matchMedia(${JSON.stringify(u)}).matches?"dark":"light";var p=t[b]||t[f];if(!p)return;var e=document.documentElement;e.setAttribute("data-skdx-theme",p[m==="dark"?1:0]);e.setAttribute("data-skdx-mode",m);}catch(e){}})();`}export{O as BRAND_STORAGE_KEY,f as MODE_STORAGE_KEY,M as getThemeInitScript,x as watchSystemMode};

package/dist/utils/theme.cjs

@@ -1 +1 @@
-"use strict";var n=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var o=Object.getOwnPropertyNames;var a=Object.prototype.hasOwnProperty;var m=(r,t)=>{for(var e in t)n(r,e,{get:t[e],enumerable:!0})},l=(r,t,e,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of o(t))!a.call(r,i)&&i!==e&&n(r,i,{get:()=>t[i],enumerable:!(s=g(t,i))||s.enumerable});return r};var d=r=>l(n({},"__esModule",{value:!0}),r);var c={};m(c,{defaultMotion:()=>h});module.exports=d(c);var h={durationInstant:"0ms",durationFast:"100ms",durationNormal:"200ms",durationSlow:"300ms",easing:"cubic-bezier(0.16, 1, 0.3, 1)",easingExit:"cubic-bezier(0.4, 0, 1, 1)",easingSteady:"cubic-bezier(0.4, 0, 0.2, 1)",easingLinear:"linear",staggerTight:"4ms",staggerLoose:"40ms"};0&&(module.exports={defaultMotion});
+"use strict";var e=Object.defineProperty;var g=Object.getOwnPropertyDescriptor;var o=Object.getOwnPropertyNames;var a=Object.prototype.hasOwnProperty;var m=(r,t)=>{for(var n in t)e(r,n,{get:t[n],enumerable:!0})},l=(r,t,n,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let i of o(t))!a.call(r,i)&&i!==n&&e(r,i,{get:()=>t[i],enumerable:!(s=g(t,i))||s.enumerable});return r};var d=r=>l(e({},"__esModule",{value:!0}),r);var h={};m(h,{defaultMotion:()=>c});module.exports=d(h);var c={durationInstant:"0ms",durationFast:"100ms",durationNormal:"200ms",durationSlow:"300ms",easing:"cubic-bezier(0.16, 1, 0.3, 1)",easingExit:"cubic-bezier(0.4, 0, 1, 1)",easingSteady:"cubic-bezier(0.4, 0, 0.2, 1)",easingLinear:"linear",staggerTight:"4ms",staggerLoose:"40ms"};0&&(module.exports={defaultMotion});

package/dist/utils/theme.d.cts

@@ -1,6 +1,3 @@
-/**
- * A theme is a plain JSON-serializable object; `themeToCss()` turns it into CSS custom properties.
- */
 /**
  * The two resolved color modes a theme renders in (resolved via `prefers-color-scheme`).
  * @public
@@ -64,11 +61,7 @@ export interface ThemeColors {
     /** Role-based colors from scales; components prefer these over raw steps. */
     semantic: SemanticColors;
 }
-/**
- * Font stacks, type scale, weight/line-height tokens, rendered as `--skdx-font-*`.
- * Theme-invariant except the two font stacks (see {@link ThemeTypographyDeviation}).
- * @public
- */
+/** Font stacks, type scale, weight/line-height tokens, rendered as `--skdx-font-*`; theme-invariant except the two font stacks (see {@link ThemeTypographyDeviation}). @public */
 export interface ThemeTypography {
     /** Body font stack. */
     fontFamily: string;
@@ -106,10 +99,7 @@ export interface ThemeTypography {
         wider: string;
     };
 }
-/**
- * Spacing scale (margin, padding, gap), rendered as `--skdx-space-<step>`.
- * Lives once in `foundation.ts` (see {@link space}). @public
- */
+/** Spacing scale (margin, padding, gap), rendered as `--skdx-space-<step>`; lives once in `foundation.ts` (see {@link space}). @public */
 export interface ThemeSpace {
     '1': string;
     '2': string;
@@ -122,10 +112,7 @@ export interface ThemeSpace {
     '12': string;
     '16': string;
 }
-/**
- * Border-radius scale, rendered as `--skdx-radius-<size>`.
- * Lives once in `foundation.ts` (see {@link radii}). @public
- */
+/** Border-radius scale, rendered as `--skdx-radius-<size>`; lives once in `foundation.ts` (see {@link radii}). @public */
 export interface ThemeRadii {
     sm: string;
     /** Nested box radius (relationship between `sm` and `md`, not a size step). */
@@ -136,10 +123,7 @@ export interface ThemeRadii {
     /** Fully round, for pills and circular avatars. */
     full: string;
 }
-/**
- * Control geometry: metrics Button, Input and Select snap to.
- * Lives once in `foundation.ts` (see {@link controls}). @public
- */
+/** Control geometry: metrics Button, Input and Select snap to, living once in `foundation.ts` (see {@link controls}). @public */
 export interface ThemeControls {
     /** Vertical rhythm, inline padding and icon gap. */
     control: {
@@ -198,10 +182,7 @@ export interface ThemeControls {
         min: string;
     };
 }
-/**
- * {@link ThemeControls} overrides for coarse pointers. Only hit-target sizes;
- * padding, gaps, radii, icons unchanged. @public
- */
+/** {@link ThemeControls} overrides for coarse pointers — only hit-target sizes; padding, gaps, radii, icons unchanged. @public */
 export interface ThemeControlsCoarse {
     control: {
         height: {
@@ -222,11 +203,7 @@ export interface ThemeControlsCoarse {
         min: string;
     };
 }
-/**
- * Box-shadow scale, rendered as `--skdx-shadow-<size>`. Geometry lives once
- * in `foundation.ts` (see {@link shadows}); color defers to {@link ThemeShadowColor}.
- * @public
- */
+/** Box-shadow scale, rendered as `--skdx-shadow-<size>`; geometry lives once in `foundation.ts` (see {@link shadows}), color defers to {@link ThemeShadowColor}. @public */
 export interface ThemeShadows {
     sm: string;
     md: string;
@@ -234,40 +211,20 @@ export interface ThemeShadows {
     /** Elevated overlay surfaces (dialogs, popovers, dropdowns). */
     overlay: string;
 }
-/**
- * Shadow color: the only part of {@link shadows} a theme owns;
- * geometry lives in the base.  @public
- */
+/** Shadow color: the only part of {@link shadows} a theme owns; geometry lives in the base. @public */
 export interface ThemeShadowColor {
     /** sRGB channels (e.g. `'2 6 23'`), substituted into `rgb(<color> / <alpha>)`. */
     color: string;
-    /**
-     * Multiplier for base alphas in {@link shadows}. `'1'` for light themes;
-     * dark themes ~`'5'` (shadow must work on dark surface).
-     */
+    /** Multiplier for base alphas in {@link shadows}: `'1'` for light themes, ~`'5'` for dark. */
     strength: string;
 }
-/**
- * Font stacks a theme may override (only part of {@link typography} not fixed).
- * Only `fluent` and `material-you` declare it. @public
- */
+/** Font stacks a theme may override — the only part of {@link typography} not fixed; only `fluent` and `material-you` declare it. @public */
 export type ThemeTypographyDeviation = Partial<Pick<ThemeTypography, 'fontFamily' | 'fontFamilyMono'>>;
-/**
- * Motion tokens a theme may retune. Optional ones (exit, staggers) stay uniform.
- * Only `material-you`, `fluent` and `ant-daybreak` declare. @public
- */
+/** Motion tokens a theme may retune; only `material-you`, `fluent` and `ant-daybreak` declare. @public */
 export type ThemeMotionDeviation = Partial<Pick<ThemeMotion, 'durationFast' | 'durationNormal' | 'durationSlow' | 'easing'>>;
-/**
- * Animation durations, easing curves, and staggers rendered as `--skdx-motion-*`.
- * Theme-invariant by default (timing shift reads as bug, affects vestibular users).
- * Lives once in `foundation.ts` (see {@link motion}). `materialBrand`, `antBrand`,
- * `fluentBrand` retune via {@link ThemeMotionDeviation}. @public
- */
+/** Animation durations, easing curves, and staggers rendered as `--skdx-motion-*`; theme-invariant by default, lives once in `foundation.ts` (see {@link motion}). @public */
 export interface ThemeMotion {
-    /**
-     * Zero for state changes that feel like data, not animation (value updates).
-     * @default '0ms'
-     */
+    /** Zero for state changes that feel like data, not animation (value updates). @default '0ms' */
     durationInstant?: string;
     /** Hover/focus/press micro-interactions (direct manipulation). */
     durationFast: string;
@@ -277,43 +234,20 @@ export interface ThemeMotion {
     durationSlow: string;
     /** Default curve: fast start, soft landing (for entering/opening). */
     easing: string;
-    /**
-     * Mirror of {@link ThemeMotion.easing} (slow start, accelerates). For exits.
-     * @default 'cubic-bezier(0.4, 0, 1, 1)'
-     */
+    /** Mirror of {@link ThemeMotion.easing} (slow start, accelerates), for exits. @default 'cubic-bezier(0.4, 0, 1, 1)' */
     easingExit?: string;
-    /**
-     * Symmetric ease-in-out, no overshoot (in-place: color swaps, toggles).
-     * @default 'cubic-bezier(0.4, 0, 0.2, 1)'
-     */
+    /** Symmetric ease-in-out, no overshoot (in-place: color swaps, toggles). @default 'cubic-bezier(0.4, 0, 0.2, 1)' */
     easingSteady?: string;
-    /**
-     * Constant rate (indeterminate loops: spinner, shimmer).
-     * @default 'linear'
-     */
+    /** Constant rate for indeterminate loops (spinner, shimmer). @default 'linear' */
     easingLinear?: string;
-    /**
-     * Per-item sweep delay (reads as one gesture for large/unbounded lists).
-     * @default '4ms'
-     */
+    /** Per-item sweep delay, reads as one gesture for large/unbounded lists. @default '4ms' */
     staggerTight?: string;
-    /**
-     * Per-item sequence delay (distinct arrival, short/bounded lists only).
-     * @default '40ms'
-     */
+    /** Per-item sequence delay, for distinct arrival on short/bounded lists only. @default '40ms' */
     staggerLoose?: string;
 }
-/**
- * Default motion values; merged under a theme's `motion` so every theme
- * emits the complete `--skdx-motion-*` surface.
- */
+/** Default motion values, merged under a theme's `motion` so every theme emits the complete `--skdx-motion-*` surface. */
 export declare const defaultMotion: Required<ThemeMotion>;
-/**
- * Complete theme object flowing through {@link createTheme}, {@link themeToCss},
- * and {@link applyTheme}. Contains only colors; type scale, spacing, radii,
- * shadow, motion are theme-invariant (see `foundation.ts`). `typography` and
- * `motion` are escape hatches for impersonating design languages. @public
- */
+/** Complete theme object flowing through {@link createTheme}, {@link themeToCss} and {@link applyTheme}; contains only colors, since the rest is theme-invariant (see `foundation.ts`). @public */
 export interface Theme {
     /** Unique theme name (e.g. `"skanda-light"`), used as `[data-skdx-theme="..."]` selector. */
     name: string;
@@ -328,8 +262,7 @@ export interface Theme {
     motion?: ThemeMotionDeviation;
 }
 /**
- * Partial {@link Theme} describing only what a brand changes. Passed to
- * {@link createTheme}, which deep-merges onto a base theme.
+ * Partial {@link Theme} describing only what a brand changes, passed to {@link createTheme} which deep-merges it onto a base theme.
  * @example
  * ```ts
  * const override: ThemeOverride = {
@@ -339,8 +272,8 @@ export interface Theme {
  * ```
  * @public
  */
-export type ThemeOverride = {
-    [K in keyof Theme]?: Theme[K] extends object ? {
-        [K2 in keyof Theme[K]]?: Theme[K][K2] extends object ? Partial<Theme[K][K2]> : Theme[K][K2];
-    } : Theme[K];
+export type ThemeOverride = DeepPartial<Theme>;
+type DeepPartial<T> = {
+    [K in keyof T]?: (T[K] extends object ? DeepPartial<T[K]> : T[K]) | undefined;
 };
+export {};