@nxds/core 0.11.0 → 0.12.0

package/dist/runtime/index.cjs

@@ -26,12 +26,19 @@ __export(src_exports, {
   CORNER_OPTIONS: () => CORNER_OPTIONS,
   DEFAULT_BRAND_COLOR: () => DEFAULT_BRAND_COLOR,
   DEFAULT_COOKIE_KEY: () => DEFAULT_COOKIE_KEY,
+  DEFAULT_ICON_LIBRARY: () => DEFAULT_ICON_LIBRARY,
   DEFAULT_NXDS_APPEARANCE: () => DEFAULT_NXDS_APPEARANCE,
+  DEFAULT_NXDS_THEME: () => DEFAULT_NXDS_THEME,
   DEFAULT_STORAGE_KEY: () => DEFAULT_STORAGE_KEY,
   DENSITY_OPTIONS: () => DENSITY_OPTIONS,
   ELEVATION_OPTIONS: () => ELEVATION_OPTIONS,
+  FONT_OPTIONS: () => FONT_OPTIONS,
+  FONT_SIZE_PX_MAX: () => FONT_SIZE_PX_MAX,
+  FONT_SIZE_PX_MIN: () => FONT_SIZE_PX_MIN,
+  ICON_LIBRARY_OPTIONS: () => ICON_LIBRARY_OPTIONS,
   NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS: () => NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS,
   NXDS_APPEARANCE_DATA_ATTRS: () => NXDS_APPEARANCE_DATA_ATTRS,
+  NXDS_THEME_FIELDS: () => NXDS_THEME_FIELDS,
   PALETTE_KEYS: () => PALETTE_KEYS,
   RUNTIME_LAYER_ORDER: () => RUNTIME_LAYER_ORDER,
   SEMANTIC_TOKEN_REGISTRY: () => SEMANTIC_TOKEN_REGISTRY,
@@ -42,6 +49,7 @@ __export(src_exports, {
   apcaLc: () => apcaLc,
   appearancePrefsToCss: () => appearancePrefsToCss,
   applyNxdsAppearance: () => applyNxdsAppearance,
+  applyNxdsThemeFlags: () => applyNxdsThemeFlags,
   createDefaultNxdsAppearanceSnapshot: () => createDefaultNxdsAppearanceSnapshot,
   createNxdsAppearanceBootstrapScript: () => createNxdsAppearanceBootstrapScript,
   createNxdsAppearanceSnapshot: () => createNxdsAppearanceSnapshot,
@@ -54,6 +62,7 @@ __export(src_exports, {
   isColor: () => isColor,
   measureThemeContrast: () => measureThemeContrast,
   normalizeAppearanceModeIds: () => normalizeAppearanceModeIds,
+  nxdsThemeFlags: () => nxdsThemeFlags,
   parseNxdsAppearanceStateCookie: () => parseNxdsAppearanceStateCookie,
   persistNxdsAppearance: () => persistNxdsAppearance,
   prefersDarkColorScheme: () => prefersDarkColorScheme,
@@ -65,6 +74,8 @@ __export(src_exports, {
   sanitizeNxdsAppearancePrefs: () => sanitizeNxdsAppearancePrefs,
   sanitizeNxdsAppearanceSnapshot: () => sanitizeNxdsAppearanceSnapshot,
   serializeNxdsAppearanceStateCookie: () => serializeNxdsAppearanceStateCookie,
+  shuffleNxdsAppearance: () => shuffleNxdsAppearance,
+  shuffleNxdsIconLibrary: () => shuffleNxdsIconLibrary,
   themeToCss: () => themeToCss,
   watchColorScheme: () => watchColorScheme
 });
@@ -2475,8 +2486,10 @@ function rampFromSeed(seedHex, options = {}) {
 }
 
 // src/lib/contrast.ts
+var CONTRAST_MIN = 0;
+var CONTRAST_MAX = 100;
 function normalizeContrast(value, fallback = 50) {
-  return typeof value === "number" && Number.isFinite(value) ? Math.round(Math.max(0, Math.min(100, value))) : fallback;
+  return typeof value === "number" && Number.isFinite(value) ? Math.round(Math.max(CONTRAST_MIN, Math.min(CONTRAST_MAX, value))) : fallback;
 }
 function contrastTarget(tier, contrast) {
   return TIER_THRESHOLDS[tier] + 15 * contrast / 100;
@@ -2668,6 +2681,7 @@ var DEFAULT_NXDS_APPEARANCE = {
   stroke: "normal",
   prefs: {
     uiFont: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+    headingFont: null,
     codeFont: 'ui-monospace, "SF Mono", Menlo, monospace',
     uiFontSize: 14,
     codeFontSize: 12,
@@ -2676,8 +2690,8 @@ var DEFAULT_NXDS_APPEARANCE = {
     fontSmoothing: false
   }
 };
-var FONT_PX_MIN = 8;
-var FONT_PX_MAX = 32;
+var FONT_SIZE_PX_MIN = 8;
+var FONT_SIZE_PX_MAX = 32;
 var APPEARANCE_MODES = /* @__PURE__ */ new Set([
   "light",
   "dark",
@@ -2703,7 +2717,7 @@ var FONT_FAMILY_UNSAFE = /[;{}<]/;
 var fontFamilyOr = (value, fallback) => typeof value === "string" && value.length > 0 && !FONT_FAMILY_UNSAFE.test(value) ? value : fallback;
 var boolOr = (value, fallback) => typeof value === "boolean" ? value : fallback;
 var enumOr = (value, values, fallback) => typeof value === "string" && values.has(value) ? value : fallback;
-var clampFontSize = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.min(FONT_PX_MAX, Math.max(FONT_PX_MIN, value)) : fallback;
+var clampFontSize = (value, fallback) => typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.min(FONT_SIZE_PX_MAX, Math.max(FONT_SIZE_PX_MIN, value)) : fallback;
 function formatPx(value) {
   return `${Number(value.toFixed(4))}px`;
 }
@@ -2754,6 +2768,7 @@ function sanitizeNxdsAppearancePrefs(raw) {
   const d = DEFAULT_NXDS_APPEARANCE.prefs;
   return {
     uiFont: fontFamilyOr(o.uiFont, d.uiFont),
+    headingFont: fontFamilyOr(o.headingFont, d.headingFont),
     codeFont: fontFamilyOr(o.codeFont, d.codeFont),
     uiFontSize: clampFontSize(o.uiFontSize, d.uiFontSize),
     codeFontSize: clampFontSize(o.codeFontSize, d.codeFontSize),
@@ -2800,6 +2815,7 @@ function appearancePrefsToCss(prefs) {
   const blocks = [
     inRuntimeLayer(`:root {
   --nx-typography-family-font-sans: ${prefs.uiFont};
+  --nx-typography-family-font-heading: ${prefs.headingFont ?? "var(--nx-typography-family-font-sans)"};
   --nx-typography-family-font-mono: ${prefs.codeFont};
 ${typographyScaleVariables(uiPx)}
 }`),
@@ -4900,6 +4916,127 @@ function findBrandColorPreset(color) {
   return BRAND_COLOR_PRESETS.find((preset) => preset.color === hex);
 }
 
+// src/lib/font-options.ts
+var SANS_FALLBACK = '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif';
+var SERIF_FALLBACK = "Georgia, serif";
+var MONO_FALLBACK = 'ui-monospace, "SF Mono", Menlo, monospace';
+var FONT_OPTIONS = [
+  {
+    value: "geist",
+    label: "Geist",
+    category: "sans",
+    family: `"Geist Variable", ${SANS_FALLBACK}`,
+    package: "@fontsource-variable/geist"
+  },
+  {
+    value: "inter",
+    label: "Inter",
+    category: "sans",
+    family: `"Inter Variable", ${SANS_FALLBACK}`,
+    package: "@fontsource-variable/inter"
+  },
+  {
+    value: "figtree",
+    label: "Figtree",
+    category: "sans",
+    family: `"Figtree Variable", ${SANS_FALLBACK}`,
+    package: "@fontsource-variable/figtree"
+  },
+  {
+    value: "dm-sans",
+    label: "DM Sans",
+    category: "sans",
+    family: `"DM Sans Variable", ${SANS_FALLBACK}`,
+    package: "@fontsource-variable/dm-sans"
+  },
+  {
+    value: "manrope",
+    label: "Manrope",
+    category: "sans",
+    family: `"Manrope Variable", ${SANS_FALLBACK}`,
+    package: "@fontsource-variable/manrope"
+  },
+  {
+    value: "ibm-plex-sans",
+    label: "IBM Plex Sans",
+    category: "sans",
+    family: `"IBM Plex Sans Variable", ${SANS_FALLBACK}`,
+    package: "@fontsource-variable/ibm-plex-sans"
+  },
+  {
+    value: "lora",
+    label: "Lora",
+    category: "serif",
+    family: `"Lora Variable", ${SERIF_FALLBACK}`,
+    package: "@fontsource-variable/lora"
+  },
+  {
+    value: "playfair-display",
+    label: "Playfair Display",
+    category: "serif",
+    family: `"Playfair Display Variable", ${SERIF_FALLBACK}`,
+    package: "@fontsource-variable/playfair-display"
+  },
+  {
+    value: "geist-mono",
+    label: "Geist Mono",
+    category: "mono",
+    family: `"Geist Mono Variable", ${MONO_FALLBACK}`,
+    package: "@fontsource-variable/geist-mono"
+  },
+  {
+    value: "jetbrains-mono",
+    label: "JetBrains Mono",
+    category: "mono",
+    family: `"JetBrains Mono Variable", ${MONO_FALLBACK}`,
+    package: "@fontsource-variable/jetbrains-mono"
+  }
+];
+
+// src/lib/icon-libraries.ts
+var ICON_LIBRARY_OPTIONS = [
+  { value: "phosphor", label: "Phosphor" },
+  { value: "lucide", label: "Lucide" },
+  { value: "tabler", label: "Tabler Icons" },
+  { value: "hugeicons", label: "HugeIcons" },
+  { value: "remix", label: "Remix Icon" }
+];
+var DEFAULT_ICON_LIBRARY = "phosphor";
+
+// src/lib/appearance-shuffle.ts
+function pick(options, random) {
+  const option = options[Math.floor(random() * options.length)];
+  if (option === void 0) throw new Error("No option to pick from.");
+  return option;
+}
+function shuffleNxdsAppearance(state, { fonts = FONT_OPTIONS, random = Math.random } = {}) {
+  const textFonts = fonts.filter((font) => font.category !== "mono").map((font) => font.family);
+  if (textFonts.length === 0) {
+    throw new Error(
+      "shuffleNxdsAppearance: `fonts` needs at least one sans or serif font."
+    );
+  }
+  return {
+    ...state,
+    brandColor: pick(BRAND_COLOR_PRESETS, random).color,
+    surfaceTone: pick(BASE_TONE_OPTIONS, random).value,
+    density: pick(DENSITY_OPTIONS, random).value,
+    corners: pick(CORNER_OPTIONS, random).value,
+    elevation: pick(ELEVATION_OPTIONS, random).value,
+    stroke: pick(STROKE_OPTIONS, random).value,
+    prefs: {
+      ...state.prefs,
+      uiFont: pick(textFonts, random),
+      headingFont: pick([null, ...textFonts], random)
+    }
+  };
+}
+function shuffleNxdsIconLibrary({
+  random = Math.random
+} = {}) {
+  return pick(ICON_LIBRARY_OPTIONS, random).value;
+}
+
 // src/lib/theme-contrast.ts
 var MODES = ["light", "dark"];
 var cssVar = (name) => `--nx-color-${name}`;
@@ -4925,6 +5062,211 @@ function measureThemeContrast(theme) {
   );
 }
 
+// src/lib/theme-fields.ts
+var DEFAULT_NXDS_THEME = {
+  appearance: DEFAULT_NXDS_APPEARANCE,
+  iconLibrary: DEFAULT_ICON_LIBRARY
+};
+function invalid(flag, value, accepted) {
+  return new Error(`--${flag} "${value}" isn't ${accepted}.`);
+}
+function withAppearance(theme, patch) {
+  return { ...theme, appearance: { ...theme.appearance, ...patch } };
+}
+function withPrefs(theme, patch) {
+  return withAppearance(theme, {
+    prefs: { ...theme.appearance.prefs, ...patch }
+  });
+}
+function oneOf(flag, values, value) {
+  const match = values.find((candidate) => candidate === value);
+  if (match === void 0) {
+    throw invalid(flag, value, `one of ${values.join(", ")}`);
+  }
+  return match;
+}
+function enumField(flag, key, description, values) {
+  return {
+    kind: "choice",
+    flag,
+    key,
+    description,
+    values,
+    read: (theme) => theme.appearance[key],
+    write: (theme, value) => withAppearance(theme, {
+      [key]: oneOf(flag, values, value)
+    })
+  };
+}
+function integer(flag, value, min, max) {
+  const parsed = Number(value);
+  if (!/^\d+$/.test(value) || parsed < min || parsed > max) {
+    throw invalid(flag, value, `a whole number from ${min} to ${max}`);
+  }
+  return parsed;
+}
+function contrastField(flag, key, description) {
+  return {
+    kind: "integer",
+    flag,
+    key,
+    description,
+    min: CONTRAST_MIN,
+    max: CONTRAST_MAX,
+    read: (theme) => String(theme.appearance[key]),
+    write: (theme, value) => withAppearance(theme, {
+      [key]: integer(flag, value, CONTRAST_MIN, CONTRAST_MAX)
+    })
+  };
+}
+function fontSizeField(flag, key, description) {
+  return {
+    kind: "integer",
+    flag,
+    key: `prefs.${key}`,
+    description,
+    min: FONT_SIZE_PX_MIN,
+    max: FONT_SIZE_PX_MAX,
+    read: (theme) => String(theme.appearance.prefs[key]),
+    write: (theme, value) => withPrefs(theme, {
+      [key]: integer(flag, value, FONT_SIZE_PX_MIN, FONT_SIZE_PX_MAX)
+    })
+  };
+}
+function fontField(flag, key, description, categories, fallback) {
+  const fonts = FONT_OPTIONS.filter(
+    (font) => categories.includes(font.category)
+  );
+  return {
+    kind: "font",
+    flag,
+    key: `prefs.${key}`,
+    description,
+    values: [fallback.value, ...fonts.map((font) => font.value)],
+    categories,
+    fallback,
+    read: (theme) => {
+      const family = theme.appearance.prefs[key];
+      if (family === fallback.family) return fallback.value;
+      return fonts.find((font) => font.family === family)?.value;
+    },
+    write: (theme, value) => {
+      const family = value === fallback.value ? fallback.family : fonts.find((font) => font.value === value)?.family;
+      if (family === void 0) {
+        throw invalid(
+          flag,
+          value,
+          `one of ${[fallback.value, ...fonts.map((font) => font.value)].join(", ")}`
+        );
+      }
+      return withPrefs(theme, { [key]: family });
+    }
+  };
+}
+var DEFAULT_PREFS = DEFAULT_NXDS_APPEARANCE.prefs;
+var TEXT_FONTS = ["sans", "serif"];
+var NXDS_THEME_FIELDS = [
+  {
+    kind: "color",
+    flag: "brand-color",
+    key: "brandColor",
+    description: 'brand color, as any CSS color, such as "#4f46e5"',
+    read: (theme) => theme.appearance.brandColor,
+    write: (theme, value) => {
+      if (!isColor(value)) throw invalid("brand-color", value, "a CSS color");
+      return withAppearance(theme, { brandColor: value });
+    }
+  },
+  enumField(
+    "surface-tone",
+    "surfaceTone",
+    "neutral tone of backgrounds and borders",
+    BASE_TONE_OPTIONS.map((option) => option.value)
+  ),
+  enumField(
+    "density",
+    "density",
+    "spacing and control size",
+    DENSITY_OPTIONS.map((option) => option.value)
+  ),
+  enumField(
+    "corners",
+    "corners",
+    "corner radius",
+    CORNER_OPTIONS.map((option) => option.value)
+  ),
+  enumField(
+    "elevation",
+    "elevation",
+    "shadow depth",
+    ELEVATION_OPTIONS.map((option) => option.value)
+  ),
+  enumField(
+    "stroke",
+    "stroke",
+    "border width",
+    STROKE_OPTIONS.map((option) => option.value)
+  ),
+  enumField("mode", "mode", "color scheme", ["light", "dark", "system"]),
+  contrastField(
+    "light-contrast",
+    "lightContrast",
+    "light mode contrast, 0 to 100"
+  ),
+  contrastField(
+    "dark-contrast",
+    "darkContrast",
+    "dark mode contrast, 0 to 100"
+  ),
+  fontField("font", "uiFont", "font for UI text", TEXT_FONTS, {
+    value: "system",
+    family: DEFAULT_PREFS.uiFont
+  }),
+  fontField(
+    "heading-font",
+    "headingFont",
+    'font for headings, or "ui" for the UI font',
+    TEXT_FONTS,
+    { value: "ui", family: null }
+  ),
+  fontField("code-font", "codeFont", "font for code", ["mono"], {
+    value: "system",
+    family: DEFAULT_PREFS.codeFont
+  }),
+  fontSizeField("font-size", "uiFontSize", "UI text size in px"),
+  fontSizeField("code-font-size", "codeFontSize", "code text size in px"),
+  {
+    kind: "choice",
+    flag: "icons",
+    description: "icon library nxds components draw",
+    values: ICON_LIBRARY_OPTIONS.map((option) => option.value),
+    read: (theme) => theme.iconLibrary,
+    write: (theme, value) => ({
+      ...theme,
+      iconLibrary: oneOf(
+        "icons",
+        ICON_LIBRARY_OPTIONS.map((option) => option.value),
+        value
+      )
+    })
+  }
+];
+function nxdsThemeFlags(theme) {
+  return NXDS_THEME_FIELDS.flatMap((field) => {
+    const value = field.read(theme);
+    if (value === void 0 || value === field.read(DEFAULT_NXDS_THEME)) {
+      return [];
+    }
+    return [{ flag: field.flag, value }];
+  });
+}
+function applyNxdsThemeFlags(theme, values) {
+  return NXDS_THEME_FIELDS.reduce((current, field) => {
+    const value = values[field.flag];
+    return value === void 0 ? current : field.write(current, value);
+  }, theme);
+}
+
 // src/lib/token-registry.ts
 var SURFACE_TOKEN_NAMES = [
   "background",
@@ -5075,12 +5417,19 @@ var SEMANTIC_TOKEN_REGISTRY = [
   CORNER_OPTIONS,
   DEFAULT_BRAND_COLOR,
   DEFAULT_COOKIE_KEY,
+  DEFAULT_ICON_LIBRARY,
   DEFAULT_NXDS_APPEARANCE,
+  DEFAULT_NXDS_THEME,
   DEFAULT_STORAGE_KEY,
   DENSITY_OPTIONS,
   ELEVATION_OPTIONS,
+  FONT_OPTIONS,
+  FONT_SIZE_PX_MAX,
+  FONT_SIZE_PX_MIN,
+  ICON_LIBRARY_OPTIONS,
   NXDS_APPEARANCE_COOKIE_MAX_AGE_SECONDS,
   NXDS_APPEARANCE_DATA_ATTRS,
+  NXDS_THEME_FIELDS,
   PALETTE_KEYS,
   RUNTIME_LAYER_ORDER,
   SEMANTIC_TOKEN_REGISTRY,
@@ -5091,6 +5440,7 @@ var SEMANTIC_TOKEN_REGISTRY = [
   apcaLc,
   appearancePrefsToCss,
   applyNxdsAppearance,
+  applyNxdsThemeFlags,
   createDefaultNxdsAppearanceSnapshot,
   createNxdsAppearanceBootstrapScript,
   createNxdsAppearanceSnapshot,
@@ -5103,6 +5453,7 @@ var SEMANTIC_TOKEN_REGISTRY = [
   isColor,
   measureThemeContrast,
   normalizeAppearanceModeIds,
+  nxdsThemeFlags,
   parseNxdsAppearanceStateCookie,
   persistNxdsAppearance,
   prefersDarkColorScheme,
@@ -5114,6 +5465,8 @@ var SEMANTIC_TOKEN_REGISTRY = [
   sanitizeNxdsAppearancePrefs,
   sanitizeNxdsAppearanceSnapshot,
   serializeNxdsAppearanceStateCookie,
+  shuffleNxdsAppearance,
+  shuffleNxdsIconLibrary,
   themeToCss,
   watchColorScheme
 });