@classic-homes/theme-docs 0.1.0 → 0.2.0

package/dist/lib/components/enhance.js

@@ -0,0 +1,179 @@
+/**
+ * Progressive enhancements for rendered markdown. Call them once the HTML is in the DOM
+ * (e.g. from an `$effect`); each returns a cleanup function that undoes its changes.
+ */
+const COPY_ICON = '<svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>';
+const CHECK_ICON = '<svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>';
+/**
+ * Add a "Copy code" button to every highlighted code block under `root`, as Docusaurus
+ * does. A polite live region announces "Copied" for screen readers.
+ *
+ * @example
+ * ```ts
+ * $effect(() => enhanceCodeBlocks(article));
+ * ```
+ */
+export function enhanceCodeBlocks(root) {
+    const added = [];
+    const wrapped = [];
+    const timers = [];
+    const status = document.createElement('span');
+    status.className = 'docs-sr-only';
+    status.setAttribute('role', 'status');
+    status.setAttribute('aria-live', 'polite');
+    root.appendChild(status);
+    for (const pre of root.querySelectorAll('pre.shiki')) {
+        let wrapper = pre.parentElement;
+        if (!wrapper?.classList.contains('code-block-wrapper')) {
+            wrapper = document.createElement('div');
+            wrapper.className = 'code-block-wrapper';
+            pre.replaceWith(wrapper);
+            wrapper.appendChild(pre);
+            wrapped.push(wrapper);
+        }
+        if (wrapper.querySelector(':scope > .code-copy-button'))
+            continue;
+        wrapper.classList.add('has-copy-button');
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'code-copy-button';
+        button.setAttribute('aria-label', 'Copy code');
+        button.title = 'Copy code';
+        button.innerHTML = COPY_ICON;
+        button.addEventListener('click', async () => {
+            if (!(await copyText((pre.textContent ?? '').replace(/\n$/, '')))) {
+                status.textContent = 'Copy failed';
+                return;
+            }
+            button.innerHTML = CHECK_ICON;
+            button.dataset.copied = '';
+            status.textContent = 'Copied';
+            timers.push(setTimeout(() => {
+                button.innerHTML = COPY_ICON;
+                delete button.dataset.copied;
+                status.textContent = '';
+            }, 2000));
+        });
+        wrapper.appendChild(button);
+        added.push(button);
+    }
+    return () => {
+        for (const timer of timers)
+            clearTimeout(timer);
+        for (const button of added) {
+            button.parentElement?.classList.remove('has-copy-button');
+            button.remove();
+        }
+        for (const wrapper of wrapped)
+            wrapper.replaceWith(...wrapper.childNodes);
+        status.remove();
+    };
+}
+/**
+ * Copy text with the Clipboard API, which needs a secure context (HTTPS or localhost),
+ * falling back to a hidden textarea and `execCommand('copy')` elsewhere.
+ */
+async function copyText(text) {
+    try {
+        if (navigator.clipboard && window.isSecureContext) {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+    }
+    catch {
+        // fall through to the legacy path
+    }
+    const area = document.createElement('textarea');
+    area.value = text;
+    area.setAttribute('readonly', '');
+    area.style.cssText = 'position:fixed;top:0;left:0;opacity:0;pointer-events:none';
+    document.body.appendChild(area);
+    const focused = document.activeElement;
+    area.select();
+    try {
+        return document.execCommand('copy');
+    }
+    catch {
+        return false;
+    }
+    finally {
+        area.remove();
+        focused?.focus();
+    }
+}
+const SKIP = new Set(['PRE', 'CODE', 'SCRIPT', 'STYLE', 'MARK', 'SVG', 'TEXTAREA']);
+/**
+ * Wrap occurrences of `terms` in text under `root` with `<mark class="search-highlight">`,
+ * as Docusaurus does for `?_highlight=` after a search. Code blocks are left alone.
+ * Returns a cleanup that removes the marks. Scrolls nothing; the first mark is returned
+ * for the caller to scroll to if it wants.
+ */
+export function highlightTerms(root, terms) {
+    const words = [...new Set(terms.map((t) => t.trim()).filter((t) => t.length >= 2))];
+    if (words.length === 0)
+        return { cleanup: () => { }, first: null };
+    const pattern = new RegExp(words
+        .sort((a, b) => b.length - a.length)
+        .map((w) => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+        .join('|'), 'gi');
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+        acceptNode(node) {
+            for (let el = node.parentElement; el && el !== root; el = el.parentElement) {
+                if (SKIP.has(el.tagName.toUpperCase()))
+                    return NodeFilter.FILTER_REJECT;
+            }
+            return NodeFilter.FILTER_ACCEPT;
+        },
+    });
+    const nodes = [];
+    while (walker.nextNode())
+        nodes.push(walker.currentNode);
+    const marks = [];
+    for (const node of nodes) {
+        const text = node.data;
+        pattern.lastIndex = 0;
+        if (!pattern.test(text))
+            continue;
+        pattern.lastIndex = 0;
+        const fragment = document.createDocumentFragment();
+        let last = 0;
+        for (const match of text.matchAll(pattern)) {
+            const at = match.index ?? 0;
+            if (at > last)
+                fragment.append(text.slice(last, at));
+            const mark = document.createElement('mark');
+            mark.className = 'search-highlight';
+            mark.textContent = match[0];
+            fragment.append(mark);
+            marks.push(mark);
+            last = at + match[0].length;
+        }
+        if (last < text.length)
+            fragment.append(text.slice(last));
+        node.replaceWith(fragment);
+    }
+    return {
+        first: marks[0] ?? null,
+        cleanup: () => {
+            for (const mark of marks) {
+                const parent = mark.parentNode;
+                mark.replaceWith(mark.textContent ?? '');
+                parent?.normalize();
+            }
+        },
+    };
+}
+/**
+ * Give a rendered mermaid SVG an image role and a name: its `accTitle`/`<title>` when it
+ * has one, else "Diagram". Mermaid's own `aria-labelledby` (from `accTitle`) is kept.
+ */
+export function labelDiagram(container) {
+    const svg = container.querySelector('svg');
+    if (!svg)
+        return;
+    svg.setAttribute('role', 'img');
+    if (svg.hasAttribute('aria-labelledby') || svg.hasAttribute('aria-label'))
+        return;
+    const title = svg.querySelector('title')?.textContent?.trim();
+    svg.setAttribute('aria-label', title || 'Diagram');
+}

