@classic-homes/theme-docs 0.0.2

package/dist/lib/components/TableOfContents.svelte

@@ -0,0 +1,179 @@
+<script lang="ts">
+  /**
+   * TableOfContents - Auto-generated table of contents from headings
+   *
+   * Extracts headings from HTML content and generates a navigable
+   * table of contents with smooth scrolling. Styled after Docusaurus TOC.
+   */
+  import { onMount } 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) */
+    maxDepth?: number;
+    /** Custom class */
+    class?: string;
+    /** Title for the TOC section */
+    title?: string;
+    /** Make the TOC sticky */
+    sticky?: boolean;
+    [key: string]: unknown;
+  }
+
+  let {
+    html,
+    maxDepth = 3,
+    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;
+
+          // 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);
+  });
+
+  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',
+    };
+    return indents[level] || '';
+  }
+
+  function getLevelStyles(level: number, isActive: boolean): string {
+    const baseStyles = 'block py-1 rounded-sm transition-colors';
+
+    if (isActive) {
+      return cn(baseStyles, 'text-primary font-medium');
+    }
+
+    // Top-level items (h2) are more prominent
+    if (level <= 2) {
+      return cn(baseStyles, 'text-foreground/80 hover:text-foreground hover:bg-muted/50');
+    }
+
+    // Deeper levels are more subdued
+    return cn(
+      baseStyles,
+      'text-muted-foreground text-[12px] hover:text-foreground hover:bg-muted/50'
+    );
+  }
+
+  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;
+
+      window.scrollTo({
+        top: offsetPosition,
+        behavior: 'smooth',
+      });
+    }
+  }
+</script>
+
+{#if toc.length > 0}
+  <nav class={cn('text-sm', sticky && 'sticky top-4', className)} {...restProps}>
+    {#if title}
+      <h4 class="text-xs font-medium text-muted-foreground uppercase tracking-wider mb-2">
+        {title}
+      </h4>
+    {/if}
+
+    <ul class="space-y-0.5">
+      {#each toc as entry}
+        {@const isActive = activeId === entry.id}
+        <li class={getIndentClass(entry.level)}>
+          <a
+            href="#{entry.id}"
+            onclick={(e) => handleClick(e, entry.id)}
+            class={getLevelStyles(entry.level, isActive)}
+            aria-current={isActive ? 'true' : undefined}
+          >
+            {entry.text}
+          </a>
+        </li>
+      {/each}
+    </ul>
+  </nav>
+{/if}

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

@@ -0,0 +1,16 @@
+interface Props {
+    /** HTML content to extract headings from */
+    html: string;
+    /** Maximum heading depth to include (default: 3) */
+    maxDepth?: number;
+    /** Custom class */
+    class?: string;
+    /** Title for the TOC section */
+    title?: string;
+    /** Make the TOC sticky */
+    sticky?: boolean;
+    [key: string]: unknown;
+}
+declare const TableOfContents: import("svelte").Component<Props, {}, "">;
+type TableOfContents = ReturnType<typeof TableOfContents>;
+export default TableOfContents;

package/dist/lib/components/TocPanel.svelte

@@ -0,0 +1,263 @@
+<script lang="ts">
+  /**
+   * TocPanel - Responsive table of contents panel
+   *
+   * 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.
+   */
+  import { onMount } from 'svelte';
+  import { fly, fade } from 'svelte/transition';
+  import { cn } from '../utils.js';
+  import TableOfContents from './TableOfContents.svelte';
+
+  interface Props {
+    /** HTML content to extract headings from */
+    html: string;
+    /** Maximum heading depth to include (default: 3) */
+    maxDepth?: number;
+    /** Breakpoint for desktop view (default: 'xl') */
+    breakpoint?: 'lg' | 'xl' | '2xl';
+    /** Show desktop sidebar (default: true) */
+    showDesktop?: boolean;
+    /** Custom class for mobile panel */
+    mobileClass?: string;
+    /** Custom class for desktop sidebar */
+    desktopClass?: string;
+    /** Title for the TOC section */
+    title?: string;
+    [key: string]: unknown;
+  }
+
+  let {
+    html,
+    maxDepth = 3,
+    breakpoint = 'lg',
+    showDesktop = true,
+    mobileClass,
+    desktopClass,
+    title = 'On this page',
+    ...restProps
+  }: Props = $props();
+
+  let open = $state(false);
+  let closeButtonRef = $state<HTMLButtonElement | null>(null);
+  let previousActiveElement: HTMLElement | null = null;
+
+  function openPanel() {
+    // Store the currently focused element to restore focus when closing
+    previousActiveElement = document.activeElement as HTMLElement;
+    open = true;
+  }
+
+  function close() {
+    open = false;
+    // Restore focus to the element that opened the panel
+    previousActiveElement?.focus();
+  }
+
+  function handleKeydown(event: KeyboardEvent) {
+    if (event.key === 'Escape' && open) {
+      event.preventDefault();
+      close();
+    }
+  }
+
+  // Focus the close button when panel opens
+  $effect(() => {
+    if (open && closeButtonRef) {
+      // Small delay to ensure the panel is rendered
+      setTimeout(() => closeButtonRef?.focus(), 0);
+    }
+  });
+
+  onMount(() => {
+    // Add global escape key listener
+    document.addEventListener('keydown', handleKeydown);
+    return () => document.removeEventListener('keydown', handleKeydown);
+  });
+
+  const breakpointHide = $derived(
+    {
+      lg: 'lg:hidden',
+      xl: 'xl:hidden',
+      '2xl': '2xl:hidden',
+    }[breakpoint]
+  );
+
+  const breakpointShow = $derived(
+    {
+      lg: 'hidden lg:block',
+      xl: 'hidden xl:block',
+      '2xl': 'hidden 2xl:block',
+    }[breakpoint]
+  );
+</script>
+
+<!-- Mobile TOC Tab Trigger - Paper folder tab style -->
+{#if html && !open}
+  <button
+    class={cn(breakpointHide, 'toc-tab-trigger')}
+    onclick={openPanel}
+    aria-label="Open table of contents"
+  >
+    <span class="toc-tab-text">
+      {title}
+    </span>
+  </button>
+{/if}
+
+<!-- Mobile TOC Flyout Panel -->
+{#if html && open}
+  <!-- Backdrop -->
+  <button
+    class={cn(breakpointHide, 'toc-backdrop')}
+    onclick={close}
+    aria-label="Close table of contents"
+    transition:fade={{ duration: 200 }}
+  ></button>
+
+  <!-- Panel -->
+  <div
+    class={cn(breakpointHide, 'toc-panel', mobileClass)}
+    transition:fly={{ x: 320, duration: 300 }}
+    {...restProps}
+  >
+    <div class="toc-panel-header">
+      <span class="text-sm font-medium text-foreground">{title}</span>
+      <button
+        bind:this={closeButtonRef}
+        class="toc-close-button"
+        onclick={close}
+        aria-label="Close table of contents"
+      >
+        <svg
+          class="h-5 w-5"
+          fill="none"
+          stroke="currentColor"
+          viewBox="0 0 24 24"
+          aria-hidden="true"
+        >
+          <path
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            stroke-width="2"
+            d="M6 18L18 6M6 6l12 12"
+          />
+        </svg>
+      </button>
+    </div>
+    <div class="p-5">
+      <TableOfContents {html} {maxDepth} title="" />
+    </div>
+  </div>
+{/if}
+
+<!-- Desktop TOC Sidebar -->
+{#if html && showDesktop}
+  <aside
+    class={cn(
+      breakpointShow,
+      'fixed top-20 right-4 w-56 max-h-[calc(100vh-6rem)] overflow-y-auto z-30',
+      desktopClass
+    )}
+  >
+    <TableOfContents {html} {maxDepth} {title} />
+  </aside>
+{/if}
+
+<style>
+  /* Paper folder tab trigger - positioned on right edge */
+  .toc-tab-trigger {
+    position: fixed;
+    top: 25%;
+    right: 0;
+    transform: translateY(-50%);
+    z-index: 40;
+    /* Tab shape - taller for vertical text */
+    padding: 1rem 0.375rem;
+    /* Visual styling */
+    background-color: hsl(var(--card));
+    border: 1px solid hsl(var(--border));
+    border-right: none;
+    border-radius: 0.5rem 0 0 0.5rem;
+    box-shadow: -2px 0 8px -2px rgba(0, 0, 0, 0.1);
+    /* Hover effect */
+    transition:
+      background-color 0.15s ease,
+      padding-right 0.15s ease;
+  }
+
+  .toc-tab-trigger:hover {
+    background-color: hsl(var(--muted));
+    padding-right: 0.5rem;
+  }
+
+  /* Vertical text for folder tab */
+  .toc-tab-text {
+    display: block;
+    writing-mode: vertical-rl;
+    text-orientation: mixed;
+    transform: rotate(180deg);
+    font-size: 0.75rem;
+    font-weight: 500;
+    color: hsl(var(--muted-foreground));
+    white-space: nowrap;
+    letter-spacing: 0.025em;
+  }
+
+  /* Backdrop overlay */
+  .toc-backdrop {
+    position: fixed;
+    inset: 0;
+    background-color: rgba(0, 0, 0, 0.5);
+    z-index: 40;
+  }
+
+  /* Flyout panel */
+  .toc-panel {
+    position: fixed;
+    top: 0;
+    right: 0;
+    height: 100%;
+    width: 20rem;
+    max-width: 85vw;
+    background-color: hsl(var(--card));
+    border-left: 1px solid hsl(var(--border));
+    box-shadow: -4px 0 16px -4px rgba(0, 0, 0, 0.15);
+    z-index: 50;
+    overflow-y: auto;
+    overscroll-behavior: contain;
+  }
+
+  /* Panel header */
+  .toc-panel-header {
+    position: sticky;
+    top: 0;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 0.75rem 1rem;
+    background-color: hsl(var(--card));
+    border-bottom: 1px solid hsl(var(--border));
+  }
+
+  /* Close button */
+  .toc-close-button {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.25rem;
+    height: 2.25rem;
+    border-radius: 0.375rem;
+    color: hsl(var(--muted-foreground));
+    transition:
+      background-color 0.15s ease,
+      color 0.15s ease;
+  }
+
+  .toc-close-button:hover {
+    background-color: hsl(var(--muted));
+    color: hsl(var(--foreground));
+  }
+</style>

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

@@ -0,0 +1,20 @@
+interface Props {
+    /** HTML content to extract headings from */
+    html: string;
+    /** Maximum heading depth to include (default: 3) */
+    maxDepth?: number;
+    /** Breakpoint for desktop view (default: 'xl') */
+    breakpoint?: 'lg' | 'xl' | '2xl';
+    /** Show desktop sidebar (default: true) */
+    showDesktop?: boolean;
+    /** Custom class for mobile panel */
+    mobileClass?: string;
+    /** Custom class for desktop sidebar */
+    desktopClass?: string;
+    /** Title for the TOC section */
+    title?: string;
+    [key: string]: unknown;
+}
+declare const TocPanel: import("svelte").Component<Props, {}, "">;
+type TocPanel = ReturnType<typeof TocPanel>;
+export default TocPanel;

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

@@ -0,0 +1,15 @@
+import { type Highlighter } from 'shiki';
+/**
+ * Get or create a singleton Shiki highlighter instance
+ */
+export declare function getHighlighter(): Promise<Highlighter>;
+/**
+ * Highlight code with Shiki
+ */
+export declare function highlightCode(code: string, language: string, options?: {
+    theme?: string;
+}): Promise<string>;
+/**
+ * Escape HTML entities in a string
+ */
+export declare function escapeHtml(str: string): string;

package/dist/lib/highlighter/index.js

@@ -0,0 +1,78 @@
+import { createHighlighter, } from 'shiki';
+let highlighterPromise = null;
+// Common languages to pre-load
+const PRELOADED_LANGUAGES = [
+    'javascript',
+    'typescript',
+    'svelte',
+    'html',
+    'css',
+    'json',
+    'bash',
+    'markdown',
+    'yaml',
+    'python',
+    'sql',
+];
+const PRELOADED_THEMES = ['github-dark', 'github-light', 'one-dark-pro'];
+/**
+ * Get or create a singleton Shiki highlighter instance
+ */
+export async function getHighlighter() {
+    if (!highlighterPromise) {
+        highlighterPromise = createHighlighter({
+            themes: PRELOADED_THEMES,
+            langs: PRELOADED_LANGUAGES,
+        });
+    }
+    return highlighterPromise;
+}
+/**
+ * Highlight code with Shiki
+ */
+export async function highlightCode(code, language, options = {}) {
+    const { theme = 'github-dark' } = options;
+    const highlighter = await getHighlighter();
+    // Load language if not already loaded
+    const loadedLangs = highlighter.getLoadedLanguages();
+    if (!loadedLangs.includes(language)) {
+        try {
+            await highlighter.loadLanguage(language);
+        }
+        catch (err) {
+            // Log warning for debugging - falling back to plain text
+            console.warn(`[docs] Failed to load language "${language}", falling back to text:`, err instanceof Error ? err.message : err);
+            language = 'text';
+        }
+    }
+    // Load theme if not already loaded
+    const loadedThemes = highlighter.getLoadedThemes();
+    if (!loadedThemes.includes(theme)) {
+        try {
+            await highlighter.loadTheme(theme);
+        }
+        catch (err) {
+            // Log warning for debugging - falling back to github-dark
+            console.warn(`[docs] Failed to load theme "${theme}", falling back to github-dark:`, err instanceof Error ? err.message : err);
+            return highlighter.codeToHtml(code, {
+                lang: language,
+                theme: 'github-dark',
+            });
+        }
+    }
+    return highlighter.codeToHtml(code, {
+        lang: language,
+        theme: theme,
+    });
+}
+/**
+ * Escape HTML entities in a string
+ */
+export function escapeHtml(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Classic Theme Documentation Components
+ *
+ * A collection of Svelte 5 components for rendering markdown documentation
+ * with syntax highlighting, frontmatter support, and rich markdown extensions.
+ *
+ * Supported Markdown Extensions:
+ * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Footnotes: [^1] references and [^1]: definitions
+ * - Definition Lists: Term followed by : Definition
+ * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
+ *
+ * @packageDocumentation
+ */
+export { default as MarkdownPage } from './components/MarkdownPage.svelte';
+export { default as CodeBlock } from './components/CodeBlock.svelte';
+export { default as DocsHub } from './components/DocsHub.svelte';
+export { default as DocsCard } from './components/DocsCard.svelte';
+export { default as TableOfContents } from './components/TableOfContents.svelte';
+export { default as TocPanel } from './components/TocPanel.svelte';
+export { default as MermaidDiagram } from './components/MermaidDiagram.svelte';
+export { default as MermaidInit } from './components/MermaidInit.svelte';
+export type { AuthorInfo, FrontmatterData, ParsedMarkdown, ParseOptions, MarkdownPageProps, } from './types/frontmatter.js';
+export type { DocsItem, DocsSection, DocsHubConfig, DocsHubProps, DocsCardProps, TocEntry, TableOfContentsProps, } from './types/docs.js';
+export { parseMarkdown, extractToc } from './parser/index.js';
+export { highlightCode, getHighlighter, escapeHtml } from './highlighter/index.js';
+export { cn } from './utils.js';
+export { ADMONITION_TYPES, type AdmonitionType, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, getAllExtensions, resetFootnoteStore, renderFootnotes, } from './parser/extensions.js';
+export { tv, type VariantProps } from 'tailwind-variants';

package/dist/lib/index.js

@@ -0,0 +1,31 @@
+/**
+ * Classic Theme Documentation Components
+ *
+ * A collection of Svelte 5 components for rendering markdown documentation
+ * with syntax highlighting, frontmatter support, and rich markdown extensions.
+ *
+ * Supported Markdown Extensions:
+ * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Footnotes: [^1] references and [^1]: definitions
+ * - Definition Lists: Term followed by : Definition
+ * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
+ *
+ * @packageDocumentation
+ */
+// Components
+export { default as MarkdownPage } from './components/MarkdownPage.svelte';
+export { default as CodeBlock } from './components/CodeBlock.svelte';
+export { default as DocsHub } from './components/DocsHub.svelte';
+export { default as DocsCard } from './components/DocsCard.svelte';
+export { default as TableOfContents } from './components/TableOfContents.svelte';
+export { default as TocPanel } from './components/TocPanel.svelte';
+export { default as MermaidDiagram } from './components/MermaidDiagram.svelte';
+export { default as MermaidInit } from './components/MermaidInit.svelte';
+// Utilities
+export { parseMarkdown, extractToc } from './parser/index.js';
+export { highlightCode, getHighlighter, escapeHtml } from './highlighter/index.js';
+export { cn } from './utils.js';
+// Markdown Extensions
+export { ADMONITION_TYPES, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, getAllExtensions, resetFootnoteStore, renderFootnotes, } from './parser/extensions.js';
+// Re-export tailwind-variants types for consumer convenience
+export { tv } from 'tailwind-variants';