@ciderpress/ui 1.0.0-rc.1

package/dist/theme/components/openapi/operation.tsx

@@ -0,0 +1,200 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { CodeSample } from './code-sample'
+import { MethodBadge } from './method-badge'
+import { ParametersTable } from './parameters-table'
+import { RequestBody } from './request-body'
+import { ResponseList } from './response-list'
+import { SecurityBadges } from './security-badges'
+import { resolveBaseUrl, resolveOperation, resolveSecurities } from './spec-utils'
+
+export interface OpenAPIOperationProps {
+  /**
+   * Parsed OpenAPI spec object.
+   */
+  readonly spec: Record<string, unknown>
+  /**
+   * HTTP method (get, post, put, patch, delete).
+   */
+  readonly method: string
+  /**
+   * URL path (e.g. /users/{id}).
+   */
+  readonly path: string
+  /**
+   * Operation ID for identification.
+   */
+  readonly operationId: string
+  /**
+   * Pre-rendered markdown for the SSG-MD pass.
+   * When provided and `import.meta.env.SSG_MD` is true, this string
+   * is rendered instead of the interactive UI.
+   */
+  readonly markdown?: string
+}
+
+/**
+ * Main OpenAPI operation page component.
+ *
+ * Two-column layout: left column shows spec details (header,
+ * parameters, request body, responses, security), right column
+ * shows auto-generated code examples.
+ *
+ * @param props - Operation props with spec, method, path, and operationId
+ * @returns React element with operation details and code examples
+ */
+export function OpenAPIOperation({
+  spec,
+  method,
+  path,
+  operationId,
+  markdown,
+}: OpenAPIOperationProps): React.ReactElement {
+  if (import.meta.env.SSG_MD && markdown) {
+    return <>{markdown}</>
+  }
+
+  const operation = resolveOperation({ spec, path, method })
+
+  return match(operation)
+    .with(P.nonNullable, (op) => {
+      const parameters = (op['parameters'] ?? []) as readonly Record<string, unknown>[]
+      const requestBody = op['requestBody'] as Record<string, unknown> | undefined
+      const responses = (op['responses'] ?? {}) as Record<string, unknown>
+      const summary = op['summary'] as string | undefined
+      const description = op['description'] as string | undefined
+      const deprecated = op['deprecated'] === true
+      const securities = resolveSecurities({ operation: op, spec })
+      const baseUrl = resolveBaseUrl(spec)
+
+      const displaySummary: string | undefined = match(summary)
+        .with(P.nonNullable, (s) => s)
+        .otherwise(() =>
+          match(description)
+            .with(P.nonNullable, (d) => d as string | undefined)
+            .otherwise(() => undefined as string | undefined)
+        )
+
+      const parametersEl = match(parameters)
+        .with(
+          P.when((p): p is readonly Record<string, unknown>[] => p.length > 0),
+          (p) => <ParametersTable parameters={p} />
+        )
+        .otherwise(() => null)
+
+      const requestBodyEl = match(requestBody)
+        .with(P.nonNullable, (rb) => <RequestBody requestBody={rb} />)
+        .otherwise(() => null)
+
+      const responsesEl = match(Object.keys(responses))
+        .with(
+          P.when((k): k is string[] => k.length > 0),
+          () => <ResponseList responses={responses} />
+        )
+        .otherwise(() => null)
+
+      const securityEl = match(securities)
+        .with(
+          P.when((s): s is readonly Record<string, unknown>[] => s.length > 0),
+          (s) => <SecurityBadges securities={s} />
+        )
+        .otherwise(() => null)
+
+      return (
+        <div className="cp-oas-operation">
+          <div className="cp-oas-operation-spec">
+            <OperationHeader
+              method={method}
+              path={path}
+              operationId={operationId}
+              summary={displaySummary}
+              deprecated={deprecated}
+            />
+            {parametersEl}
+            {requestBodyEl}
+            {responsesEl}
+            {securityEl}
+          </div>
+          <div className="cp-oas-operation-examples">
+            <CodeSample
+              method={method}
+              path={path}
+              baseUrl={baseUrl}
+              parameters={parameters}
+              requestBody={requestBody}
+            />
+          </div>
+        </div>
+      )
+    })
+    .otherwise(() => <NotFound method={method} path={path} />)
+}
+
+/**
+ * Render the operation header with method badge, path, and optional deprecation tag.
+ *
+ * @private
+ * @param props - Header props including method, path, operationId, summary, and deprecated flag
+ * @returns Header element
+ */
+function OperationHeader({
+  method,
+  path,
+  operationId,
+  summary,
+  deprecated,
+}: {
+  readonly method: string
+  readonly path: string
+  readonly operationId: string
+  readonly summary: string | undefined
+  readonly deprecated: boolean
+}): React.ReactElement {
+  const summaryEl = match(summary)
+    .with(P.nonNullable, (s) => <div className="cp-oas-operation-summary">{s}</div>)
+    .otherwise(() => null)
+
+  const deprecatedEl = match(deprecated)
+    .with(true, () => <span className="cp-oas-operation-deprecated">Deprecated</span>)
+    .otherwise(() => null)
+
+  return (
+    <div>
+      <div className="cp-oas-operation-header">
+        <MethodBadge method={method} />
+        <span className="cp-oas-operation-header__path">{path}</span>
+        {deprecatedEl}
+      </div>
+      <div className="cp-oas-operation-header__id">{operationId}</div>
+      {summaryEl}
+    </div>
+  )
+}
+
+/**
+ * Render a fallback when the operation is not found in the spec.
+ *
+ * @private
+ * @param props - Props with method and path
+ * @returns Not-found element
+ */
+function NotFound({
+  method,
+  path,
+}: {
+  readonly method: string
+  readonly path: string
+}): React.ReactElement {
+  return (
+    <div className="cp-oas-operation">
+      <div className="cp-oas-operation-spec">
+        <div className="cp-oas-operation-header">
+          <MethodBadge method={method} />
+          <span className="cp-oas-operation-header__path">{path}</span>
+        </div>
+        <div className="cp-oas-operation-summary">Operation not found in the provided spec.</div>
+      </div>
+    </div>
+  )
+}

