@raystack/chronicle 0.3.0 → 0.5.0

package/src/components/ui/search.tsx

@@ -1,21 +1,19 @@
-"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";
+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("⌘");
+  const [key, setKey] = useState('⌘');
 
   useEffect(() => {
-    setKey(isMacOs ? "⌘" : "Ctrl");
+    const isMac = navigator.platform?.toUpperCase().includes('MAC');
+    setKey(isMac ? '⌘' : 'Ctrl');
   }, []);
 
   return (
@@ -26,50 +24,50 @@ function SearchShortcutKey({ className }: { className?: string }) {
 }
 
 interface SearchProps {
-  className?: string
+  className?: string;
 }
 
 export function Search({ className }: SearchProps) {
   const [open, setOpen] = useState(false);
-  const router = useRouter();
+  const navigate = useNavigate();
 
   const { search, setSearch, query } = useDocsSearch({
-    type: "fetch",
-    api: "/api/search",
+    type: 'fetch',
+    api: '/api/search',
     delayMs: 100,
-    allowEmpty: true,
+    allowEmpty: true
   });
 
   const onSelect = useCallback(
     (url: string) => {
       setOpen(false);
-      router.push(url);
+      navigate(url);
     },
-    [router],
+    [navigate]
   );
 
   useEffect(() => {
     const down = (e: KeyboardEvent) => {
-      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
         e.preventDefault();
-        setOpen((open) => !open);
+        setOpen(open => !open);
       }
     };
 
-    document.addEventListener("keydown", down);
-    return () => document.removeEventListener("keydown", down);
+    document.addEventListener('keydown', down);
+    return () => document.removeEventListener('keydown', down);
   }, []);
 
   const results = deduplicateByUrl(
-    query.data === "empty" ? [] : (query.data ?? []),
+    query.data === 'empty' ? [] : (query.data ?? [])
   );
 
   return (
     <>
       <Button
-        variant="outline"
-        color="neutral"
-        size="small"
+        variant='outline'
+        color='neutral'
+        size='small'
         onClick={() => setOpen(true)}
         className={cx(styles.trigger, className)}
         trailingIcon={<SearchShortcutKey className={styles.kbd} />}
@@ -84,7 +82,7 @@ export function Search({ className }: SearchProps) {
           </Dialog.Title>
           <Command loop>
             <Command.Input
-              placeholder="Search"
+              placeholder='Search'
               value={search}
               onValueChange={setSearch}
               className={styles.input}
@@ -100,7 +98,7 @@ export function Search({ className }: SearchProps) {
               {!query.isLoading &&
                 search.length === 0 &&
                 results.length > 0 && (
-                  <Command.Group heading="Suggestions">
+                  <Command.Group heading='Suggestions'>
                     {results.slice(0, 8).map((result: SortedResult) => (
                       <Command.Item
                         key={result.id}
@@ -111,7 +109,9 @@ export function Search({ className }: SearchProps) {
                         <div className={styles.itemContent}>
                           {getResultIcon(result)}
                           <Text className={styles.pageText}>
-                            <HighlightedText html={stripMethod(result.content)} />
+                            <HighlightedText
+                              html={stripMethod(result.content)}
+                            />
                           </Text>
                         </div>
                       </Command.Item>
@@ -129,10 +129,12 @@ export function Search({ className }: SearchProps) {
                     <div className={styles.itemContent}>
                       {getResultIcon(result)}
                       <div className={styles.resultText}>
-                        {result.type === "heading" ? (
+                        {result.type === 'heading' ? (
                           <>
                             <Text className={styles.headingText}>
-                              <HighlightedText html={stripMethod(result.content)} />
+                              <HighlightedText
+                                html={stripMethod(result.content)}
+                              />
                             </Text>
                             <Text className={styles.separator}>-</Text>
                             <Text className={styles.pageText}>
@@ -141,7 +143,9 @@ export function Search({ className }: SearchProps) {
                           </>
                         ) : (
                           <Text className={styles.pageText}>
-                            <HighlightedText html={stripMethod(result.content)} />
+                            <HighlightedText
+                              html={stripMethod(result.content)}
+                            />
                           </Text>
                         )}
                       </div>
@@ -158,49 +162,57 @@ export function Search({ className }: SearchProps) {
 
 function deduplicateByUrl(results: SortedResult[]): SortedResult[] {
   const seen = new Set<string>();
-  return results.filter((r) => {
-    const base = r.url.split("#")[0];
+  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"]);
+const API_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
 
 function extractMethod(content: string): string | null {
-  const first = content.split(" ")[0];
+  const first = content.split(' ')[0];
   return API_METHODS.has(first) ? first : null;
 }
 
 function stripMethod(content: string): string {
-  const first = content.split(" ")[0];
+  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 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" ? (
+  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;
+  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 path = url.split('#')[0];
+  const segments = path.split('/').filter(Boolean);
   const lastSegment = segments[segments.length - 1];
-  if (!lastSegment) return "Home";
+  if (!lastSegment) return 'Home';
   return lastSegment
-    .split("-")
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(" ");
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
 }

package/src/lib/api-routes.ts

@@ -1,6 +1,6 @@
 import type { OpenAPIV3 } from 'openapi-types'
 import slugify from 'slugify'
-import type { PageTree, PageTreeItem } from '@/types/content'
+import type { Root, Node, Item, Folder } from 'fumadocs-core/page-tree'
 import type { ApiSpec } from './openapi'
 
 export function getSpecSlug(spec: ApiSpec): string {
@@ -56,16 +56,15 @@ export function findApiOperation(specs: ApiSpec[], slug: string[]): ApiRouteMatc
   return null
 }
 
-export function buildApiPageTree(specs: ApiSpec[]): PageTree {
-  const children: PageTreeItem[] = []
+export function buildApiPageTree(specs: ApiSpec[]): Root {
+  const children: Node[] = []
 
   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 opsByTag = new Map<string, Item[]>()
     const tagDisplayName = new Map<string, string>()
 
     for (const [, pathItem] of Object.entries(paths)) {
@@ -90,7 +89,6 @@ export function buildApiPageTree(specs: ApiSpec[]): PageTree {
       }
     }
 
-    // Use doc.tags display names where available
     for (const t of tags) {
       const key = t.name.toLowerCase()
       if (opsByTag.has(key)) {
@@ -98,7 +96,7 @@ export function buildApiPageTree(specs: ApiSpec[]): PageTree {
       }
     }
 
-    const tagFolders: PageTreeItem[] = Array.from(opsByTag.entries()).map(([key, ops]) => ({
+    const tagFolders: Folder[] = Array.from(opsByTag.entries()).map(([key, ops]) => ({
       type: 'folder' as const,
       name: tagDisplayName.get(key) ?? key,
       icon: 'rectangle-stack',
@@ -110,7 +108,7 @@ export function buildApiPageTree(specs: ApiSpec[]): PageTree {
         type: 'folder',
         name: spec.name,
         children: tagFolders,
-      })
+      } as Folder)
     } else {
       children.push(...tagFolders)
     }

package/src/lib/config.ts

@@ -1,56 +1,32 @@
-import fs from 'fs'
-import path from 'path'
-import { parse } from 'yaml'
-import type { ChronicleConfig } from '@/types'
-
-const CONFIG_FILE = 'chronicle.yaml'
+import { parse } from 'yaml';
+import type { ChronicleConfig } from '@/types';
 
 const defaultConfig: ChronicleConfig = {
   title: 'Documentation',
   theme: { name: 'default' },
-  search: { enabled: true, placeholder: 'Search...' },
-}
-
-function resolveConfigPath(): string | null {
-  // Check project root via env var
-  const projectRoot = process.env.CHRONICLE_PROJECT_ROOT
-  if (projectRoot) {
-    const rootPath = path.join(projectRoot, CONFIG_FILE)
-    if (fs.existsSync(rootPath)) return rootPath
-  }
-  // Check cwd
-  const cwdPath = path.join(process.cwd(), CONFIG_FILE)
-  if (fs.existsSync(cwdPath)) return cwdPath
-  // Check content dir
-  const contentDir = process.env.CHRONICLE_CONTENT_DIR
-  if (contentDir) {
-    const contentPath = path.join(contentDir, CONFIG_FILE)
-    if (fs.existsSync(contentPath)) return contentPath
-  }
-  return null
-}
+  search: { enabled: true, placeholder: 'Search...' }
+};
 
 export function loadConfig(): ChronicleConfig {
-  const configPath = resolveConfigPath()
+  const raw = typeof __CHRONICLE_CONFIG_RAW__ !== 'undefined' ? __CHRONICLE_CONFIG_RAW__ : null;
 
-  if (!configPath) {
-    return defaultConfig
+  if (!raw) {
+    return defaultConfig;
   }
 
-  const raw = fs.readFileSync(configPath, 'utf-8')
-  const userConfig = parse(raw) as Partial<ChronicleConfig>
+  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 },
+      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 },
-  }
-}
+    analytics: { enabled: false, ...userConfig.analytics }
+  };
+}

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

@@ -1,5 +1,5 @@
-import fs from 'fs'
-import path from 'path'
+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'
@@ -17,14 +17,14 @@ export interface ApiSpec {
 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 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 function loadApiSpec(config: ApiConfig, contentDir: string): ApiSpec {
-  const specPath = path.resolve(contentDir, config.spec)
-  const raw = fs.readFileSync(specPath, 'utf-8')
+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
 

package/src/lib/page-context.tsx

@@ -0,0 +1,111 @@
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useState
+} from 'react';
+import { useLocation } from 'react-router';
+import type { ApiSpec } from '@/lib/openapi';
+import type { ChronicleConfig, Frontmatter, Root, TableOfContents } from '@/types';
+
+export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
+
+interface PageData {
+  slug: string[];
+  frontmatter: Frontmatter;
+  content: ReactNode;
+  toc: TableOfContents;
+}
+
+interface PageContextValue {
+  config: ChronicleConfig;
+  tree: Root;
+  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: [] } as Root,
+      page: null,
+      apiSpecs: []
+    };
+  }
+  return ctx;
+}
+
+interface PageProviderProps {
+  initialConfig: ChronicleConfig;
+  initialTree: Root;
+  initialPage: PageData | null;
+  initialApiSpecs: ApiSpec[];
+  loadMdx: MdxLoader;
+  children: ReactNode;
+}
+
+export function PageProvider({
+  initialConfig,
+  initialTree,
+  initialPage,
+  initialApiSpecs,
+  loadMdx,
+  children
+}: PageProviderProps) {
+  const { pathname } = useLocation();
+  const [tree] = useState<Root>(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; originalPath?: string }) => {
+        if (cancelled.current) return;
+        const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
+        if (cancelled.current) return;
+        setPage({ slug, frontmatter: data.frontmatter, content, toc });
+      })
+      .catch(() => {});
+
+    return () => { cancelled.current = true; };
+  }, [pathname]);
+
+  return (
+    <PageContext.Provider
+      value={{ config: initialConfig, tree, page, apiSpecs }}
+    >
+      {children}
+    </PageContext.Provider>
+  );
+}

package/src/lib/remark-strip-md-extensions.ts

@@ -0,0 +1,14 @@
+import { visit } from 'unist-util-visit'
+import type { Plugin } from 'unified'
+
+const remarkStripMdExtensions: Plugin = () => {
+  return (tree) => {
+    visit(tree, 'link', (node: any) => {
+      if (!node.url) return
+      if (node.url.startsWith('http://') || node.url.startsWith('https://')) return
+      node.url = node.url.replace(/\.mdx?(#|$)/, '$1')
+    })
+  }
+}
+
+export default remarkStripMdExtensions