@raystack/chronicle 0.7.1 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",

package/src/components/ui/breadcrumbs.tsx

@@ -8,16 +8,17 @@ import { Link as RouterLink } from 'react-router'
 interface BreadcrumbsProps {
   slug: string[]
   tree: Root
+  className?: string
 }
 
-export function Breadcrumbs({ slug, tree }: BreadcrumbsProps) {
+export function Breadcrumbs({ slug, tree, className }: BreadcrumbsProps) {
   const url = slug.length === 0 ? '/' : `/${slug.join('/')}`
   const items = getBreadcrumbItems(url, tree, { includePage: true })
 
   if (items.length === 0) return null
 
   return (
-    <Breadcrumb size="small">
+    <Breadcrumb size="small" className={className}>
       {items.flatMap((item, index) => {
         const isCurrent = index === items.length - 1
         const breadcrumbItem = (

package/src/components/ui/search.tsx

@@ -4,30 +4,86 @@ import {
   MagnifyingGlassIcon
 } from '@heroicons/react/24/outline';
 import { Command, IconButton, Text } from '@raystack/apsara';
-import type { SortedResult } from 'fumadocs-core/search';
-import { useDocsSearch } from 'fumadocs-core/search/client';
-import { useCallback, useEffect, useState } from 'react';
+import debounce from 'lodash/debounce';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
 import { usePageContext } from '@/lib/page-context';
 import styles from './search.module.css';
 
+interface SearchResult {
+  id: string;
+  url: string;
+  type: string;
+  content: string;
+}
+
 interface SearchProps {
   classNames?: { trigger?: string };
 }
 
+function buildSearchUrl(query: string, tag?: string): string {
+  const params = new URLSearchParams();
+  if (query) params.set('query', query);
+  if (tag) params.set('tag', tag);
+  const qs = params.toString();
+  return qs ? `/api/search?${qs}` : '/api/search';
+}
+
 export function Search({ classNames }: SearchProps) {
   const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState('');
+  const [results, setResults] = useState<SearchResult[]>([]);
+  const [suggestions, setSuggestions] = useState<SearchResult[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
   const navigate = useNavigate();
   const { version } = usePageContext();
+  const tag = version.dir ?? undefined;
+  const abortRef = useRef<AbortController | null>(null);
 
-  const { search, setSearch, query } = useDocsSearch({
-    type: 'fetch',
-    api: '/api/search',
-    tag: version.dir ?? undefined,
-    delayMs: 100,
-    allowEmpty: true
-  });
+  const fetchResults = useCallback(async (query: string, signal?: AbortSignal) => {
+    setIsLoading(true);
+    try {
+      const res = await fetch(buildSearchUrl(query, tag), { signal });
+      if (!res.ok || signal?.aborted) return;
+      const data: SearchResult[] = await res.json();
+      if (signal?.aborted) return;
+      if (query) {
+        setResults(data);
+      } else {
+        setSuggestions(data);
+      }
+    } catch (err) {
+      if (err instanceof DOMException && err.name === 'AbortError') return;
+      console.error('Search fetch failed:', err);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [tag]);
+
+  const debouncedSearch = useMemo(
+    () => debounce((query: string) => {
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+      fetchResults(query, controller.signal);
+    }, 150),
+    [fetchResults]
+  );
+
+  useEffect(() => {
+    if (!open) {
+      setSearch('');
+      setResults([]);
+      return;
+    }
+    if (!search) {
+      fetchResults('');
+      return;
+    }
+    debouncedSearch(search);
+    return () => debouncedSearch.cancel();
+  }, [open, search, fetchResults, debouncedSearch]);
 
   const onSelect = useCallback(
     (url: string) => {
@@ -49,9 +105,7 @@ export function Search({ classNames }: SearchProps) {
     return () => document.removeEventListener('keydown', down);
   }, []);
 
-  const results = deduplicateByUrl(
-    query.data === 'empty' ? [] : (query.data ?? [])
-  );
+  const displayResults = deduplicateByUrl(search ? results : suggestions);
 
   return (
     <>
@@ -77,18 +131,17 @@ export function Search({ classNames }: SearchProps) {
             />
 
             <Command.Content className={styles.list}>
-              {query.isLoading && <Command.Empty>Loading...</Command.Empty>}
-              {!query.isLoading &&
+              {isLoading && displayResults.length === 0 && <Command.Empty>Loading...</Command.Empty>}
+              {!isLoading &&
                 search.length > 0 &&
-                results.length === 0 && (
+                displayResults.length === 0 && (
                   <Command.Empty>No results found.</Command.Empty>
                 )}
-              {!query.isLoading &&
-                search.length === 0 &&
-                results.length > 0 && (
+              {search.length === 0 &&
+                displayResults.length > 0 && (
                   <Command.Group>
                     <Command.Label>Suggestions</Command.Label>
-                    {results.slice(0, 8).map((result: SortedResult) => (
+                    {displayResults.slice(0, 8).map((result) => (
                       <Command.Item
                         key={result.id}
                         value={result.id}
@@ -108,7 +161,7 @@ export function Search({ classNames }: SearchProps) {
                   </Command.Group>
                 )}
               {search.length > 0 &&
-                results.map((result: SortedResult) => (
+                displayResults.map((result) => (
                   <Command.Item
                     key={result.id}
                     value={result.id}
@@ -149,7 +202,7 @@ export function Search({ classNames }: SearchProps) {
   );
 }
 
-function deduplicateByUrl(results: SortedResult[]): SortedResult[] {
+function deduplicateByUrl(results: SearchResult[]): SearchResult[] {
   const seen = new Set<string>();
   return results.filter(r => {
     const base = r.url.split('#')[0];
@@ -183,7 +236,7 @@ function HighlightedText({
   );
 }
 
-function getResultIcon(result: SortedResult): React.ReactNode {
+function getResultIcon(result: SearchResult): React.ReactNode {
   if (!result.url.startsWith('/apis/')) {
     return result.type === 'page' ? (
       <DocumentIcon className={styles.icon} />

package/src/lib/page-context.tsx

@@ -1,8 +1,10 @@
 import {
   createContext,
   type ReactNode,
+  useCallback,
   useContext,
   useEffect,
+  useRef,
   useState
 } from 'react';
 import { useLocation } from 'react-router';
@@ -10,7 +12,7 @@ import type { ApiSpec } from '@/lib/openapi';
 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, Root, TableOfContents } from '@/types';
+import type { ChronicleConfig, Frontmatter, Page, PageNavLink, Root, TableOfContents } from '@/types';
 
 export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
 
@@ -18,6 +20,7 @@ interface PageContextValue {
   config: ChronicleConfig;
   tree: Root;
   page: Page | null;
+  isLoading: boolean;
   errorStatus: number | null;
   apiSpecs: ApiSpec[];
   version: VersionContext;
@@ -36,6 +39,7 @@ export function usePageContext(): PageContextValue {
       },
       tree: { name: 'root', children: [] } as Root,
       page: null,
+      isLoading: false,
       errorStatus: null,
       apiSpecs: [],
       version: LATEST_CONTEXT,
@@ -82,11 +86,71 @@ export function PageProvider({
   const [errorStatus, setErrorStatus] = useState<number | null>(getInitialErrorStatus(initialPage, initialConfig, pathname));
   const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs);
   const [version, setVersion] = useState<VersionContext>(initialVersion);
-  const [currentPath, setCurrentPath] = useState(pathname);
+  const [isLoading, setIsLoading] = useState(false);
+  const currentPathRef = useRef(pathname);
+
+  const fetchApiSpecs = useCallback(async (route: { version: VersionContext }, cancelled: { current: boolean }) => {
+    setIsLoading(true);
+    try {
+      const specsUrl = route.version.dir
+        ? `/api/specs?version=${encodeURIComponent(route.version.dir)}`
+        : '/api/specs';
+      const res = await fetch(specsUrl);
+      const specs = await res.json();
+      if (!cancelled.current) setApiSpecs(specs);
+    } catch {
+      // best-effort on client nav
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  interface PageData {
+    frontmatter: Frontmatter;
+    relativePath: string;
+    originalPath?: string;
+    prev?: PageNavLink | null;
+    next?: PageNavLink | null;
+  }
+
+  const fetchPageData = useCallback(async (slug: string[]): Promise<PageData> => {
+    const apiPath = slug.length === 0
+      ? '/api/page'
+      : `/api/page?slug=${slug.join(',')}`;
+    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 }) => {
+    setIsLoading(true);
+    try {
+      const data = await fetchPageData(slug);
+      if (cancelled.current) return;
+      const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
+      if (cancelled.current) return;
+      setErrorStatus(null);
+      setPage({
+        slug,
+        frontmatter: data.frontmatter,
+        content,
+        toc,
+        prev: data.prev ?? null,
+        next: data.next ?? null,
+      });
+    } catch (err) {
+      if (cancelled.current) return;
+      const status = Number((err as Error).message) || 500;
+      setPage(null);
+      setErrorStatus(status);
+    } finally {
+      if (!cancelled.current) setIsLoading(false);
+    }
+  }, [fetchPageData, loadMdx]);
 
   useEffect(() => {
-    if (pathname === currentPath) return;
-    setCurrentPath(pathname);
+    if (pathname === currentPathRef.current) return;
+    currentPathRef.current = pathname;
 
     const route = resolveRoute(pathname, initialConfig);
     if (route.type !== RouteType.Redirect) setVersion(route.version);
@@ -96,17 +160,7 @@ export function PageProvider({
     if (route.type === RouteType.ApiIndex || route.type === RouteType.ApiPage) {
       setPage(null);
       setErrorStatus(null);
-      const specsUrl = route.version.dir
-        ? `/api/specs?version=${encodeURIComponent(route.version.dir)}`
-        : '/api/specs';
-      fetch(specsUrl)
-        .then(res => res.json())
-        .then(specs => {
-          if (!cancelled.current) setApiSpecs(specs);
-        })
-        .catch(() => {
-          // swallow — api specs are best-effort on client nav
-        });
+      fetchApiSpecs(route, cancelled);
       return () => { cancelled.current = true; };
     }
 
@@ -116,41 +170,15 @@ export function PageProvider({
       return () => { cancelled.current = true; };
     }
 
-    const apiPath = route.slug.length === 0
-      ? '/api/page'
-      : `/api/page?slug=${route.slug.join(',')}`;
-
-    fetch(apiPath)
-      .then(res => {
-        if (!res.ok) {
-          if (!cancelled.current) {
-            setPage(null);
-            setErrorStatus(res.status);
-          }
-          return;
-        }
-        return res.json();
-      })
-      .then(async (data: { frontmatter: Frontmatter; relativePath: string; originalPath?: string; prev?: Page['prev']; next?: Page['next'] } | undefined) => {
-        if (cancelled.current || !data) return;
-        const { content, toc } = await loadMdx(data.originalPath || data.relativePath);
-        if (cancelled.current) return;
-        setErrorStatus(null);
-        setPage({ slug: route.slug, frontmatter: data.frontmatter, content, toc, prev: data.prev, next: data.next });
-      })
-      .catch(() => {
-        if (!cancelled.current) {
-          setPage(null);
-          setErrorStatus(500);
-        }
-      });
-
+    setPage(null);
+    setErrorStatus(null);
+    loadDocsPage(route.slug, cancelled);
     return () => { cancelled.current = true; };
-  }, [pathname]);
+  }, [pathname, initialConfig, fetchApiSpecs, loadDocsPage]);
 
   return (
     <PageContext.Provider
-      value={{ config: initialConfig, tree, page, errorStatus, apiSpecs, version }}
+      value={{ config: initialConfig, tree, page, isLoading, errorStatus, apiSpecs, version }}
     >
       {children}
     </PageContext.Provider>

package/src/pages/DocsPage.tsx

@@ -8,13 +8,13 @@ interface DocsPageProps {
 }
 
 export function DocsPage({ slug }: DocsPageProps) {
-  const { config, tree, page, errorStatus } = usePageContext();
+  const { config, tree, page, isLoading, errorStatus } = usePageContext();
 
   if (errorStatus === 404) return <NotFound />;
   if (errorStatus) return <NotFound />;
-  if (!page) return null;
+  const { Page, Skeleton } = getTheme(config.theme?.name);
 
-  const { Page } = getTheme(config.theme?.name);
+  if (isLoading || !page) return <Skeleton />;
   const pageUrl = config.url ? `${config.url}/${slug.join('/')}` : undefined;
   const markdownHref = `/${slug.join('/')}.md`;
 

package/src/server/App.tsx

@@ -40,7 +40,7 @@ export function App() {
           <ApiPage slug={apiSlug} />
         </ApiLayout>
       ) : (
-        <DocsLayout>
+        <DocsLayout hideSidebar={isLanding}>
           {isLanding ? <LandingPage /> : <DocsPage slug={docsSlug} />}
         </DocsLayout>
       )}

package/src/themes/default/Skeleton.tsx

@@ -0,0 +1,27 @@
+import { Skeleton } from '@raystack/apsara';
+import { Flex } from '@raystack/apsara';
+import styles from './Page.module.css';
+
+export function PageSkeleton() {
+  return (
+    <Flex className={styles.page}>
+      <article className={styles.article}>
+        <Skeleton width="40%" height="32px" />
+        <Skeleton.Provider duration={2}>
+          <Skeleton width="100%" height="16px" />
+          <Skeleton width="95%" height="16px" />
+          <Skeleton width="80%" height="16px" />
+          <Skeleton width="100%" height="16px" />
+          <Skeleton width="60%" height="16px" />
+        </Skeleton.Provider>
+        <Skeleton width="30%" height="24px" />
+        <Skeleton.Provider duration={2}>
+          <Skeleton width="100%" height="16px" />
+          <Skeleton width="90%" height="16px" />
+          <Skeleton width="100%" height="16px" />
+          <Skeleton width="70%" height="16px" />
+        </Skeleton.Provider>
+      </article>
+    </Flex>
+  );
+}

package/src/themes/default/index.ts

@@ -1,11 +1,13 @@
 import type { Theme } from '@/types';
 import { Layout } from './Layout';
 import { Page } from './Page';
+import { PageSkeleton } from './Skeleton';
 import { Toc } from './Toc';
 
 export const defaultTheme: Theme = {
   Layout,
-  Page
+  Page,
+  Skeleton: PageSkeleton,
 };
 
-export { Layout, Page, Toc };
+export { Layout, Page, PageSkeleton, Toc };

package/src/themes/paper/ChapterNav.module.css

@@ -65,6 +65,10 @@
   flex-shrink: 0;
 }
 
+.subFolder {
+  margin-top: var(--rs-space-5);
+}
+
 .subLabel {
   font-family: var(--paper-font-mono);
   font-size: var(--rs-font-size-small);

package/src/themes/paper/ChapterNav.tsx

@@ -67,7 +67,7 @@ function ChapterItem({
 
   if (item.type === 'folder') {
     return (
-      <li>
+      <li className={styles.subFolder}>
         <span className={styles.subLabel}>{item.name}</span>
         <ul className={styles.chapterItems}>
           {item.children.map(child => (

package/src/themes/paper/Page.module.css

@@ -68,34 +68,12 @@
 }
 
 .breadcrumb {
-  display: flex;
-  align-items: center;
   font-family: var(--paper-font-mono);
   font-size: var(--rs-font-size-small);
   line-height: var(--rs-line-height-small);
   letter-spacing: var(--rs-letter-spacing-small);
 }
 
-.separator {
-  margin: 0 var(--rs-space-1);
-  color: var(--rs-color-foreground-base-tertiary);
-}
-
-.crumbLink {
-  color: var(--rs-color-foreground-base-tertiary);
-  font-weight: var(--rs-font-weight-medium);
-  text-decoration: none;
-}
-
-.crumbLink:hover {
-  color: var(--rs-color-foreground-base-primary);
-}
-
-.crumbActive {
-  color: var(--rs-color-foreground-base-primary);
-  font-weight: var(--rs-font-weight-medium);
-}
-
 .article {
   flex: 1;
   min-width: 0;
@@ -160,6 +138,7 @@
     0 1px 3px rgba(0, 0, 0, 0.08),
     0 4px 12px rgba(0, 0, 0, 0.04);
   margin-bottom: var(--rs-space-9);
+  min-height: calc(100vh - var(--rs-space-12));
 }
 
 .content h1,
@@ -219,6 +198,9 @@
 }
 
 .content table {
+  display: block;
+  width: 100%;
+  overflow-x: auto;
   margin-bottom: var(--rs-space-5);
 }
 
@@ -236,3 +218,12 @@
   padding-left: 1rem;
   border-left: 3px solid var(--rs-color-border-base-primary);
 }
+
+.headerLoader {
+    align-items: center;
+    margin-bottom: var(--rs-space-5)
+}
+
+.loader {
+    margin-bottom: var(--rs-space-3)
+}

package/src/themes/paper/Page.tsx

@@ -1,7 +1,6 @@
 import {
   ArrowLeftIcon,
   ArrowRightIcon,
-  ChevronRightIcon,
   AdjustmentsHorizontalIcon,
   EyeIcon,
   SunIcon,
@@ -11,8 +10,8 @@ import {
 import { IconButton, useTheme } from '@raystack/apsara';
 import { useEffect, useMemo, useState } from 'react';
 import { Link as RouterLink, useLocation } from 'react-router';
-import { getBreadcrumbItems } from 'fumadocs-core/breadcrumb';
 import { flattenTree } from 'fumadocs-core/page-tree';
+import { Breadcrumbs } from '@/components/ui/breadcrumbs';
 import type { ThemePageProps } from '@/types';
 import styles from './Page.module.css';
 import { useReaderMode } from './ReaderModeContext';
@@ -27,21 +26,14 @@ export function Page({ page, tree }: ThemePageProps) {
 
   useEffect(() => { setIsClient(true); }, []);
 
-  const { prev, next, crumbs } = useMemo(() => {
+  const slug = pathname === '/' ? [] : pathname.replace(/^\//, '').split('/');
+
+  const { prev, next } = useMemo(() => {
     const pages = flattenTree(tree.children);
     const currentIndex = pages.findIndex(p => p.url === pathname);
-    const breadcrumbItems = getBreadcrumbItems(
-      pathname,
-      tree,
-      { includePage: true }
-    );
     return {
       prev: currentIndex > 0 ? pages[currentIndex - 1] : null,
       next: currentIndex < pages.length - 1 ? pages[currentIndex + 1] : null,
-      crumbs: breadcrumbItems.map(item => ({
-        label: item.name,
-        href: item.url ?? pathname,
-      })),
     };
   }, [tree, pathname]);
 
@@ -70,20 +62,7 @@ export function Page({ page, tree }: ThemePageProps) {
                 </span>
               )}
             </div>
-            <nav className={styles.breadcrumb}>
-              {crumbs.map((crumb, i) => (
-                <span key={crumb.href}>
-                  {i > 0 && <ChevronRightIcon width={12} height={12} className={styles.separator} />}
-                  {i === crumbs.length - 1 ? (
-                    <span className={styles.crumbActive}>{crumb.label}</span>
-                  ) : (
-                    <RouterLink to={crumb.href} className={styles.crumbLink}>
-                      {crumb.label}
-                    </RouterLink>
-                  )}
-                </span>
-              ))}
-            </nav>
+            <Breadcrumbs slug={slug} tree={tree} className={styles.breadcrumb} />
           </div>
           <div className={styles.navRight}>
             {settingsOpen ? (

package/src/themes/paper/Skeleton.tsx

@@ -0,0 +1,23 @@
+import { Skeleton } from '@raystack/apsara';
+import styles from './Page.module.css';
+
+export function PageSkeleton() {
+  return (
+    <main className={styles.main}>
+    <div className={styles.content}>
+        <header className={styles.articleHeader}>
+          <Skeleton width="50%" height="16px" containerClassName={styles.headerLoader}/>
+          <Skeleton width="70%" height="32px" containerClassName={styles.headerLoader}/>
+          <Skeleton width="50%" height="16px" containerClassName={styles.headerLoader}/>
+      </header>
+        <div className={styles.article}>
+          {
+            [...new Array(30)].map((_, i) => {
+              return <Skeleton key={i} width="100%" height="20px" containerClassName={styles.loader}/>
+            })
+          }
+      </div>
+    </div>
+    </main>
+  );
+}

package/src/themes/paper/index.ts

@@ -1,8 +1,10 @@
 import type { Theme } from '@/types';
 import { Layout } from './Layout';
 import { Page } from './Page';
+import { PageSkeleton } from './Skeleton';
 
 export const paperTheme: Theme = {
   Layout,
-  Page
+  Page,
+  Skeleton: PageSkeleton,
 };

package/src/types/theme.ts

@@ -20,5 +20,6 @@ export interface ThemePageProps {
 export interface Theme {
   Layout: React.ComponentType<ThemeLayoutProps>
   Page: React.ComponentType<ThemePageProps>
+  Skeleton: React.ComponentType
   className?: string
 }