duckfn-docs-kit 0.4.0 → 0.4.1

package/dist/source-dialog.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare class SourceDialog {
+    #private;
+    readonly root: HTMLDialogElement;
+    constructor(labels: SourceDialogLabels);
+    setLabels(labels: SourceDialogLabels): void;
+    /**
+     * 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;
+    /** Closes the dialog and releases the editor. The dialog node stays in place. */
+    destroy(): void;
+}

package/dist/sql/PreviewTabs.d.ts

@@ -1,37 +1,53 @@
+import { type DownloadPayload } from '../download';
 /**
  * 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.
  */
-/** 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;
 }
 export declare class PreviewTabs {
     #private;
     /**
-     * @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>, corner?: HTMLElement);
-    /** Releases the table (if it was ever shown) and empties every panel. */
+    constructor(host: HTMLElement, items: readonly PreviewTabItem[], downloadLabel: string, corner?: HTMLElement);
+    /** Releases every mounted item and empties the panels. */
     dispose(): void;
+    /**
+     * 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;
 }

package/dist/sql/SvgViewer.d.ts

@@ -0,0 +1,53 @@
+import { type DownloadPayload } from '../download';
+/**
+ * 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 declare class SvgViewer {
+    #private;
+    /** The box in the tab panel: the panzoom viewport, and the frame's clipping box. */
+    readonly root: HTMLDivElement;
+    /** The controls the result area's tab strip shows while this tab is active. */
+    readonly actions: HTMLDivElement;
+    constructor(svg: SVGElement | null, markup: string, labels: FigureLabels, fallback: string);
+    /** Turns zoom and pan on or off; the result area calls this with its fullscreen. */
+    setFullscreen(value: boolean): void;
+    /**
+     * 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;
+    dispose(): void;
+}
+/**
+ * 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 declare function parseSvgMarkup(document: Document, markup: string): SVGElement | null;

package/dist/sql/client.js

@@ -1,4 +1,4 @@
-import { t as e } from "../register-Dev_kc3Z.js";
+import { t as e } from "../register-wdwf0LC4.js";
 //#region src/sql/client.ts
 typeof window < "u" && e();
 //#endregion

package/dist/sql/harness.js

@@ -8000,7 +8000,7 @@ var Eu, Du, Ou, ku, Au, ju, Mu, Nu, Pu, Fu, Iu, Lu, Ru, zu, Bu, Vu, Hu, Uu, Wu,
 		11
 	])), od = {
 		name: "@duckdb/duckdb-wasm",
-		version: "1.33.1-dev64.0",
+		version: "1.33.1-dev65.0",
 		description: "DuckDB powered by WebAssembly",
 		license: "MIT",
 		repository: {

package/dist/sql/renderers.d.ts

@@ -25,6 +25,13 @@ export interface RenderContext {
      * renderer only borrows it so every result has the same chrome.
      */
     fullscreenButton: HTMLElement;
