@dreamboard-games/ui-sdk 0.0.41

package/dist/components/GameEndDisplay.js

@@ -0,0 +1,185 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * End-of-game winner display and scoreboard overlay.
+ *
+ * Visual styling derives entirely from the active {@link useTheme}
+ * (semantic + intent + elevation tokens). The win moment is the
+ * Peak-end anchor of the session, so the surface intentionally pushes
+ * the loudest theme signals (display typeface, primary intent,
+ * elevation.overlay) without inventing one-off colours.
+ */
+import { motion } from "framer-motion";
+import { Trophy, Home, Crown, Medal } from "lucide-react";
+import { useEffect, useState } from "react";
+import { Dialog, DialogContent, DialogTitle } from "../internal/ui/dialog.js";
+import { useTheme } from "../theme/ThemeProvider.js";
+import { chipStyle, intentForVariant, surfaceStyle, } from "../theme/derive.js";
+import { ThemedButton } from "./ThemedButton.js";
+function rankIntent(rank) {
+    if (rank === 1)
+        return "warning"; // gold
+    if (rank === 2)
+        return "secondary"; // silver
+    if (rank === 3)
+        return "info"; // bronze-ish (no bronze in palette)
+    return "secondary";
+}
+function RankIcon({ rank, theme }) {
+    const intent = intentForVariant(theme, rankIntent(rank));
+    if (rank === 1) {
+        return (_jsx(Trophy, { width: 20, height: 20, strokeWidth: 3, "aria-hidden": "true", style: { color: intent.solid } }));
+    }
+    if (rank === 2 || rank === 3) {
+        return (_jsx(Medal, { width: 20, height: 20, strokeWidth: 2.5, "aria-hidden": "true", style: { color: intent.solid } }));
+    }
+    return (_jsxs("span", { style: {
+            width: 20,
+            textAlign: "center",
+            color: theme.semantic.text.muted,
+            fontFamily: theme.typography.fontFamily.tabular,
+            fontWeight: theme.typography.fontWeight.bold,
+        }, children: ["#", rank] }));
+}
+export function GameEndDisplay({ isGameOver, scores, winnerMessage, showDetails = false, onReturnToLobby, className, }) {
+    const theme = useTheme();
+    const reducedMotion = theme.motion.reducedMotion === "true";
+    const [isOpen, setIsOpen] = useState(isGameOver);
+    useEffect(() => {
+        setIsOpen(isGameOver);
+    }, [isGameOver]);
+    if (!isGameOver)
+        return null;
+    const winner = scores.find((s) => s.isWinner) || scores[0];
+    const sortedScores = [...scores].sort((a, b) => b.score - a.score);
+    const winningIntent = theme.semantic.intent.warning;
+    const title = `${winner?.name ?? "Game"} Wins!`;
+    return (_jsx(Dialog, { open: isOpen, onOpenChange: setIsOpen, children: _jsxs(DialogContent, { className: `border-0 p-6 text-center shadow-none sm:max-w-lg ${className ?? ""}`, overlayClassName: "bg-black/50 backdrop-blur-md", "aria-describedby": undefined, style: {
+                ...surfaceStyle(theme, { tone: "sheet", radius: "hud" }),
+                width: "100%",
+                maxWidth: 480,
+                padding: `${theme.space[8]} ${theme.space[6]}`,
+                textAlign: "center",
+                boxShadow: theme.elevation.overlay,
+                overflow: "hidden",
+                backgroundImage: `radial-gradient(circle at top, ${winningIntent.soft} 0%, ${theme.semantic.surface.sheet} 60%)`,
+                fontFamily: theme.typography.fontFamily.body,
+            }, children: [_jsx(DialogTitle, { className: "sr-only", children: title }), _jsx(motion.div, { initial: reducedMotion
+                        ? { scale: 1 }
+                        : { scale: 0.95, rotate: -180, opacity: 0 }, animate: reducedMotion ? { scale: 1 } : { scale: 1, rotate: 0, opacity: 1 }, transition: {
+                        type: "spring",
+                        stiffness: 200,
+                        damping: 15,
+                        delay: reducedMotion ? 0 : 0.2,
+                    }, style: {
+                        marginBottom: theme.space[6],
+                        display: "inline-flex",
+                        alignItems: "center",
+                        justifyContent: "center",
+                        width: 96,
+                        height: 96,
+                        borderRadius: theme.radius.pill,
+                        background: winningIntent.soft,
+                        border: `3px solid ${winningIntent.border}`,
+                        boxShadow: theme.elevation.lifted,
+                    }, children: _jsx(Trophy, { width: 48, height: 48, strokeWidth: 2.5, "aria-hidden": "true", style: { color: winningIntent.solid } }) }), _jsxs(motion.div, { initial: reducedMotion ? { opacity: 0 } : { opacity: 0, y: 10 }, animate: reducedMotion ? { opacity: 1 } : { opacity: 1, y: 0 }, transition: { delay: reducedMotion ? 0 : 0.4 }, children: [_jsx("h2", { "aria-hidden": "true", style: {
+                                margin: 0,
+                                fontFamily: theme.typography.fontFamily.display,
+                                fontSize: theme.typography.fontSize["3xl"],
+                                fontWeight: theme.typography.fontWeight.bold,
+                                color: theme.semantic.text.primary,
+                                marginBottom: theme.space[2],
+                                lineHeight: theme.typography.lineHeight.tight,
+                            }, children: title }), winnerMessage && (_jsx("p", { style: {
+                                margin: 0,
+                                marginBottom: theme.space[6],
+                                display: "inline-block",
+                                ...chipStyle(theme, { variant: "warning", size: "md" }),
+                                fontSize: theme.typography.fontSize.sm,
+                            }, children: winnerMessage }))] }), _jsx(motion.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { delay: reducedMotion ? 0 : 0.6 }, style: {
+                        display: "flex",
+                        flexDirection: "column",
+                        gap: theme.space[3],
+                        marginBottom: theme.space[8],
+                        textAlign: "left",
+                    }, role: "list", "aria-label": "Final scores", children: sortedScores.map((player, index) => {
+                        const rank = index + 1;
+                        const intent = intentForVariant(theme, rankIntent(rank));
+                        const isWinner = player.isWinner ?? rank === 1;
+                        return (_jsxs(motion.div, { initial: reducedMotion ? { opacity: 0 } : { opacity: 0, x: -20 }, animate: reducedMotion ? { opacity: 1 } : { opacity: 1, x: 0 }, transition: {
+                                delay: reducedMotion ? 0 : 0.6 + index * 0.1,
+                            }, style: {
+                                display: "flex",
+                                alignItems: "center",
+                                justifyContent: "space-between",
+                                padding: theme.space[3],
+                                background: isWinner
+                                    ? intent.soft
+                                    : theme.semantic.surface.card,
+                                border: `1px solid ${isWinner ? intent.border : theme.semantic.border.subtle}`,
+                                borderRadius: theme.radius.lg,
+                                boxShadow: isWinner
+                                    ? theme.elevation.hover
+                                    : theme.elevation.rest,
+                            }, role: "listitem", children: [_jsxs("div", { style: {
+                                        display: "flex",
+                                        alignItems: "center",
+                                        gap: theme.space[3],
+                                    }, children: [_jsx(RankIcon, { rank: rank, theme: theme }), _jsx("span", { style: {
+                                                fontFamily: theme.typography.fontFamily.body,
+                                                fontSize: theme.typography.fontSize.lg,
+                                                fontWeight: theme.typography.fontWeight.bold,
+                                                color: isWinner
+                                                    ? intent.onSoft
+                                                    : theme.semantic.text.primary,
+                                            }, children: player.name }), isWinner && (_jsx(Crown, { width: 20, height: 20, strokeWidth: 3, "aria-label": "Winner", style: { color: intent.solid } }))] }), _jsx("span", { style: {
+                                        fontFamily: theme.typography.fontFamily.tabular,
+                                        fontSize: theme.typography.fontSize["2xl"],
+                                        fontWeight: theme.typography.fontWeight.bold,
+                                        color: isWinner
+                                            ? intent.onSoft
+                                            : theme.semantic.text.primary,
+                                        paddingInline: theme.space[2],
+                                        paddingBlock: theme.space[0.5],
+                                        background: theme.semantic.surface.inset,
+                                        borderRadius: theme.radius.md,
+                                        border: `1px solid ${theme.semantic.border.subtle}`,
+                                    }, children: player.score })] }, player.playerId));
+                    }) }), showDetails && winner?.details && (_jsxs(motion.div, { initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { delay: reducedMotion ? 0 : 0.8 }, style: {
+                        marginBottom: theme.space[8],
+                        padding: theme.space[4],
+                        background: theme.semantic.surface.inset,
+                        border: `1px dashed ${theme.semantic.border.default}`,
+                        borderRadius: theme.radius.lg,
+                        textAlign: "left",
+                    }, children: [_jsxs("h3", { style: {
+                                margin: 0,
+                                marginBottom: theme.space[3],
+                                fontFamily: theme.typography.fontFamily.display,
+                                fontSize: theme.typography.fontSize.md,
+                                fontWeight: theme.typography.fontWeight.bold,
+                                color: theme.semantic.text.primary,
+                                display: "flex",
+                                alignItems: "center",
+                                gap: theme.space[2],
+                            }, children: [_jsx("span", { style: {
+                                        width: 8,
+                                        height: 8,
+                                        background: theme.semantic.intent.primary.solid,
+                                        borderRadius: theme.radius.pill,
+                                        display: "inline-block",
+                                    } }), "Score Breakdown"] }), _jsx("div", { style: {
+                                display: "flex",
+                                flexDirection: "column",
+                                gap: theme.space[2],
+                            }, children: Object.entries(winner.details).map(([key, value]) => (_jsxs("div", { style: {
+                                    display: "flex",
+                                    justifyContent: "space-between",
+                                    fontSize: theme.typography.fontSize.md,
+                                    color: theme.semantic.text.primary,
+                                }, children: [_jsx("span", { style: { textTransform: "capitalize" }, children: key.replace(/([A-Z])/g, " $1") }), _jsx("span", { style: {
+                                            fontFamily: theme.typography.fontFamily.tabular,
+                                            fontWeight: theme.typography.fontWeight.bold,
+                                        }, children: value })] }, key))) })] })), onReturnToLobby && (_jsx(motion.div, { initial: reducedMotion ? { opacity: 0 } : { opacity: 0, y: 10 }, animate: reducedMotion ? { opacity: 1 } : { opacity: 1, y: 0 }, transition: { delay: reducedMotion ? 0 : 1 }, style: { display: "flex", justifyContent: "center" }, children: _jsxs(ThemedButton, { type: "button", variant: "primary", size: "lg", onClick: onReturnToLobby, style: {
+                            gap: theme.space[2],
+                        }, children: [_jsx(Home, { size: 20, strokeWidth: 3, "aria-hidden": "true" }), "Return to Lobby"] }) }))] }) }));
+}

