@raystack/chronicle 0.1.0-canary.323385a → 0.1.0-canary.4a4a3f8

package/src/lib/api-routes.ts

@@ -1,6 +1,6 @@
 import type { OpenAPIV3 } from 'openapi-types'
 import slugify from 'slugify'
-import type { PageTree, PageTreeItem } from '@/types/content'
+import type { Root, Node, Item, Folder } from 'fumadocs-core/page-tree'
 import type { ApiSpec } from './openapi'
 
 export function getSpecSlug(spec: ApiSpec): string {
@@ -56,16 +56,15 @@ export function findApiOperation(specs: ApiSpec[], slug: string[]): ApiRouteMatc
   return null
 }
 
-export function buildApiPageTree(specs: ApiSpec[]): PageTree {
-  const children: PageTreeItem[] = []
+export function buildApiPageTree(specs: ApiSpec[]): Root {
+  const children: Node[] = []
 
   for (const spec of specs) {
     const specSlug = getSpecSlug(spec)
     const paths = spec.document.paths ?? {}
     const tags = spec.document.tags ?? []
 
-    // Group operations by tag (case-insensitive to avoid duplicates)
-    const opsByTag = new Map<string, PageTreeItem[]>()
+    const opsByTag = new Map<string, Item[]>()
     const tagDisplayName = new Map<string, string>()
 
     for (const [, pathItem] of Object.entries(paths)) {
@@ -90,7 +89,6 @@ export function buildApiPageTree(specs: ApiSpec[]): PageTree {
       }
     }
 
-    // Use doc.tags display names where available
     for (const t of tags) {
       const key = t.name.toLowerCase()
       if (opsByTag.has(key)) {
@@ -98,7 +96,7 @@ export function buildApiPageTree(specs: ApiSpec[]): PageTree {
       }
     }
 
-    const tagFolders: PageTreeItem[] = Array.from(opsByTag.entries()).map(([key, ops]) => ({
+    const tagFolders: Folder[] = Array.from(opsByTag.entries()).map(([key, ops]) => ({
       type: 'folder' as const,
       name: tagDisplayName.get(key) ?? key,
       icon: 'rectangle-stack',
@@ -110,7 +108,7 @@ export function buildApiPageTree(specs: ApiSpec[]): PageTree {
         type: 'folder',
         name: spec.name,
         children: tagFolders,
-      })
+      } as Folder)
     } else {
       children.push(...tagFolders)
     }

package/src/lib/config.ts

@@ -1,55 +1,58 @@
-import fs from 'fs'
-import path from 'path'
-import { parse } from 'yaml'
-import type { ChronicleConfig } from '@/types'
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+import type { ChronicleConfig } from '@/types';
 
-const CONFIG_FILE = 'chronicle.yaml'
+const CONFIG_FILE = 'chronicle.yaml';
 
 const defaultConfig: ChronicleConfig = {
   title: 'Documentation',
   theme: { name: 'default' },
-  search: { enabled: true, placeholder: 'Search...' },
-}
+  search: { enabled: true, placeholder: 'Search...' }
+};
 
 function resolveConfigPath(): string | null {
-  // Check project root via env var
-  const projectRoot = process.env.CHRONICLE_PROJECT_ROOT
-  if (projectRoot) {
-    const rootPath = path.join(projectRoot, CONFIG_FILE)
-    if (fs.existsSync(rootPath)) return rootPath
-  }
-  // Check cwd
-  const cwdPath = path.join(process.cwd(), CONFIG_FILE)
-  if (fs.existsSync(cwdPath)) return cwdPath
-  // Check content dir
-  const contentDir = process.env.CHRONICLE_CONTENT_DIR
+  const projectRoot =
+    typeof __CHRONICLE_PROJECT_ROOT__ !== 'undefined'
+      ? __CHRONICLE_PROJECT_ROOT__
+      : process.cwd();
+
+  const rootPath = path.join(projectRoot, CONFIG_FILE);
+  if (fs.existsSync(rootPath)) return rootPath;
+
+  const contentDir =
+    typeof __CHRONICLE_CONTENT_DIR__ !== 'undefined'
+      ? __CHRONICLE_CONTENT_DIR__
+      : undefined;
   if (contentDir) {
-    const contentPath = path.join(contentDir, CONFIG_FILE)
-    if (fs.existsSync(contentPath)) return contentPath
+    const contentPath = path.join(contentDir, CONFIG_FILE);
+    if (fs.existsSync(contentPath)) return contentPath;
   }
-  return null
+
+  return null;
 }
 
 export function loadConfig(): ChronicleConfig {
-  const configPath = resolveConfigPath()
+  const configPath = resolveConfigPath();
 
   if (!configPath) {
-    return defaultConfig
+    return defaultConfig;
   }
 
-  const raw = fs.readFileSync(configPath, 'utf-8')
-  const userConfig = parse(raw) as Partial<ChronicleConfig>
+  const raw = fs.readFileSync(configPath, 'utf-8');
+  const userConfig = parse(raw) as Partial<ChronicleConfig>;
 
   return {
     ...defaultConfig,
     ...userConfig,
     theme: {
       name: userConfig.theme?.name ?? defaultConfig.theme!.name,
-      colors: { ...defaultConfig.theme?.colors, ...userConfig.theme?.colors },
+      colors: { ...defaultConfig.theme?.colors, ...userConfig.theme?.colors }
     },
     search: { ...defaultConfig.search, ...userConfig.search },
     footer: userConfig.footer,
     api: userConfig.api,
     llms: { enabled: false, ...userConfig.llms },
-  }
-}
+    analytics: { enabled: false, ...userConfig.analytics }
+  };
+}

package/src/lib/head.tsx

@@ -0,0 +1,49 @@
+import type { ChronicleConfig } from '@/types';
+
+export interface HeadProps {
+  title: string;
+  description?: string;
+  config: ChronicleConfig;
+  jsonLd?: Record<string, unknown>;
+}
+
+export function Head({ title, description, config, jsonLd }: HeadProps) {
+  const fullTitle = `${title} | ${config.title}`;
+  const ogParams = new URLSearchParams({ title });
+  if (description) ogParams.set('description', description);
+
+  return (
+    <>
+      <title>{fullTitle}</title>
+      {description && <meta name='description' content={description} />}
+
+      {config.url && (
+        <>
+          <meta property='og:title' content={title} />
+          {description && (
+            <meta property='og:description' content={description} />
+          )}
+          <meta property='og:site_name' content={config.title} />
+          <meta property='og:type' content='website' />
+          <meta property='og:image' content={`/og?${ogParams.toString()}`} />
+          <meta property='og:image:width' content='1200' />
+          <meta property='og:image:height' content='630' />
+
+          <meta name='twitter:card' content='summary_large_image' />
+          <meta name='twitter:title' content={title} />
+          {description && (
+            <meta name='twitter:description' content={description} />
+          )}
+          <meta name='twitter:image' content={`/og?${ogParams.toString()}`} />
+        </>
+      )}
+
+      {jsonLd && (
+        <script
+          type='application/ld+json'
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd, null, 2) }}
+        />
+      )}
+    </>
+  );
+}

