@specglass/theme-default 0.0.2

package/src/components/TableOfContents.astro

@@ -0,0 +1,111 @@
+---
+/**
+ * TableOfContents — Right-side navigation based on page headings.
+ *
+ * Renders h2 and h3 headings as a nested list with anchor links.
+ * Includes an inline scroll-spy script to highlight the currently
+ * visible section.
+ */
+
+export interface Props {
+  headings: Array<{ depth: number; slug: string; text: string }>;
+}
+
+const { headings } = Astro.props;
+
+// Filter to h2 and h3 only
+const tocHeadings = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+---
+
+{
+  tocHeadings.length > 0 && (
+    <nav aria-label="Table of contents">
+      <h2 class="text-xs font-semibold uppercase tracking-wider text-text-muted mb-3">
+        On this page
+      </h2>
+      <ul class="list-none p-0 m-0 space-y-0.5" id="toc-list">
+        {tocHeadings.map((heading) => (
+          <li>
+            <a
+              href={`#${heading.slug}`}
+              class:list={[
+                "block text-sm py-1 no-underline transition-colors duration-150",
+                heading.depth === 3 ? "pl-4" : "pl-0",
+                "text-text-muted hover:text-text",
+              ]}
+              data-toc-link
+              data-toc-id={heading.slug}
+            >
+              {heading.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}
+
+<script>
+  function initScrollSpy() {
+    const tocLinks = document.querySelectorAll("[data-toc-link]");
+    if (tocLinks.length === 0) return;
+
+    const headingIds = Array.from(tocLinks).map((link) => (link as HTMLElement).dataset.tocId!);
+
+    const headingElements = headingIds
+      .map((id) => document.getElementById(id))
+      .filter(Boolean) as HTMLElement[];
+
+    if (headingElements.length === 0) return;
+
+    let activeId = headingIds[0];
+
+    function setActive(id: string) {
+      if (id === activeId) return;
+      activeId = id;
+      tocLinks.forEach((link) => {
+        const linkId = (link as HTMLElement).dataset.tocId;
+        if (linkId === id) {
+          link.classList.add("text-primary", "font-medium");
+          link.classList.remove("text-text-muted");
+        } else {
+          link.classList.remove("text-primary", "font-medium");
+          link.classList.add("text-text-muted");
+        }
+      });
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        // Find the first visible heading
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            setActive(entry.target.id);
+            break;
+          }
+        }
+      },
+      {
+        rootMargin: "-80px 0px -70% 0px",
+        threshold: 0,
+      },
+    );
+
+    headingElements.forEach((el) => observer.observe(el));
+
+    // Set initial active state
+    setActive(headingIds[0]);
+
+    // Cleanup on page transition
+    document.addEventListener(
+      "astro:before-swap",
+      () => {
+        observer.disconnect();
+      },
+      { once: true },
+    );
+  }
+
+  initScrollSpy();
+  document.addEventListener("astro:after-swap", initScrollSpy);
+</script>

package/src/components/Tabs.astro

@@ -0,0 +1,185 @@
+---
+/**
+ * Tabs component — renders tabbed content panels with accessible tab controls.
+ *
+ * Children must be <TabItem> components. The first tab is active by default.
+ * Uses inline <script> for tab switching — NOT a React island.
+ *
+ * Accessible: role="tablist", role="tab", role="tabpanel", aria-selected,
+ * aria-controls, arrow key navigation.
+ *
+ * @example
+ * <Tabs>
+ *   <TabItem label="npm">npm install foo</TabItem>
+ *   <TabItem label="yarn">yarn add foo</TabItem>
+ * </Tabs>
+ */
+
+const tabGroupId = `tabs-${Math.random().toString(36).slice(2, 9)}`;
+---
+
+<div class="tabs-container" data-tabs-id={tabGroupId}>
+  <div role="tablist" class="tabs-header" aria-label="Tab options">
+    <!-- Tab buttons are generated client-side from TabItem children -->
+  </div>
+  <div class="tabs-content">
+    <slot />
+  </div>
+</div>
+
+<style is:global>
+  /*
+   * Must be is:global — tab buttons are created at runtime by <script>,
+   * so Astro's scoping data attribute is not present on them.
+   */
+  .tabs-container {
+    margin: 1.5rem 0;
+    border: 1px solid var(--tabs-border, #e5e7eb);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .tabs-header {
+    display: flex;
+    border-bottom: 1px solid var(--tabs-border, #e5e7eb);
+    background-color: var(--tabs-header-bg, #f9fafb);
+  }
+
+  .tabs-header [role="tab"] {
+    padding: 0.625rem 1rem;
+    border: none;
+    background: none;
+    cursor: pointer;
+    font-size: 0.875rem;
+    font-weight: 500;
+    color: var(--tabs-text, #6b7280);
+    border-bottom: 2px solid transparent;
+    transition:
+      color 0.15s,
+      border-color 0.15s;
+    white-space: nowrap;
+  }
+
+  .tabs-header [role="tab"]:hover {
+    color: var(--tabs-text-hover, #374151);
+  }
+
+  .tabs-header [role="tab"][aria-selected="true"] {
+    color: var(--tabs-text-active, #111827);
+    border-bottom-color: var(--tabs-active-border, #3b82f6);
+    background-color: var(--tabs-active-bg, transparent);
+  }
+
+  .tabs-header [role="tab"]:focus-visible {
+    outline: 2px solid var(--tabs-focus-ring, #3b82f6);
+    outline-offset: -2px;
+  }
+
+  .tabs-content {
+    padding: 1rem 1.25rem;
+  }
+
+  .tabs-content .tab-item {
+    display: none;
+  }
+
+  .tabs-content .tab-item.active {
+    display: block;
+  }
+
+  /* Dark mode — remap CSS vars to dark surface colors */
+  .dark .tabs-container {
+    --tabs-border: oklch(0.303 0.034 264.376);
+    --tabs-header-bg: oklch(0.179 0.04 264.376);
+    --tabs-text: oklch(0.708 0.014 264.364);
+    --tabs-text-hover: oklch(0.85 0.01 264);
+    --tabs-text-active: oklch(0.95 0.005 264);
+  }
+</style>
+
+<script>
+  document.addEventListener("DOMContentLoaded", () => {
+    document.querySelectorAll<HTMLDivElement>("[data-tabs-id]").forEach((container) => {
+      const tablist = container.querySelector<HTMLDivElement>('[role="tablist"]');
+      const contentArea = container.querySelector<HTMLDivElement>(".tabs-content");
+      if (!tablist || !contentArea) return;
+
+      const tabItems = contentArea.querySelectorAll<HTMLDivElement>(".tab-item");
+      if (tabItems.length === 0) return;
+
+      const groupId = container.dataset.tabsId ?? "tabs";
+
+      // Build tab buttons from TabItem children
+      tabItems.forEach((item, index) => {
+        const label = item.dataset.tabLabel ?? `Tab ${index + 1}`;
+        const tabId = `${groupId}-tab-${index}`;
+        const panelId = `${groupId}-panel-${index}`;
+
+        // Create tab button
+        const button = document.createElement("button");
+        button.role = "tab";
+        button.id = tabId;
+        button.setAttribute("aria-controls", panelId);
+        button.setAttribute("aria-selected", index === 0 ? "true" : "false");
+        button.tabIndex = index === 0 ? 0 : -1;
+        button.textContent = label;
+        tablist.appendChild(button);
+
+        // Set up panel
+        item.id = panelId;
+        item.setAttribute("role", "tabpanel");
+        item.setAttribute("aria-labelledby", tabId);
+        item.tabIndex = 0;
+
+        if (index === 0) {
+          item.classList.add("active");
+        }
+      });
+
+      // Tab switching
+      const tabs = tablist.querySelectorAll<HTMLButtonElement>('[role="tab"]');
+
+      function activateTab(index: number) {
+        tabs.forEach((tab, i) => {
+          const isActive = i === index;
+          tab.setAttribute("aria-selected", isActive ? "true" : "false");
+          tab.tabIndex = isActive ? 0 : -1;
+        });
+        tabItems.forEach((item, i) => {
+          item.classList.toggle("active", i === index);
+        });
+      }
+
+      tabs.forEach((tab, index) => {
+        tab.addEventListener("click", () => {
+          activateTab(index);
+          tab.focus();
+        });
+      });
+
+      // Keyboard navigation
+      tablist.addEventListener("keydown", (e) => {
+        const currentIndex = Array.from(tabs).findIndex((t) => t === document.activeElement);
+        if (currentIndex === -1) return;
+
+        let nextIndex: number | null = null;
+
+        if (e.key === "ArrowRight") {
+          nextIndex = (currentIndex + 1) % tabs.length;
+        } else if (e.key === "ArrowLeft") {
+          nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+        } else if (e.key === "Home") {
+          nextIndex = 0;
+        } else if (e.key === "End") {
+          nextIndex = tabs.length - 1;
+        }
+
+        if (nextIndex !== null) {
+          e.preventDefault();
+          activateTab(nextIndex);
+          tabs[nextIndex].focus();
+        }
+      });
+    });
+  });
+</script>

package/src/islands/CodeTabs.tsx

@@ -0,0 +1,212 @@
+import { useState, useEffect, useCallback, useRef, useMemo, useId } from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * CodeTabs — React island for SDK/language code tabs with persistent preference.
+ *
+ * Features:
+ * - Tab switching with keyboard navigation (ArrowLeft/Right, Home/End)
+ * - localStorage persistence of preferred language
+ * - Cross-group sync via CustomEvent broadcast
+ * - Configurable syncKey for independent tab groups
+ *
+ * Designed for `client:idle` hydration in Astro islands.
+ *
+ * @see architecture.md FR32 (SDK tab switching), FR33 (persistent preference)
+ */
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const LANGUAGE_CHANGE_EVENT = "ndocs-language-change";
+
+function getStorageKey(syncKey: string): string {
+  return `ndocs-preferred-${syncKey}`;
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A single tab definition */
+interface CodeTab {
+  /** Display label (e.g., "Python", "Node.js", "cURL") */
+  label: string;
+  /** Language key for sync/persistence (e.g., "python", "nodejs", "curl") */
+  language: string;
+  /** Pre-rendered HTML content (from Shiki or MDX) */
+  content: string;
+}
+
+interface CodeTabsProps {
+  /** Array of tab definitions */
+  tabs: CodeTab[];
+  /** Sync key — all CodeTabs with same key share selection. Default: "sdk-language" */
+  syncKey?: string;
+  /** Custom ARIA label for the tablist. Default: "SDK language tabs" */
+  ariaLabel?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Hook — useCodeTabs
+// SYNC: If changing this hook, update code-tabs.test.ts mirror copy
+// ---------------------------------------------------------------------------
+
+function useCodeTabs(languages: string[], syncKey: string) {
+  const storageKey = getStorageKey(syncKey);
+
+  // Always start at index 0 — SSR-safe. Stored preference is restored in useEffect
+  // to avoid hydration mismatch (server has no localStorage → renders index 0,
+  // but client reads a different index → React can't reconcile → multiple panels visible).
+  const [activeIndex, setActiveIndex] = useState(0);
+  const isInternalChange = useRef(false);
+
+  // Restore stored preference after hydration
+  useEffect(() => {
+    try {
+      const stored = localStorage.getItem(storageKey);
+      if (stored) {
+        const idx = languages.indexOf(stored);
+        if (idx !== -1 && idx !== 0) {
+          setActiveIndex(idx);
+        }
+      }
+    } catch {
+      // localStorage unavailable
+    }
+  }, [storageKey, languages]);
+
+  const setTab = useCallback(
+    (index: number) => {
+      if (index < 0 || index >= languages.length) return;
+      setActiveIndex(index);
+      const language = languages[index];
+      if (language) {
+        try {
+          localStorage.setItem(storageKey, language);
+        } catch {
+          // localStorage unavailable
+        }
+        isInternalChange.current = true;
+        window.dispatchEvent(
+          new CustomEvent(LANGUAGE_CHANGE_EVENT, {
+            detail: { syncKey, language },
+          }),
+        );
+        isInternalChange.current = false;
+      }
+    },
+    [languages, storageKey, syncKey],
+  );
+
+  // Listen for external language change events (from other CodeTabs instances)
+  useEffect(() => {
+    const handler = (e: Event) => {
+      if (isInternalChange.current) return;
+      const detail = (e as CustomEvent).detail;
+      if (detail?.syncKey === syncKey) {
+        const idx = languages.indexOf(detail.language);
+        if (idx !== -1) {
+          setActiveIndex(idx);
+        }
+      }
+    };
+    window.addEventListener(LANGUAGE_CHANGE_EVENT, handler);
+    return () => window.removeEventListener(LANGUAGE_CHANGE_EVENT, handler);
+  }, [languages, syncKey]);
+
+  return { activeIndex, setTab };
+}
+
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+
+function CodeTabs({ tabs, syncKey = "sdk-language", ariaLabel = "SDK language tabs" }: CodeTabsProps) {
+  // Memoize languages to prevent useEffect re-subscription on every render (H1 fix)
+  const languageKey = tabs.map((t) => t.language).join(",");
+  const languages = useMemo(() => tabs.map((t) => t.language), [languageKey]);
+  const { activeIndex, setTab } = useCodeTabs(languages, syncKey);
+
+  // Stable unique ID per instance via React's useId (HMR-safe)
+  const groupId = useId();
+
+  // Keyboard navigation
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      let nextIndex: number | null = null;
+
+      if (e.key === "ArrowRight") {
+        nextIndex = (activeIndex + 1) % tabs.length;
+      } else if (e.key === "ArrowLeft") {
+        nextIndex = (activeIndex - 1 + tabs.length) % tabs.length;
+      } else if (e.key === "Home") {
+        nextIndex = 0;
+      } else if (e.key === "End") {
+        nextIndex = tabs.length - 1;
+      }
+
+      if (nextIndex !== null) {
+        e.preventDefault();
+        setTab(nextIndex);
+        // Focus the newly active tab button
+        const btn = document.getElementById(`${groupId}-tab-${nextIndex}`);
+        btn?.focus();
+      }
+    },
+    [activeIndex, tabs.length, setTab, groupId],
+  );
+
+  if (tabs.length === 0) return null;
+
+  return (
+    <div className="my-6 border border-border rounded-lg overflow-hidden">
+      {/* Tab bar */}
+      <div
+        role="tablist"
+        aria-label={ariaLabel}
+        className="flex border-b border-border bg-surface-raised"
+        onKeyDown={handleKeyDown}
+      >
+        {tabs.map((tab, i) => (
+          <button
+            key={tab.language}
+            id={`${groupId}-tab-${i}`}
+            role="tab"
+            aria-selected={i === activeIndex}
+            aria-controls={`${groupId}-panel-${i}`}
+            tabIndex={i === activeIndex ? 0 : -1}
+            className={cn(
+              "px-4 py-2 border-b-2 border-transparent text-[0.8125rem] font-medium font-mono",
+              "text-text-muted cursor-pointer whitespace-nowrap bg-transparent",
+              "transition-colors duration-150 hover:text-text",
+              "focus-visible:outline-2 focus-visible:outline-primary focus-visible:-outline-offset-2",
+              i === activeIndex && "text-text border-b-primary",
+            )}
+            onClick={() => setTab(i)}
+          >
+            {tab.label}
+          </button>
+        ))}
+      </div>
+
+      {/* Panels */}
+      {tabs.map((tab, i) => (
+        <div
+          key={tab.language}
+          id={`${groupId}-panel-${i}`}
+          role="tabpanel"
+          aria-labelledby={`${groupId}-tab-${i}`}
+          tabIndex={0}
+          className="code-tabs-panel"
+          style={{ display: i === activeIndex ? undefined : "none" }}
+          dangerouslySetInnerHTML={{ __html: tab.content }}
+        />
+      ))}
+    </div>
+  );
+}
+
+export { CodeTabs };
+export type { CodeTab, CodeTabsProps };

package/src/islands/CopyButton.tsx

@@ -0,0 +1,101 @@
+/**
+ * CopyButton island — copies code to clipboard with visual feedback.
+ *
+ * Renders a small button with a copy icon that, on click, copies the
+ * provided `code` string to the clipboard. Shows a checkmark for 2s
+ * after a successful copy, then reverts to the copy icon.
+ *
+ * Architecture: React island in `islands/` — hydrated with `client:idle`.
+ * Uses inline SVGs (no icon library) following the ThemeToggle pattern.
+ */
+
+import { useState, useCallback, useRef } from "react";
+
+export interface CopyButtonProps {
+  /** The raw code text to copy to clipboard */
+  code: string;
+}
+
+export function CopyButton({ code }: CopyButtonProps) {
+  const [copied, setCopied] = useState(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const handleCopy = useCallback(() => {
+    // Clear any existing timeout to avoid stale state
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+
+    navigator.clipboard.writeText(code).then(() => {
+      setCopied(true);
+      timeoutRef.current = setTimeout(() => {
+        setCopied(false);
+        timeoutRef.current = null;
+      }, 2000);
+    }).catch(() => {
+      // Clipboard API unavailable — silent fail for MVP
+      console.warn("[CopyButton] Clipboard API unavailable");
+    });
+  }, [code]);
+
+  return (
+    <button
+      type="button"
+      onClick={handleCopy}
+      aria-label={copied ? "Copied!" : "Copy code"}
+      title={copied ? "Copied!" : "Copy code"}
+      className="sg-copy-btn"
+      style={{
+        position: "absolute",
+        top: "0.5rem",
+        right: "0.5rem",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        width: "2rem",
+        height: "2rem",
+        borderRadius: "0.375rem",
+        border: "1px solid var(--color-border, #e5e7eb)",
+        backgroundColor: "var(--color-surface, #ffffff)",
+        color: "var(--color-text-muted, #6b7280)",
+        cursor: "pointer",
+        opacity: copied ? 1 : 0,
+        transition: "opacity 150ms ease, background-color 150ms ease, color 150ms ease",
+      }}
+    >
+      {copied ? (
+        /* Checkmark icon */
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          style={{ color: "#22c55e" }}
+        >
+          <polyline points="20 6 9 17 4 12" />
+        </svg>
+      ) : (
+        /* Copy icon */
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          width="16"
+          height="16"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <rect x="9" y="9" width="13" height="13" rx="2" ry="2" />
+          <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" />
+        </svg>
+      )}
+    </button>
+  );
+}