@specglass/theme-default 0.0.2

package/src/components/CodeBlock.astro

@@ -0,0 +1,142 @@
+---
+/**
+ * CodeBlock component — renders syntax-highlighted code using Shiki
+ * directly (via shared highlighter utility) with a copy-to-clipboard button.
+ *
+ * Uses the same dual-theme CSS variable approach as fenced code blocks
+ * (--shiki-light, --shiki-dark) for seamless dark/light mode switching.
+ *
+ * Supports lang, title (file name label), and highlight (line highlighting).
+ * The CopyButton React island hydrates at idle (not critical for first paint).
+ *
+ * @example
+ * <CodeBlock lang="ts" title="config.ts" highlight="1,3-5">
+ * import { defineConfig } from 'astro/config';
+ * export default defineConfig({});
+ * </CodeBlock>
+ */
+
+import { highlight } from "../utils/shiki.js";
+import { CopyButton } from "../islands/CopyButton";
+import { parseHighlightRange } from "../utils/parse-highlight-range.js";
+
+export interface Props {
+  lang?: string;
+  title?: string;
+  highlight?: string;
+  code?: string;
+}
+
+const { lang = "text", title, highlight: highlightProp, code } = Astro.props;
+
+// Resolve code content: prefer `code` prop, fall back to slot text
+const slotContent = await Astro.slots.render("default");
+
+// Strip HTML tags, then decode common HTML entities from slot rendering
+function decodeEntities(str: string): string {
+  return str
+    .replace(/<\/?[^>]+(>|$)/g, "")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&#x27;/g, "'")
+    .replace(/&#x2F;/g, "/");
+}
+
+const codeContent = code ?? (slotContent ? decodeEntities(slotContent) : "");
+
+// Parse highlight ranges into line numbers array for Shiki decorations
+const markLines = highlightProp ? parseHighlightRange(highlightProp) : undefined;
+
+// Syntax highlight using shared Shiki instance (dual-theme CSS variables)
+const highlightedHtml = await highlight(codeContent, lang, {
+  highlightLines: markLines,
+});
+---
+
+<div class="code-block">
+  {
+    title && (
+      <div class="code-block-header">
+        <span class="code-block-title">{title}</span>
+      </div>
+    )
+  }
+  <div class="code-block-body">
+    <Fragment set:html={highlightedHtml} />
+    <CopyButton code={codeContent} client:idle />
+  </div>
+</div>
+
+<style>
+  .code-block {
+    margin: 1.5rem 0;
+    border: 1px solid var(--code-block-border, #e5e7eb);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .code-block-header {
+    display: flex;
+    align-items: center;
+    padding: 0.5rem 1rem;
+    background-color: var(--code-block-header-bg, #f3f4f6);
+    border-bottom: 1px solid var(--code-block-border, #e5e7eb);
+    font-size: 0.8125rem;
+    font-family: var(
+      --font-mono,
+      ui-monospace,
+      SFMono-Regular,
+      "SF Mono",
+      Menlo,
+      Consolas,
+      monospace
+    );
+  }
+
+  .code-block-title {
+    color: var(--code-block-title-color, #6b7280);
+  }
+
+  .code-block-body {
+    position: relative;
+    overflow-x: auto;
+  }
+
+  /* Show copy button on hover or when it has focus-within */
+  .code-block-body:hover :global(.sg-copy-btn),
+  .code-block-body:focus-within :global(.sg-copy-btn) {
+    opacity: 1 !important;
+  }
+
+  .code-block-body :global(.sg-copy-btn:focus-visible) {
+    outline: 2px solid var(--color-primary, #3b82f6);
+    outline-offset: 2px;
+    opacity: 1 !important;
+  }
+
+  .code-block-body :global(pre) {
+    margin: 0;
+    border-radius: 0;
+    padding: 1rem 1.25rem;
+  }
+
+  .code-block-body :global(code) {
+    font-size: 0.875rem;
+    line-height: 1.7;
+  }
+</style>
+
+<!--
+  Dark mode CSS custom property overrides.
+  Scoped Astro styles don't support :global(.dark), so use an inline style tag.
+-->
+<style is:global>
+  .dark .code-block {
+    --code-block-border: oklch(0.303 0.034 264.376);
+    --code-block-header-bg: oklch(0.179 0.04 264.376);
+    --code-block-title-color: oklch(0.708 0.014 264.364);
+  }
+</style>

package/src/components/CodeBlockGroup.astro

@@ -0,0 +1,196 @@
+---
+/**
+ * CodeBlockGroup component — renders multiple CodeBlock children in a
+ * tabbed interface for comparing related code files.
+ *
+ * Each child CodeBlock's `title` prop becomes the tab label.
+ * If no title is set, falls back to "Tab N".
+ *
+ * NOTE: This component uses its own vanilla JS tab logic rather than
+ * composing Tabs.astro/TabItem.astro. That's intentional — Astro's slot
+ * model doesn't let us dynamically wrap slotted CodeBlock children into
+ * TabItem containers at build time. The tab behavior (roles, keyboard nav,
+ * aria attributes) is equivalent to Tabs.astro.
+ *
+ * @example
+ * <CodeBlockGroup>
+ *   <CodeBlock lang="ts" title="server.ts">const app = express();</CodeBlock>
+ *   <CodeBlock lang="json" title="package.json">{"name": "app"}</CodeBlock>
+ * </CodeBlockGroup>
+ */
+
+// No imports needed — content is slotted
+---
+
+<div class="code-block-group" data-code-group>
+  <slot />
+</div>
+
+<style>
+  .code-block-group {
+    margin: 1.5rem 0;
+    border: 1px solid var(--code-block-border, #e5e7eb);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  /* Suppress child CodeBlock outer margins and borders — the group owns the chrome */
+  .code-block-group :global(.code-block) {
+    margin: 0;
+    border: none;
+    border-radius: 0;
+  }
+</style>
+
+<script>
+  document.addEventListener("DOMContentLoaded", () => {
+    document.querySelectorAll<HTMLDivElement>("[data-code-group]").forEach((group) => {
+      const codeBlocks = group.querySelectorAll<HTMLDivElement>(":scope > .code-block");
+      if (codeBlocks.length <= 1) return; // No tabs needed for single block
+
+      const groupId = `cg-${Math.random().toString(36).slice(2, 9)}`;
+
+      // Create tab header
+      const tabHeader = document.createElement("div");
+      tabHeader.role = "tablist";
+      tabHeader.className = "code-group-tabs";
+      tabHeader.setAttribute("aria-label", "Code file tabs");
+
+      // Build tabs from code blocks
+      codeBlocks.forEach((block, index) => {
+        // Extract title from the header, or use fallback
+        const titleEl = block.querySelector(".code-block-title");
+        const label = titleEl?.textContent?.trim() || `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;
+        tabHeader.appendChild(button);
+
+        // Set up panel attributes
+        block.id = panelId;
+        block.setAttribute("role", "tabpanel");
+        block.setAttribute("aria-labelledby", tabId);
+        block.tabIndex = 0;
+
+        // Hide the code-block-header since the tab bar replaces it
+        const header = block.querySelector<HTMLDivElement>(".code-block-header");
+        if (header) header.style.display = "none";
+
+        // Show/hide blocks
+        if (index !== 0) {
+          block.style.display = "none";
+        }
+      });
+
+      // Insert tab header at the top of the group
+      group.insertBefore(tabHeader, group.firstChild);
+
+      // Tab switching logic
+      const tabs = tabHeader.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;
+        });
+        codeBlocks.forEach((block, i) => {
+          block.style.display = i === index ? "" : "none";
+        });
+      }
+
+      tabs.forEach((tab, index) => {
+        tab.addEventListener("click", () => {
+          activateTab(index);
+          tab.focus();
+        });
+      });
+
+      // Keyboard navigation
+      tabHeader.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>
+
+<!-- All global styles consolidated into one block -->
+<style is:global>
+  .dark .code-block-group {
+    --code-block-border: oklch(0.303 0.034 264.376);
+    --code-block-header-bg: oklch(0.179 0.04 264.376);
+    --code-block-title-color: oklch(0.708 0.014 264.364);
+  }
+
+  .code-group-tabs {
+    display: flex;
+    border-bottom: 1px solid var(--code-block-border, #e5e7eb);
+    background-color: var(--code-block-header-bg, #f3f4f6);
+  }
+
+  .code-group-tabs [role="tab"] {
+    padding: 0.5rem 1rem;
+    border: none;
+    background: none;
+    cursor: pointer;
+    font-size: 0.8125rem;
+    font-weight: 500;
+    font-family: var(
+      --font-mono,
+      ui-monospace,
+      SFMono-Regular,
+      "SF Mono",
+      Menlo,
+      Consolas,
+      monospace
+    );
+    color: var(--code-block-title-color, #6b7280);
+    border-bottom: 2px solid transparent;
+    transition:
+      color 0.15s,
+      border-color 0.15s;
+    white-space: nowrap;
+  }
+
+  .code-group-tabs [role="tab"]:hover {
+    color: var(--color-text, #374151);
+  }
+
+  .code-group-tabs [role="tab"][aria-selected="true"] {
+    color: var(--color-text, #111827);
+    border-bottom-color: var(--color-primary, #3b82f6);
+  }
+
+  .code-group-tabs [role="tab"]:focus-visible {
+    outline: 2px solid var(--color-primary, #3b82f6);
+    outline-offset: -2px;
+  }
+</style>

package/src/components/CodeTabs.astro

@@ -0,0 +1,53 @@
+---
+/**
+ * CodeTabs wrapper — Astro component that hydrates the CodeTabs React island.
+ *
+ * Usage in MDX:
+ *
+ * ```mdx
+ * <CodeTabs tabs={[
+ *   { label: "Python", language: "python", content: "<pre>...</pre>" },
+ *   { label: "Node.js", language: "nodejs", content: "<pre>...</pre>" },
+ *   { label: "cURL", language: "curl", content: "<pre>...</pre>" },
+ * ]} />
+ * ```
+ *
+ * Or with a custom sync key (for independent tab groups):
+ *
+ * ```mdx
+ * <CodeTabs syncKey="api-style" tabs={[
+ *   { label: "REST", language: "rest", content: "..." },
+ *   { label: "GraphQL", language: "graphql", content: "..." },
+ * ]} />
+ * ```
+ *
+ * @see CodeTabs.tsx for the React island implementation
+ */
+import { CodeTabs as CodeTabsIsland } from "../islands/CodeTabs";
+
+interface Props {
+  tabs: Array<{
+    label: string;
+    language: string;
+    content: string;
+  }>;
+  syncKey?: string;
+}
+
+const { tabs, syncKey } = Astro.props as Props;
+---
+
+<CodeTabsIsland client:idle tabs={tabs} syncKey={syncKey} />
+
+<style is:global>
+  /* Suppress inner code-block chrome when rendered inside CodeTabs */
+  .code-tabs-panel .code-block {
+    margin: 0;
+    border: none;
+    border-radius: 0;
+  }
+
+  .code-tabs-panel .code-block-header {
+    display: none;
+  }
+</style>

package/src/components/Footer.astro

@@ -0,0 +1,41 @@
+---
+/**
+ * Footer component for the specglass theme.
+ *
+ * Renders a simple footer with copyright year and optional text
+ * from theme configuration. Can be overridden by placing a custom
+ * Footer.astro at src/components/overrides/Footer.astro.
+ */
+import { config } from "virtual:specglass/config";
+
+const currentYear = new Date().getFullYear();
+const footerText = config.theme?.footer;
+const headerLinks = config.theme?.headerLinks;
+---
+
+<footer class="border-t border-border bg-surface py-8 px-6" aria-label="Site footer">
+  <div
+    class="max-w-[var(--width-content-max)] mx-auto flex flex-col items-center gap-4 text-sm text-text-muted"
+  >
+    {
+      headerLinks && headerLinks.length > 0 && (
+        <nav aria-label="Footer navigation" class="flex gap-6">
+          {headerLinks.map((link) => (
+            <a
+              href={link.href}
+              class="hover:text-text transition-colors"
+              {...(link.href.startsWith("http")
+                ? { target: "_blank", rel: "noopener noreferrer" }
+                : {})}
+            >
+              {link.label}
+            </a>
+          ))}
+        </nav>
+      )
+    }
+    <p class="m-0">
+      {footerText ? footerText : `© ${currentYear} Built with specglass`}
+    </p>
+  </div>
+</footer>

package/src/components/Header.astro

@@ -0,0 +1,80 @@
+---
+/**
+ * Header — Site-wide header with title/logo and navigation links.
+ *
+ * Reads from virtual:specglass/config for site title and theme config.
+ * Includes a mobile menu toggle button and a slot for right-side items
+ */
+import { config } from "virtual:specglass/config";
+---
+
+<header
+  class="fixed top-0 left-0 right-0 z-20 h-(--height-header) border-b border-border bg-surface/95 backdrop-blur-sm"
+  data-pagefind-ignore
+>
+  <div class="flex items-center h-full px-4 md:px-6">
+    <!-- Mobile menu button -->
+    <button
+      id="mobile-menu-toggle"
+      type="button"
+      class="inline-flex items-center justify-center p-2 rounded-md text-text-muted hover:text-text hover:bg-hover-bg focus:outline-none focus-visible:ring-2 focus-visible:ring-primary md:hidden mr-2"
+      aria-expanded="false"
+      aria-controls="sidebar-mobile"
+      aria-label="Toggle navigation menu"
+    >
+      <svg
+        class="h-5 w-5"
+        fill="none"
+        viewBox="0 0 24 24"
+        stroke-width="2"
+        stroke="currentColor"
+        aria-hidden="true"
+      >
+        <path
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          d="M3.75 6.75h16.5M3.75 12h16.5m-16.5 5.25h16.5"></path>
+      </svg>
+    </button>
+
+    <!-- Site title / logo -->
+    <a
+      href="/"
+      class="flex items-center gap-2 font-semibold text-lg text-text hover:text-primary transition-colors no-underline"
+    >
+      {
+        config.theme?.logo && (
+          <img src={config.theme.logo} alt="" class="h-6 w-6" aria-hidden="true" />
+        )
+      }
+      <span>{config.site?.title ?? "Documentation"}</span>
+    </a>
+
+    <!-- Spacer -->
+    <div class="flex-1"></div>
+
+    <!-- Header navigation links from config -->
+    {
+      config.theme?.headerLinks && config.theme.headerLinks.length > 0 && (
+        <nav aria-label="Header navigation" class="hidden md:flex items-center gap-4 mr-4">
+          {config.theme.headerLinks.map((link) => (
+            <a
+              href={link.href}
+              class="text-sm text-text-muted hover:text-text transition-colors focus-visible:ring-2 focus-visible:ring-primary focus-visible:outline-none rounded px-1"
+              {...(link.href.startsWith("http")
+                ? { target: "_blank", rel: "noopener noreferrer" }
+                : {})}
+            >
+              {link.label}
+            </a>
+          ))}
+        </nav>
+      )
+    }
+
+    <!-- Right-side header actions (theme toggle, search, etc.) -->
+    <div id="header-actions" class="flex items-center gap-2">
+      <slot />
+    </div>
+  </div>
+</header>

package/src/components/Sidebar.astro

@@ -0,0 +1,117 @@
+---
+/**
+ * Sidebar — Recursive navigation tree for the documentation sidebar.
+ *
+ * Renders NavItem[] with collapsible sections, active page highlighting,
+ * external links, and hidden item filtering.
+ */
+import type { NavItem } from "@specglass/core";
+import { isActiveOrAncestor } from "../utils/sidebar-helpers.js";
+
+export interface Props {
+  items: NavItem[];
+  currentSlug: string;
+  depth?: number;
+}
+
+const { items, currentSlug, depth = 0 } = Astro.props;
+---
+
+<ul class:list={["list-none p-0 m-0", depth > 0 && "ml-3 border-l border-border pl-3"]}>
+  {
+    items
+      .filter((item) => !item.hidden)
+      .map((item) => {
+        const isActive = item.type === "page" && item.slug === currentSlug;
+        const isAncestor = item.type === "section" && isActiveOrAncestor(item, currentSlug);
+        const isCollapsed = item.collapsed && !isAncestor;
+
+        return (
+          <li class="my-0.5">
+            {item.type === "external-link" && item.href ? (
+              /* External link */
+              <a
+                href={item.href}
+                target="_blank"
+                rel="noopener noreferrer"
+                class="flex items-center gap-1.5 px-2 py-1.5 text-sm text-text-muted hover:text-text rounded-md hover:bg-hover-bg transition-colors no-underline"
+              >
+                <span>{item.title}</span>
+                <svg
+                  class="h-3.5 w-3.5 opacity-50"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  stroke-width="2"
+                  stroke="currentColor"
+                  aria-hidden="true"
+                >
+                  <path
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                    d="M13.5 6H5.25A2.25 2.25 0 003 8.25v10.5A2.25 2.25 0 005.25 21h10.5A2.25 2.25 0 0018 18.75V10.5m-10.5 6L21 3m0 0h-5.25M21 3v5.25"
+                  />
+                </svg>
+              </a>
+            ) : item.type === "section" ? (
+              /* Collapsible section */
+              <details open={!isCollapsed}>
+                <summary
+                  class:list={[
+                    "flex items-center gap-1 px-2 py-1.5 text-sm font-medium cursor-pointer select-none rounded-md hover:bg-hover-bg transition-colors list-none",
+                    isAncestor ? "text-primary" : "text-text",
+                  ]}
+                >
+                  {item.icon && <span class="mr-1">{item.icon}</span>}
+                  <span>{item.title}</span>
+                  <svg
+                    class="h-3.5 w-3.5 ml-auto opacity-40 transition-transform duration-200 details-chevron"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke-width="2"
+                    stroke="currentColor"
+                    aria-hidden="true"
+                  >
+                    <path
+                      stroke-linecap="round"
+                      stroke-linejoin="round"
+                      d="M8.25 4.5l7.5 7.5-7.5 7.5"
+                    />
+                  </svg>
+                </summary>
+                {item.children && (
+                  <Astro.self items={item.children} currentSlug={currentSlug} depth={depth + 1} />
+                )}
+              </details>
+            ) : (
+              /* Regular page link */
+              <a
+                href={`/${item.slug}`}
+                class:list={[
+                  "flex items-center gap-1.5 px-2 py-1.5 text-sm rounded-md transition-colors no-underline",
+                  isActive
+                    ? "bg-primary/10 text-primary font-medium"
+                    : "text-text-muted hover:text-text hover:bg-hover-bg",
+                ]}
+                aria-current={isActive ? "page" : undefined}
+              >
+                {item.icon && <span class="mr-1">{item.icon}</span>}
+                <span>{item.title}</span>
+              </a>
+            )}
+          </li>
+        );
+      })
+  }
+</ul>
+
+<style>
+  /* Rotate chevron when details is open */
+  details[open] > summary .details-chevron {
+    transform: rotate(90deg);
+  }
+
+  /* Remove default marker from summary */
+  summary::-webkit-details-marker {
+    display: none;
+  }
+</style>

package/src/components/TabItem.astro

@@ -0,0 +1,24 @@
+---
+/**
+ * TabItem component — wraps content for use inside <Tabs>.
+ *
+ * Each TabItem has a required `label` prop that becomes the tab button text.
+ * Content is rendered via <slot />.
+ *
+ * @example
+ * <Tabs>
+ *   <TabItem label="npm">npm install foo</TabItem>
+ *   <TabItem label="yarn">yarn add foo</TabItem>
+ * </Tabs>
+ */
+
+export interface Props {
+  label: string;
+}
+
+const { label } = Astro.props;
+---
+
+<div class="tab-item" data-tab-label={label}>
+  <slot />
+</div>