@raystack/chronicle 0.1.0-canary.111b55a → 0.1.0-canary.1e5fdae

package/src/cli/utils/resolve.ts

@@ -1,6 +1,10 @@
-import path from 'path'
-import { fileURLToPath } from 'url'
+import path from 'path';
+import { fileURLToPath } from 'url';
 
 // After bundling: dist/cli/index.js → ../.. = package root
 // After install: node_modules/@raystack/chronicle/dist/cli/index.js → ../.. = package root
-export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+export const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..'
+);

package/src/cli/utils/scaffold.ts

@@ -1,20 +1,18 @@
-import fs from 'fs'
-import path from 'path'
-import { PACKAGE_ROOT } from './resolve'
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { PACKAGE_ROOT } from './resolve';
 
-export function detectPackageManager(): string {
-  if (process.env.npm_config_user_agent) {
-    return process.env.npm_config_user_agent.split('/')[0]
+export async function linkContent(contentDir: string): Promise<void> {
+  const linkPath = path.join(PACKAGE_ROOT, '.content');
+  const target = path.resolve(contentDir);
+
+  try {
+    const existing = await fs.readlink(linkPath);
+    if (existing === target) return;
+    await fs.unlink(linkPath);
+  } catch {
+    // link doesn't exist
   }
-  const cwd = process.cwd()
-  if (fs.existsSync(path.join(cwd, 'bun.lock')) || fs.existsSync(path.join(cwd, 'bun.lockb'))) return 'bun'
-  if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm'
-  if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn'
-  return 'npm'
-}
 
-export function getChronicleVersion(): string {
-  const pkgPath = path.join(PACKAGE_ROOT, 'package.json')
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
-  return pkg.version
+  await fs.symlink(target, linkPath);
 }

package/src/components/mdx/details.module.css

@@ -1,6 +1,4 @@
 .details {
-  border: 1px solid var(--rs-color-border-base-primary);
-  border-radius: var(--rs-radius-2);
   margin: var(--rs-space-5) 0;
 }
 

package/src/components/mdx/image.tsx

@@ -1,24 +1,9 @@
-'use client'
+import type { ComponentProps } from 'react';
 
-import type { ComponentProps } from 'react'
+type ImageProps = ComponentProps<'img'>;
 
-type ImageProps = Omit<ComponentProps<'img'>, 'src'> & {
-  src?: string
-  width?: number | string
-  height?: number | string
-}
-
-export function Image({ src, alt, width, height, ...props }: ImageProps) {
-  if (!src || typeof src !== 'string') return null
+export function Image({ src, alt, ...props }: ImageProps) {
+  if (!src) return null;
 
-  return (
-    <img
-      src={src}
-      alt={alt ?? ''}
-      width={width}
-      height={height}
-      loading="lazy"
-      {...props}
-    />
-  )
+  return <img src={src} alt={alt ?? ''} loading='lazy' {...props} />;
 }

package/src/components/mdx/index.tsx

@@ -1,6 +1,6 @@
 import type { MDXComponents } from 'mdx/types'
 import { Image } from './image'
-import { MdxLink } from './link'
+import { Link } from './link'
 import { MdxTable, MdxThead, MdxTbody, MdxTr, MdxTh, MdxTd } from './table'
 import { MdxPre, MdxCode } from './code'
 import { MdxDetails, MdxSummary } from './details'
@@ -8,11 +8,25 @@ import { Mermaid } from './mermaid'
 import { MdxParagraph } from './paragraph'
 import { CalloutContainer, CalloutTitle, CalloutDescription, MdxBlockquote } from '@/components/common/callout'
 import { Tabs } from '@raystack/apsara'
+import { type ComponentProps, useEffect, useState } from 'react'
+
+function ClientOnly({ children }: { children: React.ReactNode }) {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => setMounted(true), [])
+  return mounted ? <>{children}</> : null
+}
+
+function MdxTabs(props: ComponentProps<typeof Tabs>) {
+  return <ClientOnly><Tabs {...props} /></ClientOnly>
+}
+MdxTabs.List = Tabs.List
+MdxTabs.Trigger = Tabs.Trigger
+MdxTabs.Content = Tabs.Content
 
 export const mdxComponents: MDXComponents = {
   p: MdxParagraph,
   img: Image,
-  a: MdxLink,
+  a: Link,
   table: MdxTable,
   thead: MdxThead,
   tbody: MdxTbody,
@@ -27,9 +41,9 @@ export const mdxComponents: MDXComponents = {
   Callout: CalloutContainer,
   CalloutTitle,
   CalloutDescription,
-  Tabs,
+  Tabs: MdxTabs,
   Mermaid,
 }
 
 export { Image } from './image'
-export { MdxLink } from './link'
+export { Link } from './link'

package/src/components/mdx/link.tsx

@@ -1,37 +1,41 @@
-'use client'
+import { Link as ApsaraLink } from '@raystack/apsara';
+import type { ComponentProps } from 'react';
+import { Link as RouterLink } from 'react-router';
 
-import { Link } from 'react-router-dom'
-import type { ComponentProps } from 'react'
+type LinkProps = ComponentProps<'a'>;
 
-type LinkProps = ComponentProps<'a'>
-
-export function MdxLink({ href, children, ...props }: LinkProps) {
+export function Link({ href, children, ...props }: LinkProps) {
   if (!href) {
-    return <span {...props}>{children}</span>
+    return <span {...props}>{children}</span>;
   }
 
-  const isExternal = href.startsWith('http://') || href.startsWith('https://')
-  const isAnchor = href.startsWith('#')
+  const isExternal = href.startsWith('http://') || href.startsWith('https://');
+  const isAnchor = href.startsWith('#');
 
-  if (isExternal) {
+  if (isAnchor) {
     return (
-      <a href={href} target="_blank" rel="noopener noreferrer" {...props}>
+      <ApsaraLink href={href} {...props}>
         {children}
-      </a>
-    )
+      </ApsaraLink>
+    );
   }
 
-  if (isAnchor) {
+  if (isExternal) {
     return (
-      <a href={href} {...props}>
+      <ApsaraLink
+        href={href}
+        target='_blank'
+        rel='noopener noreferrer'
+        {...props}
+      >
         {children}
-      </a>
-    )
+      </ApsaraLink>
+    );
   }
 
   return (
-    <Link to={href} className={props.className}>
+    <RouterLink to={href} className={props.className}>
       {children}
-    </Link>
-  )
+    </RouterLink>
+  );
 }

package/src/components/ui/breadcrumbs.tsx

@@ -1,53 +1,19 @@
 'use client'
 
 import { Breadcrumb } from '@raystack/apsara'
-import type { PageTree, PageTreeItem } from '@/types'
+import { getBreadcrumbItems } from 'fumadocs-core/breadcrumb'
+import type { Root } from 'fumadocs-core/page-tree'
 
 interface BreadcrumbsProps {
   slug: string[]
-  tree: PageTree
-}
-
-function findInTree(items: PageTreeItem[], targetPath: string): PageTreeItem | undefined {
-  for (const item of items) {
-    const itemUrl = item.url || `/${item.name.toLowerCase().replace(/\s+/g, '-')}`
-    if (itemUrl === targetPath || itemUrl === `/${targetPath}`) {
-      return item
-    }
-    if (item.children) {
-      const found = findInTree(item.children, targetPath)
-      if (found) return found
-    }
-  }
-  return undefined
-}
-
-function getFirstPageUrl(item: PageTreeItem): string | undefined {
-  if (item.type === 'page' && item.url) {
-    return item.url
-  }
-  if (item.children) {
-    for (const child of item.children) {
-      const url = getFirstPageUrl(child)
-      if (url) return url
-    }
-  }
-  return undefined
+  tree: Root
 }
 
 export function Breadcrumbs({ slug, tree }: BreadcrumbsProps) {
-  const items: { label: string; href: string }[] = []
+  const url = slug.length === 0 ? '/' : `/${slug.join('/')}`
+  const items = getBreadcrumbItems(url, tree, { includePage: true })
 
-  for (let i = 0; i < slug.length; i++) {
-    const currentPath = `/${slug.slice(0, i + 1).join('/')}`
-    const node = findInTree(tree.children, currentPath)
-    const href = node?.url || (node && getFirstPageUrl(node)) || currentPath
-    const label = node?.name ?? slug[i]
-    items.push({
-      label: label.charAt(0).toUpperCase() + label.slice(1),
-      href,
-    })
-  }
+  if (items.length === 0) return null
 
   return (
     <Breadcrumb size="small">
@@ -55,10 +21,10 @@ export function Breadcrumbs({ slug, tree }: BreadcrumbsProps) {
         const breadcrumbItem = (
           <Breadcrumb.Item
             key={`item-${index}`}
-            href={item.href}
+            href={item.url}
             current={index === items.length - 1}
           >
-            {item.label}
+            {item.name}
           </Breadcrumb.Item>
         )
         if (index === 0) return [breadcrumbItem]

package/src/components/ui/footer.tsx

@@ -1,5 +1,4 @@
-import { Link } from "react-router-dom";
-import { Flex, Text } from "@raystack/apsara";
+import { Flex, Link, Text } from "@raystack/apsara";
 import type { FooterConfig } from "@/types";
 import styles from "./footer.module.css";
 
@@ -19,7 +18,7 @@ export function Footer({ config }: FooterProps) {
         {config?.links && config.links.length > 0 && (
           <Flex gap="medium" className={styles.links}>
             {config.links.map((link) => (
-              <Link key={link.href} to={link.href} className={styles.link}>
+              <Link key={link.href} href={link.href} className={styles.link}>
                 {link.label}
               </Link>
             ))}

package/src/components/ui/search.tsx

@@ -1,50 +1,19 @@
-"use client";
-
-import { useState, useEffect, useCallback, useRef } from "react";
-import { useNavigate } from "react-router-dom";
-import { Button, Command, Dialog, Text } from "@raystack/apsara";
-import { cx } from "class-variance-authority";
-import { DocumentIcon, HashtagIcon } from "@heroicons/react/24/outline";
-import { MethodBadge } from "@/components/api/method-badge";
-import styles from "./search.module.css";
-
-interface SearchResult {
-  id: string;
-  url: string;
-  type: "page" | "api";
-  content: string;
-}
-
-function useSearch(query: string) {
-  const [results, setResults] = useState<SearchResult[]>([]);
-  const [isLoading, setIsLoading] = useState(false);
-  const timerRef = useRef<ReturnType<typeof setTimeout>>();
-
-  useEffect(() => {
-    clearTimeout(timerRef.current);
-    timerRef.current = setTimeout(async () => {
-      setIsLoading(true);
-      try {
-        const params = new URLSearchParams();
-        if (query) params.set("query", query);
-        const res = await fetch(`/api/search?${params}`);
-        setResults(await res.json());
-      } catch {
-        setResults([]);
-      }
-      setIsLoading(false);
-    }, 100);
-    return () => clearTimeout(timerRef.current);
-  }, [query]);
-
-  return { results, isLoading };
-}
+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("\u2318");
+  const [key, setKey] = useState('⌘');
 
   useEffect(() => {
-    setKey(navigator.platform?.startsWith("Mac") ? "\u2318" : "Ctrl");
+    const isMac = navigator.platform?.toUpperCase().includes('MAC');
+    setKey(isMac ? '⌘' : 'Ctrl');
   }, []);
 
   return (
@@ -61,35 +30,44 @@ interface SearchProps {
 export function Search({ className }: SearchProps) {
   const [open, setOpen] = useState(false);
   const navigate = useNavigate();
-  const [search, setSearch] = useState("");
-  const { results, isLoading } = useSearch(search);
+
+  const { search, setSearch, query } = useDocsSearch({
+    type: 'fetch',
+    api: '/api/search',
+    delayMs: 100,
+    allowEmpty: true
+  });
 
   const onSelect = useCallback(
     (url: string) => {
       setOpen(false);
       navigate(url);
     },
-    [navigate],
+    [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 ?? [])
+  );
+
   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} />}
@@ -104,24 +82,24 @@ export function Search({ className }: SearchProps) {
           </Dialog.Title>
           <Command loop>
             <Command.Input
-              placeholder="Search"
+              placeholder='Search'
               value={search}
               onValueChange={setSearch}
               className={styles.input}
             />
 
             <Command.List className={styles.list}>
-              {isLoading && <Command.Empty>Loading...</Command.Empty>}
-              {!isLoading &&
+              {query.isLoading && <Command.Empty>Loading...</Command.Empty>}
+              {!query.isLoading &&
                 search.length > 0 &&
                 results.length === 0 && (
                   <Command.Empty>No results found.</Command.Empty>
                 )}
-              {!isLoading &&
+              {!query.isLoading &&
                 search.length === 0 &&
                 results.length > 0 && (
-                  <Command.Group heading="Suggestions">
-                    {results.slice(0, 8).map((result) => (
+                  <Command.Group heading='Suggestions'>
+                    {results.slice(0, 8).map((result: SortedResult) => (
                       <Command.Item
                         key={result.id}
                         value={result.id}
@@ -131,7 +109,9 @@ export function Search({ className }: SearchProps) {
                         <div className={styles.itemContent}>
                           {getResultIcon(result)}
                           <Text className={styles.pageText}>
-                            {result.content}
+                            <HighlightedText
+                              html={stripMethod(result.content)}
+                            />
                           </Text>
                         </div>
                       </Command.Item>
@@ -139,7 +119,7 @@ export function Search({ className }: SearchProps) {
                   </Command.Group>
                 )}
               {search.length > 0 &&
-                results.map((result) => (
+                results.map((result: SortedResult) => (
                   <Command.Item
                     key={result.id}
                     value={result.id}
@@ -148,9 +128,27 @@ export function Search({ className }: SearchProps) {
                   >
                     <div className={styles.itemContent}>
                       {getResultIcon(result)}
-                      <Text className={styles.pageText}>
-                        {result.content}
-                      </Text>
+                      <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>
                 ))}
@@ -162,12 +160,59 @@ export function Search({ className }: SearchProps) {
   );
 }
 
-function getResultIcon(result: SearchResult): React.ReactNode {
-  if (result.type === "api") {
-    const method = result.content.split(" ")[0];
-    return ["GET", "POST", "PUT", "DELETE", "PATCH"].includes(method)
-      ? <MethodBadge method={method} size="micro" />
-      : null;
+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} />
+    );
   }
-  return <DocumentIcon 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

@@ -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)
     }