@raystack/chronicle 0.1.0-canary.0efaef0

package/src/components/ui/search.tsx

@@ -0,0 +1,218 @@
+import { DocumentIcon, HashtagIcon } from '@heroicons/react/24/outline';
+import { Button, Command, Dialog, Text } from '@raystack/apsara';
+import { cx } from 'class-variance-authority';
+import type { SortedResult } from 'fumadocs-core/search';
+import { useDocsSearch } from 'fumadocs-core/search/client';
+import { useCallback, useEffect, useState } from 'react';
+import { useNavigate } from 'react-router';
+import { MethodBadge } from '@/components/api/method-badge';
+import styles from './search.module.css';
+
+function SearchShortcutKey({ className }: { className?: string }) {
+  const [key, setKey] = useState('⌘');
+
+  useEffect(() => {
+    const isMac = navigator.platform?.toUpperCase().includes('MAC');
+    setKey(isMac ? '⌘' : 'Ctrl');
+  }, []);
+
+  return (
+    <kbd className={className} suppressHydrationWarning>
+      {key} K
+    </kbd>
+  );
+}
+
+interface SearchProps {
+  className?: string;
+}
+
+export function Search({ className }: SearchProps) {
+  const [open, setOpen] = useState(false);
+  const navigate = useNavigate();
+
+  const { search, setSearch, query } = useDocsSearch({
+    type: 'fetch',
+    api: '/api/search',
+    delayMs: 100,
+    allowEmpty: true
+  });
+
+  const onSelect = useCallback(
+    (url: string) => {
+      setOpen(false);
+      navigate(url);
+    },
+    [navigate]
+  );
+
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen(open => !open);
+      }
+    };
+
+    document.addEventListener('keydown', down);
+    return () => document.removeEventListener('keydown', down);
+  }, []);
+
+  const results = deduplicateByUrl(
+    query.data === 'empty' ? [] : (query.data ?? [])
+  );
+
+  return (
+    <>
+      <Button
+        variant='outline'
+        color='neutral'
+        size='small'
+        onClick={() => setOpen(true)}
+        className={cx(styles.trigger, className)}
+        trailingIcon={<SearchShortcutKey className={styles.kbd} />}
+      >
+        Search...
+      </Button>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <Dialog.Content className={styles.dialogContent}>
+          <Dialog.Title className={styles.visuallyHidden}>
+            Search documentation
+          </Dialog.Title>
+          <Command loop>
+            <Command.Input
+              placeholder='Search'
+              value={search}
+              onValueChange={setSearch}
+              className={styles.input}
+            />
+
+            <Command.List className={styles.list}>
+              {query.isLoading && <Command.Empty>Loading...</Command.Empty>}
+              {!query.isLoading &&
+                search.length > 0 &&
+                results.length === 0 && (
+                  <Command.Empty>No results found.</Command.Empty>
+                )}
+              {!query.isLoading &&
+                search.length === 0 &&
+                results.length > 0 && (
+                  <Command.Group heading='Suggestions'>
+                    {results.slice(0, 8).map((result: SortedResult) => (
+                      <Command.Item
+                        key={result.id}
+                        value={result.id}
+                        onSelect={() => onSelect(result.url)}
+                        className={styles.item}
+                      >
+                        <div className={styles.itemContent}>
+                          {getResultIcon(result)}
+                          <Text className={styles.pageText}>
+                            <HighlightedText
+                              html={stripMethod(result.content)}
+                            />
+                          </Text>
+                        </div>
+                      </Command.Item>
+                    ))}
+                  </Command.Group>
+                )}
+              {search.length > 0 &&
+                results.map((result: SortedResult) => (
+                  <Command.Item
+                    key={result.id}
+                    value={result.id}
+                    onSelect={() => onSelect(result.url)}
+                    className={styles.item}
+                  >
+                    <div className={styles.itemContent}>
+                      {getResultIcon(result)}
+                      <div className={styles.resultText}>
+                        {result.type === 'heading' ? (
+                          <>
+                            <Text className={styles.headingText}>
+                              <HighlightedText
+                                html={stripMethod(result.content)}
+                              />
+                            </Text>
+                            <Text className={styles.separator}>-</Text>
+                            <Text className={styles.pageText}>
+                              {getPageTitle(result.url)}
+                            </Text>
+                          </>
+                        ) : (
+                          <Text className={styles.pageText}>
+                            <HighlightedText
+                              html={stripMethod(result.content)}
+                            />
+                          </Text>
+                        )}
+                      </div>
+                    </div>
+                  </Command.Item>
+                ))}
+            </Command.List>
+          </Command>
+        </Dialog.Content>
+      </Dialog>
+    </>
+  );
+}
+
+function deduplicateByUrl(results: SortedResult[]): SortedResult[] {
+  const seen = new Set<string>();
+  return results.filter(r => {
+    const base = r.url.split('#')[0];
+    if (seen.has(base)) return false;
+    seen.add(base);
+    return true;
+  });
+}
+
+const API_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
+
+function extractMethod(content: string): string | null {
+  const first = content.split(' ')[0];
+  return API_METHODS.has(first) ? first : null;
+}
+
+function stripMethod(content: string): string {
+  const first = content.split(' ')[0];
+  return API_METHODS.has(first) ? content.slice(first.length + 1) : content;
+}
+
+function HighlightedText({
+  html,
+  className
+}: {
+  html: string;
+  className?: string;
+}) {
+  return (
+    <span className={className} dangerouslySetInnerHTML={{ __html: html }} />
+  );
+}
+
+function getResultIcon(result: SortedResult): React.ReactNode {
+  if (!result.url.startsWith('/apis/')) {
+    return result.type === 'page' ? (
+      <DocumentIcon className={styles.icon} />
+    ) : (
+      <HashtagIcon className={styles.icon} />
+    );
+  }
+  const method = extractMethod(result.content);
+  return method ? <MethodBadge method={method} size='micro' /> : null;
+}
+
+function getPageTitle(url: string): string {
+  const path = url.split('#')[0];
+  const segments = path.split('/').filter(Boolean);
+  const lastSegment = segments[segments.length - 1];
+  if (!lastSegment) return 'Home';
+  return lastSegment
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}

