@raystack/chronicle 0.12.3 → 0.12.5

package/src/cli/utils/mdx-error-report.ts

@@ -0,0 +1,48 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import chalk from 'chalk';
+import { buildCodeFrame, parseMdxError } from '@/lib/mdx-error';
+
+/**
+ * Prints a formatted report for MDX build failures (file, line:column,
+ * message, code frame). Returns false when the error is not MDX-related
+ * so the caller can rethrow it.
+ */
+export async function printMdxBuildError(err: unknown, packageRoot: string): Promise<boolean> {
+  const info = parseMdxError(err);
+  if (!info) return false;
+
+  const contentMirror = path.resolve(packageRoot, '.content');
+  const displayPath = info.file?.startsWith(contentMirror)
+    ? path.relative(contentMirror, info.file)
+    : info.file && !path.relative(process.cwd(), info.file).startsWith('..')
+      ? path.relative(process.cwd(), info.file)
+      : info.file;
+
+  console.error();
+  console.error(chalk.bgRed.white(' MDX Error '), chalk.red(info.message));
+  if (displayPath) {
+    const position = info.line ? `:${info.line}${info.column ? `:${info.column}` : ''}` : '';
+    console.error(chalk.dim(`  ${displayPath}${position}`));
+  }
+
+  if (info.file && info.line) {
+    try {
+      const source = await fs.readFile(info.file, 'utf-8');
+      const frame = buildCodeFrame(source, info.line, info.column);
+      const gutter = String(frame.lines[frame.lines.length - 1]?.number ?? 0).length;
+      console.error();
+      for (const { number, text, target } of frame.lines) {
+        const ln = `${target ? '>' : ' '} ${String(number).padStart(gutter)} | `;
+        console.error(target ? chalk.red(ln) + text : chalk.dim(ln + text));
+        if (target && frame.caretColumn) {
+          console.error(chalk.red(`  ${' '.repeat(gutter)} | ${' '.repeat(frame.caretColumn - 1)}^`));
+        }
+      }
+    } catch {
+      // source not readable — message-only report
+    }
+  }
+  console.error();
+  return true;
+}

package/src/components/api/playground-dialog.tsx

@@ -8,9 +8,66 @@ import { CounterClockwiseClockIcon, CodeIcon } from '@radix-ui/react-icons'
 import { MethodBadge } from '@/components/api/method-badge'
 import { flattenSchema, generateExampleJson, toKind, type SchemaField } from '@/lib/schema'
 import { generateCurl } from '@/lib/snippet-generators'
+import { isStaticMode } from '@/lib/static-mode'
 import { JsonEditor } from '@/components/api/json-editor'
 import styles from './playground-dialog.module.css'
 
+type ProxyResponse = {
+  status: number
+  statusText: string
+  body: unknown
+  headers?: Record<string, string>
+}
+
+async function sendViaProxy(
+  specName: string,
+  method: string,
+  path: string,
+  headers: Record<string, string>,
+  body: unknown,
+): Promise<ProxyResponse> {
+  const res = await fetch('/api/apis-proxy', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ specName, method, path, headers, body }),
+  })
+  const data = await res.json()
+  if (data.status !== undefined) return data
+  return { status: res.status, statusText: res.statusText, body: data.error ?? data }
+}
+
+async function sendDirect(
+  serverUrl: string,
+  method: string,
+  path: string,
+  headers: Record<string, string>,
+  body: unknown,
+): Promise<ProxyResponse> {
+  const url = serverUrl + path
+  try {
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    })
+    const contentType = res.headers.get('content-type') ?? ''
+    const responseBody = contentType.includes('application/json')
+      ? await res.json()
+      : await res.text()
+    const responseHeaders: Record<string, string> = {}
+    res.headers.forEach((v, k) => { responseHeaders[k] = v })
+    return { status: res.status, statusText: res.statusText, body: responseBody, headers: responseHeaders }
+  } catch (err) {
+    if (err instanceof TypeError) {
+      throw new Error(
+        `CORS Error: The API server at ${serverUrl} does not allow requests from this origin.\n` +
+        `Ask the API server administrator to add this site's origin to their CORS allowed origins.`
+      )
+    }
+    throw err
+  }
+}
+
 type AuthScheme = {
   name: string
   type: 'apiKey' | 'bearer' | 'basic' | 'none'
@@ -193,24 +250,18 @@ export function PlaygroundDialog({
     }
 
     try {
-      const res = await fetch('/api/apis-proxy', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ specName, method, path: fullPath, headers: reqHeaders, body: reqBody }),
-      })
-      const data = await res.json()
+      const data = isStaticMode()
+        ? await sendDirect(serverUrl, method, fullPath, reqHeaders, reqBody)
+        : await sendViaProxy(specName, method, fullPath, reqHeaders, reqBody)
       const elapsed = Math.round(performance.now() - startTime)
