duckfn-docs-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shijianjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# duckfn-docs-kit
+
+Shared building blocks for [duckfn](https://github.com/shijianjs/duckfn)-family
+DuckDB extension documentation sites: runnable SQL blocks, extension preloading,
+a TOC collapse control, the home-page web components and the version-placeholder
+remark plugin. Each one is a self-contained entry point that a Docusaurus 3 site
+wires into its own config — the alternative is copying the same glue into every
+extension's docs site.
+
+Plain TypeScript over the native DOM: no React and no UI framework of its own.
+The components are retained-mode classes — they build their DOM once, expose
+named domain setters and render into shadow roots, so a site's global CSS and the
+kit's never leak into each other.
+
+## Install
+
+```bash
+npm install duckfn-docs-kit
+```
+
+## Entry points
+
+| Import | Runs in | What it provides |
+| --- | --- | --- |
+| `duckfn-docs-kit` | browser | Home-page custom elements (`<dfk-hero>`, `<dfk-features>`, `<dfk-next-steps>`, `<dfk-sql>`), `registerDfkElements()` and the value types their setters accept |
+| `duckfn-docs-kit/remark` | Node (build) | `remarkVersionPlaceholder`: replaces `{{DUCKFN_VERSION}}` inside `text` / `inlineCode` / `code` nodes |
+| `duckfn-docs-kit/sql/remark` | Node (build) | `remarkRunnableSql`: turns fenced `sql run` blocks into `<dfk-sql>` elements |
+| `duckfn-docs-kit/sql/extensions` | Node (build) | `dfkExtensions()` Docusaurus plugin: preloads a site's DuckDB extensions before the first block runs |
+| `duckfn-docs-kit/toc-toggle/plugin` | Node (build) | `dfkTocToggle()` Docusaurus plugin: adds the TOC collapse control |
+| `duckfn-docs-kit/toc-toggle/TocToggle` | browser | The TOC collapse class, for a site that drives it itself |
+| `duckfn-docs-kit/src/kit.css` | CSS | Brand tokens plus the styles a shadow boundary cannot host |
+
+The two plugins inject their own browser glue (`dfk-*` element registration and
+the TOC toggle) on every page, so a site needs no `clientModules` file of its
+own. `duckfn-docs-kit/sql/client` and `duckfn-docs-kit/toc-toggle/client` are
+that glue — plugins use them, sites should not import them directly.
+
+## Wiring it up
+
+```ts
+// docusaurus.config.ts
+import {dfkExtensions} from 'duckfn-docs-kit/sql/extensions';
+import {dfkTocToggle} from 'duckfn-docs-kit/toc-toggle/plugin';
+import {remarkVersionPlaceholder} from 'duckfn-docs-kit/remark';
+import {remarkRunnableSql} from 'duckfn-docs-kit/sql/remark';
+import {DUCKFN_VERSION} from './duckfn-version';
+
+export default {
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          remarkPlugins: [
+            [remarkVersionPlaceholder, {version: DUCKFN_VERSION}],
+            remarkRunnableSql,
+          ],
+        },
+      },
+    ],
+  ],
+  plugins: [
+    dfkExtensions({
+      allowUnsignedExtensions: true,
+      preload: [
+        {
+          url: 'duckdb-extensions/duckfn.duckdb_extension.wasm',
+          release: {
+            repository: 'shijianjs/duckfn',
+            asset: 'duckfn-wasm_eh.duckdb_extension.wasm',
+          },
+        },
+      ],
+    }),
+    dfkTocToggle(),
+  ],
+};
+```
+
+The global CSS is a single import in the site's own stylesheet:
+
+```css
+/* src/css/custom.css */
+@import 'duckfn-docs-kit/src/kit.css';
+```
+
+`kit.css` aggregates the `--duckfn-*` brand tokens and the styles a shadow
+boundary cannot host (the TOC toggle). The `dfk-*` components carry their own
+styles inside the JS bundle, so they need nothing here.
+
+## Requirements
+
+- Node ≥ 20 and Docusaurus 3.x.
+- `@duckdb/duckdb-wasm` is pinned to an exact version because the WebAssembly
+  extensions a site loads have to stay ABI-compatible with the DuckDB build
+  inside the wasm bundle. Keep the pin and the extension build in lockstep.
+
+## Documentation
+
+The user guide lives at <https://shijianjs.github.io/duckfn/docs/docs-kit>. The
+conventions this package is written to — retained-mode components, shadow DOM,
+SSR safety, the SQL rendering contract — are documented in
+[`AGENTS.md`](./AGENTS.md), which ships inside the package.
+
+## License
+
+MIT

package/dist/dom.d.ts

@@ -0,0 +1,69 @@
+/**
+ * DOM helpers shared by the custom elements.
+ *
+ * `HTMLElementBase` is the whole reason this module exists: the element classes
+ * `extend` it, but Docusaurus imports this package into Node during static
+ * prerendering, where the global `HTMLElement` does not exist and evaluating
+ * `class X extends HTMLElement` would throw. Falling back to an empty base
+ * class keeps module evaluation safe on the server; the real `HTMLElement` is
+ * picked up in the browser, where the elements are actually defined and run.
+ */
+export declare const HTMLElementBase: typeof HTMLElement;
+/**
+ * The tag's props that hold a value `el()` can assign as-is — `href`, `src`,
+ * `alt`, `width`, `hidden`, and so on.
+ *
+ * Methods and object-valued props are filtered out, so an options bag can never
+ * carry `appendChild`, `style`, `dataset` or `classList`. Getter-only props
+ * (`origin`, `clientWidth`) do pass the filter; assigning one throws in strict
+ * mode, which is loud enough to be caught the first time it runs.
+ */
+type ValueProps<T> = {
+    [P in keyof T as T[P] extends Function ? never : T[P] extends object ? never : P]?: T[P];
+};
+/**
+ * Options for `el()`: the tag's own props, narrowed to that tag, plus two
+ * shorthands and the attribute escape hatch.
+ */
+export type ElOptions<T extends Element> = ValueProps<T> & {
+    /** Shorthand for `className`. */
+    class?: string;
+    /** Shorthand for `textContent`. */
+    text?: string;
+    /**
+     * Attributes that have no matching prop: `aria-*`, `data-*`, and
+     * custom-element attributes. Everything else goes through a property, so a
+     * boolean or a number keeps its real type instead of being stringified.
+     */
+    attrs?: Record<string, string>;
+};
+/**
+ * `document.createElement` with per-tag typed options and an optional `init`
+ * callback.
+ *
+ * The one sanctioned way to build nodes in this package: it returns a live
+ * element (held in a class field by the caller), never an HTML string.
+ *
+ * The options are narrowed to the tag, so a typo, a wrong value type, a method
+ * name or an object-valued prop is a compile error:
+ *
+ * ```ts
+ * el('img', {class: 'dfk-logo', alt: '', width: 480});
+ * ```
+ *
+ * `init` describes a subtree in place, for structure that is never referenced
+ * again and therefore needs no field:
+ *
+ * ```ts
+ * this.root.append(
+ *   el('span', {class: 'dfk-next-card-body'}, (body) => body.append(this.#title, this.#details)),
+ *   this.#arrow,
+ * );
+ * ```
+ *
+ * Nodes touched later stay in fields. A field initializer must not read a
+ * `#field` declared below it (initializers run in declaration order, so that is
+ * a TDZ error) — pass `init` from the constructor, where every field is ready.
+ */
+export declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, options?: ElOptions<HTMLElementTagNameMap[K]> | ((node: HTMLElementTagNameMap[K]) => void), init?: (node: HTMLElementTagNameMap[K]) => void): HTMLElementTagNameMap[K];
+export {};