package/src/lib/api-routes.ts

@@ -0,0 +1,120 @@
+import type { OpenAPIV3 } from 'openapi-types'
+import slugify from 'slugify'
+import type { PageTree, PageTreeItem } from '@/types/content'
+import type { ApiSpec } from './openapi'
+
+export function getSpecSlug(spec: ApiSpec): string {
+  return slugify(spec.name, { lower: true, strict: true })
+}
+
+
+export function buildApiRoutes(specs: ApiSpec[]): { slug: string[] }[] {
+  const routes: { slug: string[] }[] = []
+
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec)
+    const paths = spec.document.paths ?? {}
+
+    for (const [, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method]
+        if (!op?.operationId) continue
+        routes.push({ slug: [specSlug, encodeURIComponent(op.operationId)] })
+      }
+    }
+  }
+
+  return routes
+}
+
+export interface ApiRouteMatch {
+  spec: ApiSpec
+  operation: OpenAPIV3.OperationObject
+  method: string
+  path: string
+}
+
+export function findApiOperation(specs: ApiSpec[], slug: string[]): ApiRouteMatch | null {
+  if (slug.length !== 2) return null
+  const [specSlug, operationId] = slug
+
+  const spec = specs.find((s) => getSpecSlug(s) === specSlug)
+  if (!spec) return null
+
+  const paths = spec.document.paths ?? {}
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem) continue
+    for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+      const op = pathItem[method]
+      if (op?.operationId && encodeURIComponent(op.operationId) === operationId) {
+        return { spec, operation: op, method: method.toUpperCase(), path: pathStr }
+      }
+    }
+  }
+
+  return null
+}
+
+export function buildApiPageTree(specs: ApiSpec[]): PageTree {
+  const children: PageTreeItem[] = []
+
+  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 tagDisplayName = new Map<string, string>()
+
+    for (const [, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method]
+        if (!op?.operationId) continue
+
+        const rawTag = op.tags?.[0] ?? 'default'
+        const tagKey = rawTag.toLowerCase()
+        if (!opsByTag.has(tagKey)) {
+          opsByTag.set(tagKey, [])
+          tagDisplayName.set(tagKey, rawTag.charAt(0).toUpperCase() + rawTag.slice(1))
+        }
+
+        opsByTag.get(tagKey)!.push({
+          type: 'page',
+          name: op.summary ?? op.operationId,
+          url: `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`,
+          icon: `method-${method}`,
+        })
+      }
+    }
+
+    // Use doc.tags display names where available
+    for (const t of tags) {
+      const key = t.name.toLowerCase()
+      if (opsByTag.has(key)) {
+        tagDisplayName.set(key, t.name.charAt(0).toUpperCase() + t.name.slice(1))
+      }
+    }
+
+    const tagFolders: PageTreeItem[] = Array.from(opsByTag.entries()).map(([key, ops]) => ({
+      type: 'folder' as const,
+      name: tagDisplayName.get(key) ?? key,
+      icon: 'rectangle-stack',
+      children: ops,
+    }))
+
+    if (specs.length > 1) {
+      children.push({
+        type: 'folder',
+        name: spec.name,
+        children: tagFolders,
+      })
+    } else {
+      children.push(...tagFolders)
+    }
+  }
+
+  return { name: 'API Reference', children }
+}