package/dist/lib/components/sidebar.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Docs sidebars on theme-svelte's `Sidebar` / `DashboardLayout`.
+ */
+import { type NavSection } from '@classic-homes/theme-svelte';
+import type { NavItem } from '../content/types.js';
+export interface ToSidebarNavOptions {
+    /** Section title for the sidebar's top-level pages (default: none) */
+    title?: string;
+    /** Prefix for section and item IDs, so several sidebars keep separate expansion state */
+    idPrefix?: string;
+    /** Label of the entry for a category's own page (default: `'Overview'`) */
+    overviewLabel?: string;
+}
+/**
+ * Map a docs sidebar (`Sidebar.items` from `loadDocs`) onto theme-svelte navigation.
+ *
+ * theme-svelte's sidebar has three levels: a section heading, its items, and one level of
+ * children. Top-level pages become an untitled first section, each top-level category a
+ * collapsible section, and a nested category an item with children. A category's own page
+ * (linked doc or generated index) becomes its first entry. Anything nested deeper is
+ * flattened to its pages under the nearest level the theme renders.
+ *
+ * Sections and items on the path to `current` are expanded; so is any category whose
+ * `_category_.json` sets `collapsed: false`.
+ */
+export declare function toSidebarNav(items: NavItem[], current: string, options?: ToSidebarNavOptions): NavSection[];
+/**
+ * Open the sections and items leading to the active entry, without saving it as the
+ * reader's preference. The sidebar restores each reader's saved expansion when it mounts;
+ * call this after every navigation (SvelteKit: `afterNavigate`) to keep the current page
+ * visible on top of that.
+ */
+export declare function revealActive(navigation: NavSection[]): void;

package/dist/lib/components/sidebar.js

