@dreamboard-games/sdk 0.2.0

package/src/ui/components/PrimaryActionButton.tsx

@@ -0,0 +1,336 @@
+/**
+ * Theme-aware controlled primary CTA button — the dominant call-to-action on
+ * the screen at any given moment ("Roll dice", "End turn", "Confirm
+ * trade", "Place settlement").
+ *
+ * Visual contract (Laws of UX cross-references):
+ *
+ * - **Fitts** — defaults to `lg` size (min 56px tall, generous
+ *   horizontal padding) so the dock target is easy to land on.
+ *   Authors can opt down to `md`.
+ * - **Von Restorff (isolation)** — uses `intent.primary.solid` with
+ *   `elevation.lifted` and an animated halo when `attention="auto"`
+ *   and `available` is true, so the button outranks every other
+ *   element in its peripheral neighbourhood.
+ * - **Peak-end** — when the action becomes available, the halo pulses for one breath cycle
+ *   so the eye finds the change without re-scanning the screen.
+ * - **Doherty / responsiveness** — clicks set an internal `pending`
+ *   flag the moment submit fires so the button visibly absorbs the
+ *   tap, even on slow networks. Throwing submitters are swallowed
+ *   here for the same reason `<DefaultInteractionButton>` does:
+ *   descriptor availability is authoritative.
+ * - **Accessibility** — minimum 56×56 hit area satisfies WCAG 2.5.5.
+ *   `prefers-reduced-motion` zeroes out the halo and press
+ *   transitions through the theme's `motion.reducedMotion` token.
+ */
+
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { motion } from "framer-motion";
+import { useTheme } from "../theme/ThemeProvider.js";
+import {
+  intentForVariant,
+  type ButtonSize,
+  type ButtonVariant,
+} from "../theme/derive.js";
+import type { InteractionVisualState } from "../types/visual-state.js";
+import { ThemedButton } from "./ThemedButton.js";
+
+/** Attention-pulse policy for the trailing halo. */
+export type PrimaryActionAttention = "auto" | "always" | "off";
+
+export interface SubmittedActionConfig {
+  label?: ReactNode;
+  icon?: ReactNode;
+  variant?: ButtonVariant;
+}
+
+export interface PrimaryActionButtonProps extends InteractionVisualState {
+  /**
+   * Override the visual variant. Defaults to `primary` (which maps
+   * to `intent.primary` regardless of the descriptor's `emphasis`
+   * hint — the shell's primary slot is, by definition, primary).
+   */
+  variant?: ButtonVariant;
+  /**
+   * Sizing. Defaults to `lg` so the dock target is comfortable on
+   * touch and visually outranks panel buttons sized `md`.
+   */
+  size?: ButtonSize;
+  /**
+   * Override the label inferred from `descriptor.label`. Use only
+   * when the descriptor's label needs phase-specific copy that the
+   * authoring layer can't express.
+   */
+  label?: ReactNode;
+  /** Client-side draft readiness. Reducer availability remains authoritative. */
+  ready?: boolean;
+  /** Whether the action is currently available according to the caller. */
+  available?: boolean;
+  /** Optional reason rendered as the disabled tooltip. */
+  unavailableReason?: string;
+  /** External submission state. */
+  submitting?: boolean;
+  /** External submitted state. */
+  submitted?: boolean;
+  /** Copy and visual overrides once this interaction has been submitted. */
+  whenSubmitted?: SubmittedActionConfig;
+  /**
+   * Optional leading icon override. When omitted, falls back to
+   * `descriptor.icon` (an emoji glyph from the authoring spec).
+   */
+  icon?: ReactNode;
+  /** Stable identifier for diagnostics and tests. */
+  actionId?: string;
+  /** Called when the controlled action is activated. */
+  onAction?: () => void | Promise<void>;
+  /**
+   * Attention-halo policy. `auto` (default) pulses the halo for one
+   * breath when the button transitions from disabled → enabled (so
+   * the user sees the moment the action becomes available), then
+   * settles into a slow ambient breath while the action remains
+   * available. `always` keeps the breath running unconditionally.
+   * `off` suppresses the halo entirely.
+   *
+   * Ignored when `theme.motion.reducedMotion === "true"`.
+   */
+  attention?: PrimaryActionAttention;
+  /** Additional inline style merged after the resolved button style. */
+  style?: CSSProperties;
+  /** Optional className for downstream styling hooks. */
+  className?: string;
+}
+
+/**
+ * @see PrimaryActionButtonProps
+ */
+export function PrimaryActionButton({
+  variant = "primary",
+  size = "lg",
+  label = "Action",
+  ready = true,
+  available: availableProp = true,
+  unavailableReason,
+  submitting: submittingProp = false,
+  submitted = false,
+  whenSubmitted,
+  icon,
+  actionId,
+  onAction,
+  attention = "auto",
+  style,
+  className,
+}: PrimaryActionButtonProps) {
+  const theme = useTheme();
+  const reducedMotion = theme.motion.reducedMotion === "true";
+  const [pending, setPending] = useState(false);
+
+  const submitting = submittingProp || pending;
+  const available = availableProp && ready && !submitted && !submitting;
+  const resolvedVariant = submitted
+    ? (whenSubmitted?.variant ?? "submitted")
+    : variant;
+  const disabled = !available;
+  const intent = intentForVariant(theme, resolvedVariant);
+
+  // Pulse the halo for one breath when availability flips on. After
+  // the breath we settle into the ambient cadence (or stop, when
+  // `attention` is `off`). Tracking the previous availability lets
+  // us catch the transition without re-mounting the component.
+  const previouslyAvailableRef = useRef(available);
+  const [pulseKey, setPulseKey] = useState(0);
+  useEffect(() => {
+    if (!previouslyAvailableRef.current && available) {
+      setPulseKey((n) => n + 1);
+    }
+    previouslyAvailableRef.current = available;
+  }, [available]);
+
+  const haloEnabled =
+    !reducedMotion && available && attention !== "off" && !submitted;
+
+  const tooltip = available
+    ? undefined
+    : formatUnavailableReason(unavailableReason);
+
+  const resolvedLabel: ReactNode = submitted
+    ? (whenSubmitted?.label ?? label)
+    : label;
+  const resolvedIcon: ReactNode =
+    submitted && whenSubmitted?.icon ? (
+      <span aria-hidden style={{ fontSize: "1.15em" }}>
+        {whenSubmitted.icon}
+      </span>
+    ) : (
+      (icon ?? null)
+    );
+
+  return (
+    <span
+      data-dreamboard-primary-action
+      data-available={available ? "true" : "false"}
+      data-pending={submitting ? "true" : undefined}
+      data-action-state={
+        submitted
+          ? "submitted"
+          : submitting
+            ? "submitting"
+            : available
+              ? "available"
+              : "unavailable"
+      }
+      style={{
+        position: "relative",
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        // The halo overflows the button bounds; the wrapper reserves
+        // a transparent buffer so it doesn't get clipped by the
+        // dock's safe-area frame.
+        padding: theme.space[1],
+      }}
+    >
+      {haloEnabled ? (
+        <>
+          {/*
+            Ambient breath — slow, low-amplitude, runs as long as the
+            action is available. The outer `haloEnabled` already
+            short-circuits when `attention === "off"`, so this layer
+            is gated purely on the availability + reduced-motion
+            checks.
+          */}
+          <motion.span
+            aria-hidden
+            style={{
+              position: "absolute",
+              inset: 0,
+              borderRadius: theme.radius.md,
+              background: intent.soft,
+              opacity: 0.55,
+              pointerEvents: "none",
+            }}
+            animate={{
+              scale: [1, 1.06, 1],
+              opacity: [0.45, 0.18, 0.45],
+            }}
+            transition={{
+              repeat: Infinity,
+              duration: 2.4,
+              ease: "easeInOut",
+            }}
+          />
+          {/*
+            One-shot announce pulse keyed on `pulseKey` — re-mounts
+            (and thus re-runs) every time availability flips on so the
+            eye registers the change. We use a separate layer (rather
+            than retriggering the ambient breath) so the announce is
+            visibly louder than the steady-state cadence.
+          */}
+          <motion.span
+            key={pulseKey}
+            aria-hidden
+            style={{
+              position: "absolute",
+              inset: 0,
+              borderRadius: theme.radius.md,
+              boxShadow: `0 0 0 0 ${intent.solid}`,
+              pointerEvents: "none",
+            }}
+            initial={{ opacity: 0.7 }}
+            animate={{
+              boxShadow: [
+                `0 0 0 0 ${withAlpha(intent.solid, 0.55)}`,
+                `0 0 0 14px ${withAlpha(intent.solid, 0)}`,
+              ],
+              opacity: [0.7, 0],
+            }}
+            transition={{ duration: 0.9, ease: "easeOut" }}
+          />
+        </>
+      ) : null}
+      <ThemedButton
+        type="button"
+        variant={resolvedVariant}
+        size={size}
+        pressed={submitting}
+        className={className}
+        aria-label={
+          typeof resolvedLabel === "string" ? resolvedLabel : "Primary action"
+        }
+        aria-disabled={disabled || undefined}
+        data-interaction-id={actionId}
+        data-emphasis="primary"
+        title={tooltip}
+        disabled={disabled}
+        style={{
+          // Sit above the halo so clicks land on the button.
+          position: "relative",
+          zIndex: 1,
+          boxShadow: disabled || submitted ? undefined : theme.elevation.lifted,
+          ...style,
+        }}
+        onClick={async (event: MouseEvent<HTMLButtonElement>) => {
+          event.preventDefault();
+          if (disabled) return;
+          setPending(true);
+          try {
+            await onAction?.();
+          } finally {
+            setPending(false);
+          }
+        }}
+      >
+        {resolvedIcon}
+        <span>{resolvedLabel}</span>
+      </ThemedButton>
+    </span>
+  );
+}
+
+function formatUnavailableReason(
+  reason: string | undefined,
+): string | undefined {
+  if (reason === "INSUFFICIENT_RESOURCES") {
+    return "Insufficient resources";
+  }
+  return reason;
+}
+
+/**
+ * Add an alpha channel to a CSS colour string. Supports `#rgb`,
+ * `#rrggbb`, and any colour the browser can paint via a fallback to
+ * `color-mix` (modern Safari/Chrome/Firefox all support this; older
+ * runtimes get the original colour without alpha which is still
+ * visible — the halo is decorative).
+ */
+function withAlpha(color: string, alpha: number): string {
+  const trimmed = color.trim();
+  if (trimmed.startsWith("#")) {
+    const hex = trimmed.slice(1);
+    if (hex.length === 3) {
+      // `String.prototype.slice` always returns a string (possibly
+      // empty) — never `undefined` — so duplicating each digit is
+      // safe to feed to `parseInt` without further narrowing.
+      const r = parseInt(hex.slice(0, 1).repeat(2), 16);
+      const g = parseInt(hex.slice(1, 2).repeat(2), 16);
+      const b = parseInt(hex.slice(2, 3).repeat(2), 16);
+      return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+    }
+    if (hex.length === 6) {
+      const r = parseInt(hex.slice(0, 2), 16);
+      const g = parseInt(hex.slice(2, 4), 16);
+      const b = parseInt(hex.slice(4, 6), 16);
+      return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+    }
+  }
+  // Best-effort fallback for non-hex colours (rgb/hsl/named): use
+  // `color-mix` with transparent. Safe to land in inline style — the
+  // halo is purely decorative and will gracefully degrade.
+  return `color-mix(in srgb, ${trimmed} ${Math.round(alpha * 100)}%, transparent)`;
+}

