@tomehq/theme 0.6.3 → 0.7.0

package/src/__tests__/feedback-widget.test.tsx

@@ -0,0 +1,132 @@
+import { describe, it, expect, vi, beforeEach, beforeAll } from "vitest";
+import React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import Shell from "../Shell.js";
+
+// jsdom doesn't provide matchMedia
+beforeAll(() => {
+  Object.defineProperty(window, "matchMedia", {
+    writable: true,
+    value: vi.fn().mockImplementation((query: string) => ({
+      matches: query.includes("dark"),
+      media: query,
+      onchange: null,
+      addListener: vi.fn(),
+      removeListener: vi.fn(),
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+      dispatchEvent: vi.fn(),
+    })),
+  });
+});
+
+// ── Minimal Shell props for feedback widget testing ──────
+
+const baseConfig = {
+  name: "Test Docs",
+  theme: { preset: "amber", mode: "auto" },
+  toc: { enabled: false },
+};
+
+const navigation = [{
+  section: "Docs",
+  pages: [{ id: "test", title: "Test Page", urlPath: "/test" }],
+}];
+
+const allPages = [{ id: "test", title: "Test Page", description: "A test page" }];
+
+function renderShell(configOverrides = {}) {
+  return render(
+    <Shell
+      config={{ ...baseConfig, ...configOverrides }}
+      navigation={navigation}
+      currentPageId="test"
+      pageHtml="<h1>Test Page</h1><p>Content here.</p>"
+      pageTitle="Test Page"
+      headings={[]}
+      allPages={allPages}
+      onNavigate={() => {}}
+    />
+  );
+}
+
+// ── Setup ────────────────────────────────────────────────
+
+beforeEach(() => {
+  localStorage.clear();
+  (window as any).__tome = {
+    trackFeedback: vi.fn(),
+    trackSearch: vi.fn(),
+  };
+});
+
+// ── Tests ────────────────────────────────────────────────
+
+describe("FeedbackWidget", () => {
+  it("renders thumbs up and down buttons by default", () => {
+    renderShell();
+    expect(screen.getByTestId("feedback-up")).toBeInTheDocument();
+    expect(screen.getByTestId("feedback-down")).toBeInTheDocument();
+    expect(screen.getByText("Was this helpful?")).toBeInTheDocument();
+  });
+
+  it("hides feedback widget when feedback.enabled is false", () => {
+    renderShell({ feedback: { enabled: false } });
+    expect(screen.queryByTestId("feedback-up")).not.toBeInTheDocument();
+    expect(screen.queryByText("Was this helpful?")).not.toBeInTheDocument();
+  });
+
+  it("shows thanks message after thumbs up without textInput", () => {
+    renderShell();
+    fireEvent.click(screen.getByTestId("feedback-up"));
+    expect(screen.getByText("Thanks for your feedback!")).toBeInTheDocument();
+    expect(screen.queryByTestId("feedback-up")).not.toBeInTheDocument();
+  });
+
+  it("fires trackFeedback on thumbs up without textInput", () => {
+    renderShell();
+    fireEvent.click(screen.getByTestId("feedback-up"));
+    expect((window as any).__tome.trackFeedback).toHaveBeenCalledWith("test", "up");
+  });
+
+  it("fires trackFeedback on thumbs down without textInput", () => {
+    renderShell();
+    fireEvent.click(screen.getByTestId("feedback-down"));
+    expect((window as any).__tome.trackFeedback).toHaveBeenCalledWith("test", "down");
+  });
+
+  it("stores feedback in localStorage", () => {
+    renderShell();
+    fireEvent.click(screen.getByTestId("feedback-up"));
+    expect(localStorage.getItem("tome-feedback-test")).toBe("up");
+  });
+
+  it("shows text input after thumbs up when textInput is enabled", () => {
+    renderShell({ feedback: { enabled: true, textInput: true } });
+    fireEvent.click(screen.getByTestId("feedback-up"));
+    expect(screen.getByTestId("feedback-text-input")).toBeInTheDocument();
+    expect(screen.getByTestId("feedback-submit")).toBeInTheDocument();
+    expect(screen.getByText("Any additional feedback? (optional)")).toBeInTheDocument();
+  });
+
+  it("submits text feedback and shows thanks", () => {
+    renderShell({ feedback: { enabled: true, textInput: true } });
+    fireEvent.click(screen.getByTestId("feedback-up"));
+
+    const input = screen.getByTestId("feedback-text-input");
+    fireEvent.change(input, { target: { value: "Great docs!" } });
+    fireEvent.click(screen.getByTestId("feedback-submit"));
+
+    expect((window as any).__tome.trackFeedback).toHaveBeenCalledWith("test", "up", "Great docs!");
+    expect(screen.getByText("Thanks for your feedback!")).toBeInTheDocument();
+  });
+
+  it("skip button submits without comment", () => {
+    renderShell({ feedback: { enabled: true, textInput: true } });
+    fireEvent.click(screen.getByTestId("feedback-down"));
+    fireEvent.click(screen.getByText("Skip"));
+
+    expect((window as any).__tome.trackFeedback).toHaveBeenCalledWith("test", "down");
+    expect(screen.getByText("Thanks for your feedback!")).toBeInTheDocument();
+  });
+});

