@dreamboard-games/ui-sdk 0.0.41

package/dist/components/surfaces/PanelSurface.d.ts

@@ -0,0 +1,111 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type InteractionHandle } from "../../hooks/useInteractionHandle.js";
+import type { InteractionDescriptor } from "../../types/plugin-state.js";
+import type { InteractionDefaultedKeysOf, InteractionParamsByKeyShape, InteractionParamsOf, SurfaceRenderMap } from "./types.js";
+/**
+ * Resolved salience tier for a panel interaction. Authors set
+ * `descriptor.salience` directly; when omitted we derive a sensible
+ * default from `descriptor.emphasis` so existing workspaces inherit
+ * the new ordering / disclosure behaviour without being touched.
+ *
+ * - `descriptor.salience === "hero"` → `hero`
+ * - `descriptor.salience === "tertiary"` → `tertiary`
+ * - `descriptor.emphasis === "primary"` → `hero`
+ * - `descriptor.emphasis === "destructive"` → `tertiary`
+ * - everything else → `secondary` (the default tier)
+ */
+export type PanelSalience = "hero" | "secondary" | "tertiary";
+export interface PanelSurfaceProps<I extends string = never, ParamsByKey extends Partial<InteractionParamsByKeyShape> = {}> {
+    /**
+     * Optional per-interaction overrides. Omit entirely to use the default
+     * renderer (`DefaultInteractionButton`) for every interaction; supply a
+     * partial map to replace the default UI for specific interaction ids.
+     */
+    render?: SurfaceRenderMap<I, ParamsByKey>;
+    /**
+     * Fallback renderer for interactions without a `render` entry. Defaults
+     * to the built-in `DefaultInteractionButton` which honours metadata
+     * (`icon`, `label`, `emphasis`, `unavailableReason`).
+     */
+    renderItem?: (descriptor: InteractionDescriptor<I>, handle: InteractionHandle<InteractionParamsOf<ParamsByKey, I>, InteractionDefaultedKeysOf<ParamsByKey, I>>) => ReactNode;
+    /** Shown when no panel interactions are available. */
+    empty?: ReactNode;
+    /**
+     * Optional grouping function. Defaults to `descriptor.group`; authors
+     * can override to cluster interactions differently. Returning
+     * `undefined` keeps the interaction in the ungrouped tail cluster.
+     */
+    groupBy?: (descriptor: InteractionDescriptor<I>) => string | undefined;
+    /**
+     * Override the default salience derivation. Receives the descriptor
+     * and returns the tier it should occupy. Use to demote something the
+     * authoring layer mis-tagged as `emphasis: "primary"` without
+     * changing the upstream contract.
+     */
+    salienceFor?: (descriptor: InteractionDescriptor<I>) => PanelSalience;
+    /**
+     * Maximum number of `secondary`-tier items to render directly in the
+     * panel. Excess secondaries spill into the {@link MoreActions}
+     * disclosure (alongside the always-disclosed `tertiary` tier).
+     * Defaults to `Infinity` — secondaries stay visible. Lower this on
+     * dense HUDs to fight Hick's Law.
+     *
+     * Hero items are never spilled, so a panel with three hero entries
+     * and `maxVisibleSecondary: 0` still renders three buttons inline
+     * plus the disclosure.
+     */
+    maxVisibleSecondary?: number;
+    /**
+     * Label for the disclosure toggle. Defaults to `"More"`. Pass a
+     * workspace-specific copy ("Advanced", "Manage", …) when the
+     * generic label feels wrong.
+     */
+    moreActionsLabel?: string;
+    /** Interaction keys intentionally rendered elsewhere, such as auto primary actions. */
+    excludeInteractionKeys?: readonly string[];
+    /**
+     * Render unavailable interactions as disabled items. Defaults to false so
+     * stale-step actions do not compete with legal actions.
+     */
+    showUnavailable?: boolean;
+    /**
+     * Layout overrides for the default container. Useful for tightly
+     * constrained mobile layouts. When the caller supplies their own
+     * `render` for every interaction they can ignore these entirely.
+     */
+    layout?: {
+        direction?: "row" | "column";
+        wrap?: boolean;
+        gap?: CSSProperties["gap"];
+        align?: CSSProperties["alignItems"];
+        justify?: CSSProperties["justifyContent"];
+    };
+}
+/**
+ * Default salience resolver — see {@link PanelSalience}. Exported so
+ * authors who want to slightly tweak the policy can compose with it
+ * (`salienceFor: (d) => d.id === "x" ? "hero" : defaultPanelSalience(d)`).
+ */
+export declare function defaultPanelSalience(_descriptor: InteractionDescriptor): PanelSalience;
+/**
+ * Default renderer for `surface: "panel"` interactions.
+ *
+ * Visual styling comes entirely from the active {@link useTheme}; mount
+ * `<ThemeProvider theme={...}/>` to swap the look. Per-interaction overrides
+ * via `render` are the escape hatch when a specific interaction needs bespoke
+ * UI.
+ *
+ * Salience policy
+ * ===============
+ * Each descriptor is assigned a {@link PanelSalience} via
+ * {@link defaultPanelSalience} (override with the `salienceFor` prop).
+ * The panel sorts groups so `hero` items render first, then
+ * `secondary`, then `tertiary` — and the `tertiary` cluster (plus any
+ * spill from `maxVisibleSecondary`) lives behind a {@link MoreActions}
+ * disclosure so a crowded panel doesn't drown the player in choices
+ * (Hick's Law). Groups stay contiguous: a group inherits the highest
+ * salience among its members so a hero+secondary cluster doesn't get
+ * split across the disclosure boundary.
+ */
+export declare function PanelSurface<I extends string = never, ParamsByKey extends Partial<InteractionParamsByKeyShape> = {}>({ render, renderItem, empty, groupBy, salienceFor, maxVisibleSecondary, moreActionsLabel, excludeInteractionKeys, showUnavailable, layout, }: PanelSurfaceProps<I, ParamsByKey>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=PanelSurface.d.ts.map

package/dist/components/surfaces/PanelSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PanelSurface.d.ts","sourceRoot":"","sources":["../../../src/components/surfaces/PanelSurface.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEtD,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AAGzE,OAAO,KAAK,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,CAAC;AAE9D,MAAM,WAAW,iBAAiB,CAChC,CAAC,SAAS,MAAM,GAAG,KAAK,EACxB,WAAW,SAAS,OAAO,CAAC,2BAA2B,CAAC,GAAG,EAAE;IAE7D;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAC1C;;;;OAIG;IACH,UAAU,CAAC,EAAE,CACX,UAAU,EAAE,qBAAqB,CAAC,CAAC,CAAC,EACpC,MAAM,EAAE,iBAAiB,CACvB,mBAAmB,CAAC,WAAW,EAAE,CAAC,CAAC,EACnC,0BAA0B,CAAC,WAAW,EAAE,CAAC,CAAC,CAC3C,KACE,SAAS,CAAC;IACf,sDAAsD;IACtD,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC;IACvE;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,aAAa,CAAC;IACtE;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,MAAM,CAAC,EAAE;QACP,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;QAC7B,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,GAAG,CAAC,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC;QAC3B,KAAK,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;QACpC,OAAO,CAAC,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;KAC3C,CAAC;CACH;AAQD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,qBAAqB,GACjC,aAAa,CAEf;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS,MAAM,GAAG,KAAK,EACxB,WAAW,SAAS,OAAO,CAAC,2BAA2B,CAAC,GAAG,EAAE,EAC7D,EACA,MAAM,EACN,UAAU,EACV,KAAY,EACZ,OAAyB,EACzB,WAAW,EACX,mBAA8C,EAC9C,gBAAgB,EAChB,sBAAsB,EACtB,eAAuB,EACvB,MAAM,GACP,EAAE,iBAAiB,CAAC,CAAC,EAAE,WAAW,CAAC,2CAkGnC"}

package/dist/components/surfaces/PanelSurface.js

@@ -0,0 +1,180 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSeatInbox } from "../../hooks/useSeatInbox.js";
+import { useInteractionHandle, } from "../../hooks/useInteractionHandle.js";
+import { useTheme } from "../../theme/ThemeProvider.js";
+import { DefaultInteractionButton } from "./internal/DefaultInteractionButton.js";
+import { MoreActions } from "../MoreActions.js";
+const SALIENCE_RANK = {
+    hero: 0,
+    secondary: 1,
+    tertiary: 2,
+};
+/**
+ * Default salience resolver — see {@link PanelSalience}. Exported so
+ * authors who want to slightly tweak the policy can compose with it
+ * (`salienceFor: (d) => d.id === "x" ? "hero" : defaultPanelSalience(d)`).
+ */
+export function defaultPanelSalience(_descriptor) {
+    return "secondary";
+}
+// `align: "flex-start"` is deliberate. Panel items are heterogeneous —
+// a `DefaultInteractionButton` sits next to authored cards that can
+// expand into multi-row draft forms (e.g. an offer-trade card). With
+// `stretch` the short buttons get dragged to the tallest sibling's
+// height and render as floor-to-ceiling bars next to the expanded form.
+// Authors who *do* want uniform heights can opt in via `layout.align`.
+const defaultLayout = {
+    direction: "row",
+    wrap: true,
+    gap: "8px",
+    align: "flex-start",
+    justify: "flex-start",
+};
+/**
+ * Default renderer for `surface: "panel"` interactions.
+ *
+ * Visual styling comes entirely from the active {@link useTheme}; mount
+ * `<ThemeProvider theme={...}/>` to swap the look. Per-interaction overrides
+ * via `render` are the escape hatch when a specific interaction needs bespoke
+ * UI.
+ *
+ * Salience policy
+ * ===============
+ * Each descriptor is assigned a {@link PanelSalience} via
+ * {@link defaultPanelSalience} (override with the `salienceFor` prop).
+ * The panel sorts groups so `hero` items render first, then
+ * `secondary`, then `tertiary` — and the `tertiary` cluster (plus any
+ * spill from `maxVisibleSecondary`) lives behind a {@link MoreActions}
+ * disclosure so a crowded panel doesn't drown the player in choices
+ * (Hick's Law). Groups stay contiguous: a group inherits the highest
+ * salience among its members so a hero+secondary cluster doesn't get
+ * split across the disclosure boundary.
+ */
+export function PanelSurface({ render, renderItem, empty = null, groupBy = () => undefined, salienceFor, maxVisibleSecondary = Number.POSITIVE_INFINITY, moreActionsLabel, excludeInteractionKeys, showUnavailable = false, layout, }) {
+    const inbox = useSeatInbox();
+    const excluded = new Set(excludeInteractionKeys ?? []);
+    const items = (inbox.bySurface.panel ?? []).filter((descriptor) => !excluded.has(descriptor.interactionKey) &&
+        (showUnavailable || descriptor.available));
+    if (items.length === 0)
+        return _jsx(_Fragment, { children: empty });
+    const resolvedLayout = { ...defaultLayout, ...(layout ?? {}) };
+    const resolveSalience = salienceFor ?? defaultPanelSalience;
+    // Compute groups first (preserves authored cohesion), then assign
+    // each group a tier from its highest-salience member, then sort by
+    // tier while keeping members in their original order.
+    const grouped = groupInteractions(items, groupBy, resolveSalience);
+    const sorted = [...grouped].sort((a, b) => {
+        const tierDiff = SALIENCE_RANK[a.tier] - SALIENCE_RANK[b.tier];
+        if (tierDiff !== 0)
+            return tierDiff;
+        // Same tier — preserve authored order via the cached index.
+        return a.firstIndex - b.firstIndex;
+    });
+    // Decide which groups stay in the main row vs. spill into the
+    // disclosure. Hero groups always stay; tertiary groups always
+    // spill; secondary groups spill once we've already shown
+    // `maxVisibleSecondary` of them. A group counts as 1 toward the
+    // budget regardless of how many descriptors it contains — losing
+    // half a "build" cluster would be more confusing than rendering
+    // the whole sub-row.
+    const visible = [];
+    const disclosed = [];
+    let secondariesShown = 0;
+    for (const group of sorted) {
+        if (group.tier === "hero") {
+            visible.push(group);
+            continue;
+        }
+        if (group.tier === "tertiary") {
+            disclosed.push(group);
+            continue;
+        }
+        if (secondariesShown < maxVisibleSecondary) {
+            visible.push(group);
+            secondariesShown += 1;
+        }
+        else {
+            disclosed.push(group);
+        }
+    }
+    // Count the underlying descriptors so the disclosure badge reads
+    // "More (3)" not "More (1 group)".
+    const disclosedCount = disclosed.reduce((sum, group) => sum + group.interactions.length, 0);
+    return (_jsxs("div", { role: "toolbar", "aria-label": "Panel actions", "data-shell-slot": "panel-actions", style: {
+            display: "flex",
+            flexDirection: resolvedLayout.direction,
+            flexWrap: resolvedLayout.wrap ? "wrap" : "nowrap",
+            gap: resolvedLayout.gap,
+            alignItems: resolvedLayout.align,
+            justifyContent: resolvedLayout.justify,
+        }, children: [visible.map((group) => (_jsx(PanelGroup, { group: group, render: render, renderItem: renderItem }, group.id))), disclosed.length > 0 ? (_jsx(MoreActions, { label: moreActionsLabel, count: disclosedCount, children: disclosed.map((group) => (_jsx(PanelGroup, { group: group, render: render, renderItem: renderItem }, group.id))) })) : null] }));
+}
+function groupInteractions(items, groupBy, resolveSalience) {
+    const ordered = [];
+    const byGroup = new Map();
+    items.forEach((descriptor, index) => {
+        const tier = resolveSalience(descriptor);
+        const key = groupBy(descriptor);
+        if (key === undefined) {
+            ordered.push({
+                id: `solo:${descriptor.interactionId}`,
+                grouped: false,
+                interactions: [descriptor],
+                tier,
+                firstIndex: index,
+            });
+            return;
+        }
+        const bucket = byGroup.get(key);
+        if (bucket) {
+            bucket.interactions.push(descriptor);
+            if (SALIENCE_RANK[tier] < SALIENCE_RANK[bucket.tier]) {
+                bucket.tier = tier;
+            }
+            return;
+        }
+        const fresh = {
+            id: `group:${key}`,
+            grouped: true,
+            interactions: [descriptor],
+            tier,
+            firstIndex: index,
+        };
+        byGroup.set(key, fresh);
+        ordered.push(fresh);
+    });
+    return ordered.map((bucket) => ({
+        id: bucket.id,
+        interactions: bucket.interactions,
+        grouped: bucket.grouped,
+        tier: bucket.tier,
+        firstIndex: bucket.firstIndex,
+    }));
+}
+function PanelGroup({ group, render, renderItem, }) {
+    const theme = useTheme();
+    if (!group.grouped || group.interactions.length === 1) {
+        return (_jsx(_Fragment, { children: group.interactions.map((descriptor) => (_jsx(PanelItem, { descriptor: descriptor, render: render, renderItem: renderItem, tier: group.tier }, descriptor.interactionKey))) }));
+    }
+    return (_jsx("div", { "data-panel-group": group.id, "data-panel-tier": group.tier, style: {
+            display: "inline-flex",
+            gap: theme.space[1],
+            padding: theme.space[1],
+            borderRadius: theme.radius.lg,
+            background: theme.semantic.surface.inset,
+        }, children: group.interactions.map((descriptor) => (_jsx(PanelItem, { descriptor: descriptor, render: render, renderItem: renderItem, compact: true, tier: group.tier }, descriptor.interactionKey))) }));
+}
+function PanelItem({ descriptor, render, renderItem, compact, tier, }) {
+    const handle = useInteractionHandle(descriptor);
+    const override = render?.[descriptor.interactionKey];
+    if (override)
+        return _jsx(_Fragment, { children: override(descriptor, handle) });
+    if (renderItem)
+        return _jsx(_Fragment, { children: renderItem(descriptor, handle) });
+    // Salience-driven sizing: hero buttons use the `lg` size so they
+    // outweigh the `secondary` tier next to them. Tertiary items render
+    // inside the disclosure where the smaller `sm` size keeps the
+    // disclosed cluster from feeling like a second main panel.
+    const size = compact || tier === "tertiary" ? "sm" : tier === "hero" ? "lg" : "md";
+    return (_jsx(DefaultInteractionButton, { descriptor: descriptor, handle: handle, compact: compact, size: size, "data-panel-tier": tier }));
+}

