@alacris/ui 0.0.0 → 0.1.1

package/src/motion/animate.js

@@ -0,0 +1,145 @@
+// Motion — one ergonomic layer over the Web Animations API.
+//
+// Principles:
+//   - Durations and easings come from the motion tokens, so JS-driven motion
+//     obeys the theme's `motion.scale` exactly like CSS transitions do —
+//     `animate(el, fx.fadeIn, { duration: 'medium2' })` resolves the token at
+//     call time.
+//   - `prefers-reduced-motion` is honored everywhere: animations jump to their
+//     end state instead of playing. CSS transitions get the same guard from
+//     `base.js`.
+//   - No timeouts, no rAF bookkeeping: WAAPI runs off the main thread where
+//     the browser can manage it, and `.finished` sequences the rest.
+
+import { DURATIONS, EASINGS } from '../tokens/system.js';
+
+const camelToToken = (s) => s.replace(/([A-Z]|\d+$)/g, (c) => '-' + c.toLowerCase());
+
+/** True when the user asked for reduced motion (checked live). */
+export const prefersReducedMotion = () =>
+  typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+/**
+ * Resolve a duration token ('medium2', 'extraLong1') to milliseconds, reading
+ * the live CSS token so a theme's motion scale applies. Numbers pass through.
+ */
+export function duration(key) {
+  if (typeof key === 'number') return key;
+  const token = camelToToken(key);
+  if (typeof getComputedStyle === 'function') {
+    const raw = getComputedStyle(document.documentElement).getPropertyValue(`--ui-duration-${token}`);
+    const ms = parseFloat(raw);
+    if (!Number.isNaN(ms)) return ms;
+  }
+  return DURATIONS[token] ?? 200;
+}
+
+/** Resolve an easing token ('standard', 'emphasizedDecelerate') to its curve. */
+export const easing = (key) => EASINGS[camelToToken(key)] || key;
+
+/**
+ * animate(el, keyframes, { duration: 'short4'|ms, easing: 'standard'|curve,
+ *                          fill: 'both', ...WAAPI options })
+ *
+ * Returns the Animation. Under reduced motion the animation still runs (so
+ * `.finished` chains keep working) but with ~zero duration — the element
+ * simply lands in its final state.
+ */
+export function animate(el, keyframes, opts = {}) {
+  const { duration: d = 'short4', easing: e = 'standard', fill = 'both', ...rest } = opts;
+  // Environments without WAAPI (simulated DOMs in tests) get an
+  // already-finished stand-in so `.finished` sequencing still works.
+  if (typeof el?.animate !== 'function') {
+    return { finished: Promise.resolve(), cancel() {}, finish() {}, play() {}, pause() {} };
+  }
+  const ms = prefersReducedMotion() ? 1 : duration(d);
+  const run = () => {
+    const frames = typeof keyframes === 'function' ? keyframes(el) : keyframes;
+    const anim = el.animate(frames, { duration: ms, easing: easing(e), fill, ...rest });
+    anim.finished.catch(() => {}); // cancellation is normal control flow, not an error
+    // Hidden/occluded tabs freeze the animation timeline, which would leave
+    // `.finished` chains (presence unmounts, `closed` events, snackbar queues)
+    // waiting forever. setTimeout still ticks there, so force-finish on the
+    // wall clock; in a visible tab the animation wins the race and this no-ops.
+    const delay = Number(rest.delay) || 0;
+    const guard = setTimeout(() => {
+      try { if (anim.playState === 'running' || anim.pending) anim.finish(); } catch { /* infinite/cancelled */ }
+    }, ms + delay + 100);
+    anim.finished.then(() => clearTimeout(guard), () => clearTimeout(guard));
+    return anim;
+  };
+  if (el.isConnected) return run();
+
+  // A `ref` fires while the element is still in its render fragment, before
+  // insertion. An animation created on a disconnected subtree can wedge with
+  // its first keyframe applied but its timeline never advancing — so start on
+  // the next frame, once the element is in the document. The facade keeps
+  // `.finished`/`.cancel` working either way. If rAF never fires (hidden tab),
+  // the wall-clock fallback settles without animating — the element simply
+  // rests in its CSS end state.
+  let anim = null;
+  let cancelled = false;
+  let started = false;
+  let settle;
+  const finished = new Promise((resolve) => (settle = resolve));
+  const start = () => {
+    if (cancelled || started) return;
+    started = true;
+    if (!el.isConnected) return settle();
+    anim = run();
+    anim.finished.then(settle, () => settle());
+  };
+  requestAnimationFrame(start);
+  const fallback = setTimeout(() => (started ? null : (started = true, settle())), ms + 200);
+  finished.then(() => clearTimeout(fallback));
+  return {
+    finished,
+    cancel() { cancelled = true; anim?.cancel(); settle(); },
+    finish() { anim?.finish(); },
+    play() { anim?.play(); },
+    pause() { anim?.pause(); },
+  };
+}
+
+/** Await an animation without throwing when it is cancelled mid-flight. */
+export const settled = (anim) => anim.finished.catch(() => {});
+
+// ------------------------------------------------------------------ presets
+//
+// Keyframe presets tuned to the Material motion spec. Enter presets pair with
+// 'emphasizedDecelerate', exits with 'emphasizedAccelerate' — `animate`'s
+// defaults are fine for simple fades.
+
+export const fx = {
+  fadeIn: [{ opacity: 0 }, { opacity: 1 }],
+  fadeOut: [{ opacity: 1 }, { opacity: 0 }],
+  // 0.8 is the MD3 container-transform start scale (dialogs, menus).
+  scaleIn: [{ opacity: 0, transform: 'scale(0.8)' }, { opacity: 1, transform: 'scale(1)' }],
+  scaleOut: [{ opacity: 1, transform: 'scale(1)' }, { opacity: 0, transform: 'scale(0.8)' }],
+  slideInUp: [{ opacity: 0, transform: 'translateY(16px)' }, { opacity: 1, transform: 'translateY(0)' }],
+  slideOutDown: [{ opacity: 1, transform: 'translateY(0)' }, { opacity: 0, transform: 'translateY(16px)' }],
+  slideInDown: [{ opacity: 0, transform: 'translateY(-16px)' }, { opacity: 1, transform: 'translateY(0)' }],
+  slideOutUp: [{ opacity: 1, transform: 'translateY(0)' }, { opacity: 0, transform: 'translateY(-16px)' }],
+  expandDown: (el) => {
+    const h = el?.scrollHeight || 0;
+    return [
+      { blockSize: '0px', opacity: 0, overflow: 'hidden' },
+      { blockSize: `${h}px`, opacity: 1, overflow: 'hidden' },
+    ];
+  },
+  collapseUp: (el) => {
+    const h = el?.offsetHeight || el?.scrollHeight || 0;
+    return [
+      { blockSize: `${h}px`, opacity: 1, overflow: 'hidden' },
+      { blockSize: '0px', opacity: 0, overflow: 'hidden' },
+    ];
+  },
+  slideInLeft: [{ transform: 'translateX(-100%)' }, { transform: 'translateX(0)' }],
+  slideOutLeft: [{ transform: 'translateX(0)' }, { transform: 'translateX(-100%)' }],
+  slideInRight: [{ transform: 'translateX(100%)' }, { transform: 'translateX(0)' }],
+  slideOutRight: [{ transform: 'translateX(0)' }, { transform: 'translateX(100%)' }],
+  // Bottom-sheet cover: the panel travels its full height, not a 16px nudge.
+  sheetIn: [{ transform: 'translateY(100%)' }, { transform: 'translateY(0)' }],
+  sheetOut: [{ transform: 'translateY(0)' }, { transform: 'translateY(100%)' }],
+  collapse: [{ blockSize: 'var(--ui-collapse-size, auto)', opacity: 1 }, { blockSize: '0', opacity: 0 }],
+};

