@ciderpress/ui 1.0.0-rc.1

package/dist/theme/components/openapi/response-list.tsx

@@ -0,0 +1,112 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+import { Button, Disclosure, DisclosurePanel } from 'react-aria-components'
+
+import { ChevronIcon } from './icons'
+import { SchemaViewer } from './schema-viewer'
+
+export interface ResponseListProps {
+  /**
+   * OpenAPI responses object keyed by status code.
+   */
+  readonly responses: Record<string, unknown>
+}
+
+/**
+ * Renders the list of response status codes for an OpenAPI operation.
+ *
+ * Each response is collapsible via react-aria-components Disclosure,
+ * showing the response schema when expanded.
+ *
+ * @param props - Response list props
+ * @returns React element with collapsible response entries
+ */
+export function ResponseList({ responses }: ResponseListProps): React.ReactElement {
+  const entries = Object.entries(responses)
+
+  return (
+    <div className="cp-oas-responses">
+      <div className="cp-oas-responses__title">Responses</div>
+      {entries.map(renderResponseItem)}
+    </div>
+  )
+}
+
+/**
+ * Determine the CSS class for a status code badge.
+ *
+ * @private
+ * @param code - HTTP status code string
+ * @returns CSS class name for the status code range
+ */
+function statusClass(code: string): string {
+  return match(code.charAt(0))
+    .with('2', () => 'cp-oas-response__status--2xx')
+    .with('3', () => 'cp-oas-response__status--3xx')
+    .with('4', () => 'cp-oas-response__status--4xx')
+    .with('5', () => 'cp-oas-response__status--5xx')
+    .otherwise(() => '')
+}
+
+/**
+ * Extract the schema from a response's first content type entry.
+ *
+ * @private
+ * @param response - OpenAPI response object
+ * @returns Schema object or null
+ */
+function extractSchema(response: Record<string, unknown>): Record<string, unknown> | null {
+  const content = response['content'] as Record<string, Record<string, unknown>> | undefined
+  const contentSchema = 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 [[, mediaType]] = e
+            return (mediaType['schema'] ?? null) as Record<string, unknown> | null
+          }
+        )
+        .otherwise(() => null)
+    })
+    .otherwise(() => null)
+
+  if (contentSchema !== null) {
+    return contentSchema
+  }
+
+  return match(response['schema'] as Record<string, unknown> | undefined)
+    .with(P.nonNullable, (s) => s)
+    .otherwise(() => null)
+}
+
+/**
+ * Render a single response item as a collapsible disclosure.
+ *
+ * @private
+ * @param entry - Tuple of [status code, response value]
+ * @returns Collapsible response element
+ */
+function renderResponseItem([code, value]: readonly [string, unknown]): React.ReactElement {
+  const response = (value ?? {}) as Record<string, unknown>
+  const description = String(response['description'] ?? '')
+  const schema = extractSchema(response)
+
+  const schemaEl = match(schema)
+    .with(P.nonNullable, (s) => <SchemaViewer schema={s} />)
+    .otherwise(() => <div className="cp-oas-response__description">No response body</div>)
+
+  return (
+    <Disclosure key={code} className="cp-oas-response">
+      <Button className="cp-oas-response__trigger" slot="trigger">
+        <span className={`cp-oas-response__status ${statusClass(code)}`}>{code}</span>
+        <span className="cp-oas-response__description">{description}</span>
+        <ChevronIcon className="cp-oas-response__chevron" />
+      </Button>
+      <DisclosurePanel>
+        <div className="cp-oas-response__content">{schemaEl}</div>
+      </DisclosurePanel>
+    </Disclosure>
+  )
+}

package/dist/theme/components/openapi/schema-viewer.tsx

