@dreamboard-games/ui-sdk 0.0.41

package/src/components/surfaces/PanelSurface.test.tsx

@@ -0,0 +1,496 @@
+import { expect, test } from "bun:test";
+import { renderToString } from "react-dom/server";
+import { ClientParamSchemaProvider } from "../../context/ClientParamSchemaContext.js";
+import {
+  createInteractionUiStore,
+  InteractionUiProvider,
+} from "../../context/InteractionDraftContext.js";
+import { RuntimeContext } from "../../context/RuntimeContext.js";
+import { PluginSessionContext } from "../../context/PluginSessionContext.js";
+import type { InteractionHandle } from "../../hooks/useInteractionHandle.js";
+import type {
+  InteractionDescriptor,
+  PluginStateSnapshot,
+} from "../../types/plugin-state.js";
+import type {
+  PluginSessionState,
+  RuntimeAPI,
+} from "../../types/runtime-api.js";
+import { PanelSurface, defaultPanelSalience } from "./PanelSurface.js";
+
+// React's SSR splits text nodes around dynamic children with HTML
+// comments — `(<!-- -->2<!-- -->)` reads `(2)` to humans but breaks
+// substring assertions. This helper strips the comments before we
+// assert so tests stay focused on the user-visible contract.
+function stripSsrComments(html: string): string {
+  return html.replace(/<!--\s*-->/g, "");
+}
+
+function createSessionState(): PluginSessionState {
+  return {
+    status: "ready",
+    sessionId: "session-1",
+    controllablePlayerIds: ["player-1"],
+    controllingPlayerId: "player-1",
+    userId: "user-1",
+  };
+}
+
+function createPanelDescriptor(
+  id: string,
+  overrides: Partial<InteractionDescriptor> = {},
+): InteractionDescriptor {
+  return {
+    phaseName: "play",
+    interactionKey: `play.${id}`,
+    interactionId: id,
+    kind: "action",
+    inputs: [],
+    commit: { mode: "manual" },
+    available: true,
+    ...overrides,
+  };
+}
+
+function createSnapshot(
+  session: PluginSessionState,
+  descriptors: InteractionDescriptor[],
+): PluginStateSnapshot {
+  return {
+    view: null,
+    gameplay: {
+      currentPhase: "play",
+      currentStage: null,
+      activePlayers: ["player-1"],
+      availableInteractions: descriptors,
+      zones: {},
+    },
+    lobby: null,
+    notifications: [],
+    session,
+    history: null,
+    syncId: 1,
+  };
+}
+
+function createRuntime(
+  snapshot: PluginStateSnapshot,
+  submitted?: Array<{
+    playerId: string;
+    interactionId: string;
+    params: Record<string, unknown>;
+  }>,
+): RuntimeAPI & {
+  getSnapshot: () => PluginStateSnapshot;
+  subscribeToState: (
+    listener: (state: PluginStateSnapshot) => void,
+  ) => () => void;
+} {
+  return {
+    validateInteraction: async () => ({ valid: true }),
+    submitInteraction: async (playerId, interactionId, params) => {
+      submitted?.push({ playerId, interactionId, params });
+    },
+    getSessionState: () => snapshot.session,
+    disconnect: () => undefined,
+    getSnapshot: () => snapshot,
+    subscribeToState: () => () => undefined,
+  };
+}
+
+function render(
+  snapshot: PluginStateSnapshot,
+  panelProps?: React.ComponentProps<typeof PanelSurface>,
+): string {
+  const runtime = createRuntime(snapshot);
+  return renderToString(
+    <RuntimeContext.Provider value={runtime}>
+      <PluginSessionContext.Provider value={snapshot.session}>
+        <PanelSurface {...panelProps} />
+      </PluginSessionContext.Provider>
+    </RuntimeContext.Provider>,
+  );
+}
+
+// ── Default salience derivation ────────────────────────────────────
+
+test("defaultPanelSalience keeps reducer descriptors in the neutral tier", () => {
+  expect(defaultPanelSalience(createPanelDescriptor("a"))).toBe("secondary");
+});
+
+// ── Sorting + tier markers ─────────────────────────────────────────
+
+test("PanelSurface sorts hero before secondary; tertiary is hidden by the closed disclosure", () => {
+  const session = createSessionState();
+  // Authored order is [secondary, destructive, primary] so we can
+  // prove the sort is doing real work and not just preserving input
+  // order. The destructive descriptor defaults to `tertiary` and
+  // therefore lives inside `<MoreActions>` — closed by default, so
+  // its button is NOT in the SSR tree.
+  const snapshot = createSnapshot(session, [
+    createPanelDescriptor("buildSettlement"),
+    createPanelDescriptor("dropOut"),
+    createPanelDescriptor("rollDice"),
+  ]);
+
+  const html = render(snapshot, {
+    salienceFor: (descriptor) =>
+      descriptor.interactionId === "rollDice"
+        ? "hero"
+        : descriptor.interactionId === "dropOut"
+          ? "tertiary"
+          : "secondary",
+  });
+  const indexOf = (id: string) => html.indexOf(`data-interaction-id="${id}"`);
+
+  expect(indexOf("rollDice")).toBeGreaterThanOrEqual(0);
+  expect(indexOf("buildSettlement")).toBeGreaterThan(indexOf("rollDice"));
+  // Tertiary descriptor is collapsed; its button shouldn't appear.
+  // The disclosure toggle still surfaces the count so the player
+  // knows hidden actions exist. SSR splits text nodes around dynamic
+  // children with HTML comments (`(<!-- -->1<!-- -->)`); the regex
+  // ignores those so the assertion stays focused on the contract.
+  expect(html).not.toContain('data-interaction-id="dropOut"');
+  expect(html).toContain('data-shell-slot="more-actions"');
+  expect(stripSsrComments(html)).toContain("(1)");
+});
+
+test("PanelSurface tags hero and secondary buttons with their resolved tier", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createPanelDescriptor("rollDice"),
+    createPanelDescriptor("buildSettlement"),
+  ]);
+
+  const html = render(snapshot, {
+    salienceFor: (descriptor) =>
+      descriptor.interactionId === "rollDice" ? "hero" : "secondary",
+  });
+
+  // Each button carries a `data-panel-tier` so author CSS / tests can
+  // target a tier without re-deriving it from emphasis. We assert on
+  // visible (hero + secondary) tiers — tertiary tags get exercised
+  // separately when we open the disclosure programmatically.
+  expect(html).toMatch(
+    /data-interaction-id="rollDice"[^>]*data-panel-tier="hero"/,
+  );
+  expect(html).toMatch(
+    /data-interaction-id="buildSettlement"[^>]*data-panel-tier="secondary"/,
+  );
+});
+
+test("PanelSurface hides unavailable interactions by default and exposes opt-in", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createPanelDescriptor("legal"),
+    createPanelDescriptor("staleStep", {
+      available: false,
+      unavailableReason: "Not in this step",
+    }),
+  ]);
+
+  expect(render(snapshot)).toContain('data-interaction-id="legal"');
+  expect(render(snapshot)).not.toContain('data-interaction-id="staleStep"');
+
+  const withUnavailable = render(snapshot, { showUnavailable: true });
+  expect(withUnavailable).toContain('data-interaction-id="legal"');
+  expect(withUnavailable).toContain('data-interaction-id="staleStep"');
+});
+
+// ── More disclosure ─────────────────────────────────────────────────
+
+test("PanelSurface renders a More disclosure when tertiary descriptors are present", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createPanelDescriptor("buildSettlement"),
+    createPanelDescriptor("dropOut"),
+    createPanelDescriptor("forfeit"),
+  ]);
+
+  const html = render(snapshot, {
+    salienceFor: (descriptor) =>
+      descriptor.interactionId === "buildSettlement" ? "secondary" : "tertiary",
+  });
+
+  // Toggle is present, advertises the count, and starts collapsed.
+  expect(html).toContain('data-shell-slot="more-actions"');
+  expect(html).toContain('data-more-actions-open="false"');
+  expect(stripSsrComments(html)).toContain("(2)");
+  expect(html).toContain('aria-expanded="false"');
+});
+
+test("PanelSurface omits the More disclosure when nothing is hidden", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createPanelDescriptor("buildSettlement"),
+    createPanelDescriptor("rollDice"),
+  ]);
+
+  const html = render(snapshot);
+
+  expect(html).not.toContain('data-shell-slot="more-actions"');
+});
+
+test("PanelSurface spills excess secondaries past maxVisibleSecondary into More", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createPanelDescriptor("a"),
+    createPanelDescriptor("b"),
+    createPanelDescriptor("c"),
+    createPanelDescriptor("d"),
+  ]);
+
+  const html = render(snapshot, { maxVisibleSecondary: 2 });
+
+  // Disclosure mounts because excess secondaries got spilled.
+  expect(html).toContain('data-shell-slot="more-actions"');
+  // The third + fourth secondary land inside the disclosure (count 2).
+  expect(stripSsrComments(html)).toContain("(2)");
+});
+
+// ── Group cohesion ──────────────────────────────────────────────────
+
+test("PanelSurface keeps grouped clusters together using the group's max salience", () => {
+  const session = createSessionState();
+  // A cluster with one hero member and one tertiary member should
+  // render as a single hero-tier group inline — the tertiary stays
+  // with the hero because splitting the build cluster would be more
+  // confusing than rendering its low-importance sibling early.
+  const snapshot = createSnapshot(session, [
+    createPanelDescriptor("buildSettlement", {}),
+    createPanelDescriptor("buildRoad", {}),
+    createPanelDescriptor("trade"),
+  ]);
+
+  const html = render(snapshot, {
+    groupBy: (descriptor) =>
+      descriptor.interactionId.startsWith("build") ? "build" : undefined,
+    salienceFor: (descriptor) =>
+      descriptor.interactionId === "buildSettlement" ? "hero" : "secondary",
+  });
+
+  // Both build interactions are inside the cluster wrapper, marked
+  // with the cluster's resolved tier (hero, since one member is hero).
+  expect(html).toContain('data-panel-group="group:build"');
+  expect(html).toMatch(
+    /data-panel-group="group:build"[^>]*data-panel-tier="hero"/,
+  );
+  // The cluster wins ordering against the lone secondary even though
+  // the secondary is not destructured — verify by raw position.
+  const clusterIndex = html.indexOf('data-panel-group="group:build"');
+  const tradeIndex = html.indexOf('data-interaction-id="trade"');
+  expect(clusterIndex).toBeGreaterThanOrEqual(0);
+  expect(tradeIndex).toBeGreaterThan(clusterIndex);
+  // No disclosure — the build cluster carries its tertiary along
+  // inline rather than spilling it.
+  expect(html).not.toContain('data-shell-slot="more-actions"');
+});
+
+// ── Custom salienceFor + label overrides ────────────────────────────
+
+test("PanelSurface honours a custom salienceFor override", () => {
+  const session = createSessionState();
+  // The descriptor would land in `secondary` by default; the override
+  // demotes it to `tertiary` so it spills into More.
+  const snapshot = createSnapshot(session, [
+    createPanelDescriptor("buildSettlement"),
+    createPanelDescriptor("buildCity"),
+  ]);
+
+  const html = render(snapshot, {
+    salienceFor: (descriptor) =>
+      descriptor.interactionId === "buildCity" ? "tertiary" : "secondary",
+    moreActionsLabel: "Advanced",
+  });
+
+  expect(html).toContain('data-shell-slot="more-actions"');
+  expect(html).toContain("Advanced");
+  expect(stripSsrComments(html)).toContain("(1)");
+});
+
+test("PanelSurface marks default form interactions as expandable", () => {
+  const session = createSessionState();
+  const snapshot = createSnapshot(session, [
+    createPanelDescriptor("offerTrade", {
+      inputs: [
+        {
+          key: "resource",
+          kind: "form",
+          domain: {
+            type: "choice",
+            choices: [{ value: "wood", label: "Wood" }],
+          },
+        },
+      ],
+    }),
+  ]);
+
+  const html = render(snapshot);
+
+  expect(html).toContain("Offer Trade");
+  expect(html).toContain("data-default-interaction");
+  expect(html).toContain('aria-expanded="false"');
+  expect(html).not.toContain("Wood");
+});
+
+test("PanelSurface handle validates and submits typed draft params", async () => {
+  const session = createSessionState();
+  const descriptor = createPanelDescriptor("offerTrade", {
+    inputs: [
+      {
+        key: "resource",
+        kind: "form",
+        defaultValue: "wood",
+        domain: {
+          type: "choice",
+          choices: [
+            { value: "wood", label: "Wood" },
+            { value: "brick", label: "Brick" },
+          ],
+        },
+      },
+    ],
+  });
+  const snapshot = createSnapshot(session, [descriptor]);
+  const submitted: Array<{
+    playerId: string;
+    interactionId: string;
+    params: Record<string, unknown>;
+  }> = [];
+  const runtime = createRuntime(snapshot, submitted);
+  const draftStore = createInteractionUiStore();
+  let captured: InteractionHandle<{ resource: string }, never> | null = null;
+
+  renderToString(
+    <RuntimeContext.Provider value={runtime}>
+      <PluginSessionContext.Provider value={session}>
+        <ClientParamSchemaProvider
+          schemas={{
+            play: {
+              offerTrade: {
+                safeParse: (value) => {
+                  const resource = (value as { resource?: unknown }).resource;
+                  return resource === "wood" || resource === "brick"
+                    ? {
+                        success: true,
+                        data: { resource },
+                      }
+                    : {
+                        success: false,
+                        error: {
+                          issues: [
+                            {
+                              path: ["resource"],
+                              message: "Choose a resource",
+                            },
+                          ],
+                        },
+                      };
+                },
+              },
+            },
+          }}
+        >
+          <InteractionUiProvider store={draftStore}>
+            <PanelSurface<
+              "play.offerTrade",
+              { "play.offerTrade": { resource: string } }
+            >
+              renderItem={(_descriptor, handle) => {
+                captured = handle;
+                return <span>captured</span>;
+              }}
+            />
+          </InteractionUiProvider>
+        </ClientParamSchemaProvider>
+      </PluginSessionContext.Provider>
+    </RuntimeContext.Provider>,
+  );
+
+  if (!captured) throw new Error("expected PanelSurface to expose a handle");
+
+  expect(captured.validateDraft()).toEqual({
+    ok: true,
+    params: { resource: "wood" },
+    fieldErrors: {},
+    formErrors: [],
+    missing: [],
+  });
+  await captured.submitDraft();
+
+  expect(submitted).toEqual([
+    {
+      playerId: "player-1",
+      interactionId: "offerTrade",
+      params: { resource: "wood" },
+    },
+  ]);
+  expect(draftStore.getDraft(descriptor.interactionKey)).toEqual({});
+});
+
+test("PanelSurface handle reports missing inputs as required", () => {
+  const session = createSessionState();
+  const descriptor = createPanelDescriptor("configure", {
+    inputs: [
+      {
+        key: "selection",
+        kind: "form",
+        domain: {
+          type: "choice",
+          choices: [{ value: "wood", label: "Wood" }],
+        },
+      },
+    ],
+  });
+  const snapshot = createSnapshot(session, [descriptor]);
+  const runtime = createRuntime(snapshot);
+  let captured: InteractionHandle<{ selection: string }, never> | null = null;
+
+  renderToString(
+    <RuntimeContext.Provider value={runtime}>
+      <PluginSessionContext.Provider value={session}>
+        <ClientParamSchemaProvider
+          schemas={{
+            play: {
+              configure: {
+                safeParse: () => ({
+                  success: false,
+                  error: {
+                    issues: [
+                      {
+                        path: ["selection"],
+                        message:
+                          "Invalid input: expected string, received undefined",
+                      },
+                    ],
+                  },
+                }),
+              },
+            },
+          }}
+        >
+          <InteractionUiProvider>
+            <PanelSurface<
+              "play.configure",
+              { "play.configure": { selection: string } }
+            >
+              renderItem={(_descriptor, handle) => {
+                captured = handle;
+                return <span>captured</span>;
+              }}
+            />
+          </InteractionUiProvider>
+        </ClientParamSchemaProvider>
+      </PluginSessionContext.Provider>
+    </RuntimeContext.Provider>,
+  );
+
+  if (!captured) throw new Error("expected PanelSurface to expose a handle");
+
+  expect(captured.validateDraft()).toEqual({
+    ok: false,
+    fieldErrors: {},
+    formErrors: [],
+    missing: ["selection"],
+  });
+});