@nxds/core 0.7.2 → 0.9.1

package/dist/runtime/index.d.cts

@@ -1,7 +1,7 @@
-import { T as Tier, P as PaletteKey, M as Mode } from './palette-DgJXuoTz.cjs';
-export { N as NexusSurfaceTone, a as PALETTE_KEYS, b as TIER_THRESHOLDS } from './palette-DgJXuoTz.cjs';
-import { b as NexusAppearanceState, d as DerivedTheme } from './surface-ladder-C2sSp67b.cjs';
-export { B as BASE_TONE_OPTIONS, e as BASE_TONE_SEEDS, C as CORNER_OPTIONS, f as DEFAULT_BRAND_COLOR, g as DEFAULT_NEXUS_APPEARANCE, h as DENSITY_OPTIONS, E as ELEVATION_OPTIONS, i as NexusAppearanceMode, a as NexusAppearancePrefs, j as NexusCorners, k as NexusDensity, l as NexusElevation, N as NexusPresetField, m as NexusStroke, n as NexusThemeContract, o as STROKE_OPTIONS, p as SurfaceToken, T as ThemeDerivationInput, q as ThemeSeeds, r as TokenMap, s as appearancePrefsToCss, t as createNexusThemeContract, u as deriveTheme, v as normalizeAppearanceModeIds, w as sanitizeNexusAppearance, x as sanitizeNexusAppearancePrefs, y as themeToCss } from './surface-ladder-C2sSp67b.cjs';
+import { T as Tier, P as PaletteKey, M as Mode } from './palette-BKTIQ0WC.cjs';
+export { N as NxdsSurfaceTone, a as PALETTE_KEYS, b as TIER_THRESHOLDS } from './palette-BKTIQ0WC.cjs';
+import { b as NxdsAppearanceState, d as DerivedTheme } from './surface-ladder-C8HTwT7z.cjs';
+export { B as BASE_TONE_OPTIONS, e as BASE_TONE_SEEDS, C as CORNER_OPTIONS, f as DEFAULT_BRAND_COLOR, g as DEFAULT_NXDS_APPEARANCE, h as DENSITY_OPTIONS, E as ELEVATION_OPTIONS, i as NxdsAppearanceMode, a as NxdsAppearancePrefs, j as NxdsCorners, k as NxdsDensity, l as NxdsElevation, N as NxdsPresetField, m as NxdsStroke, n as NxdsThemeContract, o as STROKE_OPTIONS, p as SurfaceToken, T as ThemeDerivationInput, q as ThemeSeeds, r as TokenMap, s as appearancePrefsToCss, t as createNxdsThemeContract, u as deriveTheme, v as normalizeAppearanceModeIds, w as sanitizeNxdsAppearance, x as sanitizeNxdsAppearancePrefs, y as themeToCss } from './surface-ladder-C8HTwT7z.cjs';
 
 type AdjustContrastTier = Tier;
 type AdjustContrastPalette = PaletteKey;
@@ -29,7 +29,7 @@ interface AdjustContrastOptions {
     palette?: AdjustContrastPalette;
 }
 /**
- * Snap a custom color to the nearest Nexus palette shade that passes the
+ * Snap a custom color to the nearest nxds palette shade that passes the
  * requested APCA tier on the target background. Lightness comes from the
  * perceptual grid; hue and chroma come from the input (or, for achromatic
  * inputs, from the chosen palette's shade 500).
@@ -62,42 +62,75 @@ declare function adjustContrast(input: string, options?: AdjustContrastOptions):
  */
 declare function apcaLc(foreground: string, background: string): number;
 
+type NxdsResolvedAppearanceMode = 'light' | 'dark';
+type NxdsAppearanceCookieSameSite = 'Lax' | 'Strict' | 'None';
+interface NxdsAppearanceCookieOptions {
+    maxAge?: number;
+    path?: string;
+    sameSite?: NxdsAppearanceCookieSameSite;
+    secure?: boolean | 'auto';
+    domain?: string;
+}
+interface NxdsAppearancePersistOptions {
+    /** localStorage key the first-paint script reads. `false` skips it. */
+    storageKey: string | false;
+    /** Cookie a server reads to render the saved appearance. `false` skips it. */
+    cookieWriteKey?: string | false;
+    cookieOptions?: NxdsAppearanceCookieOptions;
+}
+declare const NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS: number;
+declare function prefersDarkColorScheme(): boolean;
+/** Calls `onChange` when the OS colour scheme flips. Returns the unsubscribe. */
+declare function watchColorScheme(onChange: () => void): () => void;
+declare function resolveNxdsAppearanceMode(mode: NxdsAppearanceState['mode'], systemPrefersDark: boolean): NxdsResolvedAppearanceMode;
+/** The appearance saved under `storageKey`, or `fallback` when there is none. */
+declare function readStoredNxdsAppearance(storageKey: string | false, fallback: NxdsAppearanceState): NxdsAppearanceState;
+/**
+ * Writes the theme to the page: the `.dark` class and mode attributes on
+ * `<html>`, and the derived theme and preference styles in `<head>`.
+ */
+declare function applyNxdsAppearance(state: NxdsAppearanceState, systemPrefersDark: boolean): void;
+/** Undoes `applyNxdsAppearance`. */
+declare function removeNxdsAppearance(): void;
+/** Saves the appearance for the first-paint script and, optionally, the server. */
+declare function persistNxdsAppearance(state: NxdsAppearanceState, { storageKey, cookieWriteKey, cookieOptions, }: NxdsAppearancePersistOptions): void;
+
 declare const SNAPSHOT_VERSION = 9;
 declare const STATE_COOKIE_VERSION = 6;