package/src/ui/components/PrimaryButton.tsx

@@ -0,0 +1,45 @@
+/**
+ * Minimally-styled primary action button.
+ *
+ * Visual styling now flows through {@link buttonStyle}: the background,
+ * border, foreground, radius, typography and elevation all derive from
+ * the active {@link useTheme}'s `intent.primary` slot. Override the
+ * variant when a non-primary call site needs a different emphasis (the
+ * underlying `<DefaultInteractionButton>` is the canonical button for
+ * interaction-bound submission).
+ */
+
+import type { ButtonHTMLAttributes } from "react";
+import type { ButtonSize, ButtonVariant } from "../theme/derive.js";
+import type { InteractionVisualState } from "../types/visual-state.js";
+import { ThemedButton } from "./ThemedButton.js";
+
+export interface PrimaryButtonProps
+  extends ButtonHTMLAttributes<HTMLButtonElement>, InteractionVisualState {
+  /** Intent slot — defaults to `primary`. */
+  variant?: ButtonVariant;
+  /** Sizing token — defaults to `md`. */
+  size?: ButtonSize;
+}
+
+export function PrimaryButton({
+  children,
+  disabled,
+  style,
+  variant = "primary",
+  size = "md",
+  ...rest
+}: PrimaryButtonProps) {
+  return (
+    <ThemedButton
+      type="button"
+      disabled={disabled}
+      variant={variant}
+      size={size}
+      style={style}
+      {...rest}
+    >
+      {children}
+    </ThemedButton>
+  );
+}

