@springbrand/message-panel 0.1.2 → 0.1.3-alpha.1

package/src/contracts.ts

@@ -0,0 +1,138 @@
+import type { ComponentType, HTMLAttributes, ReactNode } from "react";
+
+export type MessagePanelStatus = "ready" | "submitted" | "streaming" | "error";
+export type MessageRole = "user" | "assistant" | "system" | "tool";
+
+export interface ToolApprovalView {
+  id: string;
+  approved?: boolean;
+}
+
+export type ToolApprovalDecision = "deny" | "allow_once" | "allow_level";
+
+export interface MessageAdapter<TMessage> {
+  getId: (message: TMessage, index: number) => string;
+  getRole: (message: TMessage) => MessageRole;
+  getParts: (message: TMessage) => readonly unknown[];
+  getMetadata?: (message: TMessage) => unknown;
+  getText?: (message: TMessage) => string;
+  isPartRenderable?: (part: unknown) => boolean;
+  /** Extracts provider-specific tool approval state without leaking it into UI code. */
+  getToolApproval?: (part: unknown) => ToolApprovalView | undefined;
+  /**
+   * Marks snapshot-like parts that supersede older parts with the same key.
+   * `update_plan` uses the built-in "plan" key when this is omitted.
+   */
+  getPartPresentationKey?: (part: unknown) => string | undefined;
+}
+
+export interface MessagePanelActions {
+  onCopy?: (text: string) => void | Promise<void>;
+  onRetry?: (messageId: string) => void | Promise<void>;
+  onFork?: (messageId: string) => void | Promise<void>;
+  onNavigate?: (target: string) => void;
+  onPreview?: (artifact: unknown) => void;
+  onDownload?: (artifact: unknown) => void;
+  onAnswer?: (payload: unknown) => void | Promise<void>;
+  onApprove?: (
+    approvalId: string,
+    decision: ToolApprovalDecision,
+  ) => void | Promise<void>;
+  onSuggestion?: (text: string) => void | Promise<void>;
+}
+
+export interface PartRendererContext {
+  messageId: string;
+  partIndex: number;
+  activityId: string;
+  isActive: boolean;
+  isLatestOfKind: boolean;
+  /** First user message after the assistant message that owns this part. */
+  replyText?: string;
+  approval?: ToolApprovalView;
+  status: MessagePanelStatus;
+  actions: MessagePanelActions;
+}
+
+export interface PartRendererProps<TPart = unknown> {
+  part: TPart;
+  context: PartRendererContext;
+}
+
+export type PartRendererComponent<TPart = unknown> = ComponentType<
+  PartRendererProps<TPart>
+>;
+
+export interface PartRendererDefinition {
+  name: string;
+  match: (part: unknown) => boolean;
+  component: PartRendererComponent;
+}
+
+export interface PartRendererRegistry {
+  resolve: (part: unknown) => PartRendererComponent | undefined;
+  names: readonly string[];
+}
+
+export interface MessagePanelSlots {
+  assistantHeader?: ReactNode | ((messageId: string) => ReactNode);
+  empty?: ReactNode;
+  hydrating?: ReactNode;
+  recovering?: ReactNode;
+  background?: ReactNode;
+  error?: ReactNode | ((error?: unknown) => ReactNode);
+  beforeMessages?: ReactNode;
+  afterMessages?: ReactNode;
+}
+
+export interface MessagePanelProps<TMessage>
+  extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+  messages: readonly TMessage[];
+  status: MessagePanelStatus;
+  isHydrating?: boolean;
+  isRecovering?: boolean;
+  isServerStreaming?: boolean;
+  error?: unknown;
+  adapter: MessageAdapter<TMessage>;
+  renderers?: PartRendererRegistry;
+  actions?: MessagePanelActions;
+  slots?: MessagePanelSlots;
+  emptyTitle?: string;
+  emptyDescription?: string;
+}
+
+export type RichPartKind =
+  | "text"
+  | "reasoning"
+  | "tool"
+  | "error"
+  | "image"
+  | "chart"
+  | "agent_card"
+  | "plan"
+  | "schedule"
+  | "parallel"
+  | "subagents"
+  | "confirmation"
+  | "file"
+  | "dashboard"
+  | "ask_user"
+  | "suggestions";
+
+export type MessageToolState =
+  | "input-streaming"
+  | "input-available"
+  | "approval-requested"
+  | "approval-responded"
+  | "output-available"
+  | "output-denied"
+  | "output-error";
+
+export interface AIToolPart {
+  type: string;
+  state: MessageToolState;
+  input?: unknown;
+  output?: unknown;
+  errorText?: string;
+  toolName?: string;
+}

