@raystack/chronicle 0.7.3 → 0.8.0

package/dist/cli/index.js

@@ -337,6 +337,7 @@ async function createViteConfig(options) {
   const contentMirror = path6.resolve(packageRoot, ".content");
   return {
     root: packageRoot,
+    publicDir: path6.resolve(projectRoot, "public"),
     configFile: false,
     plugins: [
       nitro({
@@ -420,6 +421,7 @@ async function createViteConfig(options) {
     },
     nitro: {
       logLevel: 2,
+      publicAssets: [{ dir: path6.resolve(projectRoot, "public") }],
       output: {
         dir: resolveOutputDir(projectRoot, preset)
       }
@@ -514,7 +516,8 @@ var contentEntrySchema = z.object({
   dir: dirNameSchema,
   label: z.string().min(1),
   description: z.string().optional(),
-  icon: z.string().optional()
+  icon: z.string().optional(),
+  index_page: z.string().optional()
 });
 var badgeVariantSchema = z.enum([
   "accent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -46,6 +46,7 @@
     "@opentelemetry/resources": "^2.6.1",
     "@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",
     "@shikijs/rehype": "^4.0.2",
     "@vitejs/plugin-react": "^6.0.1",

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

@@ -0,0 +1,23 @@
+.container {
+  border: 0.5px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  overflow: hidden;
+  width: 100%;
+}
+
+.header {
+  justify-content: space-between;
+}
+
+.title {
+  font-size: var(--rs-font-size-regular);
+  font-weight: var(--rs-font-weight-regular);
+  line-height: var(--rs-line-height-regular);
+  letter-spacing: var(--rs-letter-spacing-regular);
+  color: var(--rs-color-foreground-base-primary);
+  white-space: nowrap;
+}
+
+.body {
+  background: var(--rs-color-background-base-primary);
+}

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

@@ -0,0 +1,64 @@
+'use client'
+
+import { useMemo, useState } from 'react'
+import { CodeBlock, Flex } from '@raystack/apsara'
+import {
+  generateCurl,
+  generatePython,
+  generateGo,
+  generateTypeScript,
+} from '@/lib/snippet-generators'
+import styles from './api-code-snippet.module.css'
+
+interface ApiCodeSnippetProps {
+  title: string
+  method: string
+  url: string
+  headers: Record<string, string>
+  body?: string
+}
+
+const languages = [
+  { value: 'curl', label: 'cURL', lang: 'bash', 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 ApiCodeSnippet({ title, method, url, headers, body }: ApiCodeSnippetProps) {
+  const [selected, setSelected] = useState('curl')
+  const current = languages.find((l) => l.value === selected) ?? languages[0]
+
+  const code = useMemo(
+    () => current.generate({ method, url, headers, body }),
+    [current.generate, method, url, headers, body],
+  )
+
+  return (
+    <CodeBlock
+      value={selected}
+      onValueChange={setSelected}
+      className={styles.container}
+    >
+      <CodeBlock.Header className={styles.header}>
+        <CodeBlock.Label className={styles.title}>{title}</CodeBlock.Label>
+        <Flex align='center' gap={4}>
+          <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 />
+        </Flex>
+      </CodeBlock.Header>
+      <CodeBlock.Content className={styles.body}>
+        <CodeBlock.Code value={selected} language={current.lang}>{code}</CodeBlock.Code>
+      </CodeBlock.Content>
+    </CodeBlock>
+  )
+}

package/src/components/api/api-field-list.module.css

@@ -0,0 +1,76 @@
+.sectionTitle {
+  font-size: var(--rs-font-size-large);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-large);
+  letter-spacing: var(--rs-letter-spacing-large);
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.fieldItem {
+  padding-bottom: var(--rs-space-5);
+  border-bottom: 0.5px solid var(--rs-color-border-base-primary);
+}
+
+.fieldItem:last-child {
+  border-bottom: none;
+  padding-bottom: 0;
+}
+
+.fieldType {
+  font-size: var(--rs-font-size-small);
+  line-height: var(--rs-line-height-small);
+  letter-spacing: var(--rs-letter-spacing-small);
+  color: var(--rs-color-foreground-base-secondary);
+}
+
+.fieldDescription {
+  font-size: var(--rs-font-size-small);
+  line-height: var(--rs-line-height-small);
+  letter-spacing: var(--rs-letter-spacing-small);
+  color: var(--rs-color-foreground-base-secondary);
+}
+
+.fieldExample {
+  font-size: var(--rs-font-size-small);
+  line-height: var(--rs-line-height-small);
+  color: var(--rs-color-foreground-base-tertiary);
+}
+
+.fieldExample code {
+  font-family: var(--rs-font-mono);
+  font-size: var(--rs-font-size-mono-small);
+  background: var(--rs-color-background-neutral-secondary);
+  padding: 1px var(--rs-space-2);
+  border-radius: 3px;
+}
+
+.statusDescription {
+  font-size: var(--rs-font-size-regular);
+  line-height: var(--rs-line-height-regular);
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.expandButton {
+  padding: var(--rs-space-3) var(--rs-space-4);
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  background: var(--rs-color-background-base-secondary);
+  cursor: pointer;
+  width: 100%;
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.expandButton:hover {
+  background: var(--rs-color-background-neutral-secondary);
+}
+
+.expandLabel {
+  font-size: var(--rs-font-size-small);
+  line-height: var(--rs-line-height-small);
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.childFields {
+  padding-left: var(--rs-space-5);
+  margin-top: var(--rs-space-3);
+}

package/src/components/api/api-field-list.tsx

@@ -0,0 +1,91 @@
+'use client'
+
+import { useState, type ReactNode } from 'react'
+import { Badge, Flex } from '@raystack/apsara'
+import { ChevronRightIcon, ChevronDownIcon } from '@radix-ui/react-icons'
+import type { SchemaField } from '@/lib/schema'
+import styles from './api-field-list.module.css'
+
+interface ApiFieldSectionProps {
+  title: string
+  fields: SchemaField[]
+  headerRight?: ReactNode
+  description?: string
+}
+
+export function ApiFieldSection({ title, fields, headerRight, description }: ApiFieldSectionProps) {
+  if (fields.length === 0 && !description) return null
+
+  return (
+    <Flex direction="column" gap={6}>
+      <Flex align="center" justify="between">
+        <span className={styles.sectionTitle}>{title}</span>
+        {headerRight && (
+          <Flex align="center" gap={3}>
+            {headerRight}
+          </Flex>
+        )}
+      </Flex>
+      {description && <span className={styles.statusDescription}>{description}</span>}
+      <Flex direction="column" gap={5}>
+        {fields.map((field) => (
+          <FieldItem key={field.name} field={field} />
+        ))}
+      </Flex>
+    </Flex>
+  )
+}
+
+function FieldItem({ field }: { field: SchemaField }) {
+  const hasChildren = field.children && field.children.length > 0
+
+  return (
+    <Flex direction="column" gap={4} className={styles.fieldItem}>
+      <Flex align="center" gap={3}>
+        <Badge variant="neutral" size="micro">{field.name}</Badge>
+        <span className={styles.fieldType}>{field.type}</span>
+        {field.required && <Badge variant="danger" size="micro">required</Badge>}
+      </Flex>
+      {field.description && (
+        <span className={styles.fieldDescription}>{field.description}</span>
+      )}
+      {field.example !== undefined && (
+        <span className={styles.fieldExample}>Example: <code>{JSON.stringify(field.example)}</code></span>
+      )}
+      {hasChildren && <ExpandableChildren field={field} />}
+    </Flex>
+  )
+}
+
+function ExpandableChildren({ field }: { field: SchemaField }) {
+  const [expanded, setExpanded] = useState(false)
+
+  return (
+    <Flex direction="column">
+      <Flex
+        align="center"
+        justify="between"
+        className={styles.expandButton}
+        onClick={() => setExpanded(!expanded)}
+        role="button"
+        tabIndex={0}
+      >
+        <span className={styles.expandLabel}>
+          {expanded ? 'Hide' : 'Show'} child attributes
+        </span>
+        {expanded ? (
+          <ChevronDownIcon width={16} height={16} />
+        ) : (
+          <ChevronRightIcon width={16} height={16} />
+        )}
+      </Flex>
+      {expanded && (
+        <Flex direction="column" gap={5} className={styles.childFields}>
+          {field.children!.map((child) => (
+            <FieldItem key={child.name} field={child} />
+          ))}
+        </Flex>
+      )}
+    </Flex>
+  )
+}

package/src/components/api/api-overview.module.css

@@ -0,0 +1,65 @@
+.layout {
+  align-items: flex-start;
+  justify-content: space-between;
+  padding-left: var(--rs-space-9);
+  padding-right: var(--rs-space-9);
+  width: 100%;
+}
+
+.left {
+  min-width: 0;
+  flex: 0 1 545px;
+}
+
+.right {
+  min-width: 376px;
+  max-width: 500px;
+  width: 100%;
+}
+
+.title {
+  font-family: var(--rs-font-title);
+  font-size: var(--rs-font-size-t3);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-t3);
+  letter-spacing: var(--rs-letter-spacing-t3);
+  color: var(--rs-color-foreground-base-primary);
+  margin: 0;
+}
+
+.description {
+  font-size: var(--rs-font-size-regular);
+  line-height: var(--rs-line-height-regular);
+  letter-spacing: var(--rs-letter-spacing-regular);
+  color: var(--rs-color-foreground-base-secondary);
+  margin: 0;
+}
+
+.methodBar {
+  padding: var(--rs-space-3) 0;
+  border-radius: var(--rs-radius-2);
+}
+
+.path {
+  font-family: var(--rs-font-mono);
+  font-size: var(--rs-font-size-mono-regular);
+  line-height: var(--rs-line-height-regular);
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.divider {
+  padding: 0;
+  margin: var(--rs-space-4) 0;
+}
+
+@media (max-width: 1100px) {
+  .layout {
+    flex-direction: column;
+    gap: var(--rs-space-9);
+  }
+
+  .left,
+  .right {
+    width: 100%;
+  }
+}

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

@@ -0,0 +1,216 @@
+'use client'
+
+import { useState } from 'react'
+import type { OpenAPIV3 } from 'openapi-types'
+import { Flex, Button, Menu, CopyButton, Separator } from '@raystack/apsara'
+import { ChevronDownIcon } from '@radix-ui/react-icons'
+import { MethodBadge } from '@/components/api/method-badge'
+import { ApiCodeSnippet } from './api-code-snippet'
+import { ApiResponsePanel } from './api-response-panel'
+import { flattenSchema, generateExampleJson, type SchemaField } from '@/lib/schema'
+import { ApiFieldSection } from './api-field-list'
+import { toKind } from '@/lib/schema'
+import styles from './api-overview.module.css'
+
+interface ApiOverviewProps {
+  method: string
+  path: string
+  operation: OpenAPIV3.OperationObject
+  serverUrl: string
+  specName: string
+  auth?: { type: string; header: string; placeholder?: string }
+}
+
+export function ApiOverview({ method, path, operation, auth }: ApiOverviewProps) {
+  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 pathFields = paramsToFields(params.filter((p) => p.in === 'path'))
+  const queryFields = paramsToFields(params.filter((p) => p.in === 'query'))
+  const responses = getResponseSections(operation.responses as Record<string, OpenAPIV3.ResponseObject>)
+
+  const authFields: SchemaField[] = auth
+    ? [{ name: auth.header, type: 'String', kind: 'string' as const, required: false }]
+    : headerFields.length > 0
+      ? headerFields
+      : []
+
+  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'
+
+
+  const hasSections = authFields.length > 0 || pathFields.length > 0 ||
+    queryFields.length > 0 || (body && body.fields.length > 0) || responses.length > 0
+
+  return (
+    <Flex className={styles.layout}>
+      <Flex direction='column' gap={9} className={styles.left}>
+        <Flex direction='column' gap={7}>
+          <Flex direction='column' gap={4}>
+            {operation.summary && (
+              <h1 className={styles.title}>{operation.summary}</h1>
+            )}
+            {operation.description && (
+              <p className={styles.description}>{operation.description}</p>
+            )}
+          </Flex>
+          <Flex align='center' gap={3} className={styles.methodBar}>
+            <MethodBadge method={method} />
+            <span className={styles.path}>{path}</span>
+            <CopyButton text={path} size={2} />
+          </Flex>
+        </Flex>
+
+        {hasSections && (
+          <Flex direction='column' gap={6}>
+            {authFields.length > 0 && (
+              <ApiFieldSection title="Authorisations" fields={authFields} />
+            )}
+
+            {authFields.length > 0 && (queryFields.length > 0 || pathFields.length > 0 || (body && body.fields.length > 0) || responses.length > 0) && (
+              <Separator className={styles.divider} />
+            )}
+
+            {pathFields.length > 0 && (
+              <ApiFieldSection title="Path Parameters" fields={pathFields} />
+            )}
+
+            {pathFields.length > 0 && (queryFields.length > 0 || (body && body.fields.length > 0) || responses.length > 0) && (
+              <Separator className={styles.divider} />
+            )}
+
+            {queryFields.length > 0 && (
+              <ApiFieldSection title="Query Parameters" fields={queryFields} />
+            )}
+
+            {queryFields.length > 0 && ((body && body.fields.length > 0) || responses.length > 0) && (
+              <Separator className={styles.divider} />
+            )}
+
+            {body && body.fields.length > 0 && (
+              <ApiFieldSection title="Request Body" fields={body.fields} />
+            )}
+
+            {body && body.fields.length > 0 && responses.length > 0 && (
+              <Separator className={styles.divider} />
+            )}
+
+            {responses.length > 0 && (
+              <ResponseSection responses={responses} />
+            )}
+          </Flex>
+        )}
+      </Flex>
+
+      <Flex direction='column' gap={8} className={styles.right}>
+        <ApiCodeSnippet
+          title={operation.summary ?? `${method.toUpperCase()} ${path}`}
+          method={method}
+          url={fullUrl}
+          headers={snippetHeaders}
+          body={body ? body.jsonExample : undefined}
+        />
+        <ApiResponsePanel responses={responses} />
+      </Flex>
+    </Flex>
+  )
+}
+
+function ResponseSection({ responses }: { responses: ResponseSectionData[] }) {
+  const [selectedStatus, setSelectedStatus] = useState(responses[0]?.status ?? '200')
+  if (responses.length === 0) return null
+  const active = responses.find((r) => r.status === selectedStatus) ?? responses[0]
+
+  return (
+    <ApiFieldSection
+      title="Response"
+      fields={active.fields}
+      description={active.description}
+      headerRight={
+        <>
+          {active.contentType && (
+            <span className={styles.path}>{active.contentType}</span>
+          )}
+          <Menu>
+            <Menu.Trigger
+              render={
+                <Button variant="text" color="neutral" size="small" trailingIcon={<ChevronDownIcon />} />
+              }
+            >
+              {active.status}
+            </Menu.Trigger>
+            <Menu.Content>
+              {responses.map((resp) => (
+                <Menu.Item key={resp.status} onClick={() => setSelectedStatus(resp.status)}>
+                  {resp.status}{resp.description ? ` — ${resp.description}` : ''}
+                </Menu.Item>
+              ))}
+            </Menu.Content>
+          </Menu>
+        </>
+      }
+    />
+  )
+}
+
+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',
+      kind: toKind(schema.type),
+      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 ResponseSectionData {
+  status: string
+  description?: string
+  contentType?: string
+  fields: SchemaField[]
+  jsonExample?: string
+}
+
+function getResponseSections(responses: Record<string, OpenAPIV3.ResponseObject>): ResponseSectionData[] {
+  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,
+      contentType,
+      fields: schema ? flattenSchema(schema) : [],
+      jsonExample: schema ? JSON.stringify(generateExampleJson(schema), null, 2) : undefined,
+    }
+  })
+}

package/src/components/api/api-response-panel.module.css

@@ -0,0 +1,62 @@
+.label {
+  font-size: var(--rs-font-size-small);
+  line-height: var(--rs-line-height-small);
+  letter-spacing: var(--rs-letter-spacing-small);
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.container {
+  border: 0.5px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  overflow: hidden;
+  height: 440px;
+  width: 100%;
+}
+
+.header {
+  padding: var(--rs-space-3) var(--rs-space-5);
+  background: var(--rs-color-background-base-secondary);
+  border-bottom: 0.5px solid var(--rs-color-border-base-primary);
+  flex-shrink: 0;
+}
+
+.tab {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 20px;
+  padding: 0 var(--rs-space-2);
+  border: 0.5px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  background: transparent;
+  cursor: pointer;
+  font-family: var(--rs-font-body);
+  font-size: var(--rs-font-size-mini);
+  font-weight: var(--rs-font-weight-medium);
+  line-height: var(--rs-line-height-mini);
+  letter-spacing: var(--rs-letter-spacing-mini);
+  color: var(--rs-color-foreground-base-secondary);
+}
+
+.tab:hover {
+  background: var(--rs-color-background-neutral-secondary);
+}
+
+.tabActive {
+  background: var(--rs-color-background-neutral-primary);
+  border-color: var(--rs-color-border-base-secondary);
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.body {
+  flex: 1;
+  min-height: 0;
+  overflow-x: hidden;
+  overflow-y: auto;
+  background: var(--rs-color-background-base-primary);
+}
+
+.codeBlock {
+  border: none;
+  border-radius: 0;
+}

package/src/components/api/api-response-panel.tsx

@@ -0,0 +1,54 @@
+'use client'
+
+import { useState } from 'react'
+import { CodeBlock, CopyButton, Flex } from '@raystack/apsara'
+import styles from './api-response-panel.module.css'
+
+interface ResponseData {
+  status: string
+  description?: string
+  jsonExample?: string
+}
+
+interface ApiResponsePanelProps {
+  responses: ResponseData[]
+}
+
+export function ApiResponsePanel({ responses }: ApiResponsePanelProps) {
+  const [selected, setSelected] = useState(responses[0]?.status ?? '')
+
+  if (responses.length === 0) return null
+
+  const active = responses.find((r) => r.status === selected) ?? responses[0]
+  const displayJson = active.jsonExample ?? '{}'
+
+  return (
+    <Flex direction='column' gap={4}>
+      <span className={styles.label}>Response:</span>
+      <Flex direction='column' className={styles.container}>
+        <Flex align='center' justify='between' className={styles.header}>
+          <Flex align='center' gap={3}>
+            {responses.map((resp) => (
+              <button
+                key={resp.status}
+                type="button"
+                className={`${styles.tab} ${resp.status === active.status ? styles.tabActive : ''}`}
+                onClick={() => setSelected(resp.status)}
+              >
+                {resp.status}
+              </button>
+            ))}
+          </Flex>
+          <CopyButton text={displayJson} size={3} />
+        </Flex>
+        <div className={styles.body}>
+          <CodeBlock hideLineNumbers className={styles.codeBlock}>
+            <CodeBlock.Content>
+              <CodeBlock.Code language="json">{displayJson}</CodeBlock.Code>
+            </CodeBlock.Content>
+          </CodeBlock>
+        </div>
+      </Flex>
+    </Flex>
+  )
+}