@dreamboard-games/ui-sdk 0.0.41

package/src/components/MoreActions.test.tsx

@@ -0,0 +1,93 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import { ThemeProvider } from "../theme/ThemeProvider.js";
+import { MoreActions } from "./MoreActions.js";
+
+// React SSR splits text nodes around dynamic children with HTML
+// comments. Strip them before substring asserting so tests stay
+// readable.
+function stripSsrComments(html: string): string {
+  return html.replace(/<!--\s*-->/g, "");
+}
+
+test("MoreActions renders collapsed by default and tags state via aria + data attrs", () => {
+  // Default should always be closed so the disclosure doesn't show
+  // its hidden content unprompted (the whole point is to fight choice
+  // overload). The aria + data-* hooks let tests / hand-rolled CSS
+  // target the open state without looking at children.
+  const html = renderToString(
+    <ThemeProvider>
+      <MoreActions count={3}>
+        <button data-testid="hidden">Forfeit</button>
+      </MoreActions>
+    </ThemeProvider>,
+  );
+
+  expect(html).toContain('data-shell-slot="more-actions"');
+  expect(html).toContain('data-more-actions-open="false"');
+  expect(html).toContain('aria-expanded="false"');
+  // Toggle exposes the count so the player knows N actions are
+  // hidden without expanding first (ambient awareness).
+  expect(stripSsrComments(html)).toContain("(3)");
+  expect(html).not.toContain('data-testid="hidden"');
+});
+
+test("MoreActions opens by default when defaultOpen is true and exposes the disclosed region", () => {
+  const html = renderToString(
+    <ThemeProvider>
+      <MoreActions count={1} defaultOpen>
+        <button data-testid="visible">Forfeit</button>
+      </MoreActions>
+    </ThemeProvider>,
+  );
+
+  expect(html).toContain('data-more-actions-open="true"');
+  expect(html).toContain('aria-expanded="true"');
+  // Region is mounted with `role="region"` and an aria-label that
+  // matches the toggle so screen readers announce it as a labelled
+  // landmark.
+  expect(html).toContain('role="region"');
+  expect(html).toContain('data-testid="visible"');
+});
+
+test("MoreActions accepts a custom toggle label", () => {
+  // Workspace-specific copy (e.g. "Advanced", "Manage") flows through
+  // unchanged so authors can match their game's voice without forking
+  // the component.
+  const html = renderToString(
+    <ThemeProvider>
+      <MoreActions label="Advanced" count={2}>
+        <button>x</button>
+      </MoreActions>
+    </ThemeProvider>,
+  );
+
+  expect(html).toContain("Advanced");
+  expect(stripSsrComments(html)).toContain("(2)");
+});
+
+test("MoreActions hides the count badge when count is zero or undefined", () => {
+  // The badge would otherwise read "(0)" which is just visual noise.
+  // We check by counting the `tabular-nums` style hint we attach to
+  // the badge — the badge is the only span carrying it inside the
+  // toggle, so its absence proves we didn't mount the badge.
+  const BADGE_MARKER = "font-variant-numeric:tabular-nums";
+
+  const noCount = renderToString(
+    <ThemeProvider>
+      <MoreActions>
+        <button>x</button>
+      </MoreActions>
+    </ThemeProvider>,
+  );
+  const zeroCount = renderToString(
+    <ThemeProvider>
+      <MoreActions count={0}>
+        <button>x</button>
+      </MoreActions>
+    </ThemeProvider>,
+  );
+
+  expect(noCount).not.toContain(BADGE_MARKER);
+  expect(zeroCount).not.toContain(BADGE_MARKER);
+});

package/src/components/MoreActions.tsx

