@raystack/chronicle 0.1.0-canary.e11f924

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,67 @@
+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
+  })
+}
+
+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),
+    }
+
+    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[] = []
+  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,
+    })
+  })
+
+  children.push(...sortByOrder(folderItems))
+
+  return { name: 'root', children }
+}

package/src/themes/default/Layout.module.css

@@ -0,0 +1,81 @@
+.layout {
+  min-height: 100vh;
+}
+
+.header {
+  border-bottom: 1px solid var(--rs-color-border-base-primary);
+}
+
+.search {
+  margin-left: var(--rs-space-5);
+}
+
+.body {
+  flex: 1;
+}
+
+.sidebar {
+  width: 260px;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+}
+
+.content {
+  flex: 1;
+  padding: var(--rs-space-9);
+}
+
+.sidebarList {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.separator {
+  height: 1px;
+  background: var(--rs-color-border-base-primary);
+  margin: var(--rs-space-3) 0;
+}
+
+.folder {
+  margin-bottom: var(--rs-space-3);
+}
+
+.folderLabel {
+  font-weight: 500;
+  font-size: 0.875rem;
+  color: var(--rs-color-text-base-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.folder > .sidebarList {
+  margin-top: var(--rs-space-2);
+  padding-left: var(--rs-space-4);
+}
+
+.navButton {
+  display: flex;
+  align-items: center;
+  height: 32px;
+  padding: 0 var(--rs-space-4);
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  font-size: var(--rs-font-size-small);
+  font-weight: var(--rs-font-weight-medium);
+  color: var(--rs-color-foreground-base-primary);
+  text-decoration: none;
+}
+
+.navButton:hover {
+  background: var(--rs-color-background-base-primary-hover);
+}
+
+.groupItems {
+  padding-left: var(--rs-space-4);
+}
+
+.page {
+  padding: var(--rs-space-2) 0;
+}

package/src/themes/default/Layout.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import { useMemo, useEffect, useRef } from "react";
+import { usePathname } from "next/navigation";
+import NextLink from "next/link";
+import { cx } from "class-variance-authority";
+import { Flex, Navbar, Headline, Link, Sidebar, Button } from "@raystack/apsara";
+import { RectangleStackIcon } from "@heroicons/react/24/outline";
+import { ClientThemeSwitcher } from "@/components/ui/client-theme-switcher";
+import { Search } from "@/components/ui/search";
+import { Footer } from "@/components/ui/footer";
+import { MethodBadge } from "@/components/api/method-badge";
+import type { ThemeLayoutProps, PageTreeItem } from "@/types";
+import styles from "./Layout.module.css";
+
+const iconMap: Record<string, React.ReactNode> = {
+  "rectangle-stack": <RectangleStackIcon width={16} height={16} />,
+  "method-get": <MethodBadge method="GET" size="micro" />,
+  "method-post": <MethodBadge method="POST" size="micro" />,
+  "method-put": <MethodBadge method="PUT" size="micro" />,
+  "method-delete": <MethodBadge method="DELETE" size="micro" />,
+  "method-patch": <MethodBadge method="PATCH" size="micro" />,
+};
+
+let savedScrollTop = 0;
+
+export function Layout({ children, config, tree, classNames }: ThemeLayoutProps) {
+  const pathname = usePathname();
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const onScroll = () => { savedScrollTop = el.scrollTop; };
+    el.addEventListener('scroll', onScroll);
+    return () => el.removeEventListener('scroll', onScroll);
+  }, []);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (el) requestAnimationFrame(() => { el.scrollTop = savedScrollTop; });
+  }, [pathname]);
+
+  return (
+    <Flex direction="column" className={cx(styles.layout, classNames?.layout)}>
+      <Navbar className={styles.header}>
+        <Navbar.Start>
+          <NextLink href="/" style={{ textDecoration: 'none', color: 'inherit' }}>
+            <Headline size="small" weight="medium" as="h1">
+              {config.title}
+            </Headline>
+          </NextLink>
+        </Navbar.Start>
+        <Navbar.End>
+          <Flex gap="medium" align="center" className={styles.navActions}>
+            {config.api?.map((api) => (
+              <NextLink key={api.basePath} href={api.basePath} className={styles.navButton}>
+                {api.name} API
+              </NextLink>
+            ))}
+            {config.navigation?.links?.map((link) => (
+              <Link key={link.href} href={link.href}>
+                {link.label}
+              </Link>
+            ))}
+            {config.search?.enabled && <Search />}
+          </Flex>
+          <ClientThemeSwitcher size={16} />
+        </Navbar.End>
+      </Navbar>
+      <Flex className={cx(styles.body, classNames?.body)}>
+        <Sidebar defaultOpen collapsible={false} className={cx(styles.sidebar, classNames?.sidebar)}>
+          <Sidebar.Main ref={scrollRef}>
+            {tree.children.map((item) => (
+              <SidebarNode
+                key={item.url ?? item.name}
+                item={item}
+                pathname={pathname}
+              />
+            ))}
+          </Sidebar.Main>
+        </Sidebar>
+        <main className={cx(styles.content, classNames?.content)}>{children}</main>
+      </Flex>
+      <Footer config={config.footer} />
+    </Flex>
+  );
+}
+
+function SidebarNode({
+  item,
+  pathname,
+}: {
+  item: PageTreeItem;
+  pathname: string;
+}) {
+  if (item.type === "separator") {
+    return null;
+  }
+
+  if (item.type === "folder" && item.children) {
+    return (
+      <Sidebar.Group
+        label={item.name}
+        leadingIcon={item.icon ? iconMap[item.icon] : undefined}
+        classNames={{ items: styles.groupItems }}
+      >
+        {item.children.map((child) => (
+          <SidebarNode
+            key={child.url ?? child.name}
+            item={child}
+            pathname={pathname}
+          />
+        ))}
+      </Sidebar.Group>
+    );
+  }
+
+  const isActive = pathname === item.url;
+  const href = item.url ?? "#";
+  const link = useMemo(() => <NextLink href={href} scroll={false} />, [href]);
+
+  return (
+    <Sidebar.Item
+      href={href}
+      active={isActive}
+      leadingIcon={item.icon ? iconMap[item.icon] : undefined}
+      as={link}
+    >
+      {item.name}
+    </Sidebar.Item>
+  );
+}