@@ -0,0 +1,84 @@
+/**
+ * Docs sidebars on theme-svelte's `Sidebar` / `DashboardLayout`.
+ */
+import { sidebarStore, } from '@classic-homes/theme-svelte';
+import { navContains } from '../content/nav.js';
+/**
+ * Map a docs sidebar (`Sidebar.items` from `loadDocs`) onto theme-svelte navigation.
+ *
+ * theme-svelte's sidebar has three levels: a section heading, its items, and one level of
+ * children. Top-level pages become an untitled first section, each top-level category a
+ * collapsible section, and a nested category an item with children. A category's own page
+ * (linked doc or generated index) becomes its first entry. Anything nested deeper is
+ * flattened to its pages under the nearest level the theme renders.
+ *
+ * Sections and items on the path to `current` are expanded; so is any category whose
+ * `_category_.json` sets `collapsed: false`.
+ */
+export function toSidebarNav(items, current, options = {}) {
+    const { title, idPrefix = '', overviewLabel = 'Overview' } = options;
+    const link = (name, route) => ({
+        id: `${idPrefix}${route}`,
+        name,
+        href: route,
+        active: route === current,
+    });
+    const entriesOf = (category) => [
+        ...(category.route ? [link(overviewLabel, category.route)] : []),
+        ...category.items.map(toItem),
+    ];
+    function toItem(item) {
+        if (item.type === 'page')
+            return link(item.title, item.route);
+        return {
+            id: `${idPrefix}${item.label}:${item.route ?? ''}`,
+            name: item.label,
+            children: entriesOf(item).map((child) => (child.children ? flatten(child) : child)),
+            expanded: navContains(item, current) || item.collapsed === false,
+        };
+    }
+    /** Deeper than the theme renders: keep the entry, pointing at its first page. */
+    function flatten(item) {
+        const leaves = (i) => i.children ? i.children.flatMap(leaves) : [i];
+        const all = leaves(item);
+        return { ...item, children: undefined, href: all[0]?.href, active: all.some((l) => l.active) };
+    }
+    const sections = [];
+    const pages = items.filter((item) => item.type === 'page');
+    if (pages.length) {
+        sections.push({ id: `${idPrefix}:pages`, title, items: pages.map(toItem) });
+    }
+    for (const item of items) {
+        if (item.type !== 'category')
+            continue;
+        sections.push({
+            id: `${idPrefix}${item.label}`,
+            title: item.label,
+            items: entriesOf(item),
+            collapsible: item.collapsible !== false,
+            expanded: navContains(item, current) || item.collapsed === false,
+        });
+    }
+    return sections;
+}
+/**
+ * Open the sections and items leading to the active entry, without saving it as the
+ * reader's preference. The sidebar restores each reader's saved expansion when it mounts;
+ * call this after every navigation (SvelteKit: `afterNavigate`) to keep the current page
+ * visible on top of that.
+ */
+export function revealActive(navigation) {
+    const sections = [];
+    const items = [];
+    const walk = (list) => list.some((item) => {
+        const inside = Boolean(item.active) || (item.children ? walk(item.children) : false);
+        if (inside && item.children)
+            items.push(item.id);
+        return inside;
+    });
+    for (const section of navigation)
+        if (walk(section.items))
+            sections.push(section.id);
+    sidebarStore.forceExpandSections(sections);
+    sidebarStore.forceExpandItems(items);
+}

package/dist/lib/content/browser.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@classic-homes/theme-docs/nav` — content-model types and sidebar helpers without any
+ * Node imports, for layouts and client code that work with a `loadDocs` bundle.
+ */
+export * from './nav.js';
+export type * from './types.js';

package/dist/lib/content/browser.js

@@ -0,0 +1,5 @@
+/**
+ * `@classic-homes/theme-docs/nav` — content-model types and sidebar helpers without any
+ * Node imports, for layouts and client code that work with a `loadDocs` bundle.
+ */
+export * from './nav.js';

package/dist/lib/content/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@classic-homes/theme-docs/content` — a Docusaurus-style docs directory as data.
+ *
+ * `loadDocs` reads markdown into routes, autogenerated sidebars, generated-index pages
+ * and tags; `renderDocs` turns it into HTML with tables of contents and search text.
+ * Run both at build time and ship the result as JSON. Node-only (reads the file system);
+ * the navigation helpers are also exported from `@classic-homes/theme-docs/nav` for the
+ * browser.
+ */
+export { loadDocs, parseFrontmatter, routeOf, type LoadDocsOptions, type LoadedDocs, type AnchorLink, type BrokenLinkPolicy, type TagDefinition, } from './load.js';
+export { renderDocs, plainText, type RenderDocsOptions, type RenderDocsResult } from './render.js';
+export * from './nav.js';
+export type * from './types.js';

