@dooc-dev/dooc 0.0.0-stage → 0.0.2

package/dist/viewer/search.js

@@ -0,0 +1,358 @@
+import { inlineSegmenter } from "../core/inline.js";
+import { docPath } from "../core/routing.js";
+import { docDisplayName } from "../core/taxonomy.js";
+export const searchIndex = (site) => {
+    const parents = new Set(site.entries.map((entry) => entry.parent));
+    const segments = inlineSegmenter({ terms: site.ctx.terms });
+    const plain = (text) => segments(text)
+        .map((part) => part.text)
+        .join("");
+    const list = (items) => items
+        .map((item) => typeof item === "string"
+        ? plain(item)
+        : "blocks" in item
+            ? item.blocks.map(text).join(" ")
+            : `${plain(item.text)} ${list(item.children)}`)
+        .join(" ");
+    const text = (block) => {
+        switch (block.type) {
+            case "themeVariants":
+                return text(block.default);
+            case "external":
+                return `${block.alt ?? ""} ${block.url}`;
+            case "h":
+            case "p":
+                return plain(block.text);
+            case "quote":
+                return block.blocks.map(text).join(" ");
+            case "list":
+                return list(block.items);
+            case "code":
+                return [block.filename ?? "", ...block.lines].join(" ");
+            case "table":
+                return [block.caption ?? "", ...block.headers, ...block.rows.flat()]
+                    .map(plain)
+                    .join(" ");
+            case "callout":
+                return [
+                    block.title ?? "",
+                    ...block.body.map((part) => part.type === "p" ? plain(part.text) : list(part.items)),
+                ].join(" ");
+            case "term":
+                return [
+                    block.entry.name,
+                    block.entry.description ?? "",
+                    block.entry.definition,
+                ].join(" ");
+            case "figureRef":
+                return block.caption ?? site.ctx.figures.get(block.name)?.title ?? block.name;
+            case "graph":
+            case "schemaGraph":
+                return `${block.caption ?? ""} ${block.source ?? ""}`;
+            case "figures":
+                return [...site.ctx.figures.values()]
+                    .map((figure) => `${figure.title ?? figure.name} ${figure.desc ?? ""}`)
+                    .join(" ");
+        }
+    };
+    return site.entries.flatMap((entry) => {
+        const base = {
+            path: docPath(site.entries, entry.id),
+            file: entry.file,
+            folder: parents.has(entry.id),
+            title: docDisplayName(entry.frontmatter, entry.id),
+        };
+        let section = {
+            ...base,
+            heading: "",
+            anchor: "",
+            text: "",
+        };
+        const sections = [section];
+        for (const block of entry.blocks) {
+            if (block.type === "h") {
+                section = { ...base, heading: plain(block.text), anchor: block.slug, text: "" };
+                sections.push(section);
+            }
+            else
+                section.text += ` ${text(block)}`;
+        }
+        return sections.map((item) => ({ ...item, text: item.text.replace(/\s+/g, " ").trim() }));
+    });
+};
+// Self-contained: the viewer embeds this function in offline HTML as well.
+export const searchSections = (index, query, currentPath = "") => {
+    const normalize = (text) => text.normalize("NFKC").toLowerCase();
+    const words = [...new Set(normalize(query).trim().split(/\s+/).filter(Boolean))];
+    if (!words.length)
+        return [];
+    const seen = new Set();
+    return index
+        .flatMap((section) => {
+        const title = normalize(section.title);
+        const heading = normalize(section.heading);
+        const text = section.text.normalize("NFKC");
+        const body = text.toLowerCase();
+        const name = section.anchor ? "" : normalize(`${section.file} ${section.path}`);
+        const all = `${title} ${heading} ${body} ${name}`;
+        if (!words.every((word) => all.includes(word)))
+            return [];
+        if (section.anchor && !words.some((word) => `${heading} ${body}`.includes(word)))
+            return [];
+        const score = (title === words.join(" ") ? 100 : 0) +
+            words.reduce((sum, word) => sum +
+                (title.includes(word) ? 10 : 0) +
+                (name.includes(word) ? 10 : 0) +
+                (heading.includes(word) ? 5 : 0), 0);
+        const matches = words.map((word) => body.indexOf(word)).filter((at) => at >= 0);
+        const start = Math.max(0, (matches.length ? Math.min(...matches) : 0) - 45);
+        const snippet = `${start ? "…" : ""}${text.slice(start, start + 180)}${text.length > start + 180 ? "…" : ""}`;
+        return [{ ...section, snippet, score }];
+    })
+        .sort((a, b) => Number(b.path === currentPath) - Number(a.path === currentPath) ||
+        b.score - a.score)
+        .filter((hit) => {
+        if (hit.path === currentPath)
+            return true;
+        if (seen.has(hit.path))
+            return false;
+        seen.add(hit.path);
+        return true;
+    });
+};
+export const SEARCH_LABELS = [
+    "Search documents",
+    "No results",
+    "Searching…",
+    "Could not load search. Press Ctrl+F to retry.",
+    "{count} results",
+    "Showing {shown} of {count} results",
+    "Folder",
+    "Move search",
+    "Resize search",
+];
+// Embedded by page(); keep browser behavior independent of the editor bundle.
+export const mountSearch = (initial, search, labels, published) => {
+    const dialog = document.createElement("dialog");
+    dialog.id = "doc-search";
+    dialog.setAttribute("aria-label", labels["Search documents"] ?? "Search documents");
+    dialog.innerHTML = `<div class="search-head"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><circle cx="10.5" cy="10.5" r="6.5"/><path d="m16 16 4 4"/></svg><input id="doc-search-input" type="search" role="combobox" aria-autocomplete="list" aria-expanded="false" aria-controls="doc-search-results" autocomplete="off" spellcheck="false"></div><div class="search-status" role="status" aria-live="polite"></div><div id="doc-search-results" role="listbox"></div><div class="search-grip search-grip-left" role="button" tabindex="0"></div><div class="search-grip search-grip-right" role="button" tabindex="0"></div><div class="search-resize" role="button" tabindex="0"></div>`;
+    document.body.append(dialog);
+    const input = dialog.querySelector("input");
+    const results = dialog.querySelector("#doc-search-results");
+    const status = dialog.querySelector(".search-status");
+    const t = (key, values = {}) => {
+        const translate = window
+            .__docsTranslate;
+        return (translate?.(key) ?? labels[key] ?? key).replace(/\{(\w+)\}/g, (token, name) => String(values[name] ?? token));
+    };
+    let index = initial;
+    let selected = 0;
+    let revision = 0;
+    let loading = false;
+    let failed = false;
+    let language = "";
+    const currentPath = () => published
+        ? location.hash.slice(1).split(/[?#]/)[0] || initial[0]?.path || ""
+        : location.pathname;
+    const select = (position) => {
+        const items = [...results.querySelectorAll("a")];
+        selected = items.length ? (position + items.length) % items.length : 0;
+        items.forEach((item, i) => {
+            item.setAttribute("aria-selected", String(i === selected));
+        });
+        const active = items[selected];
+        if (active) {
+            input.setAttribute("aria-activedescendant", active.id);
+            active.scrollIntoView({ block: "nearest" });
+        }
+        else
+            input.removeAttribute("aria-activedescendant");
+    };
+    const render = () => {
+        const hits = search(index, input.value, currentPath());
+        results.replaceChildren();
+        dialog.classList.toggle("search-filled", input.value.length > 0);
+        for (const [i, hit] of hits.slice(0, 60).entries()) {
+            const link = document.createElement("a");
+            link.id = `doc-search-result-${i}`;
+            link.setAttribute("role", "option");
+            link.tabIndex = -1;
+            link.href = `${published ? "#" : ""}${hit.path}${!published && language ? `?lang=${encodeURIComponent(language)}` : ""}${hit.anchor ? `#${encodeURIComponent(hit.anchor)}` : ""}`;
+            const meta = document.createElement("div");
+            meta.className = "search-meta";
+            const folder = hit.folder && !hit.anchor;
+            const type = document.createElement("small");
+            type.textContent = folder
+                ? t("Folder")
+                : (hit.file.split(".").pop()?.toUpperCase() ?? "");
+            const path = document.createElement("small");
+            path.className = "search-path";
+            path.textContent = folder ? `${hit.path}/` : hit.file;
+            path.title = path.textContent;
+            meta.append(type, path);
+            const title = document.createElement("strong");
+            title.textContent = `${hit.title}${hit.heading ? ` › ${hit.heading}` : ""}`;
+            const snippet = document.createElement("span");
+            snippet.textContent = hit.snippet;
+            link.append(meta, title, snippet);
+            results.append(link);
+        }
+        status.textContent = loading
+            ? t("Searching…")
+            : failed
+                ? t("Could not load search. Press Ctrl+F to retry.")
+                : !input.value.trim()
+                    ? ""
+                    : !hits.length
+                        ? t("No results")
+                        : hits.length > 60
+                            ? t("Showing {shown} of {count} results", { shown: 60, count: hits.length })
+                            : t("{count} results", { count: hits.length });
+        status.classList.toggle("search-count", !loading && !failed && hits.length > 0);
+        input.setAttribute("aria-expanded", String(hits.length > 0));
+        select(0);
+    };
+    const localize = () => {
+        dialog.setAttribute("aria-label", t("Search documents"));
+        input.setAttribute("aria-label", t("Search documents"));
+        for (const handle of dialog.querySelectorAll(".search-grip, .search-resize")) {
+            handle.title = t(handle.classList.contains("search-resize") ? "Resize search" : "Move search");
+            handle.setAttribute("aria-label", handle.title);
+        }
+        render();
+    };
+    const position = (rect, dx, dy, resize = false) => {
+        const clamp = (value, min, max) => Math.max(Math.min(min, max), Math.min(value, max));
+        const width = clamp(rect.width + (resize ? dx : 0), 280, innerWidth - 16);
+        const height = clamp(rect.height + (resize ? dy : 0), 56, innerHeight - 16);
+        const left = clamp(rect.left + (resize ? 0 : dx), 8, innerWidth - width - 8);
+        const top = clamp(rect.top + (resize ? 0 : dy), 8, innerHeight - height - 8);
+        Object.assign(dialog.style, {
+            left: `${left}px`,
+            top: `${top}px`,
+            right: "auto",
+            margin: "0",
+            width: `${width}px`,
+            maxHeight: `${innerHeight - top - 8}px`,
+        });
+        if (resize || dialog.style.height)
+            dialog.style.height = `${height}px`;
+    };
+    for (const handle of dialog.querySelectorAll(".search-grip, .search-resize")) {
+        const resize = handle.classList.contains("search-resize");
+        let drag;
+        handle.addEventListener("pointerdown", (event) => {
+            if (event.button !== 0 || drag)
+                return;
+            event.preventDefault();
+            handle.focus();
+            drag = {
+                id: event.pointerId,
+                x: event.clientX,
+                y: event.clientY,
+                rect: dialog.getBoundingClientRect(),
+            };
+            handle.setPointerCapture(event.pointerId);
+        });
+        handle.addEventListener("pointermove", (event) => {
+            if (drag?.id === event.pointerId)
+                position(drag.rect, event.clientX - drag.x, event.clientY - drag.y, resize);
+        });
+        const stop = () => {
+            drag = undefined;
+        };
+        handle.addEventListener("pointerup", stop);
+        handle.addEventListener("pointercancel", stop);
+        handle.addEventListener("lostpointercapture", stop);
+        handle.addEventListener("keydown", (event) => {
+            if (!event.key.startsWith("Arrow"))
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            const step = event.shiftKey ? 40 : 10;
+            position(dialog.getBoundingClientRect(), event.key === "ArrowRight" ? step : event.key === "ArrowLeft" ? -step : 0, event.key === "ArrowDown" ? step : event.key === "ArrowUp" ? -step : 0, resize);
+        });
+    }
+    window.addEventListener("resize", () => {
+        if (dialog.open)
+            position(dialog.getBoundingClientRect(), 0, 0);
+    });
+    const open = async () => {
+        const request = ++revision;
+        language =
+            JSON.parse(document.getElementById("boot")?.textContent || "null")?.contentLanguage ??
+                new URL(location.href).searchParams.get("lang") ??
+                "";
+        if (!dialog.open)
+            dialog.show();
+        if (dialog.style.left)
+            position(dialog.getBoundingClientRect(), 0, 0);
+        input.focus();
+        input.select();
+        failed = false;
+        loading = !published;
+        if (!published)
+            index = [];
+        render();
+        if (published)
+            return;
+        try {
+            const response = await fetch(`/api/search${language ? `?lang=${encodeURIComponent(language)}` : ""}`);
+            if (!response.ok)
+                throw new Error(String(response.status));
+            const data = (await response.json());
+            if (request !== revision)
+                return;
+            index = data;
+        }
+        catch {
+            if (request !== revision)
+                return;
+            failed = true;
+        }
+        loading = false;
+        render();
+    };
+    document.addEventListener("keydown", (event) => {
+        if ((event.ctrlKey || event.metaKey) &&
+            !event.altKey &&
+            !event.shiftKey &&
+            event.key.toLowerCase() === "f") {
+            event.preventDefault();
+            event.stopPropagation();
+            if (document.querySelector(":modal"))
+                return;
+            void open();
+        }
+    }, true);
+    input.addEventListener("input", render);
+    input.addEventListener("keydown", (event) => {
+        if (event.isComposing)
+            return;
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+            select(selected + (event.key === "ArrowDown" ? 1 : -1));
+        }
+        else if (event.key === "Enter") {
+            event.preventDefault();
+            results.querySelector('[aria-selected="true"]')?.click();
+        }
+    });
+    results.addEventListener("click", (event) => {
+        if (event.target.closest("a"))
+            dialog.close();
+    });
+    dialog.addEventListener("keydown", (event) => {
+        if (event.key === "Escape" && !event.isComposing) {
+            event.preventDefault();
+            dialog.close();
+        }
+    });
+    document.addEventListener("pointerdown", (event) => {
+        if (dialog.open && !dialog.contains(event.target))
+            dialog.close();
+    });
+    document.addEventListener("docs:ui-language", localize);
+    localize();
+};

package/dist/viewer/serve.d.ts

@@ -0,0 +1,210 @@
+import { type ProjectFont } from "../compiler/fonts.js";
+import type { LanguageRegistration } from "shiki/core";
+import { type Compiled } from "../compiler/compile.js";
+import { assembleDoc } from "../compiler/ops.js";
+import { type Block, type TocEntry } from "../core/blocks.js";
+import type { TermEntry } from "../core/content-types.js";
+import { type RenderCtx } from "../core/html.js";
+import { type LanguageAdapter } from "../core/language.js";
+import { type PreviewSettings } from "../core/previewers.js";
+import { type Frontmatter } from "../core/taxonomy.js";
+import { type WorkspaceSource } from "../core/workspace.js";
+import { type FilePreviewResults } from "./file-references.js";
+import { type ViewerRuntime } from "./plugin-config.js";
+export type ServeMode = "preview" | "edit";
+/**
+ * One doc in the viewer = a view model combining the compiler's CompiledDoc (rendering) and
+ * DocSource (extra info for editing).
+ * file is `<id>.md` (= same shape as the save API's file parameter; CompiledDoc.file minus the
+ * content/ prefix).
+ */
+export interface Entry {
+    id: string;
+    translatedLanguages?: string[];
+    /** Parent doc id (omitted = top level). */
+    parent?: string;
+    file: string;
+    sourceFile?: string;
+    iconFile?: string;
+    frontmatter: Frontmatter | undefined;
+    /** Resolved language (front-matter `lang`, else the site default). */
+    lang: string;
+    /** Source md without the front-matter (the editor's initial value). */
+    body: string;
+    blocks: Block[];
+    toc: TocEntry[];
+    /**
+     * For the editor's correspondence display: body-relative start line of each block (same
+     * index as blocks).
+     */
+    blockLines: number[];
+    /**
+     * Full source on disk (including front-matter). Used as the base for the editor's
+     * external-change detection.
+     */
+    raw: string;
+    /** Validation errors for this doc (the compiler's DocSource.errors). */
+    errors: string[];
+    /** Icon for the sidebar (full svg, 1:1). */
+    icon?: string;
+    /** Names of the figures the body references (Resources' "used in"). */
+    figureRefs?: string[];
+    termRefs?: string[];
+    terms?: TermEntry[];
+}
+export interface Site {
+    fonts?: readonly ProjectFont[];
+    workspace?: WorkspaceSource;
+    filePaths?: readonly string[];
+    previews?: PreviewSettings;
+    title?: string;
+    icon?: string;
+    codeLanguages?: string[];
+    codeGrammars?: LanguageRegistration[];
+    contentLanguage?: string;
+    /** Display order (pre-order traversal of the manifest). */
+    entries: Entry[];
+    ctx: RenderCtx;
+    /** Errors not tied to a doc (the compiler's siteErrors). Shown on every page. */
+    errors: string[];
+    /** Language adapters (docs.config.mjs + built-ins); each doc renders with its own. */
+    languages: readonly LanguageAdapter[];
+    /** Site default language. */
+    defaultLang: string;
+    /** Declared site languages, when the manifest restricts the language picker. */
+    contentLanguages?: readonly string[];
+    themes?: readonly ("light" | "dark")[];
+}
+/** Compile result → viewer Site (shared by the server's per-request path and one-off publish). */
+export declare const siteFrom: ({ title, icon, docs, terms, figures, sources, siteErrors, defaultLang, previews, contentLanguages, themes, }: Compiled, languages?: readonly LanguageAdapter[]) => Site;
+export declare const filePreviewResults: (entry: Entry, site: Site) => FilePreviewResults;
+/** Renders only the requested doc, not every doc in site.entries. */
+export declare const renderEntryHtml: (site: Site, entry: Entry) => {
+    html: string;
+    errors: string[];
+};
+/** Compiles + renders one source (its current content on disk) (implements `/api/doc`). */
+export declare const renderDocFile: (site: Site, file: string, raw: string) => {
+    gitBase: string | null;
+    raw: string;
+    frontmatter: Frontmatter | undefined;
+    body: string;
+    html: string;
+    errors: string[];
+    toc: TocEntry[];
+    blockLines: number[];
+    filePreviews: FilePreviewResults;
+    previews?: PreviewSettings;
+    sourceFile?: string;
+};
+/** Response for `GET /api/doc?file=<id>.md` (status + body). mode === "edit" only. */
+export declare const docQueryResponse: (site: Site, file: unknown) => {
+    status: number;
+    body: unknown;
+};
+export { assembleDoc };
+/** Client JSON → Frontmatter (keeps supported fields and drops empty optional values). */
+export declare const sanitizeFrontmatter: (v: unknown) => Frontmatter;
+/**
+ * Compares the base the editor started from (the disk source the client last read) with the
+ * current disk source to tell whether it was rewritten externally (direct edit / git etc.)
+ * without the editor knowing.
+ * A client that sends no base (no baseRaw) can't be judged, so false (= overwrite).
+ */
+export declare const isExternallyModified: (baseRaw: unknown, currentRaw: string) => boolean;
+/**
+ * Validates the write target path — rejects anything other than `<id>.md` (directly under
+ * content/), including traversal.
+ */
+export declare const resolveContentFile: (rel: unknown) => {
+    id: string;
+    name: string;
+    abs: string;
+} | undefined;
+export declare const navGroupsHtml: (mode: ServeMode, site: Site, currentId?: string, currentRes?: string) => string;
+export declare const textfilePreviewHtml: (site: Site, file: string, source: string) => string;
+export declare const textfilePreviewErrors: (site: Site, file: string, source: string) => string[];
+export declare const resourcesMain: (site: Site, rest: string) => {
+    title: string;
+    main: string;
+    sourceFile?: string;
+} | undefined;
+/**
+ * Turns the whole Site into a single HTML file readable without a server (everything embedded,
+ * down to figures / terms / schema graph JS). Each doc is held in a
+ * <template> and switched via hash routes.
+ */
+export declare const publishHtml: (site: Site, graphJs: string, title?: string, codeJs?: string, mode?: "static" | "network") => string;
+/**
+ * Boot data for the client (edit-client.ts) — the same shape is passed for the initial render and
+ * on doc switch. Insertion happens via the client's in-editor autocomplete (`/` palette), so the
+ * candidate data (figures / docs / terms) is passed here, plus blockLines for the correspondence
+ * display.
+ */
+export interface EditorBoot {
+    gitBase: string | null;
+    filePreviews: FilePreviewResults;
+    previews?: PreviewSettings;
+    siteTitle?: string;
+    siteIcon?: string;
+    contentLanguage?: string;
+    sourceLanguage?: string;
+    docLanguage?: string;
+    translatedLanguages?: string[];
+    /** `<id>.md` (the save API's key). */
+    file: string;
+    sourceFile?: string;
+    /** Resolution key for published URLs. */
+    docId: string;
+    title: string;
+    path: string;
+    body: string;
+    figures: string[];
+    codeLanguages: readonly string[];
+    docs: {
+        ref: string;
+        title: string;
+    }[];
+    terms: TermEntry[];
+    blockLines: number[];
+    /** Full source on disk (the base for external-change detection). */
+    baseRaw: string;
+    /** Data URI of the sidebar icon (null if none). */
+    icon: string | null;
+    /** Site default language (used for lint when the `lang` field is left empty). */
+    defaultLang: string;
+    /** Language of the CodeMirror content's browser spellcheck (the doc language's adapter). */
+    spellcheckLang: string;
+}
+export declare const languageFieldHtml: (defaultLang: string, language?: string, translatedLanguages?: readonly string[], declaredLanguages?: readonly string[]) => string;
+export declare const editorBoot: (entry: Entry, site: Site) => EditorBoot;
+/**
+ * Response for `GET /api/page?route=/<ancestor/.../docId>` (status + body). mode === "edit" only.
+ * The diff for doing edit's doc switch via client-side navigation (= keep scroll position /
+ * search term / open state without rebuilding the sidebar DOM); it returns only what the client
+ * replaces: main html + the panel's variable parts (file name / front-matter fields) + the new
+ * doc's boot.
+ * File views replace the central workspace while retaining the current editor.
+ */
+export declare const pageDataResponse: (site: Site, path: unknown) => {
+    status: number;
+    body: unknown;
+};
+/** Cache of entry name → { js, etag }. clear() is called on HMR "client" notifications
+ * (changes to edit-client.ts / the schema graph interaction layer) (= invalidation is
+ * startServer's job; this is just the container). */
+export interface BundleCache {
+    get: (entry: string, build: () => Promise<string>) => Promise<{
+        js: string;
+        etag: string;
+    }>;
+    clear: () => void;
+}
+export declare const createBundleCache: () => BundleCache;
+/** Client bundle (src/<entry> as an IIFE). Sourcemap for the server, minified for publish. */
+export declare const bundleClient: (entry: string, publish?: boolean) => Promise<string>;
+export declare const startServer: (mode: ServeMode, port?: number, pluginModule?: string, startup?: {
+    file?: string;
+    data?: string;
+    login?: string;
+}) => Promise<ViewerRuntime>;