@dreamboard-games/sdk 0.2.0

package/src/types/generated-helpers.ts

@@ -0,0 +1,35 @@
+type RecordInitializer<Id extends string, Value> = Value | ((id: Id) => Value);
+
+export function buildTypedRecord<Id extends string, Value>(
+  ids: readonly Id[],
+  initial: RecordInitializer<Id, Value>,
+): Record<Id, Value> {
+  const createValue =
+    typeof initial === "function"
+      ? (initial as (id: Id) => Value)
+      : () => initial;
+
+  return Object.fromEntries(ids.map((id) => [id, createValue(id)])) as Record<
+    Id,
+    Value
+  >;
+}
+
+export function isTypedId<Id extends string>(
+  ids: readonly Id[],
+  value: string,
+): value is Id {
+  return (ids as readonly string[]).includes(value);
+}
+
+export function expectTypedId<Id extends string>(
+  ids: readonly Id[],
+  value: string,
+  description: string,
+): Id {
+  if (isTypedId(ids, value)) {
+    return value;
+  }
+
+  throw new Error(`Unknown ${description} '${value}'.`);
+}

package/src/types/index.ts

@@ -0,0 +1,147 @@
+import type {
+  DieTypeSpec as ApiDieTypeSpec,
+  GameTopologyManifest as ApiGameTopologyManifest,
+} from "./contracts.js";
+
+export type {
+  ActionDefinition,
+  ActionInteractionDescriptor,
+  ActionParameterDefinition,
+  AvailableInteractionAvailability,
+  BlockedInteractionAvailability,
+  BoardCard,
+  BoardContainerHostSpec,
+  BoardContainerSpec,
+  BoardEdgeRef,
+  BoardHostSpec,
+  BoardLayout,
+  BoardRelationSpec,
+  BoardSpaceSpec,
+  BoardSpec,
+  BoardTargetDomain,
+  BoardTemplateSpec,
+  BoardVertexRef,
+  BoundedNumberDomain,
+  CardPropertySchema,
+  CardPropertySchemaVariants,
+  CardSetDefinition,
+  CardSetSourceType,
+  CardTargetDomain,
+  ChoiceDomain,
+  ChoiceDomainOption,
+  ChoiceListDomain,
+  ComponentHomeSpec,
+  ComponentSlotSpec,
+  ComponentVisibilitySpec,
+  ContainerHomeSpec,
+  DetachedHomeSpec,
+  DieSeedSpec,
+  DieSlotHostRef,
+  EagerInputDomainDependencies,
+  EdgeHomeSpec,
+  GenericBoardSpec,
+  GenericBoardTemplateSpec,
+  HexBoardSpec,
+  HexBoardTemplateSpec,
+  HexEdgeRef,
+  HexEdgeSpec,
+  HexOrientation,
+  HexSpaceSpec,
+  HexVertexRef,
+  HexVertexSpec,
+  HistoryEntrySummary,
+  HostActionSubmitResponse,
+  HostEndedSessionSnapshot,
+  HostGameplaySeatView,
+  HostGameplaySessionSnapshot,
+  HostGameplaySharedView,
+  HostLobbySessionSnapshot,
+  HostLobbyView,
+  HostPlayerGameplayView,
+  HostSessionContext,
+  HostSessionEventCausation,
+  HostSessionGameplayUpdatedEvent,
+  HostSessionSnapshot,
+  HostSessionStatus,
+  InputDomain,
+  InputDomainDependencyCase,
+  InputDomainResolver,
+  InputSelection,
+  InsufficientResourcesInteractionAvailability,
+  InteractionAvailability,
+  InteractionCommitPolicy,
+  InteractionContext,
+  InteractionContextOption,
+  InteractionDescriptor,
+  InteractionDescriptorBase,
+  InteractionInputDescriptor,
+  JsonValue,
+  LazyBoardTargetDomain,
+  LazyCardTargetDomain,
+  LazyInputDomainDependencies,
+  ManualCardSetDefinition,
+  ManyInputSelection,
+  NotYourTurnInteractionAvailability,
+  ObjectSchema,
+  ParameterType,
+  PieceSeedSpec,
+  PieceSlotHostRef,
+  PieceTypeSpec,
+  PlayerId,
+  PlayersDefinition,
+  PresetCardSetDefinition,
+  PromptInteractionDescriptor,
+  PropertySchema,
+  ResolvedBoardTargetDomain,
+  ResolvedCardTargetDomain,
+  ResourceDefinition,
+  ResourceMapDomain,
+  ResourceMapDomainEntry,
+  SeatAssignment,
+  SessionActor,
+  SessionActorAuthUser,
+  SessionActorDemoGuest,
+  SessionGameSource,
+  SessionGameSourceDemoRevision,
+  SessionGameSourceUserCompiled,
+  SessionSnapshotHistory,
+  SessionSnapshotPhase,
+  SetupOptionChoiceSpec,
+  SetupOptionSpec,
+  SetupProfileSpec,
+  SimultaneousPhaseSnapshot,
+  SingleInputSelection,
+  SlotHomeSpec,
+  SlotHostRef,
+  SpaceHomeSpec,
+  SpaceHostSpec,
+  SquareBoardSpec,
+  SquareBoardTemplateSpec,
+  SquareEdgeSpec,
+  SquareSpaceSpec,
+  SquareVertexSpec,
+  TopologyScope,
+  VertexHomeSpec,
+  ZoneHandles,
+  ZoneHomeSpec,
+  ZoneSpec,
+  ZoneVisibility,
+} from "./contracts.js";
+
+export type DieTypeSpec = Omit<ApiDieTypeSpec, "sides"> & {
+  sides?: ApiDieTypeSpec["sides"];
+};
+
+export type GameTopologyManifest = Omit<ApiGameTopologyManifest, "dieTypes"> & {
+  dieTypes?: Array<DieTypeSpec>;
+};
+
+export type { CardCollection, ViewCard } from "./cards.js";
+export type { ViewSlotOccupant } from "./slots.js";
+export { defineTopologyManifest } from "./authoring.js";
+export type { TypedTopologyManifest } from "./authoring.js";
+export {
+  buildTypedRecord,
+  expectTypedId,
+  isTypedId,
+} from "./generated-helpers.js";

