@dreamboard-games/ui-sdk 0.0.41

package/src/components/Hand.tsx

@@ -0,0 +1,387 @@
+/**
+ * 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,
+  type CardSize,
+  type HandLayout,
+} from "../hooks/useHandLayout.js";
+import { Card, type ViewCard } from "./Card.js";
+import type { ReactNode } from "react";
+import { useTheme } from "../theme/ThemeProvider.js";
+
+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;
+}
+
+const EMPTY_SELECTED_IDS: readonly string[] = [];
+
+/**
+ * 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,
+}: HandDrawerRenderProps): ReactNode {
+  const theme = useTheme();
+  const label = `View ${cardCount} card${cardCount === 1 ? "" : "s"}${
+    selectedCount > 0 ? ` (${selectedCount} selected)` : ""
+  }`;
+  return (
+    <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,
+      }}
+    >
+      {label}
+    </div>
+  );
+}
+
+function DefaultEmpty(): ReactNode {
+  const theme = useTheme();
+  return (
+    <span
+      style={{
+        fontFamily: theme.typography.fontFamily.body,
+        fontSize: theme.typography.fontSize.xs,
+        color: theme.semantic.text.disabled,
+      }}
+    >
+      No cards in hand
+    </span>
+  );
+}
+
+/**
+ * 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<CardData extends ViewCard = ViewCard>({
+  cards,
+  selectedIds = EMPTY_SELECTED_IDS,
+  disabled = false,
+  cardSize = "md",
+  layout = "overlap",
+  "aria-label": ariaLabel = "Your hand",
+  onCardClick,
+  renderCardContent,
+  renderCard,
+  renderDrawer,
+  renderEmpty,
+  renderContainer,
+  className,
+}: HandProps<CardData>) {
+  const defaultRenderCard = useCallback(
+    (props: HandCardRenderProps<CardData>): ReactNode => (
+      <div
+        key={props.card.id}
+        className="absolute bottom-0 transition-all duration-150 ease-out"
+        style={{
+          left: props.x,
+          zIndex: props.zIndex,
+          transform: `translateY(${props.y}px)`,
+        }}
+      >
+        <Card
+          card={props.card}
+          selected={props.isSelected}
+          disabled={disabled}
+          size={cardSize}
+          onCardClick={onCardClick}
+          renderContent={renderCardContent}
+        />
+      </div>
+    ),
+    [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: React.KeyboardEvent) => {
+      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 (
+      <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" : ""}`}
+      >
+        {effectiveRenderDrawer({
+          cards,
+          selectedIds,
+          cardCount,
+          selectedCount,
+          disabled,
+          cardDimensions,
+        })}
+      </div>
+    );
+  }
+
+  // Empty hand
+  if (cardCount === 0) {
+    return (
+      <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`}
+      >
+        {effectiveRenderEmpty({ layout })}
+      </div>
+    );
+  }
+
+  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 (
+      <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)}
+      >
+        <div className="flex gap-1 justify-center flex-wrap">
+          {renderedCards}
+        </div>
+      </div>
+    );
+  }
+
+  // Overlap/Stack layout
+  const totalHeight = cardDimensions.height + constants.hoverLift + 8;
+
+  const containerProps: HandContainerRenderProps = {
+    totalWidth,
+    totalHeight,
+    cardDimensions,
+    children: renderedCards,
+    onMouseMove: handleMouseMove,
+    onMouseLeave: handleMouseLeave,
+  };
+
+  // Allow custom container rendering
+  if (renderContainer) {
+    return (
+      <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" : ""}`}
+      >
+        {renderContainer(containerProps)}
+      </div>
+    );
+  }
+
+  return (
+    <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)}
+    >
+      <div
+        ref={cardsContainerRef}
+        className="relative"
+        style={{
+          width: layout === "overlap" ? totalWidth : undefined,
+          height: totalHeight,
+        }}
+        onMouseMove={handleMouseMove}
+        onMouseLeave={handleMouseLeave}
+      >
+        {renderedCards}
+      </div>
+    </div>
+  );
+}
+
+// Re-export types and hook for users who want full control
+export { useHandLayout } from "../hooks/useHandLayout.js";
+export type {
+  UseHandLayoutOptions,
+  UseHandLayoutReturn,
+  CardPositionProps,
+  CardSize,
+  HandLayout,
+} from "../hooks/useHandLayout.js";
+export type { ViewCard } from "./Card.js";

package/src/components/HandDock.tsx

@@ -0,0 +1,257 @@
+import { useId, useState, type CSSProperties, type ReactNode } from "react";
+import {
+  Drawer,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerTrigger,
+} from "./Drawer.js";
+import { useChromeSuppression } from "./ChromeSuppressionContext.js";
+import { ThemedButton } from "./ThemedButton.js";
+import { useThemeCssVars } from "../theme/ThemeProvider.js";
+
+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;
+}
+
+const DEFAULT_MAX_WIDTH = "min(28rem, calc(100vw - 24px))";
+const DEFAULT_MAX_HEIGHT = "min(65vh, calc(100vh - 96px))";
+
+function placementStyle(placement: HandDockPlacement): CSSProperties {
+  const base: CSSProperties = {
+    position: "fixed",
+    bottom: "calc(12px + env(safe-area-inset-bottom, 0px))",
+    zIndex: 900,
+  };
+  switch (placement) {
+    case "bottom-center":
+      return {
+        ...base,
+        left: "50%",
+        transform: "translateX(-50%)",
+      };
+    case "bottom-right":
+      return {
+        ...base,
+        right: "calc(12px + env(safe-area-inset-right, 0px))",
+      };
+    case "bottom-left":
+    default:
+      return {
+        ...base,
+        left: "calc(12px + env(safe-area-inset-left, 0px))",
+      };
+  }
+}
+
+function triggerAlignment(
+  placement: HandDockPlacement,
+): CSSProperties["alignSelf"] {
+  switch (placement) {
+    case "bottom-center":
+      return "center";
+    case "bottom-right":
+      return "flex-end";
+    case "bottom-left":
+    default:
+      return "flex-start";
+  }
+}
+
+function renderToggleLabel(
+  label: string,
+  count: number,
+  open: boolean,
+  override: HandDockPresentation["toggleLabel"],
+) {
+  if (typeof override === "function") return override({ label, count, open });
+  if (override !== undefined) return override;
+  return `${label} (${count})`;
+}
+
+export function HandDock({
+  label,
+  count,
+  presentation,
+  children,
+}: HandDockProps) {
+  const mode = presentation?.mode ?? "inline";
+  const [open, setOpen] = useState(presentation?.defaultOpen ?? false);
+  const contentId = useId();
+  const themeCssVars = useThemeCssVars();
+  useChromeSuppression(contentId, mode === "drawer" && open);
+
+  if (mode === "hidden") return null;
+  if (mode === "inline") return <>{children}</>;
+
+  const placement = presentation?.placement ?? "bottom-left";
+  const toggleLabel = renderToggleLabel(
+    label,
+    count,
+    open,
+    presentation?.toggleLabel,
+  );
+
+  const fallbackContentStyle: CSSProperties = {
+    maxHeight: presentation?.maxHeight ?? DEFAULT_MAX_HEIGHT,
+    overflow: "auto",
+    padding: 12,
+    pointerEvents: "auto",
+  };
+  const triggerStyle: CSSProperties = {
+    alignSelf: triggerAlignment(placement),
+    boxShadow: "0 10px 28px rgba(15, 23, 42, 0.22)",
+    pointerEvents: "auto",
+    visibility: open ? "hidden" : "visible",
+  };
+  const canUsePortal = typeof document !== "undefined";
+  const serverOpenContent =
+    !canUsePortal && open ? (
+      <div
+        id={contentId}
+        role="region"
+        aria-label={label}
+        style={fallbackContentStyle}
+      >
+        {children}
+      </div>
+    ) : null;
+
+  return (
+    <Drawer open={open} onOpenChange={setOpen} direction="bottom">
+      <div
+        data-hand-dock={label}
+        data-state={open ? "open" : "closed"}
+        style={{
+          ...placementStyle(placement),
+          display: "flex",
+          maxWidth: presentation?.maxWidth ?? DEFAULT_MAX_WIDTH,
+          width: presentation?.maxWidth ?? DEFAULT_MAX_WIDTH,
+          flexDirection: "column",
+          alignItems: "stretch",
+          gap: 8,
+          pointerEvents: "none",
+          ...presentation?.style,
+        }}
+      >
+        {serverOpenContent}
+        <DrawerTrigger asChild>
+          <ThemedButton
+            type="button"
+            variant="secondary"
+            size="sm"
+            data-state={open ? "open" : "closed"}
+            aria-expanded={open}
+            aria-controls={open ? contentId : undefined}
+            className="rounded-full"
+            style={triggerStyle}
+          >
+            {toggleLabel}
+          </ThemedButton>
+        </DrawerTrigger>
+      </div>
+      {canUsePortal ? (
+        <DrawerContent
+          id={contentId}
+          aria-describedby={undefined}
+          className="border-border bg-background/95 shadow-2xl backdrop-blur supports-[backdrop-filter]:bg-background/90"
+          style={{
+            ...themeCssVars,
+            position: "fixed",
+            right: 0,
+            bottom: 0,
+            left: 0,
+            zIndex: 50,
+            display: "flex",
+            maxHeight: "80vh",
+            flexDirection: "column",
+            overflow: "hidden",
+            borderTop: "1px solid var(--border, #cbd5e1)",
+            borderTopLeftRadius: 16,
+            borderTopRightRadius: 16,
+            background: "var(--background, rgba(255, 255, 255, 0.96))",
+            color: "var(--foreground, #0f172a)",
+            fontFamily: "var(--font-sans)",
+            boxShadow: "0 -18px 48px rgba(15, 23, 42, 0.22)",
+            backdropFilter: "blur(8px)",
+          }}
+        >
+          <DrawerHeader
+            className="border-border border-b px-4 pb-3 pt-3 text-left"
+            style={{
+              display: "flex",
+              flexDirection: "column",
+              gap: 4,
+              borderBottom: "1px solid var(--border, #e2e8f0)",
+              padding: "12px 16px",
+              textAlign: "left",
+            }}
+          >
+            <DrawerTitle
+              className="text-base"
+              style={{ fontSize: 16, fontWeight: 600, lineHeight: 1.25 }}
+            >
+              {label}
+            </DrawerTitle>
+            <DrawerDescription>
+              {count} card{count === 1 ? "" : "s"} available.
+            </DrawerDescription>
+          </DrawerHeader>
+          <div
+            role="region"
+            aria-label={label}
+            style={{
+              maxHeight: presentation?.maxHeight ?? DEFAULT_MAX_HEIGHT,
+              maxWidth: presentation?.maxWidth ?? DEFAULT_MAX_WIDTH,
+              width: "100%",
+              margin: "0 auto",
+              overflow: "auto",
+              padding:
+                "12px 16px calc(16px + env(safe-area-inset-bottom, 0px))",
+              boxSizing: "border-box",
+            }}
+            className="mx-auto w-full overflow-y-auto px-4 pb-[calc(1rem+env(safe-area-inset-bottom,0px))] pt-3"
+          >
+            {children}
+          </div>
+        </DrawerContent>
+      ) : null}
+    </Drawer>
+  );
+}