package/src/lib/config.ts

@@ -0,0 +1,58 @@
+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 defaultConfig: ChronicleConfig = {
+  title: 'Documentation',
+  theme: { name: 'default' },
+  search: { enabled: true, placeholder: 'Search...' }
+};
+
+function resolveConfigPath(): string | null {
+  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;
+  }
+
+  return null;
+}
+
+export function loadConfig(): ChronicleConfig {
+  const configPath = resolveConfigPath();
+
+  if (!configPath) {
+    return defaultConfig;
+  }
+
+  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 }
+    },
+    search: { ...defaultConfig.search, ...userConfig.search },
+    footer: userConfig.footer,
+    api: userConfig.api,
+    llms: { enabled: false, ...userConfig.llms },
+    analytics: { enabled: false, ...userConfig.analytics }
+  };
+}

package/src/lib/get-llm-text.ts

@@ -0,0 +1,10 @@
+import { source } from '@/lib/source'
+import type { InferPageType } from 'fumadocs-core/source'
+
+export async function getLLMText(page: InferPageType<typeof source>) {
+  const processed = await page.data.getText('processed')
+
+  return `# ${page.data.title} (${page.url})
+
+${processed}`
+}

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/index.ts

@@ -0,0 +1,2 @@
+export * from './config'
+export * from './source'

package/src/lib/openapi.ts

