duckfn-docs-kit 0.4.0 → 0.4.1

package/src/panzoom-view.ts

@@ -0,0 +1,235 @@
+import type {PanzoomObject} from '@panzoom/panzoom';
+
+/**
+ * The zoom / pan behaviour behind a rendered figure, shared by `<dfk-mermaid>`
+ * and the SQL result `svg` viewer.
+ *
+ * It owns no structure: the caller builds the viewport and the content box (each
+ * with its own class names, so each consumer's stylesheet can reach them) and
+ * hands both over. What lives here is the interaction contract — when panzoom may
+ * take the gesture, and how the zoom state is reflected back onto the viewport.
+ *
+ * **Zoom is opt-in and reversible.** panzoom starts disabled and only
+ * {@link setActive} turns it on, which is what lets an inline figure leave the
+ * page's scrolling alone: a wheel over a figure that is merely displayed is the
+ * browser's, and only a figure the reader has opened moves (the SQL result's
+ * fullscreen, a diagram's own). Deactivating resets the view to fit, so the next
+ * activation starts from the whole figure.
+ *
+ * This is browser-only code: `@panzoom/panzoom` is reached through a dynamic
+ * `import()`, so a page whose figures are never zoomed never loads it.
+ */
+
+/**
+ * The zoom range. `MIN_SCALE` is the fit-to-box scale: the figure opens there and
+ * cannot go below it, which is what makes "zoomed" a clean yes/no — it is exactly
+ * the state in which a drag pans, the wheel has something to undo, and the cursor
+ * stops promising plain text.
+ */
+const MIN_SCALE = 1;
+const MAX_SCALE = 8;
+const ZOOM_STEP = 0.25;
+
+/** The pan/zoom library, loaded once per page on first use. */
+let panzoomModule: Promise<typeof import('@panzoom/panzoom')['default']> | null = null;
+
+function loadPanzoom(): Promise<typeof import('@panzoom/panzoom')['default']> {
+  panzoomModule ??= import('@panzoom/panzoom').then((module) => module.default);
+  return panzoomModule;
+}
+
+export class PanZoomView {
+  readonly #viewport: HTMLElement;
+  readonly #content: HTMLElement;
+  #panzoom: PanzoomObject | null = null;
+  #loading = false;
+  #active = false;
+  /** Whether the viewport's wheel listener is currently attached. */
+  #wheelBound = false;
+
+  readonly #onWheel = (event: WheelEvent): void => {
+    this.#panzoom?.zoomWithWheel(event);
+  };
+  /** The cursor follows the zoom state, so it never promises a pan that cannot happen. */
+  readonly #onChange = (): void => {
+    this.#viewport.classList.toggle('dfk-panzoom-zoomed', this.zoomed);
+  };
+  readonly #onStart = (): void => {
+    // `panzoomstart` fires at fit too, where the gesture was left to the browser;
+    // only a drag that will really pan gets the closed hand.
+    this.#viewport.classList.toggle('dfk-panzoom-grabbing', this.zoomed);
+  };
+  readonly #onEnd = (): void => {
+    this.#viewport.classList.remove('dfk-panzoom-grabbing');
+  };
+
+  constructor(viewport: HTMLElement, content: HTMLElement) {
+    this.#viewport = viewport;
+    this.#content = content;
+    // panzoom reports state as DOM `CustomEvent`s dispatched on the element it
+    // transforms (`@panzoom/panzoom` v4 has no `on()` API), so they are listened
+    // for here, on the content box — which also means they need no teardown, and
+    // that re-creating the panzoom instance after a reconnect cannot double them.
+    content.addEventListener('panzoomchange', this.#onChange);
+    content.addEventListener('panzoomstart', this.#onStart);
+    content.addEventListener('panzoomend', this.#onEnd);
+  }
+
+  /** Whether the figure is enlarged past its fit-to-box size. */
+  get zoomed(): boolean {
+    return (this.#panzoom?.getScale() ?? MIN_SCALE) > MIN_SCALE;
+  }
+
+  /** Replaces the figure on screen and returns the view to fit. */
+  setContent(node: Node | null): void {
+    this.#content.replaceChildren(...(node ? [node] : []));
+    this.reset();
+  }
+
+  /**
+   * Turns wheel zoom and dragging on or off. Activating loads panzoom on first
+   * use (a figure nobody zooms never pays for the chunk); deactivating leaves the
+   * view at fit, so the figure a reader returns to is the whole one.
+   */
+  setActive(active: boolean): void {
+    if (active === this.#active) {
+      return;
+    }
+    this.#active = active;
+    if (active) {
+      void this.#ensurePanzoom();
+    } else {
+      this.reset();
+      this.#setEnabled(false);
+      this.#unbindWheel();
+    }
+  }
+
+  reset(): void {
+    this.#panzoom?.reset({
+      // Zooming back to fit is a transition the reader did not ask to skip, but
+      // one they may have asked not to have.
+      animate: !prefersReducedMotion(),
+    });
+  }
+
+  /** Releases the panzoom instance and returns the viewport to its idle state. */
+  destroy(): void {
+    this.#active = false;
+    this.#unbindWheel();
+    this.#panzoom?.destroy();
+    this.#panzoom = null;
+    this.#viewport.classList.remove('dfk-panzoom-zoomed', 'dfk-panzoom-grabbing');
+  }
+
+  /**
+   * Binds panzoom to the content box. `@panzoom/panzoom` is an enhancement, not a
+   * requirement: if its chunk never arrives, the figure still renders, only wheel
+   * zoom and dragging stay inert.
+   *
+   * Three settings carry the interaction contract:
+   *
+   * - `panOnlyWhenZoomed` — a figure that already fits must not swallow drags, so
+   *   panning only engages once it is enlarged. That is also what keeps
+   *   `touchAction: 'pan-y'` meaningful: vertical page scrolling stays the
+   *   browser's, pinch and horizontal drags go to the figure.
+   * - `handleStartEvent` — panzoom's default takes the gesture on *every*
+   *   pointerdown (`preventDefault` + `stopPropagation`), which costs the reader
+   *   text selection at every zoom level. Handing the gesture over only when a
+   *   drag will really pan is what makes the labels selectable while the figure is
+   *   at fit. Nothing else blocks it: panzoom's move listener is `passive` and
+   *   never calls `preventDefault`.
+   * - no `cursor` option — panzoom would then put `grab` on the element for good,
+   *   over text that is perfectly selectable. The cursor is driven by the zoom
+   *   state instead, from each consumer's stylesheet.
+   */
+  async #ensurePanzoom(): Promise<void> {
+    if (this.#panzoom !== null) {
+      this.#setEnabled(true);
+      this.#bindWheel();
+      return;
+    }
+    if (this.#loading) {
+      return;
+    }
+    this.#loading = true;
+    try {
+      const Panzoom = await loadPanzoom();
+      // Deactivated while the chunk was in flight: nothing to build, and the next
+      // activation starts from here again.
+      if (!this.#active || this.#panzoom !== null) {
+        return;
+      }
+      this.#panzoom = Panzoom(this.#content, {
+        maxScale: MAX_SCALE,
+        minScale: MIN_SCALE,
+        step: ZOOM_STEP,
+        panOnlyWhenZoomed: true,
+        touchAction: 'pan-y',
+        // panzoom's own default is `move`, written inline on the element — the
+        // cursor has to stay a CSS decision (see the consumers' stylesheets), so
+        // it is switched off here.
+        cursor: '',
+        disablePan: false,
+        disableZoom: false,
+        handleStartEvent: (event) => {
+          if (!this.zoomed) {
+            return;
+          }
+          event.preventDefault();
+          event.stopPropagation();
+        },
+      });
+      this.#clearPanzoomStyles();
+      this.#bindWheel();
+    } catch {
+      // Nothing to report: the figure is already usable without pan/zoom.
+    } finally {
+      this.#loading = false;
+    }
+  }
+
+  #setEnabled(enabled: boolean): void {
+    if (this.#panzoom === null) {
+      return;
+    }
+    this.#panzoom.setOptions({disablePan: !enabled, disableZoom: !enabled});
+    this.#clearPanzoomStyles();
+  }
+
+  /**
+   * panzoom forces `user-select: none` inline on the element *and its parent*,
+   * with no option to prevent it — that alone made every label in every diagram
+   * unselectable. It exists to stop a drag from selecting while panning, which
+   * `handleStartEvent` already covers: whenever a pan will happen, the gesture is
+   * taken with `preventDefault()` before the browser can start a selection.
+   * panzoom writes these styles when the instance is created and again on every
+   * `setOptions`, so they are cleared after each.
+   */
+  #clearPanzoomStyles(): void {
+    this.#content.style.userSelect = '';
+    this.#viewport.style.userSelect = '';
+  }
+
+  #bindWheel(): void {
+    if (this.#wheelBound) {
+      return;
+    }
+    this.#wheelBound = true;
+    // `passive: false` because `zoomWithWheel()` calls `preventDefault()` — a
+    // passive listener could not stop the page from scrolling underneath.
+    this.#viewport.addEventListener('wheel', this.#onWheel, {passive: false});
+  }
+
+  #unbindWheel(): void {
+    if (!this.#wheelBound) {
+      return;
+    }
+    this.#wheelBound = false;
+    this.#viewport.removeEventListener('wheel', this.#onWheel);
+  }
+}
+
+function prefersReducedMotion(): boolean {
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}