package/src/ai-api.ts

@@ -0,0 +1,110 @@
+/**
+ * Shared AI API utilities for Tome's AI features (chat + search).
+ * Supports OpenAI and Anthropic providers with BYOK (Bring Your Own Key).
+ */
+
+export type AiProvider = "openai" | "anthropic" | "custom";
+
+export interface AiMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+/**
+ * Build a system prompt with optional documentation context.
+ */
+export function buildSystemPrompt(context?: string, instruction?: string): string {
+  const base = instruction || "You are a helpful documentation assistant. Answer questions accurately based on the documentation provided below. If the answer isn't in the documentation, say so clearly. Keep answers concise and reference specific sections when possible.";
+  if (!context) return base;
+  // Truncate context to stay within token limits (~100K chars ≈ 25K tokens)
+  const trimmed = context.length > 100000 ? context.slice(0, 100000) + "\n\n[Documentation truncated...]" : context;
+  return `${base}\n\nDocumentation:\n${trimmed}`;
+}
+
+/**
+ * Call OpenAI's chat completions API.
+ */
+export async function callOpenAI(
+  messages: AiMessage[],
+  apiKey: string,
+  model: string,
+  systemPrompt: string,
+): Promise<string> {
+  const res = await fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model,
+      messages: [
+        { role: "system", content: systemPrompt },
+        ...messages.map((m) => ({ role: m.role, content: m.content })),
+      ],
+    }),
+  });
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`OpenAI API error (${res.status}): ${err}`);
+  }
+  const data = await res.json();
+  return data.choices?.[0]?.message?.content || "No response.";
+}
+
+/**
+ * Call Anthropic's messages API.
+ */
+export async function callAnthropic(
+  messages: AiMessage[],
+  apiKey: string,
+  model: string,
+  systemPrompt: string,
+): Promise<string> {
+  const res = await fetch("https://api.anthropic.com/v1/messages", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+      "anthropic-dangerous-direct-browser-access": "true",
+    },
+    body: JSON.stringify({
+      model,
+      max_tokens: 1024,
+      system: systemPrompt,
+      messages: messages.map((m) => ({ role: m.role, content: m.content })),
+    }),
+  });
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Anthropic API error (${res.status}): ${err}`);
+  }
+  const data = await res.json();
+  return data.content?.[0]?.text || "No response.";
+}
+
+/**
+ * Get the default model for a provider.
+ */
+export function getDefaultModel(provider: AiProvider): string {
+  if (provider === "openai") return "gpt-4o-mini";
+  return "claude-sonnet-4-20250514";
+}
+
+/**
+ * Call the appropriate AI provider with a query and context.
+ * Returns the AI's response text.
+ */
+export async function callAiProvider(
+  provider: AiProvider,
+  messages: AiMessage[],
+  apiKey: string,
+  model: string,
+  systemPrompt: string,
+): Promise<string> {
+  if (provider === "openai") {
+    return callOpenAI(messages, apiKey, model, systemPrompt);
+  }
+  return callAnthropic(messages, apiKey, model, systemPrompt);
+}

package/src/entry-helpers.ts

@@ -52,6 +52,7 @@ export interface ApiReferencePage {
   headings: Array<{ depth: number; text: string; id: string }>;
   changelogEntries?: undefined;
   apiManifest: any;
+  asyncApiManifest?: any;
 }
 
 export type LoadedPage = HtmlPage | MdxPage | ApiReferencePage;
@@ -124,9 +125,13 @@ export async function loadPage(
   // Regular .md page — mod.default is { html, frontmatter, headings }
   if (!mod.default) throw new PageNotFoundError(id);
 
-  // API reference page (synthetic route from OpenAPI spec)
-  if (mod.isApiReference && mod.apiManifest) {
-    return { isMdx: false, isApiReference: true, ...mod.default, apiManifest: mod.apiManifest };
+  // API reference page (synthetic route from OpenAPI/AsyncAPI spec)
+  if (mod.isApiReference && (mod.apiManifest || mod.asyncApiManifest)) {
+    return {
+      isMdx: false, isApiReference: true, ...mod.default,
+      apiManifest: mod.apiManifest,
+      asyncApiManifest: mod.asyncApiManifest,
+    };
   }
 
   // Changelog page type

package/src/entry.test.tsx

@@ -1,4 +1,3 @@
-import React from "react";
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { render, act } from "@testing-library/react";
 
@@ -31,27 +30,6 @@ vi.mock("virtual:tome/config", () => ({
   },
 }));
 
-const mockRoutes = [
-  {
-    id: "index",
-    urlPath: "/",
-    filePath: "pages/index.md",
-    frontmatter: { title: "Home", description: "Welcome" },
-  },
-  {
-    id: "quickstart",
-    urlPath: "/quickstart",
-    filePath: "pages/quickstart.md",
-    frontmatter: { title: "Quick Start", description: "Get started" },
-  },
-  {
-    id: "api-reference",
-    urlPath: "/api",
-    filePath: "__api-reference__",
-    frontmatter: { title: "API Reference", description: "API docs" },
-  },
-];
-
 const mockNavigation = [
   { section: "Guide", pages: [{ id: "index", title: "Home", urlPath: "/" }] },
 ];
@@ -173,6 +151,12 @@ vi.mock("@tomehq/components", () => ({
   LinkCard: () => <div />,
   CardGrid: () => <div />,
   ApiReference: MockApiReference,
+  AsyncApiReference: (p: any) => <div data-testid="async-api-ref" />,
+  ProtocolBadge: () => <div />,
+  DirectionBadge: () => <div />,
+  ChannelCard: () => <div />,
+  MessageBlock: () => <div />,
+  AsyncParameterTable: () => <div />,
 }));
 
 // ── Global stubs ─────────────────────────────────────────

package/src/entry.tsx

@@ -7,7 +7,6 @@ import {
   computeEditUrl,
   resolveInitialPageId,
   detectCurrentVersion,
-  NavigationCancelledError,
   type LoadedPage,
 } from "./entry-helpers.js";
 
@@ -39,6 +38,7 @@ import {
   LinkCard,
   CardGrid,
   ApiReference,
+  AsyncApiReference,
 } from "@tomehq/components";
 
 const MDX_COMPONENTS: Record<string, React.ComponentType<any>> = {
@@ -576,10 +576,12 @@ function App() {
         lastUpdated={currentRoute?.lastUpdated}
         changelogEntries={!pageData?.isMdx ? pageData?.changelogEntries : undefined}
         apiManifest={(!pageData?.isMdx && pageData?.isApiReference) ? pageData.apiManifest : undefined}
+        asyncApiManifest={(!pageData?.isMdx && pageData?.isApiReference) ? (pageData as any).asyncApiManifest : undefined}
         apiBaseUrl={config.api?.baseUrl}
         apiPlayground={config.api?.playground}
         apiAuth={config.api?.auth}
         ApiReferenceComponent={ApiReference}
+        AsyncApiReferenceComponent={AsyncApiReference}
         onNavigate={navigateTo}
         allPages={allPages}
         docContext={docContext}

package/src/presets.ts

@@ -49,13 +49,13 @@ export const THEME_PRESETS = {
   cipher: {
     dark: {
       bg:"#050508",sf:"#0c0c12",sfH:"#12121a",bd:"#1a1a25",
-      tx:"#d4ff00",tx2:"#8a90a0",txM:"#6a7080",
+      tx:"#d4ff00",tx2:"#8a90a0",txM:"#7e8494",
       ac:"#6666ff",acD:"rgba(102,102,255,0.10)",acT:"#8080ff",
       cdBg:"#08080e",cdTx:"#b0c870",sbBg:"#08080d",hdBg:"rgba(5,5,8,0.88)",
     },
     light: {
       bg:"#f0f2f5",sf:"#ffffff",sfH:"#e8eaef",bd:"#d0d4db",
-      tx:"#0f1219",tx2:"#4a5060",txM:"#6a7080",
+      tx:"#0f1219",tx2:"#4a5060",txM:"#5c6272",
       ac:"#2020cc",acD:"rgba(32,32,204,0.08)",acT:"#1a1aa8",
       cdBg:"#e6e9ef",cdTx:"#2a3520",sbBg:"#ebedf2",hdBg:"rgba(240,242,245,0.90)",
     },
@@ -64,7 +64,7 @@ export const THEME_PRESETS = {
   mint: {
     dark: {
       bg:"#0d1117",sf:"#161b22",sfH:"#1c2129",bd:"#21262d",
-      tx:"#e6edf3",tx2:"#8b949e",txM:"#6e7681",
+      tx:"#e6edf3",tx2:"#8b949e",txM:"#7d858f",
       ac:"#0ea371",acD:"rgba(14,163,113,0.10)",acT:"#2dd4a0",
       cdBg:"#0a0e14",cdTx:"#adbac7",sbBg:"#0d1117",hdBg:"rgba(13,17,23,0.88)",
     },
@@ -76,6 +76,96 @@ export const THEME_PRESETS = {
     },
     fonts: { heading: "Inter", body: "Inter", code: "Fira Code" },
   },
+  ocean: {
+    dark: {
+      bg:"#0a1628",sf:"#0f1d33",sfH:"#142540",bd:"#1a2e50",
+      tx:"#e0e8f0",tx2:"#8ca0b8",txM:"#7b92aa",
+      ac:"#0ea5e9",acD:"rgba(14,165,233,0.10)",acT:"#38bdf8",
+      cdBg:"#081320",cdTx:"#94b4d0",sbBg:"#0a1628",hdBg:"rgba(10,22,40,0.90)",
+    },
+    light: {
+      bg:"#f0f7ff",sf:"#ffffff",sfH:"#e8f0fa",bd:"#ccdcef",
+      tx:"#0c1929",tx2:"#3d5a78",txM:"#4a6a88",
+      ac:"#0369a1",acD:"rgba(3,105,161,0.07)",acT:"#025e8f",
+      cdBg:"#e4edf7",cdTx:"#1a3050",sbBg:"#eef4fc",hdBg:"rgba(240,247,255,0.92)",
+    },
+    fonts: { heading: "Outfit", body: "Inter", code: "JetBrains Mono" },
+  },
+  rose: {
+    dark: {
+      bg:"#0f0a10",sf:"#171118",sfH:"#1e1620",bd:"#2a1f2c",
+      tx:"#f0e4f0",tx2:"#b09ab0",txM:"#8a7890",
+      ac:"#f43f5e",acD:"rgba(244,63,94,0.10)",acT:"#fb7185",
+      cdBg:"#0d080e",cdTx:"#c8aec8",sbBg:"#0f0a10",hdBg:"rgba(15,10,16,0.88)",
+    },
+    light: {
+      bg:"#fef7f7",sf:"#ffffff",sfH:"#fceef0",bd:"#f0d4d8",
+      tx:"#1a0f12",tx2:"#6b4048",txM:"#8a5a64",
+      ac:"#c81e3e",acD:"rgba(200,30,62,0.06)",acT:"#a81835",
+      cdBg:"#f8eaec",cdTx:"#3a1a22",sbBg:"#fdf2f4",hdBg:"rgba(254,247,247,0.92)",
+    },
+    fonts: { heading: "Playfair Display", body: "Source Sans 3", code: "Fira Code" },
+  },
+  forest: {
+    dark: {
+      bg:"#091209",sf:"#0f1a0f",sfH:"#152215",bd:"#1e2e1e",
+      tx:"#e0f0e0",tx2:"#8aaa8a",txM:"#6a8a6a",
+      ac:"#22c55e",acD:"rgba(34,197,94,0.10)",acT:"#4ade80",
+      cdBg:"#070e07",cdTx:"#a0c4a0",sbBg:"#091209",hdBg:"rgba(9,18,9,0.90)",
+    },
+    light: {
+      bg:"#f4faf4",sf:"#ffffff",sfH:"#e8f4e8",bd:"#c8e0c8",
+      tx:"#0a1a0a",tx2:"#3a5a3a",txM:"#5a7a5a",
+      ac:"#15803d",acD:"rgba(21,128,61,0.07)",acT:"#116d34",
+      cdBg:"#e4f2e4",cdTx:"#1a3a1a",sbBg:"#eef6ee",hdBg:"rgba(244,250,244,0.92)",
+    },
+    fonts: { heading: "Merriweather", body: "Nunito Sans", code: "Source Code Pro" },
+  },
+  slate: {
+    dark: {
+      bg:"#0f1115",sf:"#16181e",sfH:"#1c1f26",bd:"#24272e",
+      tx:"#e2e4e8",tx2:"#9498a0",txM:"#808690",
+      ac:"#94a3b8",acD:"rgba(148,163,184,0.10)",acT:"#b0bec8",
+      cdBg:"#0c0e12",cdTx:"#a8acb4",sbBg:"#0f1115",hdBg:"rgba(15,17,21,0.88)",
+    },
+    light: {
+      bg:"#f8fafc",sf:"#ffffff",sfH:"#f1f5f9",bd:"#d8dfe7",
+      tx:"#0f172a",tx2:"#475569",txM:"#64748b",
+      ac:"#475569",acD:"rgba(71,85,105,0.07)",acT:"#3a4a5c",
+      cdBg:"#f0f4f8",cdTx:"#1e293b",sbBg:"#f5f7fa",hdBg:"rgba(248,250,252,0.92)",
+    },
+    fonts: { heading: "Inter", body: "Inter", code: "JetBrains Mono" },
+  },
+  sunset: {
+    dark: {
+      bg:"#120c06",sf:"#1a1208",sfH:"#22180c",bd:"#2e2010",
+      tx:"#f0e4d4",tx2:"#b0986a",txM:"#907850",
+      ac:"#f97316",acD:"rgba(249,115,22,0.10)",acT:"#fb923c",
+      cdBg:"#0e0a05",cdTx:"#c8aa78",sbBg:"#120c06",hdBg:"rgba(18,12,6,0.90)",
+    },
+    light: {
+      bg:"#fffbf5",sf:"#ffffff",sfH:"#fef3e6",bd:"#f0d8b8",
+      tx:"#1a1008",tx2:"#6a5030",txM:"#8a6840",
+      ac:"#c2410c",acD:"rgba(194,65,12,0.06)",acT:"#a63a0a",
+      cdBg:"#faf0e2",cdTx:"#3a2810",sbBg:"#fdf6ec",hdBg:"rgba(255,251,245,0.92)",
+    },
+    fonts: { heading: "Sora", body: "DM Sans", code: "Fira Code" },
+  },
+  carbon: {
+    dark: {
+      bg:"#080808",sf:"#101010",sfH:"#171717",bd:"#1f1f1f",
+      tx:"#d4d4d4",tx2:"#888888",txM:"#787878",
+      ac:"#e4e4e4",acD:"rgba(228,228,228,0.08)",acT:"#f0f0f0",
+      cdBg:"#0a0a0a",cdTx:"#a0a0a0",sbBg:"#080808",hdBg:"rgba(8,8,8,0.90)",
+    },
+    light: {
+      bg:"#f5f5f5",sf:"#ffffff",sfH:"#ebebeb",bd:"#d4d4d4",
+      tx:"#171717",tx2:"#525252",txM:"#6b6b6b",
+      ac:"#262626",acD:"rgba(38,38,38,0.06)",acT:"#1a1a1a",
+      cdBg:"#eaeaea",cdTx:"#1a1a1a",sbBg:"#f0f0f0",hdBg:"rgba(245,245,245,0.92)",
+    },
+    fonts: { heading: "Geist", body: "Geist", code: "Geist Mono" },
+  },
 } as const satisfies Record<string, ThemePreset>;
 
 export type PresetName = keyof typeof THEME_PRESETS;

package/src/routing.test.ts

@@ -61,9 +61,8 @@ describe("pathnameToPageId", () => {
 
   it("resolves versioned index", () => {
     // /docs/v1/ → strip basePath → /v1/ → strip leading / → v1/ → strip trailing / → v1
-    // But our route ID is "v1/index", not "v1", so this needs to resolve properly
-    // After all stripping: "v1" — not in routes (v1/index is). Let's test this edge case.
-    expect(pathnameToPageId("/docs/v1", basePath, routes)).toBeNull();
+    // Route v1/index has urlPath "/v1/" — matches via URL-based resolution
+    expect(pathnameToPageId("/docs/v1", basePath, routes)).toBe("v1/index");
   });
 
   describe("with empty basePath", () => {

package/src/routing.ts

@@ -18,8 +18,10 @@ export function pathnameToPageId(
   routes: MinimalRoute[],
 ): string | null {
   let relative = pathname;
-  if (basePath && relative.startsWith(basePath)) {
-    relative = relative.slice(basePath.length);
+  // Handle basePath stripping — treat "/" basePath as empty to avoid stripping all leading slashes
+  const normalizedBase = basePath === "/" ? "" : basePath.replace(/\/+$/, "");
+  if (normalizedBase && relative.startsWith(normalizedBase)) {
+    relative = relative.slice(normalizedBase.length);
   }
   const id =
     relative
@@ -27,8 +29,14 @@ export function pathnameToPageId(
       .replace(/\/index\.html$/, "")
       .replace(/\.html$/, "")
       .replace(/\/$/, "") || "index";
-  const route = routes.find((r) => r.id === id);
-  return route ? id : null;
+  // Match by ID first (most common: urlPath matches ID)
+  const routeById = routes.find((r) => r.id === id);
+  if (routeById) return id;
+  // Match by urlPath (for synthetic routes where ID differs from URL, e.g. api-reference at /events-api)
+  const urlPath = "/" + id;
+  const urlPathWithSlash = urlPath + "/";
+  const routeByUrl = routes.find((r) => r.urlPath === urlPath || r.urlPath === urlPathWithSlash);
+  return routeByUrl ? routeByUrl.id : null;
 }
 
 /**