package/src/lib/mdx-loader.ts

@@ -0,0 +1,21 @@
+import React, { type ReactNode } from 'react';
+import type { TableOfContents } from 'fumadocs-core/toc';
+import { mdxComponents } from '@/components/mdx';
+
+const contentModules = import.meta.glob<{ default?: React.ComponentType<any>; toc?: TableOfContents }>(
+  '../../.content/**/*.{mdx,md}'
+);
+
+export async function loadMdxModule(relativePath: string): Promise<{ content: ReactNode; toc: TableOfContents }> {
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const key = relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = contentModules[key];
+  if (!loader) return { content: null, toc: [] };
+  const mod = await loader();
+  const content = mod.default
+    ? React.createElement(mod.default, { components: mdxComponents })
+    : null;
+  return { content, toc: mod.toc ?? [] };
+}

package/src/lib/openapi.ts

@@ -1,5 +1,5 @@
-import fs from 'fs'
-import path from 'path'
+import fs from 'node:fs/promises'
+import path from 'node:path'
 import { parse as parseYaml } from 'yaml'
 import type { OpenAPIV2, OpenAPIV3 } from 'openapi-types'
 import type { ApiConfig, ApiServerConfig, ApiAuthConfig } from '@/types/config'
@@ -17,14 +17,14 @@ export interface ApiSpec {
 export type { SchemaField } from './schema'
 export { flattenSchema } from './schema'
 
-export function loadApiSpecs(apiConfigs: ApiConfig[]): ApiSpec[] {
-  const contentDir = process.env.CHRONICLE_CONTENT_DIR ?? process.cwd()
-  return apiConfigs.map((config) => loadApiSpec(config, contentDir))
+export async function loadApiSpecs(apiConfigs: ApiConfig[]): Promise<ApiSpec[]> {
+  const projectRoot = typeof __CHRONICLE_PROJECT_ROOT__ !== 'undefined' ? __CHRONICLE_PROJECT_ROOT__ : process.cwd()
+  return Promise.all(apiConfigs.map((config) => loadApiSpec(config, projectRoot)))
 }
 
-export function loadApiSpec(config: ApiConfig, contentDir: string): ApiSpec {
-  const specPath = path.resolve(contentDir, config.spec)
-  const raw = fs.readFileSync(specPath, 'utf-8')
+export async function loadApiSpec(config: ApiConfig, projectRoot: string): Promise<ApiSpec> {
+  const specPath = path.resolve(projectRoot, config.spec)
+  const raw = await fs.readFile(specPath, 'utf-8')
   const isYaml = specPath.endsWith('.yaml') || specPath.endsWith('.yml')
   const doc = (isYaml ? parseYaml(raw) : JSON.parse(raw)) as OpenAPIV2.Document | OpenAPIV3.Document
 

package/src/lib/page-context.tsx

@@ -0,0 +1,108 @@
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useState
+} from 'react';
+import { useLocation } from 'react-router';
+import { loadMdxModule } from '@/lib/mdx-loader';
+import type { ApiSpec } from '@/lib/openapi';
+import type { ChronicleConfig, Frontmatter, Root, TableOfContents } from '@/types';
+
+interface PageData {
+  slug: string[];
+  frontmatter: Frontmatter;
+  content: ReactNode;
+  toc: TableOfContents;
+}
+
+interface PageContextValue {
+  config: ChronicleConfig;
+  tree: Root;
+  page: PageData | null;
+  apiSpecs: ApiSpec[];
+}
+
+const PageContext = createContext<PageContextValue | null>(null);
+
+export function usePageContext(): PageContextValue {
+  const ctx = useContext(PageContext);
+  if (!ctx) {
+    console.error('usePageContext: no context found!');
+    return {
+      config: { title: 'Documentation' },
+      tree: { name: 'root', children: [] } as Root,
+      page: null,
+      apiSpecs: []
+    };
+  }
+  return ctx;
+}
+
+interface PageProviderProps {
+  initialConfig: ChronicleConfig;
+  initialTree: Root;
+  initialPage: PageData | null;
+  initialApiSpecs: ApiSpec[];
+  children: ReactNode;
+}
+
+export function PageProvider({
+  initialConfig,
+  initialTree,
+  initialPage,
+  initialApiSpecs,
+  children
+}: PageProviderProps) {
+  const { pathname } = useLocation();
+  const [tree] = useState<Root>(initialTree);
+  const [page, setPage] = useState<PageData | null>(initialPage);
+  const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs);
+  const [currentPath, setCurrentPath] = useState(pathname);
+
+  useEffect(() => {
+    if (pathname === currentPath) return;
+    setCurrentPath(pathname);
+
+    const cancelled = { current: false };
+
+    if (pathname.startsWith('/apis')) {
+      if (apiSpecs.length === 0) {
+        fetch('/api/specs')
+          .then(res => res.json())
+          .then(specs => {
+            if (!cancelled.current) setApiSpecs(specs);
+          })
+          .catch(() => {});
+      }
+      return () => { cancelled.current = true; };
+    }
+
+    const slug = pathname === '/'
+      ? []
+      : pathname.slice(1).split('/').filter(Boolean);
+
+    const apiPath = slug.length === 0 ? '/api/page/' : `/api/page/${slug.join('/')}`;
+
+    fetch(apiPath)
+      .then(res => res.json())
+      .then(async (data: { frontmatter: Frontmatter; relativePath: string }) => {
+        if (cancelled.current) return;
+        const { content, toc } = await loadMdxModule(data.relativePath);
+        if (cancelled.current) return;
+        setPage({ slug, frontmatter: data.frontmatter, content, toc });
+      })
+      .catch(() => {});
+
+    return () => { cancelled.current = true; };
+  }, [pathname]);
+
+  return (
+    <PageContext.Provider
+      value={{ config: initialConfig, tree, page, apiSpecs }}
+    >
+      {children}
+    </PageContext.Provider>
+  );
+}

package/src/lib/source.ts

@@ -1,67 +1,156 @@
-import { docs } from '@/.source/server'
-import { loader } from 'fumadocs-core/source'
-import type { PageTree, PageTreeItem, Frontmatter } from '@/types'
-
-export const source = loader({
-  baseUrl: '/',
-  source: docs.toFumadocsSource(),
-})
-
-export function sortByOrder<T extends { frontmatter?: Frontmatter }>(
-  items: T[]
-): T[] {
-  return [...items].sort((a, b) => {
-    const orderA = a.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
-    const orderB = b.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
-    return orderA - orderB
-  })
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loader } from 'fumadocs-core/source';
+import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
+import matter from 'gray-matter';
+import type { MDXContent } from 'mdx/types';
+import type { TableOfContents } from 'fumadocs-core/toc';
+import type { Frontmatter } from '@/types';
+
+function getContentDir(): string {
+  return __CHRONICLE_CONTENT_DIR__ || path.join(process.cwd(), 'content');
 }
 
-export function buildPageTree(): PageTree {
-  const pages = source.getPages()
-  const folders = new Map<string, PageTreeItem[]>()
-  const rootPages: PageTreeItem[] = []
-
-  pages.forEach((page) => {
-    const data = page.data as { title?: string; order?: number }
-    const isIndex = page.url === '/'
-    const item: PageTreeItem = {
-      type: 'page',
-      name: data.title ?? page.slugs.join('/') ?? 'Untitled',
-      url: page.url,
-      order: data.order ?? (isIndex ? 0 : undefined),
-    }
+async function scanFiles(contentDir: string) {
+  const files: {
+    type: 'page' | 'meta';
+    path: string;
+    data: Record<string, unknown>;
+  }[] = [];
+
+  async function scan(dir: string, prefix: string[] = []) {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules')
+          continue;
+        const fullPath = path.join(dir, entry.name);
+        const relativePath = [...prefix, entry.name].join('/');
 
-    if (page.slugs.length > 1) {
-      const folder = page.slugs[0]
-      if (!folders.has(folder)) {
-        folders.set(folder, [])
+        if (entry.isDirectory()) {
+          await scan(fullPath, [...prefix, entry.name]);
+          continue;
+        }
+
+        if (entry.name.endsWith('.mdx') || entry.name.endsWith('.md')) {
+          const raw = await fs.readFile(fullPath, 'utf-8');
+          const { data } = matter(raw);
+          files.push({
+            type: 'page',
+            path: relativePath,
+            data: { ...data, _relativePath: relativePath }
+          });
+        } else if (entry.name === 'meta.json' || entry.name === 'meta.yaml') {
+          const raw = await fs.readFile(fullPath, 'utf-8');
+          const data = entry.name.endsWith('.json')
+            ? JSON.parse(raw)
+            : matter(raw).data;
+          files.push({ type: 'meta', path: relativePath, data });
+        }
       }
-      folders.get(folder)?.push(item)
-    } else {
-      rootPages.push(item)
+    } catch {
+      /* directory not readable */
     }
-  })
+  }
+
+  await scan(contentDir);
+  return files;
+}
+
+let cachedSource: ReturnType<typeof loader> | null = null;
+
+async function getSource() {
+  if (cachedSource) return cachedSource;
+  const contentDir = getContentDir();
+  const files = await scanFiles(contentDir);
+  cachedSource = loader({
+    source: { files },
+    baseUrl: '/'
+  });
+  return cachedSource;
+}
+
+export { getSource as source };
+
+export function invalidate() {
+  cachedSource = null;
+}
 
-  const sortByOrder = (items: PageTreeItem[]) =>
-    items.sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER))
+function getOrder(node: Node, orderMap: Map<string, number>): number | undefined {
+  if (node.type === 'page') return orderMap.get(node.url);
+  if (node.type === 'folder' && node.index) return orderMap.get(node.index.url);
+  return undefined;
+}
+
+function sortNodes(nodes: Node[], orderMap: Map<string, number>): Node[] {
+  return [...nodes]
+    .map(n =>
+      n.type === 'folder'
+        ? ({ ...n, children: sortNodes(n.children, orderMap) } as Folder)
+        : n
+    )
+    .sort(
+      (a, b) =>
+        (getOrder(a, orderMap) ?? Number.MAX_SAFE_INTEGER) -
+        (getOrder(b, orderMap) ?? Number.MAX_SAFE_INTEGER)
+    );
+}
+
+function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[]): Root {
+  const orderMap = new Map<string, number>();
+  for (const page of pages) {
+    const d = page.data as Record<string, unknown>;
+    const order = d.order as number | undefined;
+    if (order !== undefined) orderMap.set(page.url, order);
+    if (page.url === '/') orderMap.set('/', order ?? 0);
+  }
+  return { ...tree, children: sortNodes(tree.children, orderMap) };
+}
+
+export async function getPageTree(): Promise<Root> {
+  const s = await getSource();
+  return sortTreeByOrder(s.pageTree as Root, s.getPages());
+}
+
+export async function getPages() {
+  const s = await getSource();
+  return s.getPages();
+}
 