package/src/motion/flip.js

@@ -0,0 +1,46 @@
+// withFlip — animate a list reorder with the FLIP technique.
+//
+// Alacris's `each` moves the DOM nodes that changed position, synchronously.
+// Wrap the mutation and every child that moved glides to its new place;
+// children that appeared fade in. (Removed children are already gone by the
+// time we can look — exits inside a hot list are a deliberate non-goal; use
+// `presence` for individually dismissable items.)
+//
+//   withFlip(listEl, () => state.rows.sort(byName));
+//
+// Keyed by node identity, which is exactly what `each` keeps stable.
+
+import { animate, fx } from './animate.js';
+
+/**
+ * withFlip(container, mutate, { duration, easing, stagger })
+ * Returns whatever `mutate` returns.
+ */
+export function withFlip(container, mutate, opts = {}) {
+  const before = new Map();
+  for (const el of container.children) before.set(el, el.getBoundingClientRect());
+
+  const result = mutate();
+
+  let i = 0;
+  for (const el of container.children) {
+    const was = before.get(el);
+    const delay = opts.stagger ? i++ * opts.stagger : 0;
+    if (!was) {
+      animate(el, fx.fadeIn, { duration: opts.duration ?? 'medium1', delay, fill: 'backwards' });
+      continue;
+    }
+    const now = el.getBoundingClientRect();
+    const dx = was.left - now.left;
+    const dy = was.top - now.top;
+    if (dx || dy) {
+      animate(el, [{ transform: `translate(${dx}px, ${dy}px)` }, { transform: 'none' }], {
+        duration: opts.duration ?? 'medium3',
+        easing: opts.easing ?? 'emphasized',
+        delay,
+        fill: 'backwards',
+      });
+    }
+  }
+  return result;
+}

