@specglass/theme-default 0.0.2

package/src/utils/schema-renderer.test.ts

@@ -0,0 +1,269 @@
+/**
+ * Tests for the schema-renderer utility.
+ * Covers renderTypeString() and flattenSchemaProperties().
+ */
+import { describe, it, expect } from "vitest";
+import type { ApiSchema } from "@specglass/core";
+import { renderTypeString, flattenSchemaProperties } from "./schema-renderer";
+
+describe("renderTypeString", () => {
+  it("returns 'unknown' for undefined schema", () => {
+    expect(renderTypeString(undefined)).toBe("unknown");
+  });
+
+  it("renders simple string type", () => {
+    expect(renderTypeString({ type: "string" })).toBe("string");
+  });
+
+  it("renders integer type", () => {
+    expect(renderTypeString({ type: "integer" })).toBe("integer");
+  });
+
+  it("renders boolean type", () => {
+    expect(renderTypeString({ type: "boolean" })).toBe("boolean");
+  });
+
+  it("renders type with format", () => {
+    expect(renderTypeString({ type: "string", format: "uuid" })).toBe(
+      "string (uuid)",
+    );
+  });
+
+  it("renders type with date-time format", () => {
+    expect(renderTypeString({ type: "string", format: "date-time" })).toBe(
+      "string (date-time)",
+    );
+  });
+
+  it("renders array type with items", () => {
+    expect(
+      renderTypeString({ type: "array", items: { type: "string" } }),
+    ).toBe("array<string>");
+  });
+
+  it("renders nested array type", () => {
+    expect(
+      renderTypeString({
+        type: "array",
+        items: { type: "array", items: { type: "integer" } },
+      }),
+    ).toBe("array<array<integer>>");
+  });
+
+  it("renders enum type", () => {
+    expect(
+      renderTypeString({ type: "string", enum: ["active", "inactive"] }),
+    ).toBe("string (enum)");
+  });
+
+  it("renders enum without explicit type defaults to string", () => {
+    expect(renderTypeString({ enum: ["a", "b", "c"] })).toBe("string (enum)");
+  });
+
+  it("renders $ref — extracts component name", () => {
+    expect(
+      renderTypeString({ ref: "#/components/schemas/Pet" }),
+    ).toBe("Pet");
+  });
+
+  it("renders $ref with deep path", () => {
+    expect(
+      renderTypeString({ ref: "#/components/schemas/models/UserProfile" }),
+    ).toBe("UserProfile");
+  });
+
+  it("renders nullable type", () => {
+    expect(renderTypeString({ type: "string", nullable: true })).toBe(
+      "string | null",
+    );
+  });
+
+  it("renders allOf composition", () => {
+    const schema: ApiSchema = {
+      allOf: [{ ref: "#/components/schemas/Base" }, { type: "object" }],
+    };
+    expect(renderTypeString(schema)).toBe("Base & object");
+  });
+
+  it("renders oneOf composition", () => {
+    const schema: ApiSchema = {
+      oneOf: [{ type: "string" }, { type: "integer" }],
+    };
+    expect(renderTypeString(schema)).toBe("string | integer");
+  });
+
+  it("renders anyOf composition", () => {
+    const schema: ApiSchema = {
+      anyOf: [{ type: "string" }, { type: "boolean" }],
+    };
+    expect(renderTypeString(schema)).toBe("string | boolean");
+  });
+
+  it("renders object type", () => {
+    expect(renderTypeString({ type: "object" })).toBe("object");
+  });
+
+  it("handles schema with no type", () => {
+    expect(renderTypeString({})).toBe("unknown");
+  });
+});
+
+describe("flattenSchemaProperties", () => {
+  it("returns empty array for undefined schema", () => {
+    expect(flattenSchemaProperties(undefined)).toEqual([]);
+  });
+
+  it("returns empty array for schema without properties", () => {
+    expect(flattenSchemaProperties({ type: "string" })).toEqual([]);
+  });
+
+  it("flattens simple properties", () => {
+    const schema: ApiSchema = {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "User name" },
+        age: { type: "integer" },
+      },
+      required: ["name"],
+    };
+
+    const props = flattenSchemaProperties(schema);
+    expect(props).toHaveLength(2);
+    expect(props[0]).toEqual({
+      name: "name",
+      type: "string",
+      required: true,
+      description: "User name",
+      depth: 0,
+      enumValues: undefined,
+    });
+    expect(props[1]).toEqual({
+      name: "age",
+      type: "integer",
+      required: false,
+      description: undefined,
+      depth: 0,
+      enumValues: undefined,
+    });
+  });
+
+  it("marks required fields correctly", () => {
+    const schema: ApiSchema = {
+      type: "object",
+      properties: {
+        id: { type: "integer" },
+        email: { type: "string" },
+      },
+      required: ["id", "email"],
+    };
+
+    const props = flattenSchemaProperties(schema);
+    expect(props.every((p) => p.required)).toBe(true);
+  });
+
+  it("accepts external requiredFields parameter", () => {
+    const schema: ApiSchema = {
+      type: "object",
+      properties: {
+        foo: { type: "string" },
+        bar: { type: "string" },
+      },
+    };
+
+    const props = flattenSchemaProperties(schema, ["foo"]);
+    expect(props[0]!.required).toBe(true);
+    expect(props[1]!.required).toBe(false);
+  });
+
+  it("expands nested object properties to depth 1", () => {
+    const schema: ApiSchema = {
+      type: "object",
+      properties: {
+        address: {
+          type: "object",
+          properties: {
+            street: { type: "string", description: "Street name" },
+            city: { type: "string" },
+          },
+          required: ["street"],
+        },
+      },
+    };
+
+    const props = flattenSchemaProperties(schema);
+    expect(props).toHaveLength(3);
+    expect(props[0]!.name).toBe("address");
+    expect(props[0]!.depth).toBe(0);
+    expect(props[1]!.name).toBe("street");
+    expect(props[1]!.depth).toBe(1);
+    expect(props[1]!.required).toBe(true);
+    expect(props[2]!.name).toBe("city");
+    expect(props[2]!.depth).toBe(1);
+    expect(props[2]!.required).toBe(false);
+  });
+
+  it("expands array item properties to depth 1", () => {
+    const schema: ApiSchema = {
+      type: "object",
+      properties: {
+        items: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              id: { type: "integer" },
+              label: { type: "string" },
+            },
+            required: ["id"],
+          },
+        },
+      },
+    };
+
+    const props = flattenSchemaProperties(schema);
+    expect(props).toHaveLength(3);
+    expect(props[0]!.name).toBe("items");
+    expect(props[0]!.depth).toBe(0);
+    expect(props[1]!.name).toBe("id");
+    expect(props[1]!.depth).toBe(1);
+    expect(props[1]!.required).toBe(true);
+    expect(props[2]!.name).toBe("label");
+    expect(props[2]!.depth).toBe(1);
+  });
+
+  it("includes enum values in flattened properties", () => {
+    const schema: ApiSchema = {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["active", "inactive", "pending"],
+          description: "Account status",
+        },
+      },
+    };
+
+    const props = flattenSchemaProperties(schema);
+    expect(props).toHaveLength(1);
+    expect(props[0]!.enumValues).toEqual(["active", "inactive", "pending"]);
+    expect(props[0]!.type).toBe("string (enum)");
+  });
+
+  it("respects maxDepth=0 — no expansion", () => {
+    const schema: ApiSchema = {
+      type: "object",
+      properties: {
+        nested: {
+          type: "object",
+          properties: {
+            inner: { type: "string" },
+          },
+        },
+      },
+    };
+
+    const props = flattenSchemaProperties(schema, undefined, 0);
+    expect(props).toHaveLength(1);
+    expect(props[0]!.name).toBe("nested");
+  });
+});

