@awc-ui/theme 1.0.0-beta

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@awc-ui/theme",
+  "version": "1.0.0-beta",
+  "description": "MD3 theme generation and application utilities for AWC UI",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.mjs",
+      "default": "./dist/worker.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@material/material-color-utilities": "^0.4.0",
+    "esbuild": "^0.25.12",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "material-design",
+    "md3",
+    "theme",
+    "color"
+  ],
+  "license": "MIT",
+  "author": "AWC UI",
+  "homepage": "https://awc-ui.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awc-ui/core.git",
+    "directory": "packages/theme"
+  },
+  "bugs": {
+    "url": "https://github.com/awc-ui/core/issues"
+  },
+  "module": "./dist/index.mjs",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && esbuild src/index.ts --bundle --format=esm --target=es2020 --sourcemap --outfile=dist/index.mjs && esbuild src/worker.ts --bundle --format=esm --target=es2020 --sourcemap --outfile=dist/worker.mjs",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/apply-font.ts

@@ -0,0 +1,47 @@
+import { TYPESCALE_SLOTS } from './types';
+
+const GOOGLE_FONT_FAMILIES = new Set([
+  'Roboto',
+  'Inter',
+  'Open Sans',
+  'Lato',
+  'Poppins',
+  'Nunito',
+  'Montserrat',
+  'Source Sans 3',
+]);
+
+function fontStack(fontFamily: string): string {
+  const trimmed = fontFamily.trim();
+  if (!trimmed) return 'Roboto, sans-serif';
+  return trimmed.includes(',') ? trimmed : `${trimmed}, sans-serif`;
+}
+
+/** Set all 15 --md-sys-typescale-*-font-family tokens on an element. */
+export function applyFontFamily(element: HTMLElement, fontFamily: string): void {
+  const stack = fontStack(fontFamily);
+  for (const slot of TYPESCALE_SLOTS) {
+    element.style.setProperty(`--md-sys-typescale-${slot}-font-family`, stack);
+  }
+}
+
+/**
+ * Inject or update a Google Fonts stylesheet for common font choices.
+ * Custom font family strings are applied via CSS vars only (no network fetch).
+ */
+export function loadGoogleFont(fontFamily: string): void {
+  const primary = fontFamily.split(',')[0].trim();
+  if (!GOOGLE_FONT_FAMILIES.has(primary)) return;
+
+  const id = 'awc-ui-dynamic-font';
+  let link = document.getElementById(id) as HTMLLinkElement | null;
+  if (!link) {
+    link = document.createElement('link');
+    link.id = id;
+    link.rel = 'stylesheet';
+    document.head.appendChild(link);
+  }
+
+  const family = primary.replace(/ /g, '+');
+  link.href = `https://fonts.googleapis.com/css2?family=${family}:wght@300;400;500;600;700&display=swap`;
+}

package/src/apply-theme.ts

@@ -0,0 +1,31 @@
+import { generateCss } from './generate-css';
+import { tokenName } from './token-name';
+import { ROLE_KEYS, type RoleMap, type ThemeComputeResult } from './types';
+
+/** Apply generated MD3 color role tokens as inline CSS custom properties on an element. */
+export function applyThemeRoles(element: HTMLElement, roles: RoleMap): void {
+  for (const [role, hex] of Object.entries(roles)) {
+    element.style.setProperty(`--md-sys-color-${tokenName(role)}`, hex);
+  }
+}
+
+/** Remove inline MD3 color role overrides so stylesheet / data-theme tokens can apply. */
+export function clearThemeRoles(element: HTMLElement): void {
+  for (const role of ROLE_KEYS) {
+    element.style.removeProperty(`--md-sys-color-${tokenName(role)}`);
+  }
+}
+
+/** Inject or update a stylesheet with light (:root) and dark ([data-theme="dark"]) role tokens. */
+export function applyThemeStylesheet(
+  theme: ThemeComputeResult,
+  styleId = 'awc-ui-dynamic-theme',
+): void {
+  let styleEl = document.getElementById(styleId) as HTMLStyleElement | null;
+  if (!styleEl) {
+    styleEl = document.createElement('style');
+    styleEl.id = styleId;
+    document.head.appendChild(styleEl);
+  }
+  styleEl.textContent = generateCss(theme);
+}

package/src/compute-theme.ts

