@dreamboard-games/ui-sdk 0.0.41

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,252 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import { themeToCssVars } from "./css-vars.js";
+import { arcadeTheme } from "./presets/arcade.js";
+import { studioTheme } from "./presets/studio.js";
+import { tabletopTheme } from "./presets/tabletop.js";
+import { mergeTheme, type Theme, type ThemeOverride } from "./tokens.js";
+
+/**
+ * The set of preset theme ids ships in `@dreamboard/ui-sdk`. Authors
+ * may register additional ones by passing a fully-resolved {@link Theme}
+ * instead of an id.
+ */
+export type ThemePresetId = "tabletop" | "arcade" | "studio";
+
+const PRESETS: Readonly<Record<ThemePresetId, Theme>> = {
+  tabletop: tabletopTheme,
+  arcade: arcadeTheme,
+  studio: studioTheme,
+};
+
+/**
+ * Resolve a preset id (or a full theme) into a {@link Theme}.
+ *
+ * Used internally by {@link ThemeProvider}; exported so authors who
+ * compose at the call site (e.g. for a side-by-side preview) can do
+ * the same resolution without mounting a provider.
+ */
+export function resolveTheme(input: ThemePresetId | Theme | undefined): Theme {
+  if (!input) return tabletopTheme;
+  if (typeof input === "string") {
+    const preset = PRESETS[input];
+    if (!preset) {
+      throw new Error(
+        `[ui-sdk] Unknown theme preset "${input}". Pass a full Theme object or one of: ${Object.keys(
+          PRESETS,
+        ).join(", ")}.`,
+      );
+    }
+    return preset;
+  }
+  return input;
+}
+
+/** Look up a registered preset by id. Returns `undefined` if missing. */
+export function getThemePreset(id: ThemePresetId): Theme | undefined {
+  return PRESETS[id];
+}
+
+/**
+ * Subset returned by {@link useTheme} — the resolved theme plus a
+ * stable copy of its CSS-variable map so consumers can reuse it (for
+ * example, to apply tokens to a portal that escapes the provider).
+ */
+export interface ThemeContextValue {
+  /** Fully resolved theme. */
+  readonly theme: Theme;
+  /** CSS-var map consumable as `style` on a wrapper. */
+  readonly cssVars: CSSProperties;
+}
+
+const ThemeCtx = createContext<ThemeContextValue | null>(null);
+
+export interface ThemeProviderProps {
+  /**
+   * Preset id, a full {@link Theme}, or omitted to use the `tabletop`
+   * default.
+   */
+  theme?: ThemePresetId | Theme;
+  /**
+   * Deep-partial overrides merged onto the resolved base theme. Use
+   * for one-off tweaks (e.g. swapping the player palette per game)
+   * without writing a full theme.
+   */
+  override?: ThemeOverride;
+  /**
+   * Render mode for reduced-motion enforcement.
+   *
+   * - `auto` (default): respect the user's OS-level preference via
+   *   `prefers-reduced-motion: reduce`.
+   * - `force`: force `motion.reducedMotion = "true"` regardless of the
+   *   OS preference (useful for screenshot CI).
+   * - `ignore`: never override motion (use only when the embedding
+   *   shell already decides motion behaviour).
+   */
+  reducedMotion?: "auto" | "force" | "ignore";
+  /**
+   * Where to mount the wrapper. `block` (default) renders a `div` and
+   * applies the CSS variables to it. `none` skips the wrapper entirely
+   * — only useful when the parent is already a Dreamboard provider and
+   * just needs to publish a different sub-tree (rare).
+   */
+  as?: "block" | "none";
+  /** Extra style merged after the CSS-var map. */
+  style?: CSSProperties;
+  /** Extra className for the wrapper. */
+  className?: string;
+  children: ReactNode;
+}
+
+function usePrefersReducedMotion(): boolean {
+  const [prefers, setPrefers] = useState(false);
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const media = window.matchMedia("(prefers-reduced-motion: reduce)");
+    setPrefers(media.matches);
+    const handle = (event: MediaQueryListEvent) => setPrefers(event.matches);
+    media.addEventListener("change", handle);
+    return () => media.removeEventListener("change", handle);
+  }, []);
+  return prefers;
+}
+
+/**
+ * Mounts a Dreamboard theme. The provider:
+ *
+ * 1. Resolves the preset (or accepts a full theme).
+ * 2. Applies any deep-partial `override`.
+ * 3. Optionally clamps `motion.reducedMotion` to `"true"` based on the
+ *    OS-level preference (or a forced override).
+ * 4. Serialises the resolved theme into CSS variables on a wrapper
+ *    element so descendants can read tokens via `useTheme()` *or* via
+ *    `var(--db-...)` references in their own CSS / Tailwind.
+ *
+ * Defaults such as `<GameLayout>` mount this for you with the configured
+ * theme; mount it manually only when you need a sub-tree to use a different
+ * theme (e.g. a dark sheet over a light layout).
+ */
+export function ThemeProvider({
+  theme: themeInput,
+  override,
+  reducedMotion = "auto",
+  as = "block",
+  style,
+  className,
+  children,
+}: ThemeProviderProps) {
+  const prefersReduced = usePrefersReducedMotion();
+
+  const value = useMemo<ThemeContextValue>(() => {
+    const base = resolveTheme(themeInput);
+    const merged = mergeTheme(base, override);
+    const motionResolved =
+      reducedMotion === "force"
+        ? "true"
+        : reducedMotion === "ignore"
+          ? merged.motion.reducedMotion
+          : prefersReduced
+            ? "true"
+            : merged.motion.reducedMotion;
+    const final: Theme =
+      motionResolved === merged.motion.reducedMotion
+        ? merged
+        : {
+            ...merged,
+            motion: { ...merged.motion, reducedMotion: motionResolved },
+          };
+    return { theme: final, cssVars: themeToCssVars(final) };
+  }, [themeInput, override, reducedMotion, prefersReduced]);
+
+  if (as === "none") {
+    return <ThemeCtx.Provider value={value}>{children}</ThemeCtx.Provider>;
+  }
+
+  const wrapperStyle: CSSProperties = {
+    ...themeToShadcnVars(value.theme),
+    ...value.cssVars,
+    fontFamily: value.theme.typography.fontFamily.body,
+    ...style,
+  };
+
+  return (
+    <ThemeCtx.Provider value={value}>
+      <div
+        data-dreamboard-theme={value.theme.meta.id}
+        data-dreamboard-mode={value.theme.meta.mode}
+        data-dreamboard-reduced-motion={value.theme.motion.reducedMotion}
+        className={className}
+        style={wrapperStyle}
+      >
+        {children}
+      </div>
+    </ThemeCtx.Provider>
+  );
+}
+
+/**
+ * Read the active {@link Theme} from a {@link ThemeProvider} ancestor.
+ *
+ * Falls back to the `tabletop` preset (with no overrides) when called
+ * outside a provider — components remain renderable in isolated tests
+ * and Storybook/Cosmos fixtures without a wrapping shell.
+ */
+export function useTheme(): Theme {
+  const ctx = useContext(ThemeCtx);
+  return ctx?.theme ?? tabletopTheme;
+}
+
+/**
+ * Read the {@link CSSProperties} that publish the active theme as CSS
+ * variables. Useful when porting a theme into a portal or drawer that
+ * is rendered outside the provider's DOM subtree.
+ */
+export function useThemeCssVars(): CSSProperties {
+  const ctx = useContext(ThemeCtx);
+  if (ctx) return { ...themeToShadcnVars(ctx.theme), ...ctx.cssVars };
+  // Match the fallback theme exposed by `useTheme()`.
+  return {
+    ...themeToShadcnVars(tabletopTheme),
+    ...themeToCssVars(tabletopTheme),
+  };
+}
+
+export { ThemeCtx };
+
+type CssVariableStyle = CSSProperties & {
+  [K in `--${string}`]?: string | number;
+};
+
+function themeToShadcnVars(theme: Theme): CSSProperties {
+  const vars: CssVariableStyle = {
+    "--background": theme.semantic.surface.app,
+    "--foreground": theme.semantic.text.primary,
+    "--card": theme.semantic.surface.card,
+    "--card-foreground": theme.semantic.text.primary,
+    "--popover": theme.semantic.surface.sheet,
+    "--popover-foreground": theme.semantic.text.primary,
+    "--primary": theme.semantic.intent.primary.solid,
+    "--primary-foreground": theme.semantic.intent.primary.on,
+    "--secondary": theme.semantic.intent.secondary.solid,
+    "--secondary-foreground": theme.semantic.intent.secondary.on,
+    "--muted": theme.semantic.surface.inset,
+    "--muted-foreground": theme.semantic.text.muted,
+    "--accent": theme.semantic.intent.info.soft,
+    "--accent-foreground": theme.semantic.intent.info.onSoft,
+    "--destructive": theme.semantic.intent.danger.solid,
+    "--destructive-foreground": theme.semantic.intent.danger.on,
+    "--border": theme.semantic.border.default,
+    "--input": theme.semantic.border.default,
+    "--ring": theme.semantic.border.focus,
+    "--font-sans": theme.typography.fontFamily.body,
+    "--font-display": theme.typography.fontFamily.display,
+  };
+  return vars;
+}