package/src/utils/schema-renderer.ts

@@ -0,0 +1,152 @@
+/**
+ * Shared utility for rendering ApiSchema objects into displayable
+ * type strings and processing nested property structures.
+ *
+ * Used by ApiParameters.astro and ApiResponse.astro components.
+ *
+ * @module
+ */
+
+import type { ApiSchema } from "@specglass/core";
+
+/** A flattened property row for display in parameter/schema tables */
+export interface SchemaProperty {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+  depth: number;
+  enumValues?: string[];
+}
+
+/**
+ * Render an ApiSchema into a human-readable type string.
+ *
+ * Examples:
+ * - `{ type: "string" }` → `"string"`
+ * - `{ type: "string", format: "uuid" }` → `"string (uuid)"`
+ * - `{ type: "array", items: { type: "string" } }` → `"array<string>"`
+ * - `{ type: "object" }` → `"object"`
+ * - `{ ref: "#/components/schemas/Pet" }` → `"Pet"`
+ * - `{ enum: ["a", "b"] }` → `"string (enum)"`
+ * - `{ allOf: [...] }` → `"allOf<...>"`
+ * - `{ oneOf: [...] }` → `"oneOf<...>"`
+ */
+export function renderTypeString(schema: ApiSchema | undefined): string {
+  if (!schema) return "unknown";
+
+  // $ref display — extract the component name from the path
+  if (schema.ref) {
+    const parts = schema.ref.split("/");
+    return parts[parts.length - 1] || schema.ref;
+  }
+
+  // Composition types
+  if (schema.allOf && schema.allOf.length > 0) {
+    const inner = schema.allOf.map((s) => renderTypeString(s)).join(" & ");
+    return inner;
+  }
+  if (schema.oneOf && schema.oneOf.length > 0) {
+    const inner = schema.oneOf.map((s) => renderTypeString(s)).join(" | ");
+    return inner;
+  }
+  if (schema.anyOf && schema.anyOf.length > 0) {
+    const inner = schema.anyOf.map((s) => renderTypeString(s)).join(" | ");
+    return inner;
+  }
+
+  // Enum
+  if (schema.enum && schema.enum.length > 0) {
+    const baseType = schema.type || "string";
+    return `${baseType} (enum)`;
+  }
+
+  // Array
+  if (schema.type === "array" && schema.items) {
+    const itemType = renderTypeString(schema.items);
+    return `array<${itemType}>`;
+  }
+
+  // Nullable
+  const base = schema.type || "unknown";
+  const format = schema.format ? ` (${schema.format})` : "";
+  const nullable = schema.nullable ? " | null" : "";
+
+  return `${base}${format}${nullable}`;
+}
+
+/**
+ * Flatten an ApiSchema's nested properties into a list of SchemaProperty rows,
+ * suitable for rendering in a table. Only expands 1 level deep for MVP.
+ */
+export function flattenSchemaProperties(
+  schema: ApiSchema | undefined,
+  requiredFields?: string[],
+  maxDepth: number = 1,
+): SchemaProperty[] {
+  if (!schema) return [];
+
+  const properties: SchemaProperty[] = [];
+  const required = new Set(requiredFields ?? schema.required ?? []);
+
+  if (schema.properties) {
+    for (const [name, propSchema] of Object.entries(schema.properties)) {
+      properties.push({
+        name,
+        type: renderTypeString(propSchema),
+        required: required.has(name),
+        description: propSchema.description,
+        depth: 0,
+        enumValues:
+          propSchema.enum?.map((v) => String(v)),
+      });
+
+      // Expand one level of nested object properties
+      if (
+        maxDepth > 0 &&
+        propSchema.type === "object" &&
+        propSchema.properties
+      ) {
+        const nestedRequired = new Set(propSchema.required ?? []);
+        for (const [nestedName, nestedSchema] of Object.entries(
+          propSchema.properties,
+        )) {
+          properties.push({
+            name: nestedName,
+            type: renderTypeString(nestedSchema),
+            required: nestedRequired.has(nestedName),
+            description: nestedSchema.description,
+            depth: 1,
+            enumValues:
+              nestedSchema.enum?.map((v) => String(v)),
+          });
+        }
+      }
+
+      // Expand array item properties
+      if (
+        maxDepth > 0 &&
+        propSchema.type === "array" &&
+        propSchema.items?.type === "object" &&
+        propSchema.items?.properties
+      ) {
+        const nestedRequired = new Set(propSchema.items.required ?? []);
+        for (const [nestedName, nestedSchema] of Object.entries(
+          propSchema.items.properties,
+        )) {
+          properties.push({
+            name: nestedName,
+            type: renderTypeString(nestedSchema),
+            required: nestedRequired.has(nestedName),
+            description: nestedSchema.description,
+            depth: 1,
+            enumValues:
+              nestedSchema.enum?.map((v) => String(v)),
+          });
+        }
+      }
+    }
+  }
+
+  return properties;
+}