package/src/motion/index.js

@@ -0,0 +1,4 @@
+export { animate, settled, duration, easing, fx, prefersReducedMotion } from './animate.js';
+export { presence } from './presence.js';
+export { withFlip } from './flip.js';
+export { ripple } from './ripple.js';

package/src/motion/presence.js

@@ -0,0 +1,104 @@
+// presence — enter/exit animation for conditional templates.
+//
+// Alacris removes a conditional subtree the instant its condition turns false,
+// which is correct — and too soon for an exit animation. `presence` gives a
+// condition a lifecycle: mount + enter animation when it becomes truthy, exit
+// animation *then* unmount when it becomes falsy.
+//
+//   setup({ open }) {
+//     return html`
+//       <div class="host">
+//         ${presence(open, () => html`<div class="sheet">…</div>`, {
+//           enter: fx.slideInUp,
+//           exit: fx.slideOutDown,
+//         })}
+//       </div>`;
+//   }
+//
+// The returned node is a `display: contents` anchor, so it is invisible to
+// layout. Call `presence` in a child position during `setup` (or under an
+// active `root()`), because it creates an effect that must be owned.
+
+import { effect, onCleanup, render } from '@alacris/core';
+import { animate, fx } from './animate.js';
+
+/**
+ * presence(when, view, opts)
+ *
+ *   when  — signal/thunk; truthy shows the view
+ *   view  — () => template (rebuilt fresh on every entry)
+ *   opts  — enter, exit: keyframes or false to disable (default fade)
+ *           enterDuration/exitDuration, enterEasing/exitEasing: token names
+ *           target: CSS selector for the element to animate (default: the
+ *                   view's first element)
+ *           onEntered: called after the enter animation finishes
+ *           onExited: called after the exit animation finishes
+ */
+export function presence(when, view, opts = {}) {
+  const anchor = document.createElement('span');
+  anchor.style.display = 'contents';
+
+  const enterFx = opts.enter === false ? null : opts.enter || fx.fadeIn;
+  const exitFx = opts.exit === false ? null : opts.exit || fx.fadeOut;
+  const target = () => (opts.target ? anchor.querySelector(opts.target) : anchor.firstElementChild);
+
+  let dispose = null; // active render
+  let exiting = null; // in-flight exit animation
+
+  effect(() => {
+    const show = !!when();
+    if (show) {
+      // Re-entering while the exit plays: cut it short and remount fresh.
+      if (exiting) {
+        exiting.cancel();
+        exiting = null;
+        dispose?.();
+        dispose = null;
+      }
+      if (!dispose) {
+        dispose = render(view(), anchor);
+        const el = target();
+        if (el && enterFx) {
+          const anim = animate(el, enterFx, {
+            duration: opts.enterDuration ?? 'medium2',
+            easing: opts.enterEasing ?? 'emphasizedDecelerate',
+          });
+          anim.finished.then(() => {
+            try { anim.cancel(); } catch {}
+            opts.onEntered?.();
+          }, () => {});
+        } else if (opts.onEntered) {
+          opts.onEntered();
+        }
+      }
+    } else if (dispose && !exiting) {
+      const el = target();
+      const done = () => {
+        if (!exiting) return; // re-entry already tore this down
+        exiting = null;
+        dispose?.();
+        dispose = null;
+        opts.onExited?.();
+      };
+      if (el && exitFx) {
+        exiting = animate(el, exitFx, {
+          duration: opts.exitDuration ?? 'short4',
+          easing: opts.exitEasing ?? 'emphasizedAccelerate',
+        });
+        exiting.finished.then(done, () => {});
+      } else {
+        dispose();
+        dispose = null;
+      }
+    }
+  });
+
+  onCleanup(() => {
+    exiting?.cancel();
+    exiting = null;
+    dispose?.();
+    dispose = null;
+  });
+
+  return anchor;
+}