-  const children: PageTreeItem[] = sortByOrder(rootPages)
+export async function getPage(slugs?: string[]) {
+  const s = await getSource();
+  return s.getPage(slugs);
+}
 
-  const folderItems: PageTreeItem[] = []
-  folders.forEach((items, folder) => {
-    const sorted = sortByOrder(items)
-    const indexPage = items.find(item => item.url === `/${folder}`)
-    const folderOrder = indexPage?.order ?? sorted[0]?.order
-    folderItems.push({
-      type: 'folder',
-      name: folder.charAt(0).toUpperCase() + folder.slice(1),
-      order: folderOrder,
-      children: sorted,
-    })
-  })
+export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: string): Frontmatter {
+  const d = page.data as Record<string, unknown>;
+  return {
+    title: (d.title as string) ?? fallbackTitle ?? 'Untitled',
+    description: d.description as string | undefined,
+    order: d.order as number | undefined,
+    icon: d.icon as string | undefined,
+    lastModified: d.lastModified as string | undefined,
+  };
+}
 
-  children.push(...sortByOrder(folderItems))
+export function getRelativePath(page: { data: unknown }): string {
+  return ((page.data as Record<string, unknown>)._relativePath as string) ?? '';
+}
 
-  return { name: 'root', children }
+export async function loadPageModule(
+  relativePath: string
+): Promise<{ default: MDXContent | null; toc: TableOfContents }> {
+  if (!relativePath) return { default: null, toc: [] };
+  const contentDir = getContentDir();
+  const fullPath = path.join(contentDir, relativePath);
+  try {
+    await fs.access(fullPath);
+  } catch {
+    return { default: null, toc: [] };
+  }
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const mod = relativePath.endsWith('.md')
+    ? await import(`../../.content/${withoutExt}.md`)
+    : await import(`../../.content/${withoutExt}.mdx`);
+  return { default: mod.default ?? null, toc: mod.toc ?? [] };
 }

