@specglass/theme-default 0.0.2

package/src/layouts/DocPage.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Tests for DocPage layout supporting utilities and contracts.
+ *
+ * Note: .astro components cannot be unit tested directly in Vitest.
+ * These tests verify the shared utils that the layout components import,
+ * and validate data contracts. Build verification confirms rendering.
+ */
+import { describe, it, expect } from "vitest";
+import type { NavItem, NavigationTree } from "@specglass/core";
+import {
+  filterVisibleItems,
+  isActiveOrAncestor,
+} from "../utils/sidebar-helpers.js";
+import { filterTocHeadings, type Heading } from "../utils/toc-helpers.js";
+
+// ─── Tests ─────────────────────────────────────────────────────────
+
+describe("Sidebar filtering", () => {
+  it("excludes hidden items", () => {
+    const items: NavItem[] = [
+      { title: "Visible", slug: "visible", type: "page" },
+      { title: "Hidden", slug: "hidden", type: "page", hidden: true },
+      { title: "Also Visible", slug: "also-visible", type: "page" },
+    ];
+    const result = filterVisibleItems(items);
+    expect(result).toHaveLength(2);
+    expect(result.map((i) => i.title)).toEqual(["Visible", "Also Visible"]);
+  });
+
+  it("includes all items when none are hidden", () => {
+    const items: NavItem[] = [
+      { title: "A", slug: "a", type: "page" },
+      { title: "B", slug: "b", type: "page" },
+    ];
+    expect(filterVisibleItems(items)).toHaveLength(2);
+  });
+
+  it("returns empty array for all-hidden items", () => {
+    const items: NavItem[] = [
+      { title: "A", slug: "a", type: "page", hidden: true },
+    ];
+    expect(filterVisibleItems(items)).toHaveLength(0);
+  });
+});
+
+describe("Sidebar active detection", () => {
+  it("detects direct page match", () => {
+    const item: NavItem = { title: "Guide", slug: "guide", type: "page" };
+    expect(isActiveOrAncestor(item, "guide")).toBe(true);
+    expect(isActiveOrAncestor(item, "other")).toBe(false);
+  });
+
+  it("detects ancestor section when child is active", () => {
+    const section: NavItem = {
+      title: "API",
+      slug: "api",
+      type: "section",
+      children: [
+        { title: "Auth", slug: "api/auth", type: "page" },
+        { title: "Users", slug: "api/users", type: "page" },
+      ],
+    };
+    expect(isActiveOrAncestor(section, "api/auth")).toBe(true);
+    expect(isActiveOrAncestor(section, "api/users")).toBe(true);
+    expect(isActiveOrAncestor(section, "other")).toBe(false);
+  });
+
+  it("handles deeply nested sections", () => {
+    const root: NavItem = {
+      title: "Docs",
+      slug: "docs",
+      type: "section",
+      children: [
+        {
+          title: "Advanced",
+          slug: "docs/advanced",
+          type: "section",
+          children: [
+            {
+              title: "Plugins",
+              slug: "docs/advanced/plugins",
+              type: "page",
+            },
+          ],
+        },
+      ],
+    };
+    expect(isActiveOrAncestor(root, "docs/advanced/plugins")).toBe(true);
+    expect(isActiveOrAncestor(root, "other")).toBe(false);
+  });
+
+  it("ignores external links", () => {
+    const item: NavItem = {
+      title: "External",
+      slug: "",
+      type: "external-link",
+      href: "https://example.com",
+    };
+    expect(isActiveOrAncestor(item, "")).toBe(false);
+  });
+});
+
+describe("Table of contents heading filtering", () => {
+  it("includes h2 and h3 headings only", () => {
+    const headings: Heading[] = [
+      { depth: 1, slug: "title", text: "Title" },
+      { depth: 2, slug: "intro", text: "Introduction" },
+      { depth: 3, slug: "detail", text: "Detail" },
+      { depth: 4, slug: "deep", text: "Deep" },
+    ];
+    const result = filterTocHeadings(headings);
+    expect(result).toHaveLength(2);
+    expect(result.map((h) => h.text)).toEqual(["Introduction", "Detail"]);
+  });
+
+  it("returns empty array when no h2/h3 headings exist", () => {
+    const headings: Heading[] = [
+      { depth: 1, slug: "title", text: "Title" },
+      { depth: 4, slug: "deep", text: "Deep" },
+    ];
+    expect(filterTocHeadings(headings)).toHaveLength(0);
+  });
+
+  it("handles empty headings array", () => {
+    expect(filterTocHeadings([])).toHaveLength(0);
+  });
+});
+
+describe("NavigationTree contract", () => {
+  it("matches expected shape for layout props", () => {
+    const tree: NavigationTree = {
+      items: [
+        { title: "Getting Started", slug: "getting-started", type: "page" },
+        {
+          title: "API Reference",
+          slug: "api",
+          type: "section",
+          collapsed: true,
+          children: [
+            { title: "Auth", slug: "api/auth", type: "page" },
+            {
+              title: "GitHub",
+              slug: "",
+              type: "external-link",
+              href: "https://github.com",
+            },
+          ],
+        },
+      ],
+    };
+
+    expect(tree.items).toHaveLength(2);
+    expect(tree.items[0].type).toBe("page");
+    expect(tree.items[1].type).toBe("section");
+    expect(tree.items[1].collapsed).toBe(true);
+    expect(tree.items[1].children).toHaveLength(2);
+    expect(tree.items[1].children![1].type).toBe("external-link");
+    expect(tree.items[1].children![1].href).toBe("https://github.com");
+  });
+});
+
+describe("DocPage props contract", () => {
+  it("validates expected frontmatter shape", () => {
+    const frontmatter: Record<string, unknown> = {
+      title: "Getting Started",
+      description: "A guide to getting started",
+    };
+    expect(frontmatter.title).toBeDefined();
+    expect(typeof frontmatter.title).toBe("string");
+  });
+
+  it("headings array has correct shape", () => {
+    const headings = [
+      { depth: 2, slug: "installation", text: "Installation" },
+      { depth: 3, slug: "npm", text: "Using npm" },
+    ];
+    headings.forEach((h) => {
+      expect(typeof h.depth).toBe("number");
+      expect(typeof h.slug).toBe("string");
+      expect(typeof h.text).toBe("string");
+    });
+  });
+});

