@dooc-dev/dooc 0.0.0-stage → 0.0.1

package/dist/core/table-ui.d.ts

@@ -0,0 +1,2 @@
+/** Self-contained so the same controls work in the viewer and exported HTML. */
+export declare function mountTables(root: ParentNode): () => void;

package/dist/core/table-ui.js

@@ -0,0 +1,180 @@
+/** Self-contained so the same controls work in the viewer and exported HTML. */
+export function mountTables(root) {
+    const controller = new AbortController();
+    const mounted = new WeakMap();
+    const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
+    const initialize = () => {
+        for (const box of root.querySelectorAll(".data-table")) {
+            if (mounted.has(box))
+                continue;
+            const template = box.querySelector("[data-table-rows]");
+            const table = box.querySelector("table");
+            const header = box.dataset.tableMode === "header";
+            if (!template || !table)
+                continue;
+            const viewport = box.querySelector(".data-table-scroll");
+            const handle = box.querySelector(".data-table-resize");
+            if (viewport && handle) {
+                let drag;
+                const resize = (height) => {
+                    const max = Math.max(64, table.getBoundingClientRect().height + 2);
+                    const value = Math.round(Math.max(64, Math.min(height, max)));
+                    viewport.style.maxHeight = "none";
+                    viewport.style.height = `${value}px`;
+                    handle.setAttribute("aria-valuenow", String(value));
+                    handle.setAttribute("aria-valuemax", String(Math.round(max)));
+                };
+                handle.setAttribute("aria-valuemin", "64");
+                handle.addEventListener("focus", () => {
+                    handle.setAttribute("aria-valuenow", String(Math.round(viewport.getBoundingClientRect().height)));
+                    handle.setAttribute("aria-valuemax", String(Math.max(64, Math.round(table.getBoundingClientRect().height + 2))));
+                }, { signal: controller.signal });
+                handle.addEventListener("pointerdown", (event) => {
+                    if (event.button !== 0)
+                        return;
+                    drag = {
+                        y: event.clientY,
+                        height: viewport.getBoundingClientRect().height,
+                    };
+                    handle.setPointerCapture(event.pointerId);
+                    event.preventDefault();
+                }, { signal: controller.signal });
+                handle.addEventListener("pointermove", (event) => {
+                    if (drag)
+                        resize(drag.height + event.clientY - drag.y);
+                }, { signal: controller.signal });
+                handle.addEventListener("lostpointercapture", () => {
+                    drag = undefined;
+                }, { signal: controller.signal });
+                handle.addEventListener("keydown", (event) => {
+                    const height = viewport.getBoundingClientRect().height;
+                    if (event.key === "ArrowDown")
+                        resize(height + 32);
+                    else if (event.key === "ArrowUp")
+                        resize(height - 32);
+                    else if (event.key === "Home")
+                        resize(64);
+                    else if (event.key === "End")
+                        resize(table.getBoundingClientRect().height + 2);
+                    else
+                        return;
+                    event.preventDefault();
+                    event.stopPropagation();
+                }, { signal: controller.signal });
+            }
+            const rows = JSON.parse(template.content.textContent ?? "[]");
+            const key = `docs-table:${box.dataset.tableSource}:${box.dataset.tableMode}`;
+            let column = -1;
+            let descending = false;
+            try {
+                const saved = JSON.parse(localStorage.getItem(key) ?? "null");
+                if (Number.isInteger(saved?.column) && saved.column < (rows[0]?.length ?? 0))
+                    column = Math.max(-1, saved.column);
+                descending = saved?.descending === true;
+            }
+            catch {
+                // Storage is optional; source order and sorting remain usable.
+            }
+            const render = () => {
+                const label = box.querySelector("[data-table-column-label]")?.textContent ?? "Column";
+                const head = document.createElement("tr");
+                const number = document.createElement("th");
+                number.scope = "col";
+                number.textContent = "#";
+                head.append(number);
+                for (let index = 0; index < (rows[0]?.length ?? 0); index++) {
+                    const cell = document.createElement("th");
+                    cell.scope = "col";
+                    if (index === column)
+                        cell.setAttribute("aria-sort", descending ? "descending" : "ascending");
+                    const button = document.createElement("button");
+                    button.type = "button";
+                    button.dataset.tableSort = String(index);
+                    button.textContent = header
+                        ? rows[0]?.[index] || `${label} ${index + 1}`
+                        : `${label} ${index + 1}`;
+                    const mark = document.createElement("span");
+                    mark.className = "data-table-sort-mark";
+                    mark.setAttribute("aria-hidden", "true");
+                    mark.textContent = index === column && descending ? "↓" : "↑";
+                    button.append(mark);
+                    cell.append(button);
+                    head.append(cell);
+                }
+                table.tHead?.replaceChildren(head);
+                const data = rows.map((cells, index) => ({ cells, index })).slice(header ? 1 : 0);
+                if (column >= 0) {
+                    const numeric = data.every(({ cells }) => !cells[column]?.trim() ||
+                        /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(cells[column]?.trim() ?? ""));
+                    data.sort((a, b) => {
+                        const left = a.cells[column]?.trim() ?? "";
+                        const right = b.cells[column]?.trim() ?? "";
+                        if (!left || !right)
+                            return Number(!left) - Number(!right) || a.index - b.index;
+                        const order = numeric
+                            ? Number(left) - Number(right)
+                            : collator.compare(left, right);
+                        return (descending ? -order : order) || a.index - b.index;
+                    });
+                }
+                const body = document.createDocumentFragment();
+                for (const { cells, index } of data) {
+                    const row = document.createElement("tr");
+                    const number = document.createElement("th");
+                    number.scope = "row";
+                    number.textContent = String(index + 1);
+                    row.append(number);
+                    for (const text of cells) {
+                        const cell = document.createElement("td");
+                        cell.textContent = text;
+                        row.append(cell);
+                    }
+                    body.append(row);
+                }
+                table.tBodies[0]?.replaceChildren(body);
+            };
+            const persist = () => {
+                try {
+                    localStorage.setItem(key, JSON.stringify({ column, descending }));
+                }
+                catch {
+                    // Sorting also works without storage.
+                }
+                render();
+            };
+            box.addEventListener("click", (event) => {
+                const button = event.target.closest("button");
+                if (!button)
+                    return;
+                if (button.hasAttribute("data-table-sort")) {
+                    const next = Number(button.dataset.tableSort);
+                    if (column !== next) {
+                        column = next;
+                        descending = false;
+                    }
+                    else if (!descending)
+                        descending = true;
+                    else
+                        column = -1;
+                    persist();
+                    box.querySelector(`[data-table-sort="${next}"]`)?.focus({
+                        preventScroll: true,
+                    });
+                }
+            }, { signal: controller.signal });
+            mounted.set(box, render);
+            render();
+        }
+    };
+    initialize();
+    const observer = new MutationObserver(initialize);
+    observer.observe(root, { childList: true, subtree: true });
+    root.addEventListener("docs:ui-language", () => {
+        for (const box of root.querySelectorAll(".data-table"))
+            mounted.get(box)?.();
+    }, { signal: controller.signal });
+    return () => {
+        observer.disconnect();
+        controller.abort();
+    };
+}