package/dist/theme/components/openapi/overview.tsx

@@ -0,0 +1,207 @@
+import { countBy } from 'massaman/array'
+import { identity } from 'massaman/function'
+import { match, P } from 'massaman/match'
+import type React from 'react'
+import { useMemo } from 'react'
+
+import { LockIcon } from './icons'
+import { HTTP_METHODS } from './spec-utils'
+
+export interface OpenAPIOverviewProps {
+  /**
+   * Parsed OpenAPI spec object.
+   */
+  readonly spec: Record<string, unknown>
+  /**
+   * Pre-rendered markdown for the SSG-MD pass.
+   * When provided and `import.meta.env.SSG_MD` is true, this string
+   * is rendered instead of the interactive UI.
+   */
+  readonly markdown?: string
+}
+
+interface TagInfo {
+  readonly name: string
+  readonly description: string
+  readonly operationCount: number
+}
+
+/**
+ * API overview page component.
+ *
+ * Renders the API title, version, description, server URLs,
+ * authentication schemes, and tag groups with operation counts.
+ *
+ * @param props - Overview props with parsed spec
+ * @returns React element with full API overview
+ */
+export function OpenAPIOverview({ spec, markdown }: OpenAPIOverviewProps): React.ReactElement {
+  if (import.meta.env.SSG_MD && markdown) {
+    return <>{markdown}</>
+  }
+
+  const info = (spec['info'] ?? {}) as Record<string, unknown>
+  const description = info['description'] as string | undefined
+  const servers = (spec['servers'] ?? []) as readonly Record<string, unknown>[]
+  const components = (spec['components'] ?? {}) as Record<string, unknown>
+  const securitySchemes = (components['securitySchemes'] ?? {}) as Record<
+    string,
+    Record<string, unknown>
+  >
+  const tags = useMemo(() => collectTags(spec), [spec])
+
+  const descEl = match(description)
+    .with(P.nonNullable, (d) => <div className="cp-oas-overview__description">{d}</div>)
+    .otherwise(() => null)
+
+  return (
+    <div className="cp-oas-overview">
+      {descEl}
+      <ServerList servers={servers} />
+      <AuthSchemes schemes={securitySchemes} />
+      <TagGroups tags={tags} />
+    </div>
+  )
+}
+
+/**
+ * Collect all tags from the spec and count their operations.
+ *
+ * @private
+ * @param spec - Parsed OpenAPI spec object
+ * @returns Array of tag info with operation counts
+ */
+function collectTags(spec: Record<string, unknown>): readonly TagInfo[] {
+  const paths = (spec['paths'] ?? {}) as Record<string, Record<string, unknown>>
+
+  const allTags = Object.values(paths).flatMap((pathItem) =>
+    HTTP_METHODS.filter((method) => pathItem[method] !== undefined).flatMap((method) => {
+      const operation = pathItem[method] as Record<string, unknown>
+      const tags = (operation['tags'] ?? ['default']) as readonly string[]
+      return tags
+    })
+  )
+
+  const tagMap = countBy(allTags, identity)
+
+  const specTags = (spec['tags'] ?? []) as readonly Record<string, unknown>[]
+  const specTagMap = Object.fromEntries(
+    specTags.map((t) => [String(t['name'] ?? ''), String(t['description'] ?? '')])
+  )
+
+  return Object.entries(tagMap).map(([name, count]) => ({
+    name,
+    description: specTagMap[name] ?? '',
+    operationCount: count,
+  }))
+}
+
+/**
+ * Render the server list section.
+ *
+ * @private
+ * @param props - Props with servers array
+ * @returns Server list element or null
+ */
+function ServerList({
+  servers,
+}: {
+  readonly servers: readonly Record<string, unknown>[]
+}): React.ReactElement | null {
+  return match(servers)
+    .with(
+      P.when((s): s is readonly Record<string, unknown>[] => s.length > 0),
+      (s) => (
+        <div className="cp-oas-servers">
+          <div className="cp-oas-overview__section-title">Servers</div>
+          {s.map((server) => {
+            const url = String(server['url'] ?? '')
+            const description = server['description'] as string | undefined
+            const descEl = match(description)
+              .with(P.nonNullable, (d) => (
+                <span className="cp-oas-server__description">{` — ${d}`}</span>
+              ))
+              .otherwise(() => null)
+            return (
+              <div key={url} className="cp-oas-server">
+                <span className="cp-oas-server__url">{url}</span>
+                {descEl}
+              </div>
+            )
+          })}
+        </div>
+      )
+    )
+    .otherwise(() => null)
+}
+
+/**
+ * Render the authentication schemes section.
+ *
+ * @private
+ * @param props - Props with security schemes
+ * @returns Auth schemes element or null
+ */
+function AuthSchemes({
+  schemes,
+}: {
+  readonly schemes: Record<string, Record<string, unknown>>
+}): React.ReactElement | null {
+  const entries = Object.entries(schemes)
+  return match(entries)
+    .with(
+      P.when((e): e is [string, Record<string, unknown>][] => e.length > 0),
+      (e) => (
+        <div className="cp-oas-auth-schemes">
+          <div className="cp-oas-overview__section-title">Authentication</div>
+          {e.map(([name, scheme]) => (
+            <div key={name} className="cp-oas-auth-scheme">
+              <LockIcon />
+              <span className="cp-oas-auth-scheme__name">{name}</span>
+              <span className="cp-oas-auth-scheme__type">{String(scheme['type'] ?? '')}</span>
+            </div>
+          ))}
+        </div>
+      )
+    )
+    .otherwise(() => null)
+}
+
+/**
+ * Render the tag groups section with operation counts.
+ *
+ * @private
+ * @param props - Props with tags array
+ * @returns Tag groups element or null
+ */
+function TagGroups({ tags }: { readonly tags: readonly TagInfo[] }): React.ReactElement | null {
+  return match(tags)
+    .with(
+      P.when((t): t is readonly TagInfo[] => t.length > 0),
+      (t) => (
+        <div className="cp-oas-tags">
+          <div className="cp-oas-overview__section-title">Operations</div>
+          {t.map((tag) => {
+            const descEl = match(tag.description)
+              .with(
+                P.when((d): d is string => d.length > 0),
+                (d) => <div className="cp-oas-tag-group__description">{d}</div>
+              )
+              .otherwise(() => null)
+            return (
+              <div key={tag.name} className="cp-oas-tag-group">
+                <div className="cp-oas-tag-group__header">
+                  <span className="cp-oas-tag-group__name">{tag.name}</span>
+                  <span className="cp-oas-tag-group__count">
+                    {`${String(tag.operationCount)} operations`}
+                  </span>
+                </div>
+                {descEl}
+              </div>
+            )
+          })}
+        </div>
+      )
+    )
+    .otherwise(() => null)
+}