package/src/types/slots.ts

@@ -0,0 +1,11 @@
+export interface ViewSlotOccupant<
+  PieceIdValue extends string = string,
+  PlayerIdValue extends string = string,
+  SlotIdValue extends string = string,
+  Data extends Record<string, unknown> = Record<string, unknown>,
+> {
+  pieceId: PieceIdValue;
+  playerId: PlayerIdValue | null;
+  slotId: SlotIdValue;
+  data?: Data;
+}

package/src/types.ts

@@ -0,0 +1 @@
+export * from "./types/index.js";

package/src/ui/components/ActionButton.tsx

@@ -0,0 +1,97 @@
+import type {
+  ButtonHTMLAttributes,
+  ElementType,
+  MouseEvent,
+  ReactNode,
+} from "react";
+import type { ButtonSize, ButtonVariant } from "../theme/derive.js";
+import type { InteractionVisualState } from "../types/visual-state.js";
+import { CostDisplay, type ResourceDefinition } from "./CostDisplay.js";
+import { ThemedButton } from "./ThemedButton.js";
+
+export interface ActionButtonProps
+  extends
+    Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children">,
+    InteractionVisualState {
+  label?: ReactNode;
+  description?: ReactNode;
+  icon?: ElementType<{ className?: string }>;
+  cost?: Record<string, number>;
+  currentResources?: Record<string, number>;
+  resourceDefs?: ResourceDefinition[];
+  available?: boolean;
+  disabledReason?: string;
+  loading?: boolean;
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  children?: ReactNode;
+}
+
+export function ActionButton({
+  label,
+  description,
+  icon,
+  cost,
+  currentResources,
+  resourceDefs,
+  available = true,
+  disabledReason,
+  loading = false,
+  disabled,
+  eligible,
+  selected,
+  invalid,
+  submitted,
+  previewing,
+  intentProgress,
+  title,
+  variant = "secondary",
+  size = "md",
+  children,
+  onClick,
+  ...rest
+}: ActionButtonProps) {
+  const isDisabled = disabled || loading || !available;
+  const Icon = icon;
+  const resolvedTitle = title ?? (!available ? disabledReason : undefined);
+
+  function handleClick(event: MouseEvent<HTMLButtonElement>) {
+    if (isDisabled) return;
+    onClick?.(event);
+  }
+
+  return (
+    <ThemedButton
+      type="button"
+      variant={variant}
+      size={size}
+      disabled={isDisabled}
+      eligible={eligible ?? (available && !isDisabled ? undefined : undefined)}
+      selected={selected}
+      invalid={invalid}
+      submitted={submitted}
+      previewing={previewing}
+      intentProgress={intentProgress}
+      loading={loading}
+      title={resolvedTitle}
+      onClick={handleClick}
+      {...rest}
+    >
+      {Icon ? <Icon className="h-4 w-4" aria-hidden="true" /> : null}
+      <span className="inline-flex min-w-0 flex-col items-start gap-0.5">
+        <span>{children ?? label ?? "Action"}</span>
+        {description ? (
+          <span className="text-xs font-normal opacity-75">{description}</span>
+        ) : null}
+        {cost && resourceDefs ? (
+          <CostDisplay
+            cost={cost}
+            currentResources={currentResources}
+            resourceDefs={resourceDefs}
+          />
+        ) : null}
+      </span>
+      {loading ? <span aria-hidden="true">...</span> : null}
+    </ThemedButton>
+  );
+}

package/src/ui/components/ActionPanel.tsx

@@ -0,0 +1,315 @@
+/**
+ * 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}
+      data-dreamboard-action-panel=""
+      data-state={isExpanded ? "open" : "closed"}
+      data-collapsible={collapsible ? "true" : undefined}
+      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}
+      data-dreamboard-action-group=""
+      data-variant={variant}
+      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>
+  );
+}