package/src/utils/shiki.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared Shiki highlighter utility for CodeBlock components.
+ *
+ * Uses a module-level cached highlighter instance so we don't
+ * pay the startup cost on every render. Common languages are
+ * pre-loaded at initialization; additional languages are loaded
+ * on demand. Output uses `defaultColor: false` which emits CSS
+ * variables (--shiki-light, --shiki-dark) instead of hardcoded
+ * inline colors — matching the fenced code block rendering path.
+ */
+
+import { createHighlighter, type Highlighter } from "shiki";
+
+let highlighter: Highlighter | null = null;
+
+export interface HighlightOptions {
+  /** Line numbers to highlight (1-indexed) */
+  highlightLines?: number[];
+}
+
+/**
+ * Common language shorthand aliases that Shiki may not auto-resolve.
+ */
+const LANG_ALIASES: Record<string, string> = {
+  ts: "typescript",
+  js: "javascript",
+  py: "python",
+  rb: "ruby",
+  sh: "bash",
+  shell: "bash",
+  yml: "yaml",
+  md: "markdown",
+  mdx: "markdown",
+};
+
+/**
+ * Syntax-highlight `code` using Shiki dual-theme (github-light / github-dark).
+ * Returns raw HTML string with CSS variable tokens — ready for `set:html`.
+ */
+export async function highlight(
+  code: string,
+  lang: string,
+  options?: HighlightOptions,
+): Promise<string> {
+  if (!highlighter) {
+    highlighter = await createHighlighter({
+      themes: ["github-light", "github-dark"],
+      langs: [
+        "typescript",
+        "javascript",
+        "python",
+        "bash",
+        "json",
+        "yaml",
+        "html",
+        "css",
+        "markdown",
+        "tsx",
+        "jsx",
+        "ruby",
+        "go",
+        "rust",
+        "sql",
+        "graphql",
+        "diff",
+        "text",
+      ],
+    });
+  }
+
+  // Normalize common aliases
+  lang = LANG_ALIASES[lang] ?? lang;
+
+  // Load language on demand if not already loaded
+  const loaded = highlighter.getLoadedLanguages();
+  if (!loaded.includes(lang as never)) {
+    try {
+      await highlighter.loadLanguage(lang as never);
+    } catch {
+      // Unknown language — fall back to plaintext
+      lang = "text";
+    }
+  }
+
+  // Build decorations for line highlighting
+  const lines = code.split("\n");
+  const decorations = options?.highlightLines?.map((line) => ({
+    start: { line: line - 1, character: 0 },
+    end: { line: line - 1, character: lines[line - 1]?.length ?? 0 },
+    properties: { class: "highlighted" },
+  }));
+
+  return highlighter.codeToHtml(code, {
+    lang,
+    themes: { light: "github-light", dark: "github-dark" },
+    defaultColor: false,
+    ...(decorations?.length ? { decorations } : {}),
+  });
+}

