@raystack/chronicle 0.1.0-canary.6b53016 → 0.1.0-canary.9b7d924

package/src/lib/page-context.tsx

@@ -0,0 +1,95 @@
+import { createContext, useContext, useState, useEffect, type ReactNode } from 'react'
+import { useLocation } from 'react-router-dom'
+import type { ChronicleConfig, Frontmatter, PageTree } from '@/types'
+import type { ApiSpec } from '@/lib/openapi'
+import { getPage, loadPageComponent, buildPageTree } from '@/lib/source'
+import { mdxComponents } from '@/components/mdx'
+import React from 'react'
+
+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
+}
+
+export function PageProvider({ initialConfig, initialTree, initialPage, initialApiSpecs, children }: PageProviderProps) {
+  const { pathname } = useLocation()
+  const [tree, setTree] = 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)
+
+    let cancelled = false
+
+    if (pathname.startsWith('/apis')) {
+      // Fetch API specs if not already loaded
+      if (apiSpecs.length === 0) {
+        fetch('/api/specs')
+          .then((res) => res.json())
+          .then((specs) => { if (!cancelled) setApiSpecs(specs) })
+          .catch(() => {})
+      }
+      return () => { cancelled = true }
+    }
+
+    async function load() {
+      const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean)
+
+      const [sourcePage, newTree] = await Promise.all([getPage(slug), buildPageTree()])
+      if (cancelled || !sourcePage) return
+
+      const component = await loadPageComponent(sourcePage)
+      if (cancelled) return
+
+      setTree(newTree)
+      setPage({
+        slug,
+        frontmatter: sourcePage.frontmatter,
+        content: component ? React.createElement(component, { components: mdxComponents }) : null,
+      })
+    }
+    load()
+    return () => { cancelled = true }
+  }, [pathname])
+
+  return (
+    <PageContext.Provider value={{ config: initialConfig, tree, page, apiSpecs }}>
+      {children}
+    </PageContext.Provider>
+  )
+}

package/src/lib/source.ts

