@superxd-studio/adptr 0.5.0

package/source/reusable/web/message/index.tsx

@@ -0,0 +1,388 @@
+import { Children, isValidElement, useEffect, useId, useMemo, useRef, useState } from "react";
+import Markdown, { type Components } from "react-markdown";
+import remarkGfm from "remark-gfm";
+import { Link, Label, TextArea, TextField } from "react-aria-components";
+import { Button } from "../../../components/button.js";
+import {
+  IconCheck,
+  IconCopy,
+  IconChevronLeft,
+  IconChevronRight,
+} from "../../../components/icons.js";
+import { cn } from "../../../lib/cn.js";
+import type { ChatBranch } from "../../core/index.js";
+import { messageCopy, type MessageCopy } from "./copy.js";
+import { rehypeStreamingTail } from "./streaming.js";
+export { messageCopy } from "./copy.js";
+export type { MessageCopy } from "./copy.js";
+
+export interface CopyButtonProps {
+  text: string;
+  label?: string;
+  iconOnly?: boolean;
+  isDisabled?: boolean;
+  copy?: MessageCopy;
+  /** Consumer-owned clipboard I/O. Rejections never report success. */
+  writeText?: (text: string) => Promise<void>;
+}
+export function CopyButton({
+  text,
+  label,
+  iconOnly = false,
+  isDisabled,
+  copy = messageCopy,
+  writeText,
+}: CopyButtonProps) {
+  const [result, setResult] = useState<{
+    text: string;
+    phase: "idle" | "pending" | "copied" | "error";
+  }>({ text, phase: "idle" });
+  const generation = useRef(0);
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const phase = result.text === text ? result.phase : "idle";
+  useEffect(
+    () => () => {
+      ++generation.current;
+      clearTimeout(timer.current);
+    },
+    [text],
+  );
+  const onCopy = async () => {
+    const token = ++generation.current;
+    clearTimeout(timer.current);
+    setResult({ text, phase: "pending" });
+    try {
+      if (writeText) await writeText(text);
+      else {
+        if (!navigator.clipboard) throw new Error("Clipboard unavailable");
+        await navigator.clipboard.writeText(text);
+      }
+      if (token !== generation.current) return;
+      setResult({ text, phase: "copied" });
+      timer.current = setTimeout(() => {
+        if (token === generation.current) setResult({ text, phase: "idle" });
+      }, 2500);
+    } catch {
+      if (token === generation.current) setResult({ text, phase: "error" });
+    }
+  };
+  const word =
+    phase === "copied" ? copy.copied : phase === "pending" ? copy.copying : (label ?? copy.copy);
+  return (
+    <div className="flex min-w-0 flex-wrap items-center gap-2">
+      <Button
+        variant="ghost"
+        size={iconOnly ? "icon-sm" : "sm"}
+        aria-label={word}
+        isDisabled={isDisabled || !text || phase === "pending"}
+        onPress={onCopy}
+      >
+        {phase === "copied" ? <IconCheck /> : <IconCopy />}
+        {!iconOnly ? word : null}
+      </Button>
+      <span
+        role="status"
+        aria-live="polite"
+        className={phase === "error" ? "type-caption text-fg-subtle" : "sr-only"}
+      >
+        {phase === "error" ? copy.copyFailed : phase === "copied" ? copy.copied : ""}
+      </span>
+    </div>
+  );
+}
+export interface CodeBlockProps extends Pick<CopyButtonProps, "writeText" | "copy"> {
+  code: string;
+  language?: string;
+  className?: string;
+  isStreaming?: boolean;
+}
+/** Code is readable/copyable text, never executed or embedded. */
+export function CodeBlock({
+  code,
+  language,
+  className,
+  isStreaming,
+  writeText,
+  copy = messageCopy,
+}: CodeBlockProps) {
+  const title = language?.trim().slice(0, 50) || copy.code;
+  return (
+    <div
+      className={cn(
+        "reusable-code min-w-0 overflow-hidden rounded-control border border-line-subtle bg-surface-muted",
+        className,
+      )}
+    >
+      <div className="flex flex-wrap items-center justify-between gap-2 border-b border-line-subtle px-4 py-2">
+        <span className="font-mono type-caption text-fg-subtle">{title}</span>
+        <CopyButton
+          text={code}
+          label={copy.copyCode}
+          isDisabled={isStreaming}
+          writeText={writeText}
+          copy={copy}
+        />
+      </div>
+      <pre
+        tabIndex={0}
+        role="group"
+        aria-label={`${copy.code}: ${title}`}
+        className="m-0 max-w-full overflow-x-auto rounded-cell px-4 py-control-y font-mono type-caption text-fg-emphasis outline-none focus-visible:focus-ring"
+      >
+        <code>{code}</code>
+      </pre>
+    </div>
+  );
+}
+export function safeMarkdownUrl(url: string): string {
+  if (
+    /^[#]/.test(url) ||
+    (/^\/(?!\/)/.test(url) &&
+      !url.includes("\\") &&
+      !Array.from(url).some((char) => char.charCodeAt(0) <= 32))
+  )
+    return url;
+  try {
+    const parsed = new URL(url);
+    if (
+      (["https:", "http:"].includes(parsed.protocol) && !parsed.username && !parsed.password) ||
+      parsed.protocol === "mailto:"
+    )
+      return url;
+  } catch {
+    /* Untrusted or incomplete streaming URL stays plain text. */
+  }
+  return "";
+}
+export interface MessageMarkdownProps extends Pick<
+  CodeBlockProps,
+  "copy" | "writeText" | "isStreaming"
+> {
+  text: string;
+  className?: string;
+  /** The answer is arriving now: tint the newest words and show the cursor. */
+  streamingTail?: boolean;
+}
+/** Established CommonMark/GFM parser, without raw HTML, remote images or executable previews. */
+export function MessageMarkdown({
+  text,
+  className,
+  copy = messageCopy,
+  writeText,
+  isStreaming,
+  streamingTail = false,
+}: MessageMarkdownProps) {
+  const prefix = useId().replace(/[^\w-]/g, "");
+  // Stable renderers preserve code-copy feedback when the host scrolls or rerenders.
+  const components = useMemo<Components>(
+    () => ({
+      a: ({ href, children, id, ...props }) =>
+        href ? (
+          <Link
+            href={href}
+            id={id}
+            aria-label={props["aria-label"]}
+            aria-describedby={
+              props["aria-describedby"] === "footnote-label"
+                ? `sxd-${prefix}-notes`
+                : props["aria-describedby"]
+            }
+            className="rounded-cell text-fg-emphasis underline decoration-line-emphasis underline-offset-4 outline-none data-focus-visible:focus-ring"
+          >
+            {children}
+          </Link>
+        ) : (
+          <span>{children}</span>
+        ),
+      img: ({ alt }) => <span>{alt}</span>,
+      h2: ({ id, children, className }) => (
+        <h2 id={id === "footnote-label" ? `sxd-${prefix}-notes` : id} className={className}>
+          {children}
+        </h2>
+      ),
+      pre: ({ children }) => {
+        const child = Children.toArray(children).find(isValidElement);
+        const props = child?.props as { children?: string; className?: string } | undefined;
+        return (
+          <CodeBlock
+            code={String(props?.children ?? "").replace(/\n$/, "")}
+            language={props?.className?.replace(/^language-/, "")}
+            copy={copy}
+            writeText={writeText}
+            isStreaming={isStreaming}
+          />
+        );
+      },
+      table: ({ children }) => (
+        <div
+          role="group"
+          tabIndex={0}
+          aria-label={copy.table}
+          className="max-w-full overflow-x-auto rounded-control border border-line-subtle outline-none focus-visible:focus-ring"
+        >
+          <table className="w-full border-collapse type-caption">{children}</table>
+        </div>
+      ),
+    }),
+    [copy, prefix, writeText, isStreaming],
+  );
+  return (
+    <div
+      className={cn(
+        "conversation-markdown reusable-markdown min-w-0 type-body whitespace-normal text-fg-emphasis",
+        className,
+      )}
+    >
+      <Markdown
+        skipHtml
+        remarkPlugins={[remarkGfm]}
+        rehypePlugins={streamingTail ? [rehypeStreamingTail] : []}
+        urlTransform={safeMarkdownUrl}
+        remarkRehypeOptions={{
+          clobberPrefix: `sxd-${prefix}-`,
+          footnoteLabel: copy.footnotes,
+          footnoteBackLabel: copy.back,
+        }}
+        components={components}
+      >
+        {text}
+      </Markdown>
+    </div>
+  );
+}
+/**
+ * A streaming answer, like assistant-ui's streaming text: the newest words arrive tinted in
+ * the info colour and fade back to plain text as more arrive; the cursor follows the
+ * last word. When the stream ends, it's ordinary text.
+ */
+export function StreamingMessage(
+  props: Omit<MessageMarkdownProps, "isStreaming" | "streamingTail">,
+) {
+  return <MessageMarkdown {...props} isStreaming streamingTail />;
+}
+
+export interface BranchPickerProps {
+  branch: ChatBranch;
+  isDisabled?: boolean;
+  onPrevious?: () => void;
+  onNext?: () => void;
+  copy?: MessageCopy;
+}
+export function BranchPicker({
+  branch,
+  isDisabled,
+  onPrevious,
+  onNext,
+  copy = messageCopy,
+}: BranchPickerProps) {
+  if (branch.count < 2) return null;
+  return (
+    <div role="group" aria-label={copy.versions} className="flex items-center gap-1">
+      {onPrevious ? (
+        <Button
+          size="icon-sm"
+          variant="ghost"
+          aria-label={copy.previous}
+          isDisabled={isDisabled || branch.index < 1}
+          onPress={onPrevious}
+        >
+          <IconChevronLeft />
+        </Button>
+      ) : null}
+      <span
+        aria-label={`${copy.version} ${branch.index + 1} / ${branch.count}`}
+        className="font-mono type-caption text-fg-subtle numeric"
+      >
+        {branch.index + 1} / {branch.count}
+      </span>
+      {onNext ? (
+        <Button
+          size="icon-sm"
+          variant="ghost"
+          aria-label={copy.next}
+          isDisabled={isDisabled || branch.index >= branch.count - 1}
+          onPress={onNext}
+        >
+          <IconChevronRight />
+        </Button>
+      ) : null}
+    </div>
+  );
+}
+export interface MessageEditorProps {
+  text: string;
+  /** Enable only for an editor opened by the visitor. Specimens do not move focus. */
+  autoFocus?: boolean;
+  hasFiles?: boolean;
+  isDisabled?: boolean;
+  onSave: (text: string) => boolean;
+  onCancel: () => void;
+  copy?: MessageCopy;
+}
+export function MessageEditor({
+  text,
+  autoFocus = false,
+  hasFiles,
+  isDisabled,
+  onSave,
+  onCancel,
+  copy = messageCopy,
+}: MessageEditorProps) {
+  const [draft, setDraft] = useState(text);
+  const [failed, setFailed] = useState(false);
+  const input = useRef<HTMLTextAreaElement>(null);
+  const hint = useId();
+  useEffect(() => {
+    if (autoFocus) input.current?.focus({ preventScroll: true });
+  }, [autoFocus]);
+  const save = () => {
+    if (!onSave(draft)) setFailed(true);
+  };
+  return (
+    <div className="flex w-full min-w-0 flex-col gap-3 rounded-surface border border-line-input bg-surface p-4 shadow-control">
+      <TextField
+        value={draft}
+        onChange={(value) => {
+          setDraft(value);
+          setFailed(false);
+        }}
+        isDisabled={isDisabled}
+      >
+        <Label className="sr-only">{copy.editInput}</Label>
+        <TextArea
+          ref={input}
+          rows={3}
+          maxLength={20_000}
+          aria-describedby={hint}
+          onKeyDown={(event) => {
+            if (event.key === "Escape" && !event.nativeEvent.isComposing) {
+              event.preventDefault();
+              event.stopPropagation();
+              onCancel();
+            }
+          }}
+          className="max-h-48 min-h-24 w-full resize-y rounded-control border border-line-input bg-surface px-control-md-x py-control-y type-body text-fg-emphasis outline-none focus-visible:focus-ring"
+        />
+      </TextField>
+      <p id={hint} className="type-caption text-fg-subtle">
+        {copy.editNote}
+      </p>
+      <p role="status" className={failed ? "type-caption text-error" : "sr-only"}>
+        {failed ? copy.editFailed : ""}
+      </p>
+      <div className="flex flex-wrap justify-end gap-2">
+        <Button size="sm" onPress={onCancel}>
+          {copy.cancel}
+        </Button>
+        <Button
+          size="sm"
+          variant="primary"
+          isDisabled={isDisabled || draft === text || (!draft.trim() && !hasFiles)}
+          onPress={save}
+        >
+          {copy.save}
+        </Button>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,64 @@
+/* The few syntax-tree shapes this needs, described here so the source recipes need no extra
+   package. They match react-markdown's HTML tree (hast). */
+interface Text {
+  type: "text";
+  value: string;
+}
+interface Element {
+  type: "element";
+  tagName: string;
+  properties: Record<string, unknown>;
+  children: Node[];
+}
+type Node = Text | Element | { type: string; children?: Node[] };
+interface Root {
+  type: "root";
+  children: Node[];
+}
+
+/** Inside these, text is left exactly as written (code is never split into words). */
+const SKIP = new Set(["code", "pre"]);
+
+/**
+ * For an answer that is still arriving: wraps each word so the newest ones can be tinted, and
+ * puts the cursor after the last word. The tint fades back to plain text (see library.css) as
+ * newer words arrive. Modelled on assistant-ui's streaming text.
+ */
+export function rehypeStreamingTail({ fresh = 2 }: { fresh?: number } = {}) {
+  return (tree: Root) => {
+    const words: Element[] = [];
+    const wrap = (node: Root | Element) => {
+      node.children = node.children.flatMap((child): Node[] => {
+        if (child.type === "element") {
+          const element = child as Element;
+          if (!SKIP.has(element.tagName)) wrap(element);
+          return [element];
+        }
+        if (child.type !== "text") return [child];
+        return (child as Text).value
+          .split(/(\s+)/)
+          .filter(Boolean)
+          .map((part): Text | Element => {
+            if (/^\s+$/.test(part)) return { type: "text", value: part };
+            const word: Element = {
+              type: "element",
+              tagName: "span",
+              properties: { className: ["stream-word"] },
+              children: [{ type: "text", value: part }],
+            };
+            words.push(word);
+            return word;
+          });
+      });
+    };
+    wrap(tree);
+    for (const word of words.slice(-fresh))
+      (word.properties.className as string[]).push("stream-word--fresh");
+    words.at(-1)?.children.push({
+      type: "element",
+      tagName: "span",
+      properties: { className: ["stream-caret"], ariaHidden: "true" },
+      children: [],
+    });
+  };
+}

package/source/reusable/web/message/styles.css

@@ -0,0 +1,21 @@
+/* Rich responses reuse the approved conversation's geometry and semantic tokens. */
+.reusable-markdown .reusable-code pre {
+  border: 0;
+  border-radius: 0;
+}
+.reusable-markdown .reusable-code pre code {
+  padding: 0;
+}
+.reusable-markdown table :is(th, td) {
+  padding: calc(var(--spacing) * 3);
+  border-bottom: 1px solid var(--color-line-subtle);
+  text-align: start;
+  vertical-align: top;
+}
+.reusable-markdown table th {
+  background: var(--color-surface-muted);
+  font-weight: var(--heading-weight);
+}
+.reusable-markdown table tr:last-child td {
+  border-bottom: 0;
+}

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

@@ -0,0 +1,78 @@
+export const reviewCopy = {
+  proposed: "Proposed changes",
+  before: "Current",
+  after: "Proposed",
+  reason: "Why this change",
+  applied: "Applied",
+  unchanged: "Unchanged",
+  viewChange: (title: string) => `View change: ${title}`,
+  selectChange: (title: string) => `Select change: ${title}`,
+  selected: (n: number, total: number) => `${n} of ${total} selected`,
+  review: (n: number) => `Review ${n} change${n === 1 ? "" : "s"}`,
+  apply: (n: number) => `Apply ${n} change${n === 1 ? "" : "s"}`,
+  complete: (n: number) => `${n} change${n === 1 ? "" : "s"} applied`,
+  kept: (n: number) => `${n} change${n === 1 ? "" : "s"} left unchanged.`,
+  confirm: "Confirm your decision",
+  summary: "Your selection",
+  target: "Apply to",
+  applying: "Applying",
+  checking: "Checking status",
+  noSelection: "Choose the changes you want to keep.",
+  approvalNote: "Only these changes will be applied. The rest stay as they are.",
+  deny: "Decline all",
+  declineRemaining: "Decline remaining",
+  declineRemainingTitle: "Decline the remaining changes?",
+  declineRemainingNote: "Applied changes are kept. The remaining changes will stay as they were.",
+  denyConfirm: "Decline these changes?",
+  denyAction: "Decline changes",
+  denyNote: "The current draft will stay as it is.",
+  denied: "Changes declined",
+  deniedNote: "The draft is unchanged.",
+  back: "Back to review",
+  retry: "Try again",
+  check: "Check status",
+  reload: "Review latest draft",
+  loading: "Preparing your review",
+  loadingNote: "The proposed changes are being loaded.",
+  loadError: "The review couldn’t be loaded.",
+  loadErrorNote: "Try again to see the proposed changes.",
+  uncertain: "Let’s check what happened.",
+  uncertainNote:
+    "Your decision may have reached the server. Check its status before trying again. Your choices are kept.",
+  notApplied: "No changes recorded yet.",
+  notAppliedNote: "Your choices are kept. You can check again or confirm the same decision.",
+  conflict: "The draft has changed.",
+  conflictNote:
+    "Nothing from this decision was applied. Review the latest draft before deciding again.",
+  blocked: "You can view this review.",
+  blockedNote: "You don’t have permission to apply or decline these changes.",
+  partial: (applied: number, left: number) => `${applied} applied · ${left} still to review`,
+  partialNote:
+    "The applied changes are kept. Review the remaining changes before trying them again.",
+  empty: "No changes to review",
+  emptyNote: "The current draft is unchanged.",
+  unavailable: "Review not available",
+  announcement: {
+    ready: "Changes ready to review.",
+    confirming: "Decision ready to confirm.",
+    submitting: "Applying your decision.",
+    checking: "Checking your decision’s status.",
+    partial: "Some changes were applied. Review the remaining changes.",
+    complete: "Selected changes applied.",
+    denied: "Changes declined. The draft is unchanged.",
+    conflict: "The draft changed. Review it again.",
+    blocked: "You do not have permission to decide.",
+    uncertain: "Check status before retrying your decision.",
+    "load-error": "The review could not be loaded.",
+    loading: "Preparing your review.",
+    idle: "",
+  },
+} as const;
+type CustomWords<T> = {
+  [K in keyof T]: T[K] extends string
+    ? string
+    : T[K] extends (...args: infer A) => string
+      ? (...args: A) => string
+      : CustomWords<T[K]>;
+};
+export type ReviewCopy = CustomWords<typeof reviewCopy>;

package/source/reusable/web/review/flow.ts

@@ -0,0 +1,24 @@
+import { flowDirection, type FlowType } from "../../../components/flow-motion.js";
+import type { ReviewStatus } from "../../review/types.js";
+
+/** Where each status sits in the review, so a change can be tagged forward or back. */
+const STEP: Record<ReviewStatus, number> = {
+  idle: 0,
+  loading: 0,
+  "load-error": 0,
+  ready: 1,
+  partial: 1,
+  conflict: 1,
+  blocked: 1,
+  confirming: 2,
+  submitting: 2,
+  checking: 2,
+  uncertain: 2,
+  complete: 3,
+  denied: 3,
+};
+/** Steps worth moving to. Problems and in-between states change in place, without movement. */
+const MOVES_TO = new Set<ReviewStatus>(["ready", "confirming", "complete", "denied"]);
+export function reviewFlow(from: ReviewStatus, to: ReviewStatus): FlowType | null {
+  return MOVES_TO.has(to) ? flowDirection(STEP[from], STEP[to]) : null;
+}