package/src/theme/board.ts

@@ -0,0 +1,61 @@
+/**
+ * Board theming helpers.
+ *
+ * The SDK's board renderers (`<HexGrid>`, `<SquareGrid>`,
+ * `<NetworkGraph>`, `<ZoneMap>`, `<TrackBoard>`, `<SlotSystem>`) need a
+ * tiny but consistent set of visual tokens — frame border, frame fill,
+ * eligible-target hint, and active hover ring — so authors don't have
+ * to re-pick colours per board. {@link useBoardTheme} exposes those
+ * tokens, derived from the active {@link Theme}.
+ */
+
+import { useMemo } from "react";
+import { useTheme } from "./ThemeProvider.js";
+import type { Theme } from "./tokens.js";
+
+/**
+ * Resolved board tokens consumed by board renderers and per-tile
+ * default renderers. All values are CSS-ready strings.
+ */
+export interface BoardTheme {
+  /** Border drawn around the board's outer frame. */
+  readonly frameBorder: string;
+  /** Background painted under the tile renderer (visible at tile gaps). */
+  readonly frameBackground: string;
+  /** Hover-state ring drawn over an interactive target. */
+  readonly hoverRing: string;
+  /** Idle hint colour for an eligible-but-unhovered target. */
+  readonly eligibleHint: string;
+  /** Border drawn on inactive tiles (matches semantic.border.default). */
+  readonly tileBorder: string;
+  /** Subtle dotted border for non-interactive scaffolding (e.g. ports). */
+  readonly tileBorderSubtle: string;
+  /** Foreground used for board labels (numbers, port ratios). */
+  readonly tileText: string;
+  /** Recommended ring stroke width in px for hover/eligible markers. */
+  readonly ringWidth: number;
+}
+
+/**
+ * Derive a {@link BoardTheme} from the active theme. Memoised on the
+ * theme reference so consumers can pass it straight to a board's
+ * `defaultTileProps` / `defaultEdgeProps` slots.
+ */
+export function useBoardTheme(): BoardTheme {
+  const theme = useTheme();
+  return useMemo(() => deriveBoardTheme(theme), [theme]);
+}
+
+/** Standalone derivation for renderers that already hold a {@link Theme}. */
+export function deriveBoardTheme(theme: Theme): BoardTheme {
+  return {
+    frameBorder: theme.component.board.frameBorder,
+    frameBackground: theme.component.board.frameBackground,
+    hoverRing: theme.component.board.hoverRing,
+    eligibleHint: theme.component.board.eligibleHint,
+    tileBorder: theme.semantic.border.default,
+    tileBorderSubtle: theme.semantic.border.subtle,
+    tileText: theme.semantic.text.primary,
+    ringWidth: 3,
+  };
+}

