@djangocfg/ui-tools 2.1.287 → 2.1.290

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/SchemaFields/FieldRow.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+import { ChevronRight } from 'lucide-react';
+import React, { useState } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { FieldNode } from './types';
+
+interface FieldRowProps {
+    field: FieldNode;
+    /** 0-based nesting level. Used to compute left padding so the tree
+     *  visually expresses hierarchy without relying on a separate tree
+     *  component (no deps, one file). */
+    depth: number;
+    /** Parent container nodes render with an extra vertical tick so the
+     *  tree reads as a rooted graph instead of flat indented rows. */
+    showTreeLine?: boolean;
+}
+
+/** Recursive tree row. Object/array nodes are collapsible and default
+ *  to expanded at shallow depths — readers almost always want to see
+ *  the first level of nesting, and explicitly collapsing uninteresting
+ *  subtrees is cheaper than expanding every interesting one. */
+export function FieldRow({ field, depth, showTreeLine = true }: FieldRowProps) {
+    const isExpandable = (field.kind === 'object' || field.kind === 'array') &&
+        Array.isArray(field.children) && field.children.length > 0;
+
+    // Expand levels 0-1 by default; beyond that the tree can explode
+    // visually for deeply-nested objects (think Pet.category.tag.…).
+    const [open, setOpen] = useState(depth < 2);
+
+    // Inline padding via style so arbitrary depths render without a
+    // pile of Tailwind classes. 14px per level matches the chevron gap
+    // at smaller text sizes.
+    const padLeft = showTreeLine ? depth * 14 : 0;
+
+    return (
+        <div className="bg-background">
+            <div
+                className={cn(
+                    'grid grid-cols-[16px_minmax(0,1fr)] items-baseline gap-2 px-3 py-2',
+                    isExpandable && 'cursor-pointer hover:bg-muted/30',
+                )}
+                style={{ paddingLeft: 12 + padLeft }}
+                onClick={() => isExpandable && setOpen((v) => !v)}
+                role={isExpandable ? 'button' : undefined}
+                aria-expanded={isExpandable ? open : undefined}
+            >
+                <ChevronRight
+                    className={cn(
+                        'h-3.5 w-3.5 text-muted-foreground/50 shrink-0 transition-transform',
+                        !isExpandable && 'opacity-0',
+                        open && 'rotate-90',
+                    )}
+                />
+                <div className="min-w-0 space-y-1">
+                    <div className="flex items-baseline gap-2 flex-wrap">
+                        <code className="font-mono text-xs font-medium text-foreground">
+                            {field.name}
+                        </code>
+                        {field.required && (
+                            <span
+                                title="Required"
+                                className="text-[9px] text-destructive font-bold leading-none"
+                            >
+                                *
+                            </span>
+                        )}
+                        <code className="font-mono text-[11px] text-muted-foreground/70">
+                            {field.type}
+                        </code>
+                    </div>
+                    {field.description && (
+                        <p className="text-xs text-muted-foreground leading-relaxed break-words">
+                            {field.description}
+                        </p>
+                    )}
+                    {field.enumValues && field.enumValues.length > 0 && (
+                        <div className="flex flex-wrap gap-1 pt-0.5">
+                            {field.enumValues.map((v) => (
+                                <code
+                                    key={v}
+                                    className="inline-flex items-center rounded border border-border/60 bg-muted/40 px-1.5 py-px font-mono text-[10px] text-muted-foreground"
+                                >
+                                    {v}
+                                </code>
+                            ))}
+                        </div>
+                    )}
+                </div>
+            </div>
+            {isExpandable && open && (
+                <div>
+                    {field.children!.map((child, i) => (
+                        <FieldRow
+                            key={`${child.name}-${i}`}
+                            field={child}
+                            depth={depth + 1}
+                        />
+                    ))}
+                </div>
+            )}
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/SchemaFields/buildTree.ts

@@ -0,0 +1,127 @@
+/**
+ * JSON Schema → ``FieldNode`` tree.
+ *
+ *  Handles the OpenAPI 3.x subset we actually see: objects with
+ *  ``properties`` + ``required``, arrays with ``items``, enums,
+ *  primitives with ``format``. ``allOf`` / ``oneOf`` / ``anyOf`` are
+ *  flattened best-effort — we pick the first branch so the UI shows
+ *  *a* shape rather than an empty row. Upstream dereferencing
+ *  (``dereferenceSchema``) is expected to have resolved ``$ref`` before
+ *  this runs.
+ */
+
+import type { FieldKind, FieldNode } from './types';
+
+type JsonSchemaNode = Record<string, unknown> & {
+    type?: string;
+    properties?: Record<string, JsonSchemaNode>;
+    required?: string[];
+    items?: JsonSchemaNode;
+    enum?: unknown[];
+    description?: string;
+    format?: string;
+    allOf?: JsonSchemaNode[];
+    oneOf?: JsonSchemaNode[];
+    anyOf?: JsonSchemaNode[];
+};
+
+/** Hard cap on recursion so self-referential schemas can't blow the
+ *  call stack. Anything this deep is unreadable in a docs view anyway. */
+const MAX_DEPTH = 5;
+
+/** Merge ``allOf`` branches into a single pseudo-object. Shallow merge
+ *  is enough for the display — deep merge would require semantic JSON
+ *  Schema reasoning that we don't need for a read-only viewer. */
+function mergeAllOf(branches: JsonSchemaNode[]): JsonSchemaNode {
+    const properties: Record<string, JsonSchemaNode> = {};
+    const required: string[] = [];
+    for (const b of branches) {
+        if (b.properties) Object.assign(properties, b.properties);
+        if (Array.isArray(b.required)) required.push(...b.required);
+    }
+    return { type: 'object', properties, required };
+}
+
+function describeType(node: JsonSchemaNode): { label: string; kind: FieldKind } {
+    if (node.type === 'array') {
+        const itemLabel = node.items ? describeType(node.items).label : 'any';
+        return { label: `array<${itemLabel}>`, kind: 'array' };
+    }
+    if (node.type === 'object' || node.properties) {
+        return { label: 'object', kind: 'object' };
+    }
+    const base = node.type || 'any';
+    if (Array.isArray(node.enum) && node.enum.length > 0) {
+        return { label: `${base} enum`, kind: 'primitive' };
+    }
+    if (node.format) {
+        return { label: `${base} (${node.format})`, kind: 'primitive' };
+    }
+    return { label: base, kind: 'primitive' };
+}
+
+function resolveCombinators(node: JsonSchemaNode): JsonSchemaNode {
+    // ``allOf`` → merge shallowly. Other combinators → pick the first
+    // branch (see module docstring rationale).
+    if (Array.isArray(node.allOf) && node.allOf.length > 0) {
+        return { ...mergeAllOf(node.allOf), description: node.description };
+    }
+    if (Array.isArray(node.oneOf) && node.oneOf.length > 0) {
+        return { ...node.oneOf[0]!, description: node.description ?? node.oneOf[0]!.description };
+    }
+    if (Array.isArray(node.anyOf) && node.anyOf.length > 0) {
+        return { ...node.anyOf[0]!, description: node.description ?? node.anyOf[0]!.description };
+    }
+    return node;
+}
+
+function buildNode(
+    name: string,
+    schema: JsonSchemaNode,
+    isRequired: boolean,
+    depth: number,
+): FieldNode {
+    const resolved = resolveCombinators(schema);
+    const { label, kind } = describeType(resolved);
+    const node: FieldNode = {
+        name,
+        type: label,
+        kind,
+        required: isRequired,
+        description: resolved.description,
+    };
+
+    if (Array.isArray(resolved.enum) && resolved.enum.length > 0) {
+        node.enumValues = resolved.enum.map((v) => String(v));
+    }
+
+    if (depth >= MAX_DEPTH) return node;
+
+    if (kind === 'object' && resolved.properties) {
+        const required = new Set(resolved.required ?? []);
+        node.children = Object.entries(resolved.properties).map(([key, child]) =>
+            buildNode(key, child, required.has(key), depth + 1),
+        );
+    } else if (kind === 'array' && resolved.items) {
+        // Synthesise a single ``[]`` child. If items are objects, the
+        // child's own children will appear — so the tree reads as
+        // ``tags → [] → { id, name }``.
+        node.children = [buildNode('[]', resolved.items, false, depth + 1)];
+    }
+
+    return node;
+}
+
+/** Top-level entry. The root schema is usually an object or array; we
+ *  return its children directly so the tree starts one level deep
+ *  (skipping the redundant "root" node). */
+export function buildSchemaTree(schema: JsonSchemaNode | undefined): FieldNode[] {
+    if (!schema) return [];
+    const root = buildNode('', schema, false, 0);
+    if (root.children && root.children.length > 0) return root.children;
+    // Primitive body (rare) — return the root itself as a one-row tree.
+    if (root.kind === 'primitive' || (!root.children && root.name === '')) {
+        return [{ ...root, name: root.name || '(body)' }];
+    }
+    return [];
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/SchemaFields/index.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import { buildSchemaTree } from './buildTree';
+import { FieldRow } from './FieldRow';
+
+interface SchemaFieldsProps {
+    schema: Record<string, unknown>;
+}
+
+/** Tree-view of a JSON schema's fields. Replaces the old flat list
+ *  where nested objects appeared as ``category.id`` / ``category.name``
+ *  as siblings — here they nest visually under ``category``.
+ *
+ *  The component is purely presentational; all shape logic lives in
+ *  ``buildSchemaTree``. That split lets us swap the renderer later
+ *  (e.g. virtualised rows for huge schemas) without touching the
+ *  traversal. */
+export function SchemaFields({ schema }: SchemaFieldsProps) {
+    const tree = useMemo(() => buildSchemaTree(schema as never), [schema]);
+    if (tree.length === 0) return null;
+
+    return (
+        <div className="divide-y border rounded-md overflow-hidden">
+            {tree.map((node, i) => (
+                <FieldRow key={`${node.name}-${i}`} field={node} depth={0} />
+            ))}
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/SchemaFields/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Tree-view schema model.
+ *
+ *  A ``FieldNode`` represents one row in the schema tree: either a
+ *  primitive leaf (``string``, ``integer``, ``number``, ``boolean``) or
+ *  a container (``object`` / ``array``) with children. Keeping children
+ *  materialised (not lazy) makes the collapse state trivial — we know
+ *  in advance whether a node is expandable.
+ */
+
+export type FieldKind = 'object' | 'array' | 'primitive';
+
+export interface FieldNode {
+    /** Leaf name. For arrays the node synthesises a pseudo-field named
+     *  ``[]`` so the tree shows the ``items`` shape without the parent
+     *  having to special-case array children. */
+    name: string;
+    /** Short type label — rendered alongside the name in the row. */
+    type: string;
+    kind: FieldKind;
+    required: boolean;
+    description?: string;
+    /** Enum values when the field is an enum. Rendered as hint chips
+     *  below the row when present and the caller opts in. */
+    enumValues?: string[];
+    /** Nested children — non-empty only for ``object`` / ``array`` kinds. */
+    children?: FieldNode[];
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Section/SectionHeader.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { Check, ChevronDown, Link2 } from 'lucide-react';
+import { useState } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useEndpointDocContext } from '../context';
+import { buildSectionHash } from '../hooks/useSectionHash';
+import type { SectionId } from '../types';
+
+interface SectionHeaderProps {
+    /** Section identifier — needed to build the shareable hash link. */
+    sectionId: SectionId;
+    title: string;
+    badge?: number;
+    open: boolean;
+    onToggle: () => void;
+}
+
+/** Clickable header for a collapsible section. The whole row toggles,
+ *  plus a hover-revealed anchor button copies a ``#section=...`` URL so
+ *  users can share a link that lands with this exact section already
+ *  expanded (handled by ``useSectionHashRouter``). */
+export function SectionHeader({ sectionId, title, badge, open, onToggle }: SectionHeaderProps) {
+    const { endpointId } = useEndpointDocContext();
+    const [copied, setCopied] = useState(false);
+
+    const copyHash = (e: React.MouseEvent) => {
+        // Prevent the row toggle — the anchor button must not collapse
+        // the section while the user is copying the link.
+        e.stopPropagation();
+        if (typeof window === 'undefined') return;
+        const hash = buildSectionHash(endpointId, sectionId);
+        const url = `${window.location.origin}${window.location.pathname}#${hash}`;
+        void navigator.clipboard?.writeText(url).then(() => {
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1200);
+        });
+    };
+
+    return (
+        <div
+            className={cn(
+                'group/section w-full flex items-center gap-2 py-1.5 -ml-1 px-1 rounded cursor-pointer',
+                'hover:bg-muted/30 transition-colors',
+            )}
+            onClick={onToggle}
+            role="button"
+            aria-expanded={open}
+            tabIndex={0}
+            onKeyDown={(e) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault();
+                    onToggle();
+                }
+            }}
+        >
+            <ChevronDown
+                className={cn(
+                    'h-3.5 w-3.5 text-muted-foreground/50 transition-transform shrink-0',
+                    !open && '-rotate-90',
+                )}
+            />
+            <h4 className="text-[10px] font-semibold uppercase tracking-[0.12em] text-muted-foreground/80">
+                {title}
+            </h4>
+            {typeof badge === 'number' && badge > 0 && (
+                <span className="font-mono text-[10px] text-muted-foreground/50 tabular-nums">
+                    {badge}
+                </span>
+            )}
+            <button
+                type="button"
+                onClick={copyHash}
+                title="Copy link to this section"
+                className={cn(
+                    'ml-auto shrink-0 p-1 rounded text-muted-foreground/40 hover:text-foreground hover:bg-muted transition-all',
+                    'opacity-0 group-hover/section:opacity-100 focus-visible:opacity-100',
+                    copied && 'opacity-100 text-emerald-500',
+                )}
+            >
+                {copied ? <Check className="h-3 w-3" /> : <Link2 className="h-3 w-3" />}
+            </button>
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Section/defaults.ts

@@ -0,0 +1,27 @@
+import type { SectionId } from '../types';
+
+/** Per-HTTP-method defaults for which sections start open. The goal is
+ *  "the most useful section is already visible" without burying the
+ *  less-important ones entirely.
+ *
+ *  Rationale by method:
+ *    - GET/DELETE: parameters + 2xx response — the request itself has
+ *      no body, so that's what the reader needs to see first.
+ *    - POST/PUT/PATCH: request body + 2xx response — the shape to send
+ *      is the main question; parameters and code samples are
+ *      secondary, available one click away.
+ *    - Other (HEAD/OPTIONS/…): be conservative, open nothing extra
+ *      beyond responses. */
+const DEFAULTS_BY_METHOD: Record<string, Partial<Record<SectionId, boolean>>> = {
+    GET: { parameters: true, responses: true },
+    DELETE: { parameters: true, responses: true },
+    POST: { requestBody: true, responses: true },
+    PUT: { requestBody: true, responses: true },
+    PATCH: { requestBody: true, responses: true },
+};
+
+/** Resolve the default open state for a given (method, section). Falls
+ *  back to ``false`` for unknown combinations. */
+export function defaultSectionOpen(method: string, sectionId: SectionId): boolean {
+    return DEFAULTS_BY_METHOD[method.toUpperCase()]?.[sectionId] ?? false;
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Section/index.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import React from 'react';
+
+import { useEndpointDocContext } from '../context';
+import { useEndpointDocStore } from '../store';
+import { useIsSectionOpen } from '../store/selectors';
+import type { SectionId } from '../types';
+import { defaultSectionOpen } from './defaults';
+import { SectionHeader } from './SectionHeader';
+
+interface SectionProps {
+    /** Identifies the section inside the endpoint's card — used as a
+     *  key in zustand + URL hash routing. Must match one of ``SectionId``. */
+    id: SectionId;
+    title: string;
+    /** Optional count badge shown next to the title. */
+    badge?: number;
+    children: React.ReactNode;
+}
+
+/** Collapsible section wrapper. Pulls endpoint identity from
+ *  ``EndpointDocProvider`` so the component API stays at "id + title"
+ *  — the rest is implicit from context. Children render lazily when
+ *  open; a docs page may mount dozens of endpoints × four sections and
+ *  mounting everything eagerly would churn on the first scroll pass. */
+export function Section({ id, title, badge, children }: SectionProps) {
+    const { endpointId, method } = useEndpointDocContext();
+    const defaultOpen = defaultSectionOpen(method, id);
+    const open = useIsSectionOpen(endpointId, id, defaultOpen);
+    const toggleSection = useEndpointDocStore((s) => s.toggleSection);
+
+    return (
+        <div className="space-y-2.5">
+            <SectionHeader
+                sectionId={id}
+                title={title}
+                badge={badge}
+                open={open}
+                onToggle={() => toggleSection(endpointId, id)}
+            />
+            {open && <div>{children}</div>}
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/context.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import React, { createContext, useContext, useMemo } from 'react';
+
+/** Identity context for a single EndpointDoc subtree.
+ *
+ *  This is NOT a state container — state lives in the zustand store at
+ *  ``./store``. The context only carries per-endpoint *identity* values
+ *  so children (Section, CodeSamples, future ExpandAll button) don't
+ *  have to re-derive them or receive them as repeated props.
+ *
+ *  Why identity-only:
+ *    - One zustand singleton handles state for *all* endpoints on the
+ *      page, keyed by ``endpointId``. Wrapping zustand itself in a
+ *      Provider would defeat that composite-key design.
+ *    - Identity (anchor, HTTP method) is invariant inside an endpoint
+ *      card; deriving it per-child is wasted work and makes the props
+ *      table look noisier than the logic actually is. */
+interface EndpointDocContextValue {
+    /** DOM-safe anchor id for this endpoint — used as the store key
+     *  prefix (``openSections[`${endpointId}:${sectionId}`]``) and as
+     *  the URL hash target for shareable links. */
+    endpointId: string;
+    /** HTTP method (``GET`` / ``POST`` / …). Drives per-method default
+     *  open state for Section. Kept in context so ``defaultSectionOpen``
+     *  doesn't need to be threaded as a prop through every subtree. */
+    method: string;
+}
+
+const EndpointDocContext = createContext<EndpointDocContextValue | null>(null);
+
+interface EndpointDocProviderProps extends EndpointDocContextValue {
+    children: React.ReactNode;
+}
+
+export function EndpointDocProvider({ endpointId, method, children }: EndpointDocProviderProps) {
+    // Memoise the value so every re-render of the parent orchestrator
+    // doesn't invalidate children reading the context — the common
+    // hover/focus state on the header row re-renders EndpointDoc often.
+    const value = useMemo(() => ({ endpointId, method }), [endpointId, method]);
+    return <EndpointDocContext.Provider value={value}>{children}</EndpointDocContext.Provider>;
+}
+
+export function useEndpointDocContext(): EndpointDocContextValue {
+    const ctx = useContext(EndpointDocContext);
+    if (!ctx) {
+        // Treated as a programming error, not a runtime one — if this
+        // fires, something rendered EndpointDoc internals outside the
+        // provider, which means the store keys will collide or be
+        // missing entirely. Loud failure beats silent corruption.
+        throw new Error(
+            '[OpenapiViewer] useEndpointDocContext must be used inside <EndpointDocProvider>.',
+        );
+    }
+    return ctx;
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/hooks/useSectionHash.ts

@@ -0,0 +1,63 @@
+'use client';
+
+import { useEffect } from 'react';
+
+import { useEndpointDocStore } from '../store';
+import { ALL_SECTION_IDS, type SectionId } from '../types';
+
+/** Parse ``#section=<endpointId>.<sectionId>`` out of a hash string.
+ *  Returns ``null`` for any other shape (including the plain
+ *  ``#<endpointId>`` form used elsewhere for scrolling to an endpoint). */
+export function parseSectionHash(hash: string): { endpointId: string; sectionId: SectionId } | null {
+    const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+    if (!raw.startsWith('section=')) return null;
+    const value = raw.slice('section='.length);
+    const dot = value.lastIndexOf('.');
+    if (dot <= 0 || dot === value.length - 1) return null;
+    const endpointId = value.slice(0, dot);
+    const sectionIdCandidate = value.slice(dot + 1);
+    if (!(ALL_SECTION_IDS as readonly string[]).includes(sectionIdCandidate)) return null;
+    return { endpointId, sectionId: sectionIdCandidate as SectionId };
+}
+
+/** Build the shareable hash that opens a specific section. */
+export function buildSectionHash(endpointId: string, sectionId: SectionId): string {
+    return `section=${endpointId}.${sectionId}`;
+}
+
+/** On mount + on hashchange, read ``#section=...``, open that section
+ *  in the store, and scroll its endpoint into view. Runs once per
+ *  hash change, not per endpoint render — the effect lives above the
+ *  per-endpoint level in the tree.
+ *
+ *  Behaviour:
+ *    1. Parse hash. If it isn't our ``section=`` form, bail — the
+ *       browser's own anchor-scrolling handles ``#ep-…`` URLs already.
+ *    2. Open the referenced section in the zustand store so its body
+ *       is visible the moment the user lands.
+ *    3. Scroll the endpoint's ``<section id={endpointId}>`` into view
+ *       on the next frame (after the section body has mounted). */
+export function useSectionHashRouter(): void {
+    const setSectionOpen = useEndpointDocStore((s) => s.setSectionOpen);
+
+    useEffect(() => {
+        if (typeof window === 'undefined') return;
+
+        function apply() {
+            const parsed = parseSectionHash(window.location.hash);
+            if (!parsed) return;
+            setSectionOpen(parsed.endpointId, parsed.sectionId, true);
+            // Defer scroll to let the section body render first —
+            // scrolling a collapsed row lands on the wrong offset
+            // because the body takes vertical space once expanded.
+            requestAnimationFrame(() => {
+                const el = document.getElementById(parsed.endpointId);
+                el?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+            });
+        }
+
+        apply();
+        window.addEventListener('hashchange', apply);
+        return () => window.removeEventListener('hashchange', apply);
+    }, [setSectionOpen]);
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/index.tsx

@@ -0,0 +1,96 @@
+'use client';
+
+import React from 'react';
+
+import type { ApiEndpoint } from '../../../types';
+import { endpointAnchor } from '../anchor';
+import { CodeSamples } from './CodeSamples';
+import { EndpointDocProvider } from './context';
+import { EndpointHeader } from './Header';
+import { Parameters } from './Parameters';
+import { RequestBody } from './RequestBody';
+import { Responses } from './Responses';
+import { Section } from './Section';
+import type { SectionId } from './types';
+
+interface EndpointDocProps {
+    endpoint: ApiEndpoint;
+    /** Is this endpoint currently loaded in the sticky playground? */
+    isLoadedInPlayground: boolean;
+    onTryIt: () => void;
+    /** Scoping prefix for the anchor, so endpoints from different schemas
+     *  don't collide on a single page. Falls back to ``endpoint.schemaId``. */
+    schemaId?: string | null;
+}
+
+/** Card that documents one API endpoint: header + a stack of collapsible
+ *  sections (parameters, request body, responses, code samples). The
+ *  component itself is a thin orchestrator — each child folder owns its
+ *  own rendering concerns and reads the endpoint identity from context. */
+export function EndpointDoc({ endpoint, isLoadedInPlayground, onTryIt, schemaId }: EndpointDocProps) {
+    const scopedSchemaId = schemaId ?? endpoint.schemaId ?? null;
+    const anchor = endpointAnchor(endpoint, scopedSchemaId);
+    const pathParams = endpoint.parameters?.filter((p) => endpoint.path.includes(`{${p.name}}`)) ?? [];
+    const queryParams = endpoint.parameters?.filter((p) => !endpoint.path.includes(`{${p.name}}`)) ?? [];
+
+    const hasParameters = pathParams.length > 0 || queryParams.length > 0;
+    const hasResponses = (endpoint.responses?.length ?? 0) > 0;
+
+    // Collect section ids that actually render so the header's
+    // expand/collapse-all toggle only touches visible sections.
+    // ``codeSamples`` is always present — it synthesises a snippet
+    // even for parameter-less endpoints.
+    const presentSections: SectionId[] = [];
+    if (hasParameters) presentSections.push('parameters');
+    if (endpoint.requestBody) presentSections.push('requestBody');
+    presentSections.push('codeSamples');
+    if (hasResponses) presentSections.push('responses');
+
+    return (
+        <EndpointDocProvider endpointId={anchor} method={endpoint.method}>
+            <section
+                id={anchor}
+                data-endpoint-anchor={anchor}
+                data-schema-id={scopedSchemaId ?? ''}
+                className="scroll-mt-24 py-10 first:pt-0"
+            >
+                <EndpointHeader
+                    endpoint={endpoint}
+                    anchor={anchor}
+                    isLoadedInPlayground={isLoadedInPlayground}
+                    onTryIt={onTryIt}
+                    presentSections={presentSections}
+                />
+
+                <div className="mt-8 space-y-5">
+                    {hasParameters && (
+                        <Section
+                            id="parameters"
+                            title="Parameters"
+                            badge={pathParams.length + queryParams.length}
+                        >
+                            <Parameters pathParams={pathParams} queryParams={queryParams} />
+                        </Section>
+                    )}
+                    {endpoint.requestBody && (
+                        <Section id="requestBody" title="Request body">
+                            <RequestBody body={endpoint.requestBody} />
+                        </Section>
+                    )}
+                    <Section id="codeSamples" title="Code samples">
+                        <CodeSamples endpoint={endpoint} />
+                    </Section>
+                    {hasResponses && (
+                        <Section
+                            id="responses"
+                            title="Responses"
+                            badge={endpoint.responses!.length}
+                        >
+                            <Responses responses={endpoint.responses!} />
+                        </Section>
+                    )}
+                </div>
+            </section>
+        </EndpointDocProvider>
+    );
+}