package/dist/components/GameSkeleton.d.ts

@@ -0,0 +1,12 @@
+/**
+ * GameSkeleton - Loading state component
+ *
+ * Displays animated placeholders while game content loads
+ */
+export interface GameSkeletonProps {
+    variant?: "default" | "cards" | "players" | "minimal";
+    message?: string;
+    className?: string;
+}
+export declare function GameSkeleton({ variant, message, className, }: GameSkeletonProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=GameSkeleton.d.ts.map

package/dist/components/GameSkeleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GameSkeleton.d.ts","sourceRoot":"","sources":["../../src/components/GameSkeleton.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAiBH,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA8DD,wBAAgB,YAAY,CAAC,EAC3B,OAAmB,EACnB,OAA2B,EAC3B,SAAS,GACV,EAAE,iBAAiB,2CAwKnB"}

package/dist/components/GameSkeleton.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * GameSkeleton - Loading state component
+ *
+ * Displays animated placeholders while game content loads
+ */
+import { motion } from "framer-motion";
+import { clsx } from "clsx";
+import { Loader2 } from "lucide-react";
+const CARD_SKELETON_KEYS = ["card-1", "card-2", "card-3", "card-4", "card-5"];
+const PLAYER_SKELETON_KEYS = ["player-1", "player-2", "player-3", "player-4"];
+const HAND_SKELETON_KEYS = [
+    "hand-card-1",
+    "hand-card-2",
+    "hand-card-3",
+    "hand-card-4",
+    "hand-card-5",
+    "hand-card-6",
+];
+function SkeletonBox({ className, animate = true, }) {
+    return (_jsx(motion.div, { className: clsx("bg-slate-200 rounded", className), animate: animate
+            ? {
+                opacity: [0.5, 1, 0.5],
+            }
+            : undefined, transition: {
+            duration: 1.5,
+            repeat: Infinity,
+            ease: "easeInOut",
+        }, "aria-hidden": "true" }));
+}
+function CardSkeleton({ size = "md" }) {
+    const sizeClasses = {
+        sm: "w-16 h-24 sm:w-20 sm:h-28",
+        md: "w-20 h-32 sm:w-24 sm:h-36",
+        lg: "w-24 h-36 sm:w-32 sm:h-48",
+    };
+    return (_jsx(motion.div, { className: clsx("rounded-lg sm:rounded-xl overflow-hidden", sizeClasses[size]), initial: { opacity: 0, y: 20 }, animate: { opacity: 1, y: 0 }, transition: { type: "spring", stiffness: 300, damping: 25 }, children: _jsx(SkeletonBox, { className: "w-full h-full" }) }));
+}
+function PlayerSkeleton() {
+    return (_jsxs("div", { className: "flex items-center gap-3 p-3 bg-white/80 rounded-xl border-2 border-slate-200", children: [_jsx(SkeletonBox, { className: "w-12 h-12 sm:w-14 sm:h-14 rounded-full" }), _jsxs("div", { className: "flex-1 space-y-2", children: [_jsx(SkeletonBox, { className: "h-4 w-24 sm:w-32" }), _jsx(SkeletonBox, { className: "h-3 w-16 sm:w-20" })] })] }));
+}
+export function GameSkeleton({ variant = "default", message = "Loading game...", className, }) {
+    if (variant === "minimal") {
+        return (_jsxs("div", { className: clsx("flex flex-col items-center justify-center min-h-screen p-8 bg-gradient-to-br from-slate-50 to-slate-100", className), role: "status", "aria-live": "polite", "aria-label": message, children: [_jsx(motion.div, { animate: { rotate: 360 }, transition: { duration: 1, repeat: Infinity, ease: "linear" }, children: _jsx(Loader2, { size: 48, className: "text-blue-500", "aria-hidden": "true" }) }), _jsx(motion.p, { className: "mt-4 text-slate-600 text-lg font-medium", initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { delay: 0.2 }, children: message })] }));
+    }
+    if (variant === "cards") {
+        return (_jsxs("div", { className: clsx("flex flex-col items-center justify-center min-h-screen p-4 sm:p-8", className), role: "status", "aria-live": "polite", "aria-label": message, children: [_jsx("div", { className: "flex gap-2 sm:gap-4 mb-8", children: CARD_SKELETON_KEYS.map((key, i) => (_jsx(motion.div, { initial: { opacity: 0, y: 20 }, animate: { opacity: 1, y: 0 }, transition: { delay: i * 0.1 }, children: _jsx(CardSkeleton, {}) }, key))) }), _jsx(motion.p, { className: "text-slate-600 text-sm sm:text-base", initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { delay: 0.5 }, children: message })] }));
+    }
+    if (variant === "players") {
+        return (_jsxs("div", { className: clsx("flex flex-col items-center justify-center min-h-screen p-4 sm:p-8", className), role: "status", "aria-live": "polite", "aria-label": message, children: [_jsx("div", { className: "w-full max-w-md space-y-4 mb-8", children: PLAYER_SKELETON_KEYS.map((key, i) => (_jsx(motion.div, { initial: { opacity: 0, x: -20 }, animate: { opacity: 1, x: 0 }, transition: { delay: i * 0.1 }, children: _jsx(PlayerSkeleton, {}) }, key))) }), _jsx(motion.p, { className: "text-slate-600 text-sm sm:text-base", initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { delay: 0.4 }, children: message })] }));
+    }
+    // Default variant - complete game layout
+    return (_jsxs("div", { className: clsx("min-h-screen p-4 sm:p-8 bg-gradient-to-br from-slate-50 to-slate-100", className), role: "status", "aria-live": "polite", "aria-label": message, children: [_jsxs("div", { className: "flex items-center justify-between mb-6 sm:mb-8", children: [_jsx(SkeletonBox, { className: "h-8 w-32 sm:w-48" }), _jsx(SkeletonBox, { className: "h-8 w-20 sm:w-32" })] }), _jsx("div", { className: "grid grid-cols-2 lg:grid-cols-4 gap-3 sm:gap-4 mb-6 sm:mb-8", children: PLAYER_SKELETON_KEYS.map((key, i) => (_jsx(motion.div, { initial: { opacity: 0, scale: 0.9 }, animate: { opacity: 1, scale: 1 }, transition: { delay: i * 0.1 }, children: _jsx(PlayerSkeleton, {}) }, key))) }), _jsx("div", { className: "mb-6 sm:mb-8", children: _jsx(SkeletonBox, { className: "w-full h-48 sm:h-64 rounded-2xl" }) }), _jsx("div", { className: "flex justify-center gap-2 sm:gap-4", children: HAND_SKELETON_KEYS.map((key, i) => (_jsx(motion.div, { initial: { opacity: 0, y: 20 }, animate: { opacity: 1, y: 0 }, transition: { delay: 0.4 + i * 0.05 }, children: _jsx(CardSkeleton, {}) }, key))) }), _jsxs(motion.div, { className: "flex items-center justify-center mt-8", initial: { opacity: 0 }, animate: { opacity: 1 }, transition: { delay: 0.8 }, children: [_jsx(Loader2, { size: 24, className: "text-blue-500 animate-spin mr-3", "aria-hidden": "true" }), _jsx("p", { className: "text-slate-600 text-sm sm:text-base font-medium", children: message })] })] }));
+}

package/dist/components/Hand.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Player hand with adaptive overlap, automatic drawer fallback, and keyboard navigation.
+ * For full control, use the `useHandLayout` hook directly.
+ */
+import { type CardSize, type HandLayout } from "../hooks/useHandLayout.js";
+import { type ViewCard } from "./Card.js";
+import type { ReactNode } from "react";
+export interface HandCardRenderProps<CardData extends ViewCard = ViewCard> {
+    card: CardData;
+    index: number;
+    isHovered: boolean;
+    isSelected: boolean;
+    x: number;
+    y: number;
+    zIndex: number;
+    cardDimensions: {
+        width: number;
+        height: number;
+    };
+}
+export interface HandDrawerRenderProps<CardData extends ViewCard = ViewCard> {
+    cards: readonly CardData[];
+    selectedIds: readonly string[];
+    cardCount: number;
+    selectedCount: number;
+    disabled: boolean;
+    cardDimensions: {
+        width: number;
+        height: number;
+    };
+}
+export interface HandEmptyRenderProps {
+    layout: HandLayout;
+}
+export interface HandContainerRenderProps {
+    totalWidth: number;
+    totalHeight: number;
+    cardDimensions: {
+        width: number;
+        height: number;
+    };
+    children: ReactNode;
+    onMouseMove: (e: React.MouseEvent<HTMLDivElement>) => void;
+    onMouseLeave: () => void;
+}
+export interface HandProps<CardData extends ViewCard = ViewCard> {
+    cards: readonly CardData[];
+    selectedIds?: readonly string[];
+    disabled?: boolean;
+    cardSize?: CardSize;
+    layout?: HandLayout;
+    "aria-label"?: string;
+    /**
+     * Called when a card is clicked. Wired into the default `renderCard`;
+     * ignored when the caller supplies a custom `renderCard`.
+     */
+    onCardClick?: (cardId: string) => void;
+    /** Per-card content renderer forwarded to the default `<Card>`. */
+    renderCardContent?: (card: CardData) => ReactNode;
+    /** Defaults to a positioned `<Card>` honouring click/selection state. */
+    renderCard?: (props: HandCardRenderProps<CardData>) => ReactNode;
+    /** Defaults to a compact "View N cards" button that's keyboard-activatable. */
+    renderDrawer?: (props: HandDrawerRenderProps<CardData>) => ReactNode;
+    /** Defaults to a subtle "No cards in hand" placeholder. */
+    renderEmpty?: (props: HandEmptyRenderProps) => ReactNode;
+    renderContainer?: (props: HandContainerRenderProps) => ReactNode;
+    className?: string;
+}
+/**
+ * Hand component with customizable rendering via render props.
+ *
+ * `renderCard`, `renderDrawer`, and `renderEmpty` are all optional — the
+ * defaults render the built-in `<Card>` with the supplied `onCardClick` /
+ * `renderCardContent`, a compact drawer fallback on small screens, and a
+ * muted empty placeholder. Override any of them when you need a different
+ * visual treatment.
+ *
+ * For complete control over layout and interactions, use the
+ * `useHandLayout` hook directly.
+ *
+ * @example Zero-config
+ * ```tsx
+ * <Hand cards={cards} onCardClick={(id) => play(id)} />
+ * ```
+ *
+ * @example Custom card content
+ * ```tsx
+ * <Hand
+ *   cards={cards}
+ *   onCardClick={(id) => play(id)}
+ *   renderCardContent={(card) => <DevCardFace card={card} />}
+ * />
+ * ```
+ */
+export declare function Hand<CardData extends ViewCard = ViewCard>({ cards, selectedIds, disabled, cardSize, layout, "aria-label": ariaLabel, onCardClick, renderCardContent, renderCard, renderDrawer, renderEmpty, renderContainer, className, }: HandProps<CardData>): import("react/jsx-runtime").JSX.Element;
+export { useHandLayout } from "../hooks/useHandLayout.js";
+export type { UseHandLayoutOptions, UseHandLayoutReturn, CardPositionProps, CardSize, HandLayout, } from "../hooks/useHandLayout.js";
+export type { ViewCard } from "./Card.js";
+//# sourceMappingURL=Hand.d.ts.map

package/dist/components/Hand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hand.d.ts","sourceRoot":"","sources":["../../src/components/Hand.tsx"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,UAAU,EAChB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAQ,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,WAAW,mBAAmB,CAAC,QAAQ,SAAS,QAAQ,GAAG,QAAQ;IACvE,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED,MAAM,WAAW,qBAAqB,CAAC,QAAQ,SAAS,QAAQ,GAAG,QAAQ;IACzE,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,QAAQ,EAAE,SAAS,CAAC;IACpB,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC;IAC3D,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS,CAAC,QAAQ,SAAS,QAAQ,GAAG,QAAQ;IAC7D,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,mEAAmE;IACnE,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,SAAS,CAAC;IAClD,yEAAyE;IACzE,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,mBAAmB,CAAC,QAAQ,CAAC,KAAK,SAAS,CAAC;IACjE,+EAA+E;IAC/E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,CAAC,QAAQ,CAAC,KAAK,SAAS,CAAC;IACrE,2DAA2D;IAC3D,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,SAAS,CAAC;IACzD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,SAAS,CAAC;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,IAAI,CAAC,QAAQ,SAAS,QAAQ,GAAG,QAAQ,EAAE,EACzD,KAAK,EACL,WAAgC,EAChC,QAAgB,EAChB,QAAe,EACf,MAAkB,EAClB,YAAY,EAAE,SAAuB,EACrC,WAAW,EACX,iBAAiB,EACjB,UAAU,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,SAAS,GACV,EAAE,SAAS,CAAC,QAAQ,CAAC,2CAkNrB;AAGD,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC1D,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,QAAQ,EACR,UAAU,GACX,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC"}

