vocs 2.0.17 → 2.1.2

package/src/react/internal/openapi/OpenApiPage.tsx

@@ -0,0 +1,173 @@
+import { specs } from 'virtual:vocs/openapi'
+import type { ReactNode } from 'react'
+import { Layout } from '../../Layout.js'
+import * as MdxPageContext from '../../MdxPageContext.js'
+import { Endpoints } from './Endpoints.js'
+import { HeadingAnchor } from './HeadingAnchor.js'
+import { PlaygroundProvider } from './Playground.client.js'
+import { Prose, ReferenceGroup, ReferenceOverview } from './Reference.js'
+
+/**
+ * Layout for OpenAPI pages.
+ *
+ * Single-column pages (the overview and consumer guide pages) show the normal
+ * outline (the regular Vocs right gutter) — this is the default. The two-column
+ * operation (category) pages opt out (`outline={false}`), since the sidebar
+ * already exposes every operation as an anchor and the sticky playground
+ * occupies the right column.
+ */
+function OpenApiLayout(props: {
+  children: React.ReactNode
+  outline?: boolean | undefined
+  width?: 'default' | 'full'
+}) {
+  return (
+    <MdxPageContext.Provider
+      frontmatter={{ outline: props.outline ?? true, content: { width: props.width ?? 'full' } }}
+    >
+      <Layout>{props.children}</Layout>
+    </MdxPageContext.Provider>
+  )
+}
+
+/**
+ * Renders a consumer-authored "guide" page (a normal MDX page mounted under an
+ * OpenAPI section path, e.g. `pages/api/auth.mdx`).
+ *
+ * Uses the same full-bleed layout as the section landing page (the left
+ * centering gutter collapses to the sidebar, so content sits flush after it).
+ * Like the landing page it is single-column, so it keeps the normal right
+ * gutter/TOC outline (the default). The authored prose is wrapped in
+ * `[data-v-openapi-guide]`, which caps it to the readable content width and
+ * reapplies markdown block rhythm/heading treatment, so the guide keeps a
+ * regular page's article width and padding while matching the gutter layout of
+ * the rest of the section.
+ *
+ * For authored guide pages the frontmatter `title`/`description` are
+ * intentionally not rendered as an on-page header; the authored MDX owns its own
+ * headings (like a normal page). Trait pages (`x-traitTag`) opt in via `header`,
+ * since their title/subtitle come from the spec tag and the body has no heading.
+ */
+export function OpenApiGuide(props: OpenApiGuide.Props) {
+  return (
+    <OpenApiLayout width="full">
+      {props.title ? <title>{props.title}</title> : null}
+      <div data-v-openapi-guide>
+        {props.header && props.title ? (
+          <header data-v-openapi-header>
+            <h1 data-v data-v-openapi-h1 id={props.id}>
+              {props.title}
+              {props.id ? <HeadingAnchor id={props.id} /> : null}
+            </h1>
+            {props.description ? <Prose markdown={props.description} attr="description" /> : null}
+          </header>
+        ) : null}
+        {props.children}
+      </div>
+    </OpenApiLayout>
+  )
+}
+
+export declare namespace OpenApiGuide {
+  type Props = {
+    /** Authored MDX content. */
+    children?: ReactNode | undefined
+    /** Document `<title>` and page heading (from the page's frontmatter). */
+    title?: string | undefined
+    /** Subtitle Markdown rendered below the heading. */
+    description?: string | undefined
+    /**
+     * Render `title`/`description` as an on-page header above the content (used
+     * by trait pages, whose Markdown body has no heading of its own).
+     */
+    header?: boolean | undefined
+    /** Anchor id for the rendered header heading (enables a copy-link anchor). */
+    id?: string | undefined
+  }
+}
+
+/**
+ * Renders an isolated, auto-generated OpenAPI reference section (Vite/RSC site
+ * integration). The actual content is rendered by the framework-agnostic
+ * {@link file://./Reference.tsx `Reference`} components; this is the Waku
+ * adapter that resolves the spec from `virtual:vocs/openapi` and wraps it in the
+ * site `Layout`.
+ *
+ * Behavior depends on the optional `group` prop:
+ *
+ * - with `group`: renders a single category page.
+ * - without `group`: renders an overview/landing page.
+ *
+ * An optional `intro` (a consumer-authored MDX "override" page mounted at the
+ * same route) replaces the auto-generated header while the generated body still
+ * renders below it automatically.
+ */
+export function OpenApiPage(props: OpenApiPage.Props) {
+  const ir = specs[props.mount]
+
+  if (!ir)
+    return (
+      <OpenApiLayout>
+        <p>No OpenAPI spec is mounted at {props.mount}.</p>
+      </OpenApiLayout>
+    )
+
+  // Single category page.
+  if (props.group) {
+    const group = ir.groups.find((candidate) => candidate.id === props.group)
+    if (!group)
+      return (
+        <OpenApiLayout>
+          <p>
+            No category “{props.group}” exists in the API mounted at {props.mount}.
+          </p>
+        </OpenApiLayout>
+      )
+
+    return (
+      <OpenApiLayout outline={false}>
+        <title>{props.title ?? `${group.name} · ${ir.info.title}`}</title>
+        <PlaygroundProvider client={ir.client} mount={ir.path}>
+          <ReferenceGroup ir={ir} group={group} intro={props.intro} />
+        </PlaygroundProvider>
+      </OpenApiLayout>
+    )
+  }
+
+  // Overview / landing page.
+  return (
+    <OpenApiLayout width="full">
+      <title>{props.title ?? ir.info.title}</title>
+      <ReferenceOverview
+        ir={ir}
+        intro={props.intro}
+        endpoints={props.endpoints ? <Endpoints path={ir.path || undefined} /> : undefined}
+      />
+    </OpenApiLayout>
+  )
+}
+
+export declare namespace OpenApiPage {
+  type Props = {
+    /** Mount path identifying which spec to render (e.g. `/api`). */
+    mount: string
+    /**
+     * Category id to render. When omitted, renders the overview page listing
+     * every category.
+     */
+    group?: string | undefined
+    /**
+     * Consumer-authored override content rendered in place of the auto-generated
+     * header (spec title/description). The generated body still renders below.
+     */
+    intro?: ReactNode | undefined
+    /** Document `<title>` override (e.g. from the override page's frontmatter). */
+    title?: string | undefined
+    /**
+     * Render the domain/endpoint list on the overview page (ignored when `group`
+     * or `intro` is set). The standalone handler enables this so its
+     * Introduction lists every endpoint by default.
+     */
+    endpoints?: boolean | undefined
+  }
+}