package/src/layouts/LandingPage.astro

@@ -0,0 +1,143 @@
+---
+/**
+ * LandingPage layout — full-width, no sidebar.
+ *
+ * Used for the site index page or any page with `layout: landing` in frontmatter.
+ * Architecture mandate: one of three MVP layouts (DocPage, ApiReferencePage, LandingPage).
+ * Typed props from core: { frontmatter, content, navigation }.
+ */
+import Header from "../components/Header.astro";
+import Footer from "../components/Footer.astro";
+import { ThemeToggle } from "../islands/ThemeToggle";
+import { SearchPalette } from "../islands/SearchPalette";
+import "../styles/global.css";
+import type { NavigationTree } from "@specglass/core";
+import { config } from "virtual:specglass/config";
+import { generateThemeCSS } from "../utils/theme-css";
+
+export interface Props {
+  /** Page title from frontmatter */
+  title: string;
+  /** Page description from frontmatter */
+  description?: string;
+  /** Full frontmatter data */
+  frontmatter: Record<string, unknown>;
+  /** Navigation tree (for header links) */
+  navigation: NavigationTree;
+}
+
+const { title, description, frontmatter } = Astro.props;
+const themeCSS = generateThemeCSS(config);
+
+// Hero section configuration from frontmatter
+const heroTitle = (frontmatter.hero_title as string) ?? (frontmatter.title as string) ?? title;
+const heroSubtitle = (frontmatter.hero_subtitle as string) ?? description;
+const ctaLabel = (frontmatter.cta_label as string) ?? "Get Started";
+const ctaHref = (frontmatter.cta_href as string) ?? "/getting-started";
+const ctaSecondaryLabel = frontmatter.cta_secondary_label as string | undefined;
+const ctaSecondaryHref = frontmatter.cta_secondary_href as string | undefined;
+---
+
+<html lang="en" class="dark">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    {config.theme?.favicon && <link rel="icon" href={config.theme.favicon} />}
+    {config.theme?.socialImage && <meta property="og:image" content={config.theme.socialImage} />}
+    {themeCSS && <style set:html={themeCSS} />}
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap"
+      rel="stylesheet"
+    />
+    <!-- FOUC prevention: apply stored theme before first paint -->
+    <script is:inline>
+      (function () {
+        function applyStoredTheme() {
+          var stored = null;
+          try {
+            stored = localStorage.getItem("specglass-theme");
+          } catch (e) {}
+          var theme = stored === "dark" || stored === "light" ? stored : "dark";
+          if (theme === "dark") {
+            document.documentElement.classList.add("dark");
+          } else {
+            document.documentElement.classList.remove("dark");
+          }
+        }
+        applyStoredTheme();
+        if (!window.__sgThemeInit) {
+          window.__sgThemeInit = true;
+          document.addEventListener("astro:after-swap", applyStoredTheme);
+        }
+      })();
+    </script>
+  </head>
+  <body class="min-h-screen bg-surface text-text">
+    <!-- Skip to content link for accessibility -->
+    <a
+      href="#main-content"
+      class="sr-only focus:not-sr-only focus:absolute focus:top-2 focus:left-2 focus:z-50 focus:bg-primary focus:text-white focus:px-4 focus:py-2 focus:rounded"
+    >
+      Skip to content
+    </a>
+
+    <Header>
+      <SearchPalette client:idle />
+      <ThemeToggle client:load />
+    </Header>
+
+    <main id="main-content" class="pt-(--height-header)" data-pagefind-body>
+      <!-- Hero section -->
+      <section class="relative overflow-hidden py-24 px-6 text-center" aria-label="Hero">
+        <div
+          class="absolute inset-0 bg-linear-to-br from-primary/10 via-transparent to-primary/5 dark:from-primary/15 dark:to-primary/5"
+          aria-hidden="true"
+        >
+        </div>
+        <div class="relative max-w-3xl mx-auto">
+          <h1
+            class="text-5xl font-bold tracking-tight mb-6 bg-linear-to-r from-primary to-primary-light bg-clip-text text-transparent"
+          >
+            {heroTitle}
+          </h1>
+          {
+            heroSubtitle && (
+              <p class="text-xl text-text-muted mb-10 max-w-2xl mx-auto leading-relaxed">
+                {heroSubtitle}
+              </p>
+            )
+          }
+          <div class="flex justify-center gap-4 flex-wrap">
+            <a
+              href={ctaHref}
+              class="inline-flex items-center px-6 py-3 bg-primary text-white font-medium rounded-lg hover:bg-primary-dark transition-colors shadow-lg shadow-primary/25"
+            >
+              {ctaLabel}
+            </a>
+            {
+              ctaSecondaryLabel && ctaSecondaryHref && (
+                <a
+                  href={ctaSecondaryHref}
+                  class="inline-flex items-center px-6 py-3 border border-border text-text font-medium rounded-lg hover:bg-hover-bg transition-colors"
+                >
+                  {ctaSecondaryLabel}
+                </a>
+              )
+            }
+          </div>
+        </div>
+      </section>
+
+      <!-- Content area (renders MDX body) -->
+      <article class="sg-content max-w-(--width-content-max) mx-auto px-6 py-12">
+        <slot />
+      </article>
+    </main>
+
+    <Footer />
+  </body>
+</html>