package/dist/components/Hand.js

@@ -0,0 +1,162 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Player hand with adaptive overlap, automatic drawer fallback, and keyboard navigation.
+ * For full control, use the `useHandLayout` hook directly.
+ */
+import { clsx } from "clsx";
+import { useCallback, useState } from "react";
+import { useHandLayout, } from "../hooks/useHandLayout.js";
+import { Card } from "./Card.js";
+import { useTheme } from "../theme/ThemeProvider.js";
+const EMPTY_SELECTED_IDS = [];
+/**
+ * Drawer-mode placeholder rendered when the hand can't fit on screen.
+ * Pulls colours, radii, shadow, and typography from the active theme so
+ * apps that swap themes get a consistent look without overriding
+ * `renderDrawer`. Authors needing a full drawer UI (modals, swipe
+ * sheets) opt in via `renderDrawer`.
+ */
+function DefaultDrawer({ cardCount, selectedCount, }) {
+    const theme = useTheme();
+    const label = `View ${cardCount} card${cardCount === 1 ? "" : "s"}${selectedCount > 0 ? ` (${selectedCount} selected)` : ""}`;
+    return (_jsx("div", { style: {
+            background: theme.semantic.surface.card,
+            border: `1px solid ${theme.semantic.border.default}`,
+            borderRadius: theme.radius.md,
+            paddingBlock: theme.space[1.5],
+            paddingInline: theme.space[3],
+            boxShadow: theme.elevation.rest,
+            fontFamily: theme.typography.fontFamily.body,
+            fontSize: theme.typography.fontSize.xs,
+            fontWeight: theme.typography.fontWeight.bold,
+            color: theme.semantic.text.muted,
+        }, children: label }));
+}
+function DefaultEmpty() {
+    const theme = useTheme();
+    return (_jsx("span", { style: {
+            fontFamily: theme.typography.fontFamily.body,
+            fontSize: theme.typography.fontSize.xs,
+            color: theme.semantic.text.disabled,
+        }, children: "No cards in hand" }));
+}
+/**
+ * Hand component with customizable rendering via render props.
+ *
+ * `renderCard`, `renderDrawer`, and `renderEmpty` are all optional — the
+ * defaults render the built-in `<Card>` with the supplied `onCardClick` /
+ * `renderCardContent`, a compact drawer fallback on small screens, and a
+ * muted empty placeholder. Override any of them when you need a different
+ * visual treatment.
+ *
+ * For complete control over layout and interactions, use the
+ * `useHandLayout` hook directly.
+ *
+ * @example Zero-config
+ * ```tsx
+ * <Hand cards={cards} onCardClick={(id) => play(id)} />
+ * ```
+ *
+ * @example Custom card content
+ * ```tsx
+ * <Hand
+ *   cards={cards}
+ *   onCardClick={(id) => play(id)}
+ *   renderCardContent={(card) => <DevCardFace card={card} />}
+ * />
+ * ```
+ */
+export function Hand({ cards, selectedIds = EMPTY_SELECTED_IDS, disabled = false, cardSize = "md", layout = "overlap", "aria-label": ariaLabel = "Your hand", onCardClick, renderCardContent, renderCard, renderDrawer, renderEmpty, renderContainer, className, }) {
+    const defaultRenderCard = useCallback((props) => (_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: onCardClick, renderContent: renderCardContent }) }, props.card.id)), [cardSize, disabled, onCardClick, renderCardContent]);
+    const effectiveRenderCard = renderCard ?? defaultRenderCard;
+    const effectiveRenderDrawer = renderDrawer ?? DefaultDrawer;
+    const effectiveRenderEmpty = renderEmpty ?? DefaultEmpty;
+    const cardCount = cards.length;
+    const [focusedIndex, setFocusedIndex] = useState(-1);
+    const { containerRef, cardsContainerRef, totalWidth, useDrawerMode, cardDimensions, constants, hoveredIndex, handleMouseMove, handleMouseLeave, getCardPosition, } = useHandLayout({
+        cardCount,
+        cardSize,
+        layout,
+    });
+    const selectedCount = cards.filter((c) => selectedIds.includes(c.id)).length;
+    const handleKeyDown = useCallback((e) => {
+        if (cardCount === 0)
+            return;
+        switch (e.key) {
+            case "ArrowLeft":
+                e.preventDefault();
+                setFocusedIndex((prev) => (prev <= 0 ? cardCount - 1 : prev - 1));
+                break;
+            case "ArrowRight":
+                e.preventDefault();
+                setFocusedIndex((prev) => (prev >= cardCount - 1 ? 0 : prev + 1));
+                break;
+            case "Home":
+                e.preventDefault();
+                setFocusedIndex(0);
+                break;
+            case "End":
+                e.preventDefault();
+                setFocusedIndex(cardCount - 1);
+                break;
+        }
+    }, [cardCount]);
+    // Drawer mode - delegate to user's render function
+    if (useDrawerMode && layout === "overlap" && cardCount > 0) {
+        return (_jsx("div", { ref: containerRef, className: clsx("relative w-full flex items-center justify-center py-4", className), role: "group", "aria-label": `${ariaLabel} - ${cardCount} card${cardCount !== 1 ? "s" : ""}`, children: effectiveRenderDrawer({
+                cards,
+                selectedIds,
+                cardCount,
+                selectedCount,
+                disabled,
+                cardDimensions,
+            }) }));
+    }
+    // Empty hand
+    if (cardCount === 0) {
+        return (_jsx("div", { ref: containerRef, className: clsx("relative w-full flex items-end justify-center py-4 sm:py-6", className), role: "group", "aria-label": `${ariaLabel} - empty`, children: effectiveRenderEmpty({ layout }) }));
+    }
+    const renderedCards = cards.map((card, index) => {
+        const isSelected = selectedIds.includes(card.id);
+        const isFocused = focusedIndex === index;
+        const isHovered = hoveredIndex === index || isFocused;
+        const position = getCardPosition(index, isHovered, isSelected);
+        return effectiveRenderCard({
+            card,
+            index,
+            isHovered,
+            isSelected,
+            x: position.x,
+            y: position.y,
+            zIndex: position.zIndex,
+            cardDimensions,
+        });
+    });
+    if (layout === "spread") {
+        return (_jsx("div", { ref: containerRef, className: clsx("relative w-full flex items-end justify-center py-4 sm:py-6", className), role: "group", "aria-label": `${ariaLabel} - ${cardCount} card${cardCount !== 1 ? "s" : ""}`, tabIndex: 0, onKeyDown: handleKeyDown, onBlur: () => setFocusedIndex(-1), children: _jsx("div", { className: "flex gap-1 justify-center flex-wrap", children: renderedCards }) }));
+    }
+    // Overlap/Stack layout
+    const totalHeight = cardDimensions.height + constants.hoverLift + 8;
+    const containerProps = {
+        totalWidth,
+        totalHeight,
+        cardDimensions,
+        children: renderedCards,
+        onMouseMove: handleMouseMove,
+        onMouseLeave: handleMouseLeave,
+    };
+    // Allow custom container rendering
+    if (renderContainer) {
+        return (_jsx("div", { ref: containerRef, className: clsx("relative w-full flex items-end justify-center py-4 sm:py-6 overflow-visible", className), role: "group", "aria-label": `${ariaLabel} - ${cardCount} card${cardCount !== 1 ? "s" : ""}`, children: renderContainer(containerProps) }));
+    }
+    return (_jsx("div", { ref: containerRef, className: clsx("relative w-full flex items-end justify-center py-4 sm:py-6 overflow-visible", className), role: "group", "aria-label": `${ariaLabel} - ${cardCount} card${cardCount !== 1 ? "s" : ""}`, tabIndex: 0, onKeyDown: handleKeyDown, onBlur: () => setFocusedIndex(-1), children: _jsx("div", { ref: cardsContainerRef, className: "relative", style: {
+                width: layout === "overlap" ? totalWidth : undefined,
+                height: totalHeight,
+            }, onMouseMove: handleMouseMove, onMouseLeave: handleMouseLeave, children: renderedCards }) }));
+}
+// Re-export types and hook for users who want full control
+export { useHandLayout } from "../hooks/useHandLayout.js";

