@raystack/chronicle 0.1.0-canary.323385a → 0.1.0-canary.3e58cd9

package/src/cli/utils/resolve.ts

@@ -1,4 +1,10 @@
-import path from 'path'
-import { fileURLToPath } from 'url'
+import path from 'path';
+import { fileURLToPath } from 'url';
 
-export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.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)),
+  '..',
+  '..'
+);

package/src/cli/utils/scaffold.ts

@@ -1,131 +1,18 @@
-import { execSync } from 'child_process'
-import { createRequire } from 'module'
-import fs from 'fs'
-import path from 'path'
-import chalk from 'chalk'
-import { PACKAGE_ROOT } from './resolve'
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { PACKAGE_ROOT } from './resolve';
 
-const COPY_FILES = ['src', 'source.config.ts', 'tsconfig.json']
+export async function linkContent(contentDir: string): Promise<void> {
+  const linkPath = path.join(PACKAGE_ROOT, '.content');
+  const target = path.resolve(contentDir);
 
-function copyRecursive(src: string, dest: string) {
-  const stat = fs.statSync(src)
-  if (stat.isDirectory()) {
-    fs.mkdirSync(dest, { recursive: true })
-    for (const entry of fs.readdirSync(src)) {
-      copyRecursive(path.join(src, entry), path.join(dest, entry))
-    }
-  } else {
-    fs.copyFileSync(src, dest)
-  }
-}
-
-function ensureRemoved(targetPath: string) {
   try {
-    fs.lstatSync(targetPath)
-    fs.rmSync(targetPath, { recursive: true, force: true })
+    const existing = await fs.readlink(linkPath);
+    if (existing === target) return;
+    await fs.unlink(linkPath);
   } catch {
-    // nothing exists, proceed
-  }
-}
-
-export function detectPackageManager(): string {
-  if (process.env.npm_config_user_agent) {
-    return process.env.npm_config_user_agent.split('/')[0]
-  }
-  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'
-}
-
-function generateNextConfig(scaffoldPath: string) {
-  const config = `import { createMDX } from 'fumadocs-mdx/next'
-
-const withMDX = createMDX()
-
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  reactStrictMode: true,
-}
-
-export default withMDX(nextConfig)
-`
-  fs.writeFileSync(path.join(scaffoldPath, 'next.config.mjs'), config)
-}
-
-function createPackageJson(): Record<string, unknown> {
-  return {
-    name: 'chronicle-docs',
-    private: true,
-    dependencies: {
-      '@raystack/chronicle': 'latest',
-    },
-    devDependencies: {
-      '@raystack/tools-config': '0.56.0',
-      'openapi-types': '^12.1.3',
-      typescript: '5.9.3',
-      '@types/react': '^19.2.10',
-      '@types/node': '^25.1.0',
-    },
+    // link doesn't exist
   }
-}
-
-function ensureDeps() {
-  const cwd = process.cwd()
-  const cwdPkgJson = path.join(cwd, 'package.json')
-  const cwdNodeModules = path.join(cwd, 'node_modules')
-
-  if (fs.existsSync(cwdPkgJson) && fs.existsSync(cwdNodeModules)) {
-    // Case 1: existing project with deps installed
-    return
-  }
-
-  // Case 2: no package.json — create in cwd and install
-  if (!fs.existsSync(cwdPkgJson)) {
-    fs.writeFileSync(cwdPkgJson, JSON.stringify(createPackageJson(), null, 2) + '\n')
-  }
-
-  if (!fs.existsSync(cwdNodeModules)) {
-    const pm = detectPackageManager()
-    console.log(chalk.cyan(`Installing dependencies with ${pm}...`))
-    execSync(`${pm} install`, { cwd, stdio: 'inherit' })
-  }
-}
-
-export function resolveNextCli(): string {
-  const cwdRequire = createRequire(path.join(process.cwd(), 'package.json'))
-  return cwdRequire.resolve('next/dist/bin/next')
-}
-
-export function scaffoldDir(contentDir: string): string {
-  const scaffoldPath = path.join(process.cwd(), '.chronicle')
-
-  // Create .chronicle/ if not exists
-  if (!fs.existsSync(scaffoldPath)) {
-    fs.mkdirSync(scaffoldPath, { recursive: true })
-  }
-
-  // Copy package files
-  for (const name of COPY_FILES) {
-    const src = path.join(PACKAGE_ROOT, name)
-    const dest = path.join(scaffoldPath, name)
-    ensureRemoved(dest)
-    copyRecursive(src, dest)
-  }
-
-  // Generate next.config.mjs
-  generateNextConfig(scaffoldPath)
-
-  // Symlink content dir
-  const contentLink = path.join(scaffoldPath, 'content')
-  ensureRemoved(contentLink)
-  fs.symlinkSync(path.resolve(contentDir), contentLink)
-
-  // Ensure dependencies are available
-  ensureDeps()
-
-  console.log(chalk.gray(`Scaffold: ${scaffoldPath}`))
 
-  return scaffoldPath
+  await fs.symlink(target, linkPath);
 }

package/src/components/mdx/code.tsx

@@ -1,6 +1,7 @@
 'use client'
 
-import type { ComponentProps } from 'react'
+import { type ComponentProps, isValidElement, Children } from 'react'
+import { Mermaid } from './mermaid'
 import styles from './code.module.css'
 
 type PreProps = ComponentProps<'pre'> & {
@@ -16,6 +17,14 @@ export function MdxCode({ children, className, ...props }: ComponentProps<'code'
 }
 
 export function MdxPre({ children, title, className, ...props }: PreProps) {
+  // Detect mermaid code blocks
+  if (isValidElement(children)) {
+    const childProps = children.props as { className?: string; children?: string }
+    if (childProps.className?.includes('language-mermaid') && typeof childProps.children === 'string') {
+      return <Mermaid chart={childProps.children} />
+    }
+  }
+
   return (
     <div className={styles.codeBlock}>
       {title && <div className={styles.codeHeader}>{title}</div>}

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

@@ -1,35 +1,10 @@
 .details {
-  border: 1px solid var(--rs-color-border-base-primary);
-  border-radius: var(--rs-radius-2);
   margin: var(--rs-space-5) 0;
 }
 
-.summary {
-  padding: var(--rs-space-4) var(--rs-space-5);
-  cursor: pointer;
+.trigger {
   font-weight: 500;
   font-size: var(--rs-font-size-small);
-  color: var(--rs-color-text-base-primary);
-  background: var(--rs-color-background-base-secondary);
-  list-style: none;
-  display: flex;
-  align-items: center;
-  gap: var(--rs-space-3);
-}
-
-.summary::-webkit-details-marker {
-  display: none;
-}
-
-.summary::before {
-  content: '▶';
-  font-size: 10px;
-  transition: transform 0.2s ease;
-  color: var(--rs-color-text-base-secondary);
-}
-
-.details[open] > .summary::before {
-  transform: rotate(90deg);
 }
 
 .content {

package/src/components/mdx/details.tsx

@@ -1,9 +1,8 @@
 import type { ComponentProps } from 'react'
-import styles from './details.module.css'
 
 export function MdxDetails({ children, className, ...props }: ComponentProps<'details'>) {
   return (
-    <details className={`${styles.details} ${className ?? ''}`} {...props}>
+    <details className={className} {...props}>
       {children}
     </details>
   )
@@ -11,7 +10,7 @@ export function MdxDetails({ children, className, ...props }: ComponentProps<'de
 
 export function MdxSummary({ children, className, ...props }: ComponentProps<'summary'>) {
   return (
-    <summary className={`${styles.summary} ${className ?? ''}`} {...props}>
+    <summary className={className} {...props}>
       {children}
     </summary>
   )

package/src/components/mdx/image.tsx

@@ -1,38 +1,9 @@
-'use client'
+import type { ComponentProps } from 'react';
 
-import NextImage from 'next/image'
-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
-
-  const isExternal = src.startsWith('http://') || src.startsWith('https://')
-
-  if (isExternal) {
-    return (
-      // eslint-disable-next-line @next/next/no-img-element
-      <img
-        src={src}
-        alt={alt ?? ''}
-        width={width}
-        height={height}
-        {...props}
-      />
-    )
-  }
+export function Image({ src, alt, ...props }: ImageProps) {
+  if (!src) return null;
 
-  return (
-    <NextImage
-      src={src}
-      alt={alt ?? ''}
-      width={typeof width === 'string' ? parseInt(width, 10) : (width ?? 800)}
-      height={typeof height === 'string' ? parseInt(height, 10) : (height ?? 400)}
-    />
-  )
+  return <img src={src} alt={alt ?? ''} loading='lazy' {...props} />;
 }

package/src/components/mdx/index.tsx

@@ -8,6 +8,20 @@ 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,
@@ -27,7 +41,7 @@ export const mdxComponents: MDXComponents = {
   Callout: CalloutContainer,
   CalloutTitle,
   CalloutDescription,
-  Tabs,
+  Tabs: MdxTabs,
   Mermaid,
 }
 

package/src/components/mdx/link.tsx

@@ -1,38 +1,41 @@
-'use client'
+import { Link as ApsaraLink } from '@raystack/apsara';
+import type { ComponentProps } from 'react';
+import { Link as RouterLink } from 'react-router';
 
-import NextLink from 'next/link'
-import { Link as ApsaraLink } from '@raystack/apsara'
-import type { ComponentProps } from 'react'
-
-type LinkProps = ComponentProps<'a'>
+type LinkProps = ComponentProps<'a'>;
 
 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 (isAnchor) {
     return (
       <ApsaraLink href={href} {...props}>
         {children}
       </ApsaraLink>
-    )
+    );
   }
 
   if (isExternal) {
     return (
-      <ApsaraLink href={href} target="_blank" rel="noopener noreferrer" {...props}>
+      <ApsaraLink
+        href={href}
+        target='_blank'
+        rel='noopener noreferrer'
+        {...props}
+      >
         {children}
       </ApsaraLink>
-    )
+    );
   }
 
   return (
-    <NextLink href={href} className={props.className}>
+    <RouterLink to={href} className={props.className}>
       {children}
-    </NextLink>
-  )
+    </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/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(' ');
 }