package/src/utils/sidebar-helpers.ts

@@ -0,0 +1,24 @@
+/**
+ * Sidebar navigation helpers — shared logic used by both
+ * `Sidebar.astro` and its unit tests.
+ */
+import type { NavItem } from "@specglass/core";
+
+/** Filter out hidden items from a navigation list. */
+export function filterVisibleItems(items: NavItem[]): NavItem[] {
+  return items.filter((item) => !item.hidden);
+}
+
+/** Check if this item or any descendant is the current page. */
+export function isActiveOrAncestor(
+  item: NavItem,
+  currentSlug: string,
+): boolean {
+  if (item.type === "page" && item.slug === currentSlug) return true;
+  if (item.children) {
+    return item.children.some((child) =>
+      isActiveOrAncestor(child, currentSlug),
+    );
+  }
+  return false;
+}

package/src/utils/theme-css.ts

@@ -0,0 +1,101 @@
+import type { SpecglassConfig } from "@specglass/core";
+
+/**
+ * CSS custom property mapping from theme config.
+ *
+ * Maps config values to CSS custom properties that override
+ * the Tailwind @theme design tokens. This implements the config-level
+ * tier of the three-tier customization system.
+ *
+ * The generated CSS is injected as a <style> block in the layout <head>,
+ * ensuring config values take precedence over @theme defaults.
+ */
+
+/** Properties that apply globally (brand colors, fonts) — always :root */
+const ROOT_CSS_MAP: Array<{
+  configPath: (theme: NonNullable<SpecglassConfig["theme"]>) => string | undefined;
+  cssProperty: string;
+}> = [
+  { configPath: (t) => t.primaryColor ?? t.colors?.primary, cssProperty: "--color-primary" },
+  { configPath: (t) => t.accentColor ?? t.colors?.accent, cssProperty: "--color-primary-light" },
+  { configPath: (t) => t.fontFamily, cssProperty: "--font-sans" },
+  { configPath: (t) => t.codeFontFamily, cssProperty: "--font-mono" },
+];
+
+/**
+ * Surface color overrides — support light/dark pairs.
+ *
+ * Each entry maps a config color key to the CSS properties for light and dark.
+ * - `string` value → dark-only override (backward compat)
+ * - `{ light, dark }` → explicit pair, light goes to base token, dark to -dark variant
+ */
+type ColorValue = string | { light?: string; dark?: string } | undefined;
+
+interface ColorMapping {
+  configPath: (theme: NonNullable<SpecglassConfig["theme"]>) => ColorValue;
+  lightProperty: string;
+  darkProperty: string;
+}
+
+const COLOR_PAIR_MAP: ColorMapping[] = [
+  { configPath: (t) => t.colors?.background, lightProperty: "--color-surface", darkProperty: "--color-surface-dark" },
+  { configPath: (t) => t.colors?.foreground, lightProperty: "--color-text", darkProperty: "--color-text-dark" },
+  { configPath: (t) => t.colors?.muted, lightProperty: "--color-text-muted", darkProperty: "--color-text-muted-dark" },
+  { configPath: (t) => t.colors?.border, lightProperty: "--color-border", darkProperty: "--color-border-dark" },
+];
+
+/**
+ * Generates a CSS string with custom property overrides from the theme config.
+ *
+ * Brand tokens (primaryColor, fonts) are set at `:root` and apply to both modes.
+ * Surface colors support two formats:
+ * - `"#0a0a0f"` (string) → sets `-dark` variant only (backward compat)
+ * - `{ light: "#fff", dark: "#000" }` → sets both base and `-dark` variants
+ *
+ * Returns an empty string if no theme config values are set,
+ * allowing the @theme defaults to apply.
+ *
+ * @example
+ * ```ts
+ * const css = generateThemeCSS(config);
+ * // String value: ":root { --color-surface-dark: #0a0a0f; }"
+ * // Pair value:   ":root { --color-surface: #fff; --color-surface-dark: #0a0a0f; }"
+ * ```
+ */
+export function generateThemeCSS(config: SpecglassConfig): string {
+  const theme = config.theme;
+  if (!theme) return "";
+
+  const overrides: string[] = [];
+
+  // Brand / font overrides → always :root
+  for (const mapping of ROOT_CSS_MAP) {
+    const value = mapping.configPath(theme);
+    if (value !== undefined) {
+      overrides.push(`  ${mapping.cssProperty}: ${value};`);
+    }
+  }
+
+  // Surface color overrides → light/dark pair or dark-only
+  for (const mapping of COLOR_PAIR_MAP) {
+    const value = mapping.configPath(theme);
+    if (value === undefined) continue;
+
+    if (typeof value === "string") {
+      // Backward compat: string = dark-only override
+      overrides.push(`  ${mapping.darkProperty}: ${value};`);
+    } else {
+      // Explicit pair
+      if (value.light) {
+        overrides.push(`  ${mapping.lightProperty}: ${value.light};`);
+      }
+      if (value.dark) {
+        overrides.push(`  ${mapping.darkProperty}: ${value.dark};`);
+      }
+    }
+  }
+
+  if (overrides.length === 0) return "";
+
+  return `:root {\n${overrides.join("\n")}\n}`;
+}

