@raystack/chronicle 0.1.0-canary.0efaef0

package/src/lib/page-context.tsx

@@ -0,0 +1,117 @@
+import React, {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useState
+} from 'react';
+import { useLocation } from 'react-router';
+import { mdxComponents } from '@/components/mdx';
+import type { ApiSpec } from '@/lib/openapi';
+import type { ChronicleConfig, Frontmatter, PageTree } from '@/types';
+
+interface PageData {
+  slug: string[];
+  frontmatter: Frontmatter;
+  content: ReactNode;
+}
+
+interface PageContextValue {
+  config: ChronicleConfig;
+  tree: PageTree;
+  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: [] },
+      page: null,
+      apiSpecs: []
+    };
+  }
+  return ctx;
+}
+
+interface PageProviderProps {
+  initialConfig: ChronicleConfig;
+  initialTree: PageTree;
+  initialPage: PageData | null;
+  initialApiSpecs: ApiSpec[];
+  children: ReactNode;
+}
+
+async function loadMdxComponent(relativePath: string): Promise<ReactNode> {
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const mod = relativePath.endsWith('.md')
+    ? await import(`../../.content/${withoutExt}.md`)
+    : await import(`../../.content/${withoutExt}.mdx`);
+  return mod.default
+    ? React.createElement(mod.default, { components: mdxComponents })
+    : null;
+}
+
+export function PageProvider({
+  initialConfig,
+  initialTree,
+  initialPage,
+  initialApiSpecs,
+  children
+}: PageProviderProps) {
+  const { pathname } = useLocation();
+  const [tree] = useState<PageTree>(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 = await loadMdxComponent(data.relativePath);
+        if (cancelled.current) return;
+        setPage({ slug, frontmatter: data.frontmatter, content });
+      })
+      .catch(() => {});
+
+    return () => { cancelled.current = true; };
+  }, [pathname]);
+
+  return (
+    <PageContext.Provider
+      value={{ config: initialConfig, tree, page, apiSpecs }}
+    >
+      {children}
+    </PageContext.Provider>
+  );
+}

package/src/lib/remark-unused-directives.ts

@@ -0,0 +1,30 @@
+import { visit } from 'unist-util-visit'
+import type { Plugin } from 'unified'
+import type { Node } from 'unist'
+
+const remarkUnusedDirectives: Plugin = () => {
+  return (tree) => {
+    visit(tree, ['textDirective'], (node) => {
+      const directive = node as Node & {
+        name?: string
+        attributes?: Record<string, string>
+        children?: Node[]
+        value?: string
+        [key: string]: unknown
+      }
+      if (!directive.data) {
+        const hasAttributes = directive.attributes && Object.keys(directive.attributes).length > 0
+        const hasChildren = directive.children && directive.children.length > 0
+        if (!hasAttributes && !hasChildren) {
+          const name = directive.name
+          if (!name) return
+          Object.keys(directive).forEach((key) => delete directive[key])
+          directive.type = 'text'
+          directive.value = `:${name}`
+        }
+      }
+    })
+  }
+}
+
+export default remarkUnusedDirectives

package/src/lib/schema.ts