package/dist/components/surfaces/PlayerCardsSurface.d.ts

@@ -0,0 +1,104 @@
+import { type ReactNode } from "react";
+import type { ViewCard } from "@dreamboard/sdk-types";
+import type { CardSize, HandLayout } from "../../hooks/useHandLayout.js";
+import { type CardZoneInteractionContext } from "./internal/useCardZoneInteractions.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 declare function definePlayerCardsSurface<const Config extends PlayerCardsSurfaceConfig<string>>(config: Config): Config;
+export declare function row<const ZoneKey extends string>(children: ReadonlyArray<PlayerCardsLayout<ZoneKey>>): PlayerCardsGroup<ZoneKey>;
+export declare function column<const ZoneKey extends string>(children: ReadonlyArray<PlayerCardsLayout<ZoneKey>>): PlayerCardsGroup<ZoneKey>;
+export declare function pile<const ZoneKey extends string>(zone: ZoneKey, options?: Omit<PlayerCardsPileNode<ZoneKey>, "kind" | "zone">): PlayerCardsPileNode<ZoneKey>;
+export declare function fan<const ZoneKey extends string>(zone: ZoneKey, options?: Omit<PlayerCardsFanNode<ZoneKey>, "kind" | "zone">): PlayerCardsFanNode<ZoneKey>;
+export declare function custom<const ZoneKey extends string>(zone: ZoneKey, options: Omit<PlayerCardsCustomNode<ZoneKey>, "kind" | "zone">): PlayerCardsCustomNode<ZoneKey>;
+export declare function PlayerCardsSurface<I extends string = never, ParamsByKey extends Partial<InteractionParamsByKeyShape> = {}, ZoneKey extends string = string>({ layout, renderCardContent, empty, }: PlayerCardsSurfaceProps<ZoneKey>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=PlayerCardsSurface.d.ts.map

package/dist/components/surfaces/PlayerCardsSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PlayerCardsSurface.d.ts","sourceRoot":"","sources":["../../../src/components/surfaces/PlayerCardsSurface.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACpE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAKzE,OAAO,EAEL,KAAK,0BAA0B,EAChC,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AAE9D,MAAM,MAAM,iBAAiB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IACzD,kBAAkB,CAAC,OAAO,CAAC,GAC3B,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAE9B,MAAM,WAAW,gBAAgB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IAC/D,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,KAAK,GAAG,QAAQ,CAAC;IAC5B,QAAQ,EAAE,aAAa,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IAC5D,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,SAAS,QAAQ,EAAE,CAAC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,EAAE,aAAa,CAAC,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC,CAAC,CAAC,CAAC;CACtE;AAED,MAAM,MAAM,kBAAkB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAC1D,mBAAmB,CAAC,OAAO,CAAC,GAC5B,kBAAkB,CAAC,OAAO,CAAC,GAC3B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAEnC,MAAM,WAAW,mBAAmB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,OAAO,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,SAAS,CAAC;IACzD,uDAAuD;IACvD,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,SAAS,CAAC;IACvD;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,CAClB,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,0BAA0B,KAC5B,SAAS,CAAC;IACf,yCAAyC;IACzC,mBAAmB,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,SAAS,CAAC;IAC/D;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,SAAS,CAAC;CACvD;AAED,MAAM,WAAW,kBAAkB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IACjE,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,CAClB,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,0BAA0B,KAC5B,SAAS,CAAC;IACf,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,SAAS,CAAC;IACtD,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IACpE,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,SAAS,CAAC;CACtD;AAED,MAAM,WAAW,wBAAwB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM;IACvE,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,CAClB,IAAI,EAAE,QAAQ,EACd,GAAG,EAAE,0BAA0B,KAC5B,SAAS,CAAC;CAChB;AAED,MAAM,WAAW,uBAAuB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CACtE,SAAQ,wBAAwB,CAAC,OAAO,CAAC;IACzC,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,wBAAgB,wBAAwB,CACtC,KAAK,CAAC,MAAM,SAAS,wBAAwB,CAAC,MAAM,CAAC,EACrD,MAAM,EAAE,MAAM,GAAG,MAAM,CAExB;AAED,wBAAgB,GAAG,CAAC,KAAK,CAAC,OAAO,SAAS,MAAM,EAC9C,QAAQ,EAAE,aAAa,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,GAClD,gBAAgB,CAAC,OAAO,CAAC,CAE3B;AAED,wBAAgB,MAAM,CAAC,KAAK,CAAC,OAAO,SAAS,MAAM,EACjD,QAAQ,EAAE,aAAa,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,GAClD,gBAAgB,CAAC,OAAO,CAAC,CAE3B;AAED,wBAAgB,IAAI,CAAC,KAAK,CAAC,OAAO,SAAS,MAAM,EAC/C,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAM,GAChE,mBAAmB,CAAC,OAAO,CAAC,CAE9B;AAED,wBAAgB,GAAG,CAAC,KAAK,CAAC,OAAO,SAAS,MAAM,EAC9C,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAM,GAC/D,kBAAkB,CAAC,OAAO,CAAC,CAE7B;AAED,wBAAgB,MAAM,CAAC,KAAK,CAAC,OAAO,SAAS,MAAM,EACjD,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,GAC7D,qBAAqB,CAAC,OAAO,CAAC,CAEhC;AAED,wBAAgB,kBAAkB,CAChC,CAAC,SAAS,MAAM,GAAG,KAAK,EACxB,WAAW,SAAS,OAAO,CAAC,2BAA2B,CAAC,GAAG,EAAE,EAC7D,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,EACA,MAAM,EACN,iBAAiB,EACjB,KAAY,GACb,EAAE,uBAAuB,CAAC,OAAO,CAAC,2CAQlC"}

package/dist/components/surfaces/PlayerCardsSurface.js

@@ -0,0 +1,178 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment, useMemo, useState } from "react";
+import { usePluginState } from "../../context/PluginStateContext.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, } from "./internal/useCardZoneInteractions.js";
+import { CardZoneFollowUpForm } from "./internal/CardZoneFollowUpForm.js";
+export function definePlayerCardsSurface(config) {
+    return config;
+}
+export function row(children) {
+    return { kind: "group", direction: "row", children };
+}
+export function column(children) {
+    return { kind: "group", direction: "column", children };
+}
+export function pile(zone, options = {}) {
+    return { kind: "pile", zone, ...options };
+}
+export function fan(zone, options = {}) {
+    return { kind: "fan", zone, ...options };
+}
+export function custom(zone, options) {
+    return { kind: "custom", zone, ...options };
+}
+export function PlayerCardsSurface({ layout, renderCardContent, empty = null, }) {
+    if (!layout)
+        return _jsx(_Fragment, { children: empty });
+    return (_jsx(PlayerCardsLayoutNode, { layout: layout, surfaceRenderCardContent: renderCardContent }));
+}
+function PlayerCardsLayoutNode({ layout, surfaceRenderCardContent, }) {
+    const theme = useTheme();
+    if (layout.kind === "group") {
+        return (_jsx("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,
+            }, children: layout.children.map((child, index) => (_jsx(PlayerCardsLayoutNode, { layout: child, surfaceRenderCardContent: surfaceRenderCardContent }, index))) }));
+    }
+    return (_jsx(PlayerCardsZoneNode, { node: layout, surfaceRenderCardContent: surfaceRenderCardContent }));
+}
+function PlayerCardsZoneNode({ node, surfaceRenderCardContent, }) {
+    const zone = usePlayerCardZone(String(node.zone), node.label);
+    if (node.kind === "custom")
+        return _jsx(_Fragment, { children: node.renderZone(zone) });
+    if (node.kind === "pile") {
+        return (_jsx(PlayerCardsPile, { node: node, zone: zone, surfaceRenderCardContent: surfaceRenderCardContent }));
+    }
+    return (_jsx(PlayerCardsFan, { node: node, zone: zone, surfaceRenderCardContent: surfaceRenderCardContent }));
+}
+function usePlayerCardZone(zoneId, label) {
+    const interactions = useCardZoneInteractions(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]));
+        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, }) {
+    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 _jsx(_Fragment, { children: node.renderPile(zone) });
+    const previewNode = node.renderPreview ? (node.renderPreview(zone)) : previewCard ? (_jsx(Card, { card: previewCard, disabled: true, size: "sm", renderContent: cardContent
+            ? (card) => {
+                const ctx = zone.contextsByCardId.get(card.id);
+                return cardContent(card, ctx ?? emptyZoneContext(card));
+            }
+            : undefined })) : node.renderEmpty ? (node.renderEmpty(zone)) : (_jsx("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 (_jsxs(_Fragment, { children: [_jsxs("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",
+                }, children: [_jsx("span", { style: { fontSize: 12, fontWeight: 700 }, children: zone.label }), _jsxs("div", { style: { position: "relative", minWidth: 72, minHeight: 100 }, children: [previewNode, _jsx("span", { "data-player-cards-pile-count": true, style: {
+                                    position: "absolute",
+                                    right: -6,
+                                    bottom: -6,
+                                    borderRadius: 999,
+                                    padding: "2px 6px",
+                                    background: "#111",
+                                    color: "#fff",
+                                    fontSize: 12,
+                                }, children: totalCount })] })] }), _jsx(Drawer, { open: open, onOpenChange: setOpen, children: _jsxs(DrawerContent, { children: [_jsx(DrawerHeader, { children: _jsx(DrawerTitle, { children: zone.label }) }), node.renderDrawerContent ? (node.renderDrawerContent(zone)) : (_jsxs("div", { style: { display: "flex", flexWrap: "wrap", gap: 8 }, children: [zone.visibleCards.map((card) => (_jsx(Card, { card: card, disabled: true, size: "sm", renderContent: cardContent
+                                        ? (c) => {
+                                            const ctx = zone.contextsByCardId.get(c.id);
+                                            return cardContent(c, ctx ?? emptyZoneContext(c));
+                                        }
+                                        : undefined }, card.id))), Array.from({ length: zone.hiddenCount }).map((_, index) => (_jsx("div", { children: "Hidden card" }, index)))] }))] }) })] }));
+}
+function emptyZoneContext(card) {
+    return {
+        card,
+        interactions: [],
+        play: null,
+        disabled: true,
+        actionState: "unavailable",
+        selected: false,
+    };
+}
+function PlayerCardsFan({ node, zone, surfaceRenderCardContent, }) {
+    const cardSize = node.cardSize ?? "md";
+    if (node.renderZone)
+        return _jsx(_Fragment, { children: 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).
+    _jsxs("div", { "data-player-cards-fan": zone.zoneId, style: { flex: "1 1 280px", minWidth: 0 }, children: [_jsx(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 (_jsx("div", { className: "absolute bottom-0 transition-all duration-150 ease-out", style: {
+                            left: props.x,
+                            zIndex: props.zIndex,
+                            transform: `translateY(${props.y}px)`,
+                        }, children: _jsx(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 }) }, props.card.id));
+                } }), zone.followUp ? (_jsx(Fragment, { children: _jsx(CardZoneFollowUpForm, { descriptor: zone.followUp, onDone: () => zone.setFollowUp(null) }, zone.followUp.interactionKey) })) : null] }));
+}

