@dreamboard-games/sdk 0.2.0

package/src/ui/primitives/dice.tsx

@@ -0,0 +1,79 @@
+import { createContext, useContext, type ReactNode } from "react";
+
+export type DiceValue = number | null | undefined;
+
+export interface DiceState {
+  values: ReadonlyArray<number | undefined> | undefined;
+  /** Undefined if any die has not been rolled yet. */
+  sum: number | undefined;
+  diceCount: number;
+  allRolled: boolean;
+}
+
+export interface DiceRootProps {
+  values?: readonly DiceValue[] | null;
+  /** Used when values are not provided. */
+  count?: number;
+  children: ReactNode;
+}
+
+export interface DiceValuesProps {
+  children: (state: DiceState) => ReactNode;
+}
+
+export interface DiceComponents {
+  Root(props: DiceRootProps): ReactNode;
+  Values(props: DiceValuesProps): ReactNode;
+}
+
+const DiceContext = createContext<DiceState | null>(null);
+
+export function normalizeDiceState({
+  values,
+  count = 2,
+}: {
+  values?: readonly DiceValue[] | null;
+  count?: number;
+}): DiceState {
+  const normalizedValues = values?.map((value) => value ?? undefined);
+  const allRolled =
+    normalizedValues?.every((value) => value !== undefined) ?? false;
+  const sum = allRolled
+    ? normalizedValues?.reduce<number>(
+        (total, value) => total + (value ?? 0),
+        0,
+      )
+    : undefined;
+
+  return {
+    values: normalizedValues,
+    sum,
+    diceCount: normalizedValues?.length ?? count,
+    allRolled,
+  };
+}
+
+export function DiceRoot({ values, count, children }: DiceRootProps) {
+  return (
+    <DiceContext.Provider value={normalizeDiceState({ values, count })}>
+      {children}
+    </DiceContext.Provider>
+  );
+}
+
+export function useDicePrimitiveContext(): DiceState {
+  const value = useContext(DiceContext);
+  if (!value) {
+    throw new Error("Dice primitives must be rendered inside <Dice.Root>.");
+  }
+  return value;
+}
+
+export function DiceValues({ children }: DiceValuesProps) {
+  return children(useDicePrimitiveContext());
+}
+
+export const Dice: DiceComponents = {
+  Root: DiceRoot,
+  Values: DiceValues,
+};

package/src/ui/primitives/primitive-props.tsx

@@ -0,0 +1,101 @@
+import {
+  cloneElement,
+  isValidElement,
+  type AriaAttributes,
+  type CSSProperties,
+  type HTMLAttributes,
+  type JSX,
+  type ChangeEvent,
+  type MouseEvent,
+  type PointerEvent,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+export type PrimitiveDataAttributes = Record<
+  `data-${string}`,
+  string | boolean | number | undefined
+>;
+
+export type PrimitiveCommonProps = {
+  asChild?: boolean;
+  children?: ReactNode;
+  className?: string;
+  style?: CSSProperties;
+} & AriaAttributes &
+  PrimitiveDataAttributes;
+
+type EventHandler<Event> = (event: Event) => void;
+
+export function composeEventHandlers<
+  Event extends { defaultPrevented: boolean },
+>(
+  authorHandler: EventHandler<Event> | undefined,
+  primitiveHandler: EventHandler<Event> | undefined,
+): EventHandler<Event> | undefined {
+  if (!authorHandler) return primitiveHandler;
+  if (!primitiveHandler) return authorHandler;
+  return (event) => {
+    authorHandler(event);
+    if (!event.defaultPrevented) {
+      primitiveHandler(event);
+    }
+  };
+}
+
+export function renderPrimitive<
+  ElementProps extends HTMLAttributes<HTMLElement>,
+>(
+  tagName: keyof JSX.IntrinsicElements,
+  props: ElementProps & PrimitiveCommonProps,
+): ReactElement {
+  const { asChild, children, ...primitiveProps } = props;
+  if (asChild) {
+    if (!isValidElement(children)) {
+      throw new Error(
+        "asChild requires exactly one valid React element child.",
+      );
+    }
+    const element = children as ReactElement<HTMLAttributes<HTMLElement>>;
+    const childProps = element.props;
+    return cloneElement(element, {
+      ...primitiveProps,
+      ...childProps,
+      className: [primitiveProps.className, childProps.className]
+        .filter(Boolean)
+        .join(" "),
+      style: {
+        ...(primitiveProps.style ?? {}),
+        ...(childProps.style ?? {}),
+      },
+      onClick: composeEventHandlers(
+        childProps.onClick,
+        primitiveProps.onClick as EventHandler<MouseEvent<HTMLElement>>,
+      ),
+      onPointerDown: composeEventHandlers(
+        childProps.onPointerDown,
+        primitiveProps.onPointerDown as EventHandler<PointerEvent<HTMLElement>>,
+      ),
+      onPointerMove: composeEventHandlers(
+        childProps.onPointerMove,
+        primitiveProps.onPointerMove as EventHandler<PointerEvent<HTMLElement>>,
+      ),
+      onPointerUp: composeEventHandlers(
+        childProps.onPointerUp,
+        primitiveProps.onPointerUp as EventHandler<PointerEvent<HTMLElement>>,
+      ),
+      onPointerCancel: composeEventHandlers(
+        childProps.onPointerCancel,
+        primitiveProps.onPointerCancel as EventHandler<
+          PointerEvent<HTMLElement>
+        >,
+      ),
+      onChange: composeEventHandlers(
+        childProps.onChange,
+        primitiveProps.onChange as EventHandler<ChangeEvent<HTMLElement>>,
+      ),
+    });
+  }
+  const Tag = tagName as keyof JSX.IntrinsicElements;
+  return <Tag {...(primitiveProps as object)}>{children}</Tag>;
+}

package/src/ui/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-games/sdk/ui`. 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/ui/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/ui/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})`;
+}