@lessonkit/themes 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -1,17 +1,96 @@
-type LessonkitTheme = {
+type ThemeColorKey = "background" | "foreground" | "primary" | "muted" | "border" | "panel" | "danger" | "success" | "warning";
+type ThemeSpacingKey = "xs" | "sm" | "md" | "lg" | "xl";
+type ThemeTypographyKey = "fontFamily" | "fontSizeBase" | "lineHeightBase" | "fontWeightNormal" | "fontWeightStrong";
+type ThemeRadiusKey = "sm" | "md" | "lg";
+type ThemeShadowKey = "sm" | "md" | "lg";
+type LessonkitThemeColors = Record<ThemeColorKey, string> & {
+    extra?: Record<string, string>;
+};
+type LessonkitThemeSpacing = Record<ThemeSpacingKey, string>;
+type LessonkitThemeTypography = Record<ThemeTypographyKey, string>;
+type LessonkitThemeRadius = Record<ThemeRadiusKey, string>;
+type LessonkitThemeShadows = Record<ThemeShadowKey, string>;
+/** Full design token schema v1. */
+type LessonkitThemeV1 = {
     name: string;
-    colors?: {
-        background?: string;
-        foreground?: string;
-        primary?: string;
-        muted?: string;
-    };
-    radius?: {
-        sm?: string;
-        md?: string;
-        lg?: string;
-    };
+    colors: LessonkitThemeColors;
+    spacing: LessonkitThemeSpacing;
+    typography: LessonkitThemeTypography;
+    radius: LessonkitThemeRadius;
+    shadows: LessonkitThemeShadows;
+};
+/** @deprecated Use `LessonkitThemeV1` — alias kept for backward compatibility. */
+type LessonkitTheme = LessonkitThemeV1;
+type PartialLessonkitThemeV1 = {
+    name?: string;
+    colors?: Partial<LessonkitThemeColors>;
+    spacing?: Partial<LessonkitThemeSpacing>;
+    typography?: Partial<LessonkitThemeTypography>;
+    radius?: Partial<LessonkitThemeRadius>;
+    shadows?: Partial<LessonkitThemeShadows>;
+};
+type ThemeValidationIssue = {
+    path: string;
+    message: string;
+};
+type ThemeValidationResult = {
+    ok: true;
+    theme: LessonkitThemeV1;
+} | {
+    ok: false;
+    issues: ThemeValidationIssue[];
+};
+/** Validate a value as a complete `LessonkitThemeV1`. */
+declare function validateTheme(input: unknown): ThemeValidationResult;
+declare const REQUIRED_COLOR_KEYS: ThemeColorKey[];
+declare const REQUIRED_SPACING_KEYS: ThemeSpacingKey[];
+declare const REQUIRED_TYPOGRAPHY_KEYS: ThemeTypographyKey[];
+declare const REQUIRED_RADIUS_KEYS: ThemeRadiusKey[];
+declare const REQUIRED_SHADOW_KEYS: ThemeShadowKey[];
+
+/**
+ * Deep-merge theme objects left-to-right. Last writer wins for leaf token values.
+ */
+declare function mergeThemes(base: LessonkitThemeV1, ...overrides: (PartialLessonkitThemeV1 | undefined)[]): LessonkitThemeV1;
+
+/** Map a token path segment to kebab-case for CSS custom property names. */
+declare function tokenKeyToKebab(key: string): string;
+/** CSS custom property name for a color token (required keys). */
+declare function colorVarName(key: string): string;
+/** CSS custom property name for an extension color. */
+declare function colorExtraVarName(key: string): string;
+declare function spacingVarName(key: string): string;
+declare function typographyVarName(key: string): string;
+declare function radiusVarName(key: string): string;
+declare function shadowVarName(key: string): string;
+/**
+ * Convert a complete theme to a flat map of `--lk-*` CSS custom properties.
+ * Keys are sorted alphabetically for stable snapshots.
+ */
+declare function themeToCssVariables(theme: LessonkitThemeV1): Record<string, string>;
+/** Emit a `:root { ... }` or inline style declaration block. */
+declare function themeToCssDeclarationBlock(theme: LessonkitThemeV1, opts?: {
+    selector?: string;
+}): string;
+
+declare const defaultTheme: LessonkitThemeV1;
+declare const lightTheme: LessonkitThemeV1;
+declare const darkTheme: LessonkitThemeV1;
+/** Brand deltas merged onto the active mode palette (light/dark). */
+declare const brandThemeOverrides: PartialLessonkitThemeV1;
+/** Full dark reference palette for `getPresetTheme("brand")` and catalog validation. */
+declare const brandTheme: LessonkitThemeV1;
+type ThemePresetName = "default" | "light" | "dark" | "brand";
+declare function getPresetTheme(preset: ThemePresetName): LessonkitThemeV1;
+
+type ThemeCatalogEntry = {
+    tokenPath: string;
+    cssVariable: string;
+    type: "color" | "spacing" | "typography" | "radius" | "shadow" | "color-extra";
+    required: boolean;
+    description: string;
 };
-declare const defaultTheme: LessonkitTheme;
+/** Enumerable catalog of themeable tokens (v1). */
+declare function buildThemeCatalog(): ThemeCatalogEntry[];
 
-export { type LessonkitTheme, defaultTheme };
+export { type LessonkitTheme, type LessonkitThemeColors, type LessonkitThemeRadius, type LessonkitThemeShadows, type LessonkitThemeSpacing, type LessonkitThemeTypography, type LessonkitThemeV1, type PartialLessonkitThemeV1, REQUIRED_COLOR_KEYS, REQUIRED_RADIUS_KEYS, REQUIRED_SHADOW_KEYS, REQUIRED_SPACING_KEYS, REQUIRED_TYPOGRAPHY_KEYS, type ThemeCatalogEntry, type ThemeColorKey, type ThemePresetName, type ThemeRadiusKey, type ThemeShadowKey, type ThemeSpacingKey, type ThemeTypographyKey, type ThemeValidationIssue, type ThemeValidationResult, brandTheme, brandThemeOverrides, buildThemeCatalog, colorExtraVarName, colorVarName, darkTheme, defaultTheme, getPresetTheme, lightTheme, mergeThemes, radiusVarName, shadowVarName, spacingVarName, themeToCssDeclarationBlock, themeToCssVariables, tokenKeyToKebab, typographyVarName, validateTheme };

package/dist/index.js

@@ -1,18 +1,426 @@
-// src/index.ts
+// src/schema.ts
+var COLOR_KEYS = [
+  "background",
+  "foreground",
+  "primary",
+  "muted",
+  "border",
+  "panel",
+  "danger",
+  "success",
+  "warning"
+];
+var SPACING_KEYS = ["xs", "sm", "md", "lg", "xl"];
+var TYPOGRAPHY_KEYS = [
+  "fontFamily",
+  "fontSizeBase",
+  "lineHeightBase",
+  "fontWeightNormal",
+  "fontWeightStrong"
+];
+var RADIUS_KEYS = ["sm", "md", "lg"];
+var SHADOW_KEYS = ["sm", "md", "lg"];
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+function validateRequiredGroup(group, value, keys, issues) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    issues.push({ path: group, message: "must be an object" });
+    return null;
+  }
+  const obj = value;
+  const out = {};
+  for (const key of keys) {
+    const v = obj[key];
+    if (!isNonEmptyString(v)) {
+      issues.push({ path: `${group}.${key}`, message: "required non-empty string" });
+    } else {
+      out[key] = v;
+    }
+  }
+  return out;
+}
+function validateColorsExtra(value, issues) {
+  if (value === void 0) return void 0;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    issues.push({ path: "colors.extra", message: "must be an object when provided" });
+    return void 0;
+  }
+  const extra = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (!isNonEmptyString(v)) {
+      issues.push({ path: `colors.extra.${k}`, message: "must be a non-empty string" });
+    } else {
+      extra[k] = v;
+    }
+  }
+  return extra;
+}
+function validateTheme(input) {
+  const issues = [];
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    return { ok: false, issues: [{ path: "", message: "theme must be an object" }] };
+  }
+  const raw = input;
+  if (!isNonEmptyString(raw.name)) {
+    issues.push({ path: "name", message: "required non-empty string" });
+  }
+  const colorsBase = validateRequiredGroup("colors", raw.colors, COLOR_KEYS, issues);
+  let colorsExtra;
+  if (raw.colors !== null && typeof raw.colors === "object" && !Array.isArray(raw.colors)) {
+    colorsExtra = validateColorsExtra(raw.colors.extra, issues);
+  }
+  const spacing = validateRequiredGroup("spacing", raw.spacing, SPACING_KEYS, issues);
+  const typography = validateRequiredGroup("typography", raw.typography, TYPOGRAPHY_KEYS, issues);
+  const radius = validateRequiredGroup("radius", raw.radius, RADIUS_KEYS, issues);
+  const shadows = validateRequiredGroup("shadows", raw.shadows, SHADOW_KEYS, issues);
+  if (issues.length > 0) {
+    return { ok: false, issues };
+  }
+  const colors = { ...colorsBase };
+  if (colorsExtra && Object.keys(colorsExtra).length > 0) {
+    colors.extra = colorsExtra;
+  }
+  return {
+    ok: true,
+    theme: {
+      name: raw.name,
+      colors,
+      spacing,
+      typography,
+      radius,
+      shadows
+    }
+  };
+}
+var REQUIRED_COLOR_KEYS = COLOR_KEYS;
+var REQUIRED_SPACING_KEYS = SPACING_KEYS;
+var REQUIRED_TYPOGRAPHY_KEYS = TYPOGRAPHY_KEYS;
+var REQUIRED_RADIUS_KEYS = RADIUS_KEYS;
+var REQUIRED_SHADOW_KEYS = SHADOW_KEYS;
+
+// src/merge.ts
+function mergeExtra(base, override) {
+  if (!base && !override) return void 0;
+  return { ...base, ...override };
+}
+function mergeColors(base, override) {
+  if (!override) return base;
+  const { extra: overrideExtra, ...rest } = override;
+  const merged = { ...base, ...rest };
+  const extra = mergeExtra(base.extra, overrideExtra);
+  if (extra) merged.extra = extra;
+  else delete merged.extra;
+  return merged;
+}
+function mergeGroup(base, override) {
+  if (!override) return base;
+  return { ...base, ...override };
+}
+function mergeThemes(base, ...overrides) {
+  let result = { ...base };
+  for (const o of overrides) {
+    if (!o) continue;
+    result = {
+      name: o.name ?? result.name,
+      colors: mergeColors(result.colors, o.colors),
+      spacing: mergeGroup(result.spacing, o.spacing),
+      typography: mergeGroup(result.typography, o.typography),
+      radius: mergeGroup(result.radius, o.radius),
+      shadows: mergeGroup(result.shadows, o.shadows)
+    };
+  }
+  return result;
+}
+
+// src/cssVariables.ts
+function tokenKeyToKebab(key) {
+  return key.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+function colorVarName(key) {
+  return `--lk-color-${tokenKeyToKebab(key)}`;
+}
+function colorExtraVarName(key) {
+  return `--lk-color-extra-${tokenKeyToKebab(key)}`;
+}
+function spacingVarName(key) {
+  return `--lk-space-${key}`;
+}
+function typographyVarName(key) {
+  return `--lk-${tokenKeyToKebab(key)}`;
+}
+function radiusVarName(key) {
+  return `--lk-radius-${key}`;
+}
+function shadowVarName(key) {
+  return `--lk-shadow-${key}`;
+}
+function themeToCssVariables(theme) {
+  const vars = {};
+  for (const [key, value] of Object.entries(theme.colors)) {
+    if (key === "extra" && value && typeof value === "object") {
+      for (const [ek, ev] of Object.entries(value)) {
+        vars[colorExtraVarName(ek)] = ev;
+      }
+    } else if (key !== "extra") {
+      vars[colorVarName(key)] = value;
+    }
+  }
+  for (const [key, value] of Object.entries(theme.spacing)) {
+    vars[spacingVarName(key)] = value;
+  }
+  for (const [key, value] of Object.entries(theme.typography)) {
+    vars[typographyVarName(key)] = value;
+  }
+  for (const [key, value] of Object.entries(theme.radius)) {
+    vars[radiusVarName(key)] = value;
+  }
+  for (const [key, value] of Object.entries(theme.shadows)) {
+    vars[shadowVarName(key)] = value;
+  }
+  const sorted = {};
+  for (const key of Object.keys(vars).sort()) {
+    sorted[key] = vars[key];
+  }
+  return sorted;
+}
+function themeToCssDeclarationBlock(theme, opts) {
+  const selector = opts?.selector ?? ":root";
+  const vars = themeToCssVariables(theme);
+  const body = Object.entries(vars).map(([k, v]) => `  ${k}: ${v};`).join("\n");
+  return `${selector} {
+${body}
+}`;
+}
+
+// src/presets.ts
+var sharedTypography = {
+  fontFamily: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif',
+  fontSizeBase: "16px",
+  lineHeightBase: "1.55",
+  fontWeightNormal: "400",
+  fontWeightStrong: "700"
+};
+var sharedSpacing = {
+  xs: "4px",
+  sm: "8px",
+  md: "12px",
+  lg: "18px",
+  xl: "24px"
+};
+var sharedRadius = {
+  sm: "6px",
+  md: "10px",
+  lg: "16px"
+};
 var defaultTheme = {
   name: "default",
   colors: {
     background: "#ffffff",
     foreground: "#111827",
     primary: "#2563eb",
-    muted: "#6b7280"
+    muted: "#6b7280",
+    border: "rgba(17, 24, 39, 0.12)",
+    panel: "rgba(17, 24, 39, 0.04)",
+    danger: "#dc2626",
+    success: "#16a34a",
+    warning: "#d97706"
+  },
+  spacing: { ...sharedSpacing },
+  typography: { ...sharedTypography },
+  radius: { ...sharedRadius },
+  shadows: {
+    sm: "0 1px 2px rgba(0, 0, 0, 0.06)",
+    md: "0 8px 24px rgba(17, 24, 39, 0.12)",
+    lg: "0 18px 50px rgba(17, 24, 39, 0.14)"
+  }
+};
+var lightTheme = {
+  name: "light",
+  colors: {
+    background: "#f7f8ff",
+    foreground: "rgba(17, 24, 39, 0.92)",
+    primary: "#2563eb",
+    muted: "rgba(17, 24, 39, 0.64)",
+    border: "rgba(17, 24, 39, 0.12)",
+    panel: "rgba(17, 24, 39, 0.04)",
+    danger: "#e11d48",
+    success: "#059669",
+    warning: "#d97706",
+    extra: {
+      accent: "#22d3ee",
+      "panel-strong": "rgba(17, 24, 39, 0.06)"
+    }
   },
-  radius: {
-    sm: "6px",
-    md: "10px",
-    lg: "14px"
+  spacing: { ...sharedSpacing },
+  typography: { ...sharedTypography },
+  radius: { ...sharedRadius },
+  shadows: {
+    sm: "0 1px 2px rgba(17, 24, 39, 0.08)",
+    md: "0 8px 24px rgba(17, 24, 39, 0.1)",
+    lg: "0 18px 50px rgba(17, 24, 39, 0.14)"
   }
 };
+var darkTheme = {
+  name: "dark",
+  colors: {
+    background: "#0b1020",
+    foreground: "rgba(255, 255, 255, 0.92)",
+    primary: "#7c3aed",
+    muted: "rgba(255, 255, 255, 0.68)",
+    border: "rgba(255, 255, 255, 0.14)",
+    panel: "rgba(255, 255, 255, 0.08)",
+    danger: "#fb7185",
+    success: "#34d399",
+    warning: "#fbbf24",
+    extra: {
+      accent: "#22d3ee",
+      "panel-strong": "rgba(255, 255, 255, 0.12)"
+    }
+  },
+  spacing: { ...sharedSpacing },
+  typography: { ...sharedTypography },
+  radius: { ...sharedRadius },
+  shadows: {
+    sm: "0 1px 2px rgba(0, 0, 0, 0.2)",
+    md: "0 12px 32px rgba(0, 0, 0, 0.28)",
+    lg: "0 18px 50px rgba(0, 0, 0, 0.35)"
+  }
+};
+var brandThemeOverrides = {
+  name: "brand",
+  colors: {
+    primary: "#7c3aed",
+    extra: {
+      accent: "#22d3ee"
+    }
+  }
+};
+var brandTheme = mergeThemes(darkTheme, brandThemeOverrides);
+var PRESETS = {
+  default: defaultTheme,
+  light: lightTheme,
+  dark: darkTheme,
+  brand: brandTheme
+};
+function getPresetTheme(preset) {
+  return PRESETS[preset];
+}
+
+// src/catalog.ts
+var COLOR_DESCRIPTIONS = {
+  background: "Page and shell background",
+  foreground: "Primary text color",
+  primary: "Brand and interactive accent",
+  muted: "Secondary text and hints",
+  border: "Borders and dividers",
+  panel: "Card and panel surfaces",
+  danger: "Errors and high-risk states",
+  success: "Success and positive feedback",
+  warning: "Warnings and caution states"
+};
+var SPACING_DESCRIPTIONS = {
+  xs: "Extra-small spacing",
+  sm: "Small spacing",
+  md: "Medium spacing",
+  lg: "Large spacing",
+  xl: "Extra-large spacing"
+};
+var TYPOGRAPHY_DESCRIPTIONS = {
+  fontFamily: "Base font stack",
+  fontSizeBase: "Base font size",
+  lineHeightBase: "Base line height",
+  fontWeightNormal: "Normal text weight",
+  fontWeightStrong: "Headings and emphasis weight"
+};
+var RADIUS_DESCRIPTIONS = {
+  sm: "Small corner radius",
+  md: "Medium corner radius",
+  lg: "Large corner radius"
+};
+var SHADOW_DESCRIPTIONS = {
+  sm: "Small elevation shadow",
+  md: "Medium elevation shadow",
+  lg: "Large elevation shadow"
+};
+function buildThemeCatalog() {
+  const entries = [];
+  for (const key of REQUIRED_COLOR_KEYS) {
+    entries.push({
+      tokenPath: `colors.${key}`,
+      cssVariable: colorVarName(key),
+      type: "color",
+      required: true,
+      description: COLOR_DESCRIPTIONS[key] ?? `Color token: ${key}`
+    });
+  }
+  entries.push({
+    tokenPath: "colors.extra.*",
+    cssVariable: "--lk-color-extra-{key}",
+    type: "color-extra",
+    required: false,
+    description: "Optional extension colors (non-stable until 1.0)"
+  });
+  for (const key of REQUIRED_SPACING_KEYS) {
+    entries.push({
+      tokenPath: `spacing.${key}`,
+      cssVariable: spacingVarName(key),
+      type: "spacing",
+      required: true,
+      description: SPACING_DESCRIPTIONS[key] ?? `Spacing token: ${key}`
+    });
+  }
+  for (const key of REQUIRED_TYPOGRAPHY_KEYS) {
+    entries.push({
+      tokenPath: `typography.${key}`,
+      cssVariable: typographyVarName(key),
+      type: "typography",
+      required: true,
+      description: TYPOGRAPHY_DESCRIPTIONS[key] ?? `Typography token: ${key}`
+    });
+  }
+  for (const key of REQUIRED_RADIUS_KEYS) {
+    entries.push({
+      tokenPath: `radius.${key}`,
+      cssVariable: radiusVarName(key),
+      type: "radius",
+      required: true,
+      description: RADIUS_DESCRIPTIONS[key] ?? `Radius token: ${key}`
+    });
+  }
+  for (const key of REQUIRED_SHADOW_KEYS) {
+    entries.push({
+      tokenPath: `shadows.${key}`,
+      cssVariable: shadowVarName(key),
+      type: "shadow",
+      required: true,
+      description: SHADOW_DESCRIPTIONS[key] ?? `Shadow token: ${key}`
+    });
+  }
+  return entries;
+}
 export {
-  defaultTheme
+  REQUIRED_COLOR_KEYS,
+  REQUIRED_RADIUS_KEYS,
+  REQUIRED_SHADOW_KEYS,
+  REQUIRED_SPACING_KEYS,
+  REQUIRED_TYPOGRAPHY_KEYS,
+  brandTheme,
+  brandThemeOverrides,
+  buildThemeCatalog,
+  colorExtraVarName,
+  colorVarName,
+  darkTheme,
+  defaultTheme,
+  getPresetTheme,
+  lightTheme,
+  mergeThemes,
+  radiusVarName,
+  shadowVarName,
+  spacingVarName,
+  themeToCssDeclarationBlock,
+  themeToCssVariables,
+  tokenKeyToKebab,
+  typographyVarName,
+  validateTheme
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/themes",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": false,
   "description": "Theme primitives and tokens for LessonKit.",
   "license": "Apache-2.0",
@@ -27,17 +27,23 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./theme-contract.v1.json": "./theme-contract.v1.json",
+    "./theme-catalog.v1.json": "./theme-catalog.v1.json",
+    "./base.css": "./base.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "theme-contract.v1.json",
+    "theme-catalog.v1.json",
+    "base.css"
   ],
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "vitest run --passWithNoTests",
+    "test": "vitest run",
     "test:coverage": "vitest run --coverage --passWithNoTests=false",
     "lint": "echo \"(no lint configured yet)\""
   },