@@ -0,0 +1,99 @@
+import type { OpenAPIV3 } from 'openapi-types'
+
+export interface SchemaField {
+  name: string
+  type: string
+  required: boolean
+  description?: string
+  default?: unknown
+  enum?: unknown[]
+  children?: SchemaField[]
+}
+
+export function flattenSchema(
+  schema: OpenAPIV3.SchemaObject,
+  requiredFields: string[] = [],
+): SchemaField[] {
+  if (schema.type === 'array' && schema.items) {
+    const items = schema.items as OpenAPIV3.SchemaObject
+    const itemType = inferType(items)
+    const children =
+      itemType === 'object' || items.properties
+        ? flattenSchema(items, items.required ?? [])
+        : itemType.endsWith('[]') && (items as OpenAPIV3.ArraySchemaObject).items
+          ? flattenSchema((items as OpenAPIV3.ArraySchemaObject).items as OpenAPIV3.SchemaObject)
+          : undefined
+    return [{
+      name: 'items',
+      type: `${itemType}[]`,
+      required: true,
+      description: items.description,
+      children: children?.length ? children : undefined,
+    }]
+  }
+
+  if (schema.type === 'object' || schema.properties) {
+    const properties = (schema.properties ?? {}) as Record<string, OpenAPIV3.SchemaObject>
+    const required = schema.required ?? requiredFields
+
+    return Object.entries(properties).map(([name, prop]) => {
+      const fieldType = inferType(prop)
+      const children =
+        fieldType === 'object' || prop.properties
+          ? flattenSchema(prop, prop.required)
+          : fieldType.endsWith('[]') && (prop as OpenAPIV3.ArraySchemaObject).items
+            ? flattenSchema((prop as OpenAPIV3.ArraySchemaObject).items as OpenAPIV3.SchemaObject)
+            : undefined
+
+      return {
+        name,
+        type: fieldType,
+        required: required.includes(name),
+        description: prop.description,
+        default: prop.default,
+        enum: prop.enum,
+        children: children?.length ? children : undefined,
+      }
+    })
+  }
+
+  return []
+}
+
+export function generateExampleJson(schema: OpenAPIV3.SchemaObject): unknown {
+  if (schema.example !== undefined) return schema.example
+  if (schema.default !== undefined) return schema.default
+
+  if (schema.type === 'array') {
+    const items = schema.items as OpenAPIV3.SchemaObject | undefined
+    return items ? [generateExampleJson(items)] : []
+  }
+
+  if (schema.type === 'object' || schema.properties) {
+    const properties = (schema.properties ?? {}) as Record<string, OpenAPIV3.SchemaObject>
+    const result: Record<string, unknown> = {}
+    for (const [name, prop] of Object.entries(properties)) {
+      result[name] = generateExampleJson(prop)
+    }
+    return result
+  }
+
+  const defaults: Record<string, unknown> = {
+    string: 'string',
+    integer: 0,
+    number: 0,
+    boolean: true,
+  }
+  return defaults[schema.type as string] ?? null
+}
+
+function inferType(schema: OpenAPIV3.SchemaObject): string {
+  if (schema.type === 'array') {
+    const items = schema.items as OpenAPIV3.SchemaObject | undefined
+    const itemType = items ? inferType(items) : 'unknown'
+    return `${itemType}[]`
+  }
+
+  if (schema.format) return `${schema.type}(${schema.format})`
+  return (schema.type as string) ?? 'object'
+}

package/src/lib/snippet-generators.ts

@@ -0,0 +1,87 @@
+interface SnippetOptions {
+  method: string
+  url: string
+  headers: Record<string, string>
+  body?: string
+}
+
+export function generateCurl({ method, url, headers, body }: SnippetOptions): string {
+  const parts = [`curl -X ${method} '${url}'`]
+  for (const [key, value] of Object.entries(headers)) {
+    parts.push(`  -H '${key}: ${value}'`)
+  }
+  if (body) {
+    parts.push(`  -d '${body}'`)
+  }
+  return parts.join(' \\\n')
+}
+
+export function generatePython({ method, url, headers, body }: SnippetOptions): string {
+  const lines: string[] = ['import requests', '']
+  const methodLower = method.toLowerCase()
+  const headerEntries = Object.entries(headers)
+
+  lines.push(`response = requests.${methodLower}(`)
+  lines.push(`    "${url}",`)
+
+  if (headerEntries.length > 0) {
+    lines.push('    headers={')
+    for (const [key, value] of headerEntries) {
+      lines.push(`        "${key}": "${value}",`)
+    }
+    lines.push('    },')
+  }
+
+  if (body) {
+    lines.push(`    json=${body},`)
+  }
+
+  lines.push(')')
+  lines.push('print(response.json())')
+  return lines.join('\n')
+}
+
+export function generateGo({ method, url, headers, body }: SnippetOptions): string {
+  const lines: string[] = []
+
+  if (body) {
+    lines.push('payload := strings.NewReader(`' + body + '`)')
+    lines.push('')
+    lines.push(`req, _ := http.NewRequest("${method}", "${url}", payload)`)
+  } else {
+    lines.push(`req, _ := http.NewRequest("${method}", "${url}", nil)`)
+  }
+
+  for (const [key, value] of Object.entries(headers)) {
+    lines.push(`req.Header.Set("${key}", "${value}")`)
+  }
+
+  lines.push('')
+  lines.push('resp, _ := http.DefaultClient.Do(req)')
+  lines.push('defer resp.Body.Close()')
+  return lines.join('\n')
+}
+
+export function generateTypeScript({ method, url, headers, body }: SnippetOptions): string {
+  const lines: string[] = []
+  const headerEntries = Object.entries(headers)
+
+  lines.push(`const response = await fetch("${url}", {`)
+  lines.push(`  method: "${method}",`)
+
+  if (headerEntries.length > 0) {
+    lines.push('  headers: {')
+    for (const [key, value] of headerEntries) {
+      lines.push(`    "${key}": "${value}",`)
+    }
+    lines.push('  },')
+  }
+
+  if (body) {
+    lines.push(`  body: JSON.stringify(${body}),`)
+  }
+
+  lines.push('});')
+  lines.push('const data = await response.json();')
+  return lines.join('\n')
+}

package/src/lib/source.ts