@@ -0,0 +1,102 @@
+import {
+  argbFromHex,
+  hexFromArgb,
+  Hct,
+  TonalPalette,
+  DynamicScheme,
+  Variant,
+} from '@material/material-color-utilities';
+import {
+  ROLE_KEYS,
+  type PaletteKey,
+  type RoleKey,
+  type RoleMap,
+  type ThemeComputeRequest,
+  type ThemeComputeResult,
+} from './types';
+
+const TONES = [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100] as const;
+const NEUTRAL_CHROMA = 4;
+const NEUTRAL_VARIANT_CHROMA = 8;
+
+function paletteToTones(palette: TonalPalette): Record<number, string> {
+  const out: Record<number, string> = {};
+  for (const tone of TONES) {
+    out[tone] = hexFromArgb(palette.tone(tone)).toUpperCase();
+  }
+  return out;
+}
+
+function rolesFromScheme(scheme: DynamicScheme): RoleMap {
+  const out = {} as RoleMap;
+  for (const key of ROLE_KEYS) {
+    const argb = (scheme as unknown as Record<string, number>)[key];
+    out[key] = hexFromArgb(argb).toUpperCase();
+  }
+  return out;
+}
+
+/** Generate MD3 tonal palettes and role-mapped tokens for light and dark mode. */
+export function computeTheme(req: ThemeComputeRequest): ThemeComputeResult {
+  const start = performance.now();
+
+  const primaryArgb = argbFromHex(req.primaryHex);
+  const primaryHct = Hct.fromInt(primaryArgb);
+  const primary = TonalPalette.fromHct(primaryHct);
+
+  const secondary = req.secondaryHex
+    ? TonalPalette.fromHct(Hct.fromInt(argbFromHex(req.secondaryHex)))
+    : TonalPalette.fromHueAndChroma(primaryHct.hue, 16);
+
+  const tertiary = req.tertiaryHex
+    ? TonalPalette.fromHct(Hct.fromInt(argbFromHex(req.tertiaryHex)))
+    : TonalPalette.fromHueAndChroma(primaryHct.hue + 60, 24);
+
+  const neutral = TonalPalette.fromHueAndChroma(primaryHct.hue, NEUTRAL_CHROMA);
+  const neutralVariant = TonalPalette.fromHueAndChroma(
+    primaryHct.hue,
+    NEUTRAL_VARIANT_CHROMA,
+  );
+
+  const tones: Record<PaletteKey, Record<number, string>> = {
+    primary: paletteToTones(primary),
+    secondary: paletteToTones(secondary),
+    tertiary: paletteToTones(tertiary),
+    neutral: paletteToTones(neutral),
+    neutralVariant: paletteToTones(neutralVariant),
+  };
+
+  const requestedLevel =
+    typeof req.contrastLevel === 'number' && Number.isFinite(req.contrastLevel)
+      ? req.contrastLevel
+      : 0;
+  const contrastLevel = Math.max(-1, Math.min(1, requestedLevel));
+
+  const buildScheme = (isDark: boolean) =>
+    new DynamicScheme({
+      sourceColorHct: primaryHct,
+      variant: Variant.TONAL_SPOT,
+      contrastLevel,
+      isDark,
+      primaryPalette: primary,
+      secondaryPalette: secondary,
+      tertiaryPalette: tertiary,
+      neutralPalette: neutral,
+      neutralVariantPalette: neutralVariant,
+    });
+
+  const light = rolesFromScheme(buildScheme(false));
+  const dark = rolesFromScheme(buildScheme(true));
+
+  return {
+    tones,
+    roles: { light, dark },
+    sources: {
+      primary: req.primaryHex.toUpperCase(),
+      secondary: req.secondaryHex?.toUpperCase() ?? '',
+      tertiary: req.tertiaryHex?.toUpperCase() ?? '',
+    },
+    contrastLevel,
+    durationMs: Math.round((performance.now() - start) * 100) / 100,
+  };
+}

package/src/generate-css.ts

