@djangocfg/ui-tools 2.1.289 → 2.1.291

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Parameters/ParamGroup.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import type { ApiEndpoint } from '../../../../types';
+import { ParamRow } from './ParamRow';
+
+interface ParamGroupProps {
+    /** Small uppercase label shown above the group (``Path``, ``Query``). */
+    label: string;
+    params: NonNullable<ApiEndpoint['parameters']>;
+}
+
+/** Labelled block of parameter rows. We split path vs query so the user
+ *  can tell which values go in the URL template vs the query string at
+ *  a glance — both are ``parameters`` in OpenAPI terms but they land in
+ *  different places in the generated request. */
+export function ParamGroup({ label, params }: ParamGroupProps) {
+    if (params.length === 0) return null;
+    return (
+        <div className="space-y-1.5">
+            <div className="text-[10px] font-semibold uppercase tracking-[0.1em] text-muted-foreground/60 px-1">
+                {label}
+            </div>
+            <div className="divide-y border rounded-md overflow-hidden">
+                {params.map((p) => (
+                    <ParamRow key={`${label}-${p.name}`} param={p} />
+                ))}
+            </div>
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Parameters/ParamRow.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import type { ApiEndpoint } from '../../../../types';
+
+type Param = NonNullable<ApiEndpoint['parameters']>[number];
+
+interface ParamRowProps {
+    param: Param;
+}
+
+/** Single parameter row. Name + required marker + type + (optional)
+ *  description. Wrapped in ``<div>`` rather than a table row so the
+ *  list degrades to a stack on narrow widths without losing semantics. */
+export function ParamRow({ param }: ParamRowProps) {
+    return (
+        <div className="px-3 py-2.5 bg-background space-y-1">
+            <div className="flex items-baseline gap-2 flex-wrap">
+                <code className="font-mono text-xs font-medium text-foreground">{param.name}</code>
+                {param.required && (
+                    <span
+                        title="Required"
+                        className="text-[9px] text-destructive font-bold leading-none"
+                    >
+                        *
+                    </span>
+                )}
+                <code className="font-mono text-[11px] text-muted-foreground/70">{param.type}</code>
+            </div>
+            {param.description && (
+                <p className="text-xs text-muted-foreground leading-relaxed break-words">
+                    {param.description}
+                </p>
+            )}
+        </div>
+    );
+}

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

@@ -0,0 +1,22 @@
+'use client';
+
+import type { ApiEndpoint } from '../../../../types';
+import { ParamGroup } from './ParamGroup';
+
+interface ParametersProps {
+    pathParams: NonNullable<ApiEndpoint['parameters']>;
+    queryParams: NonNullable<ApiEndpoint['parameters']>;
+}
+
+/** Combined path + query parameters block. Each group renders only
+ *  when non-empty; when both are empty the parent should not render
+ *  the Section at all (we check up-stream so the Section badge shows a
+ *  real count). */
+export function Parameters({ pathParams, queryParams }: ParametersProps) {
+    return (
+        <div className="space-y-4">
+            <ParamGroup label="Path" params={pathParams} />
+            <ParamGroup label="Query" params={queryParams} />
+        </div>
+    );
+}

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

@@ -0,0 +1,33 @@
+'use client';
+
+import type { ApiEndpoint } from '../../../../types';
+import { SchemaFields } from '../SchemaFields';
+
+interface RequestBodyProps {
+    body: NonNullable<ApiEndpoint['requestBody']>;
+}
+
+/** Request body preview. Shows a short type summary line (``object``,
+ *  ``array<object>``, …) alongside the body description, then the
+ *  tree-view of fields. The example payload is rendered below in its
+ *  own section (code samples) because the user often wants to copy it
+ *  independently from inspecting the shape. */
+export function RequestBody({ body }: RequestBodyProps) {
+    const typeLabel = body.schema
+        ? body.type === 'array'
+            ? `array<${(body.schema as { items?: { type?: string } }).items?.type ?? 'object'}>`
+            : body.type
+        : body.type;
+
+    return (
+        <div className="space-y-3">
+            <div className="flex items-baseline gap-2 flex-wrap">
+                <code className="font-mono text-[11px] text-muted-foreground/80">{typeLabel}</code>
+                {body.description && (
+                    <span className="text-xs text-muted-foreground">{body.description}</span>
+                )}
+            </div>
+            {body.schema && <SchemaFields schema={body.schema} />}
+        </div>
+    );
+}

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[];
+}