package/dist/theme/components/openapi/parameters-table.tsx

@@ -0,0 +1,149 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+export interface ParametersTableProps {
+  /**
+   * OpenAPI parameter objects.
+   */
+  readonly parameters: readonly Record<string, unknown>[]
+}
+
+interface ParameterGroup {
+  readonly label: string
+  readonly items: readonly Record<string, unknown>[]
+}
+
+/**
+ * Renders operation parameters grouped by location (path, query, header).
+ *
+ * Each group displays a table with name, type, required, description, and default columns.
+ *
+ * @param props - Parameters table props
+ * @returns React element or null if no parameters
+ */
+export function ParametersTable({ parameters }: ParametersTableProps): React.ReactElement | null {
+  const groups = groupByIn(parameters)
+
+  return match(groups)
+    .with(
+      P.when((g): g is readonly ParameterGroup[] => g.length > 0),
+      (g) => (
+        <div className="cp-oas-parameters">
+          <div className="cp-oas-parameters__title">Parameters</div>
+          {g.map(renderGroup)}
+        </div>
+      )
+    )
+    .otherwise(() => null)
+}
+
+/**
+ * Group parameters by their `in` field (path, query, header, etc.).
+ *
+ * @private
+ * @param params - OpenAPI parameter objects
+ * @returns Array of parameter groups
+ */
+function groupByIn(params: readonly Record<string, unknown>[]): readonly ParameterGroup[] {
+  const grouped = Map.groupBy(params, (param) => String(param['in'] ?? 'other'))
+  return [...grouped.entries()].map(([label, items]) => ({ label, items }))
+}
+
+/**
+ * Render a required badge if the parameter is required.
+ *
+ * @private
+ * @param param - OpenAPI parameter object
+ * @returns Required badge element or null
+ */
+function renderRequired(param: Record<string, unknown>): React.ReactElement | null {
+  return match(param['required'])
+    .with(true, () => <span className="cp-oas-parameters__required">required</span>)
+    .otherwise(() => null)
+}
+
+/**
+ * Render a default value badge if one exists in the parameter schema.
+ *
+ * @private
+ * @param param - OpenAPI parameter object
+ * @returns Default value element or null
+ */
+function renderDefault(param: Record<string, unknown>): React.ReactElement | null {
+  const schemaDefault = match(param['schema'])
+    .with(P.nonNullable, (schema) => (schema as Record<string, unknown>)['default'])
+    .otherwise(() => null)
+  const defaultValue = schemaDefault ?? param['default']
+
+  return match(defaultValue)
+    .with(P.nonNullable, (def) => <span className="cp-oas-parameters__default">{String(def)}</span>)
+    .otherwise(() => null)
+}
+
+/**
+ * Extract the type string from a parameter's schema.
+ *
+ * @private
+ * @param param - OpenAPI parameter object
+ * @returns Type string or dash placeholder
+ */
+function extractType(param: Record<string, unknown>): string {
+  const schemaType = match(param['schema'])
+    .with(
+      P.nonNullable,
+      (schema) => (schema as Record<string, unknown>)['type'] as string | undefined
+    )
+    .otherwise(() => null)
+
+  return String(schemaType ?? param['type'] ?? '—')
+}
+
+/**
+ * Render a single parameter row in the table.
+ *
+ * @private
+ * @param param - OpenAPI parameter object
+ * @returns Table row element
+ */
+function renderRow(param: Record<string, unknown>): React.ReactElement {
+  return (
+    <tr key={String(param['name'])}>
+      <td>
+        <span className="cp-oas-parameters__name">{String(param['name'] ?? '')}</span>
+      </td>
+      <td>
+        <span className="cp-oas-parameters__type">{extractType(param)}</span>
+      </td>
+      <td>{renderRequired(param)}</td>
+      <td>{String(param['description'] ?? '')}</td>
+      <td>{renderDefault(param)}</td>
+    </tr>
+  )
+}
+
+/**
+ * Render a parameter group with its label and table.
+ *
+ * @private
+ * @param group - Parameter group with label and items
+ * @returns Group container element
+ */
+function renderGroup(group: ParameterGroup): React.ReactElement {
+  return (
+    <div key={group.label}>
+      <div className="cp-oas-parameters__group-label">{group.label}</div>
+      <table className="cp-oas-parameters__table">
+        <thead>
+          <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Required</th>
+            <th>Description</th>
+            <th>Default</th>
+          </tr>
+        </thead>
+        <tbody>{group.items.map(renderRow)}</tbody>
+      </table>
+    </div>
+  )
+}