+    /**
+     * Subscribes to the result area's fullscreen state, calling back with the
+     * current value straight away and returning the unsubscribe. A renderer whose
+     * figure zooms only in fullscreen (`svg`, `mermaid`) forwards the value to its
+     * viewer; the subscription must be released by the renderer's disposer.
+     */
+    onFullscreenChange(listener: (value: boolean) => void): () => void;
 }
 /**
  * Renders `result` into `context.host`. Resolves with a disposer releasing any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duckfn-docs-kit",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Shared Docusaurus building blocks (TOC toggle, home-page web components, brand tokens, remark version placeholder) for duckfn-family extension docs sites.",
   "license": "MIT",
   "keywords": [
@@ -58,9 +58,10 @@
     "@codemirror/lang-sql": "^6.10.0",
     "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.13",
-    "@duckdb/duckdb-wasm": "1.33.1-dev64.0",
+    "@duckdb/duckdb-wasm": "1.33.1-dev65.0",
     "@panzoom/panzoom": "^4.6.2",
     "@visactor/vtable": "^1.26.8",
+    "@visactor/vtable-search": "^1.26.8",
     "codemirror": "^6.0.2",
     "filenamify": "^7.0.3",
     "iconify-icon": "^3.0.3",

package/src/codemirror.ts

@@ -66,11 +66,20 @@ export async function mountCodeEditor(
       }),
     ],
     parent: container,
-    // `root` is left to CodeMirror's own `getRoot(container)`. The container sits
-    // in the component's shadow root, so style-mod mounts the base theme into
-    // that same shadow root — exactly where the `.cm-*` rules are needed.
-    // Pinning it to `document` would put them outside the editor's tree instead,
-    // where a shadow boundary stops them.
+    // The tree the container really belongs to — `getRootNode()`, not CodeMirror's
+    // own `getRoot()`. `getRoot()` follows `assignedSlot` before `parentNode`, so a
+    // container in a *slotted* subtree is reported as living in the shadow root it
+    // is slotted **into**. The SQL result area is exactly that (light DOM, slotted
+    // into `<dfk-sql>` through `slot="dfk-result"`), so style-mod mounted the base
+    // theme in a shadow root, where it cannot reach slotted nodes at all: the
+    // editor laid out as plain block boxes — `.cm-scroller` stacked instead of
+    // flex, gutter above the code.
+    //
+    // `getRootNode()` stops at the tree that owns the container: `document` for
+    // that slotted light DOM, the shadow root for a genuine shadow child (the
+    // code view, a diagram's dialog) — which is where the `.cm-*` rules are
+    // needed. Pinning it to `document` would break the shadow cases instead.
+    root: container.getRootNode() as Document | ShadowRoot,
   });
 
   return {

package/src/{mermaid/title.ts → download.ts}

@@ -1,28 +1,46 @@
 import filenamify from 'filenamify';
+import {el} from './dom';
 
 /**
- * What a downloaded diagram is called.
+ * Saving something the kit rendered to a file: the payload shape, the click that
+ * performs the save, and how the file is named.
  *
- * The name is derived from the page, not from the diagram: a diagram has no name
- * of its own, and the reader downloading one is after "the diagram from that
- * section", not `mermaid-diagram.svg`.
- *
- * Three sources, most specific first, each falling back to the next:
- *
- * 1. **The diagram's own title** — mermaid's frontmatter
- *    (`---\ntitle: …\n---`, which mermaid itself draws above the diagram).
- * 2. **The nearest heading above it** — the section the diagram belongs to, which
- *    on a docs page is what a reader would call it.
- * 3. **The document title** — the browser tab's title, for a diagram that sits
- *    above every heading on its page.
- *
- * Nothing found → {@link DEFAULT_DIAGRAM_FILE}.
+ * Shared by `<dfk-mermaid>` (a downloaded diagram) and the SQL result chrome (a
+ * downloaded result of any kind), so a docs page has one definition of "what a
+ * download is" rather than one per component.
  *
  * This is browser-only code.
  */
 
