duckfn-docs-kit 0.1.0

package/src/sql/PreviewTabs.ts

@@ -0,0 +1,169 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+import {el} from '../dom';
+
+/** One preview row: its tab label and how to fill its panel. */
+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;
+}
+
+/** Keeps per-instance element ids unique across every `<dfk-sql>` on a page. */
+let sequence = 0;
+
+export class PreviewTabs {
+  readonly #buttons: HTMLButtonElement[] = [];
+  readonly #panels: HTMLElement[] = [];
+  /** `null` marks the trailing table tab. */
+  readonly #items: (PreviewTabItem | null)[] = [];
+  readonly #mounted: boolean[] = [];
+  readonly #mountTable: (panel: HTMLElement) => Promise<PreviewTableHandle>;
+
+  #tableHandle: PreviewTableHandle | null = null;
+  #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.
+   */
+  constructor(
+    host: HTMLElement,
+    items: readonly PreviewTabItem[],
+    tableLabel: string,
+    mountTable: (panel: HTMLElement) => Promise<PreviewTableHandle>,
+    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
+    // scrollable with them, hence the nested list.
+    const list = el('div', {
+      class: 'dfk-sql-tab-list',
+      attrs: {role: 'tablist'},
+    });
+    const panels = el('div', {class: 'dfk-sql-panels'});
+
+    const add = (label: string, item: PreviewTabItem | null): void => {
+      const index = this.#buttons.length;
+      const panel = el('div', {
+        class: 'dfk-sql-panel',
+        hidden: true,
+        attrs: {
+          role: 'tabpanel',
+          id: `${uid}-panel-${index}`,
+          'aria-labelledby': `${uid}-tab-${index}`,
+        },
+      });
+      const button = el('button', {
+        class: 'dfk-sql-tab',
+        type: 'button',
+        text: label,
+        tabIndex: index === 0 ? 0 : -1,
+        attrs: {
+          role: 'tab',
+          id: `${uid}-tab-${index}`,
+          'aria-controls': `${uid}-panel-${index}`,
+          'aria-selected': 'false',
+        },
+      });
+      button.addEventListener('click', () => this.#select(index));
+      button.addEventListener('keydown', (event) => this.#onKeydown(event, index));
+
+      this.#buttons.push(button);
+      this.#panels.push(panel);
+      this.#items.push(item);
+      this.#mounted.push(false);
+      list.appendChild(button);
+      panels.appendChild(panel);
+    };
+
+    for (const item of items) {
+      add(item.label, item);
+    }
+    add(tableLabel, null);
+
+    bar.appendChild(list);
+    if (corner) {
+      bar.appendChild(corner);
+    }
+    // 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. */
+  dispose(): void {
+    this.#disposed = true;
+    this.#tableHandle?.dispose();
+    this.#tableHandle = null;
+    for (const panel of this.#panels) {
+      panel.replaceChildren();
+    }
+  }
+
+  /** Activation is pure mutation — no panel is rebuilt, none is discarded. */
+  #select(index: number): void {
+    for (let i = 0; i < this.#buttons.length; i += 1) {
+      const active = i === index;
+      const button = this.#buttons[i];
+      button.classList.toggle('dfk-sql-tab-active', active);
+      button.setAttribute('aria-selected', String(active));
+      button.tabIndex = active ? 0 : -1;
+      this.#panels[i].hidden = !active;
+    }
+    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);
+    }
+  }
+
+  async #mountTableInto(index: number): Promise<void> {
+    const handle = await this.#mountTable(this.#panels[index]);
+    if (this.#disposed) {
+      // Disposed while the mount was in flight: release what just arrived.
+      handle.dispose();
+      return;
+    }
+    this.#tableHandle = handle;
+  }
+
+  #onKeydown(event: KeyboardEvent, index: number): void {
+    const offset = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0;
+    if (offset === 0) {
+      return;
+    }
+    event.preventDefault();
+    const next = (index + offset + this.#buttons.length) % this.#buttons.length;
+    this.#select(next);
+    this.#buttons[next].focus();
+  }
+}

package/src/sql/client.ts

@@ -0,0 +1,16 @@
+/**
+ * The kit's client bootstrap for pages that use the `dfk-*` elements,
+ * injected by the `dfkExtensions` Docusaurus plugin on every page (through
+ * `getClientModules()`) so a consuming site does not need a client-module file
+ * of its own just to register the custom elements. The home page keeps its own
+ * module-scope `registerDfkElements()` call (it imports the barrel anyway);
+ * registering twice is a no-op.
+ *
+ * Docusaurus evaluates this module in its Node prerender pass too, where there
+ * is nothing to register — hence the guard.
+ */
+import {registerDfkElements} from '../register';
+
+if (typeof window !== 'undefined') {
+  registerDfkElements();
+}

package/src/sql/editor.ts

@@ -0,0 +1,75 @@
+/**
+ * The CodeMirror 6 editor that *is* the code view of a runnable SQL block.
+ *
+ * Every CodeMirror module arrives through dynamic `import()` inside
+ * {@link mountSqlEditor}: a page full of SQL examples pays nothing for the
+ * editor on its critical path, and Docusaurus' Node prerender never evaluates
+ * any of it.
+ */
+
+export interface SqlEditor {
+  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 async function mountSqlEditor(
+  container: HTMLElement,
+  value: string,
+  onChange: (value: string) => void,
+): Promise<SqlEditor> {
+  const [
+    {basicSetup},
+    {sql},
+    {EditorView, keymap},
+    {defaultKeymap, historyKeymap},
+    {Compartment},
+  ] = await Promise.all([
+    import('codemirror'),
+    import('@codemirror/lang-sql'),
+    import('@codemirror/view'),
+    import('@codemirror/commands'),
+    import('@codemirror/state'),
+  ]);
+
+  // 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,
+      sql(),
+      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 `<dfk-sql>`'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(),
+  };
+}