package/dist/core/taxonomy.d.ts

@@ -0,0 +1,12 @@
+export declare const CODE_TEMPLATES: Readonly<Record<string, string>>;
+export declare const CODE_LANGS: readonly ["javascript", "typescript", "jsx", "tsx", "python", "java", "c", "cpp", "csharp", "go", "rust", "ruby", "php", "swift", "kotlin", "bash", "powershell", "html", "css", "json", "yaml", "toml", "sql", "markdown", "dockerfile", "diff", "graphql", "terraform", ...string[]];
+export type CodeLang = string;
+export declare const FM_REQUIRED: readonly ["title"];
+export declare const FM_OPTIONAL: readonly ["lang"];
+export interface Frontmatter {
+    title: string;
+    /** BCP 47 tag of the doc's language (language.ts). Omitted = the site default. */
+    lang?: string;
+}
+/** Display name of a doc (nav / headings / listings). Falls back if front-matter is broken. */
+export declare const docDisplayName: (fm: Frontmatter | undefined, fallback: string) => string;

package/dist/core/taxonomy.js

@@ -0,0 +1,49 @@
+// Vocabulary for semantic code fences, front-matter fields, and code languages.
+// Both compiler validation and viewer insert-completion read this.
+export const CODE_TEMPLATES = {
+    csv: "```csv\n<value>,<value>\n```",
+    tsv: "```tsv\n<value>\t<value>\n```",
+    mermaid: "```mermaid\nflowchart LR\n  A[<start>] --> B[<end>]\n```",
+    callouth: "```callouth <caption>\n- <item>\n```",
+    schemath: "```schemath <caption>\n### <group>\n<table>:\n  id: pk\n  <field>: fk(<ref_table>)\n\n<ref_table>:\n  id: pk\n```",
+    graphth: "```graphth <caption>\n[<id>]: <label>\n[<ref_id>]: <ref_label>\n\n[<id>] -> [<ref_id>]\n```",
+    termth: '```termth\nname: "<name>"\ndefinition: "<definition>"\n```',
+};
+// Default syntax-highlighting languages; additional grammars live in .dooc/code-languages/.
+export const CODE_LANGS = [
+    "javascript",
+    "typescript",
+    "jsx",
+    "tsx",
+    "python",
+    "java",
+    "c",
+    "cpp",
+    "csharp",
+    "go",
+    "rust",
+    "ruby",
+    "php",
+    "swift",
+    "kotlin",
+    "bash",
+    "powershell",
+    "html",
+    "css",
+    "json",
+    "yaml",
+    "toml",
+    "sql",
+    "markdown",
+    "dockerfile",
+    "diff",
+    "graphql",
+    "terraform",
+    ...Object.keys(CODE_TEMPLATES),
+];
+// Front-matter schema (the hierarchy's SoT is dooc.yaml, so it is not written in
+// front-matter; writing it there is an unknown-key error).
+export const FM_REQUIRED = ["title"];
+export const FM_OPTIONAL = ["lang"];
+/** Display name of a doc (nav / headings / listings). Falls back if front-matter is broken. */
+export const docDisplayName = (fm, fallback) => fm?.title ?? fallback;

