@classic-homes/theme-docs 0.1.0 → 0.3.0

package/dist/lib/components/TableOfContents.svelte

@@ -1,22 +1,31 @@
 <script lang="ts">
   /**
-   * TableOfContents - Auto-generated table of contents from headings
+   * TableOfContents - "On this page" navigation with scroll-spy
    *
-   * Extracts headings from HTML content and generates a navigable
-   * table of contents with smooth scrolling. Styled after Docusaurus TOC.
+   * Pass `toc` (from `parseMarkdown`/`renderDocs`) to render on the server, or `html` to
+   * extract headings in the browser. The heading being read is marked `aria-current`.
+   * Entries are plain `#id` links, so the browser (or your router) scrolls and records the
+   * hash; give headings a `scroll-margin-top` to clear a fixed header (`.markdown-content`
+   * does, from `--docs-header-offset`). Styled after Docusaurus.
    */
-  import { onMount } from 'svelte';
+  import { untrack } from 'svelte';
   import { cn } from '../utils.js';
   import type { TocEntry } from '../types/docs.js';
 
   interface Props {
-    /** HTML content to extract headings from */
-    html: string;
-    /** Maximum heading depth to include (default: 3) */
+    /** Prebuilt entries, e.g. `page.toc` from `renderDocs`. Takes precedence over `html`. */
+    toc?: TocEntry[];
+    /** HTML to extract headings from in the browser, when there is no `toc` */
+    html?: string;
+    /** Shallowest heading level to include (default: 1) */
+    minDepth?: number;
+    /** Deepest heading level to include (default: 3) */
     maxDepth?: number;
+    /** Height of any fixed header, in px: where a heading counts as reached (default: 80) */
+    offset?: number;
     /** Custom class */
     class?: string;
-    /** Title for the TOC section */
+    /** Title for the TOC section. Empty hides it (the nav is then labelled "On this page"). */
     title?: string;
     /** Make the TOC sticky */
     sticky?: boolean;
@@ -24,151 +33,131 @@
   }
 
   let {
+    toc,
     html,
+    minDepth = 1,
     maxDepth = 3,
+    offset = 80,
     class: className,
     title = 'On this page',
     sticky = false,
     ...restProps
   }: Props = $props();
 
-  let toc = $state<TocEntry[]>([]);
-  let activeId = $state<string | null>(null);
-  let ignoreObserver = false;
-
-  onMount(async () => {
-    const { extractToc } = await import('../parser/index.js');
-    toc = extractToc(html, maxDepth);
-
-    // Set up intersection observer to track active heading
-    // 100ms delay ensures DOM is fully rendered after markdown parsing completes
-    // This is necessary because markdown content is rendered asynchronously
-    setTimeout(() => {
-      const headings = document.querySelectorAll('h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]');
-      if (headings.length === 0) return;
-
-      // Set initial active heading based on scroll position
-      const firstVisibleHeading = Array.from(headings).find((heading) => {
-        const rect = heading.getBoundingClientRect();
-        return rect.top >= 0 && rect.top < window.innerHeight / 2;
-      });
-      if (firstVisibleHeading) {
-        activeId = firstVisibleHeading.id;
-      } else if (headings[0]) {
-        activeId = headings[0].id;
-      }
-
-      const observer = new IntersectionObserver(
-        (entries) => {
-          // Skip if we recently clicked a TOC link
-          if (ignoreObserver) return;
+  const uid = $props.id();
 
-          // Find the first intersecting entry
-          const intersecting = entries.filter((e) => e.isIntersecting);
-          if (intersecting.length > 0) {
-            // Sort by position and take the topmost
-            const topmost = intersecting.sort(
-              (a, b) => a.boundingClientRect.top - b.boundingClientRect.top
-            )[0];
-            activeId = topmost.target.id;
-          }
-        },
-        {
-          // rootMargin: top right bottom left
-          // -80px top: accounts for fixed header height (~80px)
-          // -70% bottom: heading becomes "active" when it enters the top 30% of viewport
-          // This creates a natural reading experience where the heading is highlighted
-          // before the user has scrolled past it
-          rootMargin: '-80px 0px -70% 0px',
-          threshold: 0,
-        }
-      );
-
-      headings.forEach((heading) => observer.observe(heading));
-
-      return () => {
-        headings.forEach((heading) => observer.unobserve(heading));
-      };
-    }, 100);
-  });
+  let extracted = $state<TocEntry[]>([]);
+  const entries = $derived(
+    (toc ?? extracted).filter((entry) => entry.level >= minDepth && entry.level <= maxDepth)
+  );
+  let activeId = $state<string | null>(null);
 
