@dreamboard-games/ui-sdk 0.0.41

package/src/theme/presets/tabletop.ts

@@ -0,0 +1,266 @@
+import type { Theme } from "../tokens.js";
+
+/**
+ * `tabletop` — the default Dreamboard theme.
+ *
+ * Visual identity: warm paper backgrounds, deep ink-blue brand,
+ * confident type, rounded but disciplined corners. Designed to feel
+ * like a polished hobby-game client (Splendor digital, modern Catan
+ * apps) without leaning into a specific game's IP.
+ *
+ * Picked deliberately for the default: a board game UI sitting on
+ * cool grey or pure white reads as "spreadsheet"; warm parchment
+ * cues "play" without sliding into kitsch.
+ */
+export const tabletopTheme: Theme = {
+  meta: {
+    id: "tabletop",
+    name: "Tabletop",
+    mode: "light",
+  },
+  color: {
+    neutral: {
+      50: "#fbf8f1",
+      100: "#f4ecd8",
+      200: "#e7dcc1",
+      400: "#a89c84",
+      600: "#5f5547",
+      800: "#2f2a22",
+      950: "#15120d",
+    },
+    brand: {
+      50: "#eef3fb",
+      100: "#d3e0f3",
+      200: "#a7c1e7",
+      400: "#5780bf",
+      600: "#2d5da1",
+      800: "#1a3c6b",
+      950: "#0d1f37",
+    },
+    accent: {
+      50: "#fff5e0",
+      100: "#ffe5b3",
+      200: "#fcd07a",
+      400: "#f0a738",
+      600: "#c87a16",
+      800: "#7e4a08",
+      950: "#3c2103",
+    },
+    success: {
+      50: "#e8f6ec",
+      100: "#c4ecd0",
+      200: "#8fd6a3",
+      400: "#3fae62",
+      600: "#1f7d3e",
+      800: "#0d4a23",
+      950: "#062213",
+    },
+    warning: {
+      50: "#fff5dc",
+      100: "#ffe7a8",
+      200: "#fad164",
+      400: "#dca41a",
+      600: "#9c6f06",
+      800: "#5b4002",
+      950: "#2b1d00",
+    },
+    danger: {
+      50: "#fdecec",
+      100: "#f9c7c7",
+      200: "#f08e8e",
+      400: "#d53f3f",
+      600: "#a31d1d",
+      800: "#5e0d0d",
+      950: "#2a0404",
+    },
+    info: {
+      50: "#e6f5fb",
+      100: "#bfe3f4",
+      200: "#7ec5e6",
+      400: "#2f8fc4",
+      600: "#0d5e8a",
+      800: "#073650",
+      950: "#021a26",
+    },
+  },
+  semantic: {
+    surface: {
+      app: "#f6efe0",
+      board: "#1a3552",
+      hud: "#fbf8f1",
+      card: "#ffffff",
+      sheet: "#fbf8f1",
+      overlay: "rgba(15, 23, 42, 0.55)",
+      inset: "#f4ecd8",
+    },
+    text: {
+      primary: "#2f2a22",
+      muted: "#5f5547",
+      onIntent: "#ffffff",
+      accent: "#1a3c6b",
+      disabled: "#a89c84",
+    },
+    border: {
+      subtle: "#e7dcc1",
+      default: "#a89c84",
+      strong: "#5f5547",
+      focus: "#2d5da1",
+    },
+    intent: {
+      primary: {
+        solid: "#2d5da1",
+        on: "#ffffff",
+        soft: "#d3e0f3",
+        onSoft: "#1a3c6b",
+        border: "#1a3c6b",
+      },
+      secondary: {
+        solid: "#fbf8f1",
+        on: "#2f2a22",
+        soft: "#f4ecd8",
+        onSoft: "#2f2a22",
+        border: "#a89c84",
+      },
+      success: {
+        solid: "#1f7d3e",
+        on: "#ffffff",
+        soft: "#c4ecd0",
+        onSoft: "#0d4a23",
+        border: "#0d4a23",
+      },
+      danger: {
+        solid: "#a31d1d",
+        on: "#ffffff",
+        soft: "#f9c7c7",
+        onSoft: "#5e0d0d",
+        border: "#5e0d0d",
+      },
+      warning: {
+        solid: "#dca41a",
+        on: "#2f2a22",
+        soft: "#ffe7a8",
+        onSoft: "#5b4002",
+        border: "#9c6f06",
+      },
+      info: {
+        solid: "#0d5e8a",
+        on: "#ffffff",
+        soft: "#bfe3f4",
+        onSoft: "#073650",
+        border: "#073650",
+      },
+    },
+  },
+  radius: {
+    none: "0px",
+    sm: "6px",
+    md: "10px",
+    lg: "16px",
+    hud: "20px",
+    pill: "9999px",
+  },
+  space: {
+    0: "0",
+    0.5: "0.125rem",
+    1: "0.25rem",
+    1.5: "0.375rem",
+    2: "0.5rem",
+    3: "0.75rem",
+    4: "1rem",
+    6: "1.5rem",
+    8: "2rem",
+    12: "3rem",
+  },
+  typography: {
+    fontFamily: {
+      display:
+        '"Fraunces", "Iowan Old Style", "Source Serif Pro", "Georgia", serif',
+      body: '"Inter", "SF Pro Text", system-ui, -apple-system, sans-serif',
+      tabular: '"JetBrains Mono", "SF Mono", "ui-monospace", monospace',
+      mono: '"JetBrains Mono", "SF Mono", "ui-monospace", monospace',
+    },
+    fontSize: {
+      xs: "0.6875rem",
+      sm: "0.8125rem",
+      md: "0.9375rem",
+      lg: "1.0625rem",
+      xl: "1.25rem",
+      "2xl": "1.5rem",
+      "3xl": "2rem",
+    },
+    fontWeight: {
+      regular: "400",
+      medium: "500",
+      bold: "700",
+    },
+    lineHeight: {
+      tight: "1.15",
+      normal: "1.4",
+      relaxed: "1.6",
+    },
+    letterSpacing: {
+      tight: "-0.01em",
+      normal: "0",
+      wide: "0.04em",
+      caps: "0.14em",
+    },
+  },
+  elevation: {
+    rest: "0 1px 0 rgba(15, 18, 13, 0.06), 0 2px 6px rgba(15, 18, 13, 0.05)",
+    hover: "0 4px 0 rgba(15, 18, 13, 0.05), 0 8px 18px rgba(15, 18, 13, 0.12)",
+    lifted:
+      "0 12px 0 rgba(15, 18, 13, 0.05), 0 18px 36px rgba(15, 18, 13, 0.18)",
+    overlay: "0 24px 64px rgba(15, 18, 13, 0.32)",
+    inset: "inset 0 1px 0 rgba(15, 18, 13, 0.08)",
+  },
+  motion: {
+    duration: {
+      fast: "80ms",
+      normal: "160ms",
+      slow: "280ms",
+      ambient: "1800ms",
+    },
+    easing: {
+      out: "cubic-bezier(0.16, 1, 0.3, 1)",
+      in: "cubic-bezier(0.4, 0, 1, 0.4)",
+      inOut: "cubic-bezier(0.65, 0, 0.35, 1)",
+      spring: "cubic-bezier(0.34, 1.56, 0.64, 1)",
+    },
+    reducedMotion: "false",
+  },
+  player: [
+    { solid: "#d04848", soft: "#fcdedd", on: "#ffffff" },
+    { solid: "#2d5da1", soft: "#d3e0f3", on: "#ffffff" },
+    { solid: "#1f7d3e", soft: "#c4ecd0", on: "#ffffff" },
+    { solid: "#c87a16", soft: "#ffe5b3", on: "#2f2a22" },
+    { solid: "#7d4a8a", soft: "#e6d6ee", on: "#ffffff" },
+    { solid: "#0d5e8a", soft: "#bfe3f4", on: "#ffffff" },
+  ],
+  component: {
+    board: {
+      frameBorder: "#a89c84",
+      frameBackground: "#1a3552",
+      hoverRing: "#f0a738",
+      eligibleHint: "rgba(240, 167, 56, 0.55)",
+    },
+    card: {
+      border: "#2f2a22",
+      backBorder: "#1a3c6b",
+      backBackground: "#2d5da1",
+      selectedRing: "#d04848",
+    },
+    playerCard: {
+      activeBackground: "#fff5e0",
+      activeBorder: "#f0a738",
+      activeGlow: "rgba(240, 167, 56, 0.32)",
+      youBadgeBackground: "#d3e0f3",
+      youBadgeForeground: "#1a3c6b",
+    },
+    toast: {
+      successBackground: "#1f7d3e",
+      errorBackground: "#a31d1d",
+      infoBackground: "#0d5e8a",
+      foreground: "#ffffff",
+    },
+  },
+};

