@raystack/chronicle 0.1.0-canary.1f5227c

package/src/components/mdx/mermaid.tsx

@@ -0,0 +1,37 @@
+'use client'
+
+import { useEffect, useId, useState } from 'react'
+import styles from './mermaid.module.css'
+
+interface MermaidProps {
+  chart: string
+}
+
+export function Mermaid({ chart }: MermaidProps) {
+  const mermaidId = useId().replace(/:/g, '-')
+  const [svg, setSvg] = useState<string>('')
+
+  useEffect(() => {
+    let cancelled = false
+
+    async function render() {
+      const { default: mermaid } = await import('mermaid')
+      mermaid.initialize({ startOnLoad: false, theme: 'default' })
+      const { svg: rendered } = await mermaid.render(
+        mermaidId,
+        chart
+      )
+      if (!cancelled) setSvg(rendered)
+    }
+
+    render()
+    return () => { cancelled = true }
+  }, [chart])
+
+  return (
+    <div
+      className={styles.mermaid}
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  )
+}

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

@@ -0,0 +1,8 @@
+.paragraph {
+  font-size: var(--rs-font-size-regular);
+  margin-bottom: var(--rs-space-5);
+}
+
+.paragraph :global(a) {
+  font-size: inherit;
+}

package/src/components/mdx/paragraph.tsx

@@ -0,0 +1,19 @@
+import { Children, isValidElement, type ComponentProps } from 'react'
+import styles from './paragraph.module.css'
+
+const BLOCK_ELEMENTS = new Set(['summary', 'details', 'div', 'table', 'ul', 'ol'])
+
+function hasBlockChild(children: React.ReactNode): boolean {
+  return Children.toArray(children).some(
+    (child) => isValidElement(child) && typeof child.type === 'string' && BLOCK_ELEMENTS.has(child.type)
+  )
+}
+
+export function MdxParagraph({ children, className, ...props }: ComponentProps<'p'>) {
+  const Tag = hasBlockChild(children) ? 'div' : 'p'
+  return (
+    <Tag className={`${styles.paragraph} ${className ?? ''}`} {...props}>
+      {children}
+    </Tag>
+  )
+}

package/src/components/mdx/table.tsx

@@ -0,0 +1,40 @@
+'use client'
+
+import { Table } from '@raystack/apsara'
+import type { ComponentProps, ReactNode } from 'react'
+
+type TableProps = ComponentProps<'table'>
+
+export function MdxTable({ children, ...props }: TableProps) {
+  return <Table {...props}>{children}</Table>
+}
+
+type TheadProps = ComponentProps<'thead'>
+
+export function MdxThead({ children, ...props }: TheadProps) {
+  return <Table.Header {...props}>{children}</Table.Header>
+}
+
+type TbodyProps = ComponentProps<'tbody'>
+
+export function MdxTbody({ children, ...props }: TbodyProps) {
+  return <Table.Body {...props}>{children}</Table.Body>
+}
+
+type TrProps = ComponentProps<'tr'>
+
+export function MdxTr({ children, ...props }: TrProps) {
+  return <Table.Row {...props}>{children}</Table.Row>
+}
+
+type ThProps = ComponentProps<'th'>
+
+export function MdxTh({ children, ...props }: ThProps) {
+  return <Table.Head {...props}>{children}</Table.Head>
+}
+
+type TdProps = ComponentProps<'td'>
+
+export function MdxTd({ children, ...props }: TdProps) {
+  return <Table.Cell {...props}>{children}</Table.Cell>
+}

package/src/components/ui/breadcrumbs.tsx

@@ -0,0 +1,72 @@
+'use client'
+
+import { Breadcrumb } from '@raystack/apsara'
+import type { PageTree, PageTreeItem } from '@/types'
+
+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
+}
+
+export function Breadcrumbs({ slug, tree }: BreadcrumbsProps) {
+  const items: { label: string; href: string }[] = []
+
+  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,
+    })
+  }
+
+  return (
+    <Breadcrumb size="small">
+      {items.flatMap((item, index) => {
+        const breadcrumbItem = (
+          <Breadcrumb.Item
+            key={`item-${index}`}
+            href={item.href}
+            current={index === items.length - 1}
+          >
+            {item.label}
+          </Breadcrumb.Item>
+        )
+        if (index === 0) return [breadcrumbItem]
+        return [
+          <Breadcrumb.Separator key={`sep-${index}`} style={{ display: 'flex' }} />,
+          breadcrumbItem,
+        ]
+      })}
+    </Breadcrumb>
+  )
+}

package/src/components/ui/client-theme-switcher.tsx

@@ -0,0 +1,18 @@
+'use client'
+
+import { ThemeSwitcher } from '@raystack/apsara'
+import { useState, useEffect } from 'react'
+
+interface ClientThemeSwitcherProps {
+  size?: number
+}
+
+export function ClientThemeSwitcher({ size }: ClientThemeSwitcherProps) {
+  const [isClient, setIsClient] = useState(false)
+
+  useEffect(() => {
+    setIsClient(true)
+  }, [])
+
+  return isClient ? <ThemeSwitcher size={size} /> : null
+}

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