package/dist/home/DfkFeatures.d.ts

@@ -0,0 +1,20 @@
+import { HTMLElementBase } from '../dom';
+import type { FeatureItem } from '../types';
+/**
+ * `<dfk-features>` — the "Why duckfn" grid of feature cards. Ported from the
+ * home page's `Features()`.
+ *
+ * Retained-mode: the grid is built once and each card (a {@link DfkFeatureCard})
+ * holds its own nodes. `setFeatures()` grows or shrinks the list to the new
+ * length and mutates the cards in place — the grid is never cleared and rebuilt.
+ *
+ * The tree lives in a shadow root (adopting the shared `homeStyles()` sheet);
+ * see `DfkHero` for why the theme crosses the boundary through custom
+ * properties.
+ */
+export declare class DfkFeatures extends HTMLElementBase {
+    #private;
+    constructor();
+    setSectionTitle(text: string): void;
+    setFeatures(items: readonly FeatureItem[]): void;
+}

package/dist/home/DfkHero.d.ts

@@ -0,0 +1,25 @@
+import { HTMLElementBase } from '../dom';
+import type { HeroAction, HeroBadge, HeroLink } from '../types';
+/**
+ * `<dfk-hero>` — the landing hero: logo, title, tagline, the two call-to-action
+ * buttons and the badge row. Ported from the Docusaurus home page's `Hero()`.
+ *
+ * Retained-mode: every node is held in a field, the structure is assembled once
+ * in the constructor and the `set*` methods only mutate the nodes they own.
+ *
+ * The tree lives in a shadow root (adopting the shared `homeStyles()` sheet), so
+ * the site's global CSS cannot reach it; theme colours cross the boundary
+ * through the inherited `--duckfn-*` / `--ifm-*` custom properties.
+ */
+export declare class DfkHero extends HTMLElementBase {
+    #private;
+    constructor();
+    setLogo(src: string): void;
+    setTitle(text: string): void;
+    setTagline(text: string): void;
+    /** The "Get started" button: an internal link, so it stays in the same tab. */
+    setPrimaryAction(link: HeroLink): void;
+    /** The GitHub button: always external, always carries the glyph. */
+    setSecondaryAction(action: HeroAction): void;
+    setBadges(badges: readonly HeroBadge[]): void;
+}