-/** Used when nothing on the page says anything about this diagram. */
-export const DEFAULT_DIAGRAM_FILE = 'mermaid-diagram.svg';
+/** One file's worth of text, ready to save. */
+export interface DownloadPayload {
+  /** The file name, extension included. */
+  name: string;
+  /** The blob's MIME type. */
+  mime: string;
+  /** The file's contents — text for every format the kit produces. */
+  text: string;
+}
+
+/**
+ * Saves a payload through a temporary object URL.
+ *
+ * The anchor is in the document for the click — some browsers ignore a detached
+ * one — and the URL is revoked on the next tick, once the download has been
+ * handed to the browser.
+ */
+export function saveDownload(payload: DownloadPayload): void {
+  const blob = new Blob([payload.text], {type: payload.mime});
+  const url = URL.createObjectURL(blob);
+  const link = el('a', {href: url, download: payload.name});
+  document.body.appendChild(link);
+  link.click();
+  link.remove();
+  window.setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+
+/** Used when nothing on the page says anything about what this is. */
+const DEFAULT_BASE = 'diagram';
 
 /**
  * The length cap. `filenamify` truncates by grapheme, so a CJK heading is cut at
@@ -53,15 +71,39 @@ function cleanTitle(value: string | undefined): string {
   return value === undefined ? '' : value.replace(EDGE_NOISE, '');
 }
 
-export function diagramFileName(source: string, element: Element): string {
+/**
+ * What a downloaded figure is called.
+ *
+ * The name is derived from the page, not from the figure: a diagram or an SVG
+ * result has no name of its own, and the reader downloading one is after "the
+ * figure from that section", not `diagram.svg`.
+ *
+ * Three sources, most specific first, each falling back to the next:
+ *
+ * 1. **The figure's own title** — mermaid's frontmatter (`---\ntitle: …\n---`,
+ *    which mermaid itself draws above the diagram); only read when `options.source`
+ *    is given.
+ * 2. **The nearest heading above it** — the section the figure belongs to, which
+ *    on a docs page is what a reader would call it.
+ * 3. **The document title** — the browser tab's title, for a figure that sits
+ *    above every heading on its page.
+ *
+ * Nothing found → `options.fallback` (or {@link DEFAULT_BASE}), with `extension`
+ * appended either way.
+ */
+export function sectionFileName(
+  element: Element,
+  extension: string,
+  options: {source?: string; fallback?: string} = {},
+): string {
   const candidates = [
-    frontmatterTitle(source),
+    options.source === undefined ? undefined : frontmatterTitle(options.source),
     precedingHeading(element),
     element.ownerDocument.title,
   ].map(cleanTitle);
   const title = candidates.find((candidate) => candidate !== '');
   if (title === undefined) {
-    return DEFAULT_DIAGRAM_FILE;
+    return `${options.fallback ?? DEFAULT_BASE}.${extension}`;
   }
   // Filenames are a filesystem concern, so they go through a library rather than a
   // hand-rolled character class. Three things it does that matter here and that a
@@ -74,7 +116,7 @@ export function diagramFileName(source: string, element: Element): string {
   // It also normalises Unicode whitespace and drops format characters, which
   // quietly cleans up Docusaurus' heading anchors: the `<a>` it appends to every
   // heading contributes a zero-width space to `textContent`.
-  return `${filenamify(title, {replacement: REPLACEMENT, maxLength: MAX_LENGTH})}.svg`;
+  return `${filenamify(title, {replacement: REPLACEMENT, maxLength: MAX_LENGTH})}.${extension}`;
 }
 
 /**
@@ -102,11 +144,11 @@ function unquote(value: string): string {
 }
 
 /**
- * The text of the last heading that precedes the diagram, or `undefined`.
+ * The text of the last heading that precedes the figure, or `undefined`.
  *
  * The search is scoped to the enclosing `<article>` where there is one: a docs
  * page's navbar, sidebar and footer are full of headings that have nothing to do
- * with this diagram, and the article is the one container that holds the page's
+ * with this figure, and the article is the one container that holds the page's
  * own content.
  */
 function precedingHeading(element: Element): string | undefined {
@@ -124,4 +166,4 @@ function precedingHeading(element: Element): string | undefined {
     }
   }
   return found;
-}
+}

package/src/mermaid/DfkMermaid.css

@@ -16,6 +16,14 @@
   margin: 1rem 0;
 }
 
+/* Embedded in a SQL result: the result area's tab strip and panel already draw
+   the frame, so the element contributes neither margin nor border nor padding —
+   two nested frames are one too many. Its zoom controls live in the tab strip
+   instead of floating here, which `DfkMermaid.ts` arranges. */
+:host([embedded]) {
+  margin: 0;
+}
+
 .dfk-mermaid-canvas {
   position: relative;
 }
@@ -31,6 +39,34 @@
   padding: 0.75rem;
 }
 
+/* The SQL result panel is the frame; this one is only a clipping box. */
+:host([embedded]) .dfk-mermaid-viewport {
+  border: none;
+  border-radius: 0;
+  padding: 0;
+}
+
+/* Fullscreen (embedded): the result area hands the panel its height, so the
+   viewport fills it instead of sizing to the diagram. `:host(...)` rather than a
+   descendant selector because the class sits on the element itself, outside this
+   shadow tree. */
+:host(.dfk-mermaid-fullscreen) {
+  height: 100%;
+}
+
+/* The canvas is what the viewport's `height: 100%` resolves against, so the
+   fullscreen height has to pass *through* it. Left `auto`, the percentage above
+   has nothing to resolve against and collapses back to the diagram's own height —
+   the figure then looks the same in fullscreen, and the wheel/drag surface (and
+   the clip box) stays a strip as tall as the diagram. */
+:host(.dfk-mermaid-fullscreen) .dfk-mermaid-canvas {
+  height: 100%;
+}
+
+:host(.dfk-mermaid-fullscreen) .dfk-mermaid-viewport {
+  height: 100%;
+}
+
 /* Mermaid sizes its own `<svg>` (`width="100%"` plus an inline `max-width`), so
    nothing here fights that: the rules only centre it once the inline cap kicks
    in, and give it a line box so the viewport has a height. */
