@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/chat/transcript/chat-export.ts

@@ -0,0 +1,133 @@
+/**
+ * One export model for every skin: a format (`md` | `html`) and a scope.
+ *
+ * - The message menu exports that assistant message only.
+ * - The chat menu (`/export`, the settings list) exports the whole
+ *   conversation, user and assistant turns in order.
+ *
+ * Markdown is built from the runtime messages. HTML is a snapshot of the
+ * rendered thread (`replay/browser`), so it looks like the chat.
+ */
+
+import { serializeAssistantMarkdown, type TranscriptTurn } from "./transcript-markdown";
+
+export type ChatExportFormat = "md" | "html";
+
+export const CHAT_EXPORT_FORMATS: readonly ChatExportFormat[] = ["md", "html"];
+
+/** `md`, `markdown`, `html`, case-insensitive. Empty means markdown. */
+export function parseChatExportFormat(raw: string | null | undefined): ChatExportFormat | null {
+  const value = (raw ?? "").trim().toLowerCase().replace(/^\./, "");
+  if (value === "" || value === "md" || value === "markdown") return "md";
+  if (value === "html" || value === "htm") return "html";
+  return null;
+}
+
+export type ChatExportStrings = {
+  /** The submenu trigger: `Export`. */
+  export: string;
+  markdown: string;
+  html: string;
+  /** Hint under the chat-level `/export` row. */
+  conversationHint: string;
+  /** Turn headings in the markdown file. */
+  user: string;
+  assistant: string;
+};
+
+const EN: ChatExportStrings = {
+  export: "Export",
+  markdown: "Markdown (.md)",
+  html: "HTML (.html)",
+  conversationHint: "Download this conversation as a file.",
+  user: "User",
+  assistant: "Assistant",
+};
+
+const FR: ChatExportStrings = {
+  export: "Exporter",
+  markdown: "Markdown (.md)",
+  html: "HTML (.html)",
+  conversationHint: "Télécharger cette conversation dans un fichier.",
+  user: "Utilisateur",
+  assistant: "Assistant",
+};
+
+export const CHAT_EXPORT_LOCALES: Readonly<Record<string, ChatExportStrings>> = { en: EN, fr: FR };
+
+/** Strings for a language code (`fr`, `fr-CA`). Unknown languages get English. */
+export function chatExportStrings(locale?: string | null): ChatExportStrings {
+  const code = (locale ?? "").split(/[-_]/)[0]?.toLowerCase() ?? "";
+  return CHAT_EXPORT_LOCALES[code] ?? EN;
+}
+
+export function chatExportLabel(format: ChatExportFormat, strings: ChatExportStrings): string {
+  return format === "html" ? strings.html : strings.markdown;
+}
+
+/**
+ * Text turns from runtime messages (`content` or `parts`). Tool calls,
+ * reasoning and empty turns are left out.
+ */
+export function transcriptTurns(messages: readonly unknown[]): TranscriptTurn[] {
+  const out: TranscriptTurn[] = [];
+  for (const raw of messages) {
+    const turn = transcriptTurn(raw);
+    if (turn) out.push(turn);
+  }
+  return out;
+}
+
+export function transcriptTurn(raw: unknown): TranscriptTurn | null {
+  if (!raw || typeof raw !== "object") return null;
+  const m = raw as { role?: string; content?: unknown; parts?: unknown };
+  if (m.role !== "user" && m.role !== "assistant") return null;
+  const parts = Array.isArray(m.content) ? m.content : m.parts;
+  const text = Array.isArray(parts)
+    ? parts
+        .filter((p): p is { type: string; text?: string } => !!p && typeof p === "object")
+        .filter((p) => p.type === "text" && typeof p.text === "string")
+        .map((p) => p.text ?? "")
+        .join("")
+    : typeof m.content === "string"
+      ? m.content
+      : "";
+  if (!text.trim()) return null;
+  return { role: m.role, content: text };
+}
+
+/**
+ * The conversation file: a `## User` / `## Assistant` heading per turn, in
+ * order, separated by a rule so the turns stay apart in any viewer.
+ */
+export function conversationMarkdown(
+  turns: readonly TranscriptTurn[],
+  strings: Pick<ChatExportStrings, "user" | "assistant"> = EN,
+): string {
+  const blocks: string[] = [];
+  for (const turn of turns) {
+    const body =
+      turn.role === "assistant"
+        ? serializeAssistantMarkdown(turn.content, turn.sources)
+        : turn.content.trim();
+    if (!body) continue;
+    const heading = turn.role === "user" ? strings.user : strings.assistant;
+    blocks.push(`## ${heading}\n\n${body}`);
+  }
+  return blocks.join("\n\n---\n\n");
+}
+
+/** One assistant message, as rendered: no heading, no question. */
+export function messageMarkdown(turn: TranscriptTurn | null): string {
+  if (!turn || turn.role !== "assistant") return "";
+  return serializeAssistantMarkdown(turn.content, turn.sources);
+}
+
+/** Last user question in the turns, for the file name. */
+export function lastQuestion(turns: readonly TranscriptTurn[]): string {
+  for (let i = turns.length - 1; i >= 0; i -= 1) {
+    const turn = turns[i];
+    if (turn?.role === "user") return turn.content;
+  }
+  return "";
+}