package/src/theme/css-vars.ts

@@ -0,0 +1,105 @@
+import type { CSSProperties } from "react";
+import type { Theme } from "./tokens.js";
+
+/**
+ * CSS variable bridge for {@link Theme}.
+ *
+ * The {@link ThemeProvider} mounts a wrapper element and applies the
+ * map returned by {@link themeToCssVars} as inline `style`, which
+ * declares one CSS custom property per leaf token. Components inside
+ * the provider can:
+ *
+ * 1. Read tokens via `useTheme()` (typed) and use them inline, or
+ * 2. Read the CSS variable directly in Tailwind / className styling
+ *    via the helpers in {@link var()} below.
+ *
+ * The variable naming scheme is `--db-<dot.path>` with `.` and any
+ * non-identifier characters replaced by `-`. Example:
+ *
+ * - `theme.semantic.intent.primary.solid` → `--db-semantic-intent-primary-solid`
+ * - `theme.player[0].solid`              → `--db-player-1-solid`
+ * - `theme.color.brand.600`              → `--db-color-brand-600`
+ *
+ * The 1-based player suffix (rather than 0-based) keeps the variable
+ * name aligned with how seats are labelled in product UI ("Player 1").
+ */
+
+const PREFIX = "--db";
+
+/** Convert a token-tree path to a kebab-case CSS variable name. */
+function toVarName(parts: ReadonlyArray<string | number>): string {
+  const tail = parts
+    .map((part) => String(part))
+    .join("-")
+    .replace(/[^a-zA-Z0-9-]/g, "-")
+    .replace(/-+/g, "-");
+  return `${PREFIX}-${tail}`;
+}
+
+/**
+ * Walk the theme tree and produce a flat `{ "--db-...": value }` map.
+ * Arrays are walked positionally with a 1-based index (so
+ * `theme.player[0]` → `--db-player-1-...`).
+ */
+export function themeToCssVars(theme: Theme): CSSProperties {
+  const out: Record<string, string> = {};
+  walk(theme as unknown as Record<string, unknown>, [], out);
+  return out as CSSProperties;
+}
+
+function walk(
+  node: unknown,
+  path: ReadonlyArray<string | number>,
+  out: Record<string, string>,
+): void {
+  if (node === null || node === undefined) return;
+  if (typeof node === "string" || typeof node === "number") {
+    out[toVarName(path)] = String(node);
+    return;
+  }
+  if (Array.isArray(node)) {
+    node.forEach((child, idx) => {
+      // 1-based index for player slots, etc.
+      walk(child, [...path, idx + 1], out);
+    });
+    return;
+  }
+  if (typeof node === "object") {
+    for (const [key, value] of Object.entries(
+      node as Record<string, unknown>,
+    )) {
+      walk(value, [...path, key], out);
+    }
+  }
+}
+
+/**
+ * Build a `var(--db-...)` reference for a token path.
+ *
+ * @example
+ * ```ts
+ * cssVar("semantic", "intent", "primary", "solid")
+ *   // => "var(--db-semantic-intent-primary-solid)"
+ * cssVar("player", 1, "solid")
+ *   // => "var(--db-player-1-solid)"
+ * ```
+ */
+export function cssVar(...path: Array<string | number>): string {
+  return `var(${toVarName(path)})`;
+}
+
+/**
+ * Convenience for declaring a `var(--db-...)` with an inline fallback.
+ *
+ * @example
+ * ```ts
+ * cssVarOr("transparent", "semantic", "border", "default")
+ *   // => "var(--db-semantic-border-default, transparent)"
+ * ```
+ */
+export function cssVarOr(
+  fallback: string,
+  ...path: Array<string | number>
+): string {
+  return `var(${toVarName(path)}, ${fallback})`;
+}