package/src/react/internal/openapi/Operation.test.tsx

@@ -0,0 +1,101 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, test } from 'vitest'
+import type * as OpenApi from '../../../internal/openapi/index.js'
+import { Operation } from './Operation.js'
+import { Schema } from './Schema.js'
+
+const operation: OpenApi.IrOperation = {
+  id: 'getpet',
+  method: 'GET',
+  path: '/pets/{petId}',
+  summary: 'Get a pet',
+  description: 'Returns a **single** pet by id.',
+  parameters: [
+    {
+      name: 'petId',
+      in: 'path',
+      required: true,
+      description: 'The id of the pet',
+      schema: { type: 'string' },
+    },
+    { name: 'expand', in: 'query', schema: { type: 'boolean' } },
+  ],
+  requestBody: undefined,
+  responses: [
+    {
+      status: '200',
+      description: 'A pet',
+      content: [
+        {
+          mediaType: 'application/json',
+          schema: {
+            type: 'object',
+            required: ['id'],
+            properties: {
+              id: { type: 'string', description: 'Pet id' },
+              name: { type: 'string' },
+            },
+          },
+        },
+      ],
+      headers: [],
+    },
+    { status: '404', description: 'Not found', content: [], headers: [] },
+  ],
+}
+
+describe('Operation', () => {
+  const html = renderToStaticMarkup(<Operation operation={operation} />)
+
+  test('renders the heading, method and path', () => {
+    expect(html).toContain('Get a pet')
+    expect(html).toContain('id="getpet"')
+    expect(html).toContain('>GET<')
+    expect(html).toContain('/pets/{petId}')
+  })
+
+  test('renders the description as markdown', () => {
+    expect(html).toContain('single</strong>')
+  })
+
+  test('renders parameters grouped by location', () => {
+    expect(html).toContain('Path Parameters')
+    expect(html).toContain('Query Parameters')
+    expect(html).toContain('petId')
+    expect(html).toContain('The id of the pet')
+    expect(html).toContain('required')
+  })
+
+  test('renders responses with status and schema', () => {
+    expect(html).toContain('>200<')
+    expect(html).toContain('A pet')
+    expect(html).toContain('>404<')
+    // Response schema property names.
+    expect(html).toContain('Pet id')
+  })
+})
+
+describe('Schema', () => {
+  test('renders nested object properties recursively', () => {
+    const html = renderToStaticMarkup(
+      <Schema
+        schema={{
+          type: 'object',
+          required: ['owner'],
+          properties: {
+            owner: {
+              type: 'object',
+              properties: { name: { type: 'string', description: 'Owner name' } },
+            },
+          },
+        }}
+      />,
+    )
+    expect(html).toContain('owner')
+    expect(html).toContain('Owner name')
+  })
+
+  test('renders nothing for a schemaless value', () => {
+    expect(renderToStaticMarkup(<Schema schema={undefined} />)).toBe('')
+  })
+})