package/src/source-dialog.ts

@@ -0,0 +1,126 @@
+import type {CodeEditor} from './codemirror';
+import {mountCodeEditor} from './codemirror';
+import {el} from './dom';
+
+/**
+ * The "edit the source" dialog shared by `<dfk-mermaid>` and the SQL result `svg`
+ * viewer: a modal holding a plain-text CodeMirror editor and an Apply / Cancel
+ * pair.
+ *
+ * The editor writes back through the callback {@link open} is given rather than
+ * through an event, so the owner keeps its own source as the single truth — the
+ * dialog never renders anything and never decides what a change means.
+ *
+ * The `<dialog>` is built once and reused; the editor mounts on first open and is
+ * kept, because a reader who edits one diagram is likely to edit the next. The
+ * dialog is shown *before* the editor mounts: CodeMirror measures its container as
+ * it is constructed, and a `display: none` dialog measures to zero.
+ *
+ * This is browser-only code.
+ */
+
+export interface SourceDialogLabels {
+  title: string;
+  apply: string;
+  cancel: string;
+}
+
+export class SourceDialog {
+  readonly root = el('dialog', {class: 'dfk-source-dialog'});
+  readonly #title = el('h2', {class: 'dfk-source-dialog-title'});
+  /** Where the CodeMirror editor mounts, inside the dialog. */
+  readonly #editorHost = el('div', {class: 'dfk-source-dialog-editor'});
+  readonly #applyBtn = el('button', {
+    class: 'dfk-source-dialog-button dfk-source-dialog-apply',
+    type: 'button',
+  });
+  readonly #cancelBtn = el('button', {class: 'dfk-source-dialog-button', type: 'button'});
+
+  /** The source the dialog was opened with, and the baseline for "was it edited". */
+  #source = '';
+  #onApply: ((value: string) => void) | null = null;
+  #editor: CodeEditor | null = null;
+  #editorLoading = false;
+
+  constructor(labels: SourceDialogLabels) {
+    this.#applyBtn.addEventListener('click', () => this.#apply());
+    this.#cancelBtn.addEventListener('click', () => this.root.close());
+    this.root.append(
+      el('div', {class: 'dfk-source-dialog-body'}, (body) =>
+        body.append(
+          this.#title,
+          this.#editorHost,
+          el('div', {class: 'dfk-source-dialog-footer'}, (footer) =>
+            footer.append(this.#cancelBtn, this.#applyBtn),
+          ),
+        ),
+      ),
+    );
+    this.setLabels(labels);
+  }
+
+  setLabels(labels: SourceDialogLabels): void {
+    this.#title.textContent = labels.title;
+    this.#cancelBtn.textContent = labels.cancel;
+    this.#applyBtn.textContent = labels.apply;
+  }
+
+  /**
+   * Shows the dialog with `source` in the editor. `onApply` receives the edited
+   * text — only when it differs from what was opened, so an unedited Apply is a
+   * plain close.
+   */
+  open(source: string, onApply: (value: string) => void): void {
+    this.#source = source;
+    this.#onApply = onApply;
+    this.root.showModal();
+    if (this.#editor) {
+      this.#editor.setValue(source);
+      return;
+    }
+    void this.#mountEditor();
+  }
+
+  /** Closes the dialog and releases the editor. The dialog node stays in place. */
+  destroy(): void {
+    this.#editor?.destroy();
+    this.#editor = null;
+    if (this.root.open) {
+      this.root.close();
+    }
+  }
+
+  async #mountEditor(): Promise<void> {
+    if (this.#editorLoading) {
+      return;
+    }
+    this.#editorLoading = true;
+    try {
+      // No language: the dialog edits mermaid source or SVG markup, neither of
+      // which has a first-party CodeMirror grammar here, and the reader is
+      // touching up a figure rather than writing SQL.
+      const editor = await mountCodeEditor(this.#editorHost, this.#source, () => undefined);
+      if (!this.root.isConnected || !this.root.open) {
+        // Closed (or detached) while the modules were loading: nothing will ever
+        // dispose this editor, so dispose it here.
+        editor.destroy();
+        return;
+      }
+      editor.setWrap(true);
+      this.#editor = editor;
+    } catch {
+      // The dialog stays open with an empty editor box; a second click retries.
+    } finally {
+      this.#editorLoading = false;
+    }
+  }
+
+  #apply(): void {
+    const edited = this.#editor?.getValue();
+    this.root.close();
+    if (edited !== undefined && edited !== this.#source) {
+      this.#source = edited;
+      this.#onApply?.(edited);
+    }
+  }
+}

package/src/sql/DfkSql.ts

@@ -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: '正在加载扩展…',
@@ -206,6 +226,13 @@ export class DfkSql extends HTMLElementBase {
   #resultHost: HTMLElement | 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();
@@ -443,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 -------------------------------------------------------------------
@@ -549,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) => {