@@ -0,0 +1,277 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+import { useState } from 'react'
+
+import { ChevronIcon } from './icons'
+
+export interface SchemaViewerProps {
+  /**
+   * JSON Schema object to render.
+   */
+  readonly schema: Record<string, unknown>
+  /**
+   * Current nesting depth (max 6).
+   */
+  readonly depth?: number
+  /**
+   * Property name displayed alongside the type.
+   */
+  readonly name?: string
+  /**
+   * Whether this property is required by its parent.
+   */
+  readonly isRequired?: boolean
+}
+
+const MAX_DEPTH = 6
+
+/**
+ * Recursive JSON Schema renderer.
+ *
+ * Renders primitive types as inline badges, objects as expandable
+ * property lists, arrays with item schemas, and oneOf/anyOf as
+ * variant lists. Stops at depth 6.
+ *
+ * @param props - Schema viewer props
+ * @returns React element representing the schema
+ */
+export function SchemaViewer({
+  schema,
+  depth = 0,
+  name,
+  isRequired = false,
+}: SchemaViewerProps): React.ReactElement {
+  const schemaType = String(schema['type'] ?? '')
+  const description = schema['description'] as string | undefined
+  const enumValues = schema['enum'] as readonly unknown[] | undefined
+  const oneOf = schema['oneOf'] as readonly Record<string, unknown>[] | undefined
+  const anyOf = schema['anyOf'] as readonly Record<string, unknown>[] | undefined
+  const depthExceeded = depth >= MAX_DEPTH
+
+  const nameEl = match(name)
+    .with(P.nonNullable, (n) => <span className="cp-oas-schema__name">{n}</span>)
+    .otherwise(() => null)
+
+  const enumEl = match(enumValues)
+    .with(
+      P.when((e): e is readonly unknown[] => e !== undefined && e.length > 0),
+      (e) => <EnumValues values={e} />
+    )
+    .otherwise(() => null)
+
+  return match({ schemaType, oneOf, anyOf, depthExceeded })
+    .with({ depthExceeded: true }, () => (
+      <div className="cp-oas-schema__row">
+        {nameEl}
+        <span className="cp-oas-schema__type">{'...'}</span>
+      </div>
+    ))
+    .with({ oneOf: P.nonNullable }, ({ oneOf: variants }) => (
+      <>
+        <div className="cp-oas-schema__row">
+          {nameEl}
+          <RequiredBadge show={isRequired} />
+          <DescriptionText text={description} />
+        </div>
+        <VariantSchemas variants={variants} label="one of" depth={depth} />
+      </>
+    ))
+    .with({ anyOf: P.nonNullable }, ({ anyOf: variants }) => (
+      <>
+        <div className="cp-oas-schema__row">
+          {nameEl}
+          <RequiredBadge show={isRequired} />
+          <DescriptionText text={description} />
+        </div>
+        <VariantSchemas variants={variants} label="any of" depth={depth} />
+      </>
+    ))
+    .with({ schemaType: 'object' }, () => (
+      <>
+        <div className="cp-oas-schema__row">
+          {nameEl}
+          <RequiredBadge show={isRequired} />
+          <DescriptionText text={description} />
+        </div>
+        <ObjectProperties schema={schema} depth={depth} />
+      </>
+    ))
+    .with({ schemaType: 'array' }, () => (
+      <>
+        <div className="cp-oas-schema__row">
+          {nameEl}
+          <RequiredBadge show={isRequired} />
+          <DescriptionText text={description} />
+        </div>
+        <ArrayItems schema={schema} depth={depth} />
+      </>
+    ))
+    .otherwise(() => (
+      <div className="cp-oas-schema__row">
+        {nameEl}
+        <span className="cp-oas-schema__type">{schemaType}</span>
+        <RequiredBadge show={isRequired} />
+        {enumEl}
+        <DescriptionText text={description} />
+      </div>
+    ))
+}
+
+/**
+ * Render a required badge when the property is required.
+ *
+ * @private
+ * @param props - Props with show flag
+ * @returns Required badge element or null
+ */
+function RequiredBadge({ show }: { readonly show: boolean }): React.ReactElement | null {
+  return match(show)
+    .with(true, () => <span className="cp-oas-schema__required">required</span>)
+    .otherwise(() => null)
+}
+
+/**
+ * Render a comma-separated list of enum values.
+ *
+ * @private
+ * @param props - Props with values array
+ * @returns Enum values element
+ */
+function EnumValues({ values }: { readonly values: readonly unknown[] }): React.ReactElement {
+  return (
+    <span className="cp-oas-schema__enum">
+      {'enum: '}
+      {values.map(String).join(', ')}
+    </span>
+  )
+}
+
+/**
+ * Render a description text span if text is provided.
+ *
+ * @private
+ * @param props - Props with optional text
+ * @returns Description element or null
+ */
+function DescriptionText({
+  text,
+}: {
+  readonly text: string | undefined
+}): React.ReactElement | null {
+  return match(text)
+    .with(P.nonNullable, (t) => <span className="cp-oas-schema__description">{t}</span>)
+    .otherwise(() => null)
+}
+
+/**
+ * Render an expandable object properties viewer.
+ *
+ * @private
+ * @param props - Props with schema and depth
+ * @returns Expandable object properties element
+ */
+function ObjectProperties({
+  schema,
+  depth,
+}: {
+  readonly schema: Record<string, unknown>
+  readonly depth: number
+}): React.ReactElement {
+  const [expanded, setExpanded] = useState(depth < 2)
+  const properties = (schema['properties'] ?? {}) as Record<string, Record<string, unknown>>
+  const requiredList = (schema['required'] ?? []) as readonly string[]
+  const propEntries = Object.entries(properties)
+
+  function handleToggle() {
+    setExpanded((prev) => !prev)
+  }
+
+  return (
+    <div
+      className="cp-oas-schema"
+      data-expanded={match(expanded)
+        .with(true, () => '' as string | null)
+        .otherwise(() => null)}
+    >
+      <button type="button" className="cp-oas-schema__trigger" onClick={handleToggle}>
+        <ChevronIcon className="cp-oas-schema__trigger-chevron" />
+        <span className="cp-oas-schema__type">{'object'}</span>
+        <span className="cp-oas-schema__description">
+          {`{${String(propEntries.length)} properties}`}
+        </span>
+      </button>
+      {match(expanded)
+        .with(true, () => (
+          <div className="cp-oas-schema__indent">
+            {propEntries.map(([propName, propSchema]) => (
+              <SchemaViewer
+                key={propName}
+                schema={propSchema}
+                name={propName}
+                depth={depth + 1}
+                isRequired={requiredList.includes(propName)}
+              />
+            ))}
+          </div>
+        ))
+        .otherwise(() => null)}
+    </div>
+  )
+}
+
+/**
+ * Render an array items schema viewer.
+ *
+ * @private
+ * @param props - Props with schema and depth
+ * @returns Array items element
+ */
+function ArrayItems({
+  schema,
+  depth,
+}: {
+  readonly schema: Record<string, unknown>
+  readonly depth: number
+}): React.ReactElement {
+  const items = (schema['items'] ?? {}) as Record<string, unknown>
+  return (
+    <div className="cp-oas-schema">
+      <div className="cp-oas-schema__row">
+        <span className="cp-oas-schema__type">{'array of'}</span>
+      </div>
+      <div className="cp-oas-schema__indent">
+        <SchemaViewer schema={items} depth={depth + 1} />
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Render variant schemas for oneOf/anyOf unions.
+ *
+ * @private
+ * @param props - Props with variants array, label, and depth
+ * @returns Variant schemas element
+ */
+function VariantSchemas({
+  variants,
+  label,
+  depth,
+}: {
+  readonly variants: readonly Record<string, unknown>[]
+  readonly label: string
+  readonly depth: number
+}): React.ReactElement {
+  return (
+    <div className="cp-oas-schema">
+      <div className="cp-oas-schema__row">
+        <span className="cp-oas-schema__type">{label}</span>
+      </div>
+      <div className="cp-oas-schema__indent">
+        {variants.map((variant, idx) => (
+          <SchemaViewer key={String(idx)} schema={variant} depth={depth + 1} />
+        ))}
+      </div>
+    </div>
+  )
+}

package/dist/theme/components/openapi/security-badges.tsx

@@ -0,0 +1,63 @@
+import { match, P } from 'massaman/match'
+import type React from 'react'
+
+import { LockIcon } from './icons'
+
+export interface SecurityBadgesProps {
+  /**
+   * Security requirement objects from the OpenAPI operation.
+   * Each entry is an alternative (OR); schemes within an entry are combined (AND).
+   */
+  readonly securities: readonly Record<string, unknown>[]
+}
+
+/**
+ * Renders badges for each security requirement of an operation.
+ *
+ * Each requirement is an alternative (OR). Schemes within a single
+ * requirement are combined (AND). OAuth scopes are shown in parentheses.
+ *
+ * @param props - Security badges props
+ * @returns React element or null if no securities
+ */
+export function SecurityBadges({ securities }: SecurityBadgesProps): React.ReactElement | null {
+  return match(securities)
+    .with(
+      P.when((s): s is readonly Record<string, unknown>[] => s.length > 0),
+      (s) => (
+        <div className="cp-oas-security">
+          <div className="cp-oas-security__title">Authentication</div>
+          <div className="cp-oas-security__list">
+            {s.map((requirement, idx) => (
+              <span key={String(idx)} className="cp-oas-security__badge">
+                <LockIcon />
+                {formatSchemes(requirement)}
+              </span>
+            ))}
+          </div>
+        </div>
+      )
+    )
+    .otherwise(() => null)
+}
+
+/**
+ * Format security scheme names with optional OAuth scopes.
+ *
+ * @private
+ * @param requirement - Security requirement object
+ * @returns Formatted scheme string with AND-combined names
+ */
+function formatSchemes(requirement: Record<string, unknown>): string {
+  return Object.entries(requirement)
+    .map(([name, scopes]) => {
+      const scopeSuffix = match(scopes)
+        .with(
+          P.when((s): s is readonly string[] => Array.isArray(s) && s.length > 0),
+          (s) => ` (${s.join(', ')})`
+        )
+        .otherwise(() => '')
+      return `${name}${scopeSuffix}`
+    })
+    .join(' + ')
+}

package/dist/theme/components/openapi/spec-utils.ts

@@ -0,0 +1,122 @@
+import { match, P } from 'massaman/match'
+
+/**
+ * All HTTP methods recognised by the OpenAPI specification.
+ */
+export const HTTP_METHODS: readonly string[] = [
+  'get',
+  'post',
+  'put',
+  'patch',
+  'delete',
+  'options',
+  'head',
+  'trace',
+]
+
+/**
+ * Resolve an operation object from the spec by path and method.
+ *
+ * @param input - Spec object, URL path, and HTTP method
+ * @returns The matched operation object or null if not found
+ */
+export function resolveOperation(input: {
+  readonly spec: Record<string, unknown>
+  readonly path: string
+  readonly method: string
+}): Record<string, unknown> | null {
+  const paths = input.spec['paths'] as Record<string, Record<string, unknown>> | undefined
+  return match(paths)
+    .with(P.nonNullable, (p) => {
+      const pathItem = p[input.path]
+      return match(pathItem)
+        .with(P.nonNullable, (pi) => {
+          const op = pi[input.method.toLowerCase()]
+          return match(op)
+            .with(P.nonNullable, (o) => o as Record<string, unknown>)
+            .otherwise(() => null)
+        })
+        .otherwise(() => null)
+    })
+    .otherwise(() => null)
+}
+
+/**
+ * Extract the first server URL from the spec, falling back to a placeholder.
+ *
+ * @param spec - Parsed OpenAPI spec object
+ * @returns First server URL string or `'https://api.example.com'`
+ */
+export function resolveBaseUrl(spec: Record<string, unknown>): string {
+  const servers = spec['servers'] as readonly Record<string, unknown>[] | undefined
+  return match(servers)
+    .with(
+      P.when((s): s is readonly Record<string, unknown>[] => s !== undefined && s.length > 0),
+      (s) => String(s[0]['url'] ?? 'https://api.example.com')
+    )
+    .otherwise(() => 'https://api.example.com')
+}
+
+/**
+ * Resolve security requirements from the operation or global spec.
+ *
+ * @param input - Operation object and full spec object
+ * @returns Array of security requirement objects (operation-level takes precedence)
+ */
+export function resolveSecurities(input: {
+  readonly operation: Record<string, unknown>
+  readonly spec: Record<string, unknown>
+}): readonly Record<string, unknown>[] {
+  const opSecurity = input.operation['security'] as readonly Record<string, unknown>[] | undefined
+  const globalSecurity = input.spec['security'] as readonly Record<string, unknown>[] | undefined
+  return match(opSecurity)
+    .with(P.nonNullable, (s) => s)
+    .otherwise(() =>
+      match(globalSecurity)
+        .with(P.nonNullable, (s) => s)
+        .otherwise(() => [] as readonly Record<string, unknown>[])
+    )
+}
+
+/**
+ * Extract the first example value from a request body's content map.
+ *
+ * @param requestBody - OpenAPI request body object, or undefined
+ * @returns The first example value found, or null
+ */
+export function extractBodyExample(
+  requestBody: Record<string, unknown> | undefined
+): unknown | null {
+  return match(requestBody)
+    .with(P.nonNullable, (rb) => {
+      const content = rb['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 [[, mediaType]] = e
+                const { example } = mediaType as { readonly example?: unknown }
+                return match(example)
+                  .with(P.nonNullable, (ex) => ex)
+                  .otherwise(() => null)
+              }
+            )
+            .otherwise(() => null)
+        })
+        .otherwise(() => null)
+    })
+    .otherwise(() => null)
+}
+
+/**
+ * Check if an HTTP method typically carries a request body.
+ *
+ * @param method - Lowercase HTTP method string
+ * @returns True if the method is POST, PUT, or PATCH
+ */
+export function isBodyMethod(method: string): boolean {
+  return method === 'post' || method === 'put' || method === 'patch'
+}

