@dreamboard-games/sdk 0.2.1-alpha.1 → 0.3.0-alpha.1

package/src/ui/primitives/dice.tsx

@@ -1,79 +0,0 @@
-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

@@ -1,101 +0,0 @@
-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

@@ -1,252 +0,0 @@
-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

@@ -1,61 +0,0 @@
-/**
- * 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

@@ -1,105 +0,0 @@
-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})`;
-}