package/dist/core/term-reference.d.ts

@@ -0,0 +1,5 @@
+export declare const isTermFile: (file: string) => boolean;
+/** Term links are local files relative to the docs root, just like file embeds. */
+export declare const parseTermReference: (url: string) => string | undefined;
+export declare const termFileUrl: (file: string) => string;
+export declare const termAnchor: (id: string) => string;

package/dist/core/term-reference.js

@@ -0,0 +1,19 @@
+import { parseFileReference } from "./textfile.js";
+export const isTermFile = (file) => /\.termth$/i.test(file);
+/** Term links are local files relative to the docs root, just like file embeds. */
+export const parseTermReference = (url) => {
+    if (!/\.termth(?:[?#]|$)/i.test(url))
+        return undefined;
+    const { file, range } = parseFileReference(url);
+    if (range !== undefined ||
+        /^(?:\/|[a-z][a-z\d+.-]*:)/i.test(file) ||
+        /[\\\0\r\n]/.test(file) ||
+        file.split("/").includes(".."))
+        throw new Error("Term links require a relative .termth file inside the docs root, without a query or fragment");
+    return file
+        .split("/")
+        .filter((part) => part && part !== ".")
+        .join("/");
+};
+export const termFileUrl = (file) => file.split("/").map(encodeURIComponent).join("/").replaceAll("(", "%28").replaceAll(")", "%29");
+export const termAnchor = (id) => `term-${encodeURIComponent(id)}`;

package/dist/core/terms-ui.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Sorts terms listings in place on `[data-dict-sort]` change. The A → Z rank is computed at
+ * render time by the doc language's rule (html.ts → data-sort-order), so no language logic runs
+ * here. Delegation keeps sorting working after preview/editor content replacement.
+ */
+export declare function mountTerms(root: ParentNode): () => void;

package/dist/core/terms-ui.js

@@ -0,0 +1,22 @@
+/**
+ * Sorts terms listings in place on `[data-dict-sort]` change. The A → Z rank is computed at
+ * render time by the doc language's rule (html.ts → data-sort-order), so no language logic runs
+ * here. Delegation keeps sorting working after preview/editor content replacement.
+ */
+export function mountTerms(root) {
+    const controller = new AbortController();
+    root.addEventListener("change", (event) => {
+        const select = event.target;
+        if (!(select instanceof HTMLSelectElement) || !select.matches("[data-dict-sort]"))
+            return;
+        const list = select.closest(".terms")?.querySelector(".dict");
+        if (!list)
+            return;
+        const key = select.value === "source" ? "sourceOrder" : "sortOrder";
+        const sign = select.value === "desc" ? -1 : 1;
+        const cards = Array.from(list.querySelectorAll(".dict-card"));
+        cards.sort((a, b) => sign * (Number(a.dataset[key]) - Number(b.dataset[key])));
+        list.append(...cards);
+    }, { signal: controller.signal });
+    return () => controller.abort();
+}

package/dist/core/textfile.d.ts

@@ -0,0 +1,10 @@
+export declare const isRemoteTextfile: (file: string) => boolean;
+/** GitHub-style, one-based inclusive line numbers. */
+export declare const parseTextfileRange: (range: string) => [number, number];
+/** Split before decoding so an encoded # or ? remains part of a local filename. */
+export declare const parseFileReference: (source: string) => {
+    file: string;
+    range?: string;
+};
+/** The source stays intact for tooltips; only the visible label and language use this name. */
+export declare const textfileName: (file: string) => string;

package/dist/core/textfile.js

@@ -0,0 +1,39 @@
+export const isRemoteTextfile = (file) => /^https?:\/\//i.test(file);
+/** GitHub-style, one-based inclusive line numbers. */
+export const parseTextfileRange = (range) => {
+    const match = /^#L([1-9]\d*)(?:-L([1-9]\d*))?$/.exec(range);
+    const start = Number(match?.[1]);
+    const end = Number(match?.[2] ?? match?.[1]);
+    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || end < start)
+        throw new Error("Use #L10 or #L10-L20 with positive, ascending line numbers");
+    return [start, end];
+};
+/** Split before decoding so an encoded # or ? remains part of a local filename. */
+export const parseFileReference = (source) => {
+    const hash = source.indexOf("#");
+    const path = hash < 0 ? source : source.slice(0, hash);
+    if (!path.trim())
+        throw new Error("File path is required");
+    const remote = isRemoteTextfile(path);
+    if (!remote && path.includes("?"))
+        throw new Error("Local file references do not support query parameters");
+    return {
+        file: remote ? path : decodeURIComponent(path),
+        ...(hash < 0 ? {} : { range: decodeURIComponent(source.slice(hash)) }),
+    };
+};
+/** The source stays intact for tooltips; only the visible label and language use this name. */
+export const textfileName = (file) => {
+    if (!isRemoteTextfile(file))
+        return file.split("/").at(-1) ?? file;
+    try {
+        const url = new URL(file);
+        const path = url.pathname.endsWith(".git") && url.hash.includes(":")
+            ? url.hash.slice(url.hash.indexOf(":") + 1)
+            : url.pathname;
+        return decodeURIComponent(path.split("/").at(-1) || url.hostname);
+    }
+    catch {
+        return file;
+    }
+};

package/dist/core/theme-variants.d.ts

@@ -0,0 +1,3 @@
+export declare const themeVariantFile: (file: string, theme: string) => string;
+/** A pane selects its own variant; an absent variant falls back to the original content. */
+export declare const mountThemeVariants: (doc: Document) => void;

package/dist/core/theme-variants.js

@@ -0,0 +1,37 @@
+import { localFile } from "./files.js";
+export const themeVariantFile = (file, theme) => {
+    if (!localFile(file) || !/^[a-z][a-z0-9-]*$/.test(theme))
+        throw new Error("Expected a local file and a theme name");
+    return `themes/${theme}/${file}`;
+};
+/** A pane selects its own variant; an absent variant falls back to the original content. */
+export const mountThemeVariants = (doc) => {
+    const media = matchMedia("(prefers-color-scheme: dark)");
+    const apply = () => {
+        for (const group of doc.querySelectorAll("[data-theme-variants]")) {
+            const choice = group.closest("[data-theme]")?.dataset.theme;
+            const theme = !choice || choice === "auto" ? (media.matches ? "dark" : "light") : choice;
+            const children = [...group.children];
+            const selected = children.find((child) => child.dataset.themeVariant === theme) ??
+                children.find((child) => child.dataset.themeVariant === "");
+            for (const child of children) {
+                const hidden = child !== selected;
+                if (child.hidden === hidden)
+                    continue;
+                child.hidden = hidden;
+                // Recreate hidden frame contexts so revealed SVGs receive a live viewport.
+                if (!hidden)
+                    for (const frame of child.querySelectorAll("iframe"))
+                        frame.replaceWith(frame.cloneNode(true));
+            }
+        }
+    };
+    new MutationObserver(apply).observe(doc.documentElement, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["data-theme"],
+    });
+    media.addEventListener("change", apply);
+    apply();
+};

package/dist/core/toc-ui.d.ts

@@ -0,0 +1,2 @@
+/** Self-contained so live previews and standalone HTML share the same navigation. */
+export declare function mountToc(doc: Document): () => void;

package/dist/core/toc-ui.js

@@ -0,0 +1,161 @@
+/** Self-contained so live previews and standalone HTML share the same navigation. */
+export function mountToc(doc) {
+    const controller = new AbortController();
+    const mounted = new Map();
+    let sequence = 0;
+    let frame = 0;
+    const schedule = () => {
+        if (frame)
+            return;
+        frame = requestAnimationFrame(() => {
+            frame = 0;
+            for (const { update } of mounted.values())
+                update();
+        });
+    };
+    const resize = new ResizeObserver(schedule);
+    const initialize = () => {
+        for (const [nav, { article, dispose }] of mounted)
+            if (!nav.isConnected || !article.isConnected) {
+                dispose();
+                resize.unobserve(article);
+                mounted.delete(nav);
+                nav.remove();
+            }
+        for (const nav of doc.querySelectorAll(".in-toc")) {
+            if (mounted.has(nav))
+                continue;
+            const article = nav.closest("article");
+            const seek = nav.querySelector(".toc-seek");
+            const button = nav.querySelector(".toc-current");
+            const list = nav.querySelector("ul");
+            if (!article || !seek || !button || !list)
+                continue;
+            const pane = nav.closest(".preview-pane");
+            const scroller = pane ?? doc.scrollingElement;
+            if (!scroller)
+                continue;
+            const header = (pane ?? article.parentElement)?.querySelector(":scope > .pane-actions, :scope > .page-actions");
+            header?.prepend(nav);
+            const listeners = new AbortController();
+            const options = { signal: listeners.signal };
+            list.id = `toc-options-${++sequence}`;
+            button.setAttribute("aria-controls", list.id);
+            const sections = [...nav.querySelectorAll("[data-toc-target]")]
+                .map((link) => ({
+                link,
+                heading: article.querySelector(`#${CSS.escape(link.dataset.tocTarget ?? "")}`),
+            }))
+                .filter((section) => section.heading !== null);
+            let active;
+            const update = () => {
+                const maximum = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
+                const progress = maximum
+                    ? Math.max(0, Math.min(1, scroller.scrollTop / maximum))
+                    : 0;
+                seek.disabled = maximum === 0;
+                seek.value = String(Math.round(progress * 1000));
+                seek.style.setProperty("--toc-progress", `${progress * 100}%`);
+                const top = (header ?? nav).getBoundingClientRect().bottom + 20;
+                let current = sections[0];
+                for (const section of sections)
+                    if ((section.heading?.getBoundingClientRect().top ?? Infinity) <= top)
+                        current = section;
+                if (progress === 1)
+                    current = sections.at(-1);
+                seek.setAttribute("aria-valuetext", `${current?.link.textContent ?? ""} · ${Math.round(progress * 100)}%`);
+                if (current?.link === active)
+                    return;
+                active?.removeAttribute("aria-current");
+                active = current?.link;
+                if (active) {
+                    active.setAttribute("aria-current", "location");
+                    button.textContent = button.title = active.textContent ?? "";
+                }
+            };
+            button.addEventListener("click", () => {
+                if (list.matches(":popover-open")) {
+                    list.hidePopover();
+                    return;
+                }
+                const rect = button.getBoundingClientRect();
+                const width = Math.min(240, innerWidth - 16);
+                list.style.width = `${width}px`;
+                list.style.left = `${Math.max(8, Math.min(rect.left, innerWidth - width - 8))}px`;
+                list.style.top = `${rect.bottom + 6}px`;
+                list.showPopover();
+                list.scrollTop = Math.max(0, (active?.offsetTop ?? 0) - list.clientHeight / 2);
+                active?.focus({ preventScroll: true });
+            }, options);
+            list.addEventListener("toggle", () => {
+                button.setAttribute("aria-expanded", String(list.matches(":popover-open")));
+            }, options);
+            list.addEventListener("keydown", (event) => {
+                const index = sections.findIndex(({ link }) => link === doc.activeElement);
+                if (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) {
+                    event.preventDefault();
+                    const next = event.key === "Home"
+                        ? 0
+                        : event.key === "End"
+                            ? sections.length - 1
+                            : (index +
+                                (event.key === "ArrowDown" ? 1 : sections.length - 1)) %
+                                sections.length;
+                    sections[next]?.link.focus();
+                }
+                if (event.key === "Escape")
+                    button.focus({ preventScroll: true });
+            }, options);
+            list.addEventListener("click", (event) => {
+                if (event.button !== 0 ||
+                    event.metaKey ||
+                    event.ctrlKey ||
+                    event.shiftKey ||
+                    event.altKey)
+                    return;
+                const link = event.target.closest("[data-toc-target]");
+                const heading = sections.find((section) => section.link === link)?.heading;
+                if (!heading)
+                    return;
+                list.hidePopover();
+                button.focus({ preventScroll: true });
+                if (pane) {
+                    // Pane activation is asynchronous, so resolve the clicked pane directly.
+                    event.preventDefault();
+                    heading.scrollIntoView({ block: "start" });
+                }
+            }, options);
+            seek.addEventListener("input", () => {
+                const maximum = Math.max(0, scroller.scrollHeight - scroller.clientHeight);
+                scroller.scrollTo({
+                    top: (Number(seek.value) / 1000) * maximum,
+                    behavior: "instant",
+                });
+                schedule();
+            }, options);
+            mounted.set(nav, { article, update, dispose: () => listeners.abort() });
+            resize.observe(article);
+        }
+        schedule();
+    };
+    const observer = new MutationObserver(initialize);
+    observer.observe(doc.documentElement, { childList: true, subtree: true });
+    doc.addEventListener("scroll", schedule, {
+        capture: true,
+        passive: true,
+        signal: controller.signal,
+    });
+    doc.addEventListener("load", schedule, { capture: true, signal: controller.signal });
+    doc.addEventListener("docs:font-change", schedule, { signal: controller.signal });
+    window.addEventListener("resize", schedule, { signal: controller.signal });
+    initialize();
+    return () => {
+        controller.abort();
+        observer.disconnect();
+        resize.disconnect();
+        cancelAnimationFrame(frame);
+        for (const { dispose } of mounted.values())
+            dispose();
+        mounted.clear();
+    };
+}

package/dist/core/video-ui.d.ts

@@ -0,0 +1,2 @@
+/** Self-contained so playback controls also work in exported HTML. */
+export declare function mountVideos(doc: Document): void;