@@ -0,0 +1,188 @@
+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'
+
+type JsonObject = Record<string, unknown>
+
+export interface ApiSpec {
+  name: string
+  basePath: string
+  server: ApiServerConfig
+  auth?: ApiAuthConfig
+  document: OpenAPIV3.Document
+}
+
+export type { SchemaField } from './schema'
+export { flattenSchema } from './schema'
+
+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 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
+
+  let v3Doc: OpenAPIV3.Document
+
+  if ('swagger' in doc && doc.swagger === '2.0') {
+    v3Doc = convertV2toV3(doc as OpenAPIV2.Document)
+  } else if ('openapi' in doc && doc.openapi.startsWith('3.')) {
+    v3Doc = resolveDocument(doc as OpenAPIV3.Document)
+  } else {
+    throw new Error(`Unsupported spec version in ${config.spec}`)
+  }
+
+  return {
+    name: config.name,
+    basePath: config.basePath,
+    server: config.server,
+    auth: config.auth,
+    document: v3Doc,
+  }
+}
+
+// --- $ref resolution ---
+
+function resolveRef(ref: string, root: JsonObject): JsonObject {
+  const parts = ref.replace(/^#\//, '').split('/')
+  let current: unknown = root
+  for (const part of parts) {
+    if (current && typeof current === 'object' && !Array.isArray(current)) {
+      current = (current as JsonObject)[part]
+    } else {
+      throw new Error(`Cannot resolve $ref: ${ref}`)
+    }
+  }
+  return current as JsonObject
+}
+
+function deepResolveRefs(
+  obj: unknown,
+  root: JsonObject,
+  stack = new Set<string>(),
+  cache = new Map<string, JsonObject>(),
+): unknown {
+  if (obj === null || obj === undefined || typeof obj !== 'object') return obj
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => deepResolveRefs(item, root, stack, cache))
+  }
+
+  const record = obj as JsonObject
+
+  if (typeof record.$ref === 'string') {
+    const ref = record.$ref
+    if (cache.has(ref)) return cache.get(ref) as JsonObject
+    if (stack.has(ref)) return { type: 'object', description: '[circular]' }
+    stack.add(ref)
+    const resolved = deepResolveRefs(resolveRef(ref, root), root, stack, cache) as JsonObject
+    stack.delete(ref)
+    cache.set(ref, resolved)
+    return resolved
+  }
+
+  const result: JsonObject = {}
+  for (const [key, value] of Object.entries(record)) {
+    result[key] = deepResolveRefs(value, root, stack, cache)
+  }
+  return result
+}
+
+function resolveDocument(doc: OpenAPIV3.Document): OpenAPIV3.Document {
+  const root = doc as unknown as JsonObject
+  return deepResolveRefs(doc, root) as unknown as OpenAPIV3.Document
+}
+
+// --- V2 → V3 conversion ---
+
+function convertV2toV3(doc: OpenAPIV2.Document): OpenAPIV3.Document {
+  const root = doc as unknown as JsonObject
+  const resolved = deepResolveRefs(doc, root) as unknown as OpenAPIV2.Document
+
+  const v3Paths: OpenAPIV3.PathsObject = {}
+
+  for (const [pathStr, pathItem] of Object.entries(resolved.paths ?? {})) {
+    if (!pathItem) continue
+    const v3PathItem: OpenAPIV3.PathItemObject = {}
+
+    for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+      const op = (pathItem as Record<string, unknown>)[method] as OpenAPIV2.OperationObject | undefined
+      if (!op) continue
+      v3PathItem[method] = convertV2Operation(op)
+    }
+
+    v3Paths[pathStr] = v3PathItem
+  }
+
+  return {
+    openapi: '3.0.0',
+    info: resolved.info as unknown as OpenAPIV3.InfoObject,
+    paths: v3Paths,
+    tags: (resolved.tags ?? []) as unknown as OpenAPIV3.TagObject[],
+  }
+}
+
+function convertV2Operation(op: OpenAPIV2.OperationObject): OpenAPIV3.OperationObject {
+  const params = (op.parameters ?? []) as OpenAPIV2.Parameter[]
+
+  const v3Params: OpenAPIV3.ParameterObject[] = params
+    .filter((p) => p.in !== 'body')
+    .map((p) => ({
+      name: p.name,
+      in: p.in as 'path' | 'query' | 'header' | 'cookie',
+      required: p.required ?? false,
+      description: p.description,
+      schema: { type: ((p as JsonObject).type as string) ?? 'string', format: (p as JsonObject).format as string | undefined } as OpenAPIV3.SchemaObject,
+    }))
+
+  const bodyParam = params.find((p) => p.in === 'body') as JsonObject | undefined
+  let requestBody: OpenAPIV3.RequestBodyObject | undefined
+  if (bodyParam?.schema) {
+    requestBody = {
+      required: (bodyParam.required as boolean) ?? false,
+      content: {
+        'application/json': {
+          schema: bodyParam.schema as OpenAPIV3.SchemaObject,
+        },
+      },
+    }
+  }
+
+  const v3Responses: OpenAPIV3.ResponsesObject = {}
+  for (const [status, resp] of Object.entries(op.responses ?? {})) {
+    const v2Resp = resp as OpenAPIV2.ResponseObject
+    const v3Resp: OpenAPIV3.ResponseObject = {
+      description: v2Resp.description ?? '',
+    }
+    if ((v2Resp as unknown as JsonObject).schema) {
+      v3Resp.content = {
+        'application/json': {
+          schema: (v2Resp as unknown as JsonObject).schema as OpenAPIV3.SchemaObject,
+        },
+      }
+    }
+    v3Responses[status] = v3Resp
+  }
+
+  const result: OpenAPIV3.OperationObject = {
+    operationId: op.operationId,
+    summary: op.summary,
+    description: op.description,
+    tags: op.tags,
+    parameters: v3Params,
+    responses: v3Responses,
+  }
+
+  if (requestBody) {
+    result.requestBody = requestBody
+  }
+
+  return result
+}
+