package/dist/lib/content/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@classic-homes/theme-docs/content` — a Docusaurus-style docs directory as data.
+ *
+ * `loadDocs` reads markdown into routes, autogenerated sidebars, generated-index pages
+ * and tags; `renderDocs` turns it into HTML with tables of contents and search text.
+ * Run both at build time and ship the result as JSON. Node-only (reads the file system);
+ * the navigation helpers are also exported from `@classic-homes/theme-docs/nav` for the
+ * browser.
+ */
+export { loadDocs, parseFrontmatter, routeOf, } from './load.js';
+export { renderDocs, plainText } from './render.js';
+export * from './nav.js';

package/dist/lib/content/load.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Read a directory of markdown into the docs content model, the way Docusaurus does:
+ * routes from file paths, autogenerated sidebars ordered by `sidebar_position` and
+ * `_category_.json`, generated-index category pages, tags, and relative `.md` links
+ * rewritten to routes. Node-only (reads the file system).
+ */
+import type { FrontmatterData } from '../types/frontmatter.js';
+import type { DocSource, DocsContent } from './types.js';
+export type BrokenLinkPolicy = 'throw' | 'warn' | 'ignore';
+export interface TagDefinition {
+    label?: string;
+    description?: string;
+}
+export interface LoadDocsOptions {
+    /** The docs directory */
+    dir: string;
+    /** Route the docs directory is served at, as content links write it. Default: `/docs` */
+    routeBase?: string;
+    /**
+     * Path the whole site is served under (SvelteKit `paths.base`, Docusaurus `baseUrl`), e.g.
+     * `/svelte`. Prefixed to every route, and to root-relative links and images in content,
+     * so markdown can keep writing `/docs/...`. Default: `''`
+     */
+    baseUrl?: string;
+    /**
+     * Directories (relative to `dir`) that each get their own autogenerated sidebar, like
+     * Docusaurus `{type: 'autogenerated', dirName}`. Default: one sidebar for the whole tree.
+     */
+    sidebarRoots?: string[];
+    /**
+     * Closed tag vocabulary (the contents of a Docusaurus `tags.yml`). Pages using a tag
+     * outside it fail the load, as `onInlineTags: 'throw'` does. Default: any tag is allowed.
+     */
+    tags?: Record<string, TagDefinition | null>;
+    /** Broken `.md` links and unknown `routeBase` links. Default: `'throw'`, as Docusaurus */
+    onBrokenLinks?: BrokenLinkPolicy;
+    /** Load pages with `draft: true`. Default: false */
+    includeDrafts?: boolean;
+    /**
+     * Extra rules for each page, run once every page is known. Throw to fail the load.
+     * The place for site-specific checks (required front matter, access rules, …).
+     */
+    validate?: (page: DocSource, content: Omit<DocsContent, 'warnings'>) => void;
+}
+/** A link from one page to a heading, checked by `renderDocs` once pages have IDs. */
+export interface AnchorLink {
+    /** File the link is written in */
+    file: string;
+    /** Route of the linked page */
+    route: string;
+    anchor: string;
+}
+/** `loadDocs` result plus the anchor links found while resolving (for `renderDocs`). */
+export interface LoadedDocs extends DocsContent {
+    anchorLinks: AnchorLink[];
+}
+/** Parse YAML front matter; returns `{ data, body }`. Throws on invalid YAML. */
+export declare function parseFrontmatter(raw: string, file: string): {
+    data: FrontmatterData;
+    body: string;
+};
+/** `it/network/vpn/index.md` → `/docs/it/network/vpn`. */
+export declare function routeOf(file: string, routeBase?: string): string;
+/**
+ * Read a docs directory into pages, sidebars, generated-index pages and tags.
+ *
+ * Routes come from file paths; `slug` and `id` front matter are rejected rather than
+ * silently ignored. Relative links to `.md`/`.mdx` files become routes (anchors kept),
+ * Docusaurus' `pathname://` prefix is unwrapped, and links under `routeBase` are checked.
+ *
+ * @example
+ * ```ts
+ * const docs = loadDocs({ dir: 'docs', sidebarRoots: ['guides', 'reference'] });
+ * const { pages } = await renderDocs(docs, { parse: { headingIdStyle: 'github' } });
+ * ```
+ */
+export declare function loadDocs(options: LoadDocsOptions): LoadedDocs;