package/src/motion/ripple.js

@@ -0,0 +1,108 @@
+// ripple — the Material press ripple.
+//
+// Attach it to any positioned element (the conventions' `.control` recipe sets
+// `position: relative`); it appends a clipped overlay and expands a wave from
+// the pointer on press, from the center on keyboard activation. Colors ride
+// `currentColor` at the pressed-state opacity token, so the ripple is always
+// legible on its surface and themes with everything else. Reduced motion gets
+// an instant press tint instead of a wave (handled inside `animate`).
+//
+//   html`<button class="control" ref=${(el) => ripple(el, { disabled })}>…`
+
+import { animate, settled } from './animate.js';
+
+/**
+ * ripple(el, { disabled, centered })
+ *
+ *   disabled — boolean or thunk/signal; suppresses new ripples while truthy
+ *   centered — always expand from the center (icon buttons, switches)
+ *
+ * Idempotent per element. Returns the element for ref-chaining.
+ */
+export function ripple(el, opts = {}) {
+  if (el.__uiRipple) return el;
+  el.__uiRipple = 1;
+
+  const holder = document.createElement('span');
+  holder.setAttribute('aria-hidden', 'true');
+  Object.assign(holder.style, {
+    position: 'absolute',
+    inset: '0',
+    overflow: 'hidden',
+    borderRadius: 'inherit',
+    pointerEvents: 'none',
+  });
+  el.append(holder);
+
+  const off = () =>
+    (typeof opts.disabled === 'function' ? !!opts.disabled() : !!opts.disabled) || el.disabled;
+
+  let release = null;
+
+  const spawn = (clientX, clientY, centered) => {
+    const rect = el.getBoundingClientRect();
+    const w = rect.width || 48;
+    const h = rect.height || 48;
+    const cx = centered ? w / 2 : clientX - rect.left;
+    const cy = centered ? h / 2 : clientY - rect.top;
+    // Soft-edge padding matches material-web: the wave slightly overruns the
+    // container so the edge never looks clipped at rest.
+    const radius = Math.hypot(Math.max(cx, w - cx), Math.max(cy, h - cy)) + 10;
+
+    const dot = document.createElement('span');
+    Object.assign(dot.style, {
+      position: 'absolute',
+      left: `${cx - radius}px`,
+      top: `${cy - radius}px`,
+      width: `${radius * 2}px`,
+      height: `${radius * 2}px`,
+      borderRadius: '50%',
+      background: 'currentColor',
+      opacity: 'var(--ui-state-pressed, 0.1)',
+      willChange: 'transform, opacity',
+    });
+    holder.append(dot);
+
+    const pressedAt = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    // material-web: grow from 20% of the final size over 450ms (long1) with
+    // standard easing; stay visible at least 225ms (short4 + a beat).
+    const grow = animate(dot, [{ transform: 'scale(0.2)' }, { transform: 'scale(1)' }], {
+      duration: 'long1',
+      easing: 'standard',
+    });
+
+    let released = false;
+    release = () => {
+      if (released) return;
+      released = true;
+      const elapsed = (typeof performance !== 'undefined' ? performance.now() : Date.now()) - pressedAt;
+      const rest = Math.max(0, 225 - elapsed);
+      const fade = () => {
+        const out = animate(dot, [{ opacity: 'var(--ui-state-pressed, 0.1)' }, { opacity: '0' }], {
+          duration: 'medium1',
+          easing: 'linear',
+        });
+        settled(out).then(() => dot.remove());
+      };
+      Promise.all([settled(grow), rest ? new Promise((r) => setTimeout(r, rest)) : null]).then(fade);
+    };
+  };
+
+  el.addEventListener('pointerdown', (e) => {
+    if (off() || e.button !== 0) return;
+    spawn(e.clientX, e.clientY, opts.centered);
+    const done = () => release?.();
+    window.addEventListener('pointerup', done, { once: true });
+    window.addEventListener('pointercancel', done, { once: true });
+  });
+
+  el.addEventListener('keydown', (e) => {
+    if (off() || e.repeat) return;
+    if (e.key === 'Enter' || e.key === ' ') {
+      spawn(0, 0, true);
+      window.addEventListener('keyup', () => release?.(), { once: true });
+    }
+  });
+
+  return el;
+}