package/src/utils/theme-helpers.ts

@@ -0,0 +1,59 @@
+/**
+ * Theme utilities — pure functions for theme storage and application.
+ *
+ * Extracted to a shared utility for testability (Story 3.1 pattern).
+ * Used by ThemeToggle.tsx. The FOUC-prevention inline script reimplements
+ * the same logic inline because `is:inline` scripts cannot import modules.
+ */
+
+export type Theme = "dark" | "light";
+
+/** localStorage key for theme preference */
+export const THEME_STORAGE_KEY = "specglass-theme";
+
+/** Default theme when no preference is stored */
+export const DEFAULT_THEME: Theme = "dark";
+
+/**
+ * Read the stored theme preference from localStorage.
+ * Returns null if no preference is stored or localStorage is unavailable.
+ */
+export function getStoredTheme(): Theme | null {
+  try {
+    const stored = localStorage.getItem(THEME_STORAGE_KEY);
+    if (stored === "dark" || stored === "light") {
+      return stored;
+    }
+    return null;
+  } catch {
+    // localStorage unavailable (SSR, privacy mode, etc.)
+    return null;
+  }
+}
+
+/**
+ * Determine the effective theme given a stored preference.
+ * Falls back to DEFAULT_THEME ("dark") when no preference exists.
+ */
+export function getEffectiveTheme(stored: Theme | null): Theme {
+  return stored ?? DEFAULT_THEME;
+}
+
+/**
+ * Apply a theme by toggling the .dark class on <html>.
+ * Also persists the preference to localStorage.
+ */
+export function applyTheme(theme: Theme): void {
+  const root = document.documentElement;
+  if (theme === "dark") {
+    root.classList.add("dark");
+  } else {
+    root.classList.remove("dark");
+  }
+
+  try {
+    localStorage.setItem(THEME_STORAGE_KEY, theme);
+  } catch {
+    // localStorage unavailable — graceful degradation
+  }
+}