@raystack/chronicle 0.1.2

package/src/components/ui/search.tsx

@@ -0,0 +1,202 @@
+"use client";
+
+import { useState, useEffect, useCallback } from "react";
+import { useRouter } from "next/navigation";
+import { Button, Command, Dialog, Text } from "@raystack/apsara";
+import { cx } from "class-variance-authority";
+import { useDocsSearch } from "fumadocs-core/search/client";
+import type { SortedResult } from "fumadocs-core/search";
+import { DocumentIcon, HashtagIcon } from "@heroicons/react/24/outline";
+import { isMacOs } from "react-device-detect";
+import { MethodBadge } from "@/components/api/method-badge";
+import styles from "./search.module.css";
+
+function SearchShortcutKey({ className }: { className?: string }) {
+  const [key, setKey] = useState("⌘");
+
+  useEffect(() => {
+    setKey(isMacOs ? "⌘" : "Ctrl");
+  }, []);
+
+  return (
+    <kbd className={className} suppressHydrationWarning>
+      {key} K
+    </kbd>
+  );
+}
+
+interface SearchProps {
+  className?: string
+}
+
+export function Search({ className }: SearchProps) {
+  const [open, setOpen] = useState(false);
+  const router = useRouter();
+
+  const { search, setSearch, query } = useDocsSearch({
+    type: "fetch",
+    api: "/api/search",
+    delayMs: 100,
+    allowEmpty: true,
+  });
+
+  const onSelect = useCallback(
+    (url: string) => {
+      setOpen(false);
+      router.push(url);
+    },
+    [router],
+  );
+
+  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}>
+                            {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}>
+                              {stripMethod(result.content)}
+                            </Text>
+                            <Text className={styles.separator}>-</Text>
+                            <Text className={styles.pageText}>
+                              {getPageTitle(result.url)}
+                            </Text>
+                          </>
+                        ) : (
+                          <Text className={styles.pageText}>
+                            {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 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,36 @@
+import fs from 'fs'
+import path from '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...' },
+}
+
+export function loadConfig(): ChronicleConfig {
+  const dir = process.env.CHRONICLE_CONTENT_DIR ?? process.cwd()
+  const configPath = path.join(dir, CONFIG_FILE)
+
+  if (!fs.existsSync(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,
+  }
+}

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 'fs'
+import path from '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 function loadApiSpecs(apiConfigs: ApiConfig[]): ApiSpec[] {
+  const contentDir = process.env.CHRONICLE_CONTENT_DIR ?? process.cwd()
+  return apiConfigs.map((config) => loadApiSpec(config, contentDir))
+}
+
+export function loadApiSpec(config: ApiConfig, contentDir: string): ApiSpec {
+  const specPath = path.resolve(contentDir, config.spec)
+  const raw = fs.readFileSync(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
+}
+

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

@@ -0,0 +1,31 @@
+import { visit } from 'unist-util-visit'
+import type { Plugin } from 'unified'
+import type { Node } from 'unist'
+
+interface DirectiveNode extends Node {
+  name?: string
+  attributes?: Record<string, string>
+  children?: Node[]
+  data?: unknown
+  [key: string]: unknown
+}
+
+const remarkUnusedDirectives: Plugin = () => {
+  return (tree) => {
+    visit(tree, ['textDirective'], (node: DirectiveNode) => {
+      if (!node.data) {
+        const hasAttributes = node.attributes && Object.keys(node.attributes).length > 0
+        const hasChildren = node.children && node.children.length > 0
+        if (!hasAttributes && !hasChildren) {
+          const name = node.name
+          if (!name) return
+          Object.keys(node).forEach((key) => delete node[key])
+          node.type = 'text'
+          node.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'
+}