package/src/theme/apply-theme.js

@@ -0,0 +1,142 @@
+// applyTheme — one constructed stylesheet for the whole design system.
+//
+// All tokens live on `:root`, so they inherit through every shadow boundary
+// and a re-theme is a single `replaceSync` — no component re-renders, no
+// sheet re-adoption, every element on the page updates at once.
+//
+// Scheme selection is layered so the same sheet serves all three modes:
+//   - light tokens on `:root` (the default)
+//   - dark tokens under `prefers-color-scheme: dark` unless the app pinned
+//     light (`<html data-ui-scheme="light">`)
+//   - dark tokens whenever the app pinned dark (`data-ui-scheme="dark"`)
+
+import { signal, computed } from '@alacris/core';
+import { createTheme } from './create-theme.js';
+
+// `color-scheme` is a real CSS property riding along in the token map (it
+// keeps scrollbars and form controls in scheme); everything else gets `--ui-`.
+const decl = (name, value) => (name === 'color-scheme' ? name : `--ui-${name}`) + `:${value};`;
+
+const block = (tokens) => {
+  let s = '';
+  for (const name in tokens) s += decl(name, tokens[name]);
+  return s;
+};
+
+// Face on `:root` so native text and un-typed markup inherit the system
+// plain typeface. Components then set a type-role shorthand on top.
+const FACE = 'font-family:var(--ui-font-plain);font-optical-sizing:auto;font-synthesis:none;';
+
+export function themeCss(theme) {
+  const { common, schemes } = theme;
+  return [
+    `:root{${FACE}${block(common)}${block(schemes.light)}}`,
+    `:root[data-ui-scheme="dark"]{${block(schemes.dark)}}`,
+    `@media (prefers-color-scheme: dark){:root:not([data-ui-scheme="light"]){${block(schemes.dark)}}}`,
+  ].join('\n');
+}
+
+let sheet = null;
+let styleEl = null;
+
+/** The currently applied theme (a signal; null until applyTheme runs). */
+export const activeTheme = signal(null);
+
+/**
+ * Apply a theme to the document. Accepts a theme from `createTheme` or a
+ * config object (which is passed through `createTheme` for you). Calling it
+ * again rewrites the same stylesheet in place.
+ *
+ * Faces referenced by the theme are loaded automatically (a Google Fonts
+ * stylesheet for presets and `family` names). Pass `loadFonts: false` to
+ * skip — useful when the files are self-hosted or already on the page.
+ */
+export function applyTheme(themeOrConfig = {}) {
+  const theme = themeOrConfig.schemes ? themeOrConfig : createTheme(themeOrConfig);
+  const text = themeCss(theme);
+  if (!sheet && !styleEl) {
+    if (document.adoptedStyleSheets && typeof CSSStyleSheet.prototype.replaceSync === 'function') {
+      sheet = new CSSStyleSheet();
+      document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+    } else {
+      styleEl = document.createElement('style');
+      document.head.append(styleEl);
+    }
+  }
+  if (sheet) sheet.replaceSync(text);
+  else styleEl.textContent = text;
+  loadThemeFonts(themeOrConfig.loadFonts === false ? { fonts: { href: null } } : theme);
+  activeTheme.set(theme);
+  return theme;
+}
+
+const FONT_ATTR = 'data-ui-font';
+const PRECONNECT_ATTR = 'data-ui-font-preconnect';
+
+/**
+ * Sync the document's typeface stylesheet to `theme.fonts.href`. A null href
+ * removes a previously injected link. Safe to call repeatedly; one `<link>`
+ * is reused in place. Constructed stylesheets cannot `@import`, so this is a
+ * real element — the same one `themeCss` consumers add by hand for static CSS.
+ */
+export function loadThemeFonts(theme, doc = document) {
+  const head = doc?.head;
+  if (!head) return;
+  const href = theme?.fonts?.href || null;
+  const existing = head.querySelector(`link[${FONT_ATTR}]`);
+  if (!href) {
+    existing?.remove();
+    return;
+  }
+  if (/fonts\.googleapis\.com|fonts\.gstatic\.com/.test(href)) ensurePreconnect(head);
+  if (existing) {
+    if (existing.getAttribute('href') !== href) existing.setAttribute('href', href);
+    return;
+  }
+  const link = doc.createElement('link');
+  link.rel = 'stylesheet';
+  link.setAttribute('href', href);
+  link.setAttribute(FONT_ATTR, '');
+  head.append(link);
+}
+
+function ensurePreconnect(head) {
+  if (head.querySelector(`link[${PRECONNECT_ATTR}]`)) return;
+  for (const href of ['https://fonts.googleapis.com', 'https://fonts.gstatic.com']) {
+    const l = head.ownerDocument.createElement('link');
+    l.rel = 'preconnect';
+    l.href = href;
+    if (href.includes('gstatic')) l.crossOrigin = 'anonymous';
+    l.setAttribute(PRECONNECT_ATTR, '');
+    head.append(l);
+  }
+}
+
+// ------------------------------------------------------------------ scheme
+
+/** 'light' | 'dark' | 'auto' — what the app asked for. */
+export const schemePreference = signal('auto');
+
+const prefersDark =
+  typeof matchMedia === 'function' ? matchMedia('(prefers-color-scheme: dark)') : null;
+const osDark = signal(!!prefersDark?.matches);
+prefersDark?.addEventListener?.('change', (e) => osDark.set(e.matches));
+
+/** The scheme actually in effect right now: 'light' | 'dark'. */
+export const scheme = computed(() => {
+  const pref = schemePreference();
+  return pref === 'auto' ? (osDark() ? 'dark' : 'light') : pref;
+});
+
+/** Pin the scheme, or return to following the OS with 'auto'. */
+export function setScheme(pref /* 'light' | 'dark' | 'auto' */) {
+  schemePreference.set(pref);
+  const el = document.documentElement;
+  if (pref === 'auto') el.removeAttribute('data-ui-scheme');
+  else el.setAttribute('data-ui-scheme', pref);
+}
+
+/** Flip between light and dark (leaves 'auto' by pinning the opposite). */
+export function toggleScheme() {
+  setScheme(scheme() === 'dark' ? 'light' : 'dark');
+}