package/src/pages/ApiLayout.tsx

@@ -0,0 +1,33 @@
+import { cx } from 'class-variance-authority';
+import type { ReactNode } from 'react';
+import { Search } from '@/components/ui/search';
+import { buildApiPageTree } from '@/lib/api-routes';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+import styles from './ApiLayout.module.css';
+
+interface ApiLayoutProps {
+  children: ReactNode;
+}
+
+export function ApiLayout({ children }: ApiLayoutProps) {
+  const { config, apiSpecs } = usePageContext();
+  const { Layout, className } = getTheme(config.theme?.name);
+  const tree = buildApiPageTree(apiSpecs);
+
+  return (
+    <Layout
+      config={config}
+      tree={tree}
+      classNames={{
+        layout: cx(styles.layout, className),
+        body: styles.body,
+        sidebar: styles.sidebar,
+        content: styles.content
+      }}
+    >
+      <Search className={styles.hiddenSearch} />
+      {children}
+    </Layout>
+  );
+}

package/src/pages/ApiPage.tsx

@@ -0,0 +1,73 @@
+import { Flex, Headline, Text } from '@raystack/apsara';
+import type { OpenAPIV3 } from 'openapi-types';
+import { EndpointPage } from '@/components/api';
+import { findApiOperation } from '@/lib/api-routes';
+import { Head } from '@/lib/head';
+import type { ApiSpec } from '@/lib/openapi';
+import { usePageContext } from '@/lib/page-context';
+
+interface ApiPageProps {
+  slug: string[];
+}
+
+export function ApiPage({ slug }: ApiPageProps) {
+  const { config, apiSpecs } = usePageContext();
+
+  if (slug.length === 0) {
+    return (
+      <>
+        <Head
+          title='API Reference'
+          description={`API documentation for ${config.title}`}
+          config={config}
+        />
+        <ApiLanding specs={apiSpecs} />
+      </>
+    );
+  }
+
+  const match = findApiOperation(apiSpecs, slug);
+  if (!match) return null;
+
+  const operation = match.operation as OpenAPIV3.OperationObject;
+  const title =
+    operation.summary ?? `${match.method.toUpperCase()} ${match.path}`;
+
+  return (
+    <>
+      <Head title={title} description={operation.description} config={config} />
+      <EndpointPage
+        method={match.method}
+        path={match.path}
+        operation={match.operation}
+        serverUrl={match.spec.server.url}
+        specName={match.spec.name}
+        auth={match.spec.auth}
+      />
+    </>
+  );
+}
+
+function ApiLanding({ specs }: { specs: ApiSpec[] }) {
+  return (
+    <Flex
+      direction='column'
+      gap='large'
+      style={{ padding: 'var(--rs-space-7)' }}
+    >
+      <Headline size='medium' as='h1'>
+        API Reference
+      </Headline>
+      {specs.map(spec => (
+        <Flex key={spec.name} direction='column' gap='small'>
+          <Headline size='small' as='h2'>
+            {spec.name}
+          </Headline>
+          {spec.document.info.description && (
+            <Text size={3}>{spec.document.info.description}</Text>
+          )}
+        </Flex>
+      ))}
+    </Flex>
+  );
+}