@raystack/chronicle 0.10.0 → 0.10.2

package/dist/cli/index.js

@@ -822,6 +822,18 @@ var devCommand = new Command2("dev").description("Start development server").opt
   });
   await server.listen();
   server.printUrls();
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    try {
+      await server.close();
+    } catch {}
+    process.exit(0);
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
 });
 
 // src/cli/commands/init.ts
@@ -953,6 +965,18 @@ var startCommand = new Command5("start").description("Start production server").
     preview: { port, host: options.host }
   });
   server.printUrls();
+  let shuttingDown = false;
+  const shutdown = async () => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    try {
+      await server.close();
+    } catch {}
+    process.exit(0);
+  };
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
 });
 
 // src/cli/index.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -47,8 +47,9 @@
     "@opentelemetry/sdk-metrics": "^2.6.1",
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "@radix-ui/react-icons": "^1.3.2",
-    "@raystack/apsara": "1.0.0-rc.4",
+    "@raystack/apsara": "1.0.0-rc.7",
     "@shikijs/rehype": "^4.0.2",
+    "@tanstack/react-query": "5.100.10",
     "@vitejs/plugin-react": "^6.0.1",
     "chalk": "^5.6.2",
     "class-variance-authority": "^0.7.1",

package/src/cli/commands/dev.ts

@@ -28,4 +28,16 @@ export const devCommand = new Command('dev')
 
     await server.listen();
     server.printUrls();
+
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      try {
+        await server.close();
+      } catch { /* ignore close errors */ }
+      process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
   });

package/src/cli/commands/start.ts

@@ -26,4 +26,16 @@ export const startCommand = new Command('start')
     });
 
     server.printUrls();
+
+    let shuttingDown = false;
+    const shutdown = async () => {
+      if (shuttingDown) return;
+      shuttingDown = true;
+      try {
+        await server.close();
+      } catch { /* ignore close errors */ }
+      process.exit(0);
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
   });

package/src/components/api/api-overview.tsx

@@ -21,7 +21,7 @@ interface ApiOverviewProps {
   auth?: { type: string; header: string; placeholder?: string }
 }
 