-declare const NEXUS_APPEARANCE_DATA_ATTRS: readonly ["data-density", "data-radius", "data-shadow", "data-borderwidth"];
-type NexusAppearanceDataAttr = (typeof NEXUS_APPEARANCE_DATA_ATTRS)[number];
-interface NexusAppearanceSnapshot {
+declare const NXDS_APPEARANCE_DATA_ATTRS: readonly ["data-density", "data-radius", "data-shadow", "data-borderwidth"];
+type NxdsAppearanceDataAttr = (typeof NXDS_APPEARANCE_DATA_ATTRS)[number];
+interface NxdsAppearanceSnapshot {
     version: typeof SNAPSHOT_VERSION;
-    state: NexusAppearanceState;
+    state: NxdsAppearanceState;
     themeCss: string;
     prefsCss: string;
 }
-interface NexusAppearanceStateCookie {
+interface NxdsAppearanceStateCookie {
     version: typeof STATE_COOKIE_VERSION;
-    state: NexusAppearanceState;
+    state: NxdsAppearanceState;
 }
-interface NexusFirstPaintResolution {
+interface NxdsFirstPaintResolution {
     className: '' | 'dark';
-    dataAttrs: Record<NexusAppearanceDataAttr, string>;
+    dataAttrs: Record<NxdsAppearanceDataAttr, string>;
     themeCss: string;
     prefsCss: string;
 }
-interface NexusAppearanceBootstrapScriptOptions {
+interface NxdsAppearanceBootstrapScriptOptions {
     storageKey?: string | false;
-    defaultSnapshot?: NexusAppearanceSnapshot;
+    defaultSnapshot?: NxdsAppearanceSnapshot;
 }
-declare const DEFAULT_STORAGE_KEY = "nexus-appearance";
-declare const DEFAULT_COOKIE_KEY = "nexus-appearance-state";
-declare function createNexusAppearanceSnapshot(state: NexusAppearanceState, themeCss: string, prefsCss: string): NexusAppearanceSnapshot;
-declare function createNexusAppearanceSnapshotFromState(state: NexusAppearanceState): NexusAppearanceSnapshot;
-declare function createNexusAppearanceStateCookie(state: NexusAppearanceState): NexusAppearanceStateCookie;
-declare function serializeNexusAppearanceStateCookie(state: NexusAppearanceState): string;
-declare function parseNexusAppearanceStateCookie(raw: unknown): NexusAppearanceState | null;
-declare function createNexusAppearanceSnapshotFromCookie(raw: unknown, fallbackState?: NexusAppearanceState): NexusAppearanceSnapshot;
-declare function createDefaultNexusAppearanceSnapshot(): NexusAppearanceSnapshot;
-declare function sanitizeNexusAppearanceSnapshot(raw: unknown): NexusAppearanceSnapshot;
-declare function resolveFirstPaint(snapshot: NexusAppearanceSnapshot, systemPrefersDark: boolean): NexusFirstPaintResolution;
-declare function createNexusAppearanceBootstrapScript(options?: NexusAppearanceBootstrapScriptOptions): string;
+declare const DEFAULT_STORAGE_KEY = "nxds-appearance";
+declare const DEFAULT_COOKIE_KEY = "nxds-appearance-state";
+declare function createNxdsAppearanceSnapshot(state: NxdsAppearanceState, themeCss: string, prefsCss: string): NxdsAppearanceSnapshot;
+declare function createNxdsAppearanceSnapshotFromState(state: NxdsAppearanceState): NxdsAppearanceSnapshot;
+declare function createNxdsAppearanceStateCookie(state: NxdsAppearanceState): NxdsAppearanceStateCookie;
+declare function serializeNxdsAppearanceStateCookie(state: NxdsAppearanceState): string;
+declare function parseNxdsAppearanceStateCookie(raw: unknown): NxdsAppearanceState | null;
+declare function createNxdsAppearanceSnapshotFromCookie(raw: unknown, fallbackState?: NxdsAppearanceState): NxdsAppearanceSnapshot;
+declare function createDefaultNxdsAppearanceSnapshot(): NxdsAppearanceSnapshot;
+declare function sanitizeNxdsAppearanceSnapshot(raw: unknown): NxdsAppearanceSnapshot;
+declare function resolveFirstPaint(snapshot: NxdsAppearanceSnapshot, systemPrefersDark: boolean): NxdsFirstPaintResolution;
+declare function createNxdsAppearanceBootstrapScript(options?: NxdsAppearanceBootstrapScriptOptions): string;
 
 declare const BRAND_PRESET_FAMILIES: readonly ["indigo", "blue", "violet", "rose", "orange", "amber", "green", "teal"];
 interface BrandColorPreset {
@@ -150,4 +183,4 @@ declare const ALPHA_TOKEN_NAMES: readonly ["background-hover-alpha", "border-def
 type SemanticColorName = (typeof SURFACE_TOKEN_NAMES)[number] | (typeof TEXT_TOKEN_NAMES)[number] | (typeof BORDER_TOKEN_NAMES)[number] | (typeof BRAND_TOKEN_NAMES)[number] | (typeof STATUS_TOKEN_NAMES)[number] | (typeof CHART_TOKEN_NAMES)[number] | (typeof FOCUS_TOKEN_NAMES)[number] | (typeof ALPHA_TOKEN_NAMES)[number];
 declare const SEMANTIC_TOKEN_REGISTRY: readonly SemanticTokenMeta[];
 
-export { type AdjustContrastOptions, type AdjustContrastPalette, type AdjustContrastTier, BRAND_COLOR_PRESETS, type BrandColorPreset, DEFAULT_COOKIE_KEY, DEFAULT_STORAGE_KEY, DerivedTheme, Mode, NEXUS_APPEARANCE_DATA_ATTRS, type NexusAppearanceBootstrapScriptOptions, type NexusAppearanceDataAttr, type NexusAppearanceSnapshot, NexusAppearanceState, type NexusAppearanceStateCookie, type NexusFirstPaintResolution, SEMANTIC_TOKEN_REGISTRY, SNAPSHOT_VERSION, type SemanticColorName, type SemanticTokenMeta, type ThemeContrastCheck, Tier, type TokenCategory, adjustContrast, apcaLc, createDefaultNexusAppearanceSnapshot, createNexusAppearanceBootstrapScript, createNexusAppearanceSnapshot, createNexusAppearanceSnapshotFromCookie, createNexusAppearanceSnapshotFromState, createNexusAppearanceStateCookie, findBrandColorPreset, isColor, measureThemeContrast, parseNexusAppearanceStateCookie, resolveFirstPaint, sanitizeNexusAppearanceSnapshot, serializeNexusAppearanceStateCookie };
+export { type AdjustContrastOptions, type AdjustContrastPalette, type AdjustContrastTier, BRAND_COLOR_PRESETS, type BrandColorPreset, DEFAULT_COOKIE_KEY, DEFAULT_STORAGE_KEY, DerivedTheme, Mode, NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS, NXDS_APPEARANCE_DATA_ATTRS, type NxdsAppearanceBootstrapScriptOptions, type NxdsAppearanceCookieOptions, type NxdsAppearanceCookieSameSite, type NxdsAppearanceDataAttr, type NxdsAppearancePersistOptions, type NxdsAppearanceSnapshot, NxdsAppearanceState, type NxdsAppearanceStateCookie, type NxdsFirstPaintResolution, type NxdsResolvedAppearanceMode, SEMANTIC_TOKEN_REGISTRY, SNAPSHOT_VERSION, type SemanticColorName, type SemanticTokenMeta, type ThemeContrastCheck, Tier, type TokenCategory, adjustContrast, apcaLc, applyNxdsAppearance, createDefaultNxdsAppearanceSnapshot, createNxdsAppearanceBootstrapScript, createNxdsAppearanceSnapshot, createNxdsAppearanceSnapshotFromCookie, createNxdsAppearanceSnapshotFromState, createNxdsAppearanceStateCookie, findBrandColorPreset, isColor, measureThemeContrast, parseNxdsAppearanceStateCookie, persistNxdsAppearance, prefersDarkColorScheme, readStoredNxdsAppearance, removeNxdsAppearance, resolveFirstPaint, resolveNxdsAppearanceMode, sanitizeNxdsAppearanceSnapshot, serializeNxdsAppearanceStateCookie, watchColorScheme };

package/dist/runtime/index.d.ts

@@ -1,7 +1,7 @@
-import { T as Tier, P as PaletteKey, M as Mode } from './palette-DgJXuoTz.js';
-export { N as NexusSurfaceTone, a as PALETTE_KEYS, b as TIER_THRESHOLDS } from './palette-DgJXuoTz.js';
-import { b as NexusAppearanceState, d as DerivedTheme } from './surface-ladder-yQyRTCRt.js';
-export { B as BASE_TONE_OPTIONS, e as BASE_TONE_SEEDS, C as CORNER_OPTIONS, f as DEFAULT_BRAND_COLOR, g as DEFAULT_NEXUS_APPEARANCE, h as DENSITY_OPTIONS, E as ELEVATION_OPTIONS, i as NexusAppearanceMode, a as NexusAppearancePrefs, j as NexusCorners, k as NexusDensity, l as NexusElevation, N as NexusPresetField, m as NexusStroke, n as NexusThemeContract, o as STROKE_OPTIONS, p as SurfaceToken, T as ThemeDerivationInput, q as ThemeSeeds, r as TokenMap, s as appearancePrefsToCss, t as createNexusThemeContract, u as deriveTheme, v as normalizeAppearanceModeIds, w as sanitizeNexusAppearance, x as sanitizeNexusAppearancePrefs, y as themeToCss } from './surface-ladder-yQyRTCRt.js';
+import { T as Tier, P as PaletteKey, M as Mode } from './palette-BKTIQ0WC.js';
+export { N as NxdsSurfaceTone, a as PALETTE_KEYS, b as TIER_THRESHOLDS } from './palette-BKTIQ0WC.js';
+import { b as NxdsAppearanceState, d as DerivedTheme } from './surface-ladder-B950TU4_.js';
+export { B as BASE_TONE_OPTIONS, e as BASE_TONE_SEEDS, C as CORNER_OPTIONS, f as DEFAULT_BRAND_COLOR, g as DEFAULT_NXDS_APPEARANCE, h as DENSITY_OPTIONS, E as ELEVATION_OPTIONS, i as NxdsAppearanceMode, a as NxdsAppearancePrefs, j as NxdsCorners, k as NxdsDensity, l as NxdsElevation, N as NxdsPresetField, m as NxdsStroke, n as NxdsThemeContract, o as STROKE_OPTIONS, p as SurfaceToken, T as ThemeDerivationInput, q as ThemeSeeds, r as TokenMap, s as appearancePrefsToCss, t as createNxdsThemeContract, u as deriveTheme, v as normalizeAppearanceModeIds, w as sanitizeNxdsAppearance, x as sanitizeNxdsAppearancePrefs, y as themeToCss } from './surface-ladder-B950TU4_.js';
 
 type AdjustContrastTier = Tier;
 type AdjustContrastPalette = PaletteKey;
@@ -29,7 +29,7 @@ interface AdjustContrastOptions {
     palette?: AdjustContrastPalette;
 }
 /**
- * Snap a custom color to the nearest Nexus palette shade that passes the
+ * Snap a custom color to the nearest nxds palette shade that passes the
  * requested APCA tier on the target background. Lightness comes from the
  * perceptual grid; hue and chroma come from the input (or, for achromatic
  * inputs, from the chosen palette's shade 500).
@@ -62,42 +62,75 @@ declare function adjustContrast(input: string, options?: AdjustContrastOptions):
  */
 declare function apcaLc(foreground: string, background: string): number;
 
+type NxdsResolvedAppearanceMode = 'light' | 'dark';
+type NxdsAppearanceCookieSameSite = 'Lax' | 'Strict' | 'None';
+interface NxdsAppearanceCookieOptions {
+    maxAge?: number;
+    path?: string;
+    sameSite?: NxdsAppearanceCookieSameSite;
+    secure?: boolean | 'auto';
+    domain?: string;
+}
+interface NxdsAppearancePersistOptions {
+    /** localStorage key the first-paint script reads. `false` skips it. */
+    storageKey: string | false;
+    /** Cookie a server reads to render the saved appearance. `false` skips it. */
+    cookieWriteKey?: string | false;
+    cookieOptions?: NxdsAppearanceCookieOptions;
+}
+declare const NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS: number;
+declare function prefersDarkColorScheme(): boolean;
+/** Calls `onChange` when the OS colour scheme flips. Returns the unsubscribe. */
+declare function watchColorScheme(onChange: () => void): () => void;
+declare function resolveNxdsAppearanceMode(mode: NxdsAppearanceState['mode'], systemPrefersDark: boolean): NxdsResolvedAppearanceMode;
+/** The appearance saved under `storageKey`, or `fallback` when there is none. */
+declare function readStoredNxdsAppearance(storageKey: string | false, fallback: NxdsAppearanceState): NxdsAppearanceState;
+/**
+ * Writes the theme to the page: the `.dark` class and mode attributes on
+ * `<html>`, and the derived theme and preference styles in `<head>`.
+ */
+declare function applyNxdsAppearance(state: NxdsAppearanceState, systemPrefersDark: boolean): void;
+/** Undoes `applyNxdsAppearance`. */
+declare function removeNxdsAppearance(): void;
+/** Saves the appearance for the first-paint script and, optionally, the server. */
+declare function persistNxdsAppearance(state: NxdsAppearanceState, { storageKey, cookieWriteKey, cookieOptions, }: NxdsAppearancePersistOptions): void;
+
 declare const SNAPSHOT_VERSION = 9;
 declare const STATE_COOKIE_VERSION = 6;
-declare const NEXUS_APPEARANCE_DATA_ATTRS: readonly ["data-density", "data-radius", "data-shadow", "data-borderwidth"];
-type NexusAppearanceDataAttr = (typeof NEXUS_APPEARANCE_DATA_ATTRS)[number];
-interface NexusAppearanceSnapshot {
+declare const NXDS_APPEARANCE_DATA_ATTRS: readonly ["data-density", "data-radius", "data-shadow", "data-borderwidth"];
+type NxdsAppearanceDataAttr = (typeof NXDS_APPEARANCE_DATA_ATTRS)[number];
+interface NxdsAppearanceSnapshot {
     version: typeof SNAPSHOT_VERSION;
-    state: NexusAppearanceState;
+    state: NxdsAppearanceState;
     themeCss: string;
     prefsCss: string;
 }
-interface NexusAppearanceStateCookie {
+interface NxdsAppearanceStateCookie {
     version: typeof STATE_COOKIE_VERSION;
-    state: NexusAppearanceState;
+    state: NxdsAppearanceState;
 }
-interface NexusFirstPaintResolution {
+interface NxdsFirstPaintResolution {
     className: '' | 'dark';
-    dataAttrs: Record<NexusAppearanceDataAttr, string>;
+    dataAttrs: Record<NxdsAppearanceDataAttr, string>;
     themeCss: string;
     prefsCss: string;
 }
-interface NexusAppearanceBootstrapScriptOptions {
+interface NxdsAppearanceBootstrapScriptOptions {
     storageKey?: string | false;
-    defaultSnapshot?: NexusAppearanceSnapshot;
+    defaultSnapshot?: NxdsAppearanceSnapshot;
 }
-declare const DEFAULT_STORAGE_KEY = "nexus-appearance";
-declare const DEFAULT_COOKIE_KEY = "nexus-appearance-state";
-declare function createNexusAppearanceSnapshot(state: NexusAppearanceState, themeCss: string, prefsCss: string): NexusAppearanceSnapshot;
-declare function createNexusAppearanceSnapshotFromState(state: NexusAppearanceState): NexusAppearanceSnapshot;
-declare function createNexusAppearanceStateCookie(state: NexusAppearanceState): NexusAppearanceStateCookie;
-declare function serializeNexusAppearanceStateCookie(state: NexusAppearanceState): string;
-declare function parseNexusAppearanceStateCookie(raw: unknown): NexusAppearanceState | null;
-declare function createNexusAppearanceSnapshotFromCookie(raw: unknown, fallbackState?: NexusAppearanceState): NexusAppearanceSnapshot;
-declare function createDefaultNexusAppearanceSnapshot(): NexusAppearanceSnapshot;
-declare function sanitizeNexusAppearanceSnapshot(raw: unknown): NexusAppearanceSnapshot;
-declare function resolveFirstPaint(snapshot: NexusAppearanceSnapshot, systemPrefersDark: boolean): NexusFirstPaintResolution;
-declare function createNexusAppearanceBootstrapScript(options?: NexusAppearanceBootstrapScriptOptions): string;
+declare const DEFAULT_STORAGE_KEY = "nxds-appearance";
+declare const DEFAULT_COOKIE_KEY = "nxds-appearance-state";
+declare function createNxdsAppearanceSnapshot(state: NxdsAppearanceState, themeCss: string, prefsCss: string): NxdsAppearanceSnapshot;
+declare function createNxdsAppearanceSnapshotFromState(state: NxdsAppearanceState): NxdsAppearanceSnapshot;
+declare function createNxdsAppearanceStateCookie(state: NxdsAppearanceState): NxdsAppearanceStateCookie;
+declare function serializeNxdsAppearanceStateCookie(state: NxdsAppearanceState): string;
+declare function parseNxdsAppearanceStateCookie(raw: unknown): NxdsAppearanceState | null;
+declare function createNxdsAppearanceSnapshotFromCookie(raw: unknown, fallbackState?: NxdsAppearanceState): NxdsAppearanceSnapshot;
+declare function createDefaultNxdsAppearanceSnapshot(): NxdsAppearanceSnapshot;
+declare function sanitizeNxdsAppearanceSnapshot(raw: unknown): NxdsAppearanceSnapshot;
+declare function resolveFirstPaint(snapshot: NxdsAppearanceSnapshot, systemPrefersDark: boolean): NxdsFirstPaintResolution;
+declare function createNxdsAppearanceBootstrapScript(options?: NxdsAppearanceBootstrapScriptOptions): string;
 
 declare const BRAND_PRESET_FAMILIES: readonly ["indigo", "blue", "violet", "rose", "orange", "amber", "green", "teal"];
 interface BrandColorPreset {
@@ -150,4 +183,4 @@ declare const ALPHA_TOKEN_NAMES: readonly ["background-hover-alpha", "border-def
 type SemanticColorName = (typeof SURFACE_TOKEN_NAMES)[number] | (typeof TEXT_TOKEN_NAMES)[number] | (typeof BORDER_TOKEN_NAMES)[number] | (typeof BRAND_TOKEN_NAMES)[number] | (typeof STATUS_TOKEN_NAMES)[number] | (typeof CHART_TOKEN_NAMES)[number] | (typeof FOCUS_TOKEN_NAMES)[number] | (typeof ALPHA_TOKEN_NAMES)[number];
 declare const SEMANTIC_TOKEN_REGISTRY: readonly SemanticTokenMeta[];
 
-export { type AdjustContrastOptions, type AdjustContrastPalette, type AdjustContrastTier, BRAND_COLOR_PRESETS, type BrandColorPreset, DEFAULT_COOKIE_KEY, DEFAULT_STORAGE_KEY, DerivedTheme, Mode, NEXUS_APPEARANCE_DATA_ATTRS, type NexusAppearanceBootstrapScriptOptions, type NexusAppearanceDataAttr, type NexusAppearanceSnapshot, NexusAppearanceState, type NexusAppearanceStateCookie, type NexusFirstPaintResolution, SEMANTIC_TOKEN_REGISTRY, SNAPSHOT_VERSION, type SemanticColorName, type SemanticTokenMeta, type ThemeContrastCheck, Tier, type TokenCategory, adjustContrast, apcaLc, createDefaultNexusAppearanceSnapshot, createNexusAppearanceBootstrapScript, createNexusAppearanceSnapshot, createNexusAppearanceSnapshotFromCookie, createNexusAppearanceSnapshotFromState, createNexusAppearanceStateCookie, findBrandColorPreset, isColor, measureThemeContrast, parseNexusAppearanceStateCookie, resolveFirstPaint, sanitizeNexusAppearanceSnapshot, serializeNexusAppearanceStateCookie };
+export { type AdjustContrastOptions, type AdjustContrastPalette, type AdjustContrastTier, BRAND_COLOR_PRESETS, type BrandColorPreset, DEFAULT_COOKIE_KEY, DEFAULT_STORAGE_KEY, DerivedTheme, Mode, NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS, NXDS_APPEARANCE_DATA_ATTRS, type NxdsAppearanceBootstrapScriptOptions, type NxdsAppearanceCookieOptions, type NxdsAppearanceCookieSameSite, type NxdsAppearanceDataAttr, type NxdsAppearancePersistOptions, type NxdsAppearanceSnapshot, NxdsAppearanceState, type NxdsAppearanceStateCookie, type NxdsFirstPaintResolution, type NxdsResolvedAppearanceMode, SEMANTIC_TOKEN_REGISTRY, SNAPSHOT_VERSION, type SemanticColorName, type SemanticTokenMeta, type ThemeContrastCheck, Tier, type TokenCategory, adjustContrast, apcaLc, applyNxdsAppearance, createDefaultNxdsAppearanceSnapshot, createNxdsAppearanceBootstrapScript, createNxdsAppearanceSnapshot, createNxdsAppearanceSnapshotFromCookie, createNxdsAppearanceSnapshotFromState, createNxdsAppearanceStateCookie, findBrandColorPreset, isColor, measureThemeContrast, parseNxdsAppearanceStateCookie, persistNxdsAppearance, prefersDarkColorScheme, readStoredNxdsAppearance, removeNxdsAppearance, resolveFirstPaint, resolveNxdsAppearanceMode, sanitizeNxdsAppearanceSnapshot, serializeNxdsAppearanceStateCookie, watchColorScheme };

package/dist/runtime/index.js

@@ -2562,7 +2562,7 @@ var STROKE_OPTIONS = [
   { value: "normal", label: "Normal" },
   { value: "strong", label: "Strong" }
 ];
-var DEFAULT_NEXUS_APPEARANCE = {
+var DEFAULT_NXDS_APPEARANCE = {
   mode: "light",
   brandColor: DEFAULT_BRAND_COLOR,
   surfaceTone: "zinc",
@@ -2614,7 +2614,7 @@ function formatPx(value) {
   return `${Number(value.toFixed(4))}px`;
 }
 function typographyScaleVariables(uiPx) {
-  const scale = uiPx / DEFAULT_NEXUS_APPEARANCE.prefs.uiFontSize;
+  const scale = uiPx / DEFAULT_NXDS_APPEARANCE.prefs.uiFontSize;
   const sizeVars = Object.entries(typography_default_default.size).map(
     ([name, token2]) => `  --nx-typography-size-${name}: ${formatPx(token2.$value.value * scale)};`
   );
@@ -2655,9 +2655,9 @@ function normalizeAppearanceModeIds(raw) {
   }
   return out;
 }
-function sanitizeNexusAppearancePrefs(raw) {
+function sanitizeNxdsAppearancePrefs(raw) {
   const o = isRecord(raw) ? raw : {};
-  const d = DEFAULT_NEXUS_APPEARANCE.prefs;
+  const d = DEFAULT_NXDS_APPEARANCE.prefs;
   return {
     uiFont: fontFamilyOr(o.uiFont, d.uiFont),
     codeFont: fontFamilyOr(o.codeFont, d.codeFont),
@@ -2668,10 +2668,10 @@ function sanitizeNexusAppearancePrefs(raw) {
     fontSmoothing: boolOr(o.fontSmoothing, d.fontSmoothing)
   };
 }
-function sanitizeNexusAppearance(rawInput) {
-  if (!isRecord(rawInput)) return DEFAULT_NEXUS_APPEARANCE;
+function sanitizeNxdsAppearance(rawInput) {
+  if (!isRecord(rawInput)) return DEFAULT_NXDS_APPEARANCE;
   const raw = normalizeAppearanceModeIds(rawInput);
-  const d = DEFAULT_NEXUS_APPEARANCE;
+  const d = DEFAULT_NXDS_APPEARANCE;
   return {
     mode: enumOr(raw.mode, APPEARANCE_MODES, d.mode),
     brandColor: typeof raw.brandColor === "string" && isColor(raw.brandColor) ? raw.brandColor : d.brandColor,
@@ -2682,10 +2682,10 @@ function sanitizeNexusAppearance(rawInput) {
     corners: enumOr(raw.corners, CORNERS, d.corners),
     elevation: enumOr(raw.elevation, ELEVATIONS, d.elevation),
     stroke: enumOr(raw.stroke, STROKES, d.stroke),
-    prefs: sanitizeNexusAppearancePrefs(raw.prefs)
+    prefs: sanitizeNxdsAppearancePrefs(raw.prefs)
   };
 }
-function createNexusThemeContract(state) {
+function createNxdsThemeContract(state) {
   const tone = BASE_TONE_SEEDS[state.surfaceTone];
   return {
     surfaceTone: state.surfaceTone,
@@ -2697,11 +2697,11 @@ function createNexusThemeContract(state) {
 function appearancePrefsToCss(prefs) {
   const uiPx = clampFontSize(
     prefs.uiFontSize,
-    DEFAULT_NEXUS_APPEARANCE.prefs.uiFontSize
+    DEFAULT_NXDS_APPEARANCE.prefs.uiFontSize
   );
   const codePx = clampFontSize(
     prefs.codeFontSize,
-    DEFAULT_NEXUS_APPEARANCE.prefs.codeFontSize
+    DEFAULT_NXDS_APPEARANCE.prefs.codeFontSize
   );
   const blocks = [
     inRuntimeLayer(`:root {
@@ -4520,14 +4520,14 @@ ${block(":root.dark", derived.dark)}`
 var SNAPSHOT_VERSION = 9;
 var STATE_COOKIE_VERSION = 6;
 var SNAPSHOT_CACHE_LIMIT = 50;
-var NEXUS_APPEARANCE_DATA_ATTRS = [
+var NXDS_APPEARANCE_DATA_ATTRS = [
   "data-density",
   "data-radius",
   "data-shadow",
   "data-borderwidth"
 ];
-var DEFAULT_STORAGE_KEY = "nexus-appearance";
-var DEFAULT_COOKIE_KEY = "nexus-appearance-state";
+var DEFAULT_STORAGE_KEY = "nxds-appearance";
+var DEFAULT_COOKIE_KEY = "nxds-appearance-state";
 var isRecord2 = (value) => typeof value === "object" && value !== null;
 var cachedSnapshots = /* @__PURE__ */ new Map();
 var cachedModes = /* @__PURE__ */ new Map();
@@ -4552,7 +4552,7 @@ function deriveModeCached(contract, mode) {
   return cachedModes.get(key) ?? remember(cachedModes, key, deriveThemeMode(contract, mode));
 }
 function deriveThemeCss(state) {
-  const contract = createNexusThemeContract(state);
+  const contract = createNxdsThemeContract(state);
   return themeToCss({
     light: deriveModeCached(contract, "light"),
     dark: deriveModeCached(contract, "dark")
@@ -4561,7 +4561,7 @@ function deriveThemeCss(state) {
 function derivePrefsCss(state) {
   return appearancePrefsToCss(state.prefs);
 }
-function createNexusAppearanceSnapshot(state, themeCss, prefsCss) {
+function createNxdsAppearanceSnapshot(state, themeCss, prefsCss) {
   return {
     version: SNAPSHOT_VERSION,
     state,
@@ -4569,33 +4569,33 @@ function createNexusAppearanceSnapshot(state, themeCss, prefsCss) {
     prefsCss
   };
 }
-function createNexusAppearanceSnapshotFromState(state) {
-  const sanitizedState = sanitizeNexusAppearance(state);
+function createNxdsAppearanceSnapshotFromState(state) {
+  const sanitizedState = sanitizeNxdsAppearance(state);
   const cacheKey = cacheKeyForState(sanitizedState);
   const cachedSnapshot = cachedSnapshots.get(cacheKey);
   if (cachedSnapshot) return cachedSnapshot;
   return remember(
     cachedSnapshots,
     cacheKey,
-    createNexusAppearanceSnapshot(
+    createNxdsAppearanceSnapshot(
       sanitizedState,
       deriveThemeCss(sanitizedState),
       derivePrefsCss(sanitizedState)
     )
   );
 }
-function createNexusAppearanceStateCookie(state) {
+function createNxdsAppearanceStateCookie(state) {
   return {
     version: STATE_COOKIE_VERSION,
-    state: sanitizeNexusAppearance(state)
+    state: sanitizeNxdsAppearance(state)
   };
 }
-function serializeNexusAppearanceStateCookie(state) {
+function serializeNxdsAppearanceStateCookie(state) {
   return encodeURIComponent(
-    JSON.stringify(createNexusAppearanceStateCookie(state))
+    JSON.stringify(createNxdsAppearanceStateCookie(state))
   );
 }
-function parseNexusAppearanceStateCookie(raw) {
+function parseNxdsAppearanceStateCookie(raw) {
   if (typeof raw !== "string" || raw.length === 0) return null;
   try {
     const decoded = decodeURIComponent(raw);
@@ -4603,31 +4603,31 @@ function parseNexusAppearanceStateCookie(raw) {
     if (!isRecord2(parsed) || parsed.version !== STATE_COOKIE_VERSION || !isRecord2(parsed.state)) {
       return null;
     }
-    return sanitizeNexusAppearance(parsed.state);
+    return sanitizeNxdsAppearance(parsed.state);
   } catch {
     return null;
   }
 }
-function createNexusAppearanceSnapshotFromCookie(raw, fallbackState = DEFAULT_NEXUS_APPEARANCE) {
-  return createNexusAppearanceSnapshotFromState(
-    parseNexusAppearanceStateCookie(raw) ?? sanitizeNexusAppearance(fallbackState)
+function createNxdsAppearanceSnapshotFromCookie(raw, fallbackState = DEFAULT_NXDS_APPEARANCE) {
+  return createNxdsAppearanceSnapshotFromState(
+    parseNxdsAppearanceStateCookie(raw) ?? sanitizeNxdsAppearance(fallbackState)
   );
 }
 var cachedDefaultSnapshot;
-function createDefaultNexusAppearanceSnapshot() {
-  return cachedDefaultSnapshot ?? (cachedDefaultSnapshot = createNexusAppearanceSnapshotFromState(
-    DEFAULT_NEXUS_APPEARANCE
+function createDefaultNxdsAppearanceSnapshot() {
+  return cachedDefaultSnapshot ?? (cachedDefaultSnapshot = createNxdsAppearanceSnapshotFromState(
+    DEFAULT_NXDS_APPEARANCE
   ));
 }
-function sanitizeNexusAppearanceSnapshot(raw) {
+function sanitizeNxdsAppearanceSnapshot(raw) {
   if (!isRecord2(raw) || !isRecord2(raw.state)) {
-    return createDefaultNexusAppearanceSnapshot();
+    return createDefaultNxdsAppearanceSnapshot();
   }
-  const state = sanitizeNexusAppearance(raw.state);
+  const state = sanitizeNxdsAppearance(raw.state);
   if (raw.version === SNAPSHOT_VERSION && typeof raw.themeCss === "string" && typeof raw.prefsCss === "string") {
-    return createNexusAppearanceSnapshot(state, raw.themeCss, raw.prefsCss);
+    return createNxdsAppearanceSnapshot(state, raw.themeCss, raw.prefsCss);
   }
-  return createNexusAppearanceSnapshotFromState(state);
+  return createNxdsAppearanceSnapshotFromState(state);
 }
 function resolveFirstPaint(snapshot, systemPrefersDark) {
   const { state } = snapshot;
@@ -4647,10 +4647,104 @@ function resolveFirstPaint(snapshot, systemPrefersDark) {
 function escapeInlineScriptJson(value) {
   return JSON.stringify(value).replace(/</g, "\\u003C").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
 }
-function createNexusAppearanceBootstrapScript(options = {}) {
+function createNxdsAppearanceBootstrapScript(options = {}) {
   const storageKey = options.storageKey ?? DEFAULT_STORAGE_KEY;
-  const defaultSnapshot = options.defaultSnapshot ? sanitizeNexusAppearanceSnapshot(options.defaultSnapshot) : createDefaultNexusAppearanceSnapshot();
-  return `(function(){try{var k=${escapeInlineScriptJson(storageKey)};var f=${escapeInlineScriptJson(defaultSnapshot)};var s=f;try{if(k!==false){var r=window.localStorage&&window.localStorage.getItem(k);if(r){var p=JSON.parse(r);if(p&&p.version===f.version&&p.state&&typeof p.themeCss==="string"&&typeof p.prefsCss==="string"){s=p;}}}}catch(e){}var st=s.state||f.state;var m=st.mode==="dark"||st.mode==="light"||st.mode==="system"?st.mode:f.state.mode;var sys=false;try{sys=m==="system"&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}var dark=m==="dark"||sys===true;var root=document.documentElement;root.classList.toggle("dark",dark);root.setAttribute("data-density",typeof st.density==="string"?st.density:f.state.density);root.setAttribute("data-radius",typeof st.corners==="string"?st.corners:f.state.corners);root.setAttribute("data-shadow",typeof st.elevation==="string"?st.elevation:f.state.elevation);root.setAttribute("data-borderwidth",typeof st.stroke==="string"?st.stroke:f.state.stroke);function upsert(attr,css){var list=document.querySelectorAll("style["+attr+"]");var el=list[0]||document.createElement("style");for(var i=1;i<list.length;i++){list[i].remove();}el.setAttribute(attr,"");el.textContent=css||"";if(!el.parentNode){document.head.appendChild(el);}}upsert("data-nexus-appearance-theme",s.themeCss);upsert("data-nexus-appearance-prefs",s.prefsCss);}catch(e){}})();`;
+  const defaultSnapshot = options.defaultSnapshot ? sanitizeNxdsAppearanceSnapshot(options.defaultSnapshot) : createDefaultNxdsAppearanceSnapshot();
+  return `(function(){try{var k=${escapeInlineScriptJson(storageKey)};var f=${escapeInlineScriptJson(defaultSnapshot)};var s=f;try{if(k!==false){var r=window.localStorage&&window.localStorage.getItem(k);if(r){var p=JSON.parse(r);if(p&&p.version===f.version&&p.state&&typeof p.themeCss==="string"&&typeof p.prefsCss==="string"){s=p;}}}}catch(e){}var st=s.state||f.state;var m=st.mode==="dark"||st.mode==="light"||st.mode==="system"?st.mode:f.state.mode;var sys=false;try{sys=m==="system"&&window.matchMedia&&window.matchMedia("(prefers-color-scheme: dark)").matches;}catch(e){}var dark=m==="dark"||sys===true;var root=document.documentElement;root.classList.toggle("dark",dark);root.setAttribute("data-density",typeof st.density==="string"?st.density:f.state.density);root.setAttribute("data-radius",typeof st.corners==="string"?st.corners:f.state.corners);root.setAttribute("data-shadow",typeof st.elevation==="string"?st.elevation:f.state.elevation);root.setAttribute("data-borderwidth",typeof st.stroke==="string"?st.stroke:f.state.stroke);function upsert(attr,css){var list=document.querySelectorAll("style["+attr+"]");var el=list[0]||document.createElement("style");for(var i=1;i<list.length;i++){list[i].remove();}el.setAttribute(attr,"");el.textContent=css||"";if(!el.parentNode){document.head.appendChild(el);}}upsert("data-nxds-appearance-theme",s.themeCss);upsert("data-nxds-appearance-prefs",s.prefsCss);}catch(e){}})();`;
+}
+
+// src/lib/appearance-dom.ts
+var NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 365;
+var COLOR_SCHEME_QUERY = "(prefers-color-scheme: dark)";
+var THEME_STYLE_ATTR = "data-nxds-appearance-theme";
+var PREFS_STYLE_ATTR = "data-nxds-appearance-prefs";
+function prefersDarkColorScheme() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+    return false;
+  return window.matchMedia(COLOR_SCHEME_QUERY).matches;
+}
+function watchColorScheme(onChange) {
+  if (typeof window.matchMedia !== "function") return () => {
+  };
+  const query = window.matchMedia(COLOR_SCHEME_QUERY);
+  query.addEventListener("change", onChange);
+  return () => query.removeEventListener("change", onChange);
+}
+function resolveNxdsAppearanceMode(mode, systemPrefersDark) {
+  if (mode === "system") return systemPrefersDark ? "dark" : "light";
+  return mode;
+}
+function readStoredNxdsAppearance(storageKey, fallback) {
+  if (storageKey === false || typeof window === "undefined") return fallback;
+  try {
+    const raw = window.localStorage.getItem(storageKey);
+    return raw ? sanitizeNxdsAppearanceSnapshot(JSON.parse(raw)).state : fallback;
+  } catch {
+    return fallback;
+  }
+}
+function upsertStyle(attribute, css) {
+  const styles = Array.from(
+    document.querySelectorAll(`style[${attribute}]`)
+  );
+  const style = styles[0] ?? document.createElement("style");
+  for (const duplicate of styles.slice(1)) duplicate.remove();
+  style.setAttribute(attribute, "");
+  style.textContent = css;
+  if (!style.parentNode) document.head.appendChild(style);
+}
+function applyNxdsAppearance(state, systemPrefersDark) {
+  const firstPaint = resolveFirstPaint(
+    createNxdsAppearanceSnapshotFromState(state),
+    systemPrefersDark
+  );
+  const root = document.documentElement;
+  root.classList.toggle("dark", firstPaint.className === "dark");
+  for (const attr of NXDS_APPEARANCE_DATA_ATTRS) {
+    root.setAttribute(attr, firstPaint.dataAttrs[attr]);
+  }
+  upsertStyle(THEME_STYLE_ATTR, firstPaint.themeCss);
+  upsertStyle(PREFS_STYLE_ATTR, firstPaint.prefsCss);
+}
+function removeNxdsAppearance() {
+  document.querySelectorAll(`style[${THEME_STYLE_ATTR}], style[${PREFS_STYLE_ATTR}]`).forEach((style) => style.remove());
+  const root = document.documentElement;
+  root.classList.remove("dark");
+  for (const attr of NXDS_APPEARANCE_DATA_ATTRS) root.removeAttribute(attr);
+}
+function writeStateCookie(cookieWriteKey, state, options) {
+  const secure = options.secure === true || options.secure !== false && window.location.protocol === "https:";
+  const attrs = [
+    `Path=${(options.path ?? "/").replace(/[;\r\n]/g, "")}`,
+    `SameSite=${options.sameSite ?? "Lax"}`,
+    `Max-Age=${options.maxAge ?? NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS}`,
+    options.domain ? `Domain=${options.domain.replace(/[;\r\n]/g, "")}` : "",
+    secure ? "Secure" : ""
+  ].filter(Boolean);
+  document.cookie = `${cookieWriteKey}=${serializeNxdsAppearanceStateCookie(
+    state
+  )}; ${attrs.join("; ")}`;
+}
+function persistNxdsAppearance(state, {
+  storageKey,
+  cookieWriteKey = false,
+  cookieOptions = {}
+}) {
+  if (storageKey !== false) {
+    try {
+      window.localStorage.setItem(
+        storageKey,
+        JSON.stringify(createNxdsAppearanceSnapshotFromState(state))
+      );
+    } catch {
+    }
+  }
+  if (cookieWriteKey !== false) {
+    try {
+      writeStateCookie(cookieWriteKey, state, cookieOptions);
+    } catch {
+    }
+  }
 }
 
 // src/lib/brand-presets.ts
@@ -4846,11 +4940,12 @@ export {
   CORNER_OPTIONS,
   DEFAULT_BRAND_COLOR,
   DEFAULT_COOKIE_KEY,
-  DEFAULT_NEXUS_APPEARANCE,
+  DEFAULT_NXDS_APPEARANCE,
   DEFAULT_STORAGE_KEY,
   DENSITY_OPTIONS,
   ELEVATION_OPTIONS,
-  NEXUS_APPEARANCE_DATA_ATTRS,
+  NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS,
+  NXDS_APPEARANCE_DATA_ATTRS,
   PALETTE_KEYS,
   SEMANTIC_TOKEN_REGISTRY,
   SNAPSHOT_VERSION,
@@ -4859,24 +4954,31 @@ export {
   adjustContrast,
   apcaLc,
   appearancePrefsToCss,
-  createDefaultNexusAppearanceSnapshot,
-  createNexusAppearanceBootstrapScript,
-  createNexusAppearanceSnapshot,
-  createNexusAppearanceSnapshotFromCookie,
-  createNexusAppearanceSnapshotFromState,
-  createNexusAppearanceStateCookie,
-  createNexusThemeContract,
+  applyNxdsAppearance,
+  createDefaultNxdsAppearanceSnapshot,
+  createNxdsAppearanceBootstrapScript,
+  createNxdsAppearanceSnapshot,
+  createNxdsAppearanceSnapshotFromCookie,
+  createNxdsAppearanceSnapshotFromState,
+  createNxdsAppearanceStateCookie,
+  createNxdsThemeContract,
   deriveTheme,
   findBrandColorPreset,
   isColor,
   measureThemeContrast,
   normalizeAppearanceModeIds,
-  parseNexusAppearanceStateCookie,
+  parseNxdsAppearanceStateCookie,
+  persistNxdsAppearance,
+  prefersDarkColorScheme,
+  readStoredNxdsAppearance,
+  removeNxdsAppearance,
   resolveFirstPaint,
-  sanitizeNexusAppearance,
-  sanitizeNexusAppearancePrefs,
-  sanitizeNexusAppearanceSnapshot,
-  serializeNexusAppearanceStateCookie,
-  themeToCss
+  resolveNxdsAppearanceMode,
+  sanitizeNxdsAppearance,
+  sanitizeNxdsAppearancePrefs,
+  sanitizeNxdsAppearanceSnapshot,
+  serializeNxdsAppearanceStateCookie,
+  themeToCss,
+  watchColorScheme
 };
 //# sourceMappingURL=index.js.map