package/src/lib/utils.ts

@@ -0,0 +1,13 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+/**
+ * Merge Tailwind CSS classes with clsx and tailwind-merge.
+ * This is the standard shadcn/ui utility function.
+ *
+ * Note: Scaffolding for future shadcn/ui component integration.
+ * Will be used by UI primitives in upcoming stories (e.g., search, dialogs).
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/src/styles/global.css

@@ -0,0 +1,241 @@
+@import "tailwindcss";
+@plugin "tailwindcss-animate";
+
+/*
+ * Specglass — Design Tokens (Tailwind v4 CSS-first configuration)
+ *
+ * These tokens define the visual identity of the default theme.
+ * Override via site-level CSS or tailwind @theme extensions.
+ */
+@theme {
+  /* Primary brand colors */
+  --color-primary: oklch(0.546 0.245 262.881);
+  --color-primary-light: oklch(0.623 0.214 259.815);
+  --color-primary-dark: oklch(0.488 0.243 264.376);
+
+  /* Surface / background colors */
+  --color-surface: oklch(0.985 0.002 247.839);
+  --color-surface-dark: oklch(0.21 0.034 264.665);
+  --color-sidebar-bg: oklch(0.968 0.007 264.536);
+  --color-sidebar-bg-dark: oklch(0.179 0.04 264.376);
+
+  /* Text colors */
+  --color-text: oklch(0.21 0.034 264.665);
+  --color-text-dark: oklch(0.968 0.007 264.536);
+  --color-text-muted: oklch(0.553 0.013 264.364);
+  --color-text-muted-dark: oklch(0.708 0.014 264.364);
+
+  /* Border colors */
+  --color-border: oklch(0.872 0.01 258.338);
+  --color-border-dark: oklch(0.303 0.034 264.376);
+
+  /* Raised surfaces (e.g., kbd badges, chips) */
+  --color-surface-raised: oklch(0.937 0.006 264.364);
+  --color-surface-raised-dark: oklch(0.269 0.036 264.376);
+
+  /* Interactive states */
+  --color-hover-bg: oklch(0.951 0.004 264.364);
+  --color-hover-bg-dark: oklch(0.269 0.036 264.376);
+
+  /* Layout dimensions */
+  --width-sidebar: 16rem;
+  --width-toc: 14rem;
+  --width-content-max: 48rem;
+  --height-header: 3.5rem;
+
+  /* Spacing */
+  --spacing-page: 1.5rem;
+
+  /* Typography */
+  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
+  --font-mono: "JetBrains Mono", ui-monospace, "Cascadia Code", monospace;
+
+  /* Transitions */
+  --transition-normal: 150ms;
+}
+
+/*
+ * Tailwind v4 dark mode — class-based strategy.
+ * Activates dark: variant when .dark class is on <html>.
+ */
+@custom-variant dark (&:where(.dark, .dark *));
+
+/*
+ * Dark mode token remapping.
+ * When .dark is present on <html>, base tokens remap to their dark variants.
+ * This means ALL existing Tailwind classes (bg-surface, text-text, etc.)
+ * automatically respond to dark mode — zero component template changes needed.
+ *
+ * Note: --color-primary is intentionally NOT remapped. The brand blue
+ * oklch(0.546 0.245 262.881) has sufficient contrast (~7:1) on dark surface
+ * oklch(0.21 0.034 264.665). For lighter accents, use dark:text-primary-light.
+ */
+.dark {
+  --color-surface: var(--color-surface-dark);
+  --color-sidebar-bg: var(--color-sidebar-bg-dark);
+  --color-text: var(--color-text-dark);
+  --color-text-muted: var(--color-text-muted-dark);
+  --color-border: var(--color-border-dark);
+  --color-hover-bg: var(--color-hover-bg-dark);
+  --color-surface-raised: var(--color-surface-raised-dark);
+}
+
+/* ─── Base Styles ───────────────────────────────────────────── */
+
+html {
+  scroll-behavior: smooth;
+  scroll-padding-top: calc(var(--height-header) + 1rem);
+}
+
+body {
+  font-family: var(--font-sans);
+  color: var(--color-text);
+  background-color: var(--color-surface);
+  line-height: 1.7;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  transition: color var(--transition-normal) ease,
+              background-color var(--transition-normal) ease;
+}
+
+/* ─── Content Prose Styles ──────────────────────────────────── */
+
+.sg-content h1 {
+  @apply text-3xl font-bold mt-0 mb-4;
+}
+.sg-content h2 {
+  @apply text-2xl font-semibold mt-10 mb-4 pb-2 border-b border-border;
+}
+.sg-content h3 {
+  @apply text-xl font-semibold mt-8 mb-3;
+}
+.sg-content h4 {
+  @apply text-lg font-semibold mt-6 mb-2;
+}
+
+.sg-content p {
+  @apply my-4 leading-7;
+}
+.sg-content ul,
+.sg-content ol {
+  @apply my-4 pl-6;
+}
+.sg-content li {
+  @apply my-1;
+}
+
+.sg-content a {
+  @apply text-primary underline decoration-primary/30 underline-offset-2
+         hover:decoration-primary/80 transition-colors;
+}
+
+.sg-content code:not(pre code) {
+  @apply bg-gray-100 dark:bg-gray-800 text-sm px-1.5 py-0.5 rounded font-mono;
+}
+
+.sg-content pre {
+  @apply my-6 rounded-lg overflow-x-auto text-sm leading-6;
+  padding: 1rem 1.25rem;
+}
+
+/* ─── Shiki Dual-Theme CSS Variables ────────────────────────── */
+/*
+ * With shikiConfig.defaultColor: false, Shiki emits CSS variables
+ * (--shiki-light, --shiki-dark) on each token instead of hardcoded colors.
+ * Map the right variable set based on the active color mode.
+ *
+ * Fallback colors ensure code is visible even if Shiki variables
+ * aren't present (e.g., inline <pre> without Shiki processing).
+ */
+pre > code,
+pre > code span {
+  color: var(--shiki-light, var(--color-text, #1f2937));
+  background-color: transparent;
+}
+pre {
+  background-color: var(--shiki-light-bg, #f6f8fa) !important;
+}
+.dark pre > code,
+.dark pre > code span {
+  color: var(--shiki-dark, var(--color-text, #e5e7eb));
+}
+.dark pre {
+  background-color: var(--shiki-dark-bg, #161b22) !important;
+}
+
+/* Line highlighting — Astro/Shiki marks highlighted lines with .line.highlighted */
+pre code .line.highlighted {
+  background-color: oklch(0.546 0.245 262.881 / 0.1);
+  display: inline-block;
+  width: 100%;
+  margin: 0 -1.25rem;
+  padding: 0 1.25rem;
+}
+.dark pre code .line.highlighted {
+  background-color: oklch(0.623 0.214 259.815 / 0.15);
+}
+
+/* ─── Code Block Copy Button (fenced code blocks) ──────────── */
+
+.code-block--fenced .code-block-body {
+  position: relative;
+}
+
+.code-block--fenced .code-block-body pre {
+  margin: 0;
+  border-radius: 0;
+  padding: 1rem 1.25rem;
+}
+
+.sg-copy-btn-native {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: 0.375rem;
+  border: 1px solid var(--color-border, #e5e7eb);
+  background-color: var(--color-surface, #ffffff);
+  color: var(--color-text-muted, #6b7280);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 150ms ease, background-color 150ms ease;
+}
+
+.code-block--fenced:hover .sg-copy-btn-native,
+.sg-copy-btn-native:focus-visible {
+  opacity: 1;
+}
+
+.sg-copy-btn-native:focus-visible {
+  outline: 2px solid var(--color-primary, #3b82f6);
+  outline-offset: 2px;
+}
+
+.sg-content blockquote {
+  @apply border-l-4 border-primary/30 pl-4 my-4 italic text-text-muted;
+}
+
+.sg-content table {
+  @apply w-full my-6 text-sm;
+}
+
+.sg-content th {
+  @apply text-left font-semibold p-2 border-b-2 border-border;
+}
+
+.sg-content td {
+  @apply p-2 border-b border-border;
+}
+
+.sg-content hr {
+  @apply my-8 border-border;
+}
+
+.sg-content img {
+  @apply rounded-lg max-w-full my-6;
+}
+

package/src/utils/parse-highlight-range.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from "vitest";
+import { parseHighlightRange } from "./parse-highlight-range.js";
+
+describe("parseHighlightRange", () => {
+  it("parses a single number", () => {
+    expect(parseHighlightRange("3")).toEqual([3]);
+  });
+
+  it("parses a range", () => {
+    expect(parseHighlightRange("3-5")).toEqual([3, 4, 5]);
+  });
+
+  it("parses comma-separated numbers", () => {
+    expect(parseHighlightRange("1,3,8")).toEqual([1, 3, 8]);
+  });
+
+  it("parses mixed numbers and ranges", () => {
+    expect(parseHighlightRange("1,3-5,8")).toEqual([1, 3, 4, 5, 8]);
+  });
+
+  it("returns empty array for empty string", () => {
+    expect(parseHighlightRange("")).toEqual([]);
+  });
+
+  it("returns empty array for whitespace-only string", () => {
+    expect(parseHighlightRange("   ")).toEqual([]);
+  });
+
+  it("handles whitespace around numbers", () => {
+    expect(parseHighlightRange(" 1 , 3 - 5 , 8 ")).toEqual([1, 3, 4, 5, 8]);
+  });
+
+  it("handles a single range at start of line", () => {
+    expect(parseHighlightRange("1-3")).toEqual([1, 2, 3]);
+  });
+
+  it("skips invalid segments gracefully", () => {
+    expect(parseHighlightRange("1,abc,3")).toEqual([1, 3]);
+  });
+});

package/src/utils/parse-highlight-range.ts

@@ -0,0 +1,41 @@
+/**
+ * Parses a highlight range string into an array of line numbers.
+ *
+ * Supports single numbers, ranges (e.g., "3-5"), and comma-separated
+ * combinations (e.g., "1,3-5,8").
+ *
+ * @example
+ * parseHighlightRange("1,3-5,8") // → [1, 3, 4, 5, 8]
+ * parseHighlightRange("") // → []
+ */
+export function parseHighlightRange(range: string): number[] {
+  const trimmed = range.trim();
+  if (!trimmed) return [];
+
+  const result: number[] = [];
+  const parts = trimmed.split(",");
+
+  for (const part of parts) {
+    const segment = part.trim();
+    if (!segment) continue;
+
+    if (segment.includes("-")) {
+      const [startStr, endStr] = segment.split("-");
+      const start = parseInt(startStr.trim(), 10);
+      const end = parseInt(endStr.trim(), 10);
+
+      if (isNaN(start) || isNaN(end)) continue;
+
+      for (let i = start; i <= end; i++) {
+        result.push(i);
+      }
+    } else {
+      const num = parseInt(segment, 10);
+      if (!isNaN(num)) {
+        result.push(num);
+      }
+    }
+  }
+
+  return result;
+}