@classic-homes/theme-docs 0.1.0 → 0.3.0

package/dist/lib/components/Breadcrumbs.svelte

@@ -0,0 +1,55 @@
+<script lang="ts">
+  /**
+   * Breadcrumbs - the path to the current docs page, as Docusaurus shows above a doc.
+   *
+   * Pass `breadcrumbs(sidebar.items, route)` from `@classic-homes/theme-docs/nav`, plus an
+   * optional `home` link. The last crumb is the current page and is not a link.
+   */
+  import { cn } from '../utils.js';
+  import type { Crumb } from '../content/nav.js';
+
+  interface Props {
+    crumbs: Crumb[];
+    /** Optional first crumb, e.g. `{ label: 'Docs', href: '/' }` */
+    home?: { label: string; href: string };
+    class?: string;
+    [key: string]: unknown;
+  }
+
+  let { crumbs, home, class: className, ...restProps }: Props = $props();
+
+  const trail = $derived([...(home ? [{ label: home.label, route: home.href }] : []), ...crumbs]);
+</script>
+
+{#if trail.length > 1}
+  <nav aria-label="Breadcrumbs" class={cn('mb-4 text-sm', className)} {...restProps}>
+    <ol class="flex flex-wrap items-center gap-x-1.5 gap-y-1 text-muted-foreground">
+      {#each trail as crumb, i (i)}
+        {@const last = i === trail.length - 1}
+        <li class="flex min-w-0 items-center gap-1.5">
+          {#if i > 0}
+            <svg
+              aria-hidden="true"
+              class="h-3.5 w-3.5 shrink-0"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"><path d="m9 18 6-6-6-6" /></svg
+            >
+          {/if}
+          {#if last}
+            <span aria-current="page" class="truncate font-medium text-foreground"
+              >{crumb.label}</span
+            >
+          {:else if crumb.route}
+            <a href={crumb.route} class="truncate hover:text-foreground hover:underline"
+              >{crumb.label}</a
+            >
+          {:else}
+            <span class="truncate">{crumb.label}</span>
+          {/if}
+        </li>
+      {/each}
+    </ol>
+  </nav>
+{/if}

package/dist/lib/components/Breadcrumbs.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Crumb } from '../content/nav.js';
+interface Props {
+    crumbs: Crumb[];
+    /** Optional first crumb, e.g. `{ label: 'Docs', href: '/' }` */
+    home?: {
+        label: string;
+        href: string;
+    };
+    class?: string;
+    [key: string]: unknown;
+}
+declare const Breadcrumbs: import("svelte").Component<Props, {}, "">;
+type Breadcrumbs = ReturnType<typeof Breadcrumbs>;
+export default Breadcrumbs;

package/dist/lib/components/CategoryIndex.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+  /**
+   * CategoryIndex - a generated-index page: the category's title and description, then a
+   * card for each of its items (Docusaurus `link: { type: 'generated-index' }`).
+   *
+   * Pass a `CategoryPage` from `loadDocs`. Page cards show `descriptions[route]` when
+   * given; category cards show how many entries they hold.
+   */
+  import { ActionHeader } from '@classic-homes/theme-svelte';
+  import DocsHub from './DocsHub.svelte';
+  import { countPages, flattenNav } from '../content/nav.js';
+  import type { CategoryPage } from '../content/types.js';
+  import type { DocsItem } from '../types/docs.js';
+
+  interface Props {
+    category: Pick<CategoryPage, 'title' | 'description' | 'items'>;
+    /** Page descriptions by route, e.g. from the rendered pages */
+    descriptions?: Record<string, string> | Map<string, string>;
+    columns?: 1 | 2 | 3 | 4;
+    /** "N items" text for a category card */
+    countLabel?: (count: number) => string;
+    class?: string;
+  }
+
+  let {
+    category,
+    descriptions,
+    columns = 2,
+    countLabel = (n) => `${n} ${n === 1 ? 'item' : 'items'}`,
+    class: className,
+  }: Props = $props();
+
+  const describe = (route: string) =>
+    descriptions instanceof Map ? descriptions.get(route) : descriptions?.[route];
+
+  const items = $derived(
+    category.items.flatMap((item): DocsItem[] => {
+      if (item.type === 'page') {
+        return [{ title: item.title, href: item.route, description: describe(item.route) }];
+      }
+      const href = item.route ?? flattenNav(item.items)[0]?.route;
+      if (!href) return [];
+      return [{ title: item.label, href, description: countLabel(countPages(item.items)) }];
+    })
+  );
+</script>
+
+<div class={className}>
+  <ActionHeader class="mb-6" title={category.title} subtitle={category.description || undefined} />
+  <DocsHub {columns} config={{ sections: [{ id: 'items', items }] }} />
+</div>

package/dist/lib/components/CategoryIndex.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { CategoryPage } from '../content/types.js';
+interface Props {
+    category: Pick<CategoryPage, 'title' | 'description' | 'items'>;
+    /** Page descriptions by route, e.g. from the rendered pages */
+    descriptions?: Record<string, string> | Map<string, string>;
+    columns?: 1 | 2 | 3 | 4;
+    /** "N items" text for a category card */
+    countLabel?: (count: number) => string;
+    class?: string;
+}
+declare const CategoryIndex: import("svelte").Component<Props, {}, "">;
+type CategoryIndex = ReturnType<typeof CategoryIndex>;
+export default CategoryIndex;

package/dist/lib/components/DocPage.svelte

@@ -0,0 +1,179 @@
+<script lang="ts">
+  /**
+   * DocPage - one docs page, laid out the way Docusaurus lays out a doc.
+   *
+   * Takes HTML rendered at build time (`renderDocs`), so it renders on the server with no
+   * client-side parsing. Around the content: breadcrumbs, the title as an `ActionHeader`
+   * (like app pages) when the body has no `<h1>`, tags, an edit link, previous/next links and the table of contents. In
+   * the browser it mounts allowlisted components, renders mermaid diagrams, adds copy
+   * buttons to code blocks and highlights `?highlight=` search terms.
+   */
+  import type { Component, Snippet } from 'svelte';
+  import { ActionHeader, Button } from '@classic-homes/theme-svelte';
+  import { cn } from '../utils.js';
+  import Breadcrumbs from './Breadcrumbs.svelte';
+  import DocPager from './DocPager.svelte';
+  import MermaidInit from './MermaidInit.svelte';
+  import TagList from './TagList.svelte';
+  import TocPanel from './TocPanel.svelte';
+  import { mountComponents } from './mount.js';
+  import { enhanceCodeBlocks, highlightTerms } from './enhance.js';
+  import type { Crumb, NavLink } from '../content/nav.js';
+  import type { RenderedDoc, Tag } from '../content/types.js';
+
+  interface Props {
+    page: Pick<RenderedDoc, 'title' | 'heading' | 'html' | 'toc' | 'hasH1'> & {
+      description?: string;
+    };
+    /** `breadcrumbs(sidebar.items, route)` */
+    breadcrumbs?: Crumb[];
+    /** First breadcrumb, e.g. `{ label: 'Docs', href: '/' }` */
+    home?: { label: string; href: string };
+    previous?: NavLink | null;
+    next?: NavLink | null;
+    /** The page's tags, resolved to labels */
+    tags?: Tag[];
+    tagHref?: (tag: Tag) => string;
+    /** "Edit this page" target, e.g. the file on GitHub */
+    editUrl?: string;
+    editLabel?: string;
+    /** Components for `<Name … />` placeholders (see `parseMarkdown`'s `components`) */
+    components?: Record<string, Component<any>>;
+    /** Render mermaid diagrams (needs the optional `mermaid` peer). Default: true */
+    mermaid?: boolean;
+    /** Mermaid theme. Default: `brand` (colours from the theme tokens) */
+    mermaidTheme?: 'brand' | 'default' | 'dark' | 'forest' | 'neutral';
+    /** Copy buttons on code blocks. Default: true */
+    copyButtons?: boolean;
+    /** Query parameter whose words are highlighted in the page. Default: `highlight` */
+    highlightParam?: string | null;
+    /** Heading levels in the table of contents. Default: 2 to 3, as Docusaurus */
+    tocMinDepth?: number;
+    tocMaxDepth?: number;
+    /** Width at which the TOC moves from a slide-out panel to a column. Default: `xl` */
+    tocBreakpoint?: 'lg' | 'xl' | '2xl';
+    /** Height of the fixed header, in px, for scroll offsets. Default: 80 */
+    headerOffset?: number;
+    /** Appended to the document title: `Page | Site`. Omit to leave `<head>` alone. */
+    siteTitle?: string;
+    /**
+     * Content between the title and the body (e.g. a lead paragraph or actions). Pages
+     * rendered with `hoistTitle` put it right under the title.
+     */
+    header?: Snippet;
+    /** Extra content in the page footer, next to the edit link (e.g. a "last verified" badge) */
+    meta?: Snippet;
+    class?: string;
+  }
+
+  let {
+    page,
+    breadcrumbs = [],
+    home,
+    previous = null,
+    next = null,
+    tags = [],
+    tagHref,
+    editUrl,
+    editLabel = 'Edit this page',
+    components,
+    mermaid = true,
+    mermaidTheme = 'brand',
+    copyButtons = true,
+    highlightParam = 'highlight',
+    tocMinDepth = 2,
+    tocMaxDepth = 3,
+    tocBreakpoint = 'xl',
+    headerOffset = 80,
+    siteTitle,
+    header,
+    meta,
+    class: className,
+  }: Props = $props();
+
+  let content = $state<HTMLElement>();
+
+  const showToc = $derived(
+    page.toc.filter((e) => e.level >= tocMinDepth && e.level <= tocMaxDepth).length > 1
+  );
+
+  // Enhance the rendered HTML. `content` is keyed on the HTML below, so each page gets a
+  // fresh element and these DOM changes never meet Svelte's own bookkeeping.
+  $effect(() => {
+    if (!content) return;
+    const root = content;
+    const cleanups: (() => void)[] = [];
+    if (components) cleanups.push(mountComponents(root, components));
+    if (copyButtons) cleanups.push(enhanceCodeBlocks(root));
+    if (highlightParam) {
+      const query = new URL(location.href).searchParams.get(highlightParam);
+      if (query) {
+        const { cleanup, first } = highlightTerms(root, query.split(/\s+/));
+        cleanups.push(cleanup);
+        if (first && !location.hash) first.scrollIntoView({ block: 'center' });
+      }
+    }
+    return () => {
+      for (const cleanup of cleanups.reverse()) cleanup();
+    };
+  });
+</script>
+
+<svelte:head>
+  {#if siteTitle}
+    <title>{page.title} | {siteTitle}</title>
+    {#if page.description}<meta name="description" content={page.description} />{/if}
+  {/if}
+</svelte:head>
+
+<div class={cn('flex gap-8', className)} style="--docs-header-offset: {headerOffset + 16}px">
+  <div class="min-w-0 max-w-3xl flex-1">
+    <Breadcrumbs crumbs={breadcrumbs} {home} />
+
+    <!-- The title as app pages show theirs (ActionHeader); render with `hoistTitle` so
+         the body's own `# Title` becomes this rather than a markdown-styled h1. -->
+    {#if !page.hasH1}<ActionHeader class="mb-6" title={page.heading ?? page.title} />{/if}
+    <article class="markdown-content">
+      {@render header?.()}
+      {#key page.html}
+        <div bind:this={content}>{@html page.html}</div>
+      {/key}
+    </article>
+    {#if mermaid}<MermaidInit watch theme={mermaidTheme} />{/if}
+
+    <footer class="mt-12 space-y-6">
+      {#if tags.length}<TagList {tags} href={tagHref} />{/if}
+      {#if editUrl || meta}
+        <div class="flex flex-wrap items-center justify-between gap-2">
+          {#if editUrl}
+            <Button variant="link" href={editUrl} class="px-0">
+              <svg
+                aria-hidden="true"
+                class="mr-1.5 h-4 w-4"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                stroke-width="2"
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                ><path d="M12 20h9" /><path d="M16.5 3.5a2.12 2.12 0 0 1 3 3L7 19l-4 1 1-4Z" /></svg
+              >{editLabel}
+            </Button>
+          {:else}<span></span>{/if}
+          {@render meta?.()}
+        </div>
+      {/if}
+      <DocPager {previous} {next} />
+    </footer>
+  </div>
+
+  {#if showToc}
+    <TocPanel
+      toc={page.toc}
+      minDepth={tocMinDepth}
+      maxDepth={tocMaxDepth}
+      breakpoint={tocBreakpoint}
+      offset={headerOffset}
+    />
+  {/if}
+</div>

package/dist/lib/components/DocPage.svelte.d.ts

@@ -0,0 +1,62 @@
+/**
+   * DocPage - one docs page, laid out the way Docusaurus lays out a doc.
+   *
+   * Takes HTML rendered at build time (`renderDocs`), so it renders on the server with no
+   * client-side parsing. Around the content: breadcrumbs, the title as an `ActionHeader`
+   * (like app pages) when the body has no `<h1>`, tags, an edit link, previous/next links and the table of contents. In
+   * the browser it mounts allowlisted components, renders mermaid diagrams, adds copy
+   * buttons to code blocks and highlights `?highlight=` search terms.
+   */
+import type { Component, Snippet } from 'svelte';
+import type { Crumb, NavLink } from '../content/nav.js';
+import type { RenderedDoc, Tag } from '../content/types.js';
+interface Props {
+    page: Pick<RenderedDoc, 'title' | 'heading' | 'html' | 'toc' | 'hasH1'> & {
+        description?: string;
+    };
+    /** `breadcrumbs(sidebar.items, route)` */
+    breadcrumbs?: Crumb[];
+    /** First breadcrumb, e.g. `{ label: 'Docs', href: '/' }` */
+    home?: {
+        label: string;
+        href: string;
+    };
+    previous?: NavLink | null;
+    next?: NavLink | null;
+    /** The page's tags, resolved to labels */
+    tags?: Tag[];
+    tagHref?: (tag: Tag) => string;
+    /** "Edit this page" target, e.g. the file on GitHub */
+    editUrl?: string;
+    editLabel?: string;
+    /** Components for `<Name … />` placeholders (see `parseMarkdown`'s `components`) */
+    components?: Record<string, Component<any>>;
+    /** Render mermaid diagrams (needs the optional `mermaid` peer). Default: true */
+    mermaid?: boolean;
+    /** Mermaid theme. Default: `brand` (colours from the theme tokens) */
+    mermaidTheme?: 'brand' | 'default' | 'dark' | 'forest' | 'neutral';
+    /** Copy buttons on code blocks. Default: true */
+    copyButtons?: boolean;
+    /** Query parameter whose words are highlighted in the page. Default: `highlight` */
+    highlightParam?: string | null;
+    /** Heading levels in the table of contents. Default: 2 to 3, as Docusaurus */
+    tocMinDepth?: number;
+    tocMaxDepth?: number;
+    /** Width at which the TOC moves from a slide-out panel to a column. Default: `xl` */
+    tocBreakpoint?: 'lg' | 'xl' | '2xl';
+    /** Height of the fixed header, in px, for scroll offsets. Default: 80 */
+    headerOffset?: number;
+    /** Appended to the document title: `Page | Site`. Omit to leave `<head>` alone. */
+    siteTitle?: string;
+    /**
+     * Content between the title and the body (e.g. a lead paragraph or actions). Pages
+     * rendered with `hoistTitle` put it right under the title.
+     */
+    header?: Snippet;
+    /** Extra content in the page footer, next to the edit link (e.g. a "last verified" badge) */
+    meta?: Snippet;
+    class?: string;
+}
+declare const DocPage: Component<Props, {}, "">;
+type DocPage = ReturnType<typeof DocPage>;
+export default DocPage;

package/dist/lib/components/DocPager.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+  /**
+   * DocPager - previous / next links at the foot of a docs page (Docusaurus pagination).
+   *
+   * Pass `neighbours(sidebar.items, route)` from `@classic-homes/theme-docs/nav`.
+   */
+  import { cn } from '../utils.js';
+  import type { NavLink } from '../content/nav.js';
+
+  interface Props {
+    previous?: NavLink | null;
+    next?: NavLink | null;
+    previousLabel?: string;
+    nextLabel?: string;
+    class?: string;
+    [key: string]: unknown;
+  }
+
+  let {
+    previous = null,
+    next = null,
+    previousLabel = 'Previous',
+    nextLabel = 'Next',
+    class: className,
+    ...restProps
+  }: Props = $props();
+
+  const card =
+    'group flex flex-col gap-1 rounded-lg border border-border p-4 transition-colors hover:border-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring';
+</script>
+
+{#if previous || next}
+  <nav aria-label="Docs pages" class={cn('grid gap-4 sm:grid-cols-2', className)} {...restProps}>
+    {#if previous}
+      <a href={previous.route} rel="prev" class={card}>
+        <span class="text-xs text-muted-foreground">{previousLabel}</span>
+        <span class="font-medium text-primary">« {previous.title}</span>
+      </a>
+    {:else}
+      <span class="hidden sm:block"></span>
+    {/if}
+    {#if next}
+      <a href={next.route} rel="next" class={cn(card, 'sm:items-end sm:text-right')}>
+        <span class="text-xs text-muted-foreground">{nextLabel}</span>
+        <span class="font-medium text-primary">{next.title} »</span>
+      </a>
+    {/if}
+  </nav>
+{/if}

package/dist/lib/components/DocPager.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { NavLink } from '../content/nav.js';
+interface Props {
+    previous?: NavLink | null;
+    next?: NavLink | null;
+    previousLabel?: string;
+    nextLabel?: string;
+    class?: string;
+    [key: string]: unknown;
+}
+declare const DocPager: import("svelte").Component<Props, {}, "">;
+type DocPager = ReturnType<typeof DocPager>;
+export default DocPager;

package/dist/lib/components/MarkdownPage.svelte

@@ -86,10 +86,12 @@
 {/if}
 
 {#if loading}
-  <div class="flex items-center justify-center py-12">
+  <div class="flex items-center justify-center py-12" role="status">
     <div
       class="h-8 w-8 animate-spin rounded-full border-4 border-primary border-t-transparent"
+      aria-hidden="true"
     ></div>
+    <span class="docs-sr-only">Loading…</span>
   </div>
 {/if}
 

package/dist/lib/components/MermaidDiagram.svelte

@@ -8,6 +8,7 @@
    * Requires mermaid to be installed in the consuming application:
    * npm install mermaid
    */
+  import { labelDiagram } from './enhance.js';
   import { cn } from '../utils.js';
 
   interface Props {
@@ -60,6 +61,7 @@
         const { svg } = await mermaid.default.render(`${id}-${++renderCount}`, currentCode);
         if (cancelled) return;
         container.innerHTML = svg;
+        labelDiagram(container);
         rendered = true;
         error = null;
       } catch (err) {

package/dist/lib/components/MermaidInit.svelte

@@ -8,11 +8,15 @@
    * Requires mermaid to be installed in the consuming application:
    * npm install mermaid
    */
+  import { labelDiagram } from './enhance.js';
   import { onMount } from 'svelte';
 
   interface Props {
-    /** Mermaid theme (default: 'default') */
-    theme?: 'default' | 'dark' | 'forest' | 'neutral';
+    /**
+     * Mermaid theme (default: 'default'). `brand` colours diagrams from the theme tokens
+     * on the page (muted node fills, foreground text and lines, Figtree).
+     */
+    theme?: 'default' | 'dark' | 'forest' | 'neutral' | 'brand';
     /** Whether to watch for new diagrams via MutationObserver */
     watch?: boolean;
   }
@@ -21,6 +25,42 @@
 
   let initialized = $state(false);
 
+  /** A token's HSL triplet (`357 72% 39%`) as a colour mermaid's colour math can parse */
+  function token(styles: CSSStyleDeclaration, name: string, fallback: string): string {
+    const parts = styles.getPropertyValue(`--${name}`).trim().split(/\s+/);
+    return parts.length === 3 ? `hsl(${parts.join(', ')})` : fallback;
+  }
+
+  function brandConfig() {
+    const s = getComputedStyle(document.documentElement);
+    const foreground = token(s, 'foreground', '#4f4f4f');
+    return {
+      theme: 'base' as const,
+      themeVariables: {
+        fontFamily: 'Figtree, ui-sans-serif, system-ui, sans-serif',
+        fontSize: '14px',
+        background: token(s, 'background', '#ffffff'),
+        primaryColor: token(s, 'muted', '#e8e9e4'),
+        primaryTextColor: foreground,
+        primaryBorderColor: token(s, 'secondary', '#5f6150'),
+        secondaryColor: token(s, 'sidebar-background', '#f5f5f3'),
+        secondaryTextColor: foreground,
+        secondaryBorderColor: token(s, 'outline', '#8b8e7b'),
+        tertiaryColor: token(s, 'content-bg', '#fafafa'),
+        tertiaryTextColor: foreground,
+        tertiaryBorderColor: token(s, 'outline', '#8b8e7b'),
+        clusterBkg: token(s, 'content-bg', '#fafafa'),
+        clusterBorder: token(s, 'outline', '#8b8e7b'),
+        lineColor: token(s, 'muted-foreground', '#666666'),
+        textColor: foreground,
+        noteBkgColor: token(s, 'muted', '#e8e9e4'),
+        noteTextColor: foreground,
+        noteBorderColor: token(s, 'outline', '#8b8e7b'),
+        edgeLabelBackground: token(s, 'background', '#ffffff'),
+      },
+    };
+  }
+
   async function renderDiagrams() {
     try {
       const mermaid = await import('mermaid');
@@ -28,7 +68,7 @@
       // Initialize mermaid
       mermaid.default.initialize({
         startOnLoad: false,
-        theme: theme,
+        ...(theme === 'brand' ? brandConfig() : { theme }),
         securityLevel: 'strict',
       });
 
@@ -45,6 +85,7 @@
 
           // Replace the placeholder with the rendered SVG
           diagram.innerHTML = svg;
+          labelDiagram(diagram);
           diagram.classList.add('mermaid-rendered');
           diagram.removeAttribute('data-mermaid');
         } catch (err) {

package/dist/lib/components/MermaidInit.svelte.d.ts

@@ -1,6 +1,9 @@
 interface Props {
-    /** Mermaid theme (default: 'default') */
-    theme?: 'default' | 'dark' | 'forest' | 'neutral';
+    /**
+     * Mermaid theme (default: 'default'). `brand` colours diagrams from the theme tokens
+     * on the page (muted node fills, foreground text and lines, Figtree).
+     */
+    theme?: 'default' | 'dark' | 'forest' | 'neutral' | 'brand';
     /** Whether to watch for new diagrams via MutationObserver */
     watch?: boolean;
 }