@superxd-studio/adptr 0.5.0

package/source/reusable/web/index.tsx

@@ -0,0 +1,470 @@
+import {
+  useId,
+  useRef,
+  useState,
+  useLayoutEffect,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+import { Label, TextArea, TextField } from "react-aria-components";
+import { Button } from "../../components/button.js";
+import { Callout } from "../../components/callout.js";
+import { Thinking } from "../../components/thinking.js";
+import {
+  IconArrowUp,
+  IconArrowDown,
+  IconSquare,
+  IconEdit,
+  IconRotate,
+} from "../../components/icons.js";
+import { cn } from "../../lib/cn.js";
+import type {
+  ChatActions,
+  ChatController,
+  ChatFile,
+  ChatMessage,
+  ChatSnapshot,
+} from "../core/index.js";
+import { AttachmentList } from "./attachments/index.js";
+export { AttachmentList, AttachmentPicker, useAttachments } from "./attachments/index.js";
+export type { AttachmentListProps, AttachmentPickerProps } from "./attachments/index.js";
+export { attachmentCopy } from "./attachments/copy.js";
+import { chatCopy, type ChatCopy } from "./copy.js";
+import {
+  BranchPicker,
+  CopyButton,
+  MessageEditor,
+  MessageMarkdown,
+  StreamingMessage,
+  messageCopy,
+  type MessageCopy,
+} from "./message/index.js";
+export {
+  BranchPicker,
+  CopyButton,
+  CodeBlock,
+  MessageEditor,
+  MessageMarkdown,
+  StreamingMessage,
+  messageCopy,
+} from "./message/index.js";
+export type {
+  BranchPickerProps,
+  CopyButtonProps,
+  CodeBlockProps,
+  MessageEditorProps,
+  MessageMarkdownProps,
+  MessageCopy,
+} from "./message/index.js";
+export type { ChatCopy } from "./copy.js";
+export type { ChatActions, ChatMessage, ChatSnapshot } from "../core/index.js";
+
+export function useChatController(controller: ChatController): ChatSnapshot {
+  return useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+}
+
+export interface ChatProps {
+  snapshot: ChatSnapshot;
+  actions: ChatActions;
+  copy?: ChatCopy;
+  className?: string;
+  /** Render supplied text using the application's safe Markdown renderer if wanted. */
+  renderMessage?: (message: ChatMessage) => ReactNode;
+  footer?: ReactNode;
+  attachmentPicker?: ReactNode;
+  draftFiles?: readonly ChatFile[];
+  isAttachmentBlocked?: boolean;
+  /** Clear a draft queue only after the state owner accepts the message. */
+  onSent?: () => void;
+  messageCopy?: MessageCopy;
+  writeText?: (text: string) => Promise<void>;
+  /** Opt into the existing bounded conversation height; follows only while at the bottom. */
+  scrollable?: boolean;
+  autoScroll?: boolean;
+  /** Prompts offered in an empty conversation. Choosing one puts it in the message box. */
+  suggestions?: readonly string[];
+  /** Text already in the message box when the conversation first appears. */
+  defaultDraft?: string;
+  /** A user message already open for editing when it first appears (specimens; no focus move). */
+  defaultEditing?: string;
+}
+
+/** A controlled presentation: state comes from the host, not a mandatory provider. */
+export function Chat({
+  snapshot,
+  actions,
+  copy = chatCopy,
+  className,
+  renderMessage,
+  footer,
+  attachmentPicker,
+  draftFiles = [],
+  isAttachmentBlocked = false,
+  onSent,
+  messageCopy: words = messageCopy,
+  writeText,
+  scrollable = false,
+  autoScroll = true,
+  suggestions = [],
+  defaultDraft = "",
+  defaultEditing,
+}: ChatProps) {
+  const [draft, setDraft] = useState(defaultDraft);
+  const [editing, setEditing] = useState<string | undefined>(defaultEditing);
+  // An editor the visitor opens takes focus; one shown as a specimen doesn't
+  const [editFocus, setEditFocus] = useState(false);
+  const root = useRef<HTMLElement>(null);
+  const viewport = useRef<HTMLDivElement>(null);
+  const follow = useRef(autoScroll);
+  const [showLatest, setShowLatest] = useState(false);
+  useLayoutEffect(() => {
+    if (scrollable && autoScroll && follow.current && viewport.current)
+      viewport.current.scrollTop = viewport.current.scrollHeight;
+  }, [snapshot.messages, snapshot.status, scrollable, autoScroll]);
+  const jump = () => {
+    follow.current = true;
+    setShowLatest(false);
+    if (viewport.current) viewport.current.scrollTop = viewport.current.scrollHeight;
+  };
+  const focusComposer = () =>
+    root.current
+      ?.querySelector<HTMLTextAreaElement>("[data-chat-composer] textarea")
+      ?.focus({ preventScroll: true });
+  const closeEdit = () => {
+    setEditing(undefined);
+    window.requestAnimationFrame(focusComposer);
+  };
+  const headingId = useId();
+  const hintId = useId();
+  const running = snapshot.status === "waiting" || snapshot.status === "streaming";
+  const recoverable = ["error", "interrupted", "cancelled"].includes(snapshot.status);
+  const send = () => {
+    if (isAttachmentBlocked || running) return;
+    if (actions.send(draft, draftFiles)) {
+      setDraft("");
+      jump();
+      onSent?.();
+    }
+  };
+  return (
+    <section
+      ref={root}
+      aria-labelledby={headingId}
+      className={cn(
+        "relative flex min-w-0 flex-col gap-6 rounded-surface bg-surface p-4 sm:p-6",
+        scrollable && "h-conversation",
+        className,
+      )}
+    >
+      <h2 id={headingId} className="sr-only">
+        {copy.label}
+      </h2>
+      <div
+        ref={viewport}
+        role={scrollable ? "region" : undefined}
+        // Named after this conversation too, so several on one page stay distinguishable
+        aria-label={scrollable ? `${words.transcript}: ${copy.label}` : undefined}
+        tabIndex={scrollable ? 0 : undefined}
+        onScroll={() => {
+          const el = viewport.current;
+          if (!el) return;
+          const bottom = el.scrollHeight - el.scrollTop - el.clientHeight < 24;
+          follow.current = bottom;
+          setShowLatest(!bottom);
+        }}
+        className={cn(
+          "min-w-0",
+          scrollable &&
+            "min-h-0 flex-1 overflow-x-hidden overflow-y-auto rounded-cell outline-none focus-visible:focus-ring",
+        )}
+      >
+        {snapshot.messages.length ? (
+          <ol className="flex min-w-0 list-none flex-col gap-6 p-0">
+            {snapshot.messages.map((message, index) => (
+              <li
+                key={message.id}
+                aria-label={message.role === "user" ? copy.user : copy.assistant}
+                className="flex min-w-0 flex-col gap-2"
+              >
+                <p className="font-mono type-caption text-fg-subtle">
+                  {message.role === "user" ? copy.user : copy.assistant}
+                </p>
+                {editing === message.id && actions.edit ? (
+                  <MessageEditor
+                    autoFocus={editFocus}
+                    text={message.text}
+                    hasFiles={Boolean(message.files?.length)}
+                    isDisabled={running}
+                    onCancel={closeEdit}
+                    copy={words}
+                    onSave={(text) => {
+                      const accepted = actions.edit?.(message.id, text) ?? false;
+                      if (accepted) {
+                        closeEdit();
+                        jump();
+                      }
+                      return accepted;
+                    }}
+                  />
+                ) : (
+                  <div
+                    className={cn(
+                      "min-w-0 type-body wrap-anywhere whitespace-pre-wrap text-fg-emphasis",
+                      message.role === "user" &&
+                        "self-end rounded-surface bg-surface-muted px-control-md-x py-control-y",
+                    )}
+                  >
+                    {renderMessage ? (
+                      renderMessage(message)
+                    ) : message.role === "assistant" &&
+                      snapshot.status === "streaming" &&
+                      index === snapshot.messages.length - 1 ? (
+                      <StreamingMessage text={message.text} copy={words} writeText={writeText} />
+                    ) : message.role === "assistant" ? (
+                      <MessageMarkdown
+                        text={message.text}
+                        isStreaming={running}
+                        copy={words}
+                        writeText={writeText}
+                      />
+                    ) : (
+                      message.text
+                    )}
+                    {message.role === "assistant" && !message.text && running ? <Thinking /> : null}
+                  </div>
+                )}
+                {message.files?.length ? (
+                  <AttachmentList
+                    items={message.files.map((file) => ({
+                      id: file.id,
+                      name: file.name,
+                      mediaType: file.mediaType,
+                      size: file.size,
+                      status: "ready",
+                      file,
+                    }))}
+                    variant="inline"
+                  />
+                ) : null}
+                {editing !== message.id ? (
+                  <div className="flex min-w-0 flex-wrap items-center gap-1">
+                    {message.role === "assistant" && message.text ? (
+                      <CopyButton
+                        text={message.text}
+                        iconOnly
+                        isDisabled={running}
+                        copy={words}
+                        writeText={writeText}
+                      />
+                    ) : null}
+                    {message.role === "user" && snapshot.capabilities.edit && actions.edit ? (
+                      <Button
+                        size="icon-sm"
+                        variant="ghost"
+                        aria-label={words.edit}
+                        isDisabled={running}
+                        onPress={() => {
+                          setEditFocus(true);
+                          setEditing(message.id);
+                        }}
+                      >
+                        <IconEdit />
+                      </Button>
+                    ) : null}
+                    {message.role === "assistant" &&
+                    snapshot.capabilities.regenerate &&
+                    actions.regenerate ? (
+                      <Button
+                        size="icon-sm"
+                        variant="ghost"
+                        aria-label={words.regenerate}
+                        isDisabled={running}
+                        onPress={() => {
+                          if (actions.regenerate?.(message.id)) {
+                            focusComposer();
+                            jump();
+                          }
+                        }}
+                      >
+                        <IconRotate />
+                      </Button>
+                    ) : null}
+                    {snapshot.capabilities.branches &&
+                    snapshot.branches?.[message.id] &&
+                    actions.selectBranch ? (
+                      <BranchPicker
+                        branch={snapshot.branches[message.id] ?? { index: 0, count: 0 }}
+                        isDisabled={running}
+                        copy={words}
+                        onPrevious={() => {
+                          if (actions.selectBranch?.(message.id, "previous")) focusComposer();
+                        }}
+                        onNext={() => {
+                          if (actions.selectBranch?.(message.id, "next")) focusComposer();
+                        }}
+                      />
+                    ) : null}
+                  </div>
+                ) : null}
+              </li>
+            ))}
+          </ol>
+        ) : (
+          <div className="flex min-h-48 flex-col items-center justify-center gap-2 text-center">
+            <h3 className="type-heading text-fg-emphasis">{copy.emptyTitle}</h3>
+            <p className="max-w-sm type-body text-fg-subtle">{copy.emptyNote}</p>
+            {suggestions.length ? (
+              <div className="mt-3 flex flex-wrap justify-center gap-2">
+                {suggestions.map((prompt) => (
+                  <Button
+                    key={prompt}
+                    size="sm"
+                    isDisabled={!snapshot.capabilities.send}
+                    className="h-auto min-h-control-sm max-w-full py-2 whitespace-normal"
+                    onPress={() => {
+                      setDraft(prompt);
+                      window.requestAnimationFrame(focusComposer);
+                    }}
+                  >
+                    {prompt}
+                  </Button>
+                ))}
+              </div>
+            ) : null}
+          </div>
+        )}
+      </div>
+      {scrollable && showLatest ? (
+        <Button
+          size="sm"
+          className="self-center shadow-control"
+          onPress={() => {
+            jump();
+            focusComposer();
+          }}
+        >
+          <IconArrowDown />
+          {words.latest}
+        </Button>
+      ) : null}
+      {/* The system's voice: mono words, with the done dot when the answer is ready. The thinking
+          mark shows where the answer will appear, not here. */}
+      <p
+        role="status"
+        aria-live="polite"
+        className={cn(
+          "flex items-center gap-2 font-mono type-caption text-fg-subtle",
+          recoverable && "sr-only",
+        )}
+      >
+        {snapshot.status === "complete" ? (
+          <span aria-hidden="true" className="size-1.5 shrink-0 rounded-pill bg-done" />
+        ) : null}
+        {copy[snapshot.status]}
+      </p>
+      {snapshot.capabilities.attachments ? attachmentPicker : null}
+      {recoverable ? (
+        <Callout
+          tone={snapshot.status === "cancelled" ? "neutral" : "attention"}
+          actions={
+            snapshot.capabilities.retry ? (
+              <Button
+                size="sm"
+                onPress={() => {
+                  // The notice and its button go away; keep the visitor in the message box
+                  if (actions.retry()) focusComposer();
+                }}
+              >
+                {copy.retry}
+              </Button>
+            ) : undefined
+          }
+        >
+          {copy[snapshot.status]}
+        </Callout>
+      ) : null}
+      <div
+        data-chat-composer
+        className="conversation-composer min-w-0 rounded-surface border border-line-input bg-surface shadow-control focus-within:border-line-emphasis has-data-focus-visible:border-focus has-data-focus-visible:ring-2 has-data-focus-visible:ring-focus/15"
+      >
+        <TextField
+          value={draft}
+          onChange={setDraft}
+          isDisabled={!snapshot.capabilities.send || Boolean(editing)}
+          className="min-w-0"
+        >
+          <Label className="sr-only">{copy.input}</Label>
+          <TextArea
+            rows={3}
+            maxLength={20_000}
+            aria-describedby={hintId}
+            placeholder={copy.placeholder}
+            className="max-h-48 min-h-24 w-full resize-none rounded-surface bg-transparent px-control-md-x pt-control-y pb-2 type-body text-fg-emphasis outline-none placeholder:text-fg-subtle"
+            onKeyDown={(event) => {
+              if (
+                event.key === "Enter" &&
+                !event.shiftKey &&
+                !event.nativeEvent.isComposing &&
+                !window.matchMedia("(pointer: coarse)").matches
+              ) {
+                event.preventDefault();
+                if (!running && !editing) send();
+              }
+            }}
+          />
+        </TextField>
+        <div className="flex flex-wrap items-center justify-between gap-3 px-3 pb-3">
+          <p id={hintId} className="conversation-key-hint type-caption text-fg-subtle">
+            <span className="conversation-desktop-hint">{copy.hint}</span>
+            <span className="conversation-touch-hint">{copy.touchHint}</span>
+          </p>
+          {running && snapshot.capabilities.cancel ? (
+            <Button
+              size="sm"
+              className="ml-auto"
+              onPress={() => {
+                actions.cancel();
+                focusComposer();
+              }}
+            >
+              <IconSquare />
+              {copy.stop}
+            </Button>
+          ) : (
+            <Button
+              variant="primary"
+              className="ml-auto"
+              size="sm"
+              isDisabled={
+                running ||
+                Boolean(editing) ||
+                isAttachmentBlocked ||
+                (!draft.trim() && !draftFiles.length) ||
+                !snapshot.capabilities.send
+              }
+              onPress={send}
+            >
+              <IconArrowUp />
+              {copy.send}
+            </Button>
+          )}
+        </div>
+      </div>
+      {footer}
+    </section>
+  );
+}
+
+export {
+  DraftReview,
+  ReviewChangeCard,
+  ReviewDecisionPanel,
+  useReview,
+  reviewCopy,
+} from "./review/index.js";
+export type {
+  DraftReviewProps,
+  ReviewChangeCardProps,
+  ReviewDecisionPanelProps,
+  ReviewCopy,
+} from "./review/index.js";

package/source/reusable/web/message/copy.ts

@@ -0,0 +1,26 @@
+export const messageCopy = {
+  copy: "Copy response",
+  copyCode: "Copy code",
+  copying: "Copying",
+  copied: "Copied",
+  copyFailed: "Couldn’t copy. Select the text and copy it instead.",
+  code: "Code",
+  table: "Response table",
+  footnotes: "Notes",
+  back: "Back to the reference",
+  previous: "Previous version",
+  next: "Next version",
+  versions: "Message versions",
+  version: "Version",
+  edit: "Edit your message",
+  editInput: "Edit message",
+  save: "Save and resend",
+  cancel: "Cancel edit",
+  editNote: "Resending creates a new version. The original conversation stays available.",
+  editFailed:
+    "This message couldn’t be resent. Your edit is still here. Try again when the response has stopped.",
+  regenerate: "Regenerate response",
+  latest: "Jump to latest message",
+  transcript: "Conversation messages",
+} as const;
+export type MessageCopy = { [Key in keyof typeof messageCopy]: string };