package/src/conversation.tsx

@@ -0,0 +1,76 @@
+import { ArrowDownIcon } from "lucide-react";
+import { forwardRef, useCallback, type ComponentProps, type HTMLAttributes } from "react";
+import { StickToBottom, useStickToBottomContext } from "use-stick-to-bottom";
+import { cn } from "./internal/cn";
+
+export type ConversationProps = ComponentProps<typeof StickToBottom>;
+
+export const Conversation = ({ className, ...props }: ConversationProps) => (
+  <StickToBottom
+    className={cn("sb-conversation", className)}
+    initial="instant"
+    resize="instant"
+    role="log"
+    {...props}
+  />
+);
+
+export type ConversationContentProps = ComponentProps<
+  typeof StickToBottom.Content
+>;
+
+export const ConversationContent = ({
+  className,
+  ...props
+}: ConversationContentProps) => (
+  <StickToBottom.Content
+    className={cn("sb-conversation__content", className)}
+    {...props}
+  />
+);
+
+export interface ConversationEmptyStateProps
+  extends HTMLAttributes<HTMLDivElement> {
+  title?: string;
+  description?: string;
+  icon?: React.ReactNode;
+}
+
+export const ConversationEmptyState = forwardRef<
+  HTMLDivElement,
+  ConversationEmptyStateProps
+>(({ className, title = "开始对话", description, icon, children, ...props }, ref) => (
+  <div ref={ref} className={cn("sb-conversation__empty", className)} {...props}>
+    {children ?? (
+      <>
+        {icon}
+        <strong>{title}</strong>
+        {description && <p>{description}</p>}
+      </>
+    )}
+  </div>
+));
+ConversationEmptyState.displayName = "ConversationEmptyState";
+
+export function ConversationScrollButton({
+  className,
+  ...props
+}: React.ButtonHTMLAttributes<HTMLButtonElement>) {
+  const { isAtBottom, scrollToBottom } = useStickToBottomContext();
+  const handleClick = useCallback(() => {
+    void scrollToBottom({ animation: "smooth" });
+  }, [scrollToBottom]);
+
+  if (isAtBottom) return null;
+  return (
+    <button
+      type="button"
+      className={cn("sb-conversation__scroll", className)}
+      onClick={handleClick}
+      aria-label="回到最新消息"
+      {...props}
+    >
+      <ArrowDownIcon size={16} />
+    </button>
+  );
+}

package/src/internal/cn.ts

@@ -0,0 +1,3 @@
+export function cn(...values: Array<string | false | null | undefined>): string {
+  return values.filter(Boolean).join(" ");
+}

package/src/message-panel.tsx

