@djangocfg/ui-tools 2.1.287 → 2.1.290

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Header/MetaActions.tsx

@@ -0,0 +1,146 @@
+'use client';
+
+import {
+    Check,
+    ChevronsDownUp,
+    ChevronsUpDown,
+    FileCode2,
+    Link2,
+} from 'lucide-react';
+import React, { useCallback, useMemo, useState } from 'react';
+
+import {
+    Tooltip,
+    TooltipContent,
+    TooltipTrigger,
+    SafeTooltipProvider,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useEndpointDocContext } from '../context';
+import { sectionKey, useEndpointDocStore } from '../store';
+import type { SectionId } from '../types';
+
+interface MetaActionsProps {
+    anchor: string;
+    endpointMarkdown: string;
+    /** Sections present on this endpoint — expand/collapse acts only
+     *  on visible rows, never on catalogue items the card doesn't render. */
+    presentSections: readonly SectionId[];
+}
+
+interface IconButtonProps {
+    label: string;
+    onClick: () => void;
+    children: React.ReactNode;
+    active?: boolean;
+}
+
+/** Tight 24×24 icon button used across the meta row. Keeps the hit
+ *  target compact so the row reads as a secondary metadata strip, not
+ *  a toolbar that competes with the path for attention. */
+function IconButton({ label, onClick, children, active }: IconButtonProps) {
+    return (
+        <Tooltip>
+            <TooltipTrigger asChild>
+                <button
+                    type="button"
+                    onClick={onClick}
+                    aria-label={label}
+                    className={cn(
+                        'shrink-0 h-6 w-6 inline-flex items-center justify-center rounded',
+                        'text-muted-foreground/60 hover:text-foreground hover:bg-muted transition-colors',
+                        active && 'text-emerald-500 hover:text-emerald-500',
+                    )}
+                >
+                    {children}
+                </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" className="text-[11px]">
+                {label}
+            </TooltipContent>
+        </Tooltip>
+    );
+}
+
+/** Inline meta-row actions: copy link · copy markdown · expand/collapse
+ *  all. Actions are always visible (corporate tool pattern) but sized
+ *  down so the path on the next line stays the visual focal point. */
+export function MetaActions({ anchor, endpointMarkdown, presentSections }: MetaActionsProps) {
+    const { endpointId } = useEndpointDocContext();
+    const expandAll = useEndpointDocStore((s) => s.expandAll);
+    const collapseAll = useEndpointDocStore((s) => s.collapseAll);
+    const openSections = useEndpointDocStore((s) => s.openSections);
+
+    const [justCopied, setJustCopied] = useState<'link' | 'md' | null>(null);
+    const flash = useCallback((which: 'link' | 'md') => {
+        setJustCopied(which);
+        setTimeout(() => setJustCopied(null), 1200);
+    }, []);
+
+    const mostlyOpen = useMemo(() => {
+        if (presentSections.length === 0) return false;
+        let openCount = 0;
+        for (const sid of presentSections) {
+            if (openSections[sectionKey(endpointId, sid)]) openCount += 1;
+        }
+        return openCount > presentSections.length / 2;
+    }, [openSections, presentSections, endpointId]);
+
+    const copyLink = useCallback(() => {
+        if (typeof window === 'undefined') return;
+        const url = `${window.location.origin}${window.location.pathname}#${anchor}`;
+        void navigator.clipboard?.writeText(url).then(() => flash('link'));
+    }, [anchor, flash]);
+
+    const copyMarkdown = useCallback(() => {
+        if (typeof window === 'undefined') return;
+        void navigator.clipboard?.writeText(endpointMarkdown).then(() => flash('md'));
+    }, [endpointMarkdown, flash]);
+
+    const toggleAll = useCallback(() => {
+        if (mostlyOpen) collapseAll(endpointId, presentSections);
+        else expandAll(endpointId, presentSections);
+    }, [mostlyOpen, collapseAll, expandAll, endpointId, presentSections]);
+
+    return (
+        <SafeTooltipProvider delayDuration={200}>
+            <div className="flex items-center gap-0.5">
+                <IconButton
+                    label={justCopied === 'link' ? 'Copied!' : 'Copy link to endpoint'}
+                    onClick={copyLink}
+                    active={justCopied === 'link'}
+                >
+                    {justCopied === 'link' ? (
+                        <Check className="h-3.5 w-3.5" />
+                    ) : (
+                        <Link2 className="h-3.5 w-3.5" />
+                    )}
+                </IconButton>
+                <IconButton
+                    label={justCopied === 'md' ? 'Copied!' : 'Copy as Markdown (for AI)'}
+                    onClick={copyMarkdown}
+                    active={justCopied === 'md'}
+                >
+                    {justCopied === 'md' ? (
+                        <Check className="h-3.5 w-3.5" />
+                    ) : (
+                        <FileCode2 className="h-3.5 w-3.5" />
+                    )}
+                </IconButton>
+                {presentSections.length >= 2 && (
+                    <IconButton
+                        label={mostlyOpen ? 'Collapse all sections' : 'Expand all sections'}
+                        onClick={toggleAll}
+                    >
+                        {mostlyOpen ? (
+                            <ChevronsDownUp className="h-3.5 w-3.5" />
+                        ) : (
+                            <ChevronsUpDown className="h-3.5 w-3.5" />
+                        )}
+                    </IconButton>
+                )}
+            </div>
+        </SafeTooltipProvider>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Header/MethodBadge.tsx

@@ -0,0 +1,6 @@
+'use client';
+
+// Thin re-export so the Header barrel file stays self-contained. The
+// actual badge lives in ``shared/ui`` because it's used by the sidebar
+// and the playground too — duplicating styles would drift.
+export { MethodBadge } from '../../../shared/ui';

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Header/PathDisplay.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+import { relativePath } from '../../../shared/ui';
+
+interface PathDisplayProps {
+    path: string;
+}
+
+/** The endpoint path as the visual focal point of the card. Renders in
+ *  large monospace so readers scanning the page land on it first — the
+ *  path is what distinguishes one endpoint from another, so it should
+ *  be the biggest visible element short of the section title hierarchy.
+ *
+ *  ``relativePath`` strips the resolved base URL so the docs always
+ *  show the API-local path, not an absolute URL cluttered with host
+ *  noise. */
+export function PathDisplay({ path }: PathDisplayProps) {
+    return (
+        <code
+            className="block font-mono text-lg md:text-xl font-semibold text-foreground leading-tight"
+            style={{ overflowWrap: 'anywhere', wordBreak: 'break-word' }}
+        >
+            {relativePath(path)}
+        </code>
+    );
+}

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

@@ -0,0 +1,87 @@
+'use client';
+
+import { Play } from 'lucide-react';
+import React, { useMemo } from 'react';
+
+import { Button } from '@djangocfg/ui-core/components';
+
+import { MarkdownMessage } from '../../../../../../components/markdown';
+import type { ApiEndpoint } from '../../../../types';
+import { endpointToMarkdown } from '../../../../utils/schemaExport';
+import type { SectionId } from '../types';
+import { MetaActions } from './MetaActions';
+import { MethodBadge } from './MethodBadge';
+import { PathDisplay } from './PathDisplay';
+
+interface EndpointHeaderProps {
+    endpoint: ApiEndpoint;
+    anchor: string;
+    isLoadedInPlayground: boolean;
+    onTryIt: () => void;
+    /** Sections actually rendered on this endpoint — drives the
+     *  expand/collapse-all icon in the meta row. */
+    presentSections: readonly SectionId[];
+}
+
+/** Card header, three stacked rows:
+ *   1. Meta — small utility strip: method badge · inline actions · Try-it.
+ *   2. Path — large monospace, the visual focus of the card.
+ *   3. Description — prose, aligned to the left edge under path.
+ *
+ *  Splitting metadata from the path lets the path itself become the
+ *  focal point — readers scan paths when scrolling, not badges. The
+ *  meta row stays compact so it reads as "info about this endpoint"
+ *  rather than "toolbar that competes for attention". */
+export function EndpointHeader({
+    endpoint,
+    anchor,
+    isLoadedInPlayground,
+    onTryIt,
+    presentSections,
+}: EndpointHeaderProps) {
+    // Memoise the markdown dump — only recomputes when the endpoint
+    // reference changes, not on unrelated re-renders of the subtree.
+    const endpointMd = useMemo(() => endpointToMarkdown(endpoint), [endpoint]);
+
+    return (
+        <header className="space-y-3">
+            {/* Row 1 — meta strip. Badge + inline icon actions on the
+                left, primary CTA on the right. Kept tight (24px tall)
+                so it doesn't visually compete with the path row below. */}
+            <div className="flex items-center gap-3 flex-wrap">
+                <div className="flex items-center gap-2 min-w-0">
+                    <MethodBadge method={endpoint.method} />
+                    <MetaActions
+                        anchor={anchor}
+                        endpointMarkdown={endpointMd}
+                        presentSections={presentSections}
+                    />
+                </div>
+                <Button
+                    size="sm"
+                    variant={isLoadedInPlayground ? 'secondary' : 'default'}
+                    onClick={onTryIt}
+                    className="ml-auto h-7 text-xs gap-1.5 px-2.5"
+                >
+                    <Play className="h-3 w-3" />
+                    {isLoadedInPlayground ? 'Loaded' : 'Try it'}
+                </Button>
+            </div>
+
+            {/* Row 2 — path as the visual focal point. Larger and more
+                prominent than it was when competing with the badge
+                and action icons inline. */}
+            <div className="min-w-0">
+                <PathDisplay path={endpoint.path} />
+            </div>
+
+            {/* Row 3 — description, aligned to the left edge under the
+                path. Text-sm so it reads as subtitle, not body copy. */}
+            {endpoint.description && (
+                <div className="text-muted-foreground text-sm">
+                    <MarkdownMessage content={endpoint.description} />
+                </div>
+            )}
+        </header>
+    );
+}

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