-export function ApiOverview({ method, path, operation, auth }: ApiOverviewProps) {
+export function ApiOverview({ method, path, operation, serverUrl, auth }: ApiOverviewProps) {
   const params = (operation.parameters ?? []) as OpenAPIV3.ParameterObject[]
   const body = getRequestBody(operation.requestBody as OpenAPIV3.RequestBodyObject | undefined)
 
@@ -36,7 +36,7 @@ export function ApiOverview({ method, path, operation, auth }: ApiOverviewProps)
       ? headerFields
       : []
 
-  const fullUrl = '{domain}' + path
+  const fullUrl = serverUrl + path
   const snippetHeaders: Record<string, string> = {}
   if (auth) snippetHeaders[auth.header] = auth.placeholder ?? 'YOUR_API_KEY'
   if (body) snippetHeaders['Content-Type'] = body.contentType ?? 'application/json'

package/src/components/api/playground-dialog.tsx

@@ -1,8 +1,8 @@
 'use client'
 
-import { useState, useCallback, useMemo } from 'react'
+import { useState, useCallback, useMemo, useEffect } from 'react'
 import type { OpenAPIV3 } from 'openapi-types'
-import { Dialog, Button, Badge, IconButton, InputField, CopyButton, Select, Menu } from '@raystack/apsara'
+import { Dialog, Button, Badge, IconButton, Input, CopyButton, Select, Menu } from '@raystack/apsara'
 import { Cross2Icon, ChevronDownIcon, ChevronUpIcon, PlayIcon, PlusIcon } from '@radix-ui/react-icons'
 import { CounterClockwiseClockIcon, CodeIcon } from '@radix-ui/react-icons'
 import { MethodBadge } from '@/components/api/method-badge'
@@ -68,11 +68,21 @@ export function PlaygroundDialog({
 
   const authSchemes = useMemo(() => getAuthSchemes(document, auth), [document, auth])
   const defaultScheme = authSchemes.find((s) => s.type !== 'none') ?? authSchemes[0]
-
-  const [selectedScheme, setSelectedScheme] = useState(defaultScheme.name)
-  const [authToken, setAuthToken] = useState('')
-  const [basicUser, setBasicUser] = useState('')
-  const [basicPass, setBasicPass] = useState('')
+  const storageKey = `chronicle:auth:${specName}`
+  const savedAuth = useMemo(() => {
+    try {
+      const raw = sessionStorage.getItem(storageKey)
+      return raw ? JSON.parse(raw) : null
+    } catch { return null }
+  }, [storageKey])
+
+  const [selectedScheme, setSelectedScheme] = useState(() => {
+    if (savedAuth?.scheme && authSchemes.some((s) => s.name === savedAuth.scheme)) return savedAuth.scheme
+    return defaultScheme.name
+  })
+  const [authToken, setAuthToken] = useState(savedAuth?.token ?? '')
+  const [basicUser, setBasicUser] = useState(savedAuth?.basicUser ?? '')
+  const [basicPass, setBasicPass] = useState(savedAuth?.basicPass ?? '')
   const [headerValues, setHeaderValues] = useState<Record<string, string>>({})
   const [pathValues, setPathValues] = useState<Record<string, string>>({})
   const [queryValues, setQueryValues] = useState<Record<string, string>>({})
@@ -89,6 +99,17 @@ export function PlaygroundDialog({
   })
   const [bodyJsonStr, setBodyJsonStr] = useState(() => body ? body.jsonExample : '{}')
 
+  useEffect(() => {
+    try {
+      sessionStorage.setItem(storageKey, JSON.stringify({
+        scheme: selectedScheme,
+        token: authToken,
+        basicUser,
+        basicPass,
+      }))
+    } catch { /* ignore */ }
+  }, [storageKey, selectedScheme, authToken, basicUser, basicPass])
+
   const [responseData, setResponseData] = useState<{
     status: number; statusText: string; body: unknown; headers?: Record<string, string>; time: number
   } | null>(null)
@@ -119,6 +140,7 @@ export function PlaygroundDialog({
     setAuthToken('')
     setBasicUser('')
     setBasicPass('')
+    try { sessionStorage.removeItem(storageKey) } catch { /* ignore */ }
     setHeaderValues({})
     setPathValues({})
     setQueryValues({})
@@ -263,13 +285,13 @@ export function PlaygroundDialog({
                           <div className={styles.fieldRow}>
                             <span className={styles.fieldLabel}>Username</span>
                             <div className={styles.fieldInput}>
-                              <InputField size="small" placeholder="Enter username" value={basicUser} onChange={(e) => setBasicUser(e.target.value)} />
+                              <Input size="small" placeholder="Enter username" value={basicUser} onValueChange={setBasicUser} />
                             </div>
                           </div>
                           <div className={styles.fieldRow}>
                             <span className={styles.fieldLabel}>Password</span>
                             <div className={styles.fieldInput}>
-                              <InputField size="small" type="password" placeholder="Enter password" value={basicPass} onChange={(e) => setBasicPass(e.target.value)} />
+                              <Input size="small" type="password" placeholder="Enter password" value={basicPass} onValueChange={setBasicPass} />
                             </div>
                           </div>
                         </>
@@ -277,7 +299,7 @@ export function PlaygroundDialog({
                         <div className={styles.fieldRow}>
                           <span className={styles.fieldLabel}>{currentScheme.headerName}</span>
                           <div className={styles.fieldInput}>
-                            <InputField size="small" placeholder={currentScheme.placeholder} value={authToken} onChange={(e) => setAuthToken(e.target.value)} />
+                            <Input size="small" placeholder={currentScheme.placeholder} value={authToken} onValueChange={setAuthToken} />
                           </div>
                         </div>
                       ) : null}
@@ -285,7 +307,7 @@ export function PlaygroundDialog({
                         <div key={f.name} className={styles.fieldRow}>
                           <span className={styles.fieldLabel}>{f.name}</span>
                           <div className={styles.fieldInput}>
-                            <InputField size="small" placeholder="Enter value" value={headerValues[f.name] ?? ''} onChange={(e) => setHeaderValues({ ...headerValues, [f.name]: e.target.value })} />
+                            <Input size="small" placeholder="Enter value" value={headerValues[f.name] ?? ''} onValueChange={(v) => setHeaderValues({ ...headerValues, [f.name]: v })} />
                           </div>
                         </div>
                       ))}
@@ -307,11 +329,11 @@ export function PlaygroundDialog({
                     <div key={f.name} className={styles.fieldRow}>
                       <span className={styles.fieldLabel}>{f.name}</span>
                       <div className={styles.fieldInput}>
-                        <InputField
+                        <Input
                           size="small"
                           placeholder="Enter value"
                           value={pathValues[f.name] ?? ''}
-                          onChange={(e) => setPathValues({ ...pathValues, [f.name]: e.target.value })}
+                          onValueChange={(v) => setPathValues({ ...pathValues, [f.name]: v })}
                         />
                       </div>
                     </div>
@@ -332,11 +354,11 @@ export function PlaygroundDialog({
                     <div key={f.name} className={styles.fieldRow}>
                       <span className={styles.fieldLabel}>{f.name}</span>
                       <div className={styles.fieldInput}>
-                        <InputField
+                        <Input
                           size="small"
                           placeholder={f.description ?? 'Enter value'}
                           value={queryValues[f.name] ?? ''}
-                          onChange={(e) => setQueryValues({ ...queryValues, [f.name]: e.target.value })}
+                          onValueChange={(v) => setQueryValues({ ...queryValues, [f.name]: v })}
                         />
                       </div>
                     </div>
@@ -494,13 +516,13 @@ function BodyFieldRow({ field, value, onChange }: {
         {items.map((item, i) => (
           <div key={i} className={styles.arrayItemRow}>
             <div className={styles.fieldInput}>
-              <InputField
+              <Input
                 size="small"
                 placeholder={`${field.name}[${i}]`}
                 value={String(item)}
-                onChange={(e) => {
+                onValueChange={(v) => {
                   const updated = [...items]
-                  updated[i] = e.target.value
+                  updated[i] = v
                   onChange(updated)
                 }}
               />
@@ -539,11 +561,11 @@ function BodyFieldRow({ field, value, onChange }: {
     <div className={styles.fieldRow}>
       <span className={styles.fieldLabel}>{field.name} {field.required && <Badge variant="danger" size="micro">required</Badge>}</span>
       <div className={styles.fieldInput}>
-        <InputField
+        <Input
           size="small"
           placeholder={field.description ?? 'Enter value'}
           value={String(value ?? '')}
-          onChange={(e) => onChange(e.target.value)}
+          onValueChange={(v) => onChange(v)}
         />
       </div>
     </div>

package/src/components/mdx/link.tsx

@@ -1,12 +1,10 @@
 import { Link as ApsaraLink } from '@raystack/apsara';
-import type { ComponentProps, MouseEvent } from 'react';
-import { useNavigate } from 'react-router';
+import type { ComponentProps } from 'react';
+import { Link as RouterLink } from 'react-router';
 
 type LinkProps = ComponentProps<'a'>;
 
-export function Link({ href, children, onClick: onClickProp, ...props }: LinkProps) {
-  const navigate = useNavigate();
-
+export function Link({ href, children, ...props }: LinkProps) {
   if (!href) {
     return <span {...props}>{children}</span>;
   }
@@ -16,12 +14,7 @@ export function Link({ href, children, onClick: onClickProp, ...props }: LinkPro
 
   if (isExternal) {
     return (
-      <ApsaraLink
-        href={href}
-        target='_blank'
-        rel='noopener noreferrer'
-        {...props}
-      >
+      <ApsaraLink href={href} external {...props}>
         {children}
       </ApsaraLink>
     );
@@ -35,27 +28,8 @@ export function Link({ href, children, onClick: onClickProp, ...props }: LinkPro
     );
   }
 
-  const onClick = (e: MouseEvent<HTMLAnchorElement>) => {
-    if (
-      e.defaultPrevented ||
-      e.button !== 0 ||
-      e.metaKey ||
-      e.ctrlKey ||
-      e.shiftKey ||
-      e.altKey
-    ) {
-      return;
-    }
-
-    onClickProp?.(e);
-    if (e.defaultPrevented) return;
-
-    e.preventDefault();
-    navigate(href);
-  };
-
   return (
-    <ApsaraLink href={href} {...props} onClick={onClick}>
+    <ApsaraLink render={<RouterLink to={href} />} {...props}>
       {children}
     </ApsaraLink>
   );

package/src/components/ui/PrefetchProvider.tsx

@@ -0,0 +1,70 @@
+import { useEffect } from 'react';
+import { prefetchPageData } from '@/lib/preload';
+
+function resolvePathname(href: string | null): string | null {
+  if (!href) return null;
+  try {
+    const url = new URL(href, location.href);
+    if (url.origin !== location.origin) return null;
+    return url.pathname;
+  } catch {
+    return null;
+  }
+}
+
+export function PrefetchProvider({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    const handleMouseOver = (e: MouseEvent) => {
+      const anchor = (e.target as HTMLElement).closest?.('a[href]');
+      if (!anchor) return;
+      const pathname = resolvePathname(anchor.getAttribute('href'));
+      if (pathname) prefetchPageData(pathname);
+    };
+
+    const handleFocusIn = (e: FocusEvent) => {
+      const anchor = (e.target as HTMLElement).closest?.('a[href]');
+      if (!anchor) return;
+      const pathname = resolvePathname(anchor.getAttribute('href'));
+      if (pathname) prefetchPageData(pathname);
+    };
+
+    document.addEventListener('mouseover', handleMouseOver);
+    document.addEventListener('focusin', handleFocusIn);
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            const pathname = resolvePathname((entry.target as HTMLAnchorElement).getAttribute('href'));
+            if (pathname) prefetchPageData(pathname);
+            observer.unobserve(entry.target);
+          }
+        }
+      },
+      { rootMargin: '200px' },
+    );
+
+    const observeLinks = () => {
+      document.querySelectorAll('a[href]:not([data-prefetch-observed])').forEach((link) => {
+        const pathname = resolvePathname(link.getAttribute('href'));
+        if (pathname) {
+          link.setAttribute('data-prefetch-observed', '');
+          observer.observe(link);
+        }
+      });
+    };
+
+    const mutationObserver = new MutationObserver(observeLinks);
+    mutationObserver.observe(document.body, { childList: true, subtree: true });
+    observeLinks();
+
+    return () => {
+      document.removeEventListener('mouseover', handleMouseOver);
+      document.removeEventListener('focusin', handleFocusIn);
+      observer.disconnect();
+      mutationObserver.disconnect();
+    };
+  }, []);
+
+  return children;
+}

package/src/components/ui/search.module.css

@@ -41,6 +41,12 @@
   display: flex;
   align-items: center;
   gap: 12px;
+  flex: 1;
+}
+
+.sectionBadge {
+  margin-left: auto;
+  flex-shrink: 0;
 }
 
 .resultText {

package/src/components/ui/search.tsx

@@ -3,7 +3,7 @@ import {
   HashtagIcon,
   MagnifyingGlassIcon
 } from '@heroicons/react/24/outline';
-import { Command, IconButton, Text } from '@raystack/apsara';
+import { Badge, Command, IconButton, Text } from '@raystack/apsara';
 import { debounce } from 'lodash-es';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useNavigate } from 'react-router';
@@ -18,6 +18,7 @@ interface SearchResult {
   content: string;
   match?: 'title' | 'heading' | 'body';
   snippet?: string;
+  section?: string;
 }
 
 interface SearchProps {
@@ -157,6 +158,7 @@ export function Search({ classNames }: SearchProps) {
                               html={stripMethod(result.content)}
                             />
                           </Text>
+                          {result.section && <Badge size="small" className={styles.sectionBadge}>{result.section}</Badge>}
                         </div>
                       </Command.Item>
                     ))}
@@ -187,6 +189,7 @@ export function Search({ classNames }: SearchProps) {
                           </Text>
                         )}
                       </div>
+                      {result.section && <Badge size="small" className={styles.sectionBadge}>{result.section}</Badge>}
                     </div>
                   </Command.Item>
                 ))}

package/src/lib/env.ts

@@ -0,0 +1,9 @@
+export function substituteEnvVars(value: string): string {
+  return value.replace(/\$\{(\w+)\}/g, (_, name) => {
+    const val = process.env[name];
+    if (val === undefined) {
+      throw new Error(`Environment variable '${name}' is not set`);
+    }
+    return val;
+  });
+}

package/src/lib/openapi.ts

@@ -3,6 +3,7 @@ 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'
+import { substituteEnvVars } from '@/lib/env'
 
 type JsonObject = Record<string, unknown>
 
@@ -41,7 +42,7 @@ export async function loadApiSpec(config: ApiConfig, projectRoot: string): Promi
   return {
     name: config.name,
     basePath: config.basePath,
-    server: config.server,
+    server: { ...config.server, url: substituteEnvVars(config.server.url) },
     auth: config.auth,
     document: v3Doc,
   }

package/src/lib/page-context.tsx

@@ -13,6 +13,7 @@ import { resolveRoute, RouteType } from '@/lib/route-resolver';
 import type { VersionContext } from '@/lib/version-source';
 import { LATEST_CONTEXT } from '@/lib/version-source';
 import type { ChronicleConfig, Frontmatter, Page, PageNavLink, Root, TableOfContents } from '@/types';
+import { queryClient } from '@/lib/preload';
 
 export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
 
@@ -114,12 +115,16 @@ export function PageProvider({
   }
 
   const fetchPageData = useCallback(async (slug: string[]): Promise<PageData> => {
-    const apiPath = slug.length === 0
-      ? '/api/page'
-      : `/api/page?slug=${slug.map(s => encodeURIComponent(s)).join(',')}`;
-    const res = await fetch(apiPath);
-    if (!res.ok) throw new Error(String(res.status));
-    return res.json();
+    const key = slug.length === 0 ? '' : slug.map(s => encodeURIComponent(s)).join(',');
+    const apiPath = key ? `/api/page?slug=${key}` : '/api/page';
+    return queryClient.fetchQuery({
+      queryKey: ['pageData', key],
+      queryFn: async () => {
+        const res = await fetch(apiPath);
+        if (!res.ok) throw new Error(String(res.status));
+        return res.json();
+      },
+    });
   }, []);
 
   const loadDocsPage = useCallback(async (slug: string[], cancelled: { current: boolean }) => {

package/src/lib/preload.ts

@@ -0,0 +1,37 @@
+import { QueryClient } from '@tanstack/react-query';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: Infinity,
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+export function pageDataQueryKey(pathname: string) {
+  const slug = pathname.split('/').filter(Boolean);
+  const key = slug.length === 0 ? '' : slug.map(s => encodeURIComponent(s)).join(',');
+  return ['pageData', key] as const;
+}
+
+async function fetchPageDataByPathname(pathname: string) {
+  const slug = pathname.split('/').filter(Boolean);
+  const key = slug.length === 0 ? '' : slug.map(s => encodeURIComponent(s)).join(',');
+  const apiPath = key ? `/api/page?slug=${key}` : '/api/page';
+  const res = await fetch(apiPath);
+  if (!res.ok) throw new Error(String(res.status));
+  return res.json();
+}
+
+function isApisRoute(pathname: string): boolean {
+  return pathname === '/apis' || pathname.startsWith('/apis/');
+}
+
+export function prefetchPageData(pathname: string) {
+  if (isApisRoute(pathname)) return;
+  queryClient.prefetchQuery({
+    queryKey: pageDataQueryKey(pathname),
+    queryFn: () => fetchPageDataByPathname(pathname),
+  });
+}

package/src/lib/source.ts

@@ -174,17 +174,31 @@ function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[], me
   return { ...tree, children: sortNodes(tree.children, pageOrderMap, folderOrderMap) };
 }
 
+function filterDraftsFromTree(tree: Root, draftUrls: Set<string>): Root {
+  function filterNodes(nodes: Node[]): Node[] {
+    return nodes
+      .filter(n => n.type !== NodeType.Page || !draftUrls.has(n.url))
+      .map(n => n.type === NodeType.Folder
+        ? { ...n, children: filterNodes(n.children) } as Folder
+        : n
+      );
+  }
+  return { ...tree, children: filterNodes(tree.children) };
+}
+
 export async function getPageTree(): Promise<Root> {
   if (cachedTree) return cachedTree;
   const s = await getSource();
   const metaFiles = buildFiles().filter(f => f.type === 'meta') as { path: string; data: Record<string, unknown> }[];
-  cachedTree = sortTreeByOrder(s.pageTree as Root, s.getPages(), metaFiles);
+  const sorted = sortTreeByOrder(s.pageTree as Root, s.getPages(), metaFiles);
+  const draftUrls = new Set(s.getPages().filter(p => isDraft(p)).map(p => p.url));
+  cachedTree = draftUrls.size > 0 ? filterDraftsFromTree(sorted, draftUrls) : sorted;
   return cachedTree;
 }
 
 export async function getPages() {
   const s = await getSource();
-  return s.getPages();
+  return s.getPages().filter(p => !isDraft(p));
 }
 
 export async function getPage(slugs?: string[]) {
@@ -254,10 +268,15 @@ export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: stri
     order: d.order as number | undefined,
     icon: d.icon as string | undefined,
     lastModified: d.lastModified as string | undefined,
+    draft: d.draft as boolean | undefined,
     _readingTime: d._readingTime as number | undefined,
   };
 }
 
+export function isDraft(page: { data: unknown }): boolean {
+  return (page.data as Record<string, unknown>).draft === true;
+}
+
 export function getRelativePath(page: { data: unknown }): string {
   return ((page.data as Record<string, unknown>)._relativePath as string) ?? '';
 }

package/src/pages/DocsLayout.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import { useLocation } from 'react-router';
+import { PrefetchProvider } from '@/components/ui/PrefetchProvider';
 import { usePageContext } from '@/lib/page-context';
 import { getActiveContentDir } from '@/lib/navigation';
 import {
@@ -27,13 +28,15 @@ export function DocsLayout({ children, hideSidebar }: DocsLayoutProps) {
   );
 
   return (
-    <Layout
-      config={config}
-      tree={scopedTree}
-      hideSidebar={hideSidebar}
-      classNames={{ layout: className }}
-    >
-      {children}
-    </Layout>
+    <PrefetchProvider>
+      <Layout
+        config={config}
+        tree={scopedTree}
+        hideSidebar={hideSidebar}
+        classNames={{ layout: className }}
+      >
+        {children}
+      </Layout>
+    </PrefetchProvider>
   );
 }

package/src/server/App.module.css

@@ -0,0 +1,4 @@
+.fallback {
+  padding: var(--rs-space-8);
+  width: 80%;
+}