package/dist/theme/components/openapi/request-body.tsx

@@ -0,0 +1,90 @@
+import { CodeBlockRuntime } from '@rspress/core/theme'
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { SchemaViewer } from './schema-viewer'
+
+export interface RequestBodyProps {
+  /**
+   * OpenAPI requestBody object.
+   */
+  readonly requestBody: Record<string, unknown>
+}
+
+interface ParsedContent {
+  readonly contentType: string
+  readonly schema: Record<string, unknown>
+  readonly example: unknown | null
+}
+
+/**
+ * Renders the request body section of an OpenAPI operation.
+ *
+ * Shows the content type, description, schema tree, and example payload.
+ *
+ * @param props - Request body props
+ * @returns React element with request body details
+ */
+export function RequestBody({ requestBody }: RequestBodyProps): React.ReactElement {
+  const description = requestBody['description'] as string | undefined
+  const parsed = extractFirstContent(requestBody)
+
+  const descEl = match(description)
+    .with(P.nonNullable, (d) => <div className="cp-oas-request-body__description">{d}</div>)
+    .otherwise(() => null)
+
+  const bodyEl = match(parsed)
+    .with(P.nonNullable, (p) => (
+      <div>
+        <div className="cp-oas-request-body__content-type">{p.contentType}</div>
+        <SchemaViewer schema={p.schema} />
+      </div>
+    ))
+    .otherwise(() => null)
+
+  const exampleEl = match(parsed)
+    .with(P.nonNullable, (p) =>
+      match(p.example)
+        .with(P.nonNullable, (ex) => (
+          <CodeBlockRuntime lang="json" code={JSON.stringify(ex, null, 2)} />
+        ))
+        .otherwise(() => null)
+    )
+    .otherwise(() => null)
+
+  return (
+    <div className="cp-oas-request-body">
+      <div className="cp-oas-request-body__title">Request Body</div>
+      {descEl}
+      {bodyEl}
+      {exampleEl}
+    </div>
+  )
+}
+
+/**
+ * Extract the first content type entry from a request body.
+ *
+ * @private
+ * @param requestBody - OpenAPI request body object
+ * @returns Parsed content with type, schema, and example, or null
+ */
+function extractFirstContent(requestBody: Record<string, unknown>): ParsedContent | null {
+  const content = requestBody['content'] as Record<string, Record<string, unknown>> | undefined
+  return match(content)
+    .with(P.nonNullable, (c) => {
+      const entries = Object.entries(c)
+      return match(entries)
+        .with(
+          P.when((e): e is [string, Record<string, unknown>][] => e.length > 0),
+          (e) => {
+            const [[contentType, mediaType]] = e
+            const schema = (mediaType['schema'] ?? {}) as Record<string, unknown>
+            const { example } = mediaType as { readonly example?: unknown }
+            return { contentType, schema, example: example ?? null }
+          }
+        )
+        .otherwise(() => null)
+    })
+    .otherwise(() => null)
+}