package/src/react/internal/openapi/Operation.tsx

@@ -0,0 +1,335 @@
+import LucideChevronRight from '~icons/lucide/chevron-right'
+import * as Markdown from '../../../internal/markdown.js'
+import {
+  mediaIdBase,
+  requestBodyIdBase,
+  responseIdBase,
+  slug,
+} from '../../../internal/openapi/anchors.js'
+import type * as OpenApi from '../../../internal/openapi/index.js'
+import { codeSamples, responseSamples } from '../../../internal/openapi/sample.js'
+import { methodVariant } from '../../../internal/openapi/sidebar.js'
+import { unwrapSingleVariant } from '../../../internal/openapi/union.js'
+import { Badge } from '../../Badge.js'
+import { CodeSample } from './CodeSample.client.js'
+import { CollapsibleChildren } from './CollapsibleChildren.client.js'
+import { Disclosure } from './Disclosure.client.js'
+import { HeadingAnchor } from './HeadingAnchor.js'
+import { TestRequestButton } from './Playground.client.js'
+import {
+  enumValues,
+  PropertyRow,
+  Schema,
+  schemaExample,
+  schemaMeta,
+  typeLabel,
+  UnionView,
+  unionVariants,
+} from './Schema.js'
+
+const parameterGroups: { in: OpenApi.IrParameter['in']; title: string }[] = [
+  { in: 'path', title: 'Path Parameters' },
+  { in: 'query', title: 'Query Parameters' },
+  { in: 'header', title: 'Header Parameters' },
+  { in: 'cookie', title: 'Cookie Parameters' },
+  // JSON-RPC method params (expanded from an OpenRPC document).
+  { in: 'rpc', title: 'Parameters' },
+]
+
+export function Operation(props: Operation.Props) {
+  const { operation, server, headingLevel = 3, separator = false } = props
+  const title = operation.summary || `${operation.method} ${operation.path}`
+  const Heading = `h${headingLevel}` as 'h2' | 'h3'
+
+  const samples = codeSamples(operation, server)
+  const responses = responseSamples(operation)
+
+  return (
+    <section
+      data-v-openapi-operation
+      data-separator={separator || undefined}
+      data-deprecated={operation.deprecated || undefined}
+    >
+      {/* Header: title, endpoint, description. */}
+      <div data-v-openapi-operation-header>
+        <Heading data-v data-v-openapi-operation-title id={operation.id}>
+          {title}
+          {operation.deprecated && <Badge variant="warning">Deprecated</Badge>}
+          <HeadingAnchor id={operation.id} />
+        </Heading>
+        <div data-v-openapi-endpoint>
+          <Badge variant={methodVariant(operation.method)}>{operation.method}</Badge>
+          <code data-v-openapi-endpoint-path>{operation.path}</code>
+        </div>
+        {operation.description && <Prose markdown={operation.description} />}
+      </div>
+
+      {/* Body: parameters, request body, responses. */}
+      <div data-v-openapi-operation-body>
+        {parameterGroups.map((group) => {
+          const params = operation.parameters.filter((parameter) => parameter.in === group.in)
+          if (params.length === 0) return null
+          return (
+            <Section key={group.in} id={`${operation.id}-${slug(group.title)}`} title={group.title}>
+              <ParameterList parameters={params} idPrefix={operation.id} />
+            </Section>
+          )
+        })}
+
+        {operation.requestBody && !operation.requestBody.hidden && (
+          <Section id={`${operation.id}-request-body`} title="Request Body">
+            <Content
+              content={operation.requestBody.content}
+              idBase={requestBodyIdBase(operation.id)}
+            />
+          </Section>
+        )}
+
+        {operation.responses.length > 0 && (
+          <Section id={`${operation.id}-responses`} title="Responses">
+            <div data-v-openapi-responses>
+              {operation.responses.map((response) => (
+                <ResponseRow key={response.status} operationId={operation.id} response={response} />
+              ))}
+            </div>
+          </Section>
+        )}
+      </div>
+
+      {/* Aside: request/response sample. Sticky beside the docs on large
+          screens; on small screens it moves directly below the header (above
+          the body) via the grid template in openapi.css. */}
+      {samples.length > 0 && (
+        <div data-v-openapi-operation-aside>
+          <CodeSample
+            samples={samples}
+            responses={responses}
+            action={
+              <TestRequestButton
+                method={operation.method}
+                path={operation.path}
+                example={operation.rpcExample}
+              />
+            }
+          />
+        </div>
+      )}
+    </section>
+  )
+}
+
+export declare namespace Operation {
+  type Props = {
+    operation: OpenApi.IrOperation
+    /** Base server URL used to build request code samples. */
+    server?: string | undefined
+    /**
+     * Heading level for the operation title. Use `2` on per-category pages
+     * (category name is `<h1>`) and `3` on the single-page layout (category is
+     * `<h2>`).
+     *
+     * @default 3
+     */
+    headingLevel?: 2 | 3 | undefined
+    /**
+     * Renders a top border separating this operation from the previous one.
+     * Pass `true` for every operation except the first.
+     *
+     * @default false
+     */
+    separator?: boolean | undefined
+  }
+}
+
+function Section(props: { id: string; title: string; children: React.ReactNode }) {
+  return (
+    <section data-v-openapi-section>
+      <h3 data-v data-v-openapi-section-title id={props.id}>
+        {props.title}
+        <HeadingAnchor id={props.id} />
+      </h3>
+      {props.children}
+    </section>
+  )
+}
+
+function ParameterList(props: { parameters: OpenApi.IrParameter[]; idPrefix: string }) {
+  return (
+    <div data-v-openapi-params>
+      {props.parameters.map((parameter) => {
+        // Unwrap a nullable single-variant union (e.g. `oneOf: [null, X]`) so X's
+        // type and nested properties render instead of a bare `null | object`.
+        const schema = parameter.schema
+          ? (unwrapSingleVariant(parameter.schema) ?? parameter.schema)
+          : parameter.schema
+        const union = unionVariants(schema)
+        return (
+          <PropertyRow
+            key={parameter.name}
+            id={`${props.idPrefix}-${slug(parameter.name)}`}
+            name={parameter.name}
+            type={union ? undefined : typeLabel(schema)}
+            values={union ? undefined : enumValues(schema)}
+            meta={union ? [] : schemaMeta(schema)}
+            example={union ? undefined : parameterExample(parameter)}
+            required={parameter.required}
+            deprecated={parameter.deprecated}
+            description={parameter.description}
+          >
+            {union ? (
+              <UnionView union={union} depth={1} prefix={`${parameter.name}.`} />
+            ) : (
+              schema &&
+              hasChildSchema(schema) && (
+                <CollapsibleChildren>
+                  <div data-v-openapi-children>
+                    <Schema
+                      schema={schema}
+                      depth={1}
+                      prefix={`${parameter.name}${schema['type'] === 'array' ? '[]' : ''}.`}
+                    />
+                  </div>
+                </CollapsibleChildren>
+              )
+            )}
+          </PropertyRow>
+        )
+      })}
+    </div>
+  )
+}
+
+/** Resolves a parameter/header example, preferring the item-level value. */
+function parameterExample(parameter: {
+  example?: unknown
+  schema?: Record<string, unknown> | undefined
+}): string | undefined {
+  if (parameter.example !== undefined)
+    return typeof parameter.example === 'string'
+      ? parameter.example
+      : JSON.stringify(parameter.example)
+  return schemaExample(parameter.schema)
+}
+
+/** Whether a parameter's schema has nested object/array properties to expand. */
+function hasChildSchema(schema: Record<string, unknown>): boolean {
+  if (schema['properties']) return true
+  if (schema['type'] === 'array' && schema['items'])
+    return hasChildSchema(schema['items'] as Record<string, unknown>)
+  return false
+}
+
+function Content(props: {
+  content: OpenApi.IrMediaType[]
+  hideMediaType?: boolean
+  idBase?: string | undefined
+}) {
+  if (props.content.length === 0) return null
+  return (
+    <div data-v-openapi-content>
+      {props.content.map((media) => {
+        const schemaIdBase = props.idBase
+          ? mediaIdBase(props.idBase, media.mediaType, props.content.length)
+          : undefined
+        return (
+          <div key={media.mediaType} data-v-openapi-media>
+            {!props.hideMediaType && <code data-v-openapi-media-type>{media.mediaType}</code>}
+            {media.schema ? (
+              <Schema schema={media.schema} idBase={schemaIdBase} />
+            ) : media.example !== undefined ? (
+              <Example value={media.example} />
+            ) : null}
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+function ResponseRow(props: { operationId: string; response: OpenApi.IrResponse }) {
+  const { operationId, response } = props
+  const headers = response.headers ?? []
+  const idBase = responseIdBase(operationId, response.status)
+  const variant =
+    response.status.startsWith('2') || response.status === 'default'
+      ? 'success'
+      : response.status.startsWith('4') || response.status.startsWith('5')
+        ? 'danger'
+        : 'info'
+  const hasContent = response.content.length > 0 || headers.length > 0
+  const header = (
+    <>
+      {hasContent ? (
+        <LucideChevronRight data-v-openapi-response-chevron />
+      ) : (
+        <span data-v-openapi-response-spacer aria-hidden />
+      )}
+      <Badge variant={variant} data-v-openapi-response-status>
+        {response.status}
+      </Badge>
+      {response.description && (
+        <span data-v-openapi-response-description title={response.description}>
+          {response.description}
+        </span>
+      )}
+    </>
+  )
+
+  // Responses without a body have nothing to expand — render a static row.
+  if (!hasContent)
+    return (
+      <div data-v-openapi-response data-static>
+        {header}
+      </div>
+    )
+
+  return (
+    <div data-v-openapi-response>
+      <Disclosure trigger={header}>
+        <div data-v-openapi-response-content>
+          {headers.length > 0 && (
+            <CollapsibleChildren label="Headers">
+              <div data-v-openapi-params>
+                {headers.map((item) => (
+                  <PropertyRow
+                    key={item.name}
+                    name={item.name}
+                    type={typeLabel(item.schema)}
+                    values={enumValues(item.schema)}
+                    meta={schemaMeta(item.schema)}
+                    example={parameterExample(item)}
+                    required={item.required}
+                    deprecated={item.deprecated}
+                    description={item.description}
+                  />
+                ))}
+              </div>
+            </CollapsibleChildren>
+          )}
+          {response.content.length > 0 && (
+            <Content content={response.content} hideMediaType idBase={idBase} />
+          )}
+        </div>
+      </Disclosure>
+    </div>
+  )
+}
+
+function Example(props: { value: unknown }) {
+  return (
+    <pre data-v-openapi-example>
+      <code>{JSON.stringify(props.value, null, 2)}</code>
+    </pre>
+  )
+}
+
+function Prose(props: { markdown: string }) {
+  return (
+    <div
+      data-v-openapi-prose
+      data-v-content
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: server-rendered trusted spec content
+      dangerouslySetInnerHTML={{ __html: Markdown.toHtml(props.markdown) }}
+    />
+  )
+}