@dreamboard-games/ui-sdk 0.0.41

package/src/components/surfaces/PlayerCardsSurface.tsx

@@ -0,0 +1,525 @@
+import { Fragment, useMemo, useState, type ReactNode } from "react";
+import type { ViewCard } from "@dreamboard/sdk-types";
+import { usePluginState } from "../../context/PluginStateContext.js";
+import type { CardSize, HandLayout } from "../../hooks/useHandLayout.js";
+import { useTheme } from "../../theme/ThemeProvider.js";
+import { Card } from "../Card.js";
+import { Drawer, DrawerContent, DrawerHeader, DrawerTitle } from "../Drawer.js";
+import { Hand } from "../Hand.js";
+import {
+  useCardZoneInteractions,
+  type CardZoneInteractionContext,
+} from "./internal/useCardZoneInteractions.js";
+import { CardZoneFollowUpForm } from "./internal/CardZoneFollowUpForm.js";
+import type { InteractionParamsByKeyShape } from "./types.js";
+
+export type PlayerCardsLayout<ZoneKey extends string = string> =
+  | PlayerCardZoneNode<ZoneKey>
+  | PlayerCardsGroup<ZoneKey>;
+
+export interface PlayerCardsGroup<ZoneKey extends string = string> {
+  kind: "group";
+  direction: "row" | "column";
+  children: ReadonlyArray<PlayerCardsLayout<ZoneKey>>;
+}
+
+export interface PlayerCardZoneModel<I extends string = string> {
+  zoneId: string;
+  label: string;
+  totalCount: number;
+  visibleCards: readonly ViewCard[];
+  hiddenCount: number;
+  hiddenCardIds: readonly string[];
+  contexts: ReadonlyArray<CardZoneInteractionContext<I>>;
+  contextsByCardId: ReadonlyMap<string, CardZoneInteractionContext<I>>;
+}
+
+export type PlayerCardZoneNode<ZoneKey extends string = string> =
+  | PlayerCardsPileNode<ZoneKey>
+  | PlayerCardsFanNode<ZoneKey>
+  | PlayerCardsCustomNode<ZoneKey>;
+
+export interface PlayerCardsPileNode<ZoneKey extends string = string> {
+  kind: "pile";
+  zone: ZoneKey;
+  label?: string;
+  top?: "first" | "last";
+  details?: "drawer" | "none";
+  /**
+   * Explicit override for the count badge. Use when the player view
+   * hides the zone's `cardIds` (private decks, hidden draw piles) so
+   * the SDK's auto-derived `zone.totalCount` reads zero. The reducer
+   * still owns the source of truth — pass it through `defineView`.
+   */
+  count?: number;
+  /**
+   * Explicit override for the visible top-card preview. Use when the
+   * top card isn't part of the player's zone projection but is known
+   * via a custom view field. Falls back to {@link top} selection over
+   * `zone.visibleCards` when omitted.
+   */
+  topCard?: ViewCard | null;
+  /**
+   * Replace just the visible top-card / face-down preview while keeping
+   * the SDK's button + count badge + drawer machinery. Use this when you
+   * want a custom card face but still want clicks to open the drawer.
+   */
+  renderPreview?: (zone: PlayerCardZoneModel) => ReactNode;
+  /** Replace the empty-state (no cards) preview only. */
+  renderEmpty?: (zone: PlayerCardZoneModel) => ReactNode;
+  /**
+   * Per-card content renderer used by the default drawer body. Authors
+   * who supply this on every node can hoist it to the surface root via
+   * {@link PlayerCardsSurfaceConfig.renderCardContent}.
+   */
+  renderCardContent?: (
+    card: ViewCard,
+    ctx: CardZoneInteractionContext,
+  ) => ReactNode;
+  /** Replace the drawer body wholesale. */
+  renderDrawerContent?: (zone: PlayerCardZoneModel) => ReactNode;
+  /**
+   * Escape hatch — replaces the pile entirely (button, count badge,
+   * drawer, click handling). Prefer {@link renderPreview} +
+   * {@link renderDrawerContent} so authors don't accidentally drop the
+   * default click-to-open behavior. Reserved for cases that need fully
+   * bespoke chrome.
+   */
+  renderPile?: (zone: PlayerCardZoneModel) => ReactNode;
+}
+
+export interface PlayerCardsFanNode<ZoneKey extends string = string> {
+  kind: "fan";
+  zone: ZoneKey;
+  label?: string;
+  renderCardContent?: (
+    card: ViewCard,
+    ctx: CardZoneInteractionContext,
+  ) => ReactNode;
+  renderZone?: (zone: PlayerCardZoneModel) => ReactNode;
+  cardSize?: CardSize;
+  layout?: HandLayout;
+}
+
+export interface PlayerCardsCustomNode<ZoneKey extends string = string> {
+  kind: "custom";
+  zone: ZoneKey;
+  label?: string;
+  renderZone: (zone: PlayerCardZoneModel) => ReactNode;
+}
+
+export interface PlayerCardsSurfaceConfig<ZoneKey extends string = string> {
+  layout: PlayerCardsLayout<ZoneKey>;
+  /**
+   * Default per-card content renderer inherited by every `pile` and
+   * `fan` in the layout. Per-node `renderCardContent` (on a fan) or
+   * `renderCardContent` / `renderPreview` (on a pile) still wins. Set
+   * this once at the surface root to avoid passing the same `<CardFace>`
+   * to every zone.
+   */
+  renderCardContent?: (
+    card: ViewCard,
+    ctx: CardZoneInteractionContext,
+  ) => ReactNode;
+}
+
+export interface PlayerCardsSurfaceProps<ZoneKey extends string = string>
+  extends PlayerCardsSurfaceConfig<ZoneKey> {
+  empty?: ReactNode;
+}
+
+export function definePlayerCardsSurface<
+  const Config extends PlayerCardsSurfaceConfig<string>,
+>(config: Config): Config {
+  return config;
+}
+
+export function row<const ZoneKey extends string>(
+  children: ReadonlyArray<PlayerCardsLayout<ZoneKey>>,
+): PlayerCardsGroup<ZoneKey> {
+  return { kind: "group", direction: "row", children };
+}
+
+export function column<const ZoneKey extends string>(
+  children: ReadonlyArray<PlayerCardsLayout<ZoneKey>>,
+): PlayerCardsGroup<ZoneKey> {
+  return { kind: "group", direction: "column", children };
+}
+
+export function pile<const ZoneKey extends string>(
+  zone: ZoneKey,
+  options: Omit<PlayerCardsPileNode<ZoneKey>, "kind" | "zone"> = {},
+): PlayerCardsPileNode<ZoneKey> {
+  return { kind: "pile", zone, ...options };
+}
+
+export function fan<const ZoneKey extends string>(
+  zone: ZoneKey,
+  options: Omit<PlayerCardsFanNode<ZoneKey>, "kind" | "zone"> = {},
+): PlayerCardsFanNode<ZoneKey> {
+  return { kind: "fan", zone, ...options };
+}
+
+export function custom<const ZoneKey extends string>(
+  zone: ZoneKey,
+  options: Omit<PlayerCardsCustomNode<ZoneKey>, "kind" | "zone">,
+): PlayerCardsCustomNode<ZoneKey> {
+  return { kind: "custom", zone, ...options };
+}
+
+export function PlayerCardsSurface<
+  I extends string = never,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+  ZoneKey extends string = string,
+>({
+  layout,
+  renderCardContent,
+  empty = null,
+}: PlayerCardsSurfaceProps<ZoneKey>) {
+  if (!layout) return <>{empty}</>;
+  return (
+    <PlayerCardsLayoutNode<I, ParamsByKey>
+      layout={layout}
+      surfaceRenderCardContent={renderCardContent}
+    />
+  );
+}
+
+function PlayerCardsLayoutNode<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape>,
+>({
+  layout,
+  surfaceRenderCardContent,
+}: {
+  layout: PlayerCardsLayout<string>;
+  surfaceRenderCardContent?: (
+    card: ViewCard,
+    ctx: CardZoneInteractionContext,
+  ) => ReactNode;
+}) {
+  const theme = useTheme();
+  if (layout.kind === "group") {
+    return (
+      <div
+        data-player-cards-group={layout.direction}
+        style={{
+          display: "flex",
+          flexDirection: layout.direction,
+          gap: theme.space[2],
+          alignItems: layout.direction === "row" ? "flex-end" : "stretch",
+          // Fill the parent so flex children (especially the fan with
+          // `flex: 1 1 ...`) can grow to use the available width.
+          // Without this, the row collapses to its children's intrinsic
+          // size and the fan never gets room to spread.
+          width: "100%",
+          minWidth: 0,
+        }}
+      >
+        {layout.children.map((child, index) => (
+          <PlayerCardsLayoutNode<I, ParamsByKey>
+            key={index}
+            layout={child as PlayerCardsLayout<string>}
+            surfaceRenderCardContent={surfaceRenderCardContent}
+          />
+        ))}
+      </div>
+    );
+  }
+  return (
+    <PlayerCardsZoneNode<I, ParamsByKey>
+      node={layout}
+      surfaceRenderCardContent={surfaceRenderCardContent}
+    />
+  );
+}
+
+function PlayerCardsZoneNode<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape>,
+>({
+  node,
+  surfaceRenderCardContent,
+}: {
+  node: PlayerCardZoneNode<string>;
+  surfaceRenderCardContent?: (
+    card: ViewCard,
+    ctx: CardZoneInteractionContext,
+  ) => ReactNode;
+}) {
+  const zone = usePlayerCardZone<I>(String(node.zone), node.label);
+  if (node.kind === "custom") return <>{node.renderZone(zone)}</>;
+  if (node.kind === "pile") {
+    return (
+      <PlayerCardsPile
+        node={node}
+        zone={zone}
+        surfaceRenderCardContent={surfaceRenderCardContent}
+      />
+    );
+  }
+  return (
+    <PlayerCardsFan<I, ParamsByKey>
+      node={node}
+      zone={zone}
+      surfaceRenderCardContent={surfaceRenderCardContent}
+    />
+  );
+}
+
+function usePlayerCardZone<I extends string>(
+  zoneId: string,
+  label?: string,
+): PlayerCardZoneModel<I> & ReturnType<typeof useCardZoneInteractions<I>> {
+  const interactions = useCardZoneInteractions<I>(zoneId, { surface: "hand" });
+  const zone = usePluginState((s) => s.gameplay.zones?.[zoneId]);
+  return useMemo(() => {
+    const cardIds = zone?.cardIds ?? [];
+    const visibleIds = new Set(interactions.cards.map((card) => card.id));
+    const contextsByCardId = new Map(
+      interactions.contexts.map((ctx) => [ctx.card.id, ctx] as const),
+    );
+    return {
+      ...interactions,
+      zoneId,
+      label: label ?? zoneId,
+      totalCount: cardIds.length,
+      visibleCards: interactions.cards,
+      hiddenCount: Math.max(0, cardIds.length - interactions.cards.length),
+      hiddenCardIds: cardIds.filter((cardId) => !visibleIds.has(cardId)),
+      contexts: interactions.contexts,
+      contextsByCardId,
+    };
+  }, [interactions, label, zone?.cardIds, zoneId]);
+}
+
+function PlayerCardsPile({
+  node,
+  zone,
+  surfaceRenderCardContent,
+}: {
+  node: PlayerCardsPileNode<string>;
+  zone: PlayerCardZoneModel;
+  surfaceRenderCardContent?: (
+    card: ViewCard,
+    ctx: CardZoneInteractionContext,
+  ) => ReactNode;
+}) {
+  const [open, setOpen] = useState(false);
+  const top = node.top ?? "first";
+  const previewCard =
+    node.topCard !== undefined
+      ? node.topCard
+      : top === "last"
+        ? (zone.visibleCards[zone.visibleCards.length - 1] ?? null)
+        : (zone.visibleCards[0] ?? null);
+  const totalCount = node.count ?? zone.totalCount;
+  const drawerEnabled = (node.details ?? "drawer") !== "none";
+  const cardContent = node.renderCardContent ?? surfaceRenderCardContent;
+
+  // Full escape hatch — author owns button + drawer + everything.
+  if (node.renderPile) return <>{node.renderPile(zone)}</>;
+
+  const previewNode = node.renderPreview ? (
+    node.renderPreview(zone)
+  ) : previewCard ? (
+    <Card
+      card={previewCard}
+      disabled
+      size="sm"
+      renderContent={
+        cardContent
+          ? (card) => {
+              const ctx = zone.contextsByCardId.get(card.id);
+              return cardContent(card, ctx ?? emptyZoneContext(card));
+            }
+          : undefined
+      }
+    />
+  ) : node.renderEmpty ? (
+    node.renderEmpty(zone)
+  ) : (
+    <div
+      aria-label="Hidden card"
+      style={{
+        width: 72,
+        height: 100,
+        borderRadius: 8,
+        border: "2px solid #111",
+        background:
+          "repeating-linear-gradient(135deg, #ddd, #ddd 6px, #bbb 6px, #bbb 12px)",
+      }}
+    />
+  );
+
+  return (
+    <>
+      <button
+        type="button"
+        data-player-cards-pile={zone.zoneId}
+        onClick={() => {
+          if (drawerEnabled) setOpen(true);
+        }}
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          gap: 6,
+          border: 0,
+          background: "transparent",
+          padding: 0,
+          cursor: drawerEnabled ? "pointer" : "default",
+        }}
+      >
+        <span style={{ fontSize: 12, fontWeight: 700 }}>{zone.label}</span>
+        <div style={{ position: "relative", minWidth: 72, minHeight: 100 }}>
+          {previewNode}
+          <span
+            data-player-cards-pile-count
+            style={{
+              position: "absolute",
+              right: -6,
+              bottom: -6,
+              borderRadius: 999,
+              padding: "2px 6px",
+              background: "#111",
+              color: "#fff",
+              fontSize: 12,
+            }}
+          >
+            {totalCount}
+          </span>
+        </div>
+      </button>
+      <Drawer open={open} onOpenChange={setOpen}>
+        <DrawerContent>
+          <DrawerHeader>
+            <DrawerTitle>{zone.label}</DrawerTitle>
+          </DrawerHeader>
+          {node.renderDrawerContent ? (
+            node.renderDrawerContent(zone)
+          ) : (
+            <div style={{ display: "flex", flexWrap: "wrap", gap: 8 }}>
+              {zone.visibleCards.map((card) => (
+                <Card
+                  key={card.id}
+                  card={card}
+                  disabled
+                  size="sm"
+                  renderContent={
+                    cardContent
+                      ? (c) => {
+                          const ctx = zone.contextsByCardId.get(c.id);
+                          return cardContent(c, ctx ?? emptyZoneContext(c));
+                        }
+                      : undefined
+                  }
+                />
+              ))}
+              {Array.from({ length: zone.hiddenCount }).map((_, index) => (
+                <div key={index}>Hidden card</div>
+              ))}
+            </div>
+          )}
+        </DrawerContent>
+      </Drawer>
+    </>
+  );
+}
+
+function emptyZoneContext(card: ViewCard): CardZoneInteractionContext {
+  return {
+    card,
+    interactions: [],
+    play: null,
+    disabled: true,
+    actionState: "unavailable",
+    selected: false,
+  };
+}
+
+function PlayerCardsFan<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape>,
+>({
+  node,
+  zone,
+  surfaceRenderCardContent,
+}: {
+  node: PlayerCardsFanNode<string>;
+  zone: PlayerCardZoneModel<I> & ReturnType<typeof useCardZoneInteractions<I>>;
+  surfaceRenderCardContent?: (
+    card: ViewCard,
+    ctx: CardZoneInteractionContext,
+  ) => ReactNode;
+}) {
+  const cardSize = node.cardSize ?? "md";
+  if (node.renderZone) return <>{node.renderZone(zone)}</>;
+  const renderCardContent = node.renderCardContent ?? surfaceRenderCardContent;
+  return (
+    // `min-width: 0` lets the flex item shrink below its intrinsic
+    // content width when the row's other children need space. `Hand`
+    // self-clamps card positions to the measured container width via
+    // `useHandLayout`, so cards no longer bleed into sibling piles
+    // without us needing to clip the wrapper (which would also
+    // suppress the hover-lift translateY above the dock chrome).
+    <div
+      data-player-cards-fan={zone.zoneId}
+      style={{ flex: "1 1 280px", minWidth: 0 }}
+    >
+      <Hand
+        cards={zone.visibleCards}
+        cardSize={cardSize}
+        layout={node.layout}
+        renderCard={(props) => {
+          const ctx = zone.contextsByCardId.get(props.card.id);
+          const disabled = ctx?.disabled ?? true;
+          return (
+            <div
+              key={props.card.id}
+              className="absolute bottom-0 transition-all duration-150 ease-out"
+              style={{
+                left: props.x,
+                zIndex: props.zIndex,
+                transform: `translateY(${props.y}px)`,
+              }}
+            >
+              <Card
+                card={props.card}
+                selected={props.isSelected}
+                disabled={disabled}
+                size={cardSize}
+                onCardClick={
+                  disabled
+                    ? undefined
+                    : (cardId) => {
+                        const clickedCtx = zone.contextsByCardId.get(cardId);
+                        if (clickedCtx?.play) void clickedCtx.play();
+                      }
+                }
+                renderContent={
+                  renderCardContent
+                    ? (card) => {
+                        const renderCtx = zone.contextsByCardId.get(card.id);
+                        if (!renderCtx) return null;
+                        return renderCardContent(card, renderCtx);
+                      }
+                    : undefined
+                }
+              />
+            </div>
+          );
+        }}
+      />
+      {zone.followUp ? (
+        <Fragment>
+          <CardZoneFollowUpForm<I, ParamsByKey>
+            key={zone.followUp.interactionKey}
+            descriptor={zone.followUp}
+            onDone={() => zone.setFollowUp(null)}
+          />
+        </Fragment>
+      ) : null}
+    </div>
+  );
+}

package/src/components/surfaces/internal/CardZoneFollowUpForm.tsx

@@ -0,0 +1,35 @@
+import { InteractionForm } from "../../InteractionForm.js";
+import { useInteractionHandle } from "../../../hooks/useInteractionHandle.js";
+import type { InteractionDescriptor } from "../../../types/plugin-state.js";
+import type {
+  InteractionDefaultedKeysOf,
+  InteractionParamsByKeyShape,
+  InteractionParamsOf,
+} from "../types.js";
+
+export function CardZoneFollowUpForm<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({
+  descriptor,
+  onDone,
+}: {
+  descriptor: InteractionDescriptor<I>;
+  onDone: () => void;
+}) {
+  const handle = useInteractionHandle<
+    InteractionParamsOf<ParamsByKey, I>,
+    InteractionDefaultedKeysOf<ParamsByKey, I>
+  >(descriptor);
+  return (
+    <InteractionForm
+      descriptor={descriptor}
+      handle={handle}
+      hiddenFields={[
+        "cardId" as keyof InteractionParamsOf<ParamsByKey, I> & string,
+      ]}
+      onCancel={onDone}
+      onSubmitSuccess={onDone}
+    />
+  );
+}