@@ -0,0 +1,27 @@
+.footer {
+  border-top: 1px solid var(--rs-color-border-base-primary);
+  padding: var(--rs-space-5) var(--rs-space-7);
+}
+
+.container {
+  max-width: 1200px;
+  margin: 0 auto;
+  width: 100%;
+}
+
+.copyright {
+  color: var(--rs-color-foreground-base-secondary);
+}
+
+.links {
+  flex-wrap: wrap;
+}
+
+.link {
+  color: var(--rs-color-foreground-base-secondary);
+  font-size: 14px;
+}
+
+.link:hover {
+  color: var(--rs-color-foreground-base-primary);
+}

package/src/components/ui/footer.tsx

@@ -0,0 +1,31 @@
+import { Link } from "react-router-dom";
+import { Flex, Text } from "@raystack/apsara";
+import type { FooterConfig } from "@/types";
+import styles from "./footer.module.css";
+
+interface FooterProps {
+  config?: FooterConfig;
+}
+
+export function Footer({ config }: FooterProps) {
+  return (
+    <footer className={styles.footer}>
+      <Flex align="center" justify="between" className={styles.container}>
+        {config?.copyright && (
+          <Text size={2} className={styles.copyright}>
+            {config.copyright}
+          </Text>
+        )}
+        {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.label}
+              </Link>
+            ))}
+          </Flex>
+        )}
+      </Flex>
+    </footer>
+  );
+}

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

@@ -0,0 +1,111 @@
+.trigger {
+  gap: 8px;
+  color: var(--rs-color-foreground-base-secondary);
+  cursor: pointer;
+}
+
+.kbd {
+  padding: 2px 6px;
+  border-radius: 4px;
+  border: 1px solid var(--rs-color-border-base-primary);
+  font-size: 12px;
+}
+
+.dialogContent {
+  max-width: 600px;
+  padding: 0;
+  min-height: 0;
+  position: fixed;
+  top: 20%;
+  left: 50%;
+  transform: translateX(-50%);
+  border-radius: var(--rs-radius-4);
+}
+
+.input {
+  flex: 1;
+  border: none;
+  outline: none;
+  background: transparent;
+  font-size: 16px;
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.list {
+  max-height: 300px;
+  overflow: auto;
+  padding: 0;
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.item {
+  padding: 12px 16px;
+  cursor: pointer;
+  border-radius: 6px;
+}
+
+.item[data-selected="true"] {
+  background: var(--rs-color-background-base-secondary);
+  color: var(--rs-color-foreground-accent-primary-hover);
+}
+
+.itemContent {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+.resultText {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.headingText {
+  color: var(--rs-color-foreground-base-secondary);
+}
+
+.item[data-selected="true"] .headingText {
+  color: var(--rs-color-foreground-accent-primary-hover);
+}
+
+.separator {
+  color: var(--rs-color-foreground-base-secondary);
+}
+
+.pageText {
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.item[data-selected="true"] .pageText {
+  color: var(--rs-color-foreground-accent-primary-hover);
+}
+
+.icon {
+  width: 18px;
+  height: 18px;
+  color: var(--rs-color-foreground-base-secondary);
+  flex-shrink: 0;
+}
+
+.item[data-selected="true"] .icon {
+  color: var(--rs-color-foreground-accent-primary-hover);
+}
+
+.pageText :global(mark),
+.headingText :global(mark) {
+  background: transparent;
+  color: var(--rs-color-foreground-accent-primary);
+  font-weight: 600;
+}

package/src/components/ui/search.tsx

@@ -0,0 +1,174 @@
+"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 { isMacOs } from "react-device-detect";
+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 };
+}
+
+function SearchShortcutKey({ className }: { className?: string }) {
+  const [key, setKey] = useState("\u2318");
+
+  useEffect(() => {
+    setKey(isMacOs ? "\u2318" : "Ctrl");
+  }, []);
+
+  return (
+    <kbd className={className} suppressHydrationWarning>
+      {key} K
+    </kbd>
+  );
+}
+
+interface SearchProps {
+  className?: string;
+}
+
+export function Search({ className }: SearchProps) {
+  const [open, setOpen] = useState(false);
+  const navigate = useNavigate();
+  const [search, setSearch] = useState("");
+  const { results, isLoading } = useSearch(search);
+
+  const onSelect = useCallback(
+    (url: string) => {
+      setOpen(false);
+      navigate(url);
+    },
+    [navigate],
+  );
+
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen((open) => !open);
+      }
+    };
+
+    document.addEventListener("keydown", down);
+    return () => document.removeEventListener("keydown", down);
+  }, []);
+
+  return (
+    <>
+      <Button
+        variant="outline"
+        color="neutral"
+        size="small"
+        onClick={() => setOpen(true)}
+        className={cx(styles.trigger, className)}
+        trailingIcon={<SearchShortcutKey className={styles.kbd} />}
+      >
+        Search...
+      </Button>
+
+      <Dialog open={open} onOpenChange={setOpen}>
+        <Dialog.Content className={styles.dialogContent}>
+          <Dialog.Title className={styles.visuallyHidden}>
+            Search documentation
+          </Dialog.Title>
+          <Command loop>
+            <Command.Input
+              placeholder="Search"
+              value={search}
+              onValueChange={setSearch}
+              className={styles.input}
+            />
+
+            <Command.List className={styles.list}>
+              {isLoading && <Command.Empty>Loading...</Command.Empty>}
+              {!isLoading &&
+                search.length > 0 &&
+                results.length === 0 && (
+                  <Command.Empty>No results found.</Command.Empty>
+                )}
+              {!isLoading &&
+                search.length === 0 &&
+                results.length > 0 && (
+                  <Command.Group heading="Suggestions">
+                    {results.slice(0, 8).map((result) => (
+                      <Command.Item
+                        key={result.id}
+                        value={result.id}
+                        onSelect={() => onSelect(result.url)}
+                        className={styles.item}
+                      >
+                        <div className={styles.itemContent}>
+                          {getResultIcon(result)}
+                          <Text className={styles.pageText}>
+                            {result.content}
+                          </Text>
+                        </div>
+                      </Command.Item>
+                    ))}
+                  </Command.Group>
+                )}
+              {search.length > 0 &&
+                results.map((result) => (
+                  <Command.Item
+                    key={result.id}
+                    value={result.id}
+                    onSelect={() => onSelect(result.url)}
+                    className={styles.item}
+                  >
+                    <div className={styles.itemContent}>
+                      {getResultIcon(result)}
+                      <Text className={styles.pageText}>
+                        {result.content}
+                      </Text>
+                    </div>
+                  </Command.Item>
+                ))}
+            </Command.List>
+          </Command>
+        </Dialog.Content>
+      </Dialog>
+    </>
+  );
+}
+
+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;
+  }
+  return <DocumentIcon className={styles.icon} />;
+}

