duckfn-docs-kit 0.3.0 → 0.4.1

package/src/sql/DfkSql.ts

@@ -1,8 +1,8 @@
-import type {IconifyIconHTMLElement} from 'iconify-icon';
 import type {RunnableSqlConfig} from './remark';
 import {DuckDBRuntime, type QueryResult} from './runtime';
 import {rendererFor, type RenderContext} from './renderers';
-import {mountSqlEditor, type SqlEditor} from './editor';
+import {mountCodeEditor, type CodeEditor} from '../codemirror';
+import {IconButton} from '../IconButton';
 import {sqlStyles} from './styles';
 import {el, HTMLElementBase} from '../dom';
 
@@ -50,7 +50,7 @@ type SqlLabels = {
   wrapOff: string;
   copy: string;
   copied: string;
-  /** Context-menu labels for the result table (see `renderers.ts`). */
+  /** Result-table chrome: the tab strip's controls and the context menu. */
   copyAll: string;
   wrapColumn: string;
   unwrapColumn: string;
@@ -58,11 +58,19 @@ type SqlLabels = {
   unfreezeColumns: string;
   resetView: string;
   noData: string;
-  /** Width-mode submenu of the result table (see `renderers.ts`). */
-  widthMode: string;
+  search: string;
+  /** Width-mode button at the right end of the result tab strip. */
   widthAdaptive: string;
   widthStandard: string;
   widthFill: string;
+  /** The tab strip's download button (every result format). */
+  download: string;
+  /** Figure controls: the svg viewer, and embedded `<dfk-mermaid>`. */
+  resetZoom: string;
+  editSource: string;
+  svgSource: string;
+  apply: string;
+  cancel: string;
   running: string;
   initializing: string;
   loadingExtensions: string;
@@ -93,10 +101,16 @@ const LABELS: Record<string, SqlLabels> = {
     unfreezeColumns: 'Unfreeze columns',
     resetView: 'Reset view',
     noData: 'No rows',
-    widthMode: 'Column width',
+    search: 'Search',
     widthAdaptive: 'Fill the width',
     widthStandard: 'Content widths, scroll sideways',
     widthFill: 'Content first, fill when it fits',
+    download: 'Download',
+    resetZoom: 'Reset zoom',
+    editSource: 'Edit source',
+    svgSource: 'SVG source',
+    apply: 'Apply',
+    cancel: 'Cancel',
     running: 'Running…',
     initializing: 'Initializing DuckDB…',
     loadingExtensions: 'Loading extensions…',
@@ -125,10 +139,16 @@ const LABELS: Record<string, SqlLabels> = {
     unfreezeColumns: '取消冻结',
     resetView: '重置视图',
     noData: '无数据',
-    widthMode: '列宽模式',
+    search: '搜索',
     widthAdaptive: '铺满宽度',
     widthStandard: '按内容列宽（可横向滚动）',
     widthFill: '内容优先，装得下就铺满',
+    download: '下载',
+    resetZoom: '还原缩放',
+    editSource: '编辑源码',
+    svgSource: 'SVG 源码',
+    apply: '应用',
+    cancel: '取消',
     running: '执行中…',
     initializing: '正在初始化 DuckDB…',
     loadingExtensions: '正在加载扩展…',
@@ -204,8 +224,15 @@ export class DfkSql extends HTMLElementBase {
   };
 
   #resultHost: HTMLElement | null = null;
-  #editor: SqlEditor | null = null;
+  #editor: CodeEditor | null = null;
   #disposeResult: (() => void) | null = null;
+  /**
+   * Renderers watching the result area's fullscreen state. A figure zooms only
+   * where the result is expanded, so its renderer subscribes through
+   * `RenderContext.onFullscreenChange` and forwards every change — including the
+   * one at subscription time — to its viewer.
+   */
+  readonly #fullscreenListeners = new Set<(value: boolean) => void>();
 
   constructor() {
     super();
@@ -337,9 +364,14 @@ export class DfkSql extends HTMLElementBase {
     this.#mounting = true;
     this.#setEditorPending(true);
     try {
-      const editor = await mountSqlEditor(this.#editorHost, this.#currentSql, (value) => {
-        this.#currentSql = value;
-      });
+      const editor = await mountCodeEditor(
+        this.#editorHost,
+        this.#currentSql,
+        (value) => {
+          this.#currentSql = value;
+        },
+        {language: 'sql'},
+      );
       if (!this.isConnected) {
         // Disconnected while the CodeMirror modules were loading: nothing will
         // ever dispose this editor, so dispose it here.
@@ -438,6 +470,22 @@ export class DfkSql extends HTMLElementBase {
       }
       this.#escBound = value;
     }
+    for (const listener of this.#fullscreenListeners) {
+      listener(value);
+    }
+  }
+
+  /**
+   * Subscribes a renderer to the fullscreen state above, calling back with the
+   * current value straight away (a renderer can mount while the result is
+   * already expanded) and returning the unsubscribe.
+   */
+  #onFullscreenChange(listener: (value: boolean) => void): () => void {
+    this.#fullscreenListeners.add(listener);
+    listener(this.#expanded);
+    return () => {
+      this.#fullscreenListeners.delete(listener);
+    };
   }
 
   // --- Run -------------------------------------------------------------------
@@ -544,6 +592,7 @@ export class DfkSql extends HTMLElementBase {
       config: this.#config,
       labels: this.#labels,
       fullscreenButton: this.#fullscreenBtn.root,
+      onFullscreenChange: (listener) => this.#onFullscreenChange(listener),
     };
     const renderer = rendererFor(this.#config, result);
     void renderer(context, result).then((dispose) => {
@@ -571,46 +620,6 @@ export class DfkSql extends HTMLElementBase {
   }
 }
 
-/**
- * A compact icon-only button with a hover tooltip, built once. The tooltip is
- * also the accessible name — an icon-only control has no text to fall back on.
- */
-class IconButton {
-  readonly root = el('button', {class: 'dfk-sql-icon-button', type: 'button'});
-  readonly #icon: IconifyIconHTMLElement = el('iconify-icon', {
-    class: 'dfk-sql-icon',
-    attrs: {'aria-hidden': 'true'},
-  });
-
-  constructor(icon: string, onClick: () => void) {
-    this.root.appendChild(this.#icon);
-    this.root.addEventListener('click', onClick);
-    this.setIcon(icon);
-  }
-
-  setIcon(icon: string): void {
-    this.#icon.setAttribute('icon', icon);
-  }
-
-  setLabel(text: string): void {
-    this.root.setAttribute('data-tip', text);
-    this.root.setAttribute('aria-label', text);
-  }
-
-  /** Marks a toggle as currently on (the wrap button). */
-  setOn(on: boolean): void {
-    this.root.classList.toggle('dfk-sql-icon-on', on);
-  }
-
-  setDisabled(disabled: boolean): void {
-    if (disabled) {
-      this.root.setAttribute('disabled', '');
-    } else {
-      this.root.removeAttribute('disabled');
-    }
-  }
-}
-
 function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/src/sql/PreviewTabs.ts

@@ -1,32 +1,43 @@
+import {el} from '../dom';
+import {saveDownload, type DownloadPayload} from '../download';
+import {IconButton} from '../IconButton';
+
 /**
  * Every renderer's result shell: a tab strip plus the panels behind it.
  *
- * The strip is one tab per preview row plus a `Table` tab that always comes
- * **last**; a renderer with a single view passes no items at all, so a plain
- * table result is a strip holding nothing but that trailing `Table` tab. Every
- * result therefore has the same chrome — which is where the fullscreen toggle
- * lives.
+ * The strip holds one tab per item — a preview row, a `Text` view, or the
+ * trailing `Table` view — and, at its right end, the chrome that acts on the
+ * result as a whole: the active tab's own {@link PreviewTabItem.actions}, a
+ * **download** button, and whatever the caller parks last (the fullscreen toggle
+ * `<dfk-sql>` owns). Every result therefore has the same chrome, and the panel
+ * behind a tab is built the first time that tab is shown.
  *
- * Retained mode: every button and panel is built in the constructor and held in
- * a field. Activating a tab mutates the nodes it owns (`hidden`, `classList`,
- * `aria-selected`, `tabIndex`) — there is no rebuild, and a panel is filled the
- * first time it is shown rather than up front.
- *
- * The table panel is mounted on first activation on purpose: VTable measures
- * its container when it is constructed, and a `hidden` panel measures to zero.
+ * Retained mode: every button, action container and panel is built in the
+ * constructor and held in a field. Activating a tab mutates the nodes it owns
+ * (`hidden`, `classList`, `aria-selected`, `tabIndex`) — there is no rebuild, and
+ * a panel is filled the first time it is shown rather than up front.
  */
 
-import {el} from '../dom';
-
-/** One preview row: its tab label and how to fill its panel. */
+/** One tab: its label, how to fill its panel, and what it offers the strip. */
 export interface PreviewTabItem {
   label: string;
-  mount(panel: HTMLElement): void;
-}
-
-/** What `PreviewTabs` needs from the caller to own the trailing table tab. */
-export interface PreviewTableHandle {
-  dispose(): void;
+  /**
+   * Fills the panel. Called once, the first time the tab is shown; an async mount
+   * may resolve with a disposer, which the strip runs when it is disposed (that is
+   * how the table's handle gets released, including when the countdown lands after
+   * {@link PreviewTabs.dispose}).
+   */
+  mount(panel: HTMLElement): void | (() => void) | Promise<void | (() => void)>;
+  /**
+   * Controls for the strip's right end, shown only while this tab is active — the
+   * place for actions that belong to *this* result (a table's search and view
+   * switches, a figure's zoom reset) rather than to every result.
+   */
+  actions?: HTMLElement;
+  /** This tab's file, or `null` while there is nothing to save yet. */
+  download?: () => DownloadPayload | null;
+  /** Told the result area's fullscreen state, for figures that zoom inside it. */
+  setFullscreen?: (value: boolean) => void;
 }
 
 /** Keeps per-instance element ids unique across every `<dfk-sql>` on a page. */
@@ -35,38 +46,39 @@ let sequence = 0;
 export class PreviewTabs {
   readonly #buttons: HTMLButtonElement[] = [];
   readonly #panels: HTMLElement[] = [];
-  /** `null` marks the trailing table tab. */
-  readonly #items: (PreviewTabItem | null)[] = [];
+  readonly #items: PreviewTabItem[] = [];
   readonly #mounted: boolean[] = [];
-  readonly #mountTable: (panel: HTMLElement) => Promise<PreviewTableHandle>;
+  /** Disposers returned by mounts, run on {@link dispose}. */
+  readonly #disposers: (() => void)[] = [];
+  readonly #downloadBtn: IconButton;
 
-  #tableHandle: PreviewTableHandle | null = null;
+  #active = 0;
+  #fullscreen = false;
   #disposed = false;
 
   /**
-   * @param corner Node parked at the right end of the strip, outside the
-   * scrolling tab list. `<dfk-sql>` passes its fullscreen toggle: it owns that
-   * button's state, so it owns the node and only lends it here.
+   * @param corner Node parked at the very end of the strip, after the download
+   * button. `<dfk-sql>` passes its fullscreen toggle: it owns that button's state,
+   * so it owns the node and only lends it here.
    */
   constructor(
     host: HTMLElement,
     items: readonly PreviewTabItem[],
-    tableLabel: string,
-    mountTable: (panel: HTMLElement) => Promise<PreviewTableHandle>,
+    downloadLabel: string,
     corner?: HTMLElement,
   ) {
-    this.#mountTable = mountTable;
     const uid = `dfk-sql-tabs-${(sequence += 1)}`;
     const bar = el('div', {class: 'dfk-sql-tabs'});
-    // Only the tab buttons belong to the tablist; the corner button must not be
+    // Only the tab buttons belong to the tablist; the corner must not be
     // scrollable with them, hence the nested list.
     const list = el('div', {
       class: 'dfk-sql-tab-list',
       attrs: {role: 'tablist'},
     });
+    const cornerBox = el('div', {class: 'dfk-sql-tab-corner'});
     const panels = el('div', {class: 'dfk-sql-panels'});
 
-    const add = (label: string, item: PreviewTabItem | null): void => {
+    const add = (item: PreviewTabItem): void => {
       const index = this.#buttons.length;
       const panel = el('div', {
         class: 'dfk-sql-panel',
@@ -80,7 +92,7 @@ export class PreviewTabs {
       const button = el('button', {
         class: 'dfk-sql-tab',
         type: 'button',
-        text: label,
+        text: item.label,
         tabIndex: index === 0 ? 0 : -1,
         attrs: {
           role: 'tab',
@@ -98,34 +110,54 @@ export class PreviewTabs {
       this.#mounted.push(false);
       list.appendChild(button);
       panels.appendChild(panel);
+      if (item.actions) {
+        item.actions.hidden = true;
+        cornerBox.appendChild(item.actions);
+      }
     };
 
     for (const item of items) {
-      add(item.label, item);
+      add(item);
     }
-    add(tableLabel, null);
 
-    bar.appendChild(list);
+    this.#downloadBtn = new IconButton('lucide:download', () => this.#download());
+    this.#downloadBtn.setLabel(downloadLabel);
+    this.#downloadBtn.root.hidden = true;
+    cornerBox.appendChild(this.#downloadBtn.root);
     if (corner) {
-      bar.appendChild(corner);
+      cornerBox.appendChild(corner);
     }
+
+    bar.append(list, cornerBox);
     // The one-time installation of this widget's own subtree.
     host.replaceChildren(bar, panels);
     this.#select(0);
   }
 
-  /** Releases the table (if it was ever shown) and empties every panel. */
+  /** Releases every mounted item and empties the panels. */
   dispose(): void {
     this.#disposed = true;
-    this.#tableHandle?.dispose();
-    this.#tableHandle = null;
+    for (const dispose of this.#disposers) {
+      dispose();
+    }
+    this.#disposers.length = 0;
     for (const panel of this.#panels) {
       panel.replaceChildren();
     }
   }
 
+  /**
+   * Records the result area's fullscreen state and passes it on to the tab on
+   * screen: a figure zooms only where the result is expanded (see `PanZoomView`).
+   */
+  setFullscreen(value: boolean): void {
+    this.#fullscreen = value;
+    this.#items[this.#active]?.setFullscreen?.(value);
+  }
+
   /** Activation is pure mutation — no panel is rebuilt, none is discarded. */
   #select(index: number): void {
+    this.#active = index;
     for (let i = 0; i < this.#buttons.length; i += 1) {
       const active = i === index;
       const button = this.#buttons[i];
@@ -133,27 +165,41 @@ export class PreviewTabs {
       button.setAttribute('aria-selected', String(active));
       button.tabIndex = active ? 0 : -1;
       this.#panels[i].hidden = !active;
+      const actions = this.#items[i].actions;
+      if (actions) {
+        actions.hidden = !active;
+      }
     }
+    const item = this.#items[index];
+    // Only a tab that can save something gets a live download button; a figure
+    // that has not rendered yet answers `null` to the click instead.
+    this.#downloadBtn.root.hidden = item.download === undefined;
+    item.setFullscreen?.(this.#fullscreen);
     if (this.#mounted[index]) {
       return;
     }
     this.#mounted[index] = true;
-    const item = this.#items[index];
-    if (item) {
-      item.mount(this.#panels[index]);
-    } else {
-      void this.#mountTableInto(index);
-    }
+    void this.#mountInto(index);
   }
 
-  async #mountTableInto(index: number): Promise<void> {
-    const handle = await this.#mountTable(this.#panels[index]);
+  async #mountInto(index: number): Promise<void> {
+    const dispose = await this.#items[index].mount(this.#panels[index]);
+    if (typeof dispose !== 'function') {
+      return;
+    }
     if (this.#disposed) {
       // Disposed while the mount was in flight: release what just arrived.
-      handle.dispose();
+      dispose();
       return;
     }
-    this.#tableHandle = handle;
+    this.#disposers.push(dispose);
+  }
+
+  #download(): void {
+    const payload = this.#items[this.#active]?.download?.();
+    if (payload) {
+      saveDownload(payload);
+    }
   }
 
   #onKeydown(event: KeyboardEvent, index: number): void {
@@ -166,4 +212,4 @@ export class PreviewTabs {
     this.#select(next);
     this.#buttons[next].focus();
   }
-}
+}

package/src/sql/SvgViewer.ts

@@ -0,0 +1,155 @@
+import {el} from '../dom';
+import {sectionFileName, type DownloadPayload} from '../download';
+import {IconButton} from '../IconButton';
+import {PanZoomView} from '../panzoom-view';
+import {SourceDialog} from '../source-dialog';
+
+/**
+ * The `svg` result view: an inline SVG a reader can zoom (in the result area's
+ * fullscreen), edit, and download — the same interactions a diagram gets from
+ * `<dfk-mermaid>`, which is why both are built on `PanZoomView` and
+ * `SourceDialog`.
+ *
+ * A plain class rather than a custom element: nothing hands it content through
+ * markup, and the SQL renderer already has the parsed node, so there is no
+ * upgrade to wait for.
+ *
+ * Like an embedded `<dfk-mermaid>`, the element contributes no frame — the result
+ * area's panel is the frame — and no floating cluster: its two controls travel out
+ * through {@link actions} for the result's tab strip, and its file travels out
+ * through {@link downloadPayload} for the strip's download button. Zoom is off
+ * until {@link setFullscreen} says the result area is expanded.
+ *
+ * This is browser-only code.
+ */
+
+/** The strings a figure's controls need. */
+export interface FigureLabels {
+  reset: string;
+  edit: string;
+  editTitle: string;
+  apply: string;
+  cancel: string;
+}
+
+export class SvgViewer {
+  /** The box in the tab panel: the panzoom viewport, and the frame's clipping box. */
+  readonly root = el('div', {class: 'dfk-sql-svg'});
+  /** The controls the result area's tab strip shows while this tab is active. */
+  readonly actions = el('div', {class: 'dfk-sql-tab-actions'});
+  readonly #content = el('div', {class: 'dfk-sql-svg-content'});
+  readonly #view = new PanZoomView(this.root, this.#content);
+  readonly #resetBtn = new IconButton('lucide:rotate-ccw', () => this.#view.reset());
+  readonly #editBtn: IconButton;
+  readonly #dialog: SourceDialog;
+
+  /** The markup as edited, the source for the next re-render and the text export. */
+  #markup: string;
+  /** The rendered node, or `null` when the markup does not parse as SVG. */
+  #svg: SVGElement | null = null;
+  /** The file-name base when nothing on the page says anything better. */
+  readonly #fallback: string;
+
+  constructor(svg: SVGElement | null, markup: string, labels: FigureLabels, fallback: string) {
+    this.#markup = markup;
+    this.#fallback = fallback;
+    this.#svg = svg;
+    this.#editBtn = new IconButton('lucide:pencil', () => this.#openEditor());
+    this.#dialog = new SourceDialog({
+      title: labels.editTitle,
+      apply: labels.apply,
+      cancel: labels.cancel,
+    });
+    this.#resetBtn.setLabel(labels.reset);
+    this.#editBtn.setLabel(labels.edit);
+    this.actions.append(this.#resetBtn.root, this.#editBtn.root);
+    this.#view.setContent(svg ?? textBlock(markup));
+    this.root.append(this.#content, this.#dialog.root);
+  }
+
+  /** Turns zoom and pan on or off; the result area calls this with its fullscreen. */
+  setFullscreen(value: boolean): void {
+    this.#view.setActive(value);
+  }
+
+  /**
+   * The file this view would be saved as: the SVG itself, or — when the markup
+   * does not parse and the view is showing it as text — that text.
+   */
+  downloadPayload(): DownloadPayload {
+    const name = sectionFileName(this.root, this.#svg === null ? 'txt' : 'svg', {
+      fallback: this.#fallback,
+    });
+    if (this.#svg === null) {
+      return {name, mime: 'text/plain;charset=utf-8', text: this.#markup};
+    }
+    return {
+      name,
+      mime: 'image/svg+xml;charset=utf-8',
+      text: new XMLSerializer().serializeToString(this.#svg),
+    };
+  }
+
+  dispose(): void {
+    this.#view.destroy();
+    this.#dialog.destroy();
+    this.#dialog.root.remove();
+  }
+
+  #openEditor(): void {
+    this.#dialog.open(this.#markup, (value) => {
+      this.#markup = value;
+      this.#svg = parseSvgMarkup(this.root.ownerDocument, value);
+      this.#view.setContent(this.#svg ?? textBlock(value));
+    });
+  }
+}
+
+/** The fallback view for markup that is not SVG: the text, not an empty box. */
+function textBlock(markup: string): HTMLElement {
+  return el('pre', {class: 'dfk-sql-text', text: markup});
+}
+
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+
+/**
+ * Parses SVG markup from a result cell into a node this document can host.
+ *
+ * `image/svg+xml` is strict XML: malformed markup (unclosed tags, a bare `&`,
+ * an HTML `<br>`) comes back as a `<parsererror>` element rather than throwing,
+ * so the caller can degrade to text. Script-bearing and event-handler content
+ * is stripped — inline SVG is *not* isolated (use the `iframe` renderer for
+ * untrusted markup).
+ */
+export function parseSvgMarkup(document: Document, markup: string): SVGElement | null {
+  if (!markup.trim()) {
+    return null;
+  }
+  const parsed = new DOMParser().parseFromString(markup, 'image/svg+xml');
+  const root = parsed.documentElement;
+  if (!root || root.localName === 'parsererror' || root.namespaceURI !== SVG_NAMESPACE) {
+    return null;
+  }
+  stripActiveContent(root);
+  return document.importNode(root, true) as unknown as SVGElement;
+}
+
+/** Removes the parts of an SVG document that could execute or navigate. */
+function stripActiveContent(root: Element): void {
+  for (const node of root.querySelectorAll('script, foreignObject')) {
+    node.remove();
+  }
+  const visit = (element: Element): void => {
+    for (const attribute of [...element.attributes]) {
+      const name = attribute.name.toLowerCase();
+      const value = attribute.value.replace(/\s/g, '').toLowerCase();
+      if (name.startsWith('on') || ((name === 'href' || name === 'xlink:href') && value.startsWith('javascript:'))) {
+        element.removeAttribute(attribute.name);
+      }
+    }
+    for (const child of element.children) {
+      visit(child);
+    }
+  };
+  visit(root);
+}

package/src/sql/remark.ts

@@ -36,8 +36,13 @@ export interface RunnableSqlConfig {
    *
    * `html` and `iframe` are the same renderer: both sandbox the markup in an
    * iframe, so scripts run with an opaque origin.
+   *
+   * `mermaid` renders the column's mermaid source as a diagram through
+   * `<dfk-mermaid>` (the same element a ```mermaid fence produces), so the result
+   * gets the element's zoom, fullscreen, source editing and SVG download for
+   * free.
    */
-  show?: 'table' | 'html' | 'iframe' | 'svg' | 'text';
+  show?: 'table' | 'html' | 'iframe' | 'svg' | 'text' | 'mermaid';
   /**
    * What this block is expected to do when the docs' own SQL test suite runs it
    * (`duckfn-docs-kit/sql/verify`). Defaults to `'ok'`; `'error'` marks a block