@open-agent-toolkit/docs-theme 0.3.14 → 0.3.15

package/README.md

@@ -49,6 +49,22 @@ export function Page({ toc, chart }) {
 - `Mermaid`
 - `Tab`
 - `Tabs`
+- `ZoomImage`: Markdown image renderer. Map it as `img` in your MDX
+  components.
+  - SVG images open in a full-screen view that renders them at least 900px
+    wide, so diagram text stays legible on a phone; the reader pans to see the
+    rest. Other images open in Fumadocs `ImageZoom`.
+  - Root-relative paths such as `/diagrams/x.svg` get the site base path
+    (`NEXT_PUBLIC_BASE_PATH`, which `@open-agent-toolkit/docs-config` sets
+    from `basePath`).
+  - Files named `<name>-light.<ext>` / `<name>-dark.<ext>` show only in the
+    matching theme. Add
+    `@source '../node_modules/@open-agent-toolkit/docs-theme/dist/**/*.js';`
+    to your Tailwind CSS so those theme classes are generated.
+
+`Mermaid` diagrams take their colors from the site's Fumadocs color tokens
+(`--color-fd-*`) in light and dark mode, and open in the same full-screen view
+when clicked.
 
 ## Docs
 

package/dist/image-src.d.ts

@@ -0,0 +1,8 @@
+export type ImageThemeVariant = 'light' | 'dark';
+/** Which site theme an image file is for, from its `-light`/`-dark` name. */
+export declare function themeVariantOf(src: string | undefined): ImageThemeVariant | null;
+/** Prefix a root-relative public asset path with the site's base path. */
+export declare function withBasePath(src: string, basePath: string): string;
+/** Whether an image file is an SVG (diagrams are authored as SVG). */
+export declare function isSvgSource(src: string | undefined): boolean;
+//# sourceMappingURL=image-src.d.ts.map

package/dist/image-src.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-src.d.ts","sourceRoot":"","sources":["../src/image-src.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,CAAC;AAQjD,6EAA6E;AAC7E,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,iBAAiB,GAAG,IAAI,CAK1B;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAIlE;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE5D"}

package/dist/image-src.js

@@ -0,0 +1,25 @@
+// A file named `<name>-light.<ext>` or `<name>-dark.<ext>` is shown only in
+// that site theme. The optional middle segment covers the content hash the
+// bundler adds to imported assets (`<name>-dark.4f3a2b1c.svg`).
+const THEME_VARIANT_PATTERN = /-(light|dark)(?:\.[\w-]+)?\.(?:svg|png|jpe?g|gif|webp|avif)(?:[?#].*)?$/i;
+/** Which site theme an image file is for, from its `-light`/`-dark` name. */
+export function themeVariantOf(src) {
+    if (!src)
+        return null;
+    const match = THEME_VARIANT_PATTERN.exec(src);
+    if (!match)
+        return null;
+    return match[1].toLowerCase();
+}
+/** Prefix a root-relative public asset path with the site's base path. */
+export function withBasePath(src, basePath) {
+    if (!basePath || !src.startsWith('/') || src.startsWith('//'))
+        return src;
+    if (src === basePath || src.startsWith(`${basePath}/`))
+        return src;
+    return `${basePath}${src}`;
+}
+/** Whether an image file is an SVG (diagrams are authored as SVG). */
+export function isSvgSource(src) {
+    return !!src && /\.svg(?:[?#].*)?$/i.test(src);
+}

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export { DocsLayout } from './docs-layout.js';
 export { DocsPage } from './docs-page.js';
 export { Mermaid } from './mermaid.js';
 export { Tab, Tabs } from './tabs.js';
+export { ZoomImage } from './zoom-image.js';
 export type { BrandingConfig } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -2,3 +2,4 @@ export { DocsLayout } from './docs-layout.js';
 export { DocsPage } from './docs-page.js';
 export { Mermaid } from './mermaid.js';
 export { Tab, Tabs } from './tabs.js';
+export { ZoomImage } from './zoom-image.js';

package/dist/mermaid-theme.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Mermaid theme variables for the current page, or `undefined` when the site
+ * does not define the Fumadocs color tokens (Mermaid then uses its stock
+ * theme).
+ */
+export declare function siteMermaidThemeVariables(dark: boolean): Record<string, string | boolean> | undefined;
+//# sourceMappingURL=mermaid-theme.d.ts.map

package/dist/mermaid-theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid-theme.d.ts","sourceRoot":"","sources":["../src/mermaid-theme.ts"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,OAAO,GACZ,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,SAAS,CAqD9C"}

package/dist/mermaid-theme.js

@@ -0,0 +1,88 @@
+// Builds Mermaid `base` theme variables from the site's Fumadocs color tokens
+// so diagrams follow the docs site's palette in light and dark mode.
+const TOKENS = {
+    background: '--color-fd-background',
+    card: '--color-fd-card',
+    foreground: '--color-fd-foreground',
+    mutedForeground: '--color-fd-muted-foreground',
+    muted: '--color-fd-muted',
+    secondary: '--color-fd-secondary',
+    border: '--color-fd-border',
+    primary: '--color-fd-primary',
+};
+// Mermaid derives shades from its theme variables and only understands sRGB
+// hex/rgb input, while sites may define tokens in any CSS color space. Paint
+// the color into a 1x1 canvas and read the sRGB pixel back.
+function toHex(color, ctx) {
+    if (!color)
+        return undefined;
+    ctx.clearRect(0, 0, 1, 1);
+    ctx.fillStyle = '#000';
+    ctx.fillStyle = color;
+    ctx.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+    if (a === 0)
+        return undefined;
+    return `#${[r, g, b].map((n) => n.toString(16).padStart(2, '0')).join('')}`;
+}
+/**
+ * Mermaid theme variables for the current page, or `undefined` when the site
+ * does not define the Fumadocs color tokens (Mermaid then uses its stock
+ * theme).
+ */
+export function siteMermaidThemeVariables(dark) {
+    if (typeof document === 'undefined')
+        return undefined;
+    const ctx = document
+        .createElement('canvas')
+        .getContext('2d', { willReadFrequently: true });
+    if (!ctx)
+        return undefined;
+    const style = getComputedStyle(document.documentElement);
+    const c = {};
+    for (const [name, prop] of Object.entries(TOKENS)) {
+        const hex = toHex(style.getPropertyValue(prop).trim(), ctx);
+        if (!hex)
+            return undefined;
+        c[name] = hex;
+    }
+    return {
+        darkMode: dark,
+        fontFamily: getComputedStyle(document.body).fontFamily,
+        background: c.card,
+        textColor: c.foreground,
+        titleColor: c.foreground,
+        lineColor: c.mutedForeground,
+        primaryColor: c.secondary,
+        primaryTextColor: c.foreground,
+        primaryBorderColor: c.primary,
+        secondaryColor: c.muted,
+        secondaryTextColor: c.foreground,
+        secondaryBorderColor: c.border,
+        tertiaryColor: c.card,
+        tertiaryTextColor: c.foreground,
+        tertiaryBorderColor: c.border,
+        mainBkg: c.secondary,
+        nodeBorder: c.primary,
+        nodeTextColor: c.foreground,
+        clusterBkg: c.muted,
+        clusterBorder: c.border,
+        edgeLabelBackground: c.card,
+        noteBkgColor: c.muted,
+        noteTextColor: c.foreground,
+        noteBorderColor: c.border,
+        actorBkg: c.secondary,
+        actorBorder: c.primary,
+        actorTextColor: c.foreground,
+        actorLineColor: c.mutedForeground,
+        signalColor: c.foreground,
+        signalTextColor: c.foreground,
+        labelBoxBkgColor: c.secondary,
+        labelBoxBorderColor: c.border,
+        labelTextColor: c.foreground,
+        loopTextColor: c.foreground,
+        activationBkgColor: c.muted,
+        activationBorderColor: c.primary,
+        sequenceNumberColor: c.card,
+    };
+}

package/dist/mermaid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../src/mermaid.tsx"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAID,wBAAgB,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,YAAY,2CA+C9C"}
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../src/mermaid.tsx"],"names":[],"mappings":"AAQA,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,OAAO,CAAC,EAAE,KAAK,EAAE,EAAE,YAAY,2CA4D9C"}

package/dist/mermaid.js

@@ -2,7 +2,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useTheme } from 'next-themes';
 import { useEffect, useRef, useState } from 'react';
-let mermaidInitialized = false;
+import { siteMermaidThemeVariables } from './mermaid-theme.js';
+import { ZoomFrame } from './zoom-frame.js';
 export function Mermaid({ chart }) {
     const containerRef = useRef(null);
     const [svg, setSvg] = useState('');
@@ -11,19 +12,14 @@ export function Mermaid({ chart }) {
         let cancelled = false;
         async function render() {
             const mermaid = (await import('mermaid')).default;
-            if (!mermaidInitialized) {
-                mermaid.initialize({
-                    startOnLoad: false,
-                    theme: resolvedTheme === 'dark' ? 'dark' : 'default',
-                });
-                mermaidInitialized = true;
-            }
-            else {
-                mermaid.initialize({
-                    startOnLoad: false,
-                    theme: resolvedTheme === 'dark' ? 'dark' : 'default',
-                });
-            }
+            const dark = resolvedTheme === 'dark';
+            const themeVariables = siteMermaidThemeVariables(dark);
+            mermaid.initialize({
+                startOnLoad: false,
+                ...(themeVariables
+                    ? { theme: 'base', themeVariables }
+                    : { theme: dark ? 'dark' : 'default' }),
+            });
             const id = `mermaid-${Math.random().toString(36).slice(2, 9)}`;
             const { svg: rendered } = await mermaid.render(id, chart);
             if (!cancelled) {
@@ -35,7 +31,11 @@ export function Mermaid({ chart }) {
             cancelled = true;
         };
     }, [chart, resolvedTheme]);
-    return (_jsx("div", { ref: containerRef, className: 'mermaid', 
-        // oxlint-disable-next-line react/no-danger -- mermaid renders SVG from trusted chart definitions
-        dangerouslySetInnerHTML: { __html: svg } }));
+    return (_jsx(ZoomFrame, { label: 'Diagram', disabled: !svg, zoomed: _jsx("div", { className: 'mermaid', 
+            // oxlint-disable-next-line react/no-danger -- same trusted SVG as above
+            dangerouslySetInnerHTML: {
+                __html: svg.replace(/<svg\b([^>]*?)\sstyle="[^"]*"/, '<svg$1 style="width:100%;height:auto;max-width:none"'),
+            } }), children: _jsx("div", { ref: containerRef, className: 'mermaid', 
+            // oxlint-disable-next-line react/no-danger -- mermaid renders SVG from trusted chart definitions
+            dangerouslySetInnerHTML: { __html: svg } }) }));
 }

package/dist/zoom-frame.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+export interface ZoomFrameProps {
+    /** Accessible name for the enlarge control, e.g. the diagram's alt text. */
+    label: string;
+    /** The inline, column-width rendering. */
+    children: ReactNode;
+    /** What to show in the full-screen view. */
+    zoomed: ReactNode;
+    disabled?: boolean;
+}
+/**
+ * Click-to-enlarge wrapper for diagrams. The inline view fits the column; the
+ * full-screen view is a native modal dialog that scrolls in both directions
+ * and closes on Escape, the close button, or a click.
+ */
+export declare function ZoomFrame({ label, children, zoomed, disabled, }: ZoomFrameProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=zoom-frame.d.ts.map

package/dist/zoom-frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zoom-frame.d.ts","sourceRoot":"","sources":["../src/zoom-frame.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAA+B,MAAM,OAAO,CAAC;AAGpE,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,QAAQ,EAAE,SAAS,CAAC;IACpB,4CAA4C;IAC5C,MAAM,EAAE,SAAS,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAQD;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,QAAQ,EACR,MAAM,EACN,QAAQ,GACT,EAAE,cAAc,2CAiHhB"}

package/dist/zoom-frame.js

@@ -0,0 +1,83 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+// The full-screen view renders the diagram at least this wide, so labels stay
+// legible on a phone; the reader pans to see the rest. Wider screens fit the
+// diagram to the window, up to the maximum.
+const ZOOMED_MIN_WIDTH = 900;
+const ZOOMED_MAX_WIDTH = 1400;
+/**
+ * Click-to-enlarge wrapper for diagrams. The inline view fits the column; the
+ * full-screen view is a native modal dialog that scrolls in both directions
+ * and closes on Escape, the close button, or a click.
+ */
+export function ZoomFrame({ label, children, zoomed, disabled, }) {
+    const dialogRef = useRef(null);
+    // The dialog lives in a portal on <body>: rendered in place it would sit
+    // inside a Markdown <p>, which the HTML parser splits, breaking hydration.
+    const [mounted, setMounted] = useState(false);
+    useEffect(() => setMounted(true), []);
+    const open = () => {
+        const dialog = dialogRef.current;
+        if (!dialog || disabled)
+            return;
+        dialog.showModal();
+        dialog.scrollLeft = (dialog.scrollWidth - dialog.clientWidth) / 2;
+        dialog.scrollTop = 0;
+    };
+    const close = () => dialogRef.current?.close();
+    return (_jsxs(_Fragment, { children: [_jsxs("button", { type: 'button', onClick: open, disabled: disabled, "aria-label": `Enlarge: ${label}`, title: 'Enlarge', style: {
+                    position: 'relative',
+                    display: 'block',
+                    width: '100%',
+                    padding: 0,
+                    border: 0,
+                    background: 'none',
+                    color: 'inherit',
+                    font: 'inherit',
+                    textAlign: 'inherit',
+                    cursor: disabled ? 'default' : 'zoom-in',
+                }, children: [children, !disabled && (_jsx("span", { "aria-hidden": 'true', style: {
+                            position: 'absolute',
+                            top: '0.5rem',
+                            right: '0.5rem',
+                            padding: '0.15rem 0.5rem',
+                            borderRadius: '9999px',
+                            border: '1px solid var(--color-fd-border, #ccc)',
+                            background: 'var(--color-fd-card, #fff)',
+                            color: 'var(--color-fd-muted-foreground, #555)',
+                            fontSize: '0.75rem',
+                            lineHeight: 1.4,
+                        }, children: "\u2922 Enlarge" }))] }), mounted &&
+                createPortal(_jsxs("dialog", { ref: dialogRef, "aria-label": label, onClick: close, style: {
+                        width: '100vw',
+                        maxWidth: '100vw',
+                        height: '100dvh',
+                        maxHeight: '100dvh',
+                        margin: 0,
+                        padding: '3rem 1rem 1rem',
+                        border: 0,
+                        background: 'var(--color-fd-background, #fff)',
+                        color: 'inherit',
+                        overflow: 'auto',
+                        cursor: 'zoom-out',
+                    }, children: [_jsx("button", { type: 'button', onClick: close, "aria-label": 'Close enlarged view', style: {
+                                position: 'fixed',
+                                top: '0.75rem',
+                                right: '0.75rem',
+                                width: '2.25rem',
+                                height: '2.25rem',
+                                borderRadius: '9999px',
+                                border: '1px solid var(--color-fd-border, #ccc)',
+                                background: 'var(--color-fd-card, #fff)',
+                                color: 'inherit',
+                                fontSize: '1.25rem',
+                                lineHeight: 1,
+                                cursor: 'pointer',
+                            }, children: "\u00D7" }), _jsx("div", { style: {
+                                width: `max(100%, ${ZOOMED_MIN_WIDTH}px)`,
+                                maxWidth: `${ZOOMED_MAX_WIDTH}px`,
+                                margin: '0 auto',
+                            }, children: zoomed })] }), document.body)] }));
+}

package/dist/zoom-image.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentProps } from 'react';
+type ZoomImageProps = ComponentProps<'img'>;
+/**
+ * Markdown image renderer; map it as `img` in the MDX components. SVG
+ * diagrams open in a full-screen view that pans on small screens, other
+ * images use Fumadocs ImageZoom, and a `-light` / `-dark` file pair shows only
+ * the file that matches the site theme.
+ */
+export declare function ZoomImage(props: ZoomImageProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=zoom-image.d.ts.map

package/dist/zoom-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zoom-image.d.ts","sourceRoot":"","sources":["../src/zoom-image.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,OAAO,CAAC;AAcvD,KAAK,cAAc,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;AAoB5C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,2CA0C9C"}

package/dist/zoom-image.js

@@ -0,0 +1,49 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { ImageZoom } from 'fumadocs-ui/components/image-zoom';
+import { isSvgSource, themeVariantOf, withBasePath, } from './image-src.js';
+import { ZoomFrame } from './zoom-frame.js';
+// Set by `@open-agent-toolkit/docs-config` when the site has a basePath.
+const BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH ?? '';
+function srcToString(src) {
+    if (typeof src === 'string')
+        return src;
+    if (src && typeof src === 'object') {
+        if ('default' in src)
+            return src.default.src;
+        if ('src' in src)
+            return src.src;
+    }
+    return undefined;
+}
+const VARIANT_CLASS = {
+    light: 'block dark:hidden',
+    dark: 'hidden dark:block',
+};
+/**
+ * Markdown image renderer; map it as `img` in the MDX components. SVG
+ * diagrams open in a full-screen view that pans on small screens, other
+ * images use Fumadocs ImageZoom, and a `-light` / `-dark` file pair shows only
+ * the file that matches the site theme.
+ */
+export function ZoomImage(props) {
+    const raw = srcToString(props.src);
+    const variant = themeVariantOf(raw);
+    const src = typeof props.src === 'string'
+        ? withBasePath(props.src, BASE_PATH)
+        : props.src;
+    let node;
+    if (isSvgSource(raw)) {
+        // Diagrams use the full-screen pannable view; ImageZoom only scales an
+        // image to the viewport, which leaves diagram text unreadable on a phone.
+        const url = srcToString(src) ?? '';
+        const { src: _src, alt = '', className, ...rest } = props;
+        node = (_jsx(ZoomFrame, { label: alt || 'Diagram', zoomed: _jsx("img", { src: url, alt: alt, style: { display: 'block', width: '100%' } }), children: _jsx("img", { ...rest, src: url, alt: alt, className: className, style: { display: 'block', width: '100%', height: 'auto' } }) }));
+    }
+    else {
+        node = _jsx(ImageZoom, { ...{ ...props, src } });
+    }
+    if (!variant)
+        return node;
+    return (_jsx("span", { className: VARIANT_CLASS[variant], "data-theme-variant": variant, children: node }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/docs-theme",
-  "version": "0.3.14",
+  "version": "0.3.15",
   "private": false,
   "description": "Theme components for OAT documentation sites",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/docs-theme",
@@ -43,7 +43,8 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-7": "npm:typescript@^7.0.2"
+    "typescript-7": "npm:typescript@^7.0.2",
+    "vitest": "^4.0.18"
   },
   "peerDependencies": {
     "fumadocs-core": ">=16.0.0",
@@ -64,6 +65,8 @@
     "format:fix": "oxfmt .",
     "lint": "oxlint . && oxlint --type-aware -A all -D typescript/no-floating-promises -D typescript/no-misused-promises --ignore-pattern '**/*.test.ts' --ignore-pattern '**/*.spec.ts' .",
     "lint:fix": "oxlint --fix . && oxlint --type-aware -A all -D typescript/no-floating-promises -D typescript/no-misused-promises --ignore-pattern '**/*.test.ts' --ignore-pattern '**/*.spec.ts' .",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "type-check": "tsc --noEmit"
   }
 }