@classic-homes/theme-docs 0.0.2

package/dist/lib/components/CodeBlock.svelte

@@ -0,0 +1,73 @@
+<script lang="ts">
+  /**
+   * CodeBlock - Standalone syntax-highlighted code block
+   *
+   * For use outside of markdown content when you need
+   * to display code with highlighting directly.
+   */
+  import { onMount } from 'svelte';
+  import { cn } from '../utils.js';
+  import { escapeHtml } from '../highlighter/index.js';
+
+  interface Props {
+    /** Code to highlight */
+    code: string;
+    /** Language for syntax highlighting */
+    language?: string;
+    /** Shiki theme */
+    theme?: string;
+    /** Custom class */
+    class?: string;
+    /** Optional filename to display */
+    filename?: string;
+    [key: string]: unknown;
+  }
+
+  let {
+    code,
+    language = 'text',
+    theme = 'github-dark',
+    class: className,
+    filename,
+    ...restProps
+  }: Props = $props();
+
+  let highlighted = $state('');
+  let loading = $state(true);
+
+  onMount(async () => {
+    try {
+      const { highlightCode } = await import('../highlighter/index.js');
+      highlighted = await highlightCode(code, language, { theme });
+      loading = false;
+    } catch (err) {
+      // Log warning for debugging - falling back to plain code
+      console.warn(
+        '[docs] Failed to highlight code block, showing plain code:',
+        err instanceof Error ? err.message : err
+      );
+      highlighted = `<pre class="shiki bg-muted rounded-lg p-4 overflow-x-auto"><code>${escapeHtml(code)}</code></pre>`;
+      loading = false;
+    }
+  });
+</script>
+
+<div class={cn('code-block-wrapper', className)} {...restProps}>
+  {#if filename}
+    <div
+      class="code-block-filename bg-muted/50 px-4 py-2 text-sm text-muted-foreground border-b border-border rounded-t-lg font-mono"
+    >
+      {filename}
+    </div>
+  {/if}
+
+  {#if loading}
+    <div class="code-block-loading">
+      <pre class="bg-muted rounded-lg p-4 overflow-x-auto"><code class="text-sm font-mono"
+          >{code}</code
+        ></pre>
+    </div>
+  {:else}
+    {@html highlighted}
+  {/if}
+</div>

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

@@ -0,0 +1,16 @@
+interface Props {
+    /** Code to highlight */
+    code: string;
+    /** Language for syntax highlighting */
+    language?: string;
+    /** Shiki theme */
+    theme?: string;
+    /** Custom class */
+    class?: string;
+    /** Optional filename to display */
+    filename?: string;
+    [key: string]: unknown;
+}
+declare const CodeBlock: import("svelte").Component<Props, {}, "">;
+type CodeBlock = ReturnType<typeof CodeBlock>;
+export default CodeBlock;

package/dist/lib/components/DocsCard.svelte

@@ -0,0 +1,99 @@
+<script lang="ts">
+  /**
+   * DocsCard - Individual documentation card for DocsHub
+   *
+   * Displays a single documentation item with title, description,
+   * optional icon, and optional badge.
+   */
+  import { cn } from '../utils.js';
+  import { tv } from 'tailwind-variants';
+  import type { DocsItem } from '../types/docs.js';
+
+  const docsCardVariants = tv({
+    base: 'group relative flex flex-col rounded-lg border border-border bg-card p-6 transition-all hover:border-primary hover:shadow-md',
+  });
+
+  interface Props {
+    /** Documentation item to display */
+    item: DocsItem;
+    /** Custom class */
+    class?: string;
+    [key: string]: unknown;
+  }
+
+  let { item, class: className, ...restProps }: Props = $props();
+</script>
+
+<a
+  href={item.href}
+  class={cn(docsCardVariants(), className)}
+  target={item.external ? '_blank' : undefined}
+  rel={item.external ? 'noopener noreferrer' : undefined}
+  aria-label={item.external ? `${item.title} (opens in new tab)` : undefined}
+  {...restProps}
+>
+  {#if item.badge}
+    <span
+      class="absolute -top-2 -right-2 rounded-full px-2 py-0.5 text-xs font-medium {item.badge ===
+      'new'
+        ? 'bg-primary text-primary-foreground'
+        : item.badge === 'updated'
+          ? 'bg-blue-600 text-white'
+          : item.badge === 'deprecated'
+            ? 'bg-destructive text-destructive-foreground'
+            : 'bg-muted text-foreground'}"
+    >
+      {item.badge}
+    </span>
+  {/if}
+
+  <div class="flex items-start gap-4">
+    {#if item.icon}
+      <div
+        class="flex h-10 w-10 shrink-0 items-center justify-center rounded-lg bg-primary/10 text-primary"
+      >
+        <span class="text-lg">{item.icon}</span>
+      </div>
+    {/if}
+
+    <div class="flex-1 min-w-0">
+      <h3
+        class="font-semibold text-foreground group-hover:text-primary transition-colors flex items-center gap-2"
+      >
+        {item.title}
+        {#if item.external}
+          <svg
+            class="h-4 w-4 text-muted-foreground"
+            fill="none"
+            stroke="currentColor"
+            viewBox="0 0 24 24"
+            aria-hidden="true"
+          >
+            <path
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              stroke-width="2"
+              d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14"
+            />
+          </svg>
+        {/if}
+      </h3>
+
+      {#if item.description}
+        <p class="mt-1 text-sm text-muted-foreground line-clamp-2">
+          {item.description}
+        </p>
+      {/if}
+
+      {#if item.tags && item.tags.length > 0}
+        <div class="mt-3 flex flex-wrap gap-1">
+          {#each item.tags as tag}
+            <span class="rounded bg-muted px-2 py-0.5 text-xs text-muted-foreground">
+              {tag}
+            </span>
+          {/each}
+        </div>
+      {/if}
+    </div>
+  </div>
+</a>

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

@@ -0,0 +1,11 @@
+import type { DocsItem } from '../types/docs.js';
+interface Props {
+    /** Documentation item to display */
+    item: DocsItem;
+    /** Custom class */
+    class?: string;
+    [key: string]: unknown;
+}
+declare const DocsCard: import("svelte").Component<Props, {}, "">;
+type DocsCard = ReturnType<typeof DocsCard>;
+export default DocsCard;

package/dist/lib/components/DocsHub.svelte

@@ -0,0 +1,83 @@
+<script lang="ts">
+  /**
+   * DocsHub - Documentation navigation and index component
+   *
+   * Features:
+   * - Card-based layout for documentation entries
+   * - Category/section grouping
+   * - Responsive grid layout
+   */
+  import type { Snippet } from 'svelte';
+  import { cn } from '../utils.js';
+  import { tv, type VariantProps } from 'tailwind-variants';
+  import DocsCard from './DocsCard.svelte';
+  import type { DocsHubConfig, DocsSection, DocsItem } from '../types/docs.js';
+
+  const docsHubVariants = tv({
+    slots: {
+      container: '',
+      sectionContainer: 'mb-8',
+      sectionTitle: 'text-2xl font-bold text-foreground mb-2',
+      sectionDescription: 'text-muted-foreground mb-6',
+      grid: 'grid gap-4',
+    },
+    variants: {
+      columns: {
+        1: { grid: 'grid-cols-1' },
+        2: { grid: 'grid-cols-1 md:grid-cols-2' },
+        3: { grid: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3' },
+        4: { grid: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-4' },
+      },
+    },
+    defaultVariants: {
+      columns: 3,
+    },
+  });
+
+  type DocsHubVariants = VariantProps<typeof docsHubVariants>;
+
+  interface Props {
+    /** Documentation configuration */
+    config: DocsHubConfig;
+    /** Number of columns in the grid */
+    columns?: DocsHubVariants['columns'];
+    /** Custom class for the container */
+    class?: string;
+    /** Optional custom card renderer */
+    card?: Snippet<[{ item: DocsItem; section: DocsSection }]>;
+    /** Optional header slot */
+    header?: Snippet;
+    [key: string]: unknown;
+  }
+
+  let { config, columns = 3, class: className, card, header, ...restProps }: Props = $props();
+
+  const styles = $derived(docsHubVariants({ columns }));
+</script>
+
+<div class={cn(styles.container(), className)} {...restProps}>
+  {#if header}
+    {@render header()}
+  {/if}
+
+  {#each config.sections as section}
+    <div class={styles.sectionContainer()}>
+      {#if section.title}
+        <h2 class={styles.sectionTitle()}>{section.title}</h2>
+      {/if}
+      {#if section.description}
+        <p class={styles.sectionDescription()}>{section.description}</p>
+      {/if}
+
+      <div class={styles.grid()}>
+        {#each section.items as item}
+          {#if card}
+            {@render card({ item, section })}
+          {:else}
+            <DocsCard {item} />
+          {/if}
+        {/each}
+      </div>
+    </div>
+  {/each}
+</div>

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

@@ -0,0 +1,28 @@
+/**
+   * DocsHub - Documentation navigation and index component
+   *
+   * Features:
+   * - Card-based layout for documentation entries
+   * - Category/section grouping
+   * - Responsive grid layout
+   */
+import type { Snippet } from 'svelte';
+import type { DocsHubConfig, DocsSection, DocsItem } from '../types/docs.js';
+declare const DocsHub: import("svelte").Component<{
+    [key: string]: unknown;
+    /** Documentation configuration */
+    config: DocsHubConfig;
+    /** Number of columns in the grid */
+    columns?: 1 | 2 | 3 | 4 | undefined;
+    /** Custom class for the container */
+    class?: string;
+    /** Optional custom card renderer */
+    card?: Snippet<[{
+        item: DocsItem;
+        section: DocsSection;
+    }]>;
+    /** Optional header slot */
+    header?: Snippet;
+}, {}, "">;
+type DocsHub = ReturnType<typeof DocsHub>;
+export default DocsHub;

package/dist/lib/components/MarkdownPage.svelte

@@ -0,0 +1,100 @@
+<script lang="ts">
+  /**
+   * MarkdownPage - Core markdown renderer with frontmatter and syntax highlighting
+   *
+   * Features:
+   * - YAML frontmatter parsing with gray-matter
+   * - Shiki syntax highlighting for code blocks
+   * - Loading and error states
+   * - Configurable styling
+   * - Optional Table of Contents generation
+   */
+  import type { Snippet } from 'svelte';
+  import { cn } from '../utils.js';
+  import type { FrontmatterData } from '../types/index.js';
+
+  interface Props {
+    /** Raw markdown content (with optional frontmatter) */
+    content: string;
+    /** Custom class for the content container */
+    class?: string;
+    /** Custom header snippet (receives frontmatter data) */
+    header?: Snippet<[FrontmatterData | null]>;
+    /** Custom error display snippet */
+    errorSlot?: Snippet<[string]>;
+    /** Shiki theme to use */
+    theme?: 'github-dark' | 'github-light' | 'one-dark-pro' | string;
+    /** Callback when content is parsed */
+    onParsed?: (data: { frontmatter: FrontmatterData | null; html: string }) => void;
+    [key: string]: unknown;
+  }
+
+  let {
+    content,
+    class: className,
+    header,
+    errorSlot,
+    theme = 'github-dark',
+    onParsed,
+    ...restProps
+  }: Props = $props();
+
+  let htmlContent = $state('');
+  let frontmatter = $state<FrontmatterData | null>(null);
+  let loading = $state(true);
+  let error = $state('');
+
+  // Use $effect to react to content changes (enables proper navigation)
+  $effect(() => {
+    // Track content as a dependency
+    const currentContent = content;
+
+    // Reset state for new content
+    loading = true;
+    error = '';
+
+    (async () => {
+      try {
+        const { parseMarkdown } = await import('../parser/index.js');
+        const result = await parseMarkdown(currentContent, { theme });
+
+        frontmatter = result.frontmatter;
+        htmlContent = result.html;
+        loading = false;
+
+        onParsed?.({ frontmatter, html: htmlContent });
+      } catch (err: unknown) {
+        error = err instanceof Error ? err.message : 'Failed to parse markdown';
+        loading = false;
+      }
+    })();
+  });
+</script>
+
+{#if header && frontmatter}
+  {@render header(frontmatter)}
+{/if}
+
+{#if error}
+  {#if errorSlot}
+    {@render errorSlot(error)}
+  {:else}
+    <div class="rounded-lg border border-destructive bg-destructive/10 p-4 text-destructive">
+      {error}
+    </div>
+  {/if}
+{/if}
+
+{#if loading}
+  <div class="flex items-center justify-center py-12">
+    <div
+      class="h-8 w-8 animate-spin rounded-full border-4 border-primary border-t-transparent"
+    ></div>
+  </div>
+{/if}
+
+{#if !loading && !error}
+  <div class={cn('markdown-content', className)} {...restProps}>
+    {@html htmlContent}
+  </div>
+{/if}

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

@@ -0,0 +1,33 @@
+/**
+   * MarkdownPage - Core markdown renderer with frontmatter and syntax highlighting
+   *
+   * Features:
+   * - YAML frontmatter parsing with gray-matter
+   * - Shiki syntax highlighting for code blocks
+   * - Loading and error states
+   * - Configurable styling
+   * - Optional Table of Contents generation
+   */
+import type { Snippet } from 'svelte';
+import type { FrontmatterData } from '../types/index.js';
+interface Props {
+    /** Raw markdown content (with optional frontmatter) */
+    content: string;
+    /** Custom class for the content container */
+    class?: string;
+    /** Custom header snippet (receives frontmatter data) */
+    header?: Snippet<[FrontmatterData | null]>;
+    /** Custom error display snippet */
+    errorSlot?: Snippet<[string]>;
+    /** Shiki theme to use */
+    theme?: 'github-dark' | 'github-light' | 'one-dark-pro' | string;
+    /** Callback when content is parsed */
+    onParsed?: (data: {
+        frontmatter: FrontmatterData | null;
+        html: string;
+    }) => void;
+    [key: string]: unknown;
+}
+declare const MarkdownPage: import("svelte").Component<Props, {}, "">;
+type MarkdownPage = ReturnType<typeof MarkdownPage>;
+export default MarkdownPage;

package/dist/lib/components/MermaidDiagram.svelte

@@ -0,0 +1,87 @@
+<script lang="ts">
+  /**
+   * MermaidDiagram - Client-side Mermaid diagram renderer
+   *
+   * Renders Mermaid diagrams from code. Can be used standalone or
+   * automatically initialized on markdown-rendered mermaid blocks.
+   *
+   * Requires mermaid to be installed in the consuming application:
+   * npm install mermaid
+   */
+  import { onMount } from 'svelte';
+  import { cn } from '../utils.js';
+
+  interface Props {
+    /** Mermaid diagram code */
+    code: string;
+    /** Custom class */
+    class?: string;
+    /** Unique ID for the diagram (auto-generated if not provided) */
+    id?: string;
+    /** Mermaid theme (default: 'default') */
+    theme?: 'default' | 'dark' | 'forest' | 'neutral';
+    [key: string]: unknown;
+  }
+
+  let {
+    code,
+    class: className,
+    id = `mermaid-${Math.random().toString(36).slice(2, 9)}`,
+    theme = 'default',
+    ...restProps
+  }: Props = $props();
+
+  let containerRef = $state<HTMLDivElement | null>(null);
+  let rendered = $state(false);
+  let error = $state<string | null>(null);
+
+  onMount(async () => {
+    if (!containerRef) return;
+
+    try {
+      // Dynamically import mermaid to avoid SSR issues
+      const mermaid = await import('mermaid');
+
+      // Initialize mermaid with theme
+      mermaid.default.initialize({
+        startOnLoad: false,
+        theme: theme,
+        securityLevel: 'strict',
+      });
+
+      // Render the diagram
+      const { svg } = await mermaid.default.render(id, code);
+      containerRef.innerHTML = svg;
+      rendered = true;
+    } catch (err) {
+      console.warn(
+        '[docs] Failed to render Mermaid diagram:',
+        err instanceof Error ? err.message : err
+      );
+      error = err instanceof Error ? err.message : 'Failed to render diagram';
+    }
+  });
+</script>
+
+<div
+  bind:this={containerRef}
+  class={cn(
+    'mermaid-container',
+    !rendered && !error && 'mermaid-loading',
+    error && 'mermaid-error',
+    className
+  )}
+  {...restProps}
+>
+  {#if !rendered && !error}
+    <!-- Show code as fallback while loading -->
+    <pre class="mermaid-fallback"><code>{code}</code></pre>
+  {/if}
+  {#if error}
+    <div class="mermaid-error-message">
+      <p class="mermaid-error-title">Failed to render diagram</p>
+      <pre class="mermaid-error-code"><code>{code}</code></pre>
+      <p class="mermaid-error-details">{error}</p>
+    </div>
+  {/if}
+</div>

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

@@ -0,0 +1,14 @@
+interface Props {
+    /** Mermaid diagram code */
+    code: string;
+    /** Custom class */
+    class?: string;
+    /** Unique ID for the diagram (auto-generated if not provided) */
+    id?: string;
+    /** Mermaid theme (default: 'default') */
+    theme?: 'default' | 'dark' | 'forest' | 'neutral';
+    [key: string]: unknown;
+}
+declare const MermaidDiagram: import("svelte").Component<Props, {}, "">;
+type MermaidDiagram = ReturnType<typeof MermaidDiagram>;
+export default MermaidDiagram;

package/dist/lib/components/MermaidInit.svelte

@@ -0,0 +1,100 @@
+<script lang="ts">
+  /**
+   * MermaidInit - Auto-initialize all Mermaid diagrams on the page
+   *
+   * Place this component once in your layout or page to automatically
+   * render all mermaid diagrams from markdown content.
+   *
+   * Requires mermaid to be installed in the consuming application:
+   * npm install mermaid
+   */
+  import { onMount } from 'svelte';
+
+  interface Props {
+    /** Mermaid theme (default: 'default') */
+    theme?: 'default' | 'dark' | 'forest' | 'neutral';
+    /** Whether to watch for new diagrams via MutationObserver */
+    watch?: boolean;
+  }
+
+  let { theme = 'default', watch = false }: Props = $props();
+
+  let initialized = $state(false);
+
+  async function renderDiagrams() {
+    try {
+      const mermaid = await import('mermaid');
+
+      // Initialize mermaid
+      mermaid.default.initialize({
+        startOnLoad: false,
+        theme: theme,
+        securityLevel: 'strict',
+      });
+
+      // Find all mermaid diagram placeholders
+      const diagrams = document.querySelectorAll('.mermaid-diagram[data-mermaid]');
+
+      for (const diagram of diagrams) {
+        const code = diagram.getAttribute('data-mermaid');
+        if (!code || diagram.classList.contains('mermaid-rendered')) continue;
+
+        try {
+          const id = `mermaid-${Math.random().toString(36).slice(2, 9)}`;
+          const { svg } = await mermaid.default.render(id, code);
+
+          // Replace the placeholder with the rendered SVG
+          diagram.innerHTML = svg;
+          diagram.classList.add('mermaid-rendered');
+          diagram.removeAttribute('data-mermaid');
+        } catch (err) {
+          console.warn(
+            '[docs] Failed to render Mermaid diagram:',
+            err instanceof Error ? err.message : err
+          );
+          diagram.classList.add('mermaid-error');
+        }
+      }
+
+      initialized = true;
+    } catch (err) {
+      // Mermaid not installed - that's okay, diagrams will show as code
+      console.warn('[docs] Mermaid library not available. Install with: npm install mermaid');
+    }
+  }
+
+  onMount(() => {
+    renderDiagrams();
+
+    if (watch) {
+      // Watch for new diagrams being added to the DOM
+      const observer = new MutationObserver((mutations) => {
+        for (const mutation of mutations) {
+          if (mutation.type === 'childList') {
+            const hasNewDiagrams = Array.from(mutation.addedNodes).some(
+              (node) =>
+                node instanceof HTMLElement &&
+                (node.classList?.contains('mermaid-diagram') ||
+                  node.querySelector?.('.mermaid-diagram[data-mermaid]'))
+            );
+            if (hasNewDiagrams) {
+              renderDiagrams();
+            }
+          }
+        }
+      });
+
+      observer.observe(document.body, {
+        childList: true,
+        subtree: true,
+      });
+
+      return () => observer.disconnect();
+    }
+  });
+</script>
+
+<!-- This component has no visual output, it just initializes mermaid -->
+{#if !initialized}
+  <!-- Hidden slot for loading state if needed -->
+{/if}

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

@@ -0,0 +1,9 @@
+interface Props {
+    /** Mermaid theme (default: 'default') */
+    theme?: 'default' | 'dark' | 'forest' | 'neutral';
+    /** Whether to watch for new diagrams via MutationObserver */
+    watch?: boolean;
+}
+declare const MermaidInit: import("svelte").Component<Props, {}, "">;
+type MermaidInit = ReturnType<typeof MermaidInit>;
+export default MermaidInit;