@dreamboard-games/sdk 0.2.0

package/src/ui/components/StagingZone.tsx

@@ -0,0 +1,134 @@
+/**
+ * Controlled staging zone — a fixed row of card slots for a many-select
+ * collection (e.g. "the cards you are passing"). Filled slots render a
+ * caller-provided card and are tappable to remove it; the remaining slots
+ * render a themed empty placeholder so the zone is always visible (and always
+ * an obvious target) even before anything is staged.
+ *
+ * Purely presentational: it does not read or mutate any Dreamboard draft. A
+ * runtime adapter feeds it the staged cards plus an `onRemove` that toggles the
+ * card back out of the collection. In a later slice this same surface becomes
+ * the drop target for drag-to-stage.
+ */
+
+import { clsx } from "clsx";
+import type { ReactNode } from "react";
+import type { ViewCard } from "../../types/index.js";
+import { useTheme } from "../theme/ThemeProvider.js";
+
+export interface StagingZoneProps<CardData extends ViewCard = ViewCard> {
+  /** Cards currently staged, in order. */
+  cards: readonly CardData[];
+  /** Total number of slots to render (e.g. the collector's selection max). */
+  slotCount: number;
+  /** Card size; empty-slot dimensions match the SDK `CardFace` sizes. */
+  size?: "sm" | "md" | "lg";
+  /** Visual for a staged card (typically a `CardFace`). */
+  renderCard: (card: CardData) => ReactNode;
+  /** Fires when a staged card is activated — remove it from the collection. */
+  onRemove?: (cardId: string) => void;
+  /** Custom empty-slot content. Defaults to an empty dashed placeholder. */
+  renderEmptySlot?: (index: number) => ReactNode;
+  /** Optional heading rendered above the slots. */
+  label?: ReactNode;
+  /** Accessible label for the region. */
+  "aria-label"?: string;
+  className?: string;
+}
+
+// Match `CardFace`'s `sizeClasses` so empty slots line up with staged cards.
+const SLOT_SIZE_CLASS: Record<"sm" | "md" | "lg", string> = {
+  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",
+};
+
+export function StagingZone<CardData extends ViewCard = ViewCard>({
+  cards,
+  slotCount,
+  size = "sm",
+  renderCard,
+  onRemove,
+  renderEmptySlot,
+  label,
+  "aria-label": ariaLabel = "Staged cards",
+  className,
+}: StagingZoneProps<CardData>) {
+  const theme = useTheme();
+  const total = Math.max(0, slotCount, cards.length);
+  const slotClass = SLOT_SIZE_CLASS[size];
+  const interactive = Boolean(onRemove);
+
+  return (
+    <div
+      data-dreamboard-staging-zone=""
+      data-staged-count={cards.length}
+      role="group"
+      aria-label={ariaLabel}
+      className={clsx(
+        "flex flex-col items-center gap-2 rounded-2xl px-4 py-3",
+        className,
+      )}
+      style={{
+        background: theme.semantic.surface.inset,
+        border: `2px solid ${theme.semantic.border.subtle}`,
+      }}
+    >
+      {label != null ? (
+        <span
+          className="text-[11px] font-bold uppercase tracking-[0.12em]"
+          style={{ color: theme.semantic.text.muted }}
+        >
+          {label}
+        </span>
+      ) : null}
+      <div className="flex items-end justify-center gap-2">
+        {Array.from({ length: total }, (_, index) => {
+          const card = cards[index];
+          if (!card) {
+            return (
+              <div
+                key={`empty-${index}`}
+                data-dreamboard-staging-slot="empty"
+                aria-hidden
+                className={clsx(
+                  "flex shrink-0 items-center justify-center rounded-xl",
+                  slotClass,
+                )}
+                style={{
+                  border: `2px dashed ${theme.semantic.border.subtle}`,
+                  color: theme.semantic.text.disabled,
+                }}
+              >
+                {renderEmptySlot ? renderEmptySlot(index) : null}
+              </div>
+            );
+          }
+          const cardId = card.id as string;
+          return (
+            <button
+              key={cardId}
+              type="button"
+              data-dreamboard-staging-slot="filled"
+              data-card-id={cardId}
+              disabled={!interactive}
+              aria-label={
+                interactive ? `Remove ${card.name ?? cardId}` : undefined
+              }
+              onClick={interactive ? () => onRemove?.(cardId) : undefined}
+              className={clsx(
+                "relative shrink-0 appearance-none border-0 bg-transparent p-0 m-0",
+                "transition-transform focus-visible:outline-none",
+                interactive
+                  ? "cursor-pointer hover:-translate-y-1"
+                  : "cursor-default",
+              )}
+            >
+              {renderCard(card)}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/src/ui/components/ThemedButton.tsx

@@ -0,0 +1,113 @@
+import type { ComponentProps } from "react";
+import { clsx } from "clsx";
+import { Button as ShadcnButton } from "../internal/ui/button.js";
+import {
+  buttonStyle,
+  type ButtonSize,
+  type ButtonVariant,
+} from "../theme/derive.js";
+import { useTheme } from "../theme/ThemeProvider.js";
+import {
+  visualStateDataAttributes,
+  type InteractionVisualState,
+} from "../types/visual-state.js";
+
+type ShadcnButtonProps = ComponentProps<typeof ShadcnButton>;
+
+export interface ThemedButtonProps
+  extends Omit<ShadcnButtonProps, "variant" | "size">, InteractionVisualState {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  /** Renders the pressed/active visual treatment without changing variant. */
+  pressed?: boolean;
+  /** Render the in-flight loading state and disable activation. */
+  loading?: boolean;
+}
+
+export function ThemedButton({
+  variant = "primary",
+  size = "md",
+  pressed = false,
+  loading = false,
+  eligible,
+  selected,
+  disabled,
+  invalid,
+  submitted,
+  previewing,
+  intentProgress,
+  className,
+  style,
+  ...props
+}: ThemedButtonProps) {
+  const theme = useTheme();
+  const isDisabled = disabled || loading || submitted;
+  const dataAttributes = visualStateDataAttributes({
+    eligible,
+    selected,
+    disabled: isDisabled,
+    invalid,
+    submitted,
+    previewing,
+    intentProgress,
+  });
+  return (
+    <ShadcnButton
+      variant={toShadcnVariant(submitted ? "submitted" : variant)}
+      size={toShadcnSize(size)}
+      disabled={isDisabled}
+      data-dreamboard-button
+      data-dreamboard-button-variant={submitted ? "submitted" : variant}
+      data-dreamboard-button-size={size}
+      data-pressed={pressed ? "true" : undefined}
+      data-loading={loading ? "true" : undefined}
+      aria-busy={loading || undefined}
+      aria-pressed={selected ? true : pressed ? true : undefined}
+      aria-invalid={invalid || undefined}
+      {...dataAttributes}
+      className={clsx("font-sans", className)}
+      style={{
+        ...buttonStyle(theme, {
+          variant: submitted ? "submitted" : variant,
+          size,
+          disabled: isDisabled,
+          pressed,
+        }),
+        ...style,
+      }}
+      {...props}
+    />
+  );
+}
+
+function toShadcnVariant(
+  variant: ButtonVariant,
+): NonNullable<ShadcnButtonProps["variant"]> {
+  switch (variant) {
+    case "danger":
+      return "destructive";
+    case "ghost":
+      return "ghost";
+    case "secondary":
+      return "secondary";
+    case "primary":
+    case "submitted":
+    case "success":
+    case "warning":
+    case "info":
+      return "default";
+  }
+}
+
+function toShadcnSize(
+  size: ButtonSize,
+): NonNullable<ShadcnButtonProps["size"]> {
+  switch (size) {
+    case "sm":
+      return "sm";
+    case "md":
+      return "default";
+    case "lg":
+      return "lg";
+  }
+}

package/src/ui/components/Toast.tsx

@@ -0,0 +1,264 @@
+/**
+ * Plugin-internal toast notification system.
+ *
+ * `<ToastProvider>` exposes `<Toast.Actions>` for game-specific feedback
+ * ("Resource gained", "Card discarded", "Tip: rotate the board with R", …).
+ * It is intentionally NOT wired to the host notification stream:
+ * `YOUR_TURN`, `PROMPT_OPENED` and `ACTION_REJECTED` events are owned
+ * by the product host runtime's `<HostFeedbackToaster>` and must
+ * not be mirrored from inside the plugin tree.
+ */
+
+import { motion, AnimatePresence } from "framer-motion";
+import { X, CheckCircle, AlertCircle, Info, AlertTriangle } from "lucide-react";
+import { Alert, AlertDescription } from "../internal/ui/alert.js";
+import {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  type ReactNode,
+} from "react";
+import { useTheme } from "../theme/ThemeProvider.js";
+import { intentForVariant, type ButtonVariant } from "../theme/derive.js";
+import type { Theme } from "../theme/tokens.js";
+import { ThemedButton } from "./ThemedButton.js";
+
+export type ToastType = "success" | "error" | "info" | "warning";
+
+export interface ToastNotification {
+  id: string;
+  type: ToastType;
+  message: string;
+  duration?: number;
+}
+
+interface ToastContextValue {
+  toasts: ToastNotification[];
+  show: (message: string, type?: ToastType, duration?: number) => void;
+  dismiss: (id: string) => void;
+  success: (message: string, duration?: number) => void;
+  error: (message: string, duration?: number) => void;
+  info: (message: string, duration?: number) => void;
+  warning: (message: string, duration?: number) => void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+export type ToastActionsValue = ToastContextValue;
+
+export interface ToastProviderProps {
+  children: ReactNode;
+}
+
+export function ToastProvider({ children }: ToastProviderProps) {
+  const [toasts, setToasts] = useState<ToastNotification[]>([]);
+
+  const show = useCallback(
+    (message: string, type: ToastType = "info", duration = 3000) => {
+      const id = `toast-${Date.now()}-${Math.random()}`;
+      const toast: ToastNotification = { id, type, message, duration };
+
+      setToasts((prev) => {
+        // Dedup by `(type, message)` so a fast burst of identical
+        // toasts collapses to one visible toast instead of stacking
+        // and producing the flicker effect (toast-1 dismisses while
+        // toast-2 mounts → user sees a flash). Keep the existing
+        // entry untouched so its dismiss timer continues.
+        if (
+          prev.some((item) => item.type === type && item.message === message)
+        ) {
+          return prev;
+        }
+        return [...prev, toast];
+      });
+
+      if (duration > 0) {
+        setTimeout(() => {
+          setToasts((prev) => prev.filter((t) => t.id !== id));
+        }, duration);
+      }
+    },
+    [],
+  );
+
+  const dismiss = useCallback((id: string) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id));
+  }, []);
+
+  const success = useCallback(
+    (message: string, duration?: number) => show(message, "success", duration),
+    [show],
+  );
+  const error = useCallback(
+    (message: string, duration?: number) => show(message, "error", duration),
+    [show],
+  );
+  const info = useCallback(
+    (message: string, duration?: number) => show(message, "info", duration),
+    [show],
+  );
+  const warning = useCallback(
+    (message: string, duration?: number) => show(message, "warning", duration),
+    [show],
+  );
+
+  return (
+    <ToastContext.Provider
+      value={{ toasts, show, dismiss, success, error, info, warning }}
+    >
+      {children}
+      <ToastContainer toasts={toasts} onDismiss={dismiss} />
+    </ToastContext.Provider>
+  );
+}
+
+export function useToast() {
+  const context = useContext(ToastContext);
+  if (!context) {
+    throw new Error("useToast must be used within ToastProvider");
+  }
+  return context;
+}
+
+export interface ToastActionsProps {
+  children: (actions: ToastActionsValue) => ReactNode;
+}
+
+export function ToastActions({ children }: ToastActionsProps) {
+  return <>{children(useToast())}</>;
+}
+
+export const Toast = {
+  Actions: ToastActions,
+} as const;
+
+function ToastContainer({
+  toasts,
+  onDismiss,
+}: {
+  toasts: ToastNotification[];
+  onDismiss: (id: string) => void;
+}) {
+  return (
+    <div
+      className="fixed bottom-4 right-4 z-50 flex flex-col gap-2 pointer-events-none"
+      role="region"
+      aria-live="polite"
+      aria-label="Notifications"
+    >
+      <AnimatePresence>
+        {toasts.map((toast) => (
+          <ToastItem key={toast.id} toast={toast} onDismiss={onDismiss} />
+        ))}
+      </AnimatePresence>
+    </div>
+  );
+}
+
+const TOAST_ICONS = {
+  success: CheckCircle,
+  error: AlertCircle,
+  info: Info,
+  warning: AlertTriangle,
+} as const satisfies Record<ToastType, unknown>;
+
+const TOAST_VARIANT: Record<
+  ToastType,
+  Exclude<ButtonVariant, "ghost" | "secondary">
+> = {
+  success: "success",
+  error: "danger",
+  info: "info",
+  warning: "warning",
+};
+
+function toastSurfaceStyle(theme: Theme, type: ToastType): React.CSSProperties {
+  const intent = intentForVariant(theme, TOAST_VARIANT[type]);
+  return {
+    minWidth: 280,
+    maxWidth: 400,
+    display: "flex",
+    alignItems: "flex-start",
+    gap: theme.space[3],
+    padding: theme.space[4],
+    background: intent.soft,
+    color: intent.onSoft,
+    border: `2px solid ${intent.border}`,
+    borderRadius: theme.radius.lg,
+    boxShadow: theme.elevation.lifted,
+    backdropFilter: "blur(4px)",
+    WebkitBackdropFilter: "blur(4px)",
+    fontFamily: theme.typography.fontFamily.body,
+  };
+}
+
+function ToastItem({
+  toast,
+  onDismiss,
+}: {
+  toast: ToastNotification;
+  onDismiss: (id: string) => void;
+}) {
+  const theme = useTheme();
+  const reducedMotion = theme.motion.reducedMotion === "true";
+  const Icon = TOAST_ICONS[toast.type];
+  const intent = intentForVariant(theme, TOAST_VARIANT[toast.type]);
+  const surfaceStyle = toastSurfaceStyle(theme, toast.type);
+
+  return (
+    <motion.div
+      style={{ pointerEvents: "auto" }}
+      initial={
+        reducedMotion ? { opacity: 0 } : { opacity: 0, y: 20, scale: 0.9 }
+      }
+      animate={reducedMotion ? { opacity: 1 } : { opacity: 1, y: 0, scale: 1 }}
+      exit={reducedMotion ? { opacity: 0 } : { opacity: 0, x: 100, scale: 0.9 }}
+      transition={{ type: "spring", stiffness: 300, damping: 25 }}
+    >
+      <Alert
+        variant={toast.type === "error" ? "destructive" : "default"}
+        style={surfaceStyle}
+      >
+        <Icon
+          size={20}
+          style={{
+            marginTop: 2,
+            flexShrink: 0,
+            color: intent.solid,
+          }}
+          aria-hidden="true"
+        />
+
+        <AlertDescription
+          style={{
+            flex: 1,
+            fontSize: theme.typography.fontSize.sm,
+            fontWeight: theme.typography.fontWeight.medium,
+            lineHeight: theme.typography.lineHeight.relaxed,
+            color: intent.onSoft,
+          }}
+        >
+          {toast.message}
+        </AlertDescription>
+
+        <ThemedButton
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={() => onDismiss(toast.id)}
+          style={{
+            height: 28,
+            width: 28,
+            flexShrink: 0,
+            borderRadius: theme.radius.pill,
+            color: intent.onSoft,
+          }}
+          aria-label="Close notification"
+        >
+          <X size={16} aria-hidden="true" />
+        </ThemedButton>
+      </Alert>
+    </motion.div>
+  );
+}