@djangocfg/ui-tools 2.1.289 → 2.1.290

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Responses/ResponseBody.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import { CopyButton } from '@djangocfg/ui-core/components';
+
+import JsonTree from '../../../../../JsonTree';
+
+// Compact, read-only JsonTree config. Docs longread is space-constrained
+// so we ship less chrome than the interactive ``ResponsePanel`` — copy
+// button lives outside the tree (on the row header) and collection-info
+// stays on so long arrays don't silently truncate.
+const EXAMPLE_JSON_TREE_CONFIG = {
+    maxAutoExpandDepth: 2,
+    maxAutoExpandArrayItems: 5,
+    maxAutoExpandObjectKeys: 8,
+    maxStringLength: 160,
+    collectionLimit: 25,
+    showCollectionInfo: true,
+    showExpandControls: false,
+    showActionButtons: false,
+    preserveKeyOrder: true,
+    className: 'border-0 rounded-none',
+} as const;
+
+interface ResponseBodyProps {
+    example: string;
+    contentType?: string;
+}
+
+/** Render the example response body: content-type strip + copy button
+ *  header, then the JSON tree (falling back to a ``<pre>`` if the
+ *  example isn't valid JSON — sampler occasionally emits non-JSON for
+ *  exotic content types). */
+export function ResponseBody({ example, contentType }: ResponseBodyProps) {
+    // Parse once and cache. ``example`` is pre-stringified by the
+    // sampler; JsonTree wants a live object to render nodes with proper
+    // folding, so we flip it back here.
+    const parsed = useMemo(() => {
+        try {
+            return JSON.parse(example);
+        } catch {
+            return null;
+        }
+    }, [example]);
+
+    return (
+        <div className="border-t bg-muted/20">
+            <div className="flex items-center justify-between px-3 py-1.5 border-b border-border/50">
+                <code className="font-mono text-[10px] uppercase tracking-wider text-muted-foreground/70">
+                    {contentType ?? 'application/json'}
+                </code>
+                <CopyButton
+                    value={example}
+                    variant="ghost"
+                    size="sm"
+                    className="h-6 px-2 text-[10px] text-muted-foreground"
+                >
+                    Copy
+                </CopyButton>
+            </div>
+            {parsed != null ? (
+                <JsonTree
+                    title=""
+                    data={parsed}
+                    mode="compact"
+                    config={EXAMPLE_JSON_TREE_CONFIG}
+                />
+            ) : (
+                <pre className="p-3 text-[11px] font-mono text-foreground/70 whitespace-pre-wrap break-all leading-relaxed">
+                    {example}
+                </pre>
+            )}
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Responses/ResponseRow.tsx

@@ -0,0 +1,80 @@
+'use client';
+
+import { ChevronRight } from 'lucide-react';
+import { useState } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ApiEndpoint } from '../../../../types';
+import { ResponseBody } from './ResponseBody';
+import { StatusTag } from './StatusTag';
+
+interface ResponseRowProps {
+    response: NonNullable<ApiEndpoint['responses']>[number];
+}
+
+/** One status-code row in the Responses section.
+ *
+ *  Layout:
+ *    - Chevron column only renders when there's an example to expand.
+ *      Otherwise the row is inert (no button wrapper, no hover state)
+ *      and the space stays tight instead of reserving an empty gutter
+ *      under a disabled chevron.
+ *    - Status tag column is ``48px`` wide — enough for ``default`` and
+ *      3-digit codes in the font size we use. Keeps descriptions
+ *      aligned on their left edge across all rows regardless of code.
+ *
+ *  Expansion defaults:
+ *    - 2xx with example → open (happy-path is what readers want first).
+ *    - Everything else → closed, one click to inspect. */
+export function ResponseRow({ response }: ResponseRowProps) {
+    const hasExample = Boolean(response.example);
+    const numeric = Number.parseInt(response.code, 10);
+    const isSuccess = Number.isFinite(numeric) && numeric >= 200 && numeric < 300;
+    const [open, setOpen] = useState(hasExample && isSuccess);
+
+    // Inert row (no example available) — render as a plain div so the
+    // layout stays identical but without button affordances.
+    if (!hasExample) {
+        return (
+            <div className="flex items-center gap-3 px-3 py-2 bg-background">
+                <div className="w-12 shrink-0 flex justify-start">
+                    <StatusTag code={response.code} />
+                </div>
+                <span className="text-sm text-muted-foreground leading-relaxed break-words min-w-0">
+                    {response.description}
+                </span>
+            </div>
+        );
+    }
+
+    return (
+        <div className="bg-background">
+            <button
+                type="button"
+                onClick={() => setOpen((v) => !v)}
+                className="w-full flex items-center gap-3 px-3 py-2 text-left hover:bg-muted/40 cursor-pointer transition-colors"
+                aria-expanded={open}
+            >
+                <ChevronRight
+                    className={cn(
+                        'h-3.5 w-3.5 text-muted-foreground/60 transition-transform shrink-0',
+                        open && 'rotate-90',
+                    )}
+                />
+                <div className="w-12 shrink-0 flex justify-start">
+                    <StatusTag code={response.code} />
+                </div>
+                <span className="text-sm text-muted-foreground leading-relaxed break-words min-w-0 flex-1">
+                    {response.description}
+                </span>
+            </button>
+            {open && (
+                <ResponseBody
+                    example={response.example!}
+                    contentType={response.contentType}
+                />
+            )}
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Responses/StatusTag.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+interface StatusTagProps {
+    code: string;
+}
+
+/** HTTP status pill. Colours map to the usual conventions: 2xx green,
+ *  3xx blue, 4xx amber, 5xx red, non-numeric (``default``) neutral.
+ *  Codes that don't parse as integers render in the neutral style so we
+ *  never flash a wrong-severity colour at the user. */
+export function StatusTag({ code }: StatusTagProps) {
+    const numeric = Number.parseInt(code, 10);
+    const cls = !Number.isFinite(numeric)
+        ? 'bg-muted text-muted-foreground border-border'
+        : numeric >= 500
+            ? 'bg-red-500/10 text-red-600 dark:text-red-400 border-red-500/25'
+            : numeric >= 400
+                ? 'bg-amber-500/10 text-amber-600 dark:text-amber-400 border-amber-500/25'
+                : numeric >= 300
+                    ? 'bg-blue-500/10 text-blue-600 dark:text-blue-400 border-blue-500/25'
+                    : 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border-emerald-500/25';
+    return (
+        <span className={cn(
+            'inline-flex items-center justify-center rounded border px-2 py-0.5 font-mono text-[11px] font-bold leading-none shrink-0 tabular-nums',
+            cls,
+        )}>
+            {code}
+        </span>
+    );
+}

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

@@ -0,0 +1,21 @@
+'use client';
+
+import type { ApiEndpoint } from '../../../../types';
+import { ResponseRow } from './ResponseRow';
+
+interface ResponsesProps {
+    responses: NonNullable<ApiEndpoint['responses']>;
+}
+
+/** Flat list of response rows. Outer collapsible wrapper lives in the
+ *  ``Section`` component higher up; this component only knows how to
+ *  arrange the individual rows. */
+export function Responses({ responses }: ResponsesProps) {
+    return (
+        <div className="divide-y border rounded-md overflow-hidden">
+            {responses.map((r) => (
+                <ResponseRow key={r.code} response={r} />
+            ))}
+        </div>
+    );
+}

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>
+    );
+}