-  function getIndentClass(level: number): string {
-    // More pronounced indentation for hierarchy
-    const indents: Record<number, string> = {
-      1: '',
-      2: '', // h2 is typically top-level in TOC (no indent)
-      3: 'pl-3', // h3 indented
-      4: 'pl-6', // h4 further indented
-      5: 'pl-9',
-      6: 'pl-12',
+  // Without a prebuilt toc, extract one from the HTML. The parser loads lazily so pages
+  // that pass `toc` never download it.
+  $effect(() => {
+    if (toc || !html) return;
+    const source = html;
+    let cancelled = false;
+    void import('../parser/index.js').then(({ extractToc }) => {
+      if (!cancelled) extracted = extractToc(source, 6);
+    });
+    return () => {
+      cancelled = true;
     };
-    return indents[level] || '';
-  }
+  });
 
-  function getLevelStyles(level: number, isActive: boolean): string {
-    const baseStyles = 'block py-1 rounded-sm';
+  // Scroll-spy over this TOC's own headings, as Docusaurus does it: on scroll, the current
+  // heading is the last one above the header line. At the bottom of the page, where the
+  // last headings can't reach that line, a clicked heading that's on screen stays current.
+  $effect(() => {
+    const ids = entries.map((entry) => entry.id);
+    const line = offset + 24;
+    if (ids.length === 0) return;
 
-    if (isActive) {
-      return cn(baseStyles, 'text-primary font-medium');
-    }
+    let headings: HTMLElement[] = [];
+    let frame = 0;
 
-    // Top-level items (h2) are more prominent
-    if (level <= 2) {
-      return cn(baseStyles, 'text-foreground/80 hover:text-foreground hover:bg-muted-hover');
+    function update() {
+      frame = 0;
+      if (headings.length === 0) return;
+      let current = headings[0];
+      for (const heading of headings) {
+        if (heading.getBoundingClientRect().top > line) break;
+        current = heading;
+      }
+      const atBottom =
+        window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 2;
+      const chosen = activeId ? document.getElementById(activeId) : null;
+      if (atBottom && chosen && headings.includes(chosen)) {
+        const top = chosen.getBoundingClientRect().top;
+        if (top >= 0 && top < window.innerHeight) return;
+      }
+      activeId = current.id;
     }
+    // Throttle to one update per frame; hidden documents get no frames, so update directly.
+    const schedule = () => {
+      if (document.hidden) update();
+      else if (!frame) frame = requestAnimationFrame(update);
+    };
 
-    // Deeper levels are more subdued
-    return cn(
-      baseStyles,
-      'text-muted-foreground text-[12px] hover:text-foreground hover:bg-muted-hover'
-    );
-  }
-
-  function handleClick(event: MouseEvent, id: string) {
-    event.preventDefault();
-
-    // Immediately update active state on click
-    activeId = id;
-
-    // Temporarily ignore intersection observer to prevent it from
-    // overwriting our selection during scroll animation
-    ignoreObserver = true;
-    setTimeout(() => {
-      ignoreObserver = false;
-    }, 1000); // Longer timeout to cover scroll animation
-
-    // Find the heading element and scroll to it with offset
-    const element = document.getElementById(id);
-    if (element) {
-      const headerOffset = 100; // Account for fixed header + some padding
-      const elementPosition = element.getBoundingClientRect().top;
-      const offsetPosition = elementPosition + window.scrollY - headerOffset;
+    // Effects run after the DOM update, so the headings these entries describe are in place.
+    headings = ids
+      .map((id) => document.getElementById(id))
+      .filter((el): el is HTMLElement => el !== null);
+    // untrack: update() reads activeId, which must not become a dependency of this effect
+    untrack(update);
+    // Capture, so scrolling inside a layout's own scroll container counts too.
+    window.addEventListener('scroll', schedule, { passive: true, capture: true });
+    window.addEventListener('resize', schedule, { passive: true });
+
+    return () => {
+      cancelAnimationFrame(frame);
+      window.removeEventListener('scroll', schedule, { capture: true });
+      window.removeEventListener('resize', schedule);
+    };
+  });
 
-      window.scrollTo({
-        top: offsetPosition,
-        behavior: 'smooth',
-      });
-    }
+  const indents: Record<number, string> = {
+    3: 'pl-3',
+    4: 'pl-6',
+    5: 'pl-9',
+    6: 'pl-12',
+  };
+
+  function linkClass(level: number, isActive: boolean): string {
+    const base = 'block py-1 rounded-sm';
+    if (isActive) return cn(base, 'text-primary font-medium');
+    if (level <= 2)
+      return cn(base, 'text-foreground/80 hover:text-foreground hover:bg-muted-hover');
+    return cn(base, 'text-muted-foreground text-[12px] hover:text-foreground hover:bg-muted-hover');
   }
 </script>
 
-{#if toc.length > 0}
-  <nav class={cn('text-sm', sticky && 'sticky top-4', className)} {...restProps}>
+{#if entries.length > 0}
+  <nav
+    class={cn('text-sm', sticky && 'sticky top-4', className)}
+    aria-labelledby={title ? `${uid}-title` : undefined}
+    aria-label={title ? undefined : 'On this page'}
+    {...restProps}
+  >
     {#if title}
-      <h4 class="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-2">
+      <p
+        id="{uid}-title"
+        class="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-2"
+      >
         {title}
-      </h4>
+      </p>
     {/if}
 
     <ul class="space-y-0.5">
-      {#each toc as entry}
+      {#each entries as entry (entry.id)}
         {@const isActive = activeId === entry.id}
-        <li class={getIndentClass(entry.level)}>
+        <li class={indents[entry.level] ?? ''}>
           <a
             href="#{entry.id}"
-            onclick={(e) => handleClick(e, entry.id)}
-            class={getLevelStyles(entry.level, isActive)}
-            aria-current={isActive ? 'true' : undefined}
+            onclick={() => (activeId = entry.id)}
+            class={linkClass(entry.level, isActive)}
+            aria-current={isActive ? 'location' : undefined}
           >
             {entry.text}
           </a>

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

@@ -1,11 +1,18 @@
+import type { TocEntry } from '../types/docs.js';
 interface Props {
-    /** HTML content to extract headings from */
-    html: string;
-    /** Maximum heading depth to include (default: 3) */
+    /** Prebuilt entries, e.g. `page.toc` from `renderDocs`. Takes precedence over `html`. */
+    toc?: TocEntry[];
+    /** HTML to extract headings from in the browser, when there is no `toc` */
+    html?: string;
+    /** Shallowest heading level to include (default: 1) */
+    minDepth?: number;
+    /** Deepest heading level to include (default: 3) */
     maxDepth?: number;
+    /** Height of any fixed header, in px: where a heading counts as reached (default: 80) */
+    offset?: number;
     /** Custom class */
     class?: string;
-    /** Title for the TOC section */
+    /** Title for the TOC section. Empty hides it (the nav is then labelled "On this page"). */
     title?: string;
     /** Make the TOC sticky */
     sticky?: boolean;

package/dist/lib/components/TagIndex.svelte

@@ -0,0 +1,42 @@
+<script lang="ts">
+  /**
+   * TagIndex - every tag in use, grouped by first letter (the Docusaurus `/tags` page).
+   *
+   * Pass `tagCounts(tags, readablePages)` from `@classic-homes/theme-docs/nav`.
+   */
+  import { cn } from '../utils.js';
+  import TagList from './TagList.svelte';
+  import type { Tag } from '../content/types.js';
+
+  interface Props {
+    tags: (Tag & { count: number })[];
+    href?: (tag: Tag) => string;
+    /** Heading level for each letter (default: `h2`) */
+    as?: 'h2' | 'h3';
+    class?: string;
+    [key: string]: unknown;
+  }
+
+  let { tags, href, as = 'h2', class: className, ...restProps }: Props = $props();
+
+  const groups = $derived.by(() => {
+    const byLetter = new Map<string, (Tag & { count: number })[]>();
+    for (const tag of [...tags].sort((a, b) => a.label.localeCompare(b.label))) {
+      const letter = tag.label.charAt(0).toUpperCase();
+      if (!byLetter.has(letter)) byLetter.set(letter, []);
+      byLetter.get(letter)!.push(tag);
+    }
+    return [...byLetter];
+  });
+</script>
+
+<div class={cn('space-y-6', className)} {...restProps}>
+  {#each groups as [letter, group] (letter)}
+    <section>
+      <svelte:element this={as} class="mb-2 text-lg font-semibold text-foreground"
+        >{letter}</svelte:element
+      >
+      <TagList tags={group} {href} label="Tags starting with {letter}" />
+    </section>
+  {/each}
+</div>

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

@@ -0,0 +1,14 @@
+import type { Tag } from '../content/types.js';
+interface Props {
+    tags: (Tag & {
+        count: number;
+    })[];
+    href?: (tag: Tag) => string;
+    /** Heading level for each letter (default: `h2`) */
+    as?: 'h2' | 'h3';
+    class?: string;
+    [key: string]: unknown;
+}
+declare const TagIndex: import("svelte").Component<Props, {}, "">;
+type TagIndex = ReturnType<typeof TagIndex>;
+export default TagIndex;

package/dist/lib/components/TagList.svelte

@@ -0,0 +1,45 @@
+<script lang="ts">
+  /**
+   * TagList - a page's tags as links to their tag pages.
+   */
+  import { Badge } from '@classic-homes/theme-svelte';
+  import { cn } from '../utils.js';
+  import type { Tag } from '../content/types.js';
+
+  interface Props {
+    tags: (Tag & { count?: number })[];
+    /** Route of a tag's page (default: `/docs/tags/<id>`) */
+    href?: (tag: Tag) => string;
+    /** Accessible name of the list (default: "Tags") */
+    label?: string;
+    class?: string;
+    [key: string]: unknown;
+  }
+
+  let {
+    tags,
+    href = (tag) => `/docs/tags/${encodeURIComponent(tag.id)}`,
+    label = 'Tags',
+    class: className,
+    ...restProps
+  }: Props = $props();
+</script>
+
+{#if tags.length}
+  <ul aria-label={label} class={cn('flex flex-wrap gap-2', className)} {...restProps}>
+    {#each tags as tag (tag.id)}
+      <li>
+        <a
+          href={href(tag)}
+          title={tag.description || undefined}
+          class="rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <Badge variant="secondary" clickable>
+            {tag.label}{#if tag.count !== undefined}<span class="ml-1 opacity-70">{tag.count}</span
+              >{/if}
+          </Badge>
+        </a>
+      </li>
+    {/each}
+  </ul>
+{/if}

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

@@ -0,0 +1,15 @@
+import type { Tag } from '../content/types.js';
+interface Props {
+    tags: (Tag & {
+        count?: number;
+    })[];
+    /** Route of a tag's page (default: `/docs/tags/<id>`) */
+    href?: (tag: Tag) => string;
+    /** Accessible name of the list (default: "Tags") */
+    label?: string;
+    class?: string;
+    [key: string]: unknown;
+}
+declare const TagList: import("svelte").Component<Props, {}, "">;
+type TagList = ReturnType<typeof TagList>;
+export default TagList;

package/dist/lib/components/TocPanel.svelte

@@ -5,19 +5,28 @@
    * Provides a mobile flyout panel and optional desktop sidebar for the
    * TableOfContents component. Features a paper folder tab trigger on mobile
    * that slides out a panel from the right side. The tab is physically attached
-   * to the panel so they move together as one unit.
+   * to the panel so they move together as one unit. While open, the panel is a modal
+   * dialog that keeps focus inside; while closed, its links are inert.
    */
   import { onMount } from 'svelte';
   import { fade } from 'svelte/transition';
+  import { useFocusTrap } from '@classic-homes/theme-svelte';
   import { cn } from '../utils.js';
   import TableOfContents from './TableOfContents.svelte';
+  import type { TocEntry } from '../types/docs.js';
 
   interface Props {
-    /** HTML content to extract headings from */
-    html: string;
+    /** Prebuilt entries, e.g. `page.toc` from `renderDocs`. Takes precedence over `html`. */
+    toc?: TocEntry[];
+    /** HTML to extract headings from in the browser, when there is no `toc` */
+    html?: string;
+    /** Shallowest heading level to include (default: 1) */
+    minDepth?: number;
     /** Maximum heading depth to include (default: 3) */
     maxDepth?: number;
-    /** Breakpoint for desktop view (default: 'xl') */
+    /** Height of any fixed header, in px (default: 80) */
+    offset?: number;
+    /** Breakpoint for desktop view (default: 'lg') */
     breakpoint?: 'lg' | 'xl' | '2xl';
     /** Show desktop sidebar (default: true) */
     showDesktop?: boolean;
@@ -31,8 +40,11 @@
   }
 
   let {
+    toc,
     html,
+    minDepth = 1,
     maxDepth = 3,
+    offset = 80,
     breakpoint = 'lg',
     showDesktop = true,
     mobileClass,
@@ -42,6 +54,8 @@
   }: Props = $props();
 
   let open = $state(false);
+  const { action: trapFocus } = useFocusTrap({ active: () => open });
+  const hasContent = $derived(toc ? toc.length > 0 : Boolean(html));
   let tabButtonRef = $state<HTMLButtonElement | null>(null);
   let previousActiveElement: HTMLElement | null = null;
 
@@ -135,7 +149,7 @@
 </script>
 
 <!-- Mobile TOC Panel with attached tab - always rendered, slides via CSS transform -->
-{#if html}
+{#if hasContent}
   <!-- Backdrop - only shown when open -->
   {#if open}
     <button
@@ -148,7 +162,11 @@
 
   <!-- Panel container with attached tab -->
   <div
+    use:trapFocus
     class={cn(breakpointHide, 'toc-panel-container', open && 'toc-panel-open', mobileClass)}
+    role={open ? 'dialog' : undefined}
+    aria-modal={open ? 'true' : undefined}
+    aria-label={open ? title : undefined}
     {...restProps}
   >
     <!-- Tab - physically attached to panel -->
@@ -165,7 +183,7 @@
     </button>
 
     <!-- Panel content -->
-    <div class="toc-panel-content">
+    <div class="toc-panel-content" inert={!open}>
       <div class="toc-panel-header">
         <span class="text-sm font-medium text-foreground">{title}</span>
         <button class={closeButtonClasses} onclick={close} aria-label="Close table of contents">
@@ -186,14 +204,14 @@
         </button>
       </div>
       <div class="p-5">
-        <TableOfContents {html} {maxDepth} title="" />
+        <TableOfContents {toc} {html} {minDepth} {maxDepth} {offset} title="" />
       </div>
     </div>
   </div>
 {/if}
 
 <!-- Desktop TOC Sidebar -->
-{#if html && showDesktop}
+{#if hasContent && showDesktop}
   <aside
     class={cn(
       breakpointShow,
@@ -201,7 +219,7 @@
       desktopClass
     )}
   >
-    <TableOfContents {html} {maxDepth} {title} />
+    <TableOfContents {toc} {html} {minDepth} {maxDepth} {offset} {title} />
   </aside>
 {/if}
 

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

@@ -1,9 +1,16 @@
+import type { TocEntry } from '../types/docs.js';
 interface Props {
-    /** HTML content to extract headings from */
-    html: string;
+    /** Prebuilt entries, e.g. `page.toc` from `renderDocs`. Takes precedence over `html`. */
+    toc?: TocEntry[];
+    /** HTML to extract headings from in the browser, when there is no `toc` */
+    html?: string;
+    /** Shallowest heading level to include (default: 1) */
+    minDepth?: number;
     /** Maximum heading depth to include (default: 3) */
     maxDepth?: number;
-    /** Breakpoint for desktop view (default: 'xl') */
+    /** Height of any fixed header, in px (default: 80) */
+    offset?: number;
+    /** Breakpoint for desktop view (default: 'lg') */
     breakpoint?: 'lg' | 'xl' | '2xl';
     /** Show desktop sidebar (default: true) */
     showDesktop?: boolean;

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

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function enhanceCodeBlocks(root: ParentNode): () => void;
+/**
+ * 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 declare function highlightTerms(root: ParentNode, terms: string[]): {
+    cleanup: () => void;
+    first: HTMLElement | null;
+};
+/**
+ * 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 declare function labelDiagram(container: Element): void;