package/src/components/chat/transcript/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Transcript serializers + activity rows for the package skins (WS4).
+ *
+ * Moved from `@digithings-ai/digichat-ui` (which re-exports this barrel for
+ * compat). The three modules share no export names, so `export *` is safe.
+ */
+export * from "./transcript-markdown";
+export * from "./activity-view";
+export * from "./types";
+export * from "./chat-export";

package/src/components/chat/transcript/save-file.ts

@@ -0,0 +1,209 @@
+/**
+ * Save a generated text file (Markdown or HTML export) from the chat.
+ *
+ * Phones broke the plain `<a download>` path in two ways:
+ *
+ * 1. iOS Safari asks "Download …?" before it reads a blob URL. The old code
+ *    revoked the URL two seconds after the click, so a visitor who took
+ *    longer to confirm got an empty or failed download. The URL now lives
+ *    for a minute.
+ * 2. A download or share started after the tap's user activation expired
+ *    is dropped, silently, inside a cross-origin iframe (the OCC and
+ *    digithings.ai embeds). The HTML export runs after the menu closes and
+ *    after it inlines fonts and images, which on a phone network outlasts
+ *    the activation. When activation is gone we show a "Save" button, so
+ *    the save runs inside a fresh tap.
+ *
+ * On a touch device that can share files (and where the frame is allowed
+ * to), the system share sheet is used: it offers "Save to Files" on iOS
+ * and is the reliable path there. Desktop keeps the direct download.
+ */
+
+/** How long a blob URL outlives its click. iOS reads it after the user confirms. */
+export const SAVE_URL_LIFETIME_MS = 60_000;
+
+export const SAVE_PROMPT_SLOT = "export-save-prompt";
+
+type ShareNavigator = Navigator & {
+  canShare?: (data: ShareData) => boolean;
+  share?: (data: ShareData) => Promise<void>;
+  userActivation?: { isActive: boolean };
+};
+
+type FeaturePolicyDocument = Document & {
+  featurePolicy?: { allowsFeature: (feature: string) => boolean };
+  permissionsPolicy?: { allowsFeature: (feature: string) => boolean };
+};
+
+type Env = { navigator?: Navigator; matchMedia?: (q: string) => { matches: boolean } };
+
+function coarsePointer(win: Env): boolean {
+  try {
+    return win.matchMedia?.("(pointer: coarse)").matches === true;
+  } catch {
+    return false;
+  }
+}
+
+function shareAllowedInFrame(doc: Document): boolean {
+  const policy =
+    (doc as FeaturePolicyDocument).permissionsPolicy ??
+    (doc as FeaturePolicyDocument).featurePolicy;
+  if (!policy) return true;
+  try {
+    return policy.allowsFeature("web-share");
+  } catch {
+    return true;
+  }
+}
+
+/** False only when the browser says the tap's activation is gone. */
+export function hasUserActivation(nav: Navigator | undefined): boolean {
+  const ua = (nav as ShareNavigator | undefined)?.userActivation;
+  return ua ? ua.isActive : true;
+}
+
+function canShareFile(win: Env, doc: Document, file: File): boolean {
+  const nav = win.navigator as ShareNavigator | undefined;
+  if (!nav || typeof File === "undefined") return false;
+  if (typeof nav.share !== "function" || typeof nav.canShare !== "function") return false;
+  if (!coarsePointer(win) || !shareAllowedInFrame(doc)) return false;
+  try {
+    return nav.canShare({ files: [file] });
+  } catch {
+    return false;
+  }
+}
+
+/** Anchor download. Needs to run inside a user activation in an iframe. */
+export function anchorDownload(doc: Document, filename: string, blob: Blob): void {
+  const url = URL.createObjectURL(blob);
+  const a = doc.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.rel = "noopener";
+  (doc.body ?? doc.documentElement).appendChild(a);
+  a.click();
+  a.remove();
+  const later =
+    globalThis.setTimeout ??
+    ((fn: () => void) => {
+      fn();
+      return 0;
+    });
+  later(() => URL.revokeObjectURL(url), SAVE_URL_LIFETIME_MS);
+}
+
+/** Share sheet on a phone, else a download. Call from inside a tap. */
+function saveNow(win: Env, doc: Document, filename: string, text: string, mime: string): void {
+  const blob = new Blob([text], { type: mime });
+  const file = typeof File === "undefined" ? null : new File([text], filename, { type: mime });
+  if (file && canShareFile(win, doc, file)) {
+    const nav = win.navigator as ShareNavigator;
+    const fallback = () => {
+      // The share was refused. A download now may be outside the tap, so ask
+      // for one more tap (download only) when the activation is gone.
+      if (hasUserActivation(win.navigator)) anchorDownload(doc, filename, file);
+      else showSavePrompt(doc, filename, () => anchorDownload(doc, filename, file));
+    };
+    let pending: Promise<void>;
+    try {
+      pending = nav.share!({ files: [file], title: filename });
+    } catch {
+      // WebKit throws synchronously for data it cannot share.
+      anchorDownload(doc, filename, file);
+      return;
+    }
+    pending.catch((error: unknown) => {
+      // The visitor closed the sheet: nothing to do.
+      if (error instanceof Error && error.name === "AbortError") return;
+      fallback();
+    });
+    return;
+  }
+  anchorDownload(doc, filename, file ?? blob);
+}
+
+function removePrompt(doc: Document): void {
+  doc.querySelector(`[data-slot='${SAVE_PROMPT_SLOT}']`)?.remove();
+}
+
+/**
+ * A one-tap "Save" button for an export that finished after the tap's
+ * activation expired. Replaces any earlier prompt.
+ */
+export function showSavePrompt(
+  doc: Document,
+  filename: string,
+  onSave: () => void,
+): HTMLElement | null {
+  const host = doc.body ?? doc.documentElement;
+  if (!host) return null;
+  removePrompt(doc);
+  const box = doc.createElement("div");
+  box.setAttribute("role", "status");
+  box.setAttribute("aria-live", "polite");
+  box.setAttribute("data-slot", SAVE_PROMPT_SLOT);
+  box.style.cssText =
+    "position:fixed;left:50%;bottom:max(16px,env(safe-area-inset-bottom));transform:translateX(-50%);z-index:2147483000;display:flex;gap:8px;align-items:center;max-width:calc(100vw - 32px);padding:6px 6px 6px 12px;border:1px solid currentColor;background:Canvas;color:CanvasText;font:inherit;font-size:14px;";
+  const label = doc.createElement("span");
+  label.style.cssText = "overflow:hidden;text-overflow:ellipsis;white-space:nowrap;min-width:0;";
+  const target = "min-height:44px;min-width:44px;font:inherit;color:inherit;cursor:pointer;";
+  const save = doc.createElement("button");
+  save.type = "button";
+  save.textContent = "Save";
+  save.setAttribute("data-slot", `${SAVE_PROMPT_SLOT}-save`);
+  save.style.cssText = `${target}padding:0 14px;border:1px solid currentColor;background:transparent;`;
+  save.addEventListener("click", () => {
+    try {
+      onSave();
+    } finally {
+      removePrompt(doc);
+    }
+  });
+  const close = doc.createElement("button");
+  close.type = "button";
+  close.textContent = "×";
+  close.setAttribute("aria-label", "Dismiss");
+  close.style.cssText = `${target}padding:0;border:0;background:transparent;`;
+  close.addEventListener("click", () => removePrompt(doc));
+  box.append(label, save, close);
+  // The live region exists before its text, so screen readers announce it.
+  host.appendChild(box);
+  label.textContent = `${filename} is ready. Tap Save to download it.`;
+  try {
+    save.focus({ preventScroll: true });
+  } catch {
+    /* focus is best effort */
+  }
+  return box;
+}
+
+/** Inside a cross-origin frame or on a phone, a late save needs a fresh tap. */
+function needsFreshTap(win: Env & { parent?: unknown; self?: unknown }): boolean {
+  let framed = false;
+  try {
+    framed = win.parent !== undefined && win.parent !== win.self;
+  } catch {
+    framed = true;
+  }
+  return framed || coarsePointer(win);
+}
+
+/**
+ * Save `text` as `filename`. Inside a live tap it shares (phone) or
+ * downloads (desktop) right away. After the activation expired it asks for
+ * one more tap instead of failing silently.
+ */
+export function saveTextFile(filename: string, text: string, mime: string): void {
+  if (typeof document === "undefined") {
+    throw new Error("downloadTextFile requires a document");
+  }
+  const doc = document;
+  const win = globalThis as unknown as Env;
+  if (!hasUserActivation(win.navigator) && needsFreshTap(win)) {
+    showSavePrompt(doc, filename, () => saveNow(win, doc, filename, text, mime));
+    return;
+  }
+  saveNow(win, doc, filename, text, mime);
+}