package/src/theme/derive.ts

@@ -0,0 +1,240 @@
+import type { CSSProperties } from "react";
+import type { IntentColor, Theme } from "./tokens.js";
+
+/**
+ * Helpers that derive component-specific style fragments from a
+ * resolved {@link Theme}. They live alongside the theme module (rather
+ * than in each component) so that:
+ *
+ * - There is one canonical mapping of "intent → button style", "intent →
+ *   chip style", etc.
+ * - Component visuals stay aligned automatically when an author tweaks
+ *   the theme; nobody has to remember to update a bespoke calc inside
+ *   `<Card>` or `<DefaultInteractionButton>`.
+ *
+ * Each helper returns a plain {@link CSSProperties} fragment so the
+ * caller can spread it into an inline style (or pass it through to
+ * Framer Motion's `style` prop).
+ */
+
+/** Button visual variants derived from semantic intent slots. */
+export type ButtonVariant =
+  | "primary"
+  | "secondary"
+  | "danger"
+  | "submitted"
+  | "success"
+  | "warning"
+  | "info"
+  | "ghost";
+
+export type ButtonSize = "sm" | "md" | "lg";
+
+/**
+ * Compute the inline style for a button in `variant`/`size` from the
+ * theme. `disabled` and `pressed` are visual-only — they affect colour
+ * intensity and elevation but never touch interactivity (the consuming
+ * component owns `aria-disabled` and event wiring).
+ */
+export function buttonStyle(
+  theme: Theme,
+  options: {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    disabled?: boolean;
+    pressed?: boolean;
+  } = {},
+): CSSProperties {
+  const { variant = "primary", size = "md", disabled, pressed } = options;
+  const intent = intentForVariant(theme, variant);
+  const sizing = BUTTON_SIZE[size];
+  const visuallyDisabled = disabled && variant !== "submitted";
+
+  const baseShadow =
+    variant === "ghost"
+      ? "none"
+      : pressed
+        ? theme.elevation.rest
+        : theme.elevation.hover;
+
+  return {
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: theme.space[2],
+    minHeight: sizing.minHeight,
+    paddingBlock: sizing.paddingBlock,
+    paddingInline: sizing.paddingInline,
+    borderRadius: theme.radius.md,
+    border:
+      variant === "ghost"
+        ? "1px solid transparent"
+        : `1px solid ${visuallyDisabled ? theme.semantic.border.subtle : intent.border}`,
+    background:
+      variant === "ghost"
+        ? "transparent"
+        : visuallyDisabled
+          ? theme.semantic.surface.inset
+          : intent.solid,
+    color: visuallyDisabled
+      ? theme.semantic.text.disabled
+      : variant === "ghost"
+        ? theme.semantic.text.primary
+        : intent.on,
+    fontFamily: theme.typography.fontFamily.body,
+    fontSize: sizing.fontSize,
+    fontWeight: theme.typography.fontWeight.bold,
+    lineHeight: theme.typography.lineHeight.tight,
+    letterSpacing: theme.typography.letterSpacing.normal,
+    cursor: disabled ? "not-allowed" : "pointer",
+    boxShadow: disabled ? "none" : baseShadow,
+    transition: `background-color ${theme.motion.duration.fast} ${theme.motion.easing.out}, transform ${theme.motion.duration.fast} ${theme.motion.easing.out}, box-shadow ${theme.motion.duration.normal} ${theme.motion.easing.out}`,
+    userSelect: "none",
+    WebkitTapHighlightColor: "transparent",
+  };
+}
+
+const BUTTON_SIZE: Record<
+  ButtonSize,
+  {
+    minHeight: number;
+    paddingBlock: string;
+    paddingInline: string;
+    fontSize: string;
+  }
+> = {
+  sm: {
+    minHeight: 32,
+    paddingBlock: "0.25rem",
+    paddingInline: "0.625rem",
+    fontSize: "0.8125rem",
+  },
+  md: {
+    minHeight: 40,
+    paddingBlock: "0.5rem",
+    paddingInline: "0.875rem",
+    fontSize: "0.9375rem",
+  },
+  lg: {
+    minHeight: 52,
+    paddingBlock: "0.75rem",
+    paddingInline: "1.125rem",
+    fontSize: "1.0625rem",
+  },
+};
+
+/**
+ * Soft-intent chip ("Your turn", "Largest army", "Waiting…"). Reads
+ * `intent.<variant>.soft` for background and `.onSoft` for text.
+ */
+export function chipStyle(
+  theme: Theme,
+  options: {
+    variant?: Exclude<ButtonVariant, "ghost">;
+    size?: "sm" | "md";
+  } = {},
+): CSSProperties {
+  const { variant = "secondary", size = "sm" } = options;
+  const intent = intentForVariant(theme, variant);
+  return {
+    display: "inline-flex",
+    alignItems: "center",
+    gap: theme.space[1],
+    paddingBlock: size === "md" ? "0.25rem" : "0.125rem",
+    paddingInline: size === "md" ? "0.625rem" : "0.5rem",
+    borderRadius: theme.radius.pill,
+    border: `1px solid ${intent.border}`,
+    background: intent.soft,
+    color: intent.onSoft,
+    fontFamily: theme.typography.fontFamily.body,
+    fontSize:
+      size === "md"
+        ? theme.typography.fontSize.sm
+        : theme.typography.fontSize.xs,
+    fontWeight: theme.typography.fontWeight.bold,
+    letterSpacing: theme.typography.letterSpacing.wide,
+    textTransform: "uppercase",
+    whiteSpace: "nowrap",
+  };
+}
+
+/**
+ * Standard surface card (player card, action panel, hand drawer). The
+ * `tone` selects which `surface.*` slot to read; `interactive` adds
+ * the hover-elevation transition baseline.
+ */
+export function surfaceStyle(
+  theme: Theme,
+  options: {
+    tone?: keyof Theme["semantic"]["surface"];
+    interactive?: boolean;
+    /** Override radius to one of the theme tokens. Defaults to `lg`. */
+    radius?: keyof Theme["radius"];
+  } = {},
+): CSSProperties {
+  const { tone = "card", interactive, radius = "lg" } = options;
+  return {
+    background: theme.semantic.surface[tone],
+    color: theme.semantic.text.primary,
+    border: `1px solid ${theme.semantic.border.subtle}`,
+    borderRadius: theme.radius[radius],
+    boxShadow: theme.elevation.rest,
+    transition: interactive
+      ? `box-shadow ${theme.motion.duration.normal} ${theme.motion.easing.out}, transform ${theme.motion.duration.normal} ${theme.motion.easing.out}`
+      : undefined,
+  };
+}
+
+/** Resolve a {@link ButtonVariant} to its underlying {@link IntentColor}. */
+export function intentForVariant(
+  theme: Theme,
+  variant: ButtonVariant,
+): IntentColor {
+  switch (variant) {
+    case "primary":
+      return theme.semantic.intent.primary;
+    case "secondary":
+      return theme.semantic.intent.secondary;
+    case "danger":
+      return theme.semantic.intent.danger;
+    case "submitted":
+      return theme.semantic.intent.success;
+    case "success":
+      return theme.semantic.intent.success;
+    case "warning":
+      return theme.semantic.intent.warning;
+    case "info":
+      return theme.semantic.intent.info;
+    case "ghost":
+      return theme.semantic.intent.secondary;
+  }
+}
+
+/**
+ * Pick a {@link Theme.player} entry by 0-based seat slot, wrapping
+ * around when there are more players than palette entries (so a
+ * 7-player game cycles back to player 1's palette).
+ */
+export function playerColor(theme: Theme, slot: number) {
+  const length = theme.player.length;
+  const idx = ((slot % length) + length) % length;
+  // The {@link Theme.player} contract pins length === 6 at the type
+  // level, but indexing by a runtime-computed value widens the result
+  // to `PlayerColor | undefined`. Falling back to slot 0 (also typed
+  // `PlayerColor`) keeps the return type narrow without a non-null
+  // assertion.
+  return theme.player[idx] ?? theme.player[0];
+}
+
+/**
+ * Returns `theme.motion.duration.<key>` zeroed out when the theme has
+ * `motion.reducedMotion === "true"`. Use this in any component that
+ * starts an animation so `prefers-reduced-motion` is honoured uniformly.
+ */
+export function motionDuration(
+  theme: Theme,
+  key: keyof Theme["motion"]["duration"],
+): string {
+  if (theme.motion.reducedMotion === "true") return "0ms";
+  return theme.motion.duration[key];
+}