@tomehq/theme 0.3.1 → 0.3.3

package/dist/entry.js

@@ -1,6 +1,6 @@
 import {
   entry_default
-} from "./chunk-YXKONM3A.js";
+} from "./chunk-MSXVVBDW.js";
 export {
   entry_default as default
 };

package/dist/index.d.ts

@@ -10,6 +10,7 @@ interface I18nInfo {
     defaultLocale: string;
     locales: string[];
     localeNames?: Record<string, string>;
+    localeDirs?: Record<string, "ltr" | "rtl">;
 }
 interface ShellProps {
     config: {
@@ -49,6 +50,12 @@ interface ShellProps {
             link?: string;
             dismissible?: boolean;
         };
+        socialLinks?: Array<{
+            platform: string;
+            url: string;
+            label?: string;
+            icon?: string;
+        }>;
         [key: string]: unknown;
     };
     navigation: Array<{
@@ -58,6 +65,10 @@ interface ShellProps {
             id: string;
             urlPath: string;
             icon?: string;
+            badge?: {
+                text: string;
+                variant: string;
+            };
         }>;
     }>;
     currentPageId: string;
@@ -85,6 +96,22 @@ interface ShellProps {
             items: string[];
         }>;
     }>;
+    apiManifest?: any;
+    apiBaseUrl?: string;
+    apiPlayground?: boolean;
+    apiAuth?: {
+        type: "bearer" | "apiKey";
+        header?: string;
+    };
+    ApiReferenceComponent?: React.ComponentType<{
+        manifest: any;
+        baseUrl?: string;
+        showPlayground?: boolean;
+        playgroundAuth?: {
+            type: "bearer" | "apiKey";
+            header?: string;
+        };
+    }>;
     onNavigate: (id: string) => void;
     allPages: Array<{
         id: string;
@@ -101,8 +128,17 @@ interface ShellProps {
         content: string;
     }>;
     basePath?: string;
+    isDraft?: boolean;
+    dir?: "ltr" | "rtl";
+    overrides?: {
+        Header?: React.ComponentType<any>;
+        Footer?: React.ComponentType<any>;
+        Sidebar?: React.ComponentType<any>;
+        Toc?: React.ComponentType<any>;
+        PageFooter?: React.ComponentType<any>;
+    };
 }
-declare function Shell({ config, navigation, currentPageId, pageHtml, pageComponent, mdxComponents, pageTitle, pageDescription, headings, tocEnabled, editUrl, lastUpdated, changelogEntries, onNavigate, allPages, versioning, currentVersion, i18n, currentLocale, docContext, basePath, }: ShellProps): react_jsx_runtime.JSX.Element;
+declare function Shell({ config, navigation, currentPageId, pageHtml, pageComponent, mdxComponents, pageTitle, pageDescription, headings, tocEnabled, editUrl, lastUpdated, changelogEntries, apiManifest, apiBaseUrl, apiPlayground, apiAuth, ApiReferenceComponent, onNavigate, allPages, versioning, currentVersion, i18n, currentLocale, docContext, basePath, isDraft, dir: dirProp, overrides, }: ShellProps): react_jsx_runtime.JSX.Element;
 
 interface AiChatProps {
     provider: "openai" | "anthropic" | "custom";

package/dist/index.js

@@ -3,7 +3,7 @@ import {
   Shell,
   THEME_PRESETS,
   entry_default
-} from "./chunk-YXKONM3A.js";
+} from "./chunk-MSXVVBDW.js";
 export {
   AiChat,
   entry_default as App,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomehq/theme",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Tome default theme and React app shell",
   "type": "module",
   "main": "./src/index.tsx",
@@ -9,8 +9,8 @@
     "./entry": "./src/entry.tsx"
   },
   "dependencies": {
-    "@tomehq/components": "0.3.1",
-    "@tomehq/core": "0.3.1"
+    "@tomehq/components": "0.3.3",
+    "@tomehq/core": "0.3.3"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -41,11 +41,11 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/vxcozy/tome.git",
+    "url": "https://github.com/tomehq/tome.git",
     "directory": "packages/theme"
   },
   "scripts": {
-    "build": "tsup src/index.tsx src/entry.tsx --format esm --dts --external react --external react-dom --external 'virtual:tome/config' --external 'virtual:tome/routes' --external 'virtual:tome/page-loader' --external 'virtual:tome/doc-context' --external '@tomehq/components'",
+    "build": "tsup src/index.tsx src/entry.tsx --format esm --dts --external react --external react-dom --external 'virtual:tome/config' --external 'virtual:tome/routes' --external 'virtual:tome/page-loader' --external 'virtual:tome/doc-context' --external 'virtual:tome/overrides' --external '@tomehq/components'",
     "dev": "tsup src/index.tsx src/entry.tsx --format esm --dts --external react --external react-dom --external 'virtual:tome/config' --external 'virtual:tome/routes' --external 'virtual:tome/page-loader' --external 'virtual:tome/doc-context' --external '@tomehq/components' --watch",
     "clean": "rm -rf dist"
   }