package/dist/components/surfaces/internal/CardZoneFollowUpForm.d.ts

@@ -0,0 +1,7 @@
+import type { InteractionDescriptor } from "../../../types/plugin-state.js";
+import type { InteractionParamsByKeyShape } from "../types.js";
+export declare function CardZoneFollowUpForm<I extends string, ParamsByKey extends Partial<InteractionParamsByKeyShape> = {}>({ descriptor, onDone, }: {
+    descriptor: InteractionDescriptor<I>;
+    onDone: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=CardZoneFollowUpForm.d.ts.map

package/dist/components/surfaces/internal/CardZoneFollowUpForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CardZoneFollowUpForm.d.ts","sourceRoot":"","sources":["../../../../src/components/surfaces/internal/CardZoneFollowUpForm.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,KAAK,EAEV,2BAA2B,EAE5B,MAAM,aAAa,CAAC;AAErB,wBAAgB,oBAAoB,CAClC,CAAC,SAAS,MAAM,EAChB,WAAW,SAAS,OAAO,CAAC,2BAA2B,CAAC,GAAG,EAAE,EAC7D,EACA,UAAU,EACV,MAAM,GACP,EAAE;IACD,UAAU,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB,2CAgBA"}

package/dist/components/surfaces/internal/CardZoneFollowUpForm.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { InteractionForm } from "../../InteractionForm.js";
+import { useInteractionHandle } from "../../../hooks/useInteractionHandle.js";
+export function CardZoneFollowUpForm({ descriptor, onDone, }) {
+    const handle = useInteractionHandle(descriptor);
+    return (_jsx(InteractionForm, { descriptor: descriptor, handle: handle, hiddenFields: [
+            "cardId",
+        ], onCancel: onDone, onSubmitSuccess: onDone }));
+}