@dreamboard-games/sdk 0.2.1-alpha.0 → 0.3.0-alpha.1

package/src/ui/components/PrimaryActionButton.tsx

@@ -1,336 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-/**
- * 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

@@ -1,270 +0,0 @@
-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,
-};