@dreamboard-games/ui-sdk 0.0.41

package/src/components/surfaces/InboxSurface.tsx

@@ -0,0 +1,245 @@
+import { useState, type ReactNode } from "react";
+import { useSeatInbox } from "../../hooks/useSeatInbox.js";
+import {
+  useInteractionHandle,
+  type InteractionHandle,
+} from "../../hooks/useInteractionHandle.js";
+import { surfaceStyle } from "../../theme/derive.js";
+import { useTheme } from "../../theme/ThemeProvider.js";
+import type {
+  InteractionContextOption,
+  InteractionDescriptor,
+} from "../../types/plugin-state.js";
+import { interactionInputKeys } from "../../utils/interaction-inputs.js";
+import { interactionLabel } from "../../utils/interaction-labels.js";
+import { DefaultInteractionButton } from "./internal/DefaultInteractionButton.js";
+import { ThemedButton } from "../ThemedButton.js";
+import type {
+  InteractionDefaultedKeysOf,
+  InteractionParamsByKeyShape,
+  InteractionParamsOf,
+  SurfaceRenderMap,
+} from "./types.js";
+
+export interface InboxSurfaceProps<
+  I extends string = never,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+> {
+  /**
+   * Optional per-interaction overrides. Most prompt-kind interactions do not
+   * need this: if the authored spec declares `options`, the default renderer
+   * draws one button per option and auto-submits on click. Provide a
+   * renderer here to fully replace the default UI for a specific prompt id.
+   */
+  render?: SurfaceRenderMap<I, ParamsByKey>;
+  /**
+   * Fallback renderer for inbox items without an entry in `render`. Called
+   * whenever the default option-button layout doesn't fit — e.g., when a
+   * prompt has no `context.options`. Defaults to the standard
+   * `DefaultInteractionButton` which surfaces `label`, `icon`, `emphasis`,
+   * and `unavailableReason`.
+   */
+  renderItem?: (
+    descriptor: InteractionDescriptor<I>,
+    handle: InteractionHandle<
+      InteractionParamsOf<ParamsByKey, I>,
+      InteractionDefaultedKeysOf<ParamsByKey, I>
+    >,
+  ) => ReactNode;
+  /** Shown when no inbox items are addressed to the controlling seat. */
+  empty?: ReactNode;
+  /** Interaction keys intentionally rendered elsewhere, such as dialog groups. */
+  excludeInteractionKeys?: readonly string[];
+}
+
+/**
+ * Default renderer for `surface: "inbox"` interactions and prompt-kind
+ * interactions addressed to the controlling seat.
+ *
+ * Prompt-kind interactions with an authored `options` list are rendered
+ * as a titled group of buttons; clicking a button submits the
+ * interaction with `{ [firstInputKey]: option.id }`. Action-kind inbox
+ * items fall back to the default button. Provide `render` to override
+ * rendering for a specific interaction id.
+ *
+ * Visual styling is sourced entirely from the active {@link useTheme}
+ * — there is no per-call style override.
+ */
+export function InboxSurface<
+  I extends string = never,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({
+  render,
+  renderItem,
+  empty = null,
+  excludeInteractionKeys,
+}: InboxSurfaceProps<I, ParamsByKey>) {
+  const inbox = useSeatInbox();
+  const excluded = new Set(excludeInteractionKeys ?? []);
+  // Prompt-kind descriptors always carry `surface: "inbox"` (enforced by
+  // the trusted bundle), so `bySurface.inbox` is the unified list of
+  // inbox interactions regardless of origin. Rendering off this single
+  // bucket keeps action-kind and prompt-kind inbox items on equal
+  // footing — the old "prompts first, action-kind fallback" branch
+  // silently dropped action-kind items whenever any prompt was active.
+  const items = (inbox.bySurface.inbox ?? []) as ReadonlyArray<
+    InteractionDescriptor<I>
+  >;
+  const visibleItems = items.filter(
+    (descriptor) => !excluded.has(descriptor.interactionKey),
+  );
+  if (visibleItems.length === 0) return <>{empty}</>;
+  return (
+    <>
+      {visibleItems.map((descriptor) => (
+        <InboxItem<I, ParamsByKey>
+          key={descriptor.interactionKey}
+          descriptor={descriptor}
+          render={render}
+          renderItem={renderItem}
+        />
+      ))}
+    </>
+  );
+}
+
+function InboxItem<
+  I extends string,
+  ParamsByKey extends Partial<InteractionParamsByKeyShape> = {},
+>({
+  descriptor,
+  render,
+  renderItem,
+}: {
+  descriptor: InteractionDescriptor<I>;
+  render?: SurfaceRenderMap<I, ParamsByKey>;
+  renderItem?: (
+    descriptor: InteractionDescriptor<I>,
+    handle: InteractionHandle<
+      InteractionParamsOf<ParamsByKey, I>,
+      InteractionDefaultedKeysOf<ParamsByKey, I>
+    >,
+  ) => ReactNode;
+}) {
+  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)}</>;
+
+  const options = descriptor.context?.options;
+  if (descriptor.kind === "prompt" && options && options.length > 0) {
+    return (
+      <PromptOptionsCard
+        descriptor={descriptor}
+        handle={handle}
+        options={options}
+      />
+    );
+  }
+
+  if (renderItem) return <>{renderItem(descriptor, handle)}</>;
+  return <DefaultInteractionButton descriptor={descriptor} handle={handle} />;
+}
+
+function PromptOptionsCard<
+  I extends string,
+  Params extends Record<string, unknown> = Record<string, unknown>,
+>({
+  descriptor,
+  handle,
+  options,
+}: {
+  descriptor: InteractionDescriptor<I>;
+  handle: InteractionHandle<Params>;
+  options: readonly InteractionContextOption[];
+}) {
+  const theme = useTheme();
+  const [pendingOptionId, setPendingOptionId] = useState<string | null>(null);
+  // Option submission flows into the interaction's single declared input key
+  // by convention. Authors who need multi-input prompts should provide a
+  // custom renderer via `render` rather than relying on this default layout.
+  const inputKey = interactionInputKeys(descriptor)[0];
+  const title = descriptor.context?.title ?? interactionLabel(descriptor);
+
+  const containerStyle = {
+    ...surfaceStyle(theme, { tone: "card" }),
+    display: "flex",
+    flexDirection: "column" as const,
+    gap: theme.space[3],
+    padding: theme.space[4],
+  };
+
+  return (
+    <div
+      role="group"
+      aria-label={title}
+      data-interaction-id={descriptor.interactionId}
+      data-surface="inbox"
+      style={containerStyle}
+    >
+      <div
+        style={{
+          fontFamily: theme.typography.fontFamily.display,
+          fontSize: theme.typography.fontSize.lg,
+          fontWeight: theme.typography.fontWeight.bold,
+          color: theme.semantic.text.primary,
+          lineHeight: theme.typography.lineHeight.tight,
+        }}
+      >
+        {title}
+      </div>
+      <div
+        style={{
+          display: "flex",
+          flexDirection: "row",
+          flexWrap: "wrap",
+          gap: theme.space[2],
+        }}
+      >
+        {options.map((option) => {
+          const isPending = pendingOptionId === option.id;
+          const disabled =
+            isPending || !descriptor.available || inputKey === undefined;
+          return (
+            <ThemedButton
+              key={option.id}
+              type="button"
+              variant="secondary"
+              size="md"
+              pressed={isPending}
+              data-option-id={option.id}
+              disabled={disabled}
+              aria-label={option.label ?? option.id}
+              onClick={async (event) => {
+                event.preventDefault();
+                if (disabled || !inputKey) return;
+                setPendingOptionId(option.id);
+                try {
+                  await handle.submit({ [inputKey]: option.id } as Params);
+                } catch {
+                  // Submission errors flow through the runtime's
+                  // notification channel; we swallow here so the option
+                  // buttons re-enable on failure.
+                } finally {
+                  setPendingOptionId(null);
+                }
+              }}
+            >
+              {option.label ?? option.id}
+            </ThemedButton>
+          );
+        })}
+      </div>
+    </div>
+  );
+}