@@ -0,0 +1,368 @@
+import {
+  forwardRef,
+  useMemo,
+  type ReactNode,
+} from "react";
+import type {
+  MessageAdapter,
+  MessagePanelActions,
+  MessagePanelProps,
+  MessagePanelSlots,
+  MessageRole,
+  PartRendererRegistry,
+} from "./contracts";
+import {
+  Conversation,
+  ConversationContent,
+  ConversationEmptyState,
+  ConversationScrollButton,
+} from "./conversation";
+import { cn } from "./internal/cn";
+import {
+  AssistantMessageActions,
+  BrandMark,
+  Message,
+  MessageContent,
+} from "./message";
+import {
+  DefaultPartRenderer,
+  resolvePartKind,
+  stripNoticePrefix,
+} from "./parts";
+import { PanelStatus, ThinkingIndicator, TopLoadingBar } from "./status";
+
+function roleOf<T>(
+  adapter: MessageAdapter<T>,
+  message: T,
+): MessageRole {
+  return adapter.getRole(message);
+}
+
+function messageText<T>(
+  adapter: MessageAdapter<T>,
+  message: T,
+): string {
+  if (adapter.getText) return adapter.getText(message);
+  return adapter
+    .getParts(message)
+    .map((part) => {
+      if (
+        part != null &&
+        typeof part === "object" &&
+        (part as { type?: unknown }).type === "text"
+      ) {
+        return String((part as { text?: unknown }).text ?? "");
+      }
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function isNotice(metadata: unknown): boolean {
+  if (metadata == null || typeof metadata !== "object") return false;
+  const kind = (metadata as { deliveryKind?: unknown }).deliveryKind;
+  return kind === "notice" || kind === "interim";
+}
+
+function slotValue(
+  slot: MessagePanelSlots["assistantHeader"],
+  messageId: string,
+): ReactNode {
+  return typeof slot === "function" ? slot(messageId) : slot;
+}
+
+function presentationKey<T>(
+  adapter: MessageAdapter<T>,
+  part: unknown,
+): string | undefined {
+  const customKey = adapter.getPartPresentationKey?.(part);
+  if (customKey) return customKey;
+  return resolvePartKind(part) === "plan" ? "plan" : undefined;
+}
+
+interface MessageRowProps<T> {
+  message: T;
+  index: number;
+  messageId: string;
+  isLastAssistant: boolean;
+  isActive: boolean;
+  adapter: MessageAdapter<T>;
+  renderers?: PartRendererRegistry;
+  actions: MessagePanelActions;
+  slots: MessagePanelSlots;
+  status: MessagePanelProps<T>["status"];
+  latestActivityByKind: ReadonlyMap<string, string>;
+  replyText?: string;
+}
+
+function MessageRow<T>({
+  message,
+  messageId,
+  isLastAssistant,
+  isActive,
+  adapter,
+  renderers,
+  actions,
+  slots,
+  status,
+  latestActivityByKind,
+  replyText,
+}: MessageRowProps<T>) {
+  const role = roleOf(adapter, message);
+  const parts = adapter.getParts(message);
+  const visibleParts = adapter.isPartRenderable
+    ? parts.filter(adapter.isPartRenderable)
+    : parts;
+  const metadata = adapter.getMetadata?.(message);
+  const text = messageText(adapter, message);
+
+  if (isNotice(metadata)) {
+    return (
+      <Message from="assistant" data-message-id={messageId}>
+        <div className="sb-notice-line">{stripNoticePrefix(text)}</div>
+      </Message>
+    );
+  }
+
+  if (role === "user") {
+    return (
+      <Message from="user" data-message-id={messageId} data-message-role="user">
+        <MessageContent>
+          {parts.map((part, partIndex) => {
+            const Renderer = renderers?.resolve(part) ?? DefaultPartRenderer;
+            const activityId = `${messageId}:${partIndex}`;
+            const key = presentationKey(adapter, part);
+            return (
+              <Renderer
+                key={activityId}
+                part={part}
+                context={{
+                  messageId,
+                  partIndex,
+                  activityId,
+                  isActive: false,
+                  isLatestOfKind:
+                    key === undefined ||
+                    latestActivityByKind.get(key) === activityId,
+                  approval: adapter.getToolApproval?.(part),
+                  status,
+                  actions,
+                }}
+              />
+            );
+          })}
+        </MessageContent>
+      </Message>
+    );
+  }
+
+  return (
+    <Message
+      from="assistant"
+      data-message-id={messageId}
+      data-message-role="assistant"
+      data-active={isActive ? "true" : undefined}
+    >
+      {slots.assistantHeader && (
+        <div className="sb-assistant-header">
+          {slotValue(slots.assistantHeader, messageId)}
+        </div>
+      )}
+      <MessageContent>
+        {parts.map((part, partIndex) => {
+          const Renderer = renderers?.resolve(part) ?? DefaultPartRenderer;
+          const activityId = `${messageId}:${partIndex}`;
+          const key = presentationKey(adapter, part);
+          return (
+            <Renderer
+              key={activityId}
+              part={part}
+              context={{
+                messageId,
+                partIndex,
+                activityId,
+                isActive,
+                isLatestOfKind:
+                  key === undefined ||
+                  latestActivityByKind.get(key) === activityId,
+                replyText,
+                approval: adapter.getToolApproval?.(part),
+                status,
+                actions,
+              }}
+            />
+          );
+        })}
+        {isActive && visibleParts.length === 0 && <ThinkingIndicator />}
+      </MessageContent>
+      {!isActive && (
+        <AssistantMessageActions
+          text={text}
+          messageId={messageId}
+          canRetry={isLastAssistant && status !== "streaming"}
+          onCopy={actions.onCopy}
+          onRetry={actions.onRetry}
+          onFork={actions.onFork}
+        />
+      )}
+    </Message>
+  );
+}
+
+function MessagePanelInner<T>(
+  {
+    messages,
+    status,
+    isHydrating = false,
+    isRecovering = false,
+    isServerStreaming = false,
+    error,
+    adapter,
+    renderers,
+    actions = {},
+    slots = {},
+    className,
+    emptyTitle = "开始对话",
+    emptyDescription = "发送消息，Agent 会在这里展示思考、工具和产出。",
+    ...props
+  }: MessagePanelProps<T>,
+  ref: React.ForwardedRef<HTMLDivElement>,
+) {
+  const ids = useMemo(
+    () => messages.map((message, index) => adapter.getId(message, index)),
+    [messages, adapter],
+  );
+  const lastAssistantIndex = useMemo(() => {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+      if (roleOf(adapter, messages[index]) === "assistant") return index;
+    }
+    return -1;
+  }, [messages, adapter]);
+  const lastRole =
+    messages.length > 0 ? roleOf(adapter, messages[messages.length - 1]) : undefined;
+  const showPending =
+    status === "submitted" &&
+    (lastRole === "user" || messages.length === 0);
+  const latestActivityByKind = useMemo(() => {
+    const latest = new Map<string, string>();
+    messages.forEach((message, messageIndex) => {
+      if (roleOf(adapter, message) !== "assistant") return;
+      adapter.getParts(message).forEach((part, partIndex) => {
+        const key = presentationKey(adapter, part);
+        if (key) latest.set(key, `${ids[messageIndex]}:${partIndex}`);
+      });
+    });
+    return latest;
+  }, [adapter, ids, messages]);
+  const replyTextByMessageId = useMemo(() => {
+    const replies = new Map<string, string>();
+    messages.forEach((message, messageIndex) => {
+      if (roleOf(adapter, message) !== "assistant") return;
+      for (
+        let replyIndex = messageIndex + 1;
+        replyIndex < messages.length;
+        replyIndex += 1
+      ) {
+        const reply = messages[replyIndex];
+        if (roleOf(adapter, reply) !== "user") continue;
+        const text = messageText(adapter, reply).trim();
+        if (text) replies.set(ids[messageIndex], text);
+        break;
+      }
+    });
+    return replies;
+  }, [adapter, ids, messages]);
+
+  return (
+    <div
+      ref={ref}
+      className={cn("sb-message-panel", className)}
+      data-sb-message-panel=""
+      data-status={status}
+      data-hydrating={isHydrating ? "true" : undefined}
+      aria-busy={status === "submitted" || status === "streaming" || isHydrating}
+      {...props}
+    >
+      <TopLoadingBar status={status} />
+      {isRecovering &&
+        (slots.recovering ?? (
+          <PanelStatus kind="recovering">正在恢复对话流…</PanelStatus>
+        ))}
+      {!isRecovering &&
+        isServerStreaming &&
+        (slots.background ?? (
+          <PanelStatus kind="background">Agent 正在后台更新…</PanelStatus>
+        ))}
+      {status === "error" &&
+        (typeof slots.error === "function"
+          ? slots.error(error)
+          : slots.error ?? (
+              <PanelStatus kind="error">
+                {error instanceof Error ? error.message : "这一轮出错了，请重试。"}
+              </PanelStatus>
+            ))}
+      <Conversation>
+        <ConversationContent>
+          {slots.beforeMessages}
+          {messages.length === 0 &&
+            !isHydrating &&
+            (slots.empty ?? (
+              <ConversationEmptyState
+                title={emptyTitle}
+                description={emptyDescription}
+                icon={<BrandMark className="sb-brand-mark--large" />}
+              />
+            ))}
+          {messages.map((message, index) => (
+            <MessageRow
+              key={ids[index]}
+              message={message}
+              index={index}
+              messageId={ids[index]}
+              isLastAssistant={index === lastAssistantIndex}
+              isActive={
+                status === "streaming" &&
+                index === messages.length - 1 &&
+                roleOf(adapter, message) === "assistant"
+              }
+              adapter={adapter}
+              renderers={renderers}
+              actions={actions}
+              slots={slots}
+              status={status}
+              latestActivityByKind={latestActivityByKind}
+              replyText={replyTextByMessageId.get(ids[index])}
+            />
+          ))}
+          {showPending && (
+            <Message
+              from="assistant"
+              data-message-role="assistant"
+              data-pending="true"
+            >
+              {slots.assistantHeader && (
+                <div className="sb-assistant-header">
+                  {slotValue(slots.assistantHeader, "pending")}
+                </div>
+              )}
+              <ThinkingIndicator />
+            </Message>
+          )}
+          {slots.afterMessages}
+        </ConversationContent>
+        {isHydrating &&
+          (slots.hydrating ?? (
+            <div className="sb-hydrating-overlay">
+              <PanelStatus kind="hydrating">正在恢复历史消息…</PanelStatus>
+            </div>
+          ))}
+        <ConversationScrollButton />
+      </Conversation>
+    </div>
+  );
+}
+
+export const MessagePanel = forwardRef(MessagePanelInner) as <T>(
+  props: MessagePanelProps<T> & { ref?: React.ForwardedRef<HTMLDivElement> },
+) => React.ReactElement;