package/dist/theme/components/shared/accordion.css

@@ -0,0 +1,118 @@
+/**
+ * Accordion — expandable disclosure sections.
+ */
+
+.cp-accordion-group {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.cp-accordion {
+  border: 1px solid var(--cp-c-border);
+  border-radius: var(--rp-radius);
+  background: var(--cp-c-bg-soft);
+  overflow: hidden;
+  transition: border-color 0.2s;
+}
+
+.cp-accordion:hover {
+  border-color: var(--cp-c-brand-1);
+}
+
+.cp-accordion__trigger {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  min-height: 40px;
+  margin: 0;
+  padding: 10px 14px;
+  border: none;
+  background: none;
+  cursor: pointer;
+  color: var(--cp-c-text-1);
+  font-size: 14px;
+  font-weight: 600;
+  font-family: var(--cp-font-family-base);
+  text-align: left;
+  line-height: 1.4;
+}
+
+.cp-accordion__trigger:focus-visible {
+  outline: 2px solid var(--cp-c-brand-1);
+  outline-offset: 2px;
+}
+
+.cp-accordion__icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  width: 16px;
+  height: 16px;
+  color: var(--cp-c-brand-1);
+}
+
+.cp-accordion__icon svg {
+  display: block;
+}
+
+.cp-accordion__header {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  flex: 1;
+  min-width: 0;
+}
+
+.cp-accordion__title {
+  line-height: 1.4;
+}
+
+.cp-accordion__description {
+  font-size: 12px;
+  font-weight: 400;
+  color: var(--cp-c-text-2);
+  line-height: 1.4;
+}
+
+.cp-accordion__chevron {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  min-height: 40px;
+  width: 16px;
+  transition: transform 0.2s;
+  color: var(--cp-c-text-3);
+}
+
+.cp-accordion__chevron svg {
+  display: block;
+}
+
+.cp-accordion[data-expanded] .cp-accordion__chevron {
+  transform: rotate(90deg);
+}
+
+.cp-accordion__panel {
+  display: none;
+  padding: 0 14px 10px;
+  font-size: 14px;
+  line-height: 1.7;
+  color: var(--cp-c-text-2);
+}
+
+.cp-accordion[data-expanded] .cp-accordion__panel {
+  display: block;
+}
+
+.cp-accordion__panel > * {
+  margin-top: 0;
+  margin-bottom: 0;
+}
+
+.cp-accordion__panel > * + * {
+  margin-top: 8px;
+}