@@ -47,12 +83,13 @@
    zoom state rather than set on the element once and for all (panzoom's `cursor`
    option does the latter, and it was promising a pan at fit — over text that is
    perfectly selectable). `cursor` is inherited, so these two rules reach the
-   diagram and every label in it; the buttons override it with `pointer`. */
-.dfk-mermaid-canvas.dfk-mermaid-zoomed {
+   diagram and every label in it; the buttons override it with `pointer`. The state
+   classes are written by the shared `PanZoomView`. */
+.dfk-mermaid-viewport.dfk-panzoom-zoomed {
   cursor: grab;
 }
 
-.dfk-mermaid-canvas.dfk-mermaid-zoomed.dfk-mermaid-grabbing {
+.dfk-mermaid-viewport.dfk-panzoom-zoomed.dfk-panzoom-grabbing {
   cursor: grabbing;
 }
 
@@ -205,7 +242,7 @@
 
 /* --- Source dialog ------------------------------------------------------- */
 
-.dfk-mermaid-dialog {
+.dfk-source-dialog {
   width: min(56rem, 92vw);
   max-width: none;
   padding: 0;
@@ -215,18 +252,18 @@
   color: var(--ifm-font-color-base, #181818);
 }
 
-.dfk-mermaid-dialog::backdrop {
+.dfk-source-dialog::backdrop {
   background: rgb(0 0 0 / 45%);
 }
 
-.dfk-mermaid-dialog-body {
+.dfk-source-dialog-body {
   display: flex;
   flex-direction: column;
   gap: 0.5rem;
   padding: 0.75rem;
 }
 
-.dfk-mermaid-dialog-title {
+.dfk-source-dialog-title {
   margin: 0;
   font-size: 0.95rem;
   font-weight: 600;
@@ -236,7 +273,7 @@
    theme in the same root the `.cm-*` rules are needed in (`src/codemirror.ts`).
    The content inset is CodeMirror's own (`padding: 4px 0`) and is left alone —
    see the note in `DfkSql.css` about `ViewState.measure()`. */
-.dfk-mermaid-dialog-editor {
+.dfk-source-dialog-editor {
   border: 1px solid var(--ifm-global-border-color, #e0e0e0);
   border-radius: var(--ifm-global-radius, 0.4rem);
   overflow: hidden;
@@ -244,24 +281,24 @@
   font-size: var(--ifm-code-font-size, 95%);
 }
 
-.dfk-mermaid-dialog-editor .cm-editor {
+.dfk-source-dialog-editor .cm-editor {
   outline: none;
 }
 
-.dfk-mermaid-dialog-editor .cm-scroller {
+.dfk-source-dialog-editor .cm-scroller {
   max-height: 55vh;
   font-family: var(--ifm-font-family-monospace, ui-monospace, SFMono-Regular,
     Menlo, monospace);
   line-height: 1.6;
 }
 
-.dfk-mermaid-dialog-footer {
+.dfk-source-dialog-footer {
   display: flex;
   justify-content: flex-end;
   gap: 0.5rem;
 }
 
-.dfk-mermaid-dialog-button {
+.dfk-source-dialog-button {
   padding: 0.3rem 0.9rem;
   border: 1px solid var(--ifm-global-border-color, #e0e0e0);
   border-radius: var(--ifm-global-radius, 0.25rem);
@@ -272,18 +309,18 @@
   cursor: pointer;
 }
 
-.dfk-mermaid-dialog-button:hover {
+.dfk-source-dialog-button:hover {
   border-color: var(--ifm-color-primary, #14459b);
   color: var(--ifm-color-primary, #14459b);
 }
 
-.dfk-mermaid-dialog-apply {
+.dfk-source-dialog-apply {
   border-color: var(--ifm-color-primary, #14459b);
   background: var(--ifm-color-primary, #14459b);
   color: var(--ifm-button-color, #fff);
 }
 
-.dfk-mermaid-dialog-apply:hover {
+.dfk-source-dialog-apply:hover {
   color: var(--ifm-button-color, #fff);
   filter: brightness(1.1);
 }