@raystack/chronicle 0.7.4 → 0.8.0

package/src/themes/default/Layout.tsx

@@ -6,18 +6,22 @@ import {
   DocumentTextIcon,
   Squares2X2Icon
 } from '@heroicons/react/24/outline';
-import { Flex, IconButton, Sidebar } from '@raystack/apsara';
+import { Flex, IconButton, Button, Sidebar } from '@raystack/apsara';
+import { PlayIcon } from '@radix-ui/react-icons';
 import { cx } from 'class-variance-authority';
-import { useEffect, useMemo, useRef } from 'react';
+import { useState, useEffect, useMemo, useRef } from 'react';
 import { Link as RouterLink, useLocation, useNavigate } from 'react-router';
+import type { OpenAPIV3 } from 'openapi-types';
 import { MethodBadge } from '@/components/api/method-badge';
+import { useApiOperation } from '@/lib/use-api-operation';
+import { PlaygroundDialog } from '@/components/api/playground-dialog';
 import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
 import { Search } from '@/components/ui/search';
 import { Breadcrumbs } from '@/components/ui/breadcrumbs';
 import { getLandingEntries } from '@/lib/config';
 import { getActiveContentDir } from '@/lib/navigation';
 import { usePageContext } from '@/lib/page-context';
-import type { Node } from 'fumadocs-core/page-tree';
+import type { Node, Root } from 'fumadocs-core/page-tree';
 import type { ThemeLayoutProps } from '@/types';
 import styles from './Layout.module.css';
 import { OpenInAI } from './OpenInAI';