@@ -0,0 +1,143 @@
+/**
+ * Disclosure that hides a list of low-salience actions behind a single
+ * "More" toggle. Sized and styled by the active theme so it looks
+ * consistent with neighbouring `<DefaultInteractionButton>` rows.
+ *
+ * Why not a popover or dropdown? Two reasons:
+ *
+ * 1. **Layout safety.** The default panel surface lives directly above
+ *    the hand strip; a floating popover would be obscured by the
+ *    hand's `overflow-x: auto` clipping. An inline expansion stays
+ *    inside the panel container and pushes neighbouring rows down.
+ * 2. **Discoverability.** Players miss menus that hide behind triple
+ *    dots / chevrons. An expanded inline list still looks like a row
+ *    of buttons (Jakob — same affordance as the always-visible row).
+ *
+ * The toggle reports its open state via `aria-expanded` and labels
+ * the disclosed region via `aria-controls` so screen readers announce
+ * "Expanded — More actions, region containing 3 buttons" naturally.
+ */
+
+import { useId, useState, type CSSProperties, type ReactNode } from "react";
+import { ChevronDown, MoreHorizontal } from "lucide-react";
+import { useTheme } from "../theme/ThemeProvider.js";
+import { ThemedButton } from "./ThemedButton.js";
+
+export interface MoreActionsProps {
+  /**
+   * Items rendered inside the disclosure when expanded. Typically
+   * `<DefaultInteractionButton>` instances for `salience: "tertiary"`
+   * descriptors, but any `ReactNode` works (custom panel cards, etc.).
+   */
+  children: ReactNode;
+  /**
+   * Toggle label. Defaults to `"More"`. The descriptor count gets
+   * appended automatically when {@link count} is supplied.
+   */
+  label?: string;
+  /**
+   * Number of hidden items, used to render the trailing "(N)" badge.
+   * Omit when the count is irrelevant or already implied (e.g. when
+   * the panel only has a fixed set of disclosed items).
+   */
+  count?: number;
+  /**
+   * Initial open state. Defaults to `false` — the disclosure is the
+   * point. Authors who want it open by default for a specific seat
+   * (e.g. tutorial mode) should pass `true`.
+   */
+  defaultOpen?: boolean;
+  /** Additional inline style merged after the default container. */
+  style?: CSSProperties;
+}
+
+export function MoreActions({
+  children,
+  label = "More",
+  count,
+  defaultOpen = false,
+  style,
+}: MoreActionsProps) {
+  const theme = useTheme();
+  const [open, setOpen] = useState(defaultOpen);
+  // `useId` keeps the aria pairing stable across re-renders even when
+  // many `<MoreActions>` exist on screen (rare, but easy to break).
+  const regionId = `more-actions-${useId().replace(/:/g, "")}`;
+
+  const showCount = typeof count === "number" && count > 0;
+
+  return (
+    <div
+      data-shell-slot="more-actions"
+      data-more-actions-open={open ? "true" : "false"}
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: theme.space[2],
+        alignItems: "stretch",
+        // The disclosure is its own block so wrap behaviour upstream
+        // doesn't interleave the toggle and the disclosed items.
+        flex: "1 1 100%",
+        minWidth: 0,
+      }}
+    >
+      <ThemedButton
+        type="button"
+        variant="secondary"
+        size="md"
+        aria-expanded={open}
+        aria-controls={regionId}
+        onClick={() => setOpen((value) => !value)}
+        style={{
+          display: "inline-flex",
+          alignItems: "center",
+          gap: theme.space[1],
+          ...style,
+        }}
+      >
+        <MoreHorizontal size={16} aria-hidden />
+        <span>{label}</span>
+        {showCount ? (
+          <span
+            aria-hidden
+            style={{
+              fontVariantNumeric: "tabular-nums",
+              opacity: 0.78,
+            }}
+          >
+            ({count})
+          </span>
+        ) : null}
+        <ChevronDown
+          size={14}
+          aria-hidden
+          style={{
+            transform: open ? "rotate(180deg)" : "rotate(0deg)",
+            transition: `transform ${theme.motion.duration.fast} ${theme.motion.easing.out}`,
+          }}
+        />
+      </ThemedButton>
+      {open ? (
+        <div
+          id={regionId}
+          role="region"
+          aria-label={label}
+          style={{
+            display: "flex",
+            flexDirection: "row",
+            flexWrap: "wrap",
+            gap: theme.space[2],
+            // Inset visually so the disclosed cluster reads as a
+            // sub-region rather than a continuation of the main panel.
+            paddingInline: theme.space[3],
+            paddingBlock: theme.space[2],
+            background: theme.semantic.surface.inset,
+            borderRadius: theme.radius.lg,
+          }}
+        >
+          {children}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/PhaseIndicator.tsx

@@ -0,0 +1,341 @@
+/**
+ * Surfaces the dominant turn-state question — "is this me?" / "who am I
+ * waiting for?" — as a single headline, with the phase label demoted to
+ * secondary copy underneath.
+ *
+ * The previous design rendered three peer chips (`Waiting`, `Roll dice`,
+ * `Player 3`) which fragmented one piece of information across three
+ * UI atoms. The redesign collapses them into a single status line:
+ *
+ *   ◐ Waiting for Player 3…
+ *      Roll dice
+ *
+ *   ● Your turn
+ *      Build, trade, or end your turn.
+ *
+ * Both states get a leading status indicator that animates so the eye
+ * picks up the "live" cue immediately. Animations are skipped when the
+ * theme reports `motion.reducedMotion === "true"`.
+ *
+ * Prop API is unchanged so existing callers (Catan, Things-in-Rings,
+ * tests) keep working without edits. The `variant` knob still toggles
+ * surface treatment (`badge` is layout-only, `bar` wraps the headline
+ * in an inset HUD strip, `minimal` collapses to a single underlined
+ * label for tight HUDs).
+ */
+
+import { motion } from "framer-motion";
+import { clsx } from "clsx";
+import { useTheme } from "../theme/ThemeProvider.js";
+import { surfaceStyle } from "../theme/derive.js";
+import type { Theme } from "../theme/tokens.js";
+
+export interface PhaseIndicatorProps {
+  currentPhase: string;
+  phaseLabels?: Record<string, string>;
+  isMyTurn?: boolean;
+  activePlayerNames?: string[];
+  variant?: "badge" | "bar" | "minimal";
+  className?: string;
+}
+
+export function PhaseIndicator({
+  currentPhase,
+  phaseLabels,
+  isMyTurn,
+  activePlayerNames,
+  variant = "badge",
+  className,
+}: PhaseIndicatorProps) {
+  const theme = useTheme();
+  const reducedMotion = theme.motion.reducedMotion === "true";
+
+  const label = phaseLabels?.[currentPhase] ?? formatPhase(currentPhase);
+
+  if (variant === "minimal") {
+    return (
+      <span
+        className={className}
+        style={{
+          fontFamily: theme.typography.fontFamily.body,
+          fontSize: theme.typography.fontSize.sm,
+          fontWeight: theme.typography.fontWeight.bold,
+          color: theme.semantic.text.muted,
+          textDecoration: "underline",
+          textDecorationStyle: "wavy",
+          textDecorationColor: theme.semantic.border.subtle,
+          textUnderlineOffset: "4px",
+        }}
+        role="status"
+        aria-label={`Current phase: ${label}`}
+      >
+        {label}
+      </span>
+    );
+  }
+
+  // Decide which state we're in. Only one is active at a time so the
+  // headline is unambiguous.
+  const state: "your-turn" | "waiting" | "phase-only" =
+    isMyTurn === true
+      ? "your-turn"
+      : isMyTurn === false && activePlayerNames && activePlayerNames.length > 0
+        ? "waiting"
+        : "phase-only";
+
+  const containerStyle: React.CSSProperties =
+    variant === "bar"
+      ? {
+          ...surfaceStyle(theme, { tone: "inset", radius: "hud" }),
+          padding: theme.space[3],
+          boxShadow: theme.elevation.inset,
+          fontFamily: theme.typography.fontFamily.body,
+        }
+      : { fontFamily: theme.typography.fontFamily.body };
+
+  const headline = renderHeadline({
+    state,
+    activePlayerNames,
+    label,
+    theme,
+    reducedMotion,
+  });
+  const ariaLabel =
+    state === "your-turn"
+      ? `Your turn — ${label}`
+      : state === "waiting"
+        ? `Waiting for ${formatPlayerList(activePlayerNames ?? [])} — ${label}`
+        : label;
+
+  return (
+    <div
+      className={clsx("flex items-center gap-3 flex-wrap", className)}
+      style={containerStyle}
+      role="status"
+      aria-live="polite"
+      aria-atomic="true"
+      aria-label={ariaLabel}
+    >
+      {headline}
+    </div>
+  );
+}
+
+function formatPhase(phase: string): string {
+  const formatted = phase
+    .replace(/([A-Z])/g, " $1")
+    .replace(/_/g, " ")
+    .trim()
+    .replace(/^\w/, (c) => c.toUpperCase());
+  return formatted === "Player Turn" ? "Turn" : formatted;
+}
+
+function formatPlayerList(names: readonly string[]): string {
+  if (names.length === 0) return "";
+  if (names.length === 1) return names[0]!;
+  if (names.length === 2) return `${names[0]} and ${names[1]}`;
+  return `${names.slice(0, -1).join(", ")}, and ${names[names.length - 1]}`;
+}
+
+interface HeadlineArgs {
+  state: "your-turn" | "waiting" | "phase-only";
+  activePlayerNames: readonly string[] | undefined;
+  label: string;
+  theme: Theme;
+  reducedMotion: boolean;
+}
+
+function renderHeadline({
+  state,
+  activePlayerNames,
+  label,
+  theme,
+  reducedMotion,
+}: HeadlineArgs) {
+  if (state === "phase-only") {
+    return (
+      <div style={textBlockStyle(theme)}>
+        <span style={titleTextStyle(theme)}>{label}</span>
+      </div>
+    );
+  }
+
+  const isYourTurn = state === "your-turn";
+  const intent = isYourTurn
+    ? theme.semantic.intent.success
+    : theme.semantic.intent.info;
+  const titleText = isYourTurn
+    ? "Your turn"
+    : `Waiting for ${formatPlayerList(activePlayerNames ?? [])}…`;
+
+  return (
+    <motion.div
+      initial={reducedMotion ? { opacity: 0 } : { opacity: 0, y: -4 }}
+      animate={reducedMotion ? { opacity: 1 } : { opacity: 1, y: 0 }}
+      style={{
+        display: "flex",
+        alignItems: "center",
+        gap: theme.space[3],
+      }}
+    >
+      <StatusIndicator
+        intent={intent}
+        kind={isYourTurn ? "pulse" : "spinner"}
+        reducedMotion={reducedMotion}
+      />
+      <div style={textBlockStyle(theme)}>
+        <span style={titleTextStyle(theme)}>{titleText}</span>
+        <span style={subtitleTextStyle(theme)}>{label}</span>
+      </div>
+    </motion.div>
+  );
+}
+
+function textBlockStyle(theme: Theme): React.CSSProperties {
+  return {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "flex-start",
+    gap: theme.space[0.5],
+    minWidth: 0,
+  };
+}
+
+function titleTextStyle(theme: Theme): React.CSSProperties {
+  return {
+    fontFamily: theme.typography.fontFamily.body,
+    fontSize: theme.typography.fontSize.lg,
+    fontWeight: theme.typography.fontWeight.bold,
+    letterSpacing: theme.typography.letterSpacing.tight,
+    lineHeight: theme.typography.lineHeight.tight,
+    color: theme.semantic.text.primary,
+  };
+}
+
+function subtitleTextStyle(theme: Theme): React.CSSProperties {
+  return {
+    fontFamily: theme.typography.fontFamily.body,
+    fontSize: theme.typography.fontSize.xs,
+    fontWeight: theme.typography.fontWeight.medium,
+    letterSpacing: theme.typography.letterSpacing.caps,
+    textTransform: "uppercase",
+    color: theme.semantic.text.muted,
+  };
+}
+
+interface StatusIndicatorProps {
+  intent: Theme["semantic"]["intent"]["success"];
+  kind: "pulse" | "spinner";
+  reducedMotion: boolean;
+}
+
+/**
+ * Animated status indicator sized to sit next to a body-font headline.
+ *
+ * Kept intentionally chip-less so it shares the chrome strip's
+ * understated treatment (the rest of the chrome uses bare typography
+ * and lets intent colour live in chips, dots, and borders — not in
+ * full-saturation surfaces). The colour comes from one
+ * {@link Theme}-supplied intent ramp so swapping themes keeps the
+ * indicator consistent with chips, toasts, and buttons that use the
+ * same intent.
+ *
+ * - `pulse` — soft halo radiating outward from a solid centre dot.
+ *   Used for the player's own active turn.
+ * - `spinner` — thin partial ring rotating around a soft-filled
+ *   centre. Reads as the standard "in flight / live" affordance.
+ */
+function StatusIndicator({
+  intent,
+  kind,
+  reducedMotion,
+}: StatusIndicatorProps) {
+  const size = 16;
+
+  if (kind === "pulse") {
+    return (
+      <span
+        aria-hidden="true"
+        style={{
+          position: "relative",
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          width: size,
+          height: size,
+          flexShrink: 0,
+        }}
+      >
+        <motion.span
+          style={{
+            position: "absolute",
+            inset: 2,
+            borderRadius: "9999px",
+            background: intent.soft,
+          }}
+          animate={
+            reducedMotion
+              ? undefined
+              : { scale: [1, 1.6, 1], opacity: [0.7, 0, 0.7] }
+          }
+          transition={{
+            repeat: reducedMotion ? 0 : Infinity,
+            duration: 1.6,
+            ease: "easeOut",
+          }}
+        />
+        <span
+          style={{
+            position: "relative",
+            display: "inline-block",
+            width: 8,
+            height: 8,
+            borderRadius: "9999px",
+            background: intent.solid,
+          }}
+        />
+      </span>
+    );
+  }
+
+  // "spinner" — partial ring rotating around an inset soft fill.
+  return (
+    <span
+      aria-hidden="true"
+      style={{
+        position: "relative",
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width: size,
+        height: size,
+        flexShrink: 0,
+      }}
+    >
+      <span
+        style={{
+          position: "absolute",
+          inset: 4,
+          borderRadius: "9999px",
+          background: intent.soft,
+        }}
+      />
+      <motion.span
+        style={{
+          position: "absolute",
+          inset: 0,
+          borderRadius: "9999px",
+          border: "2px solid transparent",
+          borderTopColor: intent.solid,
+          borderRightColor: intent.solid,
+        }}
+        animate={reducedMotion ? undefined : { rotate: 360 }}
+        transition={{
+          repeat: reducedMotion ? 0 : Infinity,
+          duration: 1.2,
+          ease: "linear",
+        }}
+      />
+    </span>
+  );
+}

package/src/components/PlayArea.tsx

@@ -0,0 +1,125 @@
+/**
+ * Central game board area for active game components (tricks, played
+ * cards, zones, etc.).
+ *
+ * Visual chrome (frame, empty placeholder, card entrance/exit) is
+ * sourced from the active {@link useTheme} so the play area re-skins
+ * with the rest of the shell.
+ */
+
+import { motion, AnimatePresence } from "framer-motion";
+import { clsx } from "clsx";
+import { Card, type CardProps, type ViewCard } from "./Card.js";
+import { useTheme } from "../theme/ThemeProvider.js";
+import { chipStyle } from "../theme/derive.js";
+
+export interface PlayAreaProps<CardData extends ViewCard = ViewCard> {
+  cards: readonly CardData[];
+  filter?: (card: CardData) => boolean;
+  cardSize?: CardProps["size"];
+  renderCard?: CardProps<CardData>["renderContent"];
+  layout?: "grid" | "row";
+  interactive?: boolean;
+  onCardClick?: (cardId: string) => void;
+  "aria-label"?: string;
+  className?: string;
+}
+
+/**
+ * @example
+ * ```tsx
+ * <PlayArea cards={trickCards} layout="row" renderCard={(card) => <PlayingCard card={card} />} />
+ * ```
+ */
+export function PlayArea<CardData extends ViewCard = ViewCard>({
+  cards,
+  filter,
+  cardSize = "md",
+  renderCard,
+  layout = "row",
+  interactive = false,
+  onCardClick,
+  "aria-label": ariaLabel = "Play area",
+  className,
+}: PlayAreaProps<CardData>) {
+  const theme = useTheme();
+  const reducedMotion = theme.motion.reducedMotion === "true";
+  const visibleCards = filter ? cards.filter(filter) : cards;
+
+  const layoutClasses = {
+    grid: "grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 gap-3 sm:gap-6",
+    row: "flex flex-wrap items-center justify-center gap-3 sm:gap-6",
+  };
+
+  return (
+    <div
+      className={clsx(
+        "relative w-full min-h-[200px] sm:min-h-[300px] p-6 sm:p-8",
+        className,
+      )}
+      style={{
+        background: theme.semantic.surface.inset,
+        border: `2px dashed ${theme.semantic.border.default}`,
+        borderRadius: theme.radius.hud,
+        fontFamily: theme.typography.fontFamily.body,
+        color: theme.semantic.text.primary,
+      }}
+      role="region"
+      aria-label={`${ariaLabel} - ${visibleCards.length} item${visibleCards.length !== 1 ? "s" : ""}`}
+    >
+      <AnimatePresence mode="popLayout">
+        {visibleCards.length === 0 ? (
+          <motion.div
+            className="flex items-center justify-center h-full absolute inset-0 pointer-events-none"
+            initial={{ opacity: 0 }}
+            animate={{ opacity: 1 }}
+            exit={{ opacity: 0 }}
+            role="status"
+            aria-live="polite"
+          >
+            <div
+              style={{
+                ...chipStyle(theme, { variant: "warning", size: "md" }),
+                fontSize: theme.typography.fontSize.md,
+                paddingBlock: theme.space[2],
+                paddingInline: theme.space[4],
+              }}
+            >
+              No cards in play
+            </div>
+          </motion.div>
+        ) : (
+          <div className={layoutClasses[layout]}>
+            {visibleCards.map((card, index) => (
+              <motion.div
+                key={card.id}
+                layout={!reducedMotion}
+                initial={
+                  reducedMotion
+                    ? { opacity: 0, scale: 1 }
+                    : { opacity: 0, scale: 0.8 }
+                }
+                animate={{ opacity: 1, scale: 1 }}
+                exit={{ opacity: 0, scale: 0.8 }}
+                transition={{
+                  type: "spring",
+                  stiffness: 260,
+                  damping: 20,
+                  delay: reducedMotion ? 0 : index * 0.05,
+                }}
+              >
+                <Card
+                  card={card}
+                  size={cardSize}
+                  renderContent={renderCard}
+                  disabled={!interactive}
+                  onCardClick={interactive ? onCardClick : undefined}
+                />
+              </motion.div>
+            ))}
+          </div>
+        )}
+      </AnimatePresence>
+    </div>
+  );
+}