@dreamboard-games/ui-sdk 0.0.41

package/src/components/surfaces/PanelSurface.tsx

@@ -0,0 +1,458 @@
+import type { CSSProperties, ReactNode } from "react";
+import { useSeatInbox } from "../../hooks/useSeatInbox.js";
+import {
+  useInteractionHandle,
+  type InteractionHandle,
+} from "../../hooks/useInteractionHandle.js";
+import { useTheme } from "../../theme/ThemeProvider.js";
+import type { InteractionDescriptor } from "../../types/plugin-state.js";
+import { DefaultInteractionButton } from "./internal/DefaultInteractionButton.js";
+import { MoreActions } from "../MoreActions.js";
+import type {
+  InteractionDefaultedKeysOf,
+  InteractionParamsByKeyShape,
+  InteractionParamsOf,
+  SurfaceRenderMap,
+} from "./types.js";
+
+/**
+ * Resolved salience tier for a panel interaction. Authors set
+ * `descriptor.salience` directly; when omitted we derive a sensible
+ * default from `descriptor.emphasis` so existing workspaces inherit
+ * the new ordering / disclosure behaviour without being touched.
+ *
+ * - `descriptor.salience === "hero"` → `hero`
+ * - `descriptor.salience === "tertiary"` → `tertiary`
+ * - `descriptor.emphasis === "primary"` → `hero`
+ * - `descriptor.emphasis === "destructive"` → `tertiary`
+ * - everything else → `secondary` (the default tier)
+ */
+export type PanelSalience = "hero" | "secondary" | "tertiary";
+
+export interface PanelSurfaceProps<
+  I extends string = never,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+> {
+  /**
+   * Optional per-interaction overrides. Omit entirely to use the default
+   * renderer (`DefaultInteractionButton`) for every interaction; supply a
+   * partial map to replace the default UI for specific interaction ids.
+   */
+  render?: SurfaceRenderMap<I, ParamsByKey>;
+  /**
+   * Fallback renderer for interactions without a `render` entry. Defaults
+   * to the built-in `DefaultInteractionButton` which honours metadata
+   * (`icon`, `label`, `emphasis`, `unavailableReason`).
+   */
+  renderItem?: (
+    descriptor: InteractionDescriptor<I>,
+    handle: InteractionHandle<
+      InteractionParamsOf<ParamsByKey, I>,
+      InteractionDefaultedKeysOf<ParamsByKey, I>
+    >,
+  ) => ReactNode;
+  /** Shown when no panel interactions are available. */
+  empty?: ReactNode;
+  /**
+   * Optional grouping function. Defaults to `descriptor.group`; authors
+   * can override to cluster interactions differently. Returning
+   * `undefined` keeps the interaction in the ungrouped tail cluster.
+   */
+  groupBy?: (descriptor: InteractionDescriptor<I>) => string | undefined;
+  /**
+   * Override the default salience derivation. Receives the descriptor
+   * and returns the tier it should occupy. Use to demote something the
+   * authoring layer mis-tagged as `emphasis: "primary"` without
+   * changing the upstream contract.
+   */
+  salienceFor?: (descriptor: InteractionDescriptor<I>) => PanelSalience;
+  /**
+   * Maximum number of `secondary`-tier items to render directly in the
+   * panel. Excess secondaries spill into the {@link MoreActions}
+   * disclosure (alongside the always-disclosed `tertiary` tier).
+   * Defaults to `Infinity` — secondaries stay visible. Lower this on
+   * dense HUDs to fight Hick's Law.
+   *
+   * Hero items are never spilled, so a panel with three hero entries
+   * and `maxVisibleSecondary: 0` still renders three buttons inline
+   * plus the disclosure.
+   */
+  maxVisibleSecondary?: number;
+  /**
+   * Label for the disclosure toggle. Defaults to `"More"`. Pass a
+   * workspace-specific copy ("Advanced", "Manage", …) when the
+   * generic label feels wrong.
+   */
+  moreActionsLabel?: string;
+  /** Interaction keys intentionally rendered elsewhere, such as auto primary actions. */
+  excludeInteractionKeys?: readonly string[];
+  /**
+   * Render unavailable interactions as disabled items. Defaults to false so
+   * stale-step actions do not compete with legal actions.
+   */
+  showUnavailable?: boolean;
+  /**
+   * Layout overrides for the default container. Useful for tightly
+   * constrained mobile layouts. When the caller supplies their own
+   * `render` for every interaction they can ignore these entirely.
+   */
+  layout?: {
+    direction?: "row" | "column";
+    wrap?: boolean;
+    gap?: CSSProperties["gap"];
+    align?: CSSProperties["alignItems"];
+    justify?: CSSProperties["justifyContent"];
+  };
+}
+
+const SALIENCE_RANK: Record<PanelSalience, number> = {
+  hero: 0,
+  secondary: 1,
+  tertiary: 2,
+};
+
+/**
+ * Default salience resolver — see {@link PanelSalience}. Exported so
+ * authors who want to slightly tweak the policy can compose with it
+ * (`salienceFor: (d) => d.id === "x" ? "hero" : defaultPanelSalience(d)`).
+ */
+export function defaultPanelSalience(
+  _descriptor: InteractionDescriptor,
+): PanelSalience {
+  return "secondary";
+}
+
+// `align: "flex-start"` is deliberate. Panel items are heterogeneous —
+// a `DefaultInteractionButton` sits next to authored cards that can
+// expand into multi-row draft forms (e.g. an offer-trade card). With
+// `stretch` the short buttons get dragged to the tallest sibling's
+// height and render as floor-to-ceiling bars next to the expanded form.
+// Authors who *do* want uniform heights can opt in via `layout.align`.
+const defaultLayout: Required<
+  NonNullable<PanelSurfaceProps<string>["layout"]>
+> = {
+  direction: "row",
+  wrap: true,
+  gap: "8px",
+  align: "flex-start",
+  justify: "flex-start",
+};
+
+/**
+ * Default renderer for `surface: "panel"` interactions.
+ *
+ * Visual styling comes entirely from the active {@link useTheme}; mount
+ * `<ThemeProvider theme={...}/>` to swap the look. Per-interaction overrides
+ * via `render` are the escape hatch when a specific interaction needs bespoke
+ * UI.
+ *
+ * Salience policy
+ * ===============
+ * Each descriptor is assigned a {@link PanelSalience} via
+ * {@link defaultPanelSalience} (override with the `salienceFor` prop).
+ * The panel sorts groups so `hero` items render first, then
+ * `secondary`, then `tertiary` — and the `tertiary` cluster (plus any
+ * spill from `maxVisibleSecondary`) lives behind a {@link MoreActions}
+ * disclosure so a crowded panel doesn't drown the player in choices
+ * (Hick's Law). Groups stay contiguous: a group inherits the highest
+ * salience among its members so a hero+secondary cluster doesn't get
+ * split across the disclosure boundary.
+ */
+export function PanelSurface<
+  I extends string = never,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({
+  render,
+  renderItem,
+  empty = null,
+  groupBy = () => undefined,
+  salienceFor,
+  maxVisibleSecondary = Number.POSITIVE_INFINITY,
+  moreActionsLabel,
+  excludeInteractionKeys,
+  showUnavailable = false,
+  layout,
+}: PanelSurfaceProps<I, ParamsByKey>) {
+  const inbox = useSeatInbox();
+  const excluded = new Set(excludeInteractionKeys ?? []);
+  const items = (
+    (inbox.bySurface.panel ?? []) as ReadonlyArray<InteractionDescriptor<I>>
+  ).filter(
+    (descriptor) =>
+      !excluded.has(descriptor.interactionKey) &&
+      (showUnavailable || descriptor.available),
+  );
+  if (items.length === 0) return <>{empty}</>;
+
+  const resolvedLayout = { ...defaultLayout, ...(layout ?? {}) };
+  const resolveSalience: (
+    descriptor: InteractionDescriptor<I>,
+  ) => PanelSalience = salienceFor ?? defaultPanelSalience;
+
+  // Compute groups first (preserves authored cohesion), then assign
+  // each group a tier from its highest-salience member, then sort by
+  // tier while keeping members in their original order.
+  const grouped = groupInteractions<I>(items, groupBy, resolveSalience);
+  const sorted = [...grouped].sort((a, b) => {
+    const tierDiff = SALIENCE_RANK[a.tier] - SALIENCE_RANK[b.tier];
+    if (tierDiff !== 0) return tierDiff;
+    // Same tier — preserve authored order via the cached index.
+    return a.firstIndex - b.firstIndex;
+  });
+
+  // Decide which groups stay in the main row vs. spill into the
+  // disclosure. Hero groups always stay; tertiary groups always
+  // spill; secondary groups spill once we've already shown
+  // `maxVisibleSecondary` of them. A group counts as 1 toward the
+  // budget regardless of how many descriptors it contains — losing
+  // half a "build" cluster would be more confusing than rendering
+  // the whole sub-row.
+  const visible: typeof sorted = [];
+  const disclosed: typeof sorted = [];
+  let secondariesShown = 0;
+  for (const group of sorted) {
+    if (group.tier === "hero") {
+      visible.push(group);
+      continue;
+    }
+    if (group.tier === "tertiary") {
+      disclosed.push(group);
+      continue;
+    }
+    if (secondariesShown < maxVisibleSecondary) {
+      visible.push(group);
+      secondariesShown += 1;
+    } else {
+      disclosed.push(group);
+    }
+  }
+
+  // Count the underlying descriptors so the disclosure badge reads
+  // "More (3)" not "More (1 group)".
+  const disclosedCount = disclosed.reduce(
+    (sum, group) => sum + group.interactions.length,
+    0,
+  );
+
+  return (
+    <div
+      role="toolbar"
+      aria-label="Panel actions"
+      data-shell-slot="panel-actions"
+      style={{
+        display: "flex",
+        flexDirection: resolvedLayout.direction,
+        flexWrap: resolvedLayout.wrap ? "wrap" : "nowrap",
+        gap: resolvedLayout.gap,
+        alignItems: resolvedLayout.align,
+        justifyContent: resolvedLayout.justify,
+      }}
+    >
+      {visible.map((group) => (
+        <PanelGroup<I, ParamsByKey>
+          key={group.id}
+          group={group}
+          render={render}
+          renderItem={renderItem}
+        />
+      ))}
+      {disclosed.length > 0 ? (
+        <MoreActions label={moreActionsLabel} count={disclosedCount}>
+          {disclosed.map((group) => (
+            <PanelGroup<I, ParamsByKey>
+              key={group.id}
+              group={group}
+              render={render}
+              renderItem={renderItem}
+            />
+          ))}
+        </MoreActions>
+      ) : null}
+    </div>
+  );
+}
+
+interface PanelGroupDescriptor<I extends string> {
+  readonly id: string;
+  readonly interactions: ReadonlyArray<InteractionDescriptor<I>>;
+  readonly grouped: boolean;
+  readonly tier: PanelSalience;
+  /** Original index of the first member, used to preserve authored
+   * order when sort keys tie. */
+  readonly firstIndex: number;
+}
+
+function groupInteractions<I extends string>(
+  items: ReadonlyArray<InteractionDescriptor<I>>,
+  groupBy: (descriptor: InteractionDescriptor<I>) => string | undefined,
+  resolveSalience: (descriptor: InteractionDescriptor<I>) => PanelSalience,
+): Array<PanelGroupDescriptor<I>> {
+  // Two-pass build so each group's tier reflects its highest-salience
+  // member regardless of arrival order. Pass 1 collects buckets while
+  // preserving the order in which each *cluster* first appears (for
+  // the eventual `firstIndex` tie-break). Pass 2 freezes the buckets
+  // into the immutable shape `PanelGroupDescriptor` advertises.
+  interface MutableBucket {
+    id: string;
+    grouped: boolean;
+    interactions: Array<InteractionDescriptor<I>>;
+    tier: PanelSalience;
+    firstIndex: number;
+  }
+  const ordered: MutableBucket[] = [];
+  const byGroup = new Map<string, MutableBucket>();
+
+  items.forEach((descriptor, index) => {
+    const tier = resolveSalience(descriptor);
+    const key = groupBy(descriptor);
+    if (key === undefined) {
+      ordered.push({
+        id: `solo:${descriptor.interactionId}`,
+        grouped: false,
+        interactions: [descriptor],
+        tier,
+        firstIndex: index,
+      });
+      return;
+    }
+    const bucket = byGroup.get(key);
+    if (bucket) {
+      bucket.interactions.push(descriptor);
+      if (SALIENCE_RANK[tier] < SALIENCE_RANK[bucket.tier]) {
+        bucket.tier = tier;
+      }
+      return;
+    }
+    const fresh: MutableBucket = {
+      id: `group:${key}`,
+      grouped: true,
+      interactions: [descriptor],
+      tier,
+      firstIndex: index,
+    };
+    byGroup.set(key, fresh);
+    ordered.push(fresh);
+  });
+
+  return ordered.map((bucket) => ({
+    id: bucket.id,
+    interactions: bucket.interactions,
+    grouped: bucket.grouped,
+    tier: bucket.tier,
+    firstIndex: bucket.firstIndex,
+  }));
+}
+
+function PanelGroup<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({
+  group,
+  render,
+  renderItem,
+}: {
+  group: PanelGroupDescriptor<I>;
+  render?: SurfaceRenderMap<I, ParamsByKey>;
+  renderItem?: (
+    descriptor: InteractionDescriptor<I>,
+    handle: InteractionHandle<
+      InteractionParamsOf<ParamsByKey, I>,
+      InteractionDefaultedKeysOf<ParamsByKey, I>
+    >,
+  ) => ReactNode;
+}) {
+  const theme = useTheme();
+  if (!group.grouped || group.interactions.length === 1) {
+    return (
+      <>
+        {group.interactions.map((descriptor) => (
+          <PanelItem<I, ParamsByKey>
+            key={descriptor.interactionKey}
+            descriptor={descriptor}
+            render={render}
+            renderItem={renderItem}
+            tier={group.tier}
+          />
+        ))}
+      </>
+    );
+  }
+  return (
+    <div
+      data-panel-group={group.id}
+      data-panel-tier={group.tier}
+      style={{
+        display: "inline-flex",
+        gap: theme.space[1],
+        padding: theme.space[1],
+        borderRadius: theme.radius.lg,
+        background: theme.semantic.surface.inset,
+      }}
+    >
+      {group.interactions.map((descriptor) => (
+        <PanelItem<I, ParamsByKey>
+          key={descriptor.interactionKey}
+          descriptor={descriptor}
+          render={render}
+          renderItem={renderItem}
+          compact
+          tier={group.tier}
+        />
+      ))}
+    </div>
+  );
+}
+
+function PanelItem<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({
+  descriptor,
+  render,
+  renderItem,
+  compact,
+  tier,
+}: {
+  descriptor: InteractionDescriptor<I>;
+  render?: SurfaceRenderMap<I, ParamsByKey>;
+  renderItem?: (
+    descriptor: InteractionDescriptor<I>,
+    handle: InteractionHandle<
+      InteractionParamsOf<ParamsByKey, I>,
+      InteractionDefaultedKeysOf<ParamsByKey, I>
+    >,
+  ) => ReactNode;
+  compact?: boolean;
+  tier: PanelSalience;
+}) {
+  const handle = useInteractionHandle<
+    InteractionParamsOf<ParamsByKey, I>,
+    InteractionDefaultedKeysOf<ParamsByKey, I>
+  >(descriptor);
+  const override = render?.[descriptor.interactionKey] as
+    | ((
+        descriptor: InteractionDescriptor<I>,
+        handle: InteractionHandle<
+          InteractionParamsOf<ParamsByKey, I>,
+          InteractionDefaultedKeysOf<ParamsByKey, I>
+        >,
+      ) => ReactNode)
+    | undefined;
+  if (override) return <>{override(descriptor, handle)}</>;
+  if (renderItem) return <>{renderItem(descriptor, handle)}</>;
+  // Salience-driven sizing: hero buttons use the `lg` size so they
+  // outweigh the `secondary` tier next to them. Tertiary items render
+  // inside the disclosure where the smaller `sm` size keeps the
+  // disclosed cluster from feeling like a second main panel.
+  const size: "sm" | "md" | "lg" =
+    compact || tier === "tertiary" ? "sm" : tier === "hero" ? "lg" : "md";
+  return (
+    <DefaultInteractionButton
+      descriptor={descriptor}
+      handle={handle}
+      compact={compact}
+      size={size}
+      data-panel-tier={tier}
+    />
+  );
+}