package/dist/components/HandDock.d.ts

@@ -0,0 +1,35 @@
+import { type CSSProperties, type ReactNode } from "react";
+export type HandDockMode = "inline" | "drawer" | "hidden";
+export type HandDockPlacement = "bottom-left" | "bottom-center" | "bottom-right";
+export interface HandDockToggleContext {
+    label: string;
+    count: number;
+    open: boolean;
+}
+export interface HandDockPresentation {
+    /**
+     * `inline` preserves the normal shell hand strip. `drawer` collapses the
+     * zone behind a viewport-safe toggle. `hidden` suppresses the zone entirely.
+     */
+    mode?: HandDockMode;
+    /** Initial drawer state. Defaults to closed. */
+    defaultOpen?: boolean;
+    /** Where the drawer toggle/tray docks in the viewport. */
+    placement?: HandDockPlacement;
+    /** Toggle label override. Receives card count and open state. */
+    toggleLabel?: ReactNode | ((context: HandDockToggleContext) => ReactNode);
+    /** Width of the opened tray. */
+    maxWidth?: CSSProperties["maxWidth"];
+    /** Height of the opened tray before it scrolls. */
+    maxHeight?: CSSProperties["maxHeight"];
+    /** Extra style escape hatch for the outer dock. */
+    style?: CSSProperties;
+}
+export interface HandDockProps {
+    label: string;
+    count: number;
+    presentation?: HandDockPresentation;
+    children: ReactNode;
+}
+export declare function HandDock({ label, count, presentation, children, }: HandDockProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=HandDock.d.ts.map

package/dist/components/HandDock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandDock.d.ts","sourceRoot":"","sources":["../../src/components/HandDock.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAa5E,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAC1D,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,eAAe,GACf,cAAc,CAAC;AAEnB,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;IACpB,gDAAgD;IAChD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,iEAAiE;IACjE,WAAW,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,OAAO,EAAE,qBAAqB,KAAK,SAAS,CAAC,CAAC;IAC1E,gCAAgC;IAChC,QAAQ,CAAC,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACrC,mDAAmD;IACnD,SAAS,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IACvC,mDAAmD;IACnD,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,QAAQ,EAAE,SAAS,CAAC;CACrB;AAyDD,wBAAgB,QAAQ,CAAC,EACvB,KAAK,EACL,KAAK,EACL,YAAY,EACZ,QAAQ,GACT,EAAE,aAAa,kDAgJf"}