@@ -0,0 +1,36 @@
+import { tokenName } from './token-name';
+import type { ThemeComputeResult } from './types';
+
+/** Format a computed theme as a drop-in CSS file overriding @awc-ui/tokens defaults. */
+export function generateCss(result: ThemeComputeResult): string {
+  const now = new Date().toISOString();
+  const { sources, roles } = result;
+  const lines: string[] = [
+    '/*!',
+    ' * AWC UI — Material Design 3 theme',
+    ` * Generated: ${now}`,
+    ' * Source colors:',
+    `   primary:   ${sources.primary}`,
+    `   secondary: ${sources.secondary}`,
+    `   tertiary:  ${sources.tertiary}`,
+    ' *',
+    ' * Drop this file after @awc-ui/tokens to override the default theme.',
+    ' * Toggle dark mode by setting [data-theme="dark"] on <html> or any ancestor.',
+    ' */',
+    '',
+    ':root {',
+  ];
+
+  for (const [role, hex] of Object.entries(roles.light)) {
+    lines.push(`  --md-sys-color-${tokenName(role)}: ${hex};`);
+  }
+
+  lines.push('}', '', '[data-theme="dark"] {');
+
+  for (const [role, hex] of Object.entries(roles.dark)) {
+    lines.push(`  --md-sys-color-${tokenName(role)}: ${hex};`);
+  }
+
+  lines.push('}', '');
+  return lines.join('\n');
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { computeTheme } from './compute-theme';
+export { applyThemeRoles, applyThemeStylesheet, clearThemeRoles } from './apply-theme';
+export { applyFontFamily, loadGoogleFont } from './apply-font';
+export { generateCss } from './generate-css';
+export { tokenName } from './token-name';
+export {
+  ROLE_KEYS,
+  DEFAULT_SEED_COLORS,
+  DEFAULT_FONT_FAMILY,
+  TYPESCALE_SLOTS,
+} from './types';
+export type {
+  PaletteKey,
+  RoleKey,
+  RoleMap,
+  ThemeComputeRequest,
+  ThemeComputeResult,
+  ThemeWorkerRequest,
+  ThemeWorkerResponse,
+} from './types';

package/src/token-name.ts

@@ -0,0 +1,4 @@
+/** Convert camelCase MD3 role names to kebab-case CSS token suffixes. */
+export function tokenName(role: string): string {
+  return role.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}

package/src/types.ts

@@ -0,0 +1,102 @@
+export type PaletteKey =
+  | 'primary'
+  | 'secondary'
+  | 'tertiary'
+  | 'neutral'
+  | 'neutralVariant';
+
+/** MD3 role names — matches --md-sys-color-* tokens and DynamicScheme getters. */
+export const ROLE_KEYS = [
+  'primary',
+  'onPrimary',
+  'primaryContainer',
+  'onPrimaryContainer',
+  'inversePrimary',
+  'secondary',
+  'onSecondary',
+  'secondaryContainer',
+  'onSecondaryContainer',
+  'tertiary',
+  'onTertiary',
+  'tertiaryContainer',
+  'onTertiaryContainer',
+  'error',
+  'onError',
+  'errorContainer',
+  'onErrorContainer',
+  'background',
+  'onBackground',
+  'surface',
+  'onSurface',
+  'surfaceVariant',
+  'onSurfaceVariant',
+  'surfaceContainerLowest',
+  'surfaceContainerLow',
+  'surfaceContainer',
+  'surfaceContainerHigh',
+  'surfaceContainerHighest',
+  'surfaceDim',
+  'surfaceBright',
+  'outline',
+  'outlineVariant',
+  'inverseSurface',
+  'inverseOnSurface',
+  'shadow',
+  'scrim',
+  'surfaceTint',
+] as const;
+
+export type RoleKey = (typeof ROLE_KEYS)[number];
+export type RoleMap = Record<RoleKey, string>;
+
+export type ThemeComputeRequest = {
+  primaryHex: string;
+  secondaryHex?: string;
+  tertiaryHex?: string;
+  /**
+   * MD3 contrast level passed to DynamicScheme.
+   * -1 reduced, 0 standard (default), 0.5 medium, 1 high contrast.
+   */
+  contrastLevel?: number;
+};
+
+export type ThemeComputeResult = {
+  tones: Record<PaletteKey, Record<number, string>>;
+  roles: { light: RoleMap; dark: RoleMap };
+  sources: { primary: string; secondary: string; tertiary: string };
+  contrastLevel: number;
+  durationMs: number;
+};
+
+export type ThemeWorkerRequest = ThemeComputeRequest & { type: 'compute' };
+
+export type ThemeWorkerResponse =
+  | ({ type: 'palette' } & ThemeComputeResult)
+  | { type: 'error'; message: string };
+
+export const DEFAULT_SEED_COLORS = {
+  primary: '#6750A4',
+  secondary: '#625B71',
+  tertiary: '#7D5260',
+} as const;
+
+export const DEFAULT_FONT_FAMILY = 'Roboto';
+
+/** All 15 MD3 typescale slots that expose a font-family token. */
+export const TYPESCALE_SLOTS = [
+  'display-large',
+  'display-medium',
+  'display-small',
+  'headline-large',
+  'headline-medium',
+  'headline-small',
+  'title-large',
+  'title-medium',
+  'title-small',
+  'label-large',
+  'label-medium',
+  'label-small',
+  'body-large',
+  'body-medium',
+  'body-small',
+] as const;

package/src/worker.ts

@@ -0,0 +1,38 @@
+/// <reference lib="webworker" />
+/**
+ * Theme Generator Web Worker
+ *
+ * Off-main-thread HCT computation for responsive color-picker drag.
+ * Messages in:  { type: 'compute', primaryHex, secondaryHex?, tertiaryHex? }
+ * Messages out: { type: 'palette', tones, roles, sources, durationMs }
+ *               { type: 'error', message }
+ */
+import { computeTheme } from './compute-theme';
+import type { ThemeWorkerRequest, ThemeWorkerResponse } from './types';
+
+self.addEventListener('message', (e: MessageEvent<ThemeWorkerRequest>) => {
+  try {
+    if (!e.data || e.data.type !== 'compute') {
+      const response: ThemeWorkerResponse = {
+        type: 'error',
+        message: `Unexpected message type: ${(e.data as { type?: string })?.type ?? 'undefined'}`,
+      };
+      (self as unknown as Worker).postMessage(response);
+      return;
+    }
+
+    const { type: _type, ...request } = e.data;
+    const result = computeTheme(request);
+    const response: ThemeWorkerResponse = {
+      type: 'palette',
+      ...result,
+    };
+    (self as unknown as Worker).postMessage(response);
+  } catch (err) {
+    const response: ThemeWorkerResponse = {
+      type: 'error',
+      message: err instanceof Error ? err.message : 'Unknown error',
+    };
+    (self as unknown as Worker).postMessage(response);
+  }
+});