@@ -67,7 +71,12 @@ export function Layout({
   const isApiRoute = pathname === '/apis' || pathname.startsWith('/apis/');
   const isApiBase = (basePath: string) =>
     pathname === basePath || pathname.startsWith(`${basePath}/`);
-  const { prev, next } = page ?? { prev: null, next: null };
+  const docNav = page ?? { prev: null, next: null };
+  const apiNav = useMemo(() => {
+    if (!isApiRoute) return { prev: null, next: null };
+    return getApiPrevNext(pathname, tree);
+  }, [isApiRoute, pathname, tree]);
+  const { prev, next } = isApiRoute ? apiNav : docNav;
 
   const contentEntries = getLandingEntries(config, version.dir);
   const activeContentDir = getActiveContentDir(pathname, config);
@@ -151,11 +160,19 @@ export function Layout({
                 </div>
               ) : null}
               {tree.children.map((item, i) => (
-                <SidebarNode
-                  key={item.type === 'page' ? item.url : (item.name?.toString() ?? i)}
-                  item={item}
-                  pathname={pathname}
-                />
+                isApiRoute ? (
+                  <ApiSidebarNode
+                    key={item.type === 'page' ? item.url : (item.name?.toString() ?? i)}
+                    item={item}
+                    pathname={pathname}
+                  />
+                ) : (
+                  <SidebarNode
+                    key={item.type === 'page' ? item.url : (item.name?.toString() ?? i)}
+                    item={item}
+                    pathname={pathname}
+                  />
+                )
               ))}
             </Sidebar.Main>
             {config.versions?.length ? (
@@ -188,9 +205,13 @@ export function Layout({
                       <ArrowRightIcon width={14} height={14} />
                     </IconButton>
                   </Flex>
-                  {!isApiRoute && <Breadcrumbs slug={slug} tree={tree} />}
+                  <Breadcrumbs slug={slug} tree={tree} />
+                </Flex>
+                <Flex align='center' gap='small'>
+                  {isApiRoute && <TestRequestButton />}
+                  {isApiRoute && <ViewDocsButton />}
+                  <OpenInAI />
                 </Flex>
-                <OpenInAI />
               </nav>
               <main className={cx(styles.content, classNames?.content)}>
                 {children}
@@ -262,3 +283,133 @@ function SidebarNode({
     </Sidebar.Item>
   );
 }
+
+const methodColorMap: Record<string, string> = {
+  'method-get': 'var(--rs-color-foreground-success-primary)',
+  'method-post': 'var(--rs-color-foreground-accent-primary)',
+  'method-put': 'var(--rs-color-foreground-attention-primary)',
+  'method-delete': 'var(--rs-color-foreground-danger-primary)',
+  'method-patch': 'var(--rs-color-foreground-base-secondary)',
+};
+
+const methodLabelMap: Record<string, string> = {
+  'method-get': 'GET',
+  'method-post': 'POST',
+  'method-put': 'PUT',
+  'method-delete': 'DEL',
+  'method-patch': 'PATCH',
+};
+
+function ApiSidebarNode({ item, pathname }: { item: Node; pathname: string }) {
+  if (item.type === 'separator') return null;
+
+  if (item.type === 'folder') {
+    return (
+      <Flex direction='column' gap='small' className={styles.apiGroup}>
+        <span className={styles.apiGroupLabel}>{item.name?.toString()}</span>
+        <Flex direction='column'>
+          {item.children.map((child, i) => (
+            <ApiSidebarNode
+              key={child.type === 'page' ? child.url : (child.name?.toString() ?? i)}
+              item={child}
+              pathname={pathname}
+            />
+          ))}
+        </Flex>
+      </Flex>
+    );
+  }
+
+  const isActive = pathname === item.url;
+  const href = item.url ?? '#';
+  const iconKey = typeof item.icon === 'string' ? item.icon : '';
+  const methodLabel = methodLabelMap[iconKey];
+  const methodColor = methodColorMap[iconKey];
+
+  return (
+    <Flex
+      align='center'
+      gap='small'
+      className={`${styles.apiItem} ${isActive ? styles.apiItemActive : ''}`}
+      render={<RouterLink to={href} />}
+    >
+      <span className={styles.apiItemName}>{item.name}</span>
+      {methodLabel && (
+        <span className={styles.apiMethodText} style={{ color: methodColor }}>
+          {methodLabel}
+        </span>
+      )}
+    </Flex>
+  );
+}
+
+function TestRequestButton() {
+  const match = useApiOperation();
+  const [open, setOpen] = useState(false);
+  if (!match) return null;
+
+  return (
+    <>
+      <Button
+        variant='outline'
+        color='neutral'
+        size='small'
+        leadingIcon={<PlayIcon width={12} height={12} />}
+        onClick={() => setOpen(true)}
+      >
+        Test request
+      </Button>
+      <PlaygroundDialog
+        key={`${match.spec.name}-${match.path}-${match.method}`}
+        open={open}
+        onOpenChange={setOpen}
+        method={match.method}
+        path={match.path}
+        operation={match.operation}
+        serverUrl={match.spec.server.url}
+        specName={match.spec.name}
+        auth={match.spec.auth}
+        document={match.spec.document}
+      />
+    </>
+  );
+}
+
+function ViewDocsButton() {
+  const match = useApiOperation();
+  if (!match) return null;
+
+  const operation = match.operation as OpenAPIV3.OperationObject;
+  const docsUrl = operation.externalDocs?.url ?? match.spec.document.externalDocs?.url;
+  if (!docsUrl) return null;
+
+  return (
+    <Button
+      variant='outline'
+      color='neutral'
+      size='small'
+      leadingIcon={<DocumentTextIcon width={12} height={12} />}
+      onClick={() => window.open(docsUrl, '_blank', 'noopener,noreferrer')}
+    >
+      View documentation
+    </Button>
+  );
+}
+
+function getApiPrevNext(pathname: string, tree: Root): { prev: { url: string; title: string } | null; next: { url: string; title: string } | null } {
+  const pages: { url: string; title: string }[] = [];
+  function collect(node: Node) {
+    if (node.type === 'page') {
+      pages.push({ url: node.url, title: node.name?.toString() ?? '' });
+    } else if (node.type === 'folder') {
+      for (const child of node.children) collect(child);
+    }
+  }
+  for (const child of tree.children) collect(child);
+
+  const idx = pages.findIndex(p => p.url === pathname);
+  return {
+    prev: idx > 0 ? pages[idx - 1] : null,
+    next: idx >= 0 && idx < pages.length - 1 ? pages[idx + 1] : null,
+  };
+}

package/src/types/config.ts

@@ -86,6 +86,7 @@ const contentEntrySchema = z.object({
   label: z.string().min(1),
   description: z.string().optional(),
   icon: z.string().optional(),
+  index_page: z.string().optional(),
 })
 
 // Variants map to Apsara Badge color prop.

package/src/components/api/code-snippets.module.css

@@ -1,7 +0,0 @@
-.snippets {
-  width: 100%;
-}
-
-.snippets :global([class*="code-block-module_header"]) {
-  justify-content: space-between;
-}

package/src/components/api/code-snippets.tsx

@@ -1,76 +0,0 @@
-"use client";
-
-import { useMemo, useState } from "react";
-import { CodeBlock } from "@raystack/apsara";
-import {
-  generateCurl,
-  generatePython,
-  generateGo,
-  generateTypeScript,
-} from "@/lib/snippet-generators";
-import styles from "./code-snippets.module.css";
-
-interface CodeSnippetsProps {
-  method: string;
-  url: string;
-  headers: Record<string, string>;
-  body?: string;
-}
-
-const languages = [
-  { value: "curl", label: "cURL", lang: "curl", generate: generateCurl },
-  {
-    value: "python",
-    label: "Python",
-    lang: "python",
-    generate: generatePython,
-  },
-  { value: "go", label: "Go", lang: "go", generate: generateGo },
-  {
-    value: "typescript",
-    label: "TypeScript",
-    lang: "typescript",
-    generate: generateTypeScript,
-  },
-];
-
-export function CodeSnippets({
-  method,
-  url,
-  headers,
-  body,
-}: CodeSnippetsProps) {
-  const opts = { method, url, headers, body };
-  const [selected, setSelected] = useState("curl");
-  const current = languages.find((l) => l.value === selected) ?? languages[0];
-
-  const code = useMemo(
-    () => current.generate(opts),
-    [selected, method, url, headers, body],
-  );
-
-  return (
-    <CodeBlock
-      value={selected}
-      onValueChange={setSelected}
-      className={styles.snippets}
-    >
-      <CodeBlock.Header>
-        <CodeBlock.LanguageSelect>
-          <CodeBlock.LanguageSelectTrigger />
-          <CodeBlock.LanguageSelectContent>
-            {languages.map((l) => (
-              <CodeBlock.LanguageSelectItem key={l.value} value={l.value}>
-                {l.label}
-              </CodeBlock.LanguageSelectItem>
-            ))}
-          </CodeBlock.LanguageSelectContent>
-        </CodeBlock.LanguageSelect>
-        <CodeBlock.CopyButton />
-      </CodeBlock.Header>
-      <CodeBlock.Content>
-        <CodeBlock.Code language={current.lang}>{code}</CodeBlock.Code>
-      </CodeBlock.Content>
-    </CodeBlock>
-  );
-}

package/src/components/api/endpoint-page.module.css

@@ -1,58 +0,0 @@
-.layout {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: var(--rs-space-9);
-  padding: var(--rs-space-7);
-  max-width: 1400px;
-}
-
-.left {
-  gap: var(--rs-space-7);
-  min-width: 0;
-}
-
-.right {
-  gap: var(--rs-space-5);
-  min-width: 0;
-}
-
-.title {
-  margin: 0;
-}
-
-.description {
-  color: var(--rs-color-foreground-base-secondary);
-}
-
-.methodPath {
-  gap: var(--rs-space-3);
-  padding: var(--rs-space-4) var(--rs-space-5);
-  border: 1px solid var(--rs-color-border-base-primary);
-  border-radius: 8px;
-  background: var(--rs-color-background-base-secondary);
-  overflow: hidden;
-}
-
-.path {
-  font-family: monospace;
-  flex: 1;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-.tryButton {
-  margin-left: auto;
-  flex-shrink: 0;
-}
-
-@media (max-width: 900px) {
-  .layout {
-    grid-template-columns: 1fr;
-  }
-
-  .right {
-    position: static;
-  }
-}

package/src/components/api/endpoint-page.tsx

@@ -1,283 +0,0 @@
-'use client'
-
-import { useState, useCallback } from 'react'
-import type { OpenAPIV3 } from 'openapi-types'
-import { Flex, Text, Headline, Button, CodeBlock } from '@raystack/apsara'
-import { MethodBadge } from './method-badge'
-import { FieldSection } from './field-section'
-import { KeyValueEditor, type KeyValueEntry } from './key-value-editor'
-import { CodeSnippets } from './code-snippets'
-import { ResponsePanel } from './response-panel'
-import { flattenSchema, generateExampleJson, type SchemaField } from '@/lib/schema'
-import styles from './endpoint-page.module.css'
-
-interface EndpointPageProps {
-  method: string
-  path: string
-  operation: OpenAPIV3.OperationObject
-  serverUrl: string
-  specName: string
-  auth?: { type: string; header: string; placeholder?: string }
-}
-
-export function EndpointPage({ method, path, operation, serverUrl, specName, auth }: EndpointPageProps) {
-  const params = (operation.parameters ?? []) as OpenAPIV3.ParameterObject[]
-  const body = getRequestBody(operation.requestBody as OpenAPIV3.RequestBodyObject | undefined)
-
-  const headerFields = paramsToFields(params.filter((p) => p.in === 'header'))
-  const headerLocations = Object.fromEntries(headerFields.map((f) => [f.name, 'header']))
-  const pathFields = paramsToFields(params.filter((p) => p.in === 'path'))
-  const pathLocations = Object.fromEntries(pathFields.map((f) => [f.name, 'path']))
-  const queryFields = paramsToFields(params.filter((p) => p.in === 'query'))
-  const queryLocations = Object.fromEntries(queryFields.map((f) => [f.name, 'query']))
-  const responses = getResponseSections(operation.responses as Record<string, OpenAPIV3.ResponseObject>)
-
-  // State for editable fields
-  const [customHeaders, setCustomHeaders] = useState<KeyValueEntry[]>(() => {
-    const initial: KeyValueEntry[] = []
-    if (auth) initial.push({ key: auth.header, value: '' })
-    return initial
-  })
-  const [headerValues, setHeaderValues] = useState<Record<string, unknown>>({})
-  const [pathValues, setPathValues] = useState<Record<string, unknown>>({})
-  const [queryValues, setQueryValues] = useState<Record<string, unknown>>({})
-  const [bodyValues, setBodyValues] = useState<Record<string, unknown>>(() => {
-    try { return body?.jsonExample ? JSON.parse(body.jsonExample) : {} }
-    catch { return {} }
-  })
-  const [bodyJsonStr, setBodyJsonStr] = useState(body?.jsonExample ?? '{}')
-  const [responseBody, setResponseBody] = useState<{ status: number; statusText: string; body: unknown } | null>(null)
-  const [loading, setLoading] = useState(false)
-
-  // Two-way sync: fields → JSON
-  const handleBodyValuesChange = useCallback((values: Record<string, unknown>) => {
-    setBodyValues(values)
-    setBodyJsonStr(JSON.stringify(values, null, 2))
-  }, [])
-
-  // Two-way sync: JSON → fields
-  const handleBodyJsonChange = useCallback((jsonStr: string) => {
-    setBodyJsonStr(jsonStr)
-    try {
-      setBodyValues(JSON.parse(jsonStr))
-    } catch { /* ignore invalid JSON while typing */ }
-  }, [])
-
-  // Try it handler
-  const handleTryIt = useCallback(async () => {
-    setLoading(true)
-    setResponseBody(null)
-
-    let resolvedPath = path
-    for (const [key, value] of Object.entries(pathValues)) {
-      resolvedPath = resolvedPath.replace(`{${key}}`, encodeURIComponent(String(value)))
-    }
-
-    const queryEntries = Object.entries(queryValues).filter(([, v]) => v !== undefined && v !== '')
-    const queryString = queryEntries
-      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
-      .join('&')
-    const fullPath = queryString ? `${resolvedPath}?${queryString}` : resolvedPath
-
-    const reqHeaders: Record<string, string> = {}
-    for (const [key, value] of Object.entries(headerValues)) {
-      if (value !== undefined && value !== null && value !== '') reqHeaders[key] = String(value)
-    }
-    for (const entry of customHeaders) {
-      if (entry.key && entry.value) reqHeaders[entry.key] = entry.value
-    }
-    if (body && bodyJsonStr) {
-      reqHeaders['Content-Type'] = body.contentType ?? 'application/json'
-    }
-
-    try {
-      const res = await fetch('/api/apis-proxy', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          specName,
-          method,
-          path: fullPath,
-          headers: reqHeaders,
-          body: body ? bodyValues : undefined,
-        }),
-      })
-      const data = await res.json()
-      if (data.status !== undefined) {
-        setResponseBody(data)
-      } else {
-        setResponseBody({ status: res.status, statusText: res.statusText, body: data.error ?? data })
-      }
-    } catch (err) {
-      console.error('API request failed:', err)
-      setResponseBody({ status: 0, statusText: 'Error', body: 'Failed to send request' })
-    } finally {
-      setLoading(false)
-    }
-  }, [specName, method, path, pathValues, queryValues, headerValues, customHeaders, bodyValues, bodyJsonStr, body])
-
-  // Snippet display values
-  const fullUrl = '{domain}' + 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'
-  }
-
-  return (
-    <div className={styles.layout}>
-      <Flex direction="column" className={styles.left}>
-        {operation.summary && (
-          <Headline size="small" as="h1" className={styles.title}>{operation.summary}</Headline>
-        )}
-        {operation.description && (
-          <Text size={3} className={styles.description}>{operation.description}</Text>
-        )}
-
-        <Flex align="center" className={styles.methodPath}>
-          <MethodBadge method={method} />
-          <Text size={3} className={styles.path}>{path}</Text>
-          <Button variant="solid" size="small" className={styles.tryButton} onClick={handleTryIt} disabled={loading}>
-            {loading ? 'Sending...' : 'Send'}
-          </Button>
-        </Flex>
-
-        <FieldSection
-          title="Headers"
-          fields={headerFields}
-          locations={headerLocations}
-          editable
-          values={headerValues}
-          onValuesChange={setHeaderValues}
-        >
-          <KeyValueEditor entries={customHeaders} onChange={setCustomHeaders} />
-        </FieldSection>
-        <FieldSection
-          title="Path"
-          fields={pathFields}
-          locations={pathLocations}
-          editable
-          values={pathValues}
-          onValuesChange={setPathValues}
-        />
-        <FieldSection
-          title="Query Parameters"
-          fields={queryFields}
-          locations={queryLocations}
-          editable
-          values={queryValues}
-          onValuesChange={setQueryValues}
-        />
-        {body && (
-          <FieldSection
-            title="Body"
-            label={body?.contentType}
-            fields={body?.fields ?? []}
-            jsonExample={bodyJsonStr}
-            editableJson
-            onJsonChange={handleBodyJsonChange}
-            alwaysShow
-            editable
-            values={bodyValues}
-            onValuesChange={handleBodyValuesChange}
-          />
-        )}
-
-        {responses.map((resp) => (
-          <FieldSection
-            key={resp.status}
-            title={`${resp.status}${resp.description ? ` — ${resp.description}` : ''}`}
-            fields={resp.fields}
-            jsonExample={resp.jsonExample}
-          />
-        ))}
-      </Flex>
-      <Flex direction="column" className={styles.right}>
-        <CodeSnippets
-          method={method}
-          url={fullUrl}
-          headers={snippetHeaders}
-          body={body ? bodyJsonStr : undefined}
-        />
-        <ResponsePanel responses={responses} />
-        {responseBody && (
-          <Flex direction="column" gap="small">
-            <Text size={3} weight="medium">
-              Response — {responseBody.status} {responseBody.statusText}
-            </Text>
-            <CodeBlock>
-              <CodeBlock.Header>
-                <CodeBlock.CopyButton />
-              </CodeBlock.Header>
-              <CodeBlock.Content>
-                <CodeBlock.Code language="json">
-                  {typeof responseBody.body === 'string'
-                    ? (responseBody.body || 'No response body')
-                    : (JSON.stringify(responseBody.body, null, 2) ?? 'No response body')}
-                </CodeBlock.Code>
-              </CodeBlock.Content>
-            </CodeBlock>
-          </Flex>
-        )}
-      </Flex>
-    </div>
-  )
-}
-
-function paramsToFields(params: OpenAPIV3.ParameterObject[]): SchemaField[] {
-  return params.map((p) => {
-    const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject
-    return {
-      name: p.name,
-      type: schema.type ? String(schema.type) : 'string',
-      required: p.required ?? false,
-      description: p.description,
-      default: schema.default,
-    }
-  })
-}
-
-interface RequestBody {
-  contentType: string
-  fields: SchemaField[]
-  jsonExample: string
-}
-
-function getRequestBody(body: OpenAPIV3.RequestBodyObject | undefined): RequestBody | null {
-  if (!body?.content) return null
-  const contentType = Object.keys(body.content)[0]
-  if (!contentType) return null
-  const schema = body.content[contentType]?.schema as OpenAPIV3.SchemaObject | undefined
-  if (!schema) return null
-  return {
-    contentType,
-    fields: flattenSchema(schema),
-    jsonExample: JSON.stringify(generateExampleJson(schema), null, 2),
-  }
-}
-
-interface ResponseSection {
-  status: string
-  description?: string
-  fields: SchemaField[]
-  jsonExample?: string
-}
-
-function getResponseSections(responses: Record<string, OpenAPIV3.ResponseObject>): ResponseSection[] {
-  return Object.entries(responses).map(([status, resp]) => {
-    const content = resp.content ?? {}
-    const contentType = Object.keys(content)[0]
-    const schema = contentType
-      ? (content[contentType]?.schema as OpenAPIV3.SchemaObject | undefined)
-      : undefined
-
-    return {
-      status,
-      description: resp.description,
-      fields: schema ? flattenSchema(schema) : [],
-      jsonExample: schema ? JSON.stringify(generateExampleJson(schema), null, 2) : undefined,
-    }
-  })
-}