@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/chat/DigichatLauncher.tsx

@@ -0,0 +1,361 @@
+"use client";
+
+/**
+ * DigichatLauncher — the reusable corner entry point for embedded digichat.
+ *
+ * Idle is a 30px square carrying the canonical compact terminal mark. Hover or
+ * keyboard focus types `digichat` one character at a time without changing the
+ * control's height or border. Opening replaces that square in place with a chat
+ * panel that expands in two steps from the same corner: first sideways into a
+ * composer-height bar, then upward to full height. The transparent backdrop,
+ * header close button, and Escape key all dismiss it, reversing both steps.
+ *
+ * The launcher portals to document.body by default so a backdrop-filter or
+ * transformed app shell cannot trap its fixed positioning. Reference specimens
+ * can set `portal={false}` to contain it inside a positioned stage.
+ *
+ * Import `@digithings-ai/ui/styles/digichat-launcher.css` once in the app shell.
+ */
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+
+import { TerminalMark } from "../symbols/terminal-marks";
+import { DigichatWordmark } from "./DigichatWordmark";
+import { DotMatrix } from "./DotMatrix";
+
+const WORDMARK = "digichat";
+const TYPE_MS = 48;
+/** Must match the close animation in styles/digichat-launcher.css. */
+const CLOSE_MS = 340;
+
+const subscribeToClient = () => () => {};
+const getClientSnapshot = () => true;
+const getServerSnapshot = () => false;
+
+/**
+ * Test a keydown against a `mod+k` / `ctrl+shift+d` style hotkey.
+ *
+ * `mod` means "ctrl or meta" so one deployment string works on both macOS and
+ * Windows/Linux; naming `ctrl` or `meta` explicitly pins that one. Every
+ * modifier not named must be absent, so `k` alone never fires on `mod+k`. A
+ * malformed string (empty token, e.g. `k+` or `mod++k`) matches nothing rather
+ * than silently degrading to the bare key.
+ */
+export function matchesHotkey(event: KeyboardEvent, hotkey: string): boolean {
+  const parts = hotkey.split("+");
+  if (parts.some((part) => part.trim() === "")) return false;
+  const tokens = parts.map((token) => token.trim().toLowerCase());
+  if (tokens.length === 0) return false;
+  const key = tokens[tokens.length - 1];
+  const mods = new Set(tokens.slice(0, -1));
+  const needsCtrl = mods.has("ctrl");
+  const needsMeta = mods.has("meta") || mods.has("cmd");
+  const needsMod = mods.has("mod");
+  const needsAlt = mods.has("alt") || mods.has("option");
+  const needsShift = mods.has("shift");
+
+  if (needsCtrl && !event.ctrlKey) return false;
+  if (needsMeta && !event.metaKey) return false;
+  // `mod` is exactly one of ctrl/meta — both held is not the shortcut.
+  if (needsMod && event.ctrlKey === event.metaKey) return false;
+  if (!needsCtrl && !needsMod && event.ctrlKey) return false;
+  if (!needsMeta && !needsMod && event.metaKey) return false;
+  if (needsAlt !== event.altKey) return false;
+  if (needsShift !== event.shiftKey) return false;
+  return event.key.toLowerCase() === key;
+}
+
+export type DigichatLauncherProps = {
+  /** Embedded chat surface, usually the digichat iframe. */
+  children: ReactNode;
+  /** Header label inside the expanded panel. */
+  title?: ReactNode;
+  /** Accessible name for the expanded panel. */
+  ariaLabel?: string;
+  /** Render into document.body (default) or inside the current container. */
+  portal?: boolean;
+  /**
+   * Keyboard shortcut that opens the panel while it is closed, e.g. `mod+k`.
+   * See `matchesHotkey` for the accepted syntax.
+   */
+  hotkey?: string;
+  /** Start open for demos or controlled previews. */
+  defaultOpen?: boolean;
+  /** Called after opening or after the close animation completes. */
+  onOpenChange?: (open: boolean) => void;
+  className?: string;
+  /** Optional CSS custom properties such as panel dimensions or offsets. */
+  style?: CSSProperties;
+  /** Reset the in-process thread. Rendered only when a caller wires it (e.g. the gallery specimen). */
+  onNewChat?: () => void;
+};
+
+export function DigichatLauncher({
+  children,
+  title = "digichat",
+  ariaLabel = "digichat",
+  portal = true,
+  hotkey,
+  defaultOpen = false,
+  onOpenChange,
+  className,
+  style,
+  onNewChat,
+}: DigichatLauncherProps) {
+  /* A portal cannot render on the server. useSyncExternalStore supplies a
+     hydration-safe client signal without a mount effect whose sole purpose is
+     a synchronous state update. */
+  const mounted = useSyncExternalStore(
+    subscribeToClient,
+    getClientSnapshot,
+    getServerSnapshot,
+  );
+  const [open, setOpen] = useState(defaultOpen);
+  const [closing, setClosing] = useState(false);
+  const [hasOpened, setHasOpened] = useState(defaultOpen);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const typedRef = useRef<HTMLSpanElement>(null);
+  const typingTimerRef = useRef<number | null>(null);
+  const closeTimerRef = useRef<number | null>(null);
+  /* Focus is restored to the trigger on close for keyboard users, but a
+     pointer-driven close should leave a bare square rather than a typed
+     wordmark — `:focus-visible` is too unreliable here to decide that. */
+  const skipFocusTypeRef = useRef(false);
+  const pendingReturnRef = useRef<{ type: boolean } | null>(null);
+
+  const stopTyping = () => {
+    if (typingTimerRef.current !== null) {
+      window.clearTimeout(typingTimerRef.current);
+      typingTimerRef.current = null;
+    }
+  };
+
+  const resetTrigger = () => {
+    stopTyping();
+    const trigger = triggerRef.current;
+    if (!trigger) return;
+    trigger.removeAttribute("data-typing");
+    if (typedRef.current) typedRef.current.textContent = "d";
+  };
+
+  const typeWordmark = () => {
+    if (open || closing) return;
+    stopTyping();
+    const trigger = triggerRef.current;
+    const typed = typedRef.current;
+    if (!trigger || !typed) return;
+
+    trigger.setAttribute("data-typing", "");
+    typed.textContent = "d";
+    let length = 1;
+
+    const reveal = () => {
+      length += 1;
+      typed.textContent = WORDMARK.slice(0, length);
+      if (length < WORDMARK.length) {
+        typingTimerRef.current = window.setTimeout(reveal, TYPE_MS);
+      } else {
+        typingTimerRef.current = null;
+      }
+    };
+
+    typingTimerRef.current = window.setTimeout(reveal, TYPE_MS);
+  };
+
+  const openPanel = () => {
+    stopTyping();
+    setHasOpened(true);
+    setOpen(true);
+    onOpenChange?.(true);
+  };
+
+  const closePanel = useCallback(
+    (options?: { typeOnReturn?: boolean }) => {
+      if (!open || closing) return;
+      pendingReturnRef.current = { type: options?.typeOnReturn === true };
+      if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) {
+        setOpen(false);
+        onOpenChange?.(false);
+        return;
+      }
+      setClosing(true);
+      closeTimerRef.current = window.setTimeout(() => {
+        setOpen(false);
+        setClosing(false);
+        onOpenChange?.(false);
+      }, CLOSE_MS);
+    },
+    [closing, onOpenChange, open],
+  );
+
+  /* Focus restoration rides the trigger's own ref callback: it is the one
+     moment the node is guaranteed to exist, and focusing an already-focused
+     node fires no event, so the typing decision is made here rather than in
+     the focus handler. */
+  const attachTrigger = (node: HTMLButtonElement | null) => {
+    triggerRef.current = node;
+    if (!node) return;
+    const pending = pendingReturnRef.current;
+    if (!pending) return;
+    pendingReturnRef.current = null;
+    skipFocusTypeRef.current = true;
+    node.focus();
+    if (pending.type) {
+      skipFocusTypeRef.current = false;
+      typeWordmark();
+      return;
+    }
+    /* React may dispatch the focus this call produced after the current task,
+       so hold the suppression until that has been delivered, then clear any
+       typing it started. */
+    window.requestAnimationFrame(() => {
+      skipFocusTypeRef.current = false;
+      resetTrigger();
+    });
+  };
+
+  useEffect(() => {
+    if (!open) return;
+    const focusFrame = window.requestAnimationFrame(() => closeRef.current?.focus());
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") closePanel({ typeOnReturn: true });
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => {
+      window.cancelAnimationFrame(focusFrame);
+      window.removeEventListener("keydown", onKeyDown);
+    };
+  }, [closePanel, open]);
+
+  /* The hotkey only opens: once the panel is up, Escape and the backdrop own
+     dismissal, so a shortcut cannot toggle the surface out from under a user
+     mid-message. `openPanelRef` keeps the listener stable across renders. */
+  const openPanelRef = useRef(openPanel);
+  // eslint-disable-next-line react-hooks/refs -- useLatest for the hotkey listener
+  openPanelRef.current = openPanel;
+
+  useEffect(() => {
+    if (!hotkey || open || closing) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (!matchesHotkey(event, hotkey)) return;
+      event.preventDefault();
+      openPanelRef.current();
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [closing, hotkey, open]);
+
+  useEffect(
+    () => () => {
+      stopTyping();
+      if (closeTimerRef.current !== null) {
+        window.clearTimeout(closeTimerRef.current);
+      }
+    },
+    [],
+  );
+
+  const retainPanel = open || closing || hasOpened;
+  const launcher = (
+    <div
+      className={[
+        "digichat-launcher",
+        portal ? "" : "digichat-launcher--contained",
+        className ?? "",
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      style={style}
+    >
+      {open ? (
+        <button
+          type="button"
+          className="digichat-launcher__backdrop"
+          aria-label="Close digichat"
+          tabIndex={-1}
+          onClick={() => closePanel()}
+        />
+      ) : null}
+      {retainPanel ? (
+        <section
+          className={[
+            "digichat-launcher__panel",
+            closing ? "is-closing" : "",
+            !open && !closing ? "is-hidden" : "",
+          ]
+            .filter(Boolean)
+            .join(" ")}
+          role="dialog"
+          aria-label={ariaLabel}
+        >
+          <header className="digichat-launcher__header">
+            <span>{title === "digichat" ? <DigichatWordmark /> : title}</span>
+            <div className="digichat-launcher__header-actions">
+              {onNewChat ? (
+                <button
+                  type="button"
+                  className="digichat-launcher__new"
+                  aria-label="New chat"
+                  data-tooltip="New chat"
+                  onClick={onNewChat}
+                >
+                  <DotMatrix state="newChat" decorative className="size-3.5" />
+                </button>
+              ) : null}
+              <button
+                ref={closeRef}
+                type="button"
+                className="digichat-launcher__close"
+                aria-label="Close digichat"
+                onClick={() => closePanel()}
+              >
+                <DotMatrix state="remove" decorative className="size-3.5" />
+              </button>
+            </div>
+          </header>
+          <div className="digichat-launcher__body">{children}</div>
+        </section>
+      ) : null}
+      {!open && !closing ? (
+        <button
+          ref={attachTrigger}
+          type="button"
+          className="digichat-launcher__trigger"
+          aria-label="Open digichat"
+          aria-expanded="false"
+          onMouseEnter={typeWordmark}
+          onMouseLeave={resetTrigger}
+          onFocus={() => {
+            if (skipFocusTypeRef.current) return;
+            typeWordmark();
+          }}
+          onBlur={resetTrigger}
+          onClick={openPanel}
+        >
+          <TerminalMark
+            variant="compact"
+            size={20}
+            className="digichat-launcher__mark"
+          />
+          <span className="digichat-launcher__word" aria-hidden="true">
+            <span ref={typedRef}>d</span>
+            <span className="digichat-launcher__cursor" />
+          </span>
+        </button>
+      ) : null}
+    </div>
+  );
+
+  if (!portal) return launcher;
+  if (!mounted) return null;
+  return createPortal(launcher, document.body);
+}

package/src/components/chat/DigichatThread.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+/**
+ * First-party digichat Thread — the gallery `/chatbot` Thread module
+ * (`gallery-thread/thread.aui.tsx` + slots + chatbot.css), not a parallel
+ * ChatMarkdown / ChatThinking / ChatToolCall tree.
+ */
+import type { FormEvent, ReactNode } from "react";
+
+import {
+  Thread,
+  type ComposerLayout,
+  type GroupDisclosureMode,
+  type ThreadComponents,
+  type ThreadGroupPart,
+  type ThreadProps,
+  type ThreadSlashTrigger,
+  type ThreadMentionTrigger,
+} from "./gallery-thread/thread.aui";
+import type { WorkVisibility } from "./stock/skin-types";
+import type { ScrollMode } from "./gallery-thread/scroll-mode";
+
+export type DigichatThreadProps = {
+  welcome?: string;
+  /** Subparagraphs under the headline. Deploy `chrome.welcome.body`. */
+  welcomeBody?: readonly string[];
+  /** Welcome-state example prompts. Deploy `chrome.suggestions`. */
+  suggestions?: readonly string[];
+  placeholder?: string;
+  className?: string;
+  /** Embed send-gate / system page-context attach. Form onSubmit. */
+  onComposerSubmit?: (event: FormEvent<HTMLFormElement>) => void;
+  composerLayout?: ComposerLayout;
+  components?: ThreadComponents;
+  /** Native `/` trigger popover (`unstable_useSlashCommandAdapter`). */
+  slash?: ThreadSlashTrigger;
+  /** Native `@` mention popover for catalog tools. */
+  mention?: ThreadMentionTrigger;
+  /** Attachment names whose chips render nowhere (file part still reaches the model). */
+  hiddenAttachmentNames?: readonly string[];
+  /** Deploy `reasoning` disclosure mode. Defaults to `collapsed`. */
+  reasoningMode?: GroupDisclosureMode;
+  /** Deploy `toolCalls` disclosure mode. Defaults to `collapsed`. */
+  toolCallsMode?: GroupDisclosureMode;
+  /** How much of the agent's work the user sees: quiet | balanced | verbose. */
+  workVisibility?: WorkVisibility;
+  /** Row rendered inside the composer border, under the input. */
+  composerToolbar?: ReactNode;
+  /** `always` reserves a scrollbar gutter; `auto` shows bars only on scroll. */
+  scrollbars?: "always" | "auto";
+  /** Worked-chain rhythm. `default` is the fixed spacing. */
+  density?: "compact" | "default" | "airy";
+  /** `follow` chases the stream; `free` never moves the viewport. */
+  scrollMode?: ScrollMode;
+  /**
+   * Private session: the work surfaces that carry user data — reasoning text
+   * and tool-call JSON — do not mount at all, and the composer shows the mode
+   * badge. Display-only; see packages/ui/ARCHITECTURE.md.
+   */
+  privateMode?: boolean;
+};
+
+export function DigichatThread({
+  welcome = "What should we inspect?",
+  welcomeBody = [],
+  suggestions,
+  placeholder = "Ask digichat…",
+  className,
+  onComposerSubmit,
+  composerLayout,
+  components,
+  slash,
+  mention,
+  hiddenAttachmentNames,
+  reasoningMode,
+  toolCallsMode,
+  workVisibility,
+  composerToolbar,
+  scrollbars,
+  density = "default",
+  scrollMode,
+  privateMode,
+}: DigichatThreadProps) {
+  return (
+    <Thread
+      welcome={welcome}
+      welcomeBody={welcomeBody}
+      suggestions={suggestions}
+      placeholder={placeholder}
+      className={className}
+      onComposerSubmit={onComposerSubmit}
+      composerLayout={composerLayout}
+      components={components}
+      slash={slash}
+      mention={mention}
+      hiddenAttachmentNames={hiddenAttachmentNames}
+      reasoningMode={reasoningMode}
+      toolCallsMode={toolCallsMode}
+      workVisibility={workVisibility}
+      composerToolbar={composerToolbar}
+      scrollbars={scrollbars}
+      density={density}
+      scrollMode={scrollMode}
+      privateMode={privateMode}
+    />
+  );
+}
+
+export {
+  Thread,
+  type ComposerLayout,
+  type GroupDisclosureMode,
+  type ThreadComponents,
+  type ThreadGroupPart,
+  type ThreadProps,
+  type ThreadSlashTrigger,
+  type ThreadMentionTrigger,
+};

package/src/components/chat/DigichatThreadList.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+/**
+ * DigichatThreadList — terminal-nav conversation list (not a ChatGPT history
+ * rail). Wraps ThreadListPrimitive so gallery mocks and product memory
+ * persistence share one dress.
+ */
+import {
+  ThreadListItemPrimitive,
+  ThreadListPrimitive,
+} from "@assistant-ui/react";
+
+import { digichatSurfaces } from "./chat-surfaces";
+import { DigichatWordmark } from "./DigichatWordmark";
+import { DotMatrix } from "./DotMatrix";
+
+export type DigichatThreadListProps = {
+  className?: string;
+  /**
+   * Landmark the list renders as. The standalone sidebar is page-level
+   * complementary content (`aside`); embedded in a page section (e.g. the
+   * digiquant landing chat band) it is a thread navigator inside `<main>`,
+   * where a complementary landmark is a violation — pass `"nav"`.
+   */
+  landmark?: "aside" | "nav";
+};
+
+export function DigichatThreadList({ className, landmark = "aside" }: DigichatThreadListProps) {
+  const cls = [digichatSurfaces.list, className ?? ""].filter(Boolean).join(" ");
+  const Tag = landmark;
+  return (
+    <Tag className={cls} data-memory-thread-list aria-label="Conversations">
+      <div className="flex h-8 shrink-0 items-center justify-between gap-2 border-b border-term-hair px-[0.7rem]">
+        <span className="min-w-0 flex-1">
+          <DigichatWordmark />
+        </span>
+        <ThreadListPrimitive.New className={digichatSurfaces.action} aria-label="New chat">
+          <DotMatrix state="newChat" decorative className="size-3.5" />
+        </ThreadListPrimitive.New>
+      </div>
+      <ThreadListPrimitive.Root className="flex min-h-0 flex-1 flex-col overflow-y-auto py-[0.25rem]">
+        <ThreadListPrimitive.Items>
+          {() => (
+            <ThreadListItemPrimitive.Root className="rounded-none">
+              <ThreadListItemPrimitive.Trigger className={digichatSurfaces.listItem}>
+                <ThreadListItemPrimitive.Title fallback="new chat" />
+              </ThreadListItemPrimitive.Trigger>
+            </ThreadListItemPrimitive.Root>
+          )}
+        </ThreadListPrimitive.Items>
+      </ThreadListPrimitive.Root>
+    </Tag>
+  );
+}

package/src/components/chat/DigichatWordmark.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+import { DIGICHAT } from "@digithings-ai/hero-banner/definitions";
+import { HeroBanner } from "@digithings-ai/hero-banner/web";
+
+/** Square-pixel DIGICHAT mark, drawn from the shared hero-banner definition
+ *  (`packages/hero-banner`, `DIGICHAT`: scramble 80/240/180 with a 960 hold,
+ *  settled at 2000 ms, seed 0). Plays once per tab — the session claim lives
+ *  inside `HeroBanner`, so header remounts keep the settled mark instead of
+ *  replaying. `live={false}` keeps the replaced component's settled behavior
+ *  rather than the definition's streaming LIVE pass. Reduced motion paints
+ *  the settled mark with no scramble (inside `HeroBanner`, not in CSS). The
+ *  fixed 140x20 box preserves the replaced SVG's intrinsic size (70x10 units
+ *  at cell 2); the `span` keeps both callers' `<span>` nesting valid. The
+ *  server render and a no-JS page show the settled mark: `HeroBanner`
+ *  renders it as a CSS mask over the mark's colour, so the canvas is never an
+ *  empty box before it paints. */
+export function DigichatWordmark() {
+  return (
+    <span className="digichat-wordmark" style={{ display: "inline-block", width: 140, height: 20 }}>
+      <HeroBanner def={DIGICHAT} live={false} />
+    </span>
+  );
+}