duckfn-docs-kit 0.3.0 → 0.4.0

package/dist/remark.d.ts

@@ -13,7 +13,7 @@ import type { Plugin } from 'unified';
  */
 export declare const DEFAULT_VERSION_PLACEHOLDER = "{{DUCKFN_VERSION}}";
 export interface VersionPlaceholderOptions {
-    /** The real version string to substitute in, e.g. `0.0.15`. */
+    /** The real version string to substitute in, e.g. `0.0.17`. */
     version: string;
     /** Override the token if a site uses a different one. */
     placeholder?: string;

package/dist/sql/client.js

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

package/dist/sql/remark.d.ts

@@ -34,8 +34,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

package/dist/sql/renderers.d.ts

@@ -5,6 +5,8 @@ import type { RunnableSqlConfig } from './remark';
  *
  * The registry is the seam later phases plug into. It ships `table` (VisActor
  * VTable), a `text` fallback, the markup previews `iframe` / `html` / `svg`,
+ * `mermaid` (which hands the cell to the kit's own `<dfk-mermaid>` element, so a
+ * query can produce a diagram the reader can zoom, expand, edit and download),
  * plus the `error` view every renderer shares.
  *
  * Heavy dependencies (`@visactor/vtable`) load through dynamic `import()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duckfn-docs-kit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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": [
@@ -59,9 +59,12 @@
     "@codemirror/state": "^6.7.6",
     "@codemirror/view": "^6.43.13",
     "@duckdb/duckdb-wasm": "1.33.1-dev64.0",
+    "@panzoom/panzoom": "^4.6.2",
     "@visactor/vtable": "^1.26.8",
     "codemirror": "^6.0.2",
+    "filenamify": "^7.0.3",
     "iconify-icon": "^3.0.3",
+    "mermaid": "^12.0.0",
     "playwright-core": "^1.63.0",
     "sql-formatter": "^15.9.0"
   },

package/src/IconButton.ts

@@ -0,0 +1,50 @@
+import type {IconifyIconHTMLElement} from 'iconify-icon';
+import {el} from './dom';
+
+/**
+ * A compact icon-only button with a hover/focus tooltip, built once and then
+ * mutated. Shared by `<dfk-sql>`'s code-block cluster and `<dfk-mermaid>`'s
+ * diagram cluster: both want the same "floating icon row over content" idiom,
+ * and neither wants a second implementation of it.
+ *
+ * The tooltip is also the accessible name — an icon-only control has no text to
+ * fall back on. The two class names are written by this module and styled in
+ * *each* consumer's shadow-root CSS; that duplication is unavoidable (a shadow
+ * boundary stops one sheet from reaching the other tree), so the rules carry the
+ * same names and are kept in sync by hand.
+ */
+export class IconButton {
+  readonly root = el('button', {class: 'dfk-icon-button', type: 'button'});
+  readonly #icon: IconifyIconHTMLElement = el('iconify-icon', {
+    class: 'dfk-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 (e.g. the SQL block's wrap toggle). */
+  setOn(on: boolean): void {
+    this.root.classList.toggle('dfk-icon-on', on);
+  }
+
+  setDisabled(disabled: boolean): void {
+    if (disabled) {
+      this.root.setAttribute('disabled', '');
+    } else {
+      this.root.removeAttribute('disabled');
+    }
+  }
+}

package/src/codemirror.ts

@@ -0,0 +1,88 @@
+/**
+ * The CodeMirror 6 editor behind the kit's editable content: the code view of a
+ * runnable SQL block (`<dfk-sql>`) and the diagram-source dialog of a
+ * `<dfk-mermaid>`. One implementation, two languages — the SQL block asks for
+ * highlighting, the diagram editor takes the plain-text default.
+ *
+ * Every CodeMirror module arrives through a dynamic `import()` inside
+ * {@link mountCodeEditor}: a page full of blocks pays nothing for the editor on
+ * its critical path, and Docusaurus' Node prerender never evaluates any of it.
+ *
+ * This is browser-only code: `document` is touched only through the container
+ * the caller hands over, and everything else is behind the `import()`s.
+ */
+
+export interface CodeEditor {
+  getValue(): string;
+  setValue(value: string): void;
+  /** Soft-wraps long lines, or stops wrapping them (the block's wrap toggle). */
+  setWrap(wrapped: boolean): void;
+  destroy(): void;
+}
+
+export interface CodeEditorOptions {
+  /**
+   * Highlight the document as SQL. Omitted, the editor is plain text — which is
+   * what a mermaid diagram gets: there is no first-party CodeMirror language for
+   * it, and a docs reader is editing prose-shaped source, not writing SQL.
+   */
+  language?: 'sql';
+}
+
+export async function mountCodeEditor(
+  container: HTMLElement,
+  value: string,
+  onChange: (value: string) => void,
+  options: CodeEditorOptions = {},
+): Promise<CodeEditor> {
+  const [{basicSetup}, {EditorView, keymap}, {defaultKeymap, historyKeymap}, {Compartment}] =
+    await Promise.all([
+      import('codemirror'),
+      import('@codemirror/view'),
+      import('@codemirror/commands'),
+      import('@codemirror/state'),
+    ]);
+  // Loaded only for the blocks that ask for it, so a diagram editor does not pull
+  // the SQL grammar (and its lezer parsers) into the page.
+  const language =
+    options.language === 'sql' ? [(await import('@codemirror/lang-sql')).sql()] : [];
+
+  // Wrapping is toggled from the outside, and reconfiguring it must not disturb
+  // the document or the undo history — that is exactly what a compartment is
+  // for, so the extension is swapped in place rather than rebuilt.
+  const wrap = new Compartment();
+
+  const view = new EditorView({
+    doc: value,
+    extensions: [
+      basicSetup,
+      ...language,
+      keymap.of([...defaultKeymap, ...historyKeymap]),
+      wrap.of([]),
+      EditorView.updateListener.of((update) => {
+        if (update.docChanged) {
+          onChange(update.state.doc.toString());
+        }
+      }),
+    ],
+    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.
+  });
+
+  return {
+    getValue: () => view.state.doc.toString(),
+    setValue: (next: string) =>
+      view.dispatch({
+        changes: {from: 0, to: view.state.doc.length, insert: next},
+      }),
+    setWrap: (wrapped: boolean) =>
+      view.dispatch({
+        effects: wrap.reconfigure(wrapped ? EditorView.lineWrapping : []),
+      }),
+    destroy: () => view.destroy(),
+  };
+}

package/src/index.ts

@@ -1,7 +1,14 @@
 import type {HTMLAttributes} from 'react';
+// Imported as well as re-exported: the `HTMLElementTagNameMap` augmentation below
+// names the classes, and a module augmentation can only refer to local bindings.
+import {DfkFeatures} from './home/DfkFeatures';
+import {DfkHero} from './home/DfkHero';
+import {DfkMermaid} from './mermaid/DfkMermaid';
+import {DfkNextSteps} from './home/DfkNextSteps';
+import {DfkSql} from './sql/DfkSql';
 
 /**
- * Browser entry for duckfn-docs-kit: the home-page custom elements and the
+ * Browser entry for duckfn-docs-kit: the custom elements it registers and the
  * value types their `set*` methods accept.
  *
  * The components are retained-mode (build once, then mutate held nodes) and
@@ -13,17 +20,16 @@ import type {HTMLAttributes} from 'react';
  * web component, which `registerDfkElements()` registers as a side effect, so
  * this package ships no icon data.
  *
- * `TocToggle` and the remark plugin keep their own subpaths
- * (`duckfn-docs-kit/toc-toggle/TocToggle`, `duckfn-docs-kit/remark`) instead of
+ * `TocToggle` and the remark plugins keep their own subpaths
+ * (`duckfn-docs-kit/toc-toggle/TocToggle`, `duckfn-docs-kit/remark`,
+ * `duckfn-docs-kit/sql/remark`, `duckfn-docs-kit/mermaid/remark`) instead of
  * being merged here: a Docusaurus config file must never pull browser code into
  * Node, and a site that only wants the TOC collapse button should not pay for
  * the bundled `iconify-icon`.
  */
-export {DfkFeatures} from './home/DfkFeatures';
-export {DfkHero} from './home/DfkHero';
-export {DfkNextSteps} from './home/DfkNextSteps';
-export {DfkSql} from './sql/DfkSql';
+export {DfkFeatures, DfkHero, DfkMermaid, DfkNextSteps, DfkSql};
 export {registerDfkElements} from './register';
+export type {DfkMermaidConfig, DfkMermaidConfigInput} from './mermaid/config';
 export type {RunnableSqlConfig} from './sql/remark';
 export type {
   FeatureItem,
@@ -47,6 +53,23 @@ export type {
  */
 export type DfkElementProps = HTMLAttributes<HTMLElement>;
 
+/**
+ * The kit's tags in the DOM's own tag map, so `document.createElement('dfk-sql')`
+ * (and the kit's `el()` helper) is typed as the class it upgrades to. Without
+ * this, every place that builds a `dfk-*` element from scratch — `sql/renderers.ts`
+ * building a `<dfk-mermaid>` for a `mermaid` result, `docs/src/pages/index.tsx`
+ * mounting the home elements — would have to cast the result.
+ */
+declare global {
+  interface HTMLElementTagNameMap {
+    'dfk-hero': DfkHero;
+    'dfk-features': DfkFeatures;
+    'dfk-next-steps': DfkNextSteps;
+    'dfk-sql': DfkSql;
+    'dfk-mermaid': DfkMermaid;
+  }
+}
+
 declare module 'react' {
   namespace JSX {
     interface IntrinsicElements {
@@ -54,6 +77,7 @@ declare module 'react' {
       'dfk-features': DfkElementProps;
       'dfk-next-steps': DfkElementProps;
       'dfk-sql': DfkElementProps;
+      'dfk-mermaid': DfkElementProps;
     }
   }
 }

package/src/mermaid/DfkMermaid.css

@@ -0,0 +1,289 @@
+/* Shadow-root styles for `<dfk-mermaid>`: the diagram viewport, the action
+   cluster floating in its top-right corner, and the source-editing dialog.
+
+   Theme colours arrive through the inherited `--ifm-*` custom properties;
+   box-sizing must be re-declared here because the host page's universal reset
+   does not cross the shadow boundary. */
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+:host {
+  display: block;
+  margin: 1rem 0;
+}
+
+.dfk-mermaid-canvas {
+  position: relative;
+}
+
+/* The zoom/pan viewport. Panzoom transforms `.dfk-mermaid-content` *inside* this
+   box, so the overflow stays clipped here rather than spilling over the page —
+   `overflow: hidden` is also what panzoom expects of a pan element's parent. */
+.dfk-mermaid-viewport {
+  overflow: hidden;
+  border: 1px solid var(--ifm-global-border-color, #e0e0e0);
+  border-radius: var(--ifm-global-radius, 0.4rem);
+  background: var(--ifm-background-surface-color, #fff);
+  padding: 0.75rem;
+}
+
+/* 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. */
+.dfk-mermaid-content > svg {
+  display: block;
+  margin: 0 auto;
+  max-width: 100%;
+  height: auto;
+}
+
+/* --- Cursor -------------------------------------------------------------- */
+
+/* The cursor says what a drag will actually do, which is why it is driven by the
+   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 {
+  cursor: grab;
+}
+
+.dfk-mermaid-canvas.dfk-mermaid-zoomed.dfk-mermaid-grabbing {
+  cursor: grabbing;
+}
+
+/* --- Status line --------------------------------------------------------- */
+
+/* Doubles as the "still rendering" placeholder: the mermaid bundle is a lazy
+   `import()`, and this line is what the reader sees while it lands (or the error
+   message, if the source does not parse). It is the component's only
+   pre-render content — a diagram's height is unknowable before it renders, so
+   the alternative would be inventing a placeholder height that is wrong for
+   every diagram but one. */
+.dfk-mermaid-message {
+  margin: 0.5rem 0 0;
+  font-size: 0.8rem;
+  color: var(--ifm-color-emphasis-700, #666);
+}
+
+.dfk-mermaid-message:empty {
+  display: none;
+}
+
+.dfk-mermaid-message-error {
+  padding: 0.5rem 0.75rem;
+  border-radius: var(--ifm-global-radius, 0.25rem);
+  color: var(--ifm-color-danger-contrast, #fff);
+  background: var(--ifm-color-danger, #d32f2f);
+  font-family: var(--ifm-font-family-monospace, ui-monospace, SFMono-Regular,
+    Menlo, monospace);
+  font-size: var(--ifm-code-font-size, 95%);
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.dfk-mermaid-canvas[hidden],
+.dfk-mermaid-message[hidden] {
+  display: none;
+}
+
+/* --- Floating actions ---------------------------------------------------- */
+
+/* Hover/focus-revealed, like the buttons on Docusaurus' own code blocks and the
+   ones on a runnable SQL block. The cluster is inert while hidden so an
+   invisible button is never a click target over the diagram. */
+.dfk-mermaid-actions {
+  position: absolute;
+  top: 0.25rem;
+  right: 0.25rem;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  gap: 0.15rem;
+  padding: 0.1rem 0.2rem;
+  border-radius: var(--ifm-global-radius, 0.3rem);
+  background: var(--ifm-color-emphasis-100, #f5f5f5);
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.12s ease;
+}
+
+.dfk-mermaid-canvas:hover .dfk-mermaid-actions,
+.dfk-mermaid-canvas:focus-within .dfk-mermaid-actions {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+/* --- Icon buttons and their tooltips ------------------------------------- */
+
+/* The class names are written by the shared `IconButton` widget
+   (`src/IconButton.ts`); the same rules live in `DfkSql.css` and `sql.css`,
+   once per shadow tree they have to reach. Keep the copies in sync. */
+.dfk-icon-button {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.6rem;
+  height: 1.6rem;
+  padding: 0;
+  border: none;
+  border-radius: var(--ifm-global-radius, 0.25rem);
+  background: transparent;
+  color: var(--ifm-color-emphasis-700, #666);
+  cursor: pointer;
+  transition: background 0.12s ease, color 0.12s ease;
+}
+
+.dfk-icon-button:hover:not(:disabled),
+.dfk-icon-button:focus-visible {
+  background: var(--ifm-color-emphasis-200, #e6e6e6);
+  color: var(--ifm-color-primary, #14459b);
+}
+
+.dfk-icon-button:disabled {
+  opacity: 0.45;
+  cursor: progress;
+}
+
+.dfk-icon-button[hidden] {
+  display: none;
+}
+
+.dfk-icon {
+  font-size: 1rem;
+}
+
+[data-tip]::after {
+  content: attr(data-tip);
+  position: absolute;
+  top: calc(100% + 0.3rem);
+  right: 0;
+  z-index: 2;
+  padding: 0.15rem 0.4rem;
+  border-radius: var(--ifm-global-radius, 0.25rem);
+  background: var(--ifm-color-emphasis-800, #333);
+  color: var(--ifm-color-emphasis-0, #fff);
+  font-size: 0.7rem;
+  line-height: 1.4;
+  white-space: nowrap;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.12s ease;
+}
+
+[data-tip]:hover::after,
+[data-tip]:focus-visible::after {
+  opacity: 1;
+}
+
+/* --- Fullscreen ---------------------------------------------------------- */
+
+/* The whole canvas becomes a fixed overlay. `z-index` has to clear Docusaurus'
+   navbar and its own overlays. The background must be the *surface* colour, not
+   `--ifm-background-color`: a site may legitimately define the latter as
+   `transparent` (this repository's docs site does), which would leave the
+   overlay see-through with the page showing underneath. */
+.dfk-mermaid-expanded {
+  position: fixed;
+  inset: 0;
+  z-index: 2147483000;
+  display: flex;
+  flex-direction: column;
+  background: var(--ifm-background-surface-color, #fff);
+}
+
+.dfk-mermaid-expanded .dfk-mermaid-viewport {
+  flex: 1;
+  border: none;
+  border-radius: 0;
+}
+
+/* --- Source dialog ------------------------------------------------------- */
+
+.dfk-mermaid-dialog {
+  width: min(56rem, 92vw);
+  max-width: none;
+  padding: 0;
+  border: 1px solid var(--ifm-global-border-color, #e0e0e0);
+  border-radius: var(--ifm-global-radius, 0.4rem);
+  background: var(--ifm-background-surface-color, #fff);
+  color: var(--ifm-font-color-base, #181818);
+}
+
+.dfk-mermaid-dialog::backdrop {
+  background: rgb(0 0 0 / 45%);
+}
+
+.dfk-mermaid-dialog-body {
+  display: flex;
+  flex-direction: column;
+  gap: 0.5rem;
+  padding: 0.75rem;
+}
+
+.dfk-mermaid-dialog-title {
+  margin: 0;
+  font-size: 0.95rem;
+  font-weight: 600;
+}
+
+/* CodeMirror mounts here, inside the shadow tree, so style-mod puts its base
+   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 {
+  border: 1px solid var(--ifm-global-border-color, #e0e0e0);
+  border-radius: var(--ifm-global-radius, 0.4rem);
+  overflow: hidden;
+  background: var(--ifm-background-surface-color, #fff);
+  font-size: var(--ifm-code-font-size, 95%);
+}
+
+.dfk-mermaid-dialog-editor .cm-editor {
+  outline: none;
+}
+
+.dfk-mermaid-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 {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.5rem;
+}
+
+.dfk-mermaid-dialog-button {
+  padding: 0.3rem 0.9rem;
+  border: 1px solid var(--ifm-global-border-color, #e0e0e0);
+  border-radius: var(--ifm-global-radius, 0.25rem);
+  background: var(--ifm-background-surface-color, #fff);
+  color: var(--ifm-font-color-base, #181818);
+  font-family: inherit;
+  font-size: 0.85rem;
+  cursor: pointer;
+}
+
+.dfk-mermaid-dialog-button:hover {
+  border-color: var(--ifm-color-primary, #14459b);
+  color: var(--ifm-color-primary, #14459b);
+}
+
+.dfk-mermaid-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 {
+  color: var(--ifm-button-color, #fff);
+  filter: brightness(1.1);
+}