@jgengine/react 0.9.0 → 0.11.0

package/README.md

@@ -1,3 +1,3 @@
 # @jgengine/react
 
-React UI layer for [JGengine](https://github.com/Noisemaker111/jgengine): `GameProvider`, hooks, and headless primitives over `@jgengine/core`. AGPL-3.0-only.
+React UI layer for [JGengine](https://github.com/Noisemaker111/jgengine): `GameProvider`, hooks, and headless primitives over `@jgengine/core`. Apache-2.0.

package/dist/actionHud.d.ts

@@ -0,0 +1,174 @@
+import { type CSSProperties, type ReactNode } from "react";
+import type { AbilitySlotSnapshot } from "@jgengine/core/combat/abilityKit";
+import { type ActionDef, type ResolvedAction } from "@jgengine/core/ui/actionModel";
+import { type PopoverSide, type TooltipContent } from "@jgengine/core/ui/tooltipModel";
+/**
+ * Composable React renderers over the headless action view model (`@jgengine/core/ui/actionModel`) —
+ * the data/renderer/chrome split for an RTS command card, an ability action bar, a build menu, or a
+ * radial. `useActionBar` is the DATA/HOOK layer (resolution + focus/hover/keyboard/hotkey), `ActionBarChrome`
+ * is the composable RENDERER (swap `renderItem` for custom chrome, or ignore it and consume the model
+ * directly for a radial), and `ActionBar` is the batteries-included default. A game swaps renderer or
+ * chrome without forking the logic. Layout, dimensions, hotkeys, and catalog-id mapping stay caller-owned.
+ */
+/**
+ * Adapt a combat {@link AbilitySlotSnapshot} into an {@link ActionDef} — the glue that binds an
+ * `AbilityKit` (via `useAbilitySlots`) to the action renderers without the game re-deriving cooldown
+ * and cost shapes. `extra` supplies the caller-owned bits the snapshot cannot know (label, icon,
+ * hotkey, description, resource name). Pure, so it is unit-testable.
+ *
+ * @capability action-from-ability-slot adapt a combat ability-kit snapshot into an action-bar action def
+ */
+export declare function actionFromAbilitySlot(slot: AbilitySlotSnapshot, extra?: Partial<ActionDef> & {
+    resourceId?: string;
+}): ActionDef;
+/** The intent a key press resolves to over an action bar: move focus, activate, or ignore. */
+export interface ActionBarKeyResult {
+    handled: boolean;
+    focusId?: string;
+    activateId?: string;
+}
+/**
+ * Pure keyboard/controller resolver for an action bar: arrows/Home/End move grid focus, Enter/Space
+ * activate the focused action, and any other single key routes through {@link actionByHotkey}. Returns
+ * the resulting intent without touching the DOM, so it unit-tests headless and `useActionBar` is a
+ * thin shell over it.
+ */
+export declare function actionBarKeyAction(actions: readonly ResolvedAction[], focusedId: string | null, columns: number, key: string, options?: {
+    wrap?: boolean;
+}): ActionBarKeyResult;
+/** A minimal keyboard-event shape — a real `KeyboardEvent`/React synthetic satisfies it. */
+export interface ActionKeyEvent {
+    key: string;
+    preventDefault(): void;
+}
+/** Options for {@link useActionBar}. */
+export interface UseActionBarOptions {
+    /** Grid width for keyboard focus math and the default grid renderer (default: number of actions). */
+    columns?: number;
+    /** Wrap focus at the grid edges (default false). */
+    wrap?: boolean;
+    /** Fired when an action is activated by click, Enter/Space, or its hotkey. */
+    onActivate?: (id: string) => void;
+    /** Set false to ignore single-key hotkeys (default true). */
+    hotkeys?: boolean;
+}
+/** The live action-bar model returned by {@link useActionBar}. */
+export interface ActionBarModel {
+    actions: readonly ResolvedAction[];
+    columns: number;
+    focusedId: string | null;
+    hoveredId: string | null;
+    setFocus: (id: string | null) => void;
+    setHover: (id: string | null) => void;
+    activate: (id: string) => void;
+    onKeyDown: (event: ActionKeyEvent) => void;
+}
+/**
+ * The DATA/HOOK layer: resolve `defs` into a live view model with focus, hover, keyboard grid
+ * navigation, and hotkey activation. Rendering-agnostic — feed the returned model to
+ * {@link ActionBarChrome}, or read it directly to lay out a radial or a bespoke card.
+ *
+ * @capability action-bar-model headless action-collection model with focus, hover, keyboard, and hotkey routing
+ */
+export declare function useActionBar(defs: readonly ActionDef[], options?: UseActionBarOptions): ActionBarModel;
+/** Render context passed to a custom {@link ActionBarChrome} item renderer. */
+export interface ActionItemContext {
+    focused: boolean;
+    hovered: boolean;
+    model: ActionBarModel;
+}
+/**
+ * The default per-item chrome — a cooldown-aware action button with hotkey cap, cost line, radial
+ * cooldown wipe, and full rest/hover/focus/pressed/active/disabled states. Accessible: it is a real
+ * `<button>` with `aria-disabled`, `aria-pressed` for toggles, `aria-keyshortcuts`, and a native
+ * `title` describing why it is blocked. Swap it via `ActionBarChrome`'s `renderItem`, or drop it into
+ * a radial layout yourself.
+ *
+ * @capability action-button cooldown/cost/hotkey action button with complete interaction states
+ */
+export declare function ActionButton({ action, focused, hovered, size, showHotkey, tabIndex, buttonRef, onActivate, onFocus, onHover, renderIcon, className, style, }: {
+    action: ResolvedAction;
+    focused?: boolean;
+    hovered?: boolean;
+    size?: number;
+    showHotkey?: boolean;
+    tabIndex?: number;
+    buttonRef?: (node: HTMLButtonElement | null) => void;
+    onActivate?: (id: string) => void;
+    onFocus?: (id: string) => void;
+    onHover?: (id: string | null) => void;
+    renderIcon?: (action: ResolvedAction) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * The composable RENDERER: lay the model's actions out as a `grid` or `list` toolbar with roving
+ * tabindex, arrow-key navigation, and a moved DOM focus. `renderItem` swaps per-item chrome; omit it
+ * for {@link ActionButton}. A radial or bespoke UI can skip this entirely and read the model. Purely
+ * a wiring/behavior layer — no panel skin — so a game art-directs freely.
+ *
+ * @capability action-bar-chrome accessible grid/list toolbar renderer over an action-bar model with swappable item chrome
+ */
+export declare function ActionBarChrome({ model, layout, itemSize, gap, ariaLabel, renderItem, className, style, }: {
+    model: ActionBarModel;
+    layout?: "grid" | "list";
+    itemSize?: number;
+    gap?: number;
+    ariaLabel?: string;
+    renderItem?: (action: ResolvedAction, ctx: ActionItemContext) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * The batteries-included default: a skinned glass panel wrapping {@link useActionBar} +
+ * {@link ActionBarChrome}. Pass `defs`, choose `grid`/`list`, and hand it `onActivate`. The renderer
+ * and item chrome are still swappable via `renderItem`; a game that wants a different frame composes
+ * the hook and chrome directly.
+ *
+ * @capability action-bar drop-in cooldown/cost/hotkey action bar over the headless action model
+ */
+export declare function ActionBar({ defs, columns, layout, wrap, hotkeys, itemSize, ariaLabel, onActivate, renderItem, className, style, }: {
+    defs: readonly ActionDef[];
+    columns?: number;
+    layout?: "grid" | "list";
+    wrap?: boolean;
+    hotkeys?: boolean;
+    itemSize?: number;
+    ariaLabel?: string;
+    onActivate?: (id: string) => void;
+    renderItem?: (action: ResolvedAction, ctx: ActionItemContext) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/**
+ * An accessible popover shell positioned by the pure {@link placePopover} math — flips and clamps
+ * against the viewport, renders nothing while closed, and defaults to `role="tooltip"`. Reuse it for
+ * an action's hover/focus description or any anchored panel.
+ *
+ * @capability popover viewport-flipping, viewport-clamped anchored popover/tooltip shell
+ */
+export declare function Popover({ open, anchorRef, side, gap, role, id, children, className, style, }: {
+    open: boolean;
+    anchorRef: {
+        current: HTMLElement | null;
+    };
+    side?: PopoverSide;
+    gap?: number;
+    role?: string;
+    id?: string;
+    children: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element | null;
+/**
+ * Render {@link TooltipContent} (from `actionTooltip`) as a styled block: title, subtitle, body,
+ * hotkey, cost lines, cooldown, and a warning footer of blocking notes. Drop it inside a
+ * {@link Popover} for an action's hover/focus description.
+ *
+ * @capability action-tooltip structured action tooltip body (title, cost, cooldown, blocking notes)
+ */
+export declare function ActionTooltip({ content, className, style, }: {
+    content: TooltipContent;
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;

package/dist/actionHud.js

@@ -0,0 +1,292 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef, useState, } from "react";
+import { actionByHotkey, actionCooldownFromFraction, actionCost, moveGridFocus, resolveActionCollection, } from "@jgengine/core/ui/actionModel";
+import { actionTooltip, placePopover } from "@jgengine/core/ui/tooltipModel";
+import { Keycap } from "./keyHint.js";
+/**
+ * Composable React renderers over the headless action view model (`@jgengine/core/ui/actionModel`) —
+ * the data/renderer/chrome split for an RTS command card, an ability action bar, a build menu, or a
+ * radial. `useActionBar` is the DATA/HOOK layer (resolution + focus/hover/keyboard/hotkey), `ActionBarChrome`
+ * is the composable RENDERER (swap `renderItem` for custom chrome, or ignore it and consume the model
+ * directly for a radial), and `ActionBar` is the batteries-included default. A game swaps renderer or
+ * chrome without forking the logic. Layout, dimensions, hotkeys, and catalog-id mapping stay caller-owned.
+ */
+/**
+ * Adapt a combat {@link AbilitySlotSnapshot} into an {@link ActionDef} — the glue that binds an
+ * `AbilityKit` (via `useAbilitySlots`) to the action renderers without the game re-deriving cooldown
+ * and cost shapes. `extra` supplies the caller-owned bits the snapshot cannot know (label, icon,
+ * hotkey, description, resource name). Pure, so it is unit-testable.
+ *
+ * @capability action-from-ability-slot adapt a combat ability-kit snapshot into an action-bar action def
+ */
+export function actionFromAbilitySlot(slot, extra) {
+    const def = { id: slot.id };
+    if (slot.cooldownRemainingMs > 0) {
+        def.cooldown = actionCooldownFromFraction(slot.cooldownRemainingMs, slot.cooldownFraction);
+    }
+    if (slot.resourceCost > 0) {
+        const available = slot.state === "no-resource" ? 0 : slot.resourceCost;
+        def.costs = [actionCost(extra?.resourceId ?? "resource", slot.resourceCost, available)];
+    }
+    if (extra?.label !== undefined)
+        def.label = extra.label;
+    if (extra?.description !== undefined)
+        def.description = extra.description;
+    if (extra?.icon !== undefined)
+        def.icon = extra.icon;
+    if (extra?.hotkey !== undefined)
+        def.hotkey = extra.hotkey;
+    if (extra?.group !== undefined)
+        def.group = extra.group;
+    if (extra?.active !== undefined)
+        def.active = extra.active;
+    if (extra?.disabled !== undefined)
+        def.disabled = extra.disabled;
+    if (extra?.reasons !== undefined)
+        def.reasons = extra.reasons;
+    return def;
+}
+const ARROW_DIRECTIONS = {
+    ArrowRight: "right",
+    ArrowLeft: "left",
+    ArrowUp: "up",
+    ArrowDown: "down",
+    Home: "first",
+    End: "last",
+};
+/**
+ * Pure keyboard/controller resolver for an action bar: arrows/Home/End move grid focus, Enter/Space
+ * activate the focused action, and any other single key routes through {@link actionByHotkey}. Returns
+ * the resulting intent without touching the DOM, so it unit-tests headless and `useActionBar` is a
+ * thin shell over it.
+ */
+export function actionBarKeyAction(actions, focusedId, columns, key, options) {
+    const index = focusedId === null ? -1 : actions.findIndex((a) => a.id === focusedId);
+    const dir = ARROW_DIRECTIONS[key];
+    if (dir !== undefined) {
+        const next = moveGridFocus(index, actions.length, columns, dir, { wrap: options?.wrap === true });
+        const nextId = actions[next]?.id;
+        return nextId === undefined ? { handled: false } : { handled: true, focusId: nextId };
+    }
+    if (key === "Enter" || key === " " || key === "Spacebar") {
+        return focusedId === null ? { handled: false } : { handled: true, activateId: focusedId };
+    }
+    const hotkeyId = actionByHotkey(actions, key);
+    return hotkeyId === null ? { handled: false } : { handled: true, focusId: hotkeyId, activateId: hotkeyId };
+}
+/**
+ * The DATA/HOOK layer: resolve `defs` into a live view model with focus, hover, keyboard grid
+ * navigation, and hotkey activation. Rendering-agnostic — feed the returned model to
+ * {@link ActionBarChrome}, or read it directly to lay out a radial or a bespoke card.
+ *
+ * @capability action-bar-model headless action-collection model with focus, hover, keyboard, and hotkey routing
+ */
+export function useActionBar(defs, options) {
+    const [focusedId, setFocusedId] = useState(null);
+    const [hoveredId, setHoveredId] = useState(null);
+    const actions = useMemo(() => resolveActionCollection(defs), [defs]);
+    const columns = options?.columns ?? Math.max(1, actions.length);
+    const activate = useCallback((id) => options?.onActivate?.(id), [options]);
+    const onKeyDown = useCallback((event) => {
+        const result = actionBarKeyAction(actions, focusedId, columns, event.key, { wrap: options?.wrap === true });
+        if (!result.handled)
+            return;
+        if (result.activateId !== undefined && options?.hotkeys === false && result.focusId === result.activateId) {
+            // hotkey routing suppressed
+        }
+        else {
+            if (result.focusId !== undefined)
+                setFocusedId(result.focusId);
+            if (result.activateId !== undefined)
+                activate(result.activateId);
+        }
+        event.preventDefault();
+    }, [actions, focusedId, columns, options, activate]);
+    return {
+        actions,
+        columns,
+        focusedId,
+        hoveredId,
+        setFocus: setFocusedId,
+        setHover: setHoveredId,
+        activate,
+        onKeyDown,
+    };
+}
+const ITEM_BASE = {
+    position: "relative",
+    boxSizing: "border-box",
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 2,
+    border: "1px solid rgba(255,255,255,0.14)",
+    borderRadius: 8,
+    background: "rgba(14,17,22,0.72)",
+    color: "#eef2f8",
+    font: "600 12px/1.1 ui-sans-serif, system-ui, sans-serif",
+    cursor: "pointer",
+    userSelect: "none",
+    overflow: "hidden",
+};
+/**
+ * The default per-item chrome — a cooldown-aware action button with hotkey cap, cost line, radial
+ * cooldown wipe, and full rest/hover/focus/pressed/active/disabled states. Accessible: it is a real
+ * `<button>` with `aria-disabled`, `aria-pressed` for toggles, `aria-keyshortcuts`, and a native
+ * `title` describing why it is blocked. Swap it via `ActionBarChrome`'s `renderItem`, or drop it into
+ * a radial layout yourself.
+ *
+ * @capability action-button cooldown/cost/hotkey action button with complete interaction states
+ */
+export function ActionButton({ action, focused = false, hovered = false, size = 52, showHotkey = true, tabIndex, buttonRef, onActivate, onFocus, onHover, renderIcon, className, style, }) {
+    const tip = actionTooltip(action);
+    const title = [tip.title, ...(tip.notes ?? [])].join("\n");
+    const cooldown = action.cooldown;
+    const wipeDeg = cooldown !== null && !cooldown.ready ? Math.round(cooldown.fraction * 360) : 0;
+    return (_jsxs("button", { type: "button", ref: buttonRef, className: className, "data-action-id": action.id, "data-active": action.active ? "" : undefined, "data-enabled": action.enabled ? "" : undefined, "data-focused": focused ? "" : undefined, "aria-disabled": !action.enabled, "aria-pressed": action.active, "aria-keyshortcuts": action.hotkey, "aria-label": action.label, title: title, tabIndex: tabIndex, onClick: () => onActivate?.(action.id), onFocus: () => onFocus?.(action.id), onPointerEnter: () => onHover?.(action.id), onPointerLeave: () => onHover?.(null), style: {
+            ...ITEM_BASE,
+            width: size,
+            height: size,
+            opacity: action.enabled ? 1 : 0.5,
+            borderColor: action.active
+                ? "rgba(56,189,248,0.95)"
+                : focused
+                    ? "rgba(148,197,255,0.9)"
+                    : hovered
+                        ? "rgba(255,255,255,0.3)"
+                        : "rgba(255,255,255,0.14)",
+            boxShadow: focused
+                ? "0 0 0 2px rgba(96,165,250,0.7)"
+                : action.active
+                    ? "0 0 0 1px rgba(56,189,248,0.6)"
+                    : "none",
+            transform: hovered && action.enabled ? "translateY(-1px)" : "none",
+            transition: "transform 120ms ease, border-color 120ms ease, box-shadow 120ms ease",
+            ...style,
+        }, children: [showHotkey && action.hotkey !== undefined ? (_jsx("span", { style: { position: "absolute", top: 2, left: 3 }, "aria-hidden": true, children: _jsx(Keycap, { style: { fontSize: 9, padding: "0 3px", opacity: 0.85 }, children: action.hotkey }) })) : null, _jsx("span", { style: { fontSize: renderIcon ? undefined : 18, lineHeight: 1 }, "data-action-icon": true, "aria-hidden": true, children: renderIcon ? renderIcon(action) : (action.icon ?? action.label.slice(0, 2)) }), action.costs.length > 0 ? (_jsx("span", { "data-action-costs": true, style: { display: "flex", gap: 4, fontSize: 9 }, children: action.costs.map((cost) => (_jsx("span", { style: { color: cost.met ? "rgba(147,197,253,0.9)" : "#f87171" }, children: cost.amount }, cost.resourceId))) })) : null, wipeDeg > 0 ? (_jsx("span", { "data-action-cooldown": true, "aria-hidden": true, style: {
+                    position: "absolute",
+                    inset: 0,
+                    pointerEvents: "none",
+                    background: `conic-gradient(rgba(4,6,10,0.62) ${wipeDeg}deg, transparent 0deg)`,
+                }, children: _jsx("span", { style: {
+                        position: "absolute",
+                        inset: 0,
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "center",
+                        fontSize: 13,
+                        fontWeight: 700,
+                        fontVariantNumeric: "tabular-nums",
+                    }, children: (action.cooldown.remainingMs / 1000).toFixed(action.cooldown.remainingMs < 10000 ? 1 : 0) }) })) : null] }));
+}
+/**
+ * The composable RENDERER: lay the model's actions out as a `grid` or `list` toolbar with roving
+ * tabindex, arrow-key navigation, and a moved DOM focus. `renderItem` swaps per-item chrome; omit it
+ * for {@link ActionButton}. A radial or bespoke UI can skip this entirely and read the model. Purely
+ * a wiring/behavior layer — no panel skin — so a game art-directs freely.
+ *
+ * @capability action-bar-chrome accessible grid/list toolbar renderer over an action-bar model with swappable item chrome
+ */
+export function ActionBarChrome({ model, layout = "grid", itemSize = 52, gap = 6, ariaLabel = "Actions", renderItem, className, style, }) {
+    const refs = useRef(new Map());
+    const { actions, focusedId, hoveredId, columns } = model;
+    const rovingId = focusedId ?? actions[0]?.id ?? null;
+    useEffect(() => {
+        if (focusedId === null)
+            return;
+        refs.current.get(focusedId)?.focus();
+    }, [focusedId]);
+    const containerStyle = layout === "grid"
+        ? { display: "grid", gridTemplateColumns: `repeat(${Math.max(1, columns)}, ${itemSize}px)`, gap }
+        : { display: "flex", flexDirection: "column", gap };
+    return (_jsx("div", { role: "toolbar", "aria-label": ariaLabel, "aria-orientation": layout === "list" ? "vertical" : "horizontal", className: className, "data-action-bar": "", onKeyDown: model.onKeyDown, style: { ...containerStyle, ...style }, children: actions.map((action) => {
+            const ctx = {
+                focused: focusedId === action.id,
+                hovered: hoveredId === action.id,
+                model,
+            };
+            if (renderItem !== undefined)
+                return _jsx("div", { children: renderItem(action, ctx) }, action.id);
+            return (_jsx(ActionButton, { action: action, focused: ctx.focused, hovered: ctx.hovered, size: itemSize, tabIndex: rovingId === action.id ? 0 : -1, buttonRef: (node) => {
+                    if (node === null)
+                        refs.current.delete(action.id);
+                    else
+                        refs.current.set(action.id, node);
+                }, onActivate: model.activate, onFocus: model.setFocus, onHover: model.setHover }, action.id));
+        }) }));
+}
+const PANEL = {
+    padding: 8,
+    borderRadius: 12,
+    background: "rgba(10,12,16,0.6)",
+    backdropFilter: "blur(6px)",
+    WebkitBackdropFilter: "blur(6px)",
+    border: "1px solid rgba(255,255,255,0.1)",
+    boxShadow: "0 4px 16px rgba(0,0,0,0.35)",
+};
+/**
+ * The batteries-included default: a skinned glass panel wrapping {@link useActionBar} +
+ * {@link ActionBarChrome}. Pass `defs`, choose `grid`/`list`, and hand it `onActivate`. The renderer
+ * and item chrome are still swappable via `renderItem`; a game that wants a different frame composes
+ * the hook and chrome directly.
+ *
+ * @capability action-bar drop-in cooldown/cost/hotkey action bar over the headless action model
+ */
+export function ActionBar({ defs, columns, layout = "grid", wrap, hotkeys, itemSize, ariaLabel, onActivate, renderItem, className, style, }) {
+    const model = useActionBar(defs, { columns, wrap, hotkeys, onActivate });
+    return (_jsx("div", { className: className, "data-action-panel": "", style: { ...PANEL, display: "inline-block", ...style }, children: _jsx(ActionBarChrome, { model: model, layout: layout, itemSize: itemSize, ariaLabel: ariaLabel, renderItem: renderItem }) }));
+}
+/**
+ * An accessible popover shell positioned by the pure {@link placePopover} math — flips and clamps
+ * against the viewport, renders nothing while closed, and defaults to `role="tooltip"`. Reuse it for
+ * an action's hover/focus description or any anchored panel.
+ *
+ * @capability popover viewport-flipping, viewport-clamped anchored popover/tooltip shell
+ */
+export function Popover({ open, anchorRef, side = "top", gap = 8, role = "tooltip", id, children, className, style, }) {
+    const ref = useRef(null);
+    const [pos, setPos] = useState(null);
+    useEffect(() => {
+        if (!open || typeof window === "undefined")
+            return;
+        const anchor = anchorRef.current;
+        const node = ref.current;
+        if (anchor === null || node === null)
+            return;
+        const a = anchor.getBoundingClientRect();
+        const c = node.getBoundingClientRect();
+        const placement = placePopover({ x: a.left, y: a.top, width: a.width, height: a.height }, { width: c.width, height: c.height }, { width: window.innerWidth, height: window.innerHeight }, { preferred: side, gap });
+        setPos({ left: placement.left, top: placement.top });
+    }, [open, side, gap, anchorRef]);
+    if (!open)
+        return null;
+    return (_jsx("div", { ref: ref, role: role, id: id, "data-popover": "", className: className, style: {
+            position: "fixed",
+            left: pos?.left ?? -9999,
+            top: pos?.top ?? -9999,
+            zIndex: 1000,
+            pointerEvents: "none",
+            ...style,
+        }, children: children }));
+}
+/**
+ * Render {@link TooltipContent} (from `actionTooltip`) as a styled block: title, subtitle, body,
+ * hotkey, cost lines, cooldown, and a warning footer of blocking notes. Drop it inside a
+ * {@link Popover} for an action's hover/focus description.
+ *
+ * @capability action-tooltip structured action tooltip body (title, cost, cooldown, blocking notes)
+ */
+export function ActionTooltip({ content, className, style, }) {
+    return (_jsxs("div", { className: className, "data-action-tooltip": "", style: {
+            maxWidth: 240,
+            padding: "8px 10px",
+            borderRadius: 8,
+            background: "rgba(8,10,14,0.95)",
+            border: "1px solid rgba(255,255,255,0.14)",
+            color: "#eef2f8",
+            font: "500 12px/1.35 ui-sans-serif, system-ui, sans-serif",
+            boxShadow: "0 8px 24px rgba(0,0,0,0.5)",
+            ...style,
+        }, children: [_jsxs("div", { style: { display: "flex", alignItems: "baseline", gap: 8 }, children: [_jsx("strong", { style: { fontSize: 13 }, children: content.title }), content.hotkey !== undefined ? (_jsx(Keycap, { style: { marginLeft: "auto", fontSize: 10 }, children: content.hotkey })) : null] }), content.subtitle !== undefined ? (_jsx("div", { style: { fontSize: 10, textTransform: "uppercase", letterSpacing: 0.4, opacity: 0.6 }, children: content.subtitle })) : null, content.body !== undefined ? _jsx("div", { style: { marginTop: 4, opacity: 0.9 }, children: content.body }) : null, content.costs !== undefined && content.costs.length > 0 ? (_jsx("div", { style: { marginTop: 4, display: "flex", gap: 8, fontSize: 11 }, children: content.costs.map((cost) => (_jsxs("span", { style: { color: cost.met ? "rgba(147,197,253,0.95)" : "#f87171" }, children: [cost.amount, " ", cost.resourceId] }, cost.resourceId))) })) : null, content.cooldown != null ? (_jsxs("div", { style: { marginTop: 4, fontSize: 11, opacity: 0.8 }, children: [(content.cooldown.remainingMs / 1000).toFixed(1), "s cooldown"] })) : null, content.notes !== undefined && content.notes.length > 0 ? (_jsx("div", { style: { marginTop: 6, paddingTop: 4, borderTop: "1px solid rgba(255,255,255,0.1)", fontSize: 11, color: "#fca5a5" }, children: content.notes.map((note) => (_jsx("div", { children: note }, note))) })) : null] }));
+}

package/dist/cards.d.ts

@@ -0,0 +1,59 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { CardPileState } from "@jgengine/core/cards/cardPile";
+import { type DragLayer } from "./dragLayer.js";
+/** The four French-deck suits. */
+export type Suit = "clubs" | "diamonds" | "hearts" | "spades";
+/** A playing-card rank, ace through king. */
+export type Rank = "A" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "J" | "Q" | "K";
+/** Suits in canonical order (clubs, diamonds, hearts, spades). */
+export declare const SUITS: readonly Suit[];
+/** Ranks in ascending order, ace low. */
+export declare const RANKS: readonly Rank[];
+/** True for the red suits (hearts, diamonds). */
+export declare function isRedSuit(suit: Suit): boolean;
+/** A single card in a stack: an id plus its face and orientation. */
+export interface PlayingCard {
+    id: string;
+    rank: Rank;
+    suit: Suit;
+    faceDown?: boolean;
+}
+/** A single playing-card face: rank + suit pips, or a patterned back when `faceDown`. */
+export declare function CardFace({ rank, suit, faceDown, width, height, className, style, children, }: {
+    rank: Rank;
+    suit: Suit;
+    faceDown?: boolean;
+    width?: number;
+    height?: number;
+    className?: string;
+    style?: CSSProperties;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+/**
+ * An overlapping fan of `CardFace`s. Plain-props: pass `cards`. Optional drag: pass a `layer`
+ * to make each card a `DraggableCard`, and `dropId` to wrap the pile in a `DropZone`.
+ */
+export declare function StackedPile({ cards, faceDown, offsetX, offsetY, cardWidth, cardHeight, layer, dropId, draggableFrom, className, cardClassName, onCardClick, renderOverlay, }: {
+    cards: readonly PlayingCard[];
+    faceDown?: boolean;
+    offsetX?: number;
+    offsetY?: number;
+    cardWidth?: number;
+    cardHeight?: number;
+    layer?: DragLayer<PlayingCard>;
+    dropId?: string;
+    draggableFrom?: number;
+    className?: string;
+    cardClassName?: string;
+    onCardClick?: (card: PlayingCard, index: number) => void;
+    renderOverlay?: (card: PlayingCard, index: number) => ReactNode;
+}): import("react").JSX.Element;
+/**
+ * `StackedPile` bound to a headless `CardPileState` zone: reads the ordered card ids from
+ * `pile.zones[zone]` and resolves each to a `PlayingCard` via `cardOf`.
+ */
+export declare function CardStack({ pile, zone, cardOf, ...rest }: {
+    pile: CardPileState;
+    zone: string;
+    cardOf: (id: string) => PlayingCard;
+} & Omit<Parameters<typeof StackedPile>[0], "cards">): import("react").JSX.Element;

package/dist/cards.js

@@ -0,0 +1,116 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { DraggableCard, DropZone } from "./dragLayer.js";
+/** Suits in canonical order (clubs, diamonds, hearts, spades). */
+export const SUITS = ["clubs", "diamonds", "hearts", "spades"];
+/** Ranks in ascending order, ace low. */
+export const RANKS = ["A", "2", "3", "4", "5", "6", "7", "8", "9", "10", "J", "Q", "K"];
+/** True for the red suits (hearts, diamonds). */
+export function isRedSuit(suit) {
+    return suit === "hearts" || suit === "diamonds";
+}
+const SUIT_PATHS = {
+    hearts: _jsx("path", { d: "M12 21C7 17 3 13.5 3 9.5A4.5 4.5 0 0112 7a4.5 4.5 0 019 2.5C21 13.5 17 17 12 21z" }),
+    diamonds: _jsx("path", { d: "M12 2l7.5 10L12 22 4.5 12z" }),
+    spades: (_jsx("path", { d: "M12 2C8.5 6 3.5 8.5 3.5 13A4 4 0 0011 15.7C10.7 18 9.7 19.3 8 21h8c-1.7-1.7-2.7-3-3-5.3A4 4 0 0020.5 13C20.5 8.5 15.5 6 12 2z" })),
+    clubs: (_jsx("path", { d: "M12 2a3.6 3.6 0 00-2.9 5.7A3.6 3.6 0 108.4 14.6 3.6 3.6 0 0011 15.3C10.8 18 9.8 19.4 8 21h8c-1.8-1.6-2.8-3-3-5.7a3.6 3.6 0 102.6-6.9A3.6 3.6 0 0012 2z" })),
+};
+function SuitGlyph({ suit, size = 16 }) {
+    return (_jsx("svg", { viewBox: "0 0 24 24", width: size, height: size, fill: "currentColor", "aria-hidden": "true", "data-suit-glyph": suit, style: { display: "block" }, children: SUIT_PATHS[suit] }));
+}
+const SUIT_LABEL = {
+    clubs: "clubs",
+    diamonds: "diamonds",
+    hearts: "hearts",
+    spades: "spades",
+};
+/** A single playing-card face: rank + suit pips, or a patterned back when `faceDown`. */
+export function CardFace({ rank, suit, faceDown = false, width = 64, height = 90, className, style, children, }) {
+    const radius = Math.round(Math.min(width, height) * 0.11);
+    const base = {
+        width,
+        height,
+        borderRadius: radius,
+        boxSizing: "border-box",
+        position: "relative",
+        userSelect: "none",
+        ...style,
+    };
+    if (faceDown) {
+        return (_jsxs("div", { className: className, "data-card-face": "", "data-face-down": "", role: "img", "aria-label": "Face-down card", style: {
+                ...base,
+                border: "1px solid #1e2a52",
+                background: "repeating-linear-gradient(45deg, #2b3a72 0, #2b3a72 4px, #1b2650 4px, #1b2650 8px)",
+            }, children: [_jsx("div", { style: {
+                        position: "absolute",
+                        inset: Math.round(Math.min(width, height) * 0.09),
+                        borderRadius: Math.max(2, radius - 3),
+                        border: "1px solid rgba(255,255,255,0.35)",
+                    } }), children] }));
+    }
+    const color = isRedSuit(suit) ? "#c02434" : "#16181d";
+    const cornerFont = Math.round(height * 0.16);
+    const corner = (rotated) => ({
+        position: "absolute",
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        lineHeight: 1,
+        color,
+        fontFamily: "Georgia, 'Times New Roman', serif",
+        fontWeight: 700,
+        fontSize: cornerFont,
+        ...(rotated
+            ? { right: Math.round(width * 0.06), bottom: Math.round(height * 0.05), transform: "rotate(180deg)" }
+            : { left: Math.round(width * 0.06), top: Math.round(height * 0.05) }),
+    });
+    return (_jsxs("div", { className: className, "data-card-face": "", "data-rank": rank, "data-suit": suit, role: "img", "aria-label": `${rank} of ${SUIT_LABEL[suit]}`, style: {
+            ...base,
+            border: "1px solid #c8ccd6",
+            background: "#ffffff",
+        }, children: [_jsxs("span", { "data-card-corner": "top", style: corner(false), children: [_jsx("span", { "data-card-rank": true, children: rank }), _jsx(SuitGlyph, { suit: suit, size: cornerFont })] }), _jsx("div", { style: {
+                    position: "absolute",
+                    inset: 0,
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    color,
+                }, children: _jsx(SuitGlyph, { suit: suit, size: Math.round(Math.min(width, height) * 0.5) }) }), _jsxs("span", { "data-card-corner": "bottom", style: corner(true), children: [_jsx("span", { "data-card-rank": true, children: rank }), _jsx(SuitGlyph, { suit: suit, size: cornerFont })] }), children] }));
+}
+/**
+ * An overlapping fan of `CardFace`s. Plain-props: pass `cards`. Optional drag: pass a `layer`
+ * to make each card a `DraggableCard`, and `dropId` to wrap the pile in a `DropZone`.
+ */
+export function StackedPile({ cards, faceDown, offsetX = 0, offsetY = 20, cardWidth = 64, cardHeight = 90, layer, dropId, draggableFrom = 0, className, cardClassName, onCardClick, renderOverlay, }) {
+    const last = Math.max(0, cards.length - 1);
+    const width = cardWidth + Math.abs(offsetX) * last;
+    const height = cardHeight + Math.abs(offsetY) * last;
+    const baseLeft = offsetX < 0 ? -offsetX * last : 0;
+    const baseTop = offsetY < 0 ? -offsetY * last : 0;
+    const body = (_jsx("div", { className: className, "data-card-stack": "", "data-count": cards.length, style: { position: "relative", width, height }, children: cards.map((card, index) => {
+            const positioned = {
+                position: "absolute",
+                left: baseLeft + offsetX * index,
+                top: baseTop + offsetY * index,
+                zIndex: index,
+            };
+            const face = (_jsx(CardFace, { rank: card.rank, suit: card.suit, faceDown: card.faceDown ?? faceDown, width: cardWidth, height: cardHeight, className: cardClassName, children: renderOverlay?.(card, index) }));
+            const clickable = onCardClick !== undefined;
+            if (layer !== undefined && index >= draggableFrom) {
+                return (_jsx("div", { style: positioned, children: _jsx(DraggableCard, { id: card.id, value: card, layer: layer, onRotate: false, children: face }) }, card.id));
+            }
+            return (_jsx("div", { "data-card-slot": index, style: { ...positioned, cursor: clickable ? "pointer" : undefined }, onClick: clickable ? () => onCardClick(card, index) : undefined, children: face }, card.id));
+        }) }));
+    if (layer !== undefined && dropId !== undefined) {
+        return (_jsx(DropZone, { id: dropId, layer: layer, children: body }));
+    }
+    return body;
+}
+/**
+ * `StackedPile` bound to a headless `CardPileState` zone: reads the ordered card ids from
+ * `pile.zones[zone]` and resolves each to a `PlayingCard` via `cardOf`.
+ */
+export function CardStack({ pile, zone, cardOf, ...rest }) {
+    const ids = pile.zones[zone] ?? [];
+    const cards = ids.map(cardOf);
+    return _jsx(StackedPile, { cards: cards, ...rest });
+}