@@ -0,0 +1,186 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loader } from 'fumadocs-core/source';
+import matter from 'gray-matter';
+import type { MDXContent } from 'mdx/types';
+import type { Frontmatter, PageTree, PageTreeItem } from '@/types';
+
+export interface SourcePage {
+  url: string;
+  slugs: string[];
+  filePath: string;
+  frontmatter: Frontmatter;
+}
+
+function getContentDir(): string {
+  return __CHRONICLE_CONTENT_DIR__ || path.join(process.cwd(), 'content');
+}
+
+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 (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, _absolutePath: fullPath }
+          });
+        } 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 });
+        }
+      }
+    } catch {
+      /* directory not readable */
+    }
+  }
+
+  await scan(contentDir);
+  return files;
+}
+
+let cachedSource: ReturnType<typeof loader> | null = null;
+let cachedPages: SourcePage[] | 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 function invalidate() {
+  cachedSource = null;
+  cachedPages = null;
+}
+
+export async function getPages(): Promise<SourcePage[]> {
+  if (cachedPages) return cachedPages;
+
+  const s = await getSource();
+  cachedPages = s.getPages().map(page => {
+    const data = page.data as Record<string, unknown>;
+    return {
+      url: page.url,
+      slugs: page.slugs,
+      filePath: (data._absolutePath as string) ?? '',
+      frontmatter: {
+        title:
+          (data.title as string) ??
+          page.slugs[page.slugs.length - 1] ??
+          'Untitled',
+        description: data.description as string | undefined,
+        order: data.order as number | undefined,
+        icon: data.icon as string | undefined,
+        lastModified: data.lastModified as string | undefined
+      }
+    };
+  });
+
+  return cachedPages;
+}
+
+export async function getPage(slug?: string[]): Promise<SourcePage | null> {
+  const pages = await getPages();
+  const targetUrl = !slug || slug.length === 0 ? '/' : `/${slug.join('/')}`;
+  return pages.find(p => p.url === targetUrl) ?? null;
+}
+
+export async function loadPageComponent(
+  page: SourcePage
+): Promise<MDXContent | null> {
+  if (!page.filePath) return null;
+  try {
+    await fs.access(page.filePath);
+  } catch {
+    return null;
+  }
+  const contentDir = getContentDir();
+  const relativePath = path.relative(contentDir, page.filePath);
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const mod = relativePath.endsWith('.md')
+    ? await import(`../../.content/${withoutExt}.md`)
+    : await import(`../../.content/${withoutExt}.mdx`);
+  return mod.default;
+}
+
+export async function buildPageTree(): Promise<PageTree> {
+  const s = await getSource();
+  const pages = s.getPages();
+  const folders = new Map<string, PageTreeItem[]>();
+  const rootPages: PageTreeItem[] = [];
+
+  for (const page of pages) {
+    const data = page.data as Record<string, unknown>;
+    const isIndex = page.url === '/';
+    const item: PageTreeItem = {
+      type: 'page',
+      name: (data.title as string) ?? page.slugs.join('/') ?? 'Untitled',
+      url: page.url,
+      order: (data.order as number | undefined) ?? (isIndex ? 0 : undefined)
+    };
+
+    if (page.slugs.length > 1) {
+      const folder = page.slugs[0];
+      if (!folders.has(folder)) {
+        folders.set(folder, []);
+      }
+      folders.get(folder)?.push(item);
+    } else {
+      rootPages.push(item);
+    }
+  }
+
+  const sortByOrder = (items: PageTreeItem[]) =>
+    items.sort(
+      (a, b) =>
+        (a.order ?? Number.MAX_SAFE_INTEGER) -
+        (b.order ?? Number.MAX_SAFE_INTEGER)
+    );
+
+  const children: PageTreeItem[] = sortByOrder(rootPages);
+
+  const folderItems: PageTreeItem[] = [];
+  for (const [folder, items] of folders) {
+    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
+    });
+  }
+
+  children.push(...sortByOrder(folderItems));
+
+  return { name: 'root', children };
+}

package/src/pages/ApiLayout.module.css

@@ -0,0 +1,22 @@
+.layout {
+  height: 100vh;
+  overflow: hidden;
+}
+
+.body {
+  overflow: hidden;
+}
+
+.sidebar {
+  height: 100%;
+}
+
+.content {
+  height: 100%;
+  overflow-y: auto;
+  padding-right: 0;
+}
+
+.hiddenSearch {
+  display: none;
+}

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>
+  );
+}

package/src/pages/DocsLayout.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+
+interface DocsLayoutProps {
+  children: ReactNode;
+}
+
+export function DocsLayout({ children }: DocsLayoutProps) {
+  const { config, tree } = usePageContext();
+  const { Layout, className } = getTheme(config.theme?.name);
+
+  return (
+    <Layout config={config} tree={tree} classNames={{ layout: className }}>
+      {children}
+    </Layout>
+  );
+}