package/src/ui/components/ResourceCounter.tsx

@@ -0,0 +1,270 @@
+import {
+  createContext,
+  createElement,
+  useContext,
+  useMemo,
+  type ComponentType,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import {
+  composeEventHandlers,
+  renderPrimitive,
+  type PrimitiveCommonProps,
+} from "../primitives/primitive-props.js";
+
+export type ResourceId = string;
+
+export interface ResourceDisplayConfig<Resource extends string = ResourceId> {
+  type: Resource;
+  label: string;
+  icon:
+    | ReactNode
+    | ComponentType<{
+        className?: string;
+        strokeWidth?: number;
+        "aria-hidden"?: boolean | "true" | "false";
+      }>;
+  iconColor?: string;
+  bgColor?: string;
+  textColor?: string;
+}
+
+export interface ResourceCounterItemState<
+  Resource extends string = ResourceId,
+> {
+  type: Resource;
+  label: string;
+  icon: ResourceDisplayConfig<Resource>["icon"];
+  iconColor?: string;
+  bgColor?: string;
+  textColor?: string;
+  count: number;
+  isZero: boolean;
+  interactive: boolean;
+  select: () => void;
+  renderIcon: (props?: ResourceIconProps) => ReactNode;
+  dataAttributes: {
+    "data-resource-id": Resource;
+    "data-resource-count": number;
+    "data-resource-zero": boolean | undefined;
+    "data-interactive": boolean | undefined;
+  };
+}
+
+export interface ResourceIconProps {
+  className?: string;
+  strokeWidth?: number;
+  "aria-hidden"?: boolean | "true" | "false";
+}
+
+export type ResourceCounterRootProps<Resource extends string = ResourceId> =
+  Omit<PrimitiveCommonProps, "children"> &
+    Omit<HTMLAttributes<HTMLElement>, "children"> & {
+      resources: ReadonlyArray<ResourceDisplayConfig<Resource>>;
+      counts: Partial<Record<Resource, number>>;
+      zero?: "show" | "hide";
+      onResourceClick?: (resourceType: Resource) => void;
+      children: ReactNode;
+    };
+
+export type BoundResourceCounterRootProps<
+  Resource extends string = ResourceId,
+> = Omit<ResourceCounterRootProps<Resource>, "resources">;
+
+export type ResourceCounterProps<Resource extends string = ResourceId> =
+  ResourceCounterRootProps<Resource>;
+
+export type ResourceCounterPartProps<Resource extends string = ResourceId> =
+  Omit<PrimitiveCommonProps, "children"> &
+    Omit<HTMLAttributes<HTMLElement>, "children"> & {
+      children?:
+        | ReactNode
+        | ((resource: ResourceCounterItemState<Resource>) => ReactNode);
+    };
+
+const ResourceCounterItemContext =
+  createContext<ResourceCounterItemState<string> | null>(null);
+
+function useResourceCounterItemContext<Resource extends string>() {
+  const value = useContext(ResourceCounterItemContext);
+  if (!value) {
+    throw new Error(
+      "ResourceCounter item primitives must be rendered inside <ResourceCounter.Item>.",
+    );
+  }
+  return value as ResourceCounterItemState<Resource>;
+}
+
+function renderResourceIcon(
+  icon: ResourceDisplayConfig<string>["icon"],
+  props: ResourceIconProps = {},
+) {
+  if (typeof icon === "function") {
+    return createElement(icon, {
+      "aria-hidden": true,
+      strokeWidth: 2.5,
+      ...props,
+    });
+  }
+  const {
+    strokeWidth: _strokeWidth,
+    "aria-hidden": ariaHidden,
+    ...spanProps
+  } = props;
+  return (
+    <span
+      aria-hidden={ariaHidden === undefined ? true : ariaHidden !== "false"}
+      {...spanProps}
+    >
+      {icon}
+    </span>
+  );
+}
+
+function resolveResourceChildren<Resource extends string>(
+  children: ResourceCounterPartProps<Resource>["children"],
+  resource: ResourceCounterItemState<Resource>,
+) {
+  return typeof children === "function" ? children(resource) : children;
+}
+
+export function ResourceCounterRoot<Resource extends string = ResourceId>({
+  resources,
+  counts,
+  zero = "show",
+  onResourceClick,
+  children,
+  "aria-label": ariaLabel,
+  ...props
+}: ResourceCounterRootProps<Resource>) {
+  const items = useMemo(
+    () =>
+      resources
+        .map((resource) => {
+          const count = counts[resource.type] ?? 0;
+          return {
+            ...resource,
+            count,
+            isZero: count === 0,
+            interactive: Boolean(onResourceClick),
+            select: () => onResourceClick?.(resource.type),
+            renderIcon: (iconProps) =>
+              renderResourceIcon(resource.icon, iconProps),
+            dataAttributes: {
+              "data-resource-id": resource.type,
+              "data-resource-count": count,
+              "data-resource-zero": count === 0 || undefined,
+              "data-interactive": onResourceClick ? true : undefined,
+            },
+          } satisfies ResourceCounterItemState<Resource>;
+        })
+        .filter((resource) => zero === "show" || !resource.isZero),
+    [counts, onResourceClick, resources, zero],
+  );
+
+  return renderPrimitive("div", {
+    role: "list",
+    "aria-label": ariaLabel ?? "Resource counts",
+    "data-dreamboard-resource-counter": "",
+    ...props,
+    children: items.map((resource) => (
+      <ResourceCounterItemContext.Provider key={resource.type} value={resource}>
+        {children}
+      </ResourceCounterItemContext.Provider>
+    )),
+  });
+}
+
+export function ResourceCounterItem<Resource extends string = ResourceId>({
+  children,
+  onClick,
+  "aria-label": ariaLabel,
+  ...props
+}: ResourceCounterPartProps<Resource>) {
+  const resource = useResourceCounterItemContext<Resource>();
+  return renderPrimitive("span", {
+    role: "listitem",
+    "aria-label": ariaLabel ?? `${resource.label}: ${resource.count}`,
+    ...resource.dataAttributes,
+    ...props,
+    onClick: composeEventHandlers(
+      onClick,
+      resource.interactive ? resource.select : undefined,
+    ),
+    children: resolveResourceChildren(children, resource),
+  });
+}
+
+export function ResourceCounterIcon<Resource extends string = ResourceId>({
+  className,
+  strokeWidth,
+  "aria-hidden": ariaHidden,
+}: ResourceIconProps): ReactNode {
+  const resource = useResourceCounterItemContext<Resource>();
+  return resource.renderIcon({
+    className,
+    strokeWidth,
+    "aria-hidden": ariaHidden,
+  });
+}
+
+export function ResourceCounterCount<Resource extends string = ResourceId>({
+  children,
+  ...props
+}: ResourceCounterPartProps<Resource>) {
+  const resource = useResourceCounterItemContext<Resource>();
+  return renderPrimitive("span", {
+    ...props,
+    "data-dreamboard-resource-count": "",
+    children: resolveResourceChildren(children ?? resource.count, resource),
+  });
+}
+
+export function ResourceCounterLabel<Resource extends string = ResourceId>({
+  children,
+  ...props
+}: ResourceCounterPartProps<Resource>) {
+  const resource = useResourceCounterItemContext<Resource>();
+  return renderPrimitive("span", {
+    ...props,
+    "data-dreamboard-resource-label": "",
+    children: resolveResourceChildren(children ?? resource.label, resource),
+  });
+}
+
+export interface ResourceCounterComponents<
+  Resource extends string = ResourceId,
+> {
+  Root(props: BoundResourceCounterRootProps<Resource>): ReactElement;
+  Item(props: ResourceCounterPartProps<Resource>): ReactElement;
+  Icon(props: ResourceIconProps): ReactNode;
+  Count(props: ResourceCounterPartProps<Resource>): ReactElement;
+  Label(props: ResourceCounterPartProps<Resource>): ReactElement;
+}
+
+export function createResourceCounter<Resource extends string>(
+  resources: ReadonlyArray<ResourceDisplayConfig<Resource>>,
+): ResourceCounterComponents<Resource> {
+  return {
+    Root(props) {
+      return createElement(ResourceCounterRoot<Resource>, {
+        ...props,
+        resources,
+      });
+    },
+    Item: ResourceCounterItem,
+    Icon: ResourceCounterIcon,
+    Count: ResourceCounterCount,
+    Label: ResourceCounterLabel,
+  } satisfies ResourceCounterComponents<Resource>;
+}
+
+export const ResourceCounter = {
+  Root: ResourceCounterRoot,
+  Item: ResourceCounterItem,
+  Icon: ResourceCounterIcon,
+  Count: ResourceCounterCount,
+  Label: ResourceCounterLabel,
+};