package/dist/home/DfkNextSteps.d.ts

@@ -0,0 +1,16 @@
+import { HTMLElementBase } from '../dom';
+import type { NextStepItem } from '../types';
+/**
+ * `<dfk-next-steps>` — the "Where to go next" row of link cards. Ported from
+ * the home page's `NextSteps()`.
+ *
+ * Same retained-mode shape as `DfkFeatures`: the grid is built once, each card
+ * holds its own nodes, `setSteps()` grows/shrinks the list and mutates in place.
+ * The tree lives in a shadow root like the other `dfk-*` elements.
+ */
+export declare class DfkNextSteps extends HTMLElementBase {
+    #private;
+    constructor();
+    setSectionTitle(text: string): void;
+    setSteps(items: readonly NextStepItem[]): void;
+}

package/dist/home/styles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The one parsed stylesheet shared by every `dfk-*` shadow root.
+ *
+ * Created lazily: Docusaurus imports this module into Node during
+ * prerendering, where `CSSStyleSheet` does not exist — only the browser ever
+ * calls this.
+ */
+export declare function homeStyles(): CSSStyleSheet;

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import type { HTMLAttributes } from 'react';
+/**
+ * Browser entry for duckfn-docs-kit: the home-page custom elements and the
+ * value types their `set*` methods accept.
+ *
+ * The components are retained-mode (build once, then mutate held nodes) and
+ * expose named setters such as `setTitle()` / `setBadges()`. They render into
+ * shadow roots and inject their own stylesheet, so the consuming site imports
+ * only the global CSS the kit cannot host in a shadow (`src/kit.css`: brand
+ * tokens + TOC toggle, imported as `duckfn-docs-kit/src/kit.css`). Icons are
+ * rendered by the official `<iconify-icon>`
+ * 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
+ * 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 { registerDfkElements } from './register';
+export type { RunnableSqlConfig } from './sql/remark';
+export type { FeatureItem, HeroAction, HeroBadge, HeroLink, NextStepItem, } from './types';
+/**
+ * Props accepted by the `dfk-*` tags when they are created from React.
+ *
+ * The content is *not* passed as a prop — an object prop would never reach the
+ * component through hydration (React only reconciles strings onto custom
+ * elements). The caller mounts the element and drives it through its setters
+ * from a callback ref, so all React needs to know about is `ref`.
+ *
+ * The alias is exported (rather than written inline) because the emitted `.d.ts`
+ * for a module augmentation can only name types that are themselves reachable
+ * from the declaration file.
+ */
+export type DfkElementProps = HTMLAttributes<HTMLElement>;
+declare module 'react' {
+    namespace JSX {
+        interface IntrinsicElements {
+            'dfk-hero': DfkElementProps;
+            'dfk-features': DfkElementProps;
+            'dfk-next-steps': DfkElementProps;
+            'dfk-sql': DfkElementProps;
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as e, i as t, n, r, t as i } from "./register-DKLiYs-F.js";
+export { e as DfkFeatures, t as DfkHero, r as DfkNextSteps, n as DfkSql, i as registerDfkElements };