package/src/Shell.test.tsx

@@ -860,6 +860,115 @@ describe("Shell feedback widget", () => {
   });
 });
 
+// ── Breadcrumbs ──────────────────────────────────────────
+
+describe("Shell breadcrumbs", () => {
+  const multiSectionNav = [
+    {
+      section: "Getting Started",
+      pages: [
+        { id: "intro", title: "Introduction", urlPath: "/intro" },
+        { id: "quickstart", title: "Quick Start", urlPath: "/quickstart" },
+      ],
+    },
+    {
+      section: "Guides",
+      pages: [
+        { id: "search", title: "Search", urlPath: "/search" },
+        { id: "deploy", title: "Deploy", urlPath: "/deploy" },
+      ],
+    },
+  ];
+
+  const multiSectionAllPages = [
+    { id: "intro", title: "Introduction" },
+    { id: "quickstart", title: "Quick Start" },
+    { id: "search", title: "Search" },
+    { id: "deploy", title: "Deploy" },
+  ];
+
+  it("renders breadcrumbs for a non-index page", () => {
+    renderShell({
+      navigation: multiSectionNav,
+      allPages: multiSectionAllPages,
+      currentPageId: "quickstart",
+      pageTitle: "Quick Start",
+    });
+    const breadcrumbs = screen.getByTestId("breadcrumbs");
+    expect(breadcrumbs).toBeInTheDocument();
+    expect(within(breadcrumbs).getByText("Getting Started")).toBeInTheDocument();
+    expect(within(breadcrumbs).getByText("Quick Start")).toBeInTheDocument();
+  });
+
+  it("does not render breadcrumbs on the index page", () => {
+    renderShell({
+      currentPageId: "index",
+      pageTitle: "Home",
+    });
+    expect(screen.queryByTestId("breadcrumbs")).not.toBeInTheDocument();
+  });
+
+  it("renders section name as a link", () => {
+    renderShell({
+      navigation: multiSectionNav,
+      allPages: multiSectionAllPages,
+      currentPageId: "deploy",
+      pageTitle: "Deploy",
+    });
+    const breadcrumbs = screen.getByTestId("breadcrumbs");
+    const sectionLink = within(breadcrumbs).getByText("Guides");
+    expect(sectionLink.tagName).toBe("A");
+  });
+
+  it("renders current page as plain text (not a link)", () => {
+    renderShell({
+      navigation: multiSectionNav,
+      allPages: multiSectionAllPages,
+      currentPageId: "deploy",
+      pageTitle: "Deploy",
+    });
+    const breadcrumbs = screen.getByTestId("breadcrumbs");
+    const currentPage = within(breadcrumbs).getByText("Deploy");
+    expect(currentPage.tagName).toBe("SPAN");
+  });
+
+  it("clicking section link calls onNavigate with first page id", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      navigation: multiSectionNav,
+      allPages: multiSectionAllPages,
+      currentPageId: "deploy",
+      pageTitle: "Deploy",
+      onNavigate,
+    });
+    const breadcrumbs = screen.getByTestId("breadcrumbs");
+    fireEvent.click(within(breadcrumbs).getByText("Guides"));
+    expect(onNavigate).toHaveBeenCalledWith("search");
+  });
+
+  it("renders separator between breadcrumb items", () => {
+    renderShell({
+      navigation: multiSectionNav,
+      allPages: multiSectionAllPages,
+      currentPageId: "quickstart",
+      pageTitle: "Quick Start",
+    });
+    const breadcrumbs = screen.getByTestId("breadcrumbs");
+    expect(breadcrumbs.textContent).toContain("\u203A");
+  });
+
+  it("has proper aria-label for accessibility", () => {
+    renderShell({
+      navigation: multiSectionNav,
+      allPages: multiSectionAllPages,
+      currentPageId: "quickstart",
+      pageTitle: "Quick Start",
+    });
+    const nav = screen.getByRole("navigation", { name: "Breadcrumbs" });
+    expect(nav).toBeInTheDocument();
+  });
+});
+
 // ── Image zoom ───────────────────────────────────────────
 
 describe("Shell image zoom", () => {
@@ -869,3 +978,299 @@ describe("Shell image zoom", () => {
     expect(zoomOverlay).toBeNull();
   });
 });
