@dreamboard-games/ui-sdk 0.0.41

package/src/components/ActionPanel.tsx

@@ -0,0 +1,310 @@
+/**
+ * Collapsible panel for grouping game actions with state-based visibility.
+ *
+ * Visual styling is sourced entirely from the active {@link useTheme}.
+ * The previous bespoke "wobbly notebook" treatment (`wobbly-border-lg` /
+ * `hard-shadow-lg` / hardcoded `#fff9c4` / `#fdfbf7`) has been retired
+ * in favour of `surfaceStyle` + `chipStyle` so the panel re-skins
+ * uniformly when authors swap themes.
+ */
+
+import { useId, useState, type ReactNode } from "react";
+import { motion, AnimatePresence } from "framer-motion";
+import { ChevronUp } from "lucide-react";
+import { useTheme } from "../theme/ThemeProvider.js";
+import {
+  chipStyle,
+  intentForVariant,
+  surfaceStyle,
+  type ButtonVariant,
+} from "../theme/derive.js";
+
+export interface ActionPanelProps {
+  title?: string;
+  /** Current game state/phase for context display */
+  state?: string;
+  /** Human-readable state labels */
+  stateLabels?: Record<string, string>;
+  collapsible?: boolean;
+  defaultExpanded?: boolean;
+  children: ReactNode;
+  className?: string;
+}
+
+export function ActionPanel({
+  title = "Actions",
+  state,
+  stateLabels,
+  collapsible = true,
+  defaultExpanded = true,
+  children,
+  className,
+}: ActionPanelProps) {
+  const theme = useTheme();
+  const reducedMotion = theme.motion.reducedMotion === "true";
+  const contentId = useId();
+  const [isExpanded, setIsExpanded] = useState(defaultExpanded);
+  const [isHovered, setIsHovered] = useState(false);
+
+  const stateLabel = state
+    ? stateLabels?.[state] || state.replace(/([A-Z])/g, " $1").trim()
+    : undefined;
+
+  return (
+    <motion.div
+      initial={reducedMotion ? { opacity: 0 } : { opacity: 0, y: 20 }}
+      animate={reducedMotion ? { opacity: 1 } : { opacity: 1, y: 0 }}
+      className={className}
+      style={{
+        ...surfaceStyle(theme, { tone: "card", radius: "hud" }),
+        boxShadow: theme.elevation.rest,
+        overflow: "hidden",
+      }}
+      role="region"
+      aria-label={title}
+    >
+      <button
+        type="button"
+        onClick={() => collapsible && setIsExpanded(!isExpanded)}
+        onMouseEnter={() => setIsHovered(true)}
+        onMouseLeave={() => setIsHovered(false)}
+        disabled={!collapsible}
+        aria-expanded={isExpanded}
+        aria-controls={contentId}
+        style={{
+          width: "100%",
+          padding: `${theme.space[3]} ${theme.space[4]}`,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: theme.space[3],
+          borderBottom: isExpanded
+            ? `1px dashed ${theme.semantic.border.subtle}`
+            : "1px solid transparent",
+          background:
+            collapsible && isHovered
+              ? theme.semantic.surface.inset
+              : theme.semantic.surface.hud,
+          color: theme.semantic.text.primary,
+          fontFamily: theme.typography.fontFamily.body,
+          cursor: collapsible ? "pointer" : "default",
+          transition: `background ${theme.motion.duration.fast} ${theme.motion.easing.out}`,
+          // Reset native button look.
+          border: "none",
+          textAlign: "left",
+          appearance: "none",
+        }}
+      >
+        <div>
+          <h2
+            style={{
+              margin: 0,
+              fontFamily: theme.typography.fontFamily.display,
+              fontSize: theme.typography.fontSize.xl,
+              fontWeight: theme.typography.fontWeight.bold,
+              color: theme.semantic.text.primary,
+              lineHeight: theme.typography.lineHeight.tight,
+            }}
+          >
+            {title}
+          </h2>
+          {stateLabel && (
+            <p
+              style={{
+                margin: 0,
+                marginTop: theme.space[1],
+                fontSize: theme.typography.fontSize.sm,
+                fontWeight: theme.typography.fontWeight.medium,
+                color: theme.semantic.text.muted,
+                display: "flex",
+                alignItems: "center",
+                gap: theme.space[2],
+              }}
+            >
+              <span
+                style={{
+                  width: 8,
+                  height: 8,
+                  borderRadius: theme.radius.pill,
+                  background: theme.semantic.intent.primary.solid,
+                  border: `1px solid ${theme.semantic.intent.primary.border}`,
+                  display: "inline-block",
+                }}
+              />
+              Phase: {stateLabel}
+            </p>
+          )}
+        </div>
+        {collapsible && (
+          <motion.div
+            animate={
+              reducedMotion ? undefined : { rotate: isExpanded ? 0 : 180 }
+            }
+            transition={{ duration: 0.2 }}
+            style={{
+              padding: theme.space[1],
+              borderRadius: theme.radius.md,
+              border: `1px solid ${theme.semantic.border.default}`,
+              background: theme.semantic.surface.card,
+              color: theme.semantic.text.primary,
+              display: "inline-flex",
+            }}
+          >
+            <ChevronUp
+              size={20}
+              strokeWidth={2.5}
+              aria-hidden="true"
+              style={{ display: "block" }}
+            />
+          </motion.div>
+        )}
+      </button>
+
+      <AnimatePresence initial={false}>
+        {isExpanded && (
+          <motion.div
+            id={contentId}
+            initial={reducedMotion ? { opacity: 0 } : { height: 0, opacity: 0 }}
+            animate={
+              reducedMotion ? { opacity: 1 } : { height: "auto", opacity: 1 }
+            }
+            exit={reducedMotion ? { opacity: 0 } : { height: 0, opacity: 0 }}
+            transition={{ duration: 0.2, ease: "easeInOut" }}
+            style={{
+              overflow: "hidden",
+              background: theme.semantic.surface.card,
+            }}
+          >
+            <div
+              style={{
+                padding: theme.space[4],
+                display: "flex",
+                flexDirection: "column",
+                gap: theme.space[6],
+              }}
+            >
+              {children}
+            </div>
+          </motion.div>
+        )}
+      </AnimatePresence>
+    </motion.div>
+  );
+}
+
+export interface ActionGroupProps {
+  title: string;
+  description?: string;
+  visible?: boolean;
+  /** Highlight style for special phases. Maps directly onto theme intent slots. */
+  variant?: "default" | "warning" | "danger" | "success";
+  children: ReactNode;
+  className?: string;
+}
+
+const VARIANT_TO_INTENT: Record<
+  ActionGroupProps["variant"] & string,
+  ButtonVariant | null
+> = {
+  default: null,
+  warning: "warning",
+  danger: "danger",
+  success: "success",
+};
+
+export function ActionGroup({
+  title,
+  description,
+  visible = true,
+  variant = "default",
+  children,
+  className,
+}: ActionGroupProps) {
+  const theme = useTheme();
+  const reducedMotion = theme.motion.reducedMotion === "true";
+
+  if (!visible) return null;
+
+  const intentVariant = VARIANT_TO_INTENT[variant];
+  const intent = intentVariant ? intentForVariant(theme, intentVariant) : null;
+
+  const containerStyle: React.CSSProperties = intent
+    ? {
+        background: intent.soft,
+        color: intent.onSoft,
+        border: `1px solid ${intent.border}`,
+        borderRadius: theme.radius.lg,
+        boxShadow: theme.elevation.rest,
+      }
+    : {
+        background: theme.semantic.surface.card,
+        color: theme.semantic.text.primary,
+        border: `1px solid ${theme.semantic.border.subtle}`,
+        borderRadius: theme.radius.lg,
+        boxShadow: theme.elevation.rest,
+      };
+
+  return (
+    <motion.div
+      initial={reducedMotion ? { opacity: 0 } : { opacity: 0, x: -10 }}
+      animate={reducedMotion ? { opacity: 1 } : { opacity: 1, x: 0 }}
+      className={className}
+      style={{
+        position: "relative",
+        padding: theme.space[4],
+        fontFamily: theme.typography.fontFamily.body,
+        ...containerStyle,
+      }}
+      role="group"
+      aria-labelledby={`action-group-${title.toLowerCase().replace(/\s+/g, "-")}`}
+    >
+      <span
+        style={{
+          position: "absolute",
+          top: -10,
+          left: theme.space[3],
+          ...chipStyle(theme, { variant: "secondary", size: "sm" }),
+          background: theme.semantic.surface.card,
+        }}
+      >
+        Group
+      </span>
+      <h3
+        id={`action-group-${title.toLowerCase().replace(/\s+/g, "-")}`}
+        style={{
+          margin: 0,
+          fontFamily: theme.typography.fontFamily.display,
+          fontSize: theme.typography.fontSize.lg,
+          fontWeight: theme.typography.fontWeight.bold,
+          color: intent?.onSoft ?? theme.semantic.text.primary,
+          marginBottom: description ? theme.space[2] : theme.space[3],
+        }}
+      >
+        {title}
+      </h3>
+      {description && (
+        <p
+          style={{
+            margin: 0,
+            marginBottom: theme.space[4],
+            fontSize: theme.typography.fontSize.sm,
+            fontWeight: theme.typography.fontWeight.medium,
+            color: intent?.onSoft ?? theme.semantic.text.muted,
+            opacity: 0.85,
+          }}
+        >
+          {description}
+        </p>
+      )}
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          gap: theme.space[3],
+        }}
+      >
+        {children}
+      </div>
+    </motion.div>
+  );
+}