package/src/theme/create-theme.js

@@ -0,0 +1,70 @@
+// createTheme — one config object in, complete token maps out.
+//
+// A theme is data: `{ config, palettes, common, schemes, fonts }`
+// where `common` and each scheme are flat maps of token name (without the
+// `--ui-` prefix) → CSS value, and `fonts` is `{ href, preset }` for the
+// typeface stylesheet `applyTheme` injects. `applyTheme` turns that into one
+// document-level stylesheet; nothing here touches the DOM, so themes can be
+// built, diffed, serialized, or generated ahead of time.
+
+import { makePalettes, makeScheme, COLOR_ROLES } from '../tokens/color.js';
+import { typographyTokens, resolveTypography } from '../tokens/typography.js';
+import {
+  shapeTokens, elevationTokens, motionTokens, spacingTokens,
+  stateTokens, focusTokens, zTokens, densityTokens,
+} from '../tokens/system.js';
+
+const kebab = (s) => s.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+
+/**
+ * createTheme({
+ *   seed: '#e8ad18',               // one color → a whole scheme, or:
+ *   colors: { primary, secondary, tertiary, neutral, neutralVariant,
+ *             error, success, warning, info },   // explicit palette seeds
+ *   typography: 'google-sans-flex' | 'google-sans' | 'roboto' | 'system'
+ *               | { preset, family, brand, plain, code, scale, load },
+ *   shape: { radius },             // multiplier: 0 = square, 2 = extra round
+ *   motion: { scale },             // 0 = instant, 1 = default
+ *   density: 0,                    // 0 … -2 (each step: -4px control height)
+ *   overrides: {                   // raw token overrides, applied last
+ *     common: { 'radius-md': '10px' },
+ *     light:  { 'color-primary': '#0b57d0' },
+ *     dark:   { 'color-surface': '#101014' },
+ *   },
+ * })
+ */
+export function createTheme(config = {}) {
+  const palettes = makePalettes(config);
+  const type = resolveTypography(config.typography);
+
+  const common = {
+    ...typographyTokens(type),
+    ...shapeTokens(config.shape),
+    ...elevationTokens(),
+    ...motionTokens(config.motion),
+    ...spacingTokens(),
+    ...stateTokens(),
+    ...focusTokens(),
+    ...zTokens(),
+    ...densityTokens(config),
+    ...(config.overrides?.common || {}),
+  };
+
+  const schemeTokens = (scheme) => {
+    const roles = makeScheme(palettes, scheme);
+    const out = {};
+    for (const role of COLOR_ROLES) out[`color-${kebab(role)}`] = roles[role];
+    // Deepen shadows on dark surfaces, keep native widgets in scheme.
+    out['shadow-rgb'] = '0 0 0';
+    out['color-scheme'] = scheme;
+    return { ...out, ...(config.overrides?.[scheme] || {}) };
+  };
+
+  return {
+    config,
+    palettes,
+    common,
+    schemes: { light: schemeTokens('light'), dark: schemeTokens('dark') },
+    fonts: { href: type.href, preset: type.preset },
+  };
+}

package/src/theme/index.js

@@ -0,0 +1,5 @@
+export { createTheme } from './create-theme.js';
+export {
+  applyTheme, themeCss, activeTheme, loadThemeFonts,
+  scheme, schemePreference, setScheme, toggleScheme,
+} from './apply-theme.js';