@@ -1,35 +1,106 @@
-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 type { MDXContent } from 'mdx/types'
+import type { Frontmatter, PageTree, PageTreeItem } from '@/types'
+
+const meta: Record<string, Frontmatter> = import.meta.glob(
+  '@content/**/*.{mdx,md}',
+  { eager: true, import: 'frontmatter' }
+)
+
+const loaders: Record<string, () => Promise<{ default: MDXContent }>> = import.meta.glob(
+  '@content/**/*.{mdx,md}'
+)
+
+export interface SourcePage {
+  url: string
+  slugs: string[]
+  filePath: string
+  frontmatter: Frontmatter
+}
+
+// Compute common directory prefix of all glob keys once
+function computePrefix(keys: string[]): string {
+  if (keys.length === 0) return ''
+  const dirs = keys.map((k) => k.split('/').slice(0, -1)) // drop filename
+  const first = dirs[0]
+  let depth = 0
+  for (let i = 0; i < first.length; i++) {
+    if (dirs.every((d) => d[i] === first[i])) {
+      depth = i + 1
+    } else {
+      break
+    }
+  }
+  return first.slice(0, depth).join('/') + '/'
+}
+
+const prefix = computePrefix(Object.keys(meta))
+
+function filePathToSlugs(filePath: string): string[] {
+  const relative = filePath.slice(prefix.length)
+  const withoutExt = relative.replace(/\.(mdx|md)$/, '')
+  const parts = withoutExt.split('/').filter(Boolean)
+  if (parts[parts.length - 1] === 'index') parts.pop()
+  return parts
+}
+
+function slugsToUrl(slugs: string[]): string {
+  return slugs.length === 0 ? '/' : '/' + slugs.join('/')
+}
+
+let cachedPages: SourcePage[] | null = null
+
+export async function getPages(): Promise<SourcePage[]> {
+  if (cachedPages) return cachedPages
+
+  cachedPages = Object.entries(meta).map(([filePath, fm]) => {
+    const slugs = filePathToSlugs(filePath)
+    const baseName = slugs[slugs.length - 1] ?? 'index'
+    return {
+      url: slugsToUrl(slugs),
+      slugs,
+      filePath,
+      frontmatter: {
+        title: fm?.title ?? baseName,
+        description: fm?.description,
+        order: fm?.order,
+        icon: fm?.icon,
+        lastModified: fm?.lastModified,
+      },
+    }
   })
+
+  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> {
+  const loader = loaders[page.filePath]
+  if (!loader) return null
+  const mod = await loader()
+  return mod.default
+}
+
+export function invalidate() {
+  cachedPages = null
 }
 
-export function buildPageTree(): PageTree {
-  const pages = source.getPages()
+export async function buildPageTree(): Promise<PageTree> {
+  const pages = await 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',
+      name: page.frontmatter.title,
       url: page.url,
-      order: data.order ?? (isIndex ? 0 : undefined),
+      order: page.frontmatter.order ?? (isIndex ? 0 : undefined),
     }
 
     if (page.slugs.length > 1) {

package/src/{app/apis/[[...slug]]/layout.tsx → pages/ApiLayout.tsx}

@@ -1,16 +1,19 @@
+import type { ReactNode } from 'react'
 import { cx } from 'class-variance-authority'
-import { loadConfig } from '@/lib/config'
-import { loadApiSpecs } from '@/lib/openapi'
+import { usePageContext } from '@/lib/page-context'
 import { buildApiPageTree } from '@/lib/api-routes'
 import { getTheme } from '@/themes/registry'
 import { Search } from '@/components/ui/search'
-import styles from './layout.module.css'
+import styles from './ApiLayout.module.css'
 
-export default function ApiLayout({ children }: { children: React.ReactNode }) {
-  const config = loadConfig()
+interface ApiLayoutProps {
+  children: ReactNode
+}
+
+export function ApiLayout({ children }: ApiLayoutProps) {
+  const { config, apiSpecs } = usePageContext()
   const { Layout, className } = getTheme(config.theme?.name)
-  const specs = loadApiSpecs(config.api ?? [])
-  const tree = buildApiPageTree(specs)
+  const tree = buildApiPageTree(apiSpecs)
 
   return (
     <Layout config={config} tree={tree} classNames={{

package/src/pages/ApiPage.tsx

@@ -0,0 +1,68 @@
+import type { OpenAPIV3 } from 'openapi-types'
+import { Flex, Headline, Text } from '@raystack/apsara'
+import { usePageContext } from '@/lib/page-context'
+import { findApiOperation } from '@/lib/api-routes'
+import { EndpointPage } from '@/components/api'
+import { Head } from '@/lib/head'
+import type { ApiSpec } from '@/lib/openapi'
+
+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>
+  )
+}

package/src/pages/DocsPage.tsx

@@ -0,0 +1,43 @@
+import { usePageContext } from '@/lib/page-context'
+import { getTheme } from '@/themes/registry'
+import { Head } from '@/lib/head'
+
+interface DocsPageProps {
+  slug: string[]
+}
+
+export function DocsPage({ slug }: DocsPageProps) {
+  const { config, tree, page } = usePageContext()
+
+  if (!page) return null
+
+  const { Page } = getTheme(config.theme?.name)
+  const pageUrl = config.url ? `${config.url}/${slug.join('/')}` : undefined
+
+  return (
+    <>
+      <Head
+        title={page.frontmatter.title}
+        description={page.frontmatter.description}
+        config={config}
+        jsonLd={{
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          headline: page.frontmatter.title,
+          description: page.frontmatter.description,
+          ...(pageUrl && { url: pageUrl }),
+        }}
+      />
+      <Page
+        page={{
+          slug,
+          frontmatter: page.frontmatter,
+          content: page.content,
+          toc: [],
+        }}
+        config={config}
+        tree={tree}
+      />
+    </>
+  )
+}

package/src/pages/NotFound.tsx

@@ -0,0 +1,10 @@
+import { Flex, Headline, Text } from '@raystack/apsara'
+
+export function NotFound() {
+  return (
+    <Flex direction="column" align="center" justify="center" style={{ minHeight: '60vh' }}>
+      <Headline size="large" as="h1">404</Headline>
+      <Text size={3}>Page not found</Text>
+    </Flex>
+  )
+}

package/src/pages/__tests__/head.test.tsx

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { Head } from '@/lib/head'
+
+describe('Head component', () => {
+  const baseConfig = {
+    title: 'Test Docs',
+    theme: { name: 'default' as const },
+    search: { enabled: true, placeholder: 'Search...' },
+  }
+
+  it('renders title tag', () => {
+    const html = renderToString(
+      <Head title="Page Title" config={baseConfig} />
+    )
+    expect(html).toContain('Page Title | Test Docs')
+  })
+
+  it('renders description meta tag', () => {
+    const html = renderToString(
+      <Head title="Page" description="A description" config={baseConfig} />
+    )
+    expect(html).toContain('A description')
+  })
+
+  it('renders OG tags when config.url is set', () => {
+    const html = renderToString(
+      <Head
+        title="Page"
+        description="Desc"
+        config={{ ...baseConfig, url: 'https://docs.example.com' }}
+      />
+    )
+    expect(html).toContain('og:title')
+    expect(html).toContain('og:description')
+    expect(html).toContain('twitter:card')
+  })
+
+  it('skips OG tags when no url in config', () => {
+    const html = renderToString(
+      <Head title="Page" config={baseConfig} />
+    )
+    expect(html).not.toContain('og:title')
+  })
+
+  it('renders JSON-LD script', () => {
+    const html = renderToString(
+      <Head
+        title="Page"
+        config={baseConfig}
+        jsonLd={{ '@context': 'https://schema.org', '@type': 'Article' }}
+      />
+    )
+    expect(html).toContain('application/ld+json')
+    expect(html).toContain('schema.org')
+  })
+})

package/src/server/App.tsx

@@ -0,0 +1,59 @@
+import '@raystack/apsara/normalize.css'
+import '@raystack/apsara/style.css'
+import { ThemeProvider } from '@raystack/apsara'
+import { useLocation } from 'react-router-dom'
+import { usePageContext } from '@/lib/page-context'
+import { Head } from '@/lib/head'
+import { DocsLayout } from '@/pages/DocsLayout'
+import { DocsPage } from '@/pages/DocsPage'
+import { ApiLayout } from '@/pages/ApiLayout'
+import { ApiPage } from '@/pages/ApiPage'
+import type { ChronicleConfig } from '@/types'
+
+function resolveRoute(pathname: string) {
+  if (pathname.startsWith('/apis')) {
+    const slug = pathname.replace(/^\/apis\/?/, '').split('/').filter(Boolean)
+    return { type: 'api' as const, slug }
+  }
+
+  const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean)
+  return { type: 'docs' as const, slug }
+}
+
+export function App() {
+  const { pathname } = useLocation()
+  const { config } = usePageContext()
+  const route = resolveRoute(pathname)
+
+  return (
+    <ThemeProvider enableSystem>
+      <RootHead config={config} />
+      {route.type === 'api' ? (
+        <ApiLayout>
+          <ApiPage slug={route.slug} />
+        </ApiLayout>
+      ) : (
+        <DocsLayout>
+          <DocsPage slug={route.slug} />
+        </DocsLayout>
+      )}
+    </ThemeProvider>
+  )
+}
+
+function RootHead({ config }: { config: ChronicleConfig }) {
+  return (
+    <Head
+      title={config.title}
+      description={config.description}
+      config={config}
+      jsonLd={config.url ? {
+        '@context': 'https://schema.org',
+        '@type': 'WebSite',
+        name: config.title,
+        description: config.description,
+        url: config.url,
+      } : undefined}
+    />
+  )
+}

package/src/server/__tests__/entry-server.test.tsx

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest'
+import { render, type SSRData } from '../entry-server'
+
+const mockData: SSRData = {
+  config: { title: 'Test Site' },
+  tree: { name: 'root', children: [] },
+  page: {
+    slug: [],
+    frontmatter: { title: 'Test' },
+    content: null,
+  },
+  apiSpecs: [],
+}
+
+describe('entry-server', () => {
+  it('exports a render function', () => {
+    expect(typeof render).toBe('function')
+  })
+
+  it('returns an HTML string', () => {
+    const html = render('http://localhost:3000/', mockData)
+    expect(typeof html).toBe('string')
+    expect(html.length).toBeGreaterThan(0)
+  })
+
+  it('renders docs route for root URL', () => {
+    const html = render('http://localhost:3000/', mockData)
+    expect(html).toBeTruthy()
+  })
+
+  it('renders api route for /apis URL', () => {
+    const html = render('http://localhost:3000/apis', mockData)
+    expect(html).toBeTruthy()
+  })
+})

package/src/server/__tests__/handlers.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest'
+import { handleHealth } from '../handlers/health'
+import { handleRobots } from '../handlers/robots'
+import { handleSitemap } from '../handlers/sitemap'
+import { handleApisProxy } from '../handlers/apis-proxy'
+import { handleLlms } from '../handlers/llms'
+
+describe('handleHealth', () => {
+  it('returns 200 with status ok', async () => {
+    const response = handleHealth()
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body).toEqual({ status: 'ok' })
+  })
+})
+
+describe('handleRobots', () => {
+  it('returns text/plain content type', async () => {
+    const response = handleRobots()
+    expect(response.headers.get('content-type')).toBe('text/plain')
+  })
+
+  it('includes User-agent directive', async () => {
+    const response = handleRobots()
+    const text = await response.text()
+    expect(text).toContain('User-agent: *')
+    expect(text).toContain('Allow: /')
+  })
+})
+
+describe('handleSitemap', () => {
+  it('returns application/xml content type', async () => {
+    const response = await handleSitemap()
+    expect(response.headers.get('content-type')).toBe('application/xml')
+  })
+
+  it('returns valid XML structure', async () => {
+    const response = await handleSitemap()
+    const xml = await response.text()
+    expect(xml).toContain('<urlset')
+  })
+})
+
+describe('handleApisProxy', () => {
+  it('returns 405 for GET requests', async () => {
+    const req = new Request('http://localhost:3000/api/apis-proxy', { method: 'GET' })
+    const response = await handleApisProxy(req)
+    expect(response.status).toBe(405)
+  })
+
+  it('returns 400 for POST without required fields', async () => {
+    const req = new Request('http://localhost:3000/api/apis-proxy', {
+      method: 'POST',
+      body: JSON.stringify({}),
+      headers: { 'Content-Type': 'application/json' },
+    })
+    const response = await handleApisProxy(req)
+    expect(response.status).toBe(400)
+  })
+
+  it('returns 404 for unknown spec', async () => {
+    const req = new Request('http://localhost:3000/api/apis-proxy', {
+      method: 'POST',
+      body: JSON.stringify({ specName: 'nonexistent', method: 'GET', path: '/test' }),
+      headers: { 'Content-Type': 'application/json' },
+    })
+    const response = await handleApisProxy(req)
+    expect(response.status).toBe(404)
+  })
+})
+
+describe('handleLlms', () => {
+  it('returns 404 when llms not enabled', async () => {
+    const response = await handleLlms()
+    expect(response.status).toBe(404)
+  })
+})

package/src/server/__tests__/og.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest'
+import { handleOg } from '../handlers/og'
+
+// OG handler requires network to fetch fonts, skip in CI-like environments
+describe.skipIf(!process.env.TEST_OG)('handleOg', () => {
+  it('returns SVG content type', async () => {
+    const req = new Request('http://localhost:3000/og?title=Test')
+    const response = await handleOg(req)
+    expect(response.headers.get('content-type')).toBe('image/svg+xml')
+  })
+
+  it('returns cache-control header', async () => {
+    const req = new Request('http://localhost:3000/og?title=Test')
+    const response = await handleOg(req)
+    expect(response.headers.get('cache-control')).toContain('max-age')
+  })
+})
+
+describe('handleOg export', () => {
+  it('exports a function', () => {
+    expect(typeof handleOg).toBe('function')
+  })
+})