package/src/theme/theme.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, test } from "bun:test";
+import {
+  arcadeTheme,
+  buttonStyle,
+  chipStyle,
+  cssVar,
+  cssVarOr,
+  getThemePreset,
+  intentForVariant,
+  mergeTheme,
+  motionDuration,
+  playerColor,
+  resolveTheme,
+  studioTheme,
+  surfaceStyle,
+  tabletopTheme,
+  themeToCssVars,
+  type Theme,
+  type ThemeOverride,
+} from "./index.js";
+
+const PRESETS: ReadonlyArray<{ id: string; theme: Theme }> = [
+  { id: "tabletop", theme: tabletopTheme },
+  { id: "arcade", theme: arcadeTheme },
+  { id: "studio", theme: studioTheme },
+];
+
+/**
+ * The token contract is a public surface — every preset must carry
+ * the same shape so any author override that compiles against
+ * `tabletop` also works against `arcade`/`studio`. A structural diff
+ * here catches preset drift before it reaches downstream components.
+ */
+describe("preset structural parity", () => {
+  function shape(value: unknown): unknown {
+    if (Array.isArray(value)) {
+      return value.map(shape);
+    }
+    if (value && typeof value === "object") {
+      const out: Record<string, unknown> = {};
+      for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+        out[key] = shape((value as Record<string, unknown>)[key]);
+      }
+      return out;
+    }
+    // Replace scalar leaves with their type so identical structures
+    // compare equal regardless of token *values*.
+    return typeof value;
+  }
+
+  const expected = shape(tabletopTheme);
+  for (const preset of PRESETS) {
+    test(`${preset.id} matches the canonical token shape`, () => {
+      expect(shape(preset.theme)).toEqual(expected);
+    });
+  }
+
+  test("every preset declares exactly six player colors", () => {
+    for (const preset of PRESETS) {
+      expect(preset.theme.player).toHaveLength(6);
+    }
+  });
+
+  test("preset meta.id is unique across presets", () => {
+    const ids = PRESETS.map((p) => p.theme.meta.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+});
+
+describe("resolveTheme", () => {
+  test("returns the tabletop preset by default", () => {
+    expect(resolveTheme(undefined)).toBe(tabletopTheme);
+  });
+
+  test("looks up presets by id", () => {
+    expect(resolveTheme("tabletop")).toBe(tabletopTheme);
+    expect(resolveTheme("arcade")).toBe(arcadeTheme);
+    expect(resolveTheme("studio")).toBe(studioTheme);
+  });
+
+  test("passes through a fully-resolved theme", () => {
+    expect(resolveTheme(tabletopTheme)).toBe(tabletopTheme);
+  });
+
+  test("throws for an unknown preset id", () => {
+    expect(() =>
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      resolveTheme("nope" as any),
+    ).toThrow(/unknown theme preset/i);
+  });
+
+  test("getThemePreset returns the same value as resolveTheme(id)", () => {
+    expect(getThemePreset("arcade")).toBe(arcadeTheme);
+  });
+});
+
+describe("mergeTheme deep override semantics", () => {
+  test("scalar overrides replace the matching leaf without touching siblings", () => {
+    const override: ThemeOverride = {
+      semantic: {
+        intent: {
+          primary: { solid: "#ff0000" },
+        },
+      },
+    };
+    const merged = mergeTheme(tabletopTheme, override);
+    expect(merged.semantic.intent.primary.solid).toBe("#ff0000");
+    // Sibling token preserved.
+    expect(merged.semantic.intent.primary.on).toBe(
+      tabletopTheme.semantic.intent.primary.on,
+    );
+    // Sibling intent preserved.
+    expect(merged.semantic.intent.danger).toEqual(
+      tabletopTheme.semantic.intent.danger,
+    );
+    // Original is not mutated.
+    expect(tabletopTheme.semantic.intent.primary.solid).not.toBe("#ff0000");
+  });
+
+  test("undefined override values fall through to the base theme", () => {
+    const merged = mergeTheme(tabletopTheme, {
+      meta: { name: undefined },
+    });
+    expect(merged.meta.name).toBe(tabletopTheme.meta.name);
+  });
+
+  test("array overrides replace wholesale rather than merging element-wise", () => {
+    const customPlayers: ThemeOverride["player"] = [
+      { solid: "#111", soft: "#222", on: "#fff" },
+      { solid: "#333", soft: "#444", on: "#fff" },
+      { solid: "#555", soft: "#666", on: "#fff" },
+      { solid: "#777", soft: "#888", on: "#fff" },
+      { solid: "#999", soft: "#aaa", on: "#fff" },
+      { solid: "#bbb", soft: "#ccc", on: "#fff" },
+    ];
+    const merged = mergeTheme(tabletopTheme, { player: customPlayers });
+    expect(merged.player).toHaveLength(6);
+    expect(merged.player[0].solid).toBe("#111");
+    // Wholesale replacement: first base player slot (red) is gone.
+    expect(merged.player[0].solid).not.toBe(tabletopTheme.player[0].solid);
+  });
+
+  test("returns the same reference when override is undefined (no allocation)", () => {
+    expect(mergeTheme(tabletopTheme, undefined)).toBe(tabletopTheme);
+  });
+});
+
+describe("themeToCssVars serializer", () => {
+  test("emits a flat record of --db-* variables", () => {
+    const vars = themeToCssVars(tabletopTheme) as Record<string, string>;
+    for (const key of Object.keys(vars)) {
+      expect(key.startsWith("--db-")).toBe(true);
+    }
+  });
+
+  test("converts dotted token paths to kebab-case", () => {
+    const vars = themeToCssVars(tabletopTheme) as Record<string, string>;
+    expect(vars["--db-semantic-intent-primary-solid"]).toBe(
+      tabletopTheme.semantic.intent.primary.solid,
+    );
+    expect(vars["--db-color-brand-600"]).toBe(tabletopTheme.color.brand[600]);
+    expect(vars["--db-radius-md"]).toBe(tabletopTheme.radius.md);
+  });
+
+  test("uses 1-based indices for player array entries", () => {
+    const vars = themeToCssVars(tabletopTheme) as Record<string, string>;
+    expect(vars["--db-player-1-solid"]).toBe(tabletopTheme.player[0].solid);
+    expect(vars["--db-player-6-solid"]).toBe(tabletopTheme.player[5].solid);
+    expect(vars["--db-player-0-solid"]).toBeUndefined();
+  });
+
+  test("scalar leaves are stringified (no nested objects in output)", () => {
+    const vars = themeToCssVars(tabletopTheme) as Record<string, string>;
+    for (const value of Object.values(vars)) {
+      expect(typeof value).toBe("string");
+    }
+  });
+});
+
+describe("cssVar / cssVarOr helpers", () => {
+  test("cssVar builds the canonical --db-* reference", () => {
+    expect(cssVar("semantic", "intent", "primary", "solid")).toBe(
+      "var(--db-semantic-intent-primary-solid)",
+    );
+    expect(cssVar("player", 1, "solid")).toBe("var(--db-player-1-solid)");
+  });
+
+  test("cssVarOr injects a fallback value", () => {
+    expect(cssVarOr("transparent", "semantic", "border", "default")).toBe(
+      "var(--db-semantic-border-default, transparent)",
+    );
+  });
+});
+
+describe("derived style helpers", () => {
+  test("buttonStyle picks intent colours for the requested variant", () => {
+    const style = buttonStyle(tabletopTheme, { variant: "danger" });
+    expect(style.background).toBe(tabletopTheme.semantic.intent.danger.solid);
+    expect(style.color).toBe(tabletopTheme.semantic.intent.danger.on);
+  });
+
+  test("buttonStyle disabled drops to the inset surface and disabled text", () => {
+    const style = buttonStyle(tabletopTheme, {
+      variant: "primary",
+      disabled: true,
+    });
+    expect(style.background).toBe(tabletopTheme.semantic.surface.inset);
+    expect(style.color).toBe(tabletopTheme.semantic.text.disabled);
+    expect(style.cursor).toBe("not-allowed");
+    expect(style.boxShadow).toBe("none");
+  });
+
+  test("buttonStyle ghost variant has no fill or border colour", () => {
+    const style = buttonStyle(tabletopTheme, { variant: "ghost" });
+    expect(style.background).toBe("transparent");
+    expect(style.boxShadow).toBe("none");
+    expect(style.color).toBe(tabletopTheme.semantic.text.primary);
+  });
+
+  test("chipStyle reads the soft intent slot for tinted backgrounds", () => {
+    const style = chipStyle(tabletopTheme, { variant: "success" });
+    expect(style.background).toBe(tabletopTheme.semantic.intent.success.soft);
+    expect(style.color).toBe(tabletopTheme.semantic.intent.success.onSoft);
+  });
+
+  test("surfaceStyle defaults to the card surface and rest elevation", () => {
+    const style = surfaceStyle(tabletopTheme);
+    expect(style.background).toBe(tabletopTheme.semantic.surface.card);
+    expect(style.boxShadow).toBe(tabletopTheme.elevation.rest);
+  });
+
+  test("intentForVariant ghost falls back to the secondary intent slot", () => {
+    expect(intentForVariant(tabletopTheme, "ghost")).toBe(
+      tabletopTheme.semantic.intent.secondary,
+    );
+  });
+
+  test("playerColor wraps slot indices around the palette length", () => {
+    expect(playerColor(tabletopTheme, 0)).toBe(tabletopTheme.player[0]);
+    expect(playerColor(tabletopTheme, tabletopTheme.player.length)).toBe(
+      tabletopTheme.player[0],
+    );
+    expect(playerColor(tabletopTheme, -1)).toBe(
+      tabletopTheme.player[tabletopTheme.player.length - 1],
+    );
+  });
+
+  test("motionDuration zeroes out durations when reducedMotion is true", () => {
+    const reduced = mergeTheme(tabletopTheme, {
+      motion: { reducedMotion: "true" },
+    });
+    expect(motionDuration(tabletopTheme, "normal")).toBe(
+      tabletopTheme.motion.duration.normal,
+    );
+    expect(motionDuration(reduced, "normal")).toBe("0ms");
+    expect(motionDuration(reduced, "ambient")).toBe("0ms");
+  });
+});