-      if (data.status !== undefined) {
-        setResponseData({ ...data, time: elapsed })
-      } else {
-        setResponseData({ status: res.status, statusText: res.statusText, body: data.error ?? data, time: elapsed })
-      }
-    } catch {
-      setResponseData({ status: 0, statusText: 'Error', body: 'Failed to send request', time: 0 })
+      setResponseData({ ...data, time: elapsed })
+    } catch (err) {
+      const message = err instanceof Error ? err.message : 'Failed to send request'
+      setResponseData({ status: 0, statusText: 'Error', body: message, time: 0 })
     } finally {
       setLoading(false)
     }
-  }, [specName, method, path, pathValues, queryValues, getAuthHeaders, headerValues, bodyValues, body])
+  }, [specName, method, path, serverUrl, pathValues, queryValues, getAuthHeaders, headerValues, bodyValues, body])
 
   const responseJson = responseData
     ? (typeof responseData.body === 'string' ? responseData.body : JSON.stringify(responseData.body, null, 2))

package/src/components/mdx/code.tsx

@@ -1,9 +1,10 @@
 'use client'
 
-import { type ComponentProps, isValidElement, Children } from 'react'
-import { Mermaid } from './mermaid'
+import { type ComponentProps, isValidElement, lazy, Suspense } from 'react'
 import styles from './code.module.css'
 