package/src/themes/default/Page.module.css

@@ -0,0 +1,46 @@
+.page {
+  gap: var(--rs-space-9);
+}
+
+.article {
+  flex: 1;
+  min-width: 0;
+  max-width: 768px;
+}
+
+.content {
+  line-height: 1.7;
+}
+
+.content h1,
+.content h2,
+.content h3,
+.content h4,
+.content h5,
+.content h6 {
+  margin-top: var(--rs-space-8);
+  margin-bottom: var(--rs-space-5);
+  line-height: 1.4;
+}
+
+.content ul,
+.content ol {
+  padding-left: var(--rs-space-5);
+  margin-bottom: var(--rs-space-5);
+}
+
+.content li {
+  font-size: var(--rs-font-size-regular);
+  margin: var(--rs-space-2) 0;
+}
+
+.content [role="tablist"] {
+  margin-bottom: var(--rs-space-3);
+}
+
+.content table {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+  margin-bottom: var(--rs-space-5);
+}

package/src/themes/default/Page.tsx

@@ -0,0 +1,21 @@
+'use client'
+
+import { Flex } from '@raystack/apsara'
+import type { ThemePageProps } from '@/types'
+import { Breadcrumbs } from '@/components/ui/breadcrumbs'
+import { Toc } from './Toc'
+import styles from './Page.module.css'
+
+export function Page({ page, tree }: ThemePageProps) {
+  return (
+    <Flex className={styles.page}>
+      <article className={styles.article}>
+        <Breadcrumbs slug={page.slug} tree={tree} />
+        <div className={styles.content}>
+          {page.content}
+        </div>
+      </article>
+      <Toc items={page.toc} />
+    </Flex>
+  )
+}

package/src/themes/default/Toc.module.css

@@ -0,0 +1,48 @@
+.toc {
+  width: 200px;
+  flex-shrink: 0;
+  position: sticky;
+  top: var(--rs-space-9);
+  max-height: calc(100vh - var(--rs-space-17));
+  overflow-y: auto;
+}
+
+.title {
+  display: block;
+  color: var(--rs-color-foreground-base-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-bottom: var(--rs-space-3);
+  font-size: var(--rs-font-size-mini);
+}
+
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  border-left: 1px solid var(--rs-color-border-base-primary);
+  padding-left: var(--rs-space-3);
+  margin-bottom: var(--rs-space-6);
+}
+
+.link {
+  color: var(--rs-color-foreground-base-tertiary);
+  text-decoration: none;
+  font-size: var(--rs-font-size-small);
+  line-height: 1.4;
+  padding: var(--rs-space-1) 0;
+  transition: color 0.15s ease;
+}
+
+.link:hover {
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.active {
+  color: var(--rs-color-foreground-base-primary);
+  font-weight: 500;
+}
+
+.nested {
+  padding-left: var(--rs-space-3);
+}

package/src/themes/default/Toc.tsx

@@ -0,0 +1,66 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+import { Text } from '@raystack/apsara'
+import type { TocItem } from '@/types'
+import styles from './Toc.module.css'
+
+interface TocProps {
+  items: TocItem[]
+}
+
+export function Toc({ items }: TocProps) {
+  const [activeId, setActiveId] = useState<string>('')
+
+  // Filter to only show h2 and h3 headings
+  const filteredItems = items.filter((item) => item.depth >= 2 && item.depth <= 3)
+
+  useEffect(() => {
+    const headingIds = filteredItems.map((item) => item.url.replace('#', ''))
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id)
+          }
+        })
+      },
+      // -80px top: offset for fixed header, -80% bottom: trigger when heading is in top 20% of viewport
+      { rootMargin: '-80px 0px -80% 0px' }
+    )
+
+    headingIds.forEach((id) => {
+      const element = document.getElementById(id)
+      if (element) observer.observe(element)
+    })
+
+    return () => observer.disconnect()
+  }, [filteredItems])
+
+  if (filteredItems.length === 0) return null
+
+  return (
+    <aside className={styles.toc}>
+      <Text size={1} weight="medium" className={styles.title}>
+        On this page
+      </Text>
+      <nav className={styles.nav}>
+        {filteredItems.map((item) => {
+          const id = item.url.replace('#', '')
+          const isActive = activeId === id
+          const isNested = item.depth > 2
+          return (
+            <a
+              key={item.url}
+              href={item.url}
+              className={`${styles.link} ${isActive ? styles.active : ''} ${isNested ? styles.nested : ''}`}
+            >
+              {item.title}
+            </a>
+          )
+        })}
+      </nav>
+    </aside>
+  )
+}

package/src/themes/default/font.ts

@@ -0,0 +1,6 @@
+import { Inter } from 'next/font/google'
+
+export const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap',
+})

package/src/themes/default/index.ts

@@ -0,0 +1,13 @@
+import { Layout } from './Layout'
+import { Page } from './Page'
+import { Toc } from './Toc'
+import { inter } from './font'
+import type { Theme } from '@/types'
+
+export const defaultTheme: Theme = {
+  Layout,
+  Page,
+  className: inter.className,
+}
+
+export { Layout, Page, Toc }