+
+// ── RTL support ──────────────────────────────────────────
+
+describe("Shell RTL support", () => {
+  it("sets dir='rtl' on root element when dir prop is 'rtl'", () => {
+    const { container } = renderShell({ dir: "rtl" });
+    const root = container.querySelector("[dir='rtl']");
+    expect(root).not.toBeNull();
+  });
+
+  it("sets dir='ltr' on root element by default", () => {
+    const { container } = renderShell();
+    const root = container.querySelector("[dir='ltr']");
+    expect(root).not.toBeNull();
+  });
+
+  it("sets dir='ltr' when dir prop is explicitly 'ltr'", () => {
+    const { container } = renderShell({ dir: "ltr" });
+    const root = container.querySelector("[dir='ltr']");
+    expect(root).not.toBeNull();
+    expect(container.querySelector("[dir='rtl']")).toBeNull();
+  });
+
+  it("resolves dir from i18n.localeDirs when dir prop is not set", () => {
+    const { container } = renderShell({
+      i18n: {
+        defaultLocale: "en",
+        locales: ["en", "ar"],
+        localeDirs: { ar: "rtl" },
+      },
+      currentLocale: "ar",
+    });
+    const root = container.querySelector("[dir='rtl']");
+    expect(root).not.toBeNull();
+  });
+
+  it("defaults to ltr when locale has no entry in localeDirs", () => {
+    const { container } = renderShell({
+      i18n: {
+        defaultLocale: "en",
+        locales: ["en", "ar"],
+        localeDirs: { ar: "rtl" },
+      },
+      currentLocale: "en",
+    });
+    const root = container.querySelector("[dir='ltr']");
+    expect(root).not.toBeNull();
+  });
+
+  it("reverses main layout flex direction for RTL", () => {
+    const { container } = renderShell({ dir: "rtl" });
+    const flexRow = container.querySelector('[style*="flex-direction: row-reverse"]');
+    expect(flexRow).not.toBeNull();
+  });
+
+  it("uses normal row direction for LTR", () => {
+    const { container } = renderShell({ dir: "ltr" });
+    const flexRowReverse = container.querySelector('[style*="flex-direction: row-reverse"]');
+    expect(flexRowReverse).toBeNull();
+  });
+
+  it("mirrors sidebar border to borderLeft for RTL", () => {
+    const { container } = renderShell({ dir: "rtl" });
+    const aside = container.querySelector("aside");
+    expect(aside).not.toBeNull();
+    expect(aside!.style.borderLeft).toContain("1px solid");
+  });
+
+  it("renders without errors in RTL mode", () => {
+    expect(() =>
+      renderShell({ dir: "rtl" })
+    ).not.toThrow();
+  });
+});
+
+// ── API Reference (TOM-19) ──────────────────────────────
+
+describe("Shell API reference rendering", () => {
+  const mockManifest = {
+    title: "Test API",
+    version: "1.0.0",
+    servers: [{ url: "https://api.example.com" }],
+    tags: [{ name: "Users", description: "User management" }],
+    endpoints: [
+      {
+        method: "GET",
+        path: "/users",
+        summary: "List all users",
+        tags: ["Users"],
+        parameters: [],
+        responses: [{ status: "200", description: "OK" }],
+      },
+    ],
+  };
+
+  function MockApiRef({ manifest, baseUrl, showPlayground, playgroundAuth }: { manifest: any; baseUrl?: string; showPlayground?: boolean; playgroundAuth?: { type: string; header?: string } }) {
+    return (
+      <div data-testid="api-reference">
+        <span data-testid="api-title">{manifest.title}</span>
+        {baseUrl && <span data-testid="api-base-url">{baseUrl}</span>}
+        {showPlayground && <span data-testid="api-playground">playground-enabled</span>}
+        {playgroundAuth && <span data-testid="api-auth">{playgroundAuth.type}</span>}
+      </div>
+    );
+  }
+
+  it("renders ApiReferenceComponent when both apiManifest and component are provided", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-reference")).toBeInTheDocument();
+    expect(screen.getByTestId("api-title")).toHaveTextContent("Test API");
+  });
+
+  it("passes baseUrl to ApiReferenceComponent", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      apiBaseUrl: "https://api.example.com",
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-base-url")).toHaveTextContent("https://api.example.com");
+  });
+
+  it("does not render API reference when only apiManifest is provided (no component)", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      pageHtml: "<p>Fallback content</p>",
+    });
+    expect(screen.queryByTestId("api-reference")).not.toBeInTheDocument();
+  });
+
+  it("does not render API reference when only component is provided (no manifest)", () => {
+    renderShell({
+      ApiReferenceComponent: MockApiRef,
+      pageHtml: "<p>Fallback content</p>",
+    });
+    expect(screen.queryByTestId("api-reference")).not.toBeInTheDocument();
+  });
+
+  it("falls back to pageHtml when no apiManifest", () => {
+    const { container } = renderShell({
+      pageHtml: "<p>Regular page content</p>",
+    });
+    expect(container.querySelector(".tome-content")).toBeInTheDocument();
+    expect(screen.queryByTestId("api-reference")).not.toBeInTheDocument();
+  });
+
+  it("API reference takes precedence over changelog entries", () => {
+    const changelogEntries = [
+      { version: "1.0.0", sections: [{ type: "Added", items: ["Feature"] }] },
+    ];
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      changelogEntries,
+      pageHtml: undefined,
+    });
+    // API reference should render, not changelog
+    expect(screen.getByTestId("api-reference")).toBeInTheDocument();
+    expect(screen.queryByTestId("changelog-timeline")).not.toBeInTheDocument();
+  });
+
+  it("API reference takes precedence over pageComponent", () => {
+    const PageComp = () => <div data-testid="page-comp">MDX content</div>;
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      pageComponent: PageComp,
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-reference")).toBeInTheDocument();
+    expect(screen.queryByTestId("page-comp")).not.toBeInTheDocument();
+  });
+
+  it("passes showPlayground prop to ApiReferenceComponent", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      apiPlayground: true,
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-playground")).toHaveTextContent("playground-enabled");
+  });
+
+  it("passes playgroundAuth prop to ApiReferenceComponent", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      apiPlayground: true,
+      apiAuth: { type: "bearer" },
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-auth")).toHaveTextContent("bearer");
+  });
+
+  it("does not pass playground props when not provided", () => {
+    renderShell({
+      apiManifest: mockManifest,
+      ApiReferenceComponent: MockApiRef,
+      pageHtml: undefined,
+    });
+    expect(screen.getByTestId("api-reference")).toBeInTheDocument();
+    expect(screen.queryByTestId("api-playground")).not.toBeInTheDocument();
+    expect(screen.queryByTestId("api-auth")).not.toBeInTheDocument();
+  });
+});
+
+// ── Content link interception ───────────────────────────────
+
+describe("Content link interception", () => {
+  it("intercepts internal bare page ID links and calls onNavigate", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="quickstart">Go to quickstart</a></p>',
+    });
+    const link = screen.getByText("Go to quickstart");
+    fireEvent.click(link);
+    expect(onNavigate).toHaveBeenCalledWith("quickstart");
+  });
+
+  it("intercepts ./relative links and strips the prefix", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="./installation">Install</a></p>',
+    });
+    fireEvent.click(screen.getByText("Install"));
+    expect(onNavigate).toHaveBeenCalledWith("installation");
+  });
+
+  it("does not intercept external http links", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="https://example.com">External</a></p>',
+    });
+    fireEvent.click(screen.getByText("External"));
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it("does not intercept mailto links", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="mailto:test@example.com">Email</a></p>',
+    });
+    fireEvent.click(screen.getByText("Email"));
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it("does not intercept pure anchor links", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="#section-1">Jump to section</a></p>',
+    });
+    fireEvent.click(screen.getByText("Jump to section"));
+    expect(onNavigate).not.toHaveBeenCalled();
+  });
+
+  it("strips basePath prefix from links", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      basePath: "/docs/",
+      pageHtml: '<p><a href="/docs/quickstart">Go</a></p>',
+    });
+    fireEvent.click(screen.getByText("Go"));
+    expect(onNavigate).toHaveBeenCalledWith("quickstart");
+  });
+
+  it("resolves basePath-only link to index", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      basePath: "/docs/",
+      pageHtml: '<p><a href="/docs/">Home</a></p>',
+    });
+    fireEvent.click(screen.getByText("Home"));
+    expect(onNavigate).toHaveBeenCalledWith("index");
+  });
+
+  it("resolves empty path to index", () => {
+    const onNavigate = vi.fn();
+    renderShell({
+      onNavigate,
+      pageHtml: '<p><a href="./">Home</a></p>',
+    });
+    fireEvent.click(screen.getByText("Home"));
+    expect(onNavigate).toHaveBeenCalledWith("index");
+  });
+});