+const Mermaid = lazy(() => import('./mermaid').then(m => ({ default: m.Mermaid })))
+
 type PreProps = ComponentProps<'pre'> & {
   'data-language'?: string
   title?: string
@@ -21,7 +22,11 @@ export function MdxPre({ children, title, className, ...props }: PreProps) {
   if (isValidElement(children)) {
     const childProps = children.props as { className?: string; children?: string }
     if (childProps.className?.includes('language-mermaid') && typeof childProps.children === 'string') {
-      return <Mermaid chart={childProps.children} />
+      return (
+        <Suspense fallback={<pre className={styles.pre}><code>{childProps.children}</code></pre>}>
+          <Mermaid chart={childProps.children} />
+        </Suspense>
+      )
     }
   }
 

package/src/components/mdx/image.tsx

@@ -1,13 +1,27 @@
 import type { ComponentProps } from 'react';
 import { isLocalImage, isSvg, buildOptimizedUrl, DEFAULT_WIDTH } from '@/lib/image-utils';
+import { isStaticMode } from '@/lib/static-mode';
 
 type MDXImageProps = ComponentProps<'img'>;
 
+function webpUrl(src: string): string {
+  return src.replace(/\.[^.]+$/, '.webp');
+}
+
 export function MDXImage({ src, alt, ...props }: MDXImageProps) {
   if (!src) return null;
 
   const optimize = isLocalImage(src) && !isSvg(src);
-  const imgSrc = optimize ? buildOptimizedUrl(src, DEFAULT_WIDTH) : src;
 
+  if (optimize && isStaticMode()) {
+    return (
+      <picture>
+        <source srcSet={webpUrl(src)} type="image/webp" />
+        <img src={src} alt={alt ?? ''} loading='lazy' decoding='async' {...props} />
+      </picture>
+    );
+  }
+
+  const imgSrc = optimize ? buildOptimizedUrl(src, DEFAULT_WIDTH) : src;
   return <img src={imgSrc} alt={alt ?? ''} loading='lazy' decoding='async' {...props} />;
 }

package/src/components/mdx/index.tsx

@@ -4,11 +4,12 @@ import { Link } from './link'
 import { MdxTable, MdxThead, MdxTbody, MdxTr, MdxTh, MdxTd } from './table'
 import { MdxPre, MdxCode } from './code'
 import { MdxDetails, MdxSummary } from './details'
-import { Mermaid } from './mermaid'
 import { MdxParagraph } from './paragraph'
 import { CalloutContainer, CalloutTitle, CalloutDescription, MdxBlockquote } from '@/components/common/callout'
 import { Tabs } from '@raystack/apsara'
-import { type ComponentProps, useEffect, useState } from 'react'
+import { type ComponentProps, lazy, useEffect, useState, Suspense } from 'react'
+
+const LazyMermaid = lazy(() => import('./mermaid').then(m => ({ default: m.Mermaid })))
 
 function ClientOnly({ children }: { children: React.ReactNode }) {
   const [mounted, setMounted] = useState(false)
@@ -23,6 +24,8 @@ MdxTabs.List = Tabs.List
 MdxTabs.Tab = Tabs.Tab
 MdxTabs.Content = Tabs.Content
 
+// Capitalized keys must stay in sync with MDX_COMPONENT_NAMES in
+// src/lib/mdx-component-names.ts (used for compile-time validation).
 export const mdxComponents: MDXComponents = {
   p: MdxParagraph,
   img: MDXImage,
@@ -42,7 +45,11 @@ export const mdxComponents: MDXComponents = {
   CalloutTitle,
   CalloutDescription,
   Tabs: MdxTabs,
-  Mermaid,
+  Mermaid: (props: { chart: string }) => (
+    <Suspense fallback={<pre><code>{props.chart}</code></pre>}>
+      <LazyMermaid {...props} />
+    </Suspense>
+  ),
 }
 
 export { MDXImage } from './image'

package/src/components/ui/search.tsx

@@ -7,11 +7,24 @@ import {
 } from '@heroicons/react/24/outline';
 import { Command, IconButton, Text } from '@raystack/apsara';
 import { keepPreviousData, useQuery } from '@tanstack/react-query';
+import GithubSlugger from 'github-slugger';
 import { debounce } from 'lodash-es';
-import { useCallback, useEffect, useMemo, useState, type ChangeEvent } from 'react';
+import MiniSearch from 'minisearch';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ChangeEvent,
+  type ReactNode
+} from 'react';
 import { useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
 import { usePageContext } from '@/lib/page-context';
+import { isStaticMode } from '@/lib/static-mode';
+import { searchIndexUrl } from '@/lib/data-urls';
 import { SearchMatchType } from '@/types';
 import styles from './search.module.css';
 
@@ -29,6 +42,127 @@ interface SearchProps {
   classNames?: { trigger?: string };
 }
 
+interface SearchDocument {
+  id: string;
+  url: string;
+  title: string;
+  headings: string;
+  body: string;
+  type: string;
+  section: string;
+}
+
+let miniSearchInstance: MiniSearch<SearchDocument> | null = null;
+let miniSearchLoading: Promise<MiniSearch<SearchDocument>> | null = null;
+let searchDocuments: SearchDocument[] = [];
+
+function loadSearchIndex(): Promise<MiniSearch<SearchDocument>> {
+  if (miniSearchInstance) return Promise.resolve(miniSearchInstance);
+  if (miniSearchLoading) return miniSearchLoading;
+
+  miniSearchLoading = fetch(searchIndexUrl())
+    .then(res => {
+      if (!res.ok) throw new Error(`Failed to load search index: ${res.status}`);
+      return res.json() as Promise<SearchDocument[]>;
+    })
+    .then(docs => {
+      searchDocuments = docs;
+      const ms = new MiniSearch<SearchDocument>({
+        fields: ['title', 'headings', 'body'],
+        storeFields: ['url', 'title', 'headings', 'body', 'type', 'section'],
+        searchOptions: {
+          boost: { title: 10, headings: 5, body: 1 },
+          prefix: true,
+          fuzzy: 0.2,
+        },
+      });
+      ms.addAll(docs);
+      miniSearchInstance = ms;
+      return ms;
+    })
+    .catch(err => {
+      miniSearchLoading = null;
+      throw err;
+    });
+
+  return miniSearchLoading;
+}
+
+function findMatch(
+  query: string,
+  title: string,
+  headings: string,
+  body: string,
+): { match: SearchMatchType; snippet: string; slug?: string } {
+  if (title.toLowerCase().includes(query)) {
+    return { match: SearchMatchType.Title, snippet: title };
+  }
+
+  const slugger = new GithubSlugger();
+  const headingList = headings.split('\n').filter(Boolean);
+  for (const h of headingList) {
+    const slug = slugger.slug(h);
+    if (h.toLowerCase().includes(query)) {
+      return { match: SearchMatchType.Heading, snippet: h, slug };
+    }
+  }
+
+  const idx = body.toLowerCase().indexOf(query);
+  if (idx >= 0) {
+    const start = Math.max(0, idx - 40);
+    const end = Math.min(body.length, idx + query.length + 80);
+    const snippet = (start > 0 ? '...' : '') + body.slice(start, end).trim() + (end < body.length ? '...' : '');
+    return { match: SearchMatchType.Body, snippet };
+  }
+
+  return { match: SearchMatchType.Title, snippet: title };
+}
+
+async function searchStatic(query: string, tag?: string): Promise<SearchResult[]> {
+  const ms = await loadSearchIndex();
+
+  if (!query) {
+    let docs = searchDocuments.filter(d => d.type === 'page');
+    if (tag) docs = docs.filter(d => d.url === `/${tag}` || d.url.startsWith(`/${tag}/`));
+    return docs.slice(0, 8).map(d => ({
+      id: d.id,
+      url: d.url,
+      type: d.type,
+      content: d.title,
+      section: d.section || undefined,
+    }));
+  }
+
+  let results = ms.search(query);
+  if (tag) {
+    results = results.filter(r => {
+      const url = r.url as string;
+      return url === `/${tag}` || url.startsWith(`/${tag}/`);
+    });
+  }
+
+  const queryLower = query.toLowerCase();
+  return results.slice(0, 20).map(r => {
+    const { match, snippet, slug } = findMatch(
+      queryLower,
+      r.title as string,
+      r.headings as string,
+      r.body as string,
+    );
+    const id = match === SearchMatchType.Heading && slug ? `${r.id}#${slug}` : r.id as string;
+    const url = match === SearchMatchType.Heading && slug ? `${r.url}#${slug}` : r.url as string;
+    return {
+      id,
+      url,
+      type: r.type as string,
+      content: r.title as string,
+      match,
+      snippet,
+      section: (r.section as string) || undefined,
+    };
+  });
+}
+
 function buildSearchUrl(query: string, tag?: string): string {
   const params = new URLSearchParams();
   if (query) params.set('query', query);
@@ -37,8 +171,43 @@ function buildSearchUrl(query: string, tag?: string): string {
   return qs ? `/api/search?${qs}` : '/api/search';
 }
 
-export function Search({ classNames }: SearchProps) {
+interface SearchContextValue {
+  open: boolean;
+  setOpen: React.Dispatch<React.SetStateAction<boolean>>;
+}
+
+const SearchContext = createContext<SearchContextValue | null>(null);
+
+export function SearchProvider({ children }: { children: ReactNode }) {
   const [open, setOpen] = useState(false);
+  const value = useMemo(() => ({ open, setOpen }), [open]);
+  return <SearchContext.Provider value={value}>{children}</SearchContext.Provider>;
+}
+
+function useSearch(): SearchContextValue {
+  const ctx = useContext(SearchContext);
+  if (!ctx) throw new Error('Search components must be used within <SearchProvider>');
+  return ctx;
+}
+
+export function Search({ classNames }: SearchProps) {
+  const { setOpen } = useSearch();
+
+  return (
+    <IconButton
+      size={3}
+      aria-label='Search'
+      title='Search (Ctrl/⌘K)'
+      onClick={() => setOpen(true)}
+      className={classNames?.trigger}
+    >
+      <MagnifyingGlassIcon width={16} height={16} />
+    </IconButton>
+  );
+}
+
+export function SearchDialog() {
+  const { open, setOpen } = useSearch();
   const [search, setSearch] = useState('');
   const [debouncedSearch, setDebouncedSearch] = useState('');
   const navigate = useNavigate();
@@ -64,9 +233,14 @@ export function Search({ classNames }: SearchProps) {
     }
   }, [open, updateDebouncedSearch]);
 
+  const staticMode = isStaticMode();
+
   const { data = [], isLoading } = useQuery<SearchResult[]>({
-    queryKey: ['search', debouncedSearch, tag],
+    queryKey: ['search', debouncedSearch, tag, staticMode],
     queryFn: async ({ signal }) => {
+      if (staticMode) {
+        return searchStatic(debouncedSearch, tag);
+      }
       const res = await fetch(buildSearchUrl(debouncedSearch, tag), { signal });
       if (!res.ok) throw new Error(String(res.status));
       return res.json();
@@ -98,67 +272,55 @@ export function Search({ classNames }: SearchProps) {
   const displayResults = deduplicateByUrl(data);
 
   return (
-    <>
-      <IconButton
-        size={3}
-        aria-label='Search'
-        title='Search (Ctrl/⌘K)'
-        onClick={() => setOpen(true)}
-        className={classNames?.trigger}
-      >
-        <MagnifyingGlassIcon width={16} height={16} />
-      </IconButton>
-
-      <Command.Dialog open={open} onOpenChange={setOpen}>
-        <Command.DialogContent className={styles.dialogContent}>
-          <Command items={displayResults}>
-            <Command.Input
-              placeholder='Search'
-              leadingIcon={<MagnifyingGlassIcon width={16} height={16} />}
-              value={search}
-              onChange={onSearchChange}
-              className={styles.input}
-            />
-
-            <Command.Content className={styles.list}>
-              {isLoading && displayResults.length === 0 && <Command.Empty>Loading...</Command.Empty>}
-              {!isLoading &&
-                search.length > 0 &&
-                displayResults.length === 0 && (
-                  <Command.Empty>No results found.</Command.Empty>
-                )}
-              {search.length === 0 &&
-                displayResults.length > 0 && (
-                  <Command.Group>
-                    <Command.Label>Suggestions</Command.Label>
-                    {displayResults.slice(0, 8).map((result) => (
-                      <Command.Item
-                        key={result.id}
-                        value={result.id}
-                        onClick={() => onSelect(result.url)}
-                        className={styles.item}
-                      >
-                        <SearchResultItem result={result} query="" />
-                      </Command.Item>
-                    ))}
-                  </Command.Group>
-                )}
-              {search.length > 0 &&
-                displayResults.map((result) => (
-                  <Command.Item
-                    key={result.id}
-                    value={result.id}
-                    onClick={() => onSelect(result.url)}
-                    className={styles.item}
-                  >
-                    <SearchResultItem result={result} query={search} />
-                  </Command.Item>
-                ))}
-            </Command.Content>
-          </Command>
-        </Command.DialogContent>
-      </Command.Dialog>
-    </>
+    <Command.Dialog open={open} onOpenChange={setOpen}>
+      <Command.DialogContent className={styles.dialogContent}>
+        <Command items={displayResults}>
+          <Command.Input
+            placeholder='Search'
+            leadingIcon={<MagnifyingGlassIcon width={16} height={16} />}
+            value={search}
+            onChange={onSearchChange}
+            className={styles.input}
+          />
+
+          <Command.Content className={styles.list}>
+            {isLoading && displayResults.length === 0 && <Command.Empty>Loading...</Command.Empty>}
+            {!isLoading &&
+              search.length > 0 &&
+              displayResults.length === 0 && (
+                <Command.Empty>No results found.</Command.Empty>
+              )}
+            {search.length === 0 &&
+              displayResults.length > 0 && (
+                <Command.Group>
+                  <Command.Label>Suggestions</Command.Label>
+                  {displayResults.slice(0, 8).map((result) => (
+                    <Command.Item
+                      key={result.id}
+                      value={result.id}
+                      onClick={() => onSelect(result.url)}
+                      className={styles.item}
+                    >
+                      <SearchResultItem result={result} query="" />
+                    </Command.Item>
+                  ))}
+                </Command.Group>
+              )}
+            {search.length > 0 &&
+              displayResults.map((result) => (
+                <Command.Item
+                  key={result.id}
+                  value={result.id}
+                  onClick={() => onSelect(result.url)}
+                  className={styles.item}
+                >
+                  <SearchResultItem result={result} query={search} />
+                </Command.Item>
+              ))}
+          </Command.Content>
+        </Command>
+      </Command.DialogContent>
+    </Command.Dialog>
   );
 }
 

package/src/lib/data-urls.ts

@@ -0,0 +1,23 @@
+import { isStaticMode } from './static-mode';
+
+export function pageDataUrl(slug: string[]): string {
+  const key = slug.length === 0 ? '' : slug.map(s => encodeURIComponent(s)).join(',');
+  if (isStaticMode()) {
+    return `/data/pages/${key || 'index'}.json`;
+  }
+  return key ? `/api/page?slug=${key}` : '/api/page';
+}
+
+export function specsUrl(versionDir: string | null): string {
+  if (isStaticMode()) {
+    const file = versionDir ? `${encodeURIComponent(versionDir)}.json` : 'latest.json';
+    return `/data/specs/${file}`;
+  }
+  return versionDir
+    ? `/api/specs?version=${encodeURIComponent(versionDir)}`
+    : '/api/specs';
+}
+
+export function searchIndexUrl(): string {
+  return '/data/search.json';
+}

package/src/lib/head.tsx

@@ -9,8 +9,9 @@ export interface HeadProps {
   markdownHref?: string;
 }
 
-export function Head({ title, description, config, jsonLd, markdownHref }: HeadProps) {
+export function Head({ title, description: pageDescription, config, jsonLd, markdownHref }: HeadProps) {
   const { pathname } = useLocation();
+  const description = pageDescription || config.site.description;
   const fullTitle = `${title} | ${config.site.title}`;
   const ogParams = new URLSearchParams({ title });
   if (description) ogParams.set('description', description);

package/src/lib/mdx-component-names.ts

@@ -0,0 +1,15 @@
+import { htmlTagNames } from 'html-tag-names'
+import { svgTagNames } from 'svg-tag-names'
+
+// Names of custom components available to MDX content.
+// Keep in sync with the capitalized keys of `mdxComponents` in src/components/mdx/index.tsx.
+// This lives in a React-free module so the CLI/vite-config can import it.
+export const MDX_COMPONENT_NAMES = [
+  'Callout',
+  'CalloutTitle',
+  'CalloutDescription',
+  'Tabs',
+  'Mermaid',
+] as const
+
+export const KNOWN_TAGS = new Set<string>([...htmlTagNames, ...svgTagNames])