package/src/lib/api-routes.ts

@@ -0,0 +1,120 @@
+import type { OpenAPIV3 } from 'openapi-types'
+import slugify from 'slugify'
+import type { PageTree, PageTreeItem } from '@/types/content'
+import type { ApiSpec } from './openapi'
+
+export function getSpecSlug(spec: ApiSpec): string {
+  return slugify(spec.name, { lower: true, strict: true })
+}
+
+
+export function buildApiRoutes(specs: ApiSpec[]): { slug: string[] }[] {
+  const routes: { slug: string[] }[] = []
+
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec)
+    const paths = spec.document.paths ?? {}
+
+    for (const [, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method]
+        if (!op?.operationId) continue
+        routes.push({ slug: [specSlug, encodeURIComponent(op.operationId)] })
+      }
+    }
+  }
+
+  return routes
+}
+
+export interface ApiRouteMatch {
+  spec: ApiSpec
+  operation: OpenAPIV3.OperationObject
+  method: string
+  path: string
+}
+
+export function findApiOperation(specs: ApiSpec[], slug: string[]): ApiRouteMatch | null {
+  if (slug.length !== 2) return null
+  const [specSlug, operationId] = slug
+
+  const spec = specs.find((s) => getSpecSlug(s) === specSlug)
+  if (!spec) return null
+
+  const paths = spec.document.paths ?? {}
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem) continue
+    for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+      const op = pathItem[method]
+      if (op?.operationId && encodeURIComponent(op.operationId) === operationId) {
+        return { spec, operation: op, method: method.toUpperCase(), path: pathStr }
+      }
+    }
+  }
+
+  return null
+}
+
+export function buildApiPageTree(specs: ApiSpec[]): PageTree {
+  const children: PageTreeItem[] = []
+
+  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 tagDisplayName = new Map<string, string>()
+
+    for (const [, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method]
+        if (!op?.operationId) continue
+
+        const rawTag = op.tags?.[0] ?? 'default'
+        const tagKey = rawTag.toLowerCase()
+        if (!opsByTag.has(tagKey)) {
+          opsByTag.set(tagKey, [])
+          tagDisplayName.set(tagKey, rawTag.charAt(0).toUpperCase() + rawTag.slice(1))
+        }
+
+        opsByTag.get(tagKey)!.push({
+          type: 'page',
+          name: op.summary ?? op.operationId,
+          url: `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`,
+          icon: `method-${method}`,
+        })
+      }
+    }
+
+    // Use doc.tags display names where available
+    for (const t of tags) {
+      const key = t.name.toLowerCase()
+      if (opsByTag.has(key)) {
+        tagDisplayName.set(key, t.name.charAt(0).toUpperCase() + t.name.slice(1))
+      }
+    }
+
+    const tagFolders: PageTreeItem[] = Array.from(opsByTag.entries()).map(([key, ops]) => ({
+      type: 'folder' as const,
+      name: tagDisplayName.get(key) ?? key,
+      icon: 'rectangle-stack',
+      children: ops,
+    }))
+
+    if (specs.length > 1) {
+      children.push({
+        type: 'folder',
+        name: spec.name,
+        children: tagFolders,
+      })
+    } else {
+      children.push(...tagFolders)
+    }
+  }
+
+  return { name: 'API Reference', children }
+}