package/src/components/Card.tsx

@@ -0,0 +1,385 @@
+/**
+ * Presentational card component. Feed from reducer views, not runtime state.
+ *
+ * Visual styling is sourced entirely from the active {@link useTheme}
+ * — there are no hardcoded colors, borders, or shadows in this file.
+ * Authors who need a different look should mount a different
+ * {@link ThemeProvider} rather than re-implementing the card primitive.
+ */
+
+import { motion, type HTMLMotionProps } from "framer-motion";
+import { clsx } from "clsx";
+import type { ViewCard } from "@dreamboard/sdk-types";
+import { useTheme } from "../theme/ThemeProvider.js";
+import { motionDuration } from "../theme/derive.js";
+
+export interface CardProps<CardData extends ViewCard = ViewCard>
+  extends Omit<HTMLMotionProps<"button">, "children"> {
+  card: CardData;
+  selected?: boolean;
+  disabled?: boolean;
+  size?: "sm" | "md" | "lg";
+  faceDown?: boolean;
+  renderContent?: (card: CardData) => React.ReactNode;
+  onCardClick?: (cardId: string) => void;
+  "aria-label"?: string;
+}
+
+/**
+ * Reserved keys on `ViewCard.properties` that the default content
+ * renderer recognises and styles consistently. Authors who set these
+ * keys at view-build time get a properly laid-out card face for free
+ * (icon → title → subtitle → effect → cost), instead of the previous
+ * "first three properties as label/value" fallback that produced
+ * inconsistent card faces across games.
+ *
+ * Any other property keys are still rendered, just below the
+ * conventional cluster, so authors can mix and match without losing
+ * data — but the canonical surface should pick from these slots first.
+ *
+ * Slots:
+ *
+ * - `icon` — short visual flag (emoji, glyph). Rendered large at the
+ *   top of the card.
+ * - `title` — primary label. Falls back to `card.name`.
+ * - `subtitle` — short qualifier ("1 VP", "Action", "Resource").
+ * - `effect` — body text describing what the card does.
+ * - `cost` — short cost line ("3 brick"); rendered as a chip footer.
+ */
+const RESERVED_CONTENT_KEYS = [
+  "icon",
+  "title",
+  "subtitle",
+  "effect",
+  "cost",
+] as const;
+
+type ReservedKey = (typeof RESERVED_CONTENT_KEYS)[number];
+
+const RESERVED_KEY_SET: ReadonlySet<string> = new Set(RESERVED_CONTENT_KEYS);
+
+function readReserved(
+  props: Record<string, unknown> | undefined,
+  key: ReservedKey,
+): string | undefined {
+  if (!props) return undefined;
+  const raw = props[key];
+  if (raw === undefined || raw === null) return undefined;
+  return String(raw);
+}
+
+/** Default card content renderer. */
+function DefaultCardContent({ card }: { card: ViewCard }) {
+  const theme = useTheme();
+  const props = card.properties as Record<string, unknown> | undefined;
+  const icon = readReserved(props, "icon");
+  const title = readReserved(props, "title") ?? card.name;
+  const subtitle = readReserved(props, "subtitle");
+  const effect = readReserved(props, "effect");
+  const cost = readReserved(props, "cost");
+  const extra = props
+    ? Object.entries(props).filter(([key]) => !RESERVED_KEY_SET.has(key))
+    : [];
+
+  const hasAnyReserved = icon || title || subtitle || effect || cost;
+
+  return (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        justifyContent: "space-between",
+        height: "100%",
+        textAlign: "center",
+        padding: theme.space[2],
+        gap: theme.space[1],
+      }}
+    >
+      {icon ? (
+        <span
+          aria-hidden
+          style={{
+            fontSize: theme.typography.fontSize["2xl"],
+            lineHeight: 1,
+          }}
+        >
+          {icon}
+        </span>
+      ) : null}
+      {title ? (
+        <span
+          style={{
+            fontFamily: theme.typography.fontFamily.display,
+            fontSize: theme.typography.fontSize.sm,
+            fontWeight: theme.typography.fontWeight.bold,
+            color: theme.semantic.text.primary,
+            lineHeight: theme.typography.lineHeight.tight,
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            display: "-webkit-box",
+            WebkitLineClamp: 2,
+            WebkitBoxOrient: "vertical",
+            wordBreak: "break-word",
+          }}
+        >
+          {title}
+        </span>
+      ) : null}
+      {subtitle ? (
+        <span
+          style={{
+            fontFamily: theme.typography.fontFamily.body,
+            fontSize: theme.typography.fontSize.xs,
+            fontWeight: theme.typography.fontWeight.medium,
+            color: theme.semantic.text.muted,
+            letterSpacing: theme.typography.letterSpacing.wide,
+            textTransform: "uppercase",
+          }}
+        >
+          {subtitle}
+        </span>
+      ) : null}
+      {effect ? (
+        <span
+          style={{
+            fontFamily: theme.typography.fontFamily.body,
+            fontSize: theme.typography.fontSize.xs,
+            color: theme.semantic.text.muted,
+            lineHeight: theme.typography.lineHeight.normal,
+            display: "-webkit-box",
+            WebkitLineClamp: 3,
+            WebkitBoxOrient: "vertical",
+            overflow: "hidden",
+          }}
+        >
+          {effect}
+        </span>
+      ) : null}
+      {cost ? (
+        <span
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            gap: theme.space[1],
+            paddingBlock: theme.space[0.5],
+            paddingInline: theme.space[2],
+            borderRadius: theme.radius.pill,
+            background: theme.semantic.surface.inset,
+            border: `1px solid ${theme.semantic.border.subtle}`,
+            fontFamily: theme.typography.fontFamily.tabular,
+            fontSize: theme.typography.fontSize.xs,
+            fontWeight: theme.typography.fontWeight.bold,
+            color: theme.semantic.text.primary,
+          }}
+        >
+          {cost}
+        </span>
+      ) : null}
+      {!hasAnyReserved && extra.length > 0
+        ? extra.slice(0, 3).map(([key, value]) => (
+            <span
+              key={key}
+              style={{
+                fontFamily: theme.typography.fontFamily.body,
+                fontSize: theme.typography.fontSize.xs,
+                color: theme.semantic.text.primary,
+              }}
+            >
+              <span style={{ color: theme.semantic.text.muted }}>{key}:</span>{" "}
+              <span style={{ fontWeight: theme.typography.fontWeight.bold }}>
+                {String(value)}
+              </span>
+            </span>
+          ))
+        : null}
+      {!hasAnyReserved && extra.length === 0 ? (
+        <span
+          style={{
+            fontFamily: theme.typography.fontFamily.mono,
+            fontSize: theme.typography.fontSize.xs,
+            color: theme.semantic.text.disabled,
+          }}
+        >
+          {card.id.slice(0, 8)}
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * @example
+ * ```tsx
+ * <Card card={card} onCardClick={(id) => console.log(id)} />
+ * ```
+ */
+export function Card<CardData extends ViewCard = ViewCard>({
+  card,
+  selected = false,
+  disabled = false,
+  size = "md",
+  faceDown = false,
+  renderContent,
+  onCardClick,
+  className,
+  "aria-label": ariaLabel,
+  ...motionProps
+}: CardProps<CardData>) {
+  const theme = useTheme();
+  const sizeClasses = {
+    sm: "w-16 h-24 sm:w-20 sm:h-28",
+    md: "w-20 h-32 sm:w-24 sm:h-36",
+    lg: "w-24 h-36 sm:w-32 sm:h-48",
+  };
+
+  const handleClick = () => {
+    if (!disabled && onCardClick) {
+      onCardClick(card.id);
+    }
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent) => {
+    if (!disabled && onCardClick && (e.key === "Enter" || e.key === " ")) {
+      e.preventDefault();
+      onCardClick(card.id);
+    }
+  };
+
+  // Generate accessible label.
+  const label = ariaLabel || card.name || `Card ${card.id}`;
+  const props = card.properties || {};
+  const metadataStr = Object.entries(props)
+    .map(([k, v]) => `${k}: ${v}`)
+    .join(", ");
+
+  // The card silhouette is a deck-card aspect ratio with one *iconic*
+  // detail: stacked corners (`25px 8px 25px 8px / 8px 25px 8px 25px`)
+  // and a hard offset shadow that reads as "physical card" rather than
+  // "Material card". Ported into theme tokens — the offset and corner
+  // radii now scale with `theme.radius.lg` so themes that prefer
+  // squared corners (e.g. `studio`) get a flatter card automatically.
+  const cardCornerRadius = theme.radius.lg;
+  const selectionRingColor = theme.component.card.selectedRing;
+  const restBorderColor = theme.component.card.border;
+  const restShadow = `4px 4px 0px 0px ${restBorderColor}`;
+  const selectedShadow = `6px 6px 0px 0px ${selectionRingColor}`;
+
+  return (
+    <motion.button
+      type="button"
+      className={clsx(
+        "relative",
+        "focus-visible:outline-none",
+        sizeClasses[size],
+        {
+          "cursor-pointer": !disabled && onCardClick,
+          "cursor-not-allowed": disabled,
+          "cursor-default": !onCardClick,
+        },
+        className,
+      )}
+      style={{
+        opacity: disabled ? 0.5 : 1,
+        transitionProperty: "transform",
+        transitionDuration: motionDuration(theme, "normal"),
+        transitionTimingFunction: theme.motion.easing.out,
+      }}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      disabled={disabled}
+      aria-label={`${label}${metadataStr ? `. ${metadataStr}` : ""}`}
+      aria-pressed={selected}
+      aria-disabled={disabled}
+      role="button"
+      tabIndex={disabled ? -1 : 0}
+      {...motionProps}
+      initial={motionProps.initial ?? { opacity: 0, y: 20 }}
+      animate={motionProps.animate ?? { opacity: 1, y: 0 }}
+      whileHover={
+        // Honour explicit overrides; otherwise apply a default lift only
+        // when the card is interactive and the theme allows motion.
+        "whileHover" in motionProps
+          ? motionProps.whileHover
+          : !disabled && onCardClick && theme.motion.reducedMotion !== "true"
+            ? { y: -4, scale: 1.05 }
+            : undefined
+      }
+      whileTap={
+        "whileTap" in motionProps
+          ? motionProps.whileTap
+          : !disabled && onCardClick && theme.motion.reducedMotion !== "true"
+            ? { scale: 0.95 }
+            : undefined
+      }
+      transition={
+        motionProps.transition ?? {
+          type: "spring",
+          stiffness: 300,
+          damping: 20,
+        }
+      }
+    >
+      {faceDown ? (
+        <div
+          className="absolute inset-0 overflow-hidden pointer-events-none"
+          style={{
+            background: theme.component.card.backBackground,
+            borderStyle: "solid",
+            borderWidth: 3,
+            borderColor: theme.component.card.backBorder,
+            borderRadius: `${cardCornerRadius} ${theme.radius.sm} ${cardCornerRadius} ${theme.radius.sm} / ${theme.radius.sm} ${cardCornerRadius} ${theme.radius.sm} ${cardCornerRadius}`,
+            boxShadow: `4px 4px 0px 0px ${theme.component.card.backBorder}`,
+          }}
+        >
+          <div
+            className="absolute inset-2"
+            style={{
+              borderStyle: "solid",
+              borderWidth: 2,
+              borderColor: `${theme.component.card.border}66`,
+              borderRadius: `${theme.radius.md} ${theme.radius.sm} ${theme.radius.md} ${theme.radius.sm} / ${theme.radius.sm} ${theme.radius.md} ${theme.radius.sm} ${theme.radius.md}`,
+              background:
+                "repeating-linear-gradient(45deg, transparent, transparent 10px, rgba(255,255,255,0.2) 10px, rgba(255,255,255,0.2) 20px)",
+            }}
+          />
+        </div>
+      ) : (
+        <div
+          className="absolute inset-0 overflow-hidden pointer-events-none"
+          style={{
+            background: theme.semantic.surface.card,
+            borderStyle: "solid",
+            borderWidth: 3,
+            borderColor: restBorderColor,
+            borderRadius: `${cardCornerRadius} ${theme.radius.sm} ${cardCornerRadius} ${theme.radius.sm} / ${theme.radius.sm} ${cardCornerRadius} ${theme.radius.sm} ${cardCornerRadius}`,
+            boxShadow: selected ? selectedShadow : restShadow,
+            outline: selected ? `4px solid ${selectionRingColor}` : undefined,
+          }}
+        >
+          {renderContent ? (
+            renderContent(card)
+          ) : (
+            <DefaultCardContent card={card} />
+          )}
+        </div>
+      )}
+
+      {!disabled && onCardClick && theme.motion.reducedMotion !== "true" && (
+        <motion.div
+          className="absolute inset-0 pointer-events-none"
+          style={{
+            borderRadius: theme.radius.lg,
+            background:
+              "linear-gradient(135deg, rgba(255,255,255,0) 0%, rgba(255,255,255,0.3) 50%, rgba(255,255,255,0) 100%)",
+            opacity: 0,
+          }}
+          whileHover={{ opacity: 1 }}
+          transition={{ duration: 0.3 }}
+        />
+      )}
+    </motion.button>
+  );
+}
+
+export type { ViewCard };