@djangocfg/ui-tools 2.1.285 → 2.1.286

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

@@ -0,0 +1,268 @@
+'use client';
+
+import { Check, Link2, Play } from 'lucide-react';
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { Button, CopyButton } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { MarkdownMessage } from '../../../../components/markdown';
+import type { ApiEndpoint } from '../../types';
+import { endpointToMarkdown } from '../../utils/schemaExport';
+import { MethodBadge, relativePath } from '../shared/ui';
+import { endpointAnchor } from './anchor';
+import { schemaToFields, type SchemaField } from './schemaFields';
+
+interface EndpointDocProps {
+    endpoint: ApiEndpoint;
+    /** Is this endpoint currently loaded in the sticky playground? */
+    isLoadedInPlayground: boolean;
+    onTryIt: () => void;
+}
+
+export function EndpointDoc({ endpoint, isLoadedInPlayground, onTryIt }: EndpointDocProps) {
+    const anchor = endpointAnchor(endpoint);
+    const pathParams = endpoint.parameters?.filter((p) => endpoint.path.includes(`{${p.name}}`)) ?? [];
+    const queryParams = endpoint.parameters?.filter((p) => !endpoint.path.includes(`{${p.name}}`)) ?? [];
+
+    const [copied, setCopied] = useState(false);
+    const copyAnchor = useCallback(() => {
+        if (typeof window === 'undefined') return;
+        const url = `${window.location.origin}${window.location.pathname}#${anchor}`;
+        void navigator.clipboard?.writeText(url).then(() => {
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1200);
+        });
+    }, [anchor]);
+
+    // Markdown summary used by the Copy-for-AI button. Memoised so moving
+    // the mouse over the section doesn't rebuild the same string.
+    const endpointMd = useMemo(() => endpointToMarkdown(endpoint), [endpoint]);
+
+    return (
+        <section
+            id={anchor}
+            data-endpoint-anchor={anchor}
+            className="scroll-mt-24 py-10 first:pt-0"
+        >
+            <header className="space-y-4">
+                <div className="flex items-start justify-between gap-3 flex-wrap">
+                    <div className="flex items-baseline gap-2.5 min-w-0 flex-1 group/header">
+                        <span className="shrink-0 translate-y-[2px]">
+                            <MethodBadge method={endpoint.method} />
+                        </span>
+                        <code
+                            className="font-mono text-sm md:text-[15px] font-medium text-foreground leading-snug min-w-0"
+                            style={{ overflowWrap: 'anywhere', wordBreak: 'break-word' }}
+                        >
+                            {relativePath(endpoint.path)}
+                        </code>
+                        <button
+                            type="button"
+                            onClick={copyAnchor}
+                            title="Copy link to this section"
+                            className={cn(
+                                'shrink-0 p-1 rounded text-muted-foreground/40 hover:text-foreground hover:bg-muted transition-all',
+                                'opacity-0 group-hover/header:opacity-100',
+                                copied && 'opacity-100 text-emerald-500',
+                            )}
+                        >
+                            {copied ? <Check className="h-3.5 w-3.5" /> : <Link2 className="h-3.5 w-3.5" />}
+                        </button>
+                        <CopyButton
+                            value={endpointMd}
+                            title="Copy endpoint as markdown (for AI)"
+                            variant="ghost"
+                            size="icon"
+                            iconClassName="h-3.5 w-3.5"
+                            className={cn(
+                                'shrink-0 h-6 w-6 text-muted-foreground/40 hover:text-foreground',
+                                'opacity-0 group-hover/header:opacity-100 focus-visible:opacity-100',
+                            )}
+                        />
+                    </div>
+                    <Button
+                        size="sm"
+                        variant={isLoadedInPlayground ? 'secondary' : 'default'}
+                        onClick={onTryIt}
+                        className="shrink-0 h-8 text-xs gap-1.5 lg:flex hidden"
+                    >
+                        <Play className="h-3 w-3" />
+                        {isLoadedInPlayground ? 'Loaded' : 'Try it'}
+                    </Button>
+                </div>
+                {endpoint.description && (
+                    <div className="text-muted-foreground">
+                        <MarkdownMessage content={endpoint.description} />
+                    </div>
+                )}
+                {/* Mobile/tablet: Try it sits under the description so it's always reachable */}
+                <Button
+                    size="sm"
+                    variant={isLoadedInPlayground ? 'secondary' : 'default'}
+                    onClick={onTryIt}
+                    className="lg:hidden h-8 text-xs gap-1.5"
+                >
+                    <Play className="h-3 w-3" />
+                    {isLoadedInPlayground ? 'Loaded in playground' : 'Try it'}
+                </Button>
+            </header>
+
+            {(pathParams.length > 0 || queryParams.length > 0 || endpoint.requestBody || endpoint.responses?.length) && (
+                <div className="mt-8 space-y-8">
+                    {pathParams.length > 0 && (
+                        <ParamTable title="Path parameters" params={pathParams} />
+                    )}
+                    {queryParams.length > 0 && (
+                        <ParamTable title="Query parameters" params={queryParams} />
+                    )}
+                    {endpoint.requestBody && (
+                        <RequestBodySection body={endpoint.requestBody} />
+                    )}
+                    {endpoint.responses && endpoint.responses.length > 0 && (
+                        <Subsection title="Responses">
+                            <div className="divide-y border rounded-md overflow-hidden">
+                                {endpoint.responses.map((r) => (
+                                    <div
+                                        key={r.code}
+                                        className="grid grid-cols-[72px_minmax(0,1fr)] items-center gap-3 px-3 py-2.5 bg-background"
+                                    >
+                                        <div className="flex justify-start">
+                                            <StatusTag code={r.code} />
+                                        </div>
+                                        <span className="text-sm text-muted-foreground leading-relaxed break-words">
+                                            {r.description}
+                                        </span>
+                                    </div>
+                                ))}
+                            </div>
+                        </Subsection>
+                    )}
+                </div>
+            )}
+        </section>
+    );
+}
+
+function RequestBodySection({ body }: { body: NonNullable<ApiEndpoint['requestBody']> }) {
+    const fields = useMemo(() => schemaToFields(body.schema), [body.schema]);
+    const typeLabel = body.schema
+        ? body.type === 'array'
+            ? `array<${(body.schema as { items?: { type?: string } }).items?.type ?? 'object'}>`
+            : body.type
+        : body.type;
+
+    return (
+        <Subsection title="Request body">
+            <div className="space-y-2">
+                <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>
+                {fields.length > 0 && <FieldsTable fields={fields} />}
+            </div>
+        </Subsection>
+    );
+}
+
+function FieldsTable({ fields }: { fields: SchemaField[] }) {
+    return (
+        <div className="divide-y border rounded-md overflow-hidden">
+            {fields.map((f) => (
+                <div key={f.name} 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">{f.name}</code>
+                        {f.required && (
+                            <span
+                                title="Required"
+                                className="text-[9px] text-destructive font-bold leading-none"
+                            >
+                                *
+                            </span>
+                        )}
+                        <code className="font-mono text-[11px] text-muted-foreground/70">{f.type}</code>
+                    </div>
+                    {f.description && (
+                        <p className="text-xs text-muted-foreground leading-relaxed break-words">
+                            {f.description}
+                        </p>
+                    )}
+                </div>
+            ))}
+        </div>
+    );
+}
+
+function Subsection({ title, children }: { title: string; children: React.ReactNode }) {
+    return (
+        <div className="space-y-2.5">
+            <h4 className="text-[10px] font-semibold uppercase tracking-[0.12em] text-muted-foreground/70">
+                {title}
+            </h4>
+            {children}
+        </div>
+    );
+}
+
+function ParamTable({
+    title,
+    params,
+}: {
+    title: string;
+    params: NonNullable<ApiEndpoint['parameters']>;
+}) {
+    return (
+        <Subsection title={title}>
+            <div className="divide-y border rounded-md overflow-hidden">
+                {params.map((p) => (
+                    <div key={p.name} 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">
+                                {p.name}
+                            </code>
+                            {p.required && (
+                                <span
+                                    title="Required"
+                                    className="text-[9px] text-destructive font-bold leading-none"
+                                >
+                                    *
+                                </span>
+                            )}
+                            <code className="font-mono text-[11px] text-muted-foreground/70">
+                                {p.type}
+                            </code>
+                        </div>
+                        {p.description ? (
+                            <p className="text-xs text-muted-foreground leading-relaxed break-words">
+                                {p.description}
+                            </p>
+                        ) : null}
+                    </div>
+                ))}
+            </div>
+        </Subsection>
+    );
+}
+
+function StatusTag({ code }: { code: string }) {
+    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/SchemaCopyMenu.tsx

@@ -0,0 +1,139 @@
+'use client';
+
+import { Check, ChevronDown, Sparkles } from 'lucide-react';
+import React, { useCallback, useMemo, useState } from 'react';
+
+import {
+    Button,
+    DropdownMenu,
+    DropdownMenuContent,
+    DropdownMenuItem,
+    DropdownMenuLabel,
+    DropdownMenuSeparator,
+    DropdownMenuTrigger,
+} from '@djangocfg/ui-core/components';
+
+import type { ApiEndpoint, OpenApiSchema } from '../../types';
+import {
+    formatBytes,
+    toCompactJson,
+    toMarkdown,
+    toRawJson,
+} from '../../utils/schemaExport';
+
+type Flavour = 'markdown' | 'compact' | 'raw';
+
+const FLAVOUR_LABELS: Record<Flavour, { title: string; hint: string }> = {
+    markdown: {
+        title: 'Markdown for LLM',
+        hint: 'Endpoints + params as prose. Smallest.',
+    },
+    compact: {
+        title: 'Compact JSON',
+        hint: 'Dereferenced, no examples, minified.',
+    },
+    raw: {
+        title: 'Raw JSON',
+        hint: 'Full OpenAPI document with $refs.',
+    },
+};
+
+interface SchemaCopyMenuProps {
+    schema: OpenApiSchema | null;
+    endpoints: ApiEndpoint[];
+    /** Resolved base URL that gets embedded into the copy so the AI
+     *  receives working URLs, not the ones originally in ``schema.servers``. */
+    baseUrl?: string;
+}
+
+/**
+ * Per-schema copy dropdown. Shows three flavours tuned for different LLM
+ * use-cases. We compute each flavour lazily (only on click) because
+ * dereferencing + stringifying a large schema can be non-trivial — sizes
+ * are displayed after the first successful copy, via a tiny cache.
+ */
+export function SchemaCopyMenu({ schema, endpoints, baseUrl }: SchemaCopyMenuProps) {
+    const [sizeCache, setSizeCache] = useState<Partial<Record<Flavour, string>>>({});
+    const [justCopied, setJustCopied] = useState<Flavour | null>(null);
+    const [open, setOpen] = useState(false);
+
+    const isReady = schema !== null && endpoints.length > 0;
+
+    const build = useCallback(
+        (flavour: Flavour): string => {
+            if (!schema) return '';
+            if (flavour === 'markdown') return toMarkdown(schema, endpoints, baseUrl);
+            if (flavour === 'compact') return toCompactJson(schema, baseUrl);
+            return toRawJson(schema, baseUrl);
+        },
+        [schema, endpoints, baseUrl],
+    );
+
+    const handleCopy = useCallback(
+        async (flavour: Flavour) => {
+            if (!isReady) return;
+            const text = build(flavour);
+            try {
+                await navigator.clipboard.writeText(text);
+                setSizeCache((prev) => ({ ...prev, [flavour]: formatBytes(text) }));
+                setJustCopied(flavour);
+                setTimeout(() => setJustCopied(null), 1500);
+                setOpen(false);
+            } catch {
+                // Silent: clipboard perm denied. CopyButton handles the same case.
+            }
+        },
+        [build, isReady],
+    );
+
+    const flavours = useMemo<Flavour[]>(() => ['markdown', 'compact', 'raw'], []);
+
+    return (
+        <DropdownMenu open={open} onOpenChange={setOpen}>
+            <DropdownMenuTrigger asChild>
+                <Button variant="outline" size="sm" className="h-8 gap-1.5 text-xs" disabled={!isReady}>
+                    <Sparkles className="h-3 w-3" />
+                    Copy for AI
+                    <ChevronDown className="h-3 w-3 opacity-60" />
+                </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" className="w-72">
+                <DropdownMenuLabel className="text-[10px] uppercase tracking-wider text-muted-foreground/70">
+                    Copy schema
+                </DropdownMenuLabel>
+                <DropdownMenuSeparator />
+                {flavours.map((f) => {
+                    const label = FLAVOUR_LABELS[f];
+                    const size = sizeCache[f];
+                    const isDone = justCopied === f;
+                    return (
+                        <DropdownMenuItem
+                            key={f}
+                            onClick={(e) => {
+                                e.preventDefault();
+                                void handleCopy(f);
+                            }}
+                            className="flex flex-col items-start gap-0.5 py-2 cursor-pointer"
+                        >
+                            <div className="flex w-full items-center gap-2">
+                                <span className="text-xs font-medium flex-1">{label.title}</span>
+                                {isDone ? (
+                                    <span className="inline-flex items-center gap-1 text-[10px] text-emerald-500">
+                                        <Check className="h-3 w-3" /> Copied
+                                    </span>
+                                ) : size ? (
+                                    <span className="text-[10px] font-mono text-muted-foreground/70 tabular-nums">
+                                        {size}
+                                    </span>
+                                ) : null}
+                            </div>
+                            <span className="text-[10px] text-muted-foreground/70 leading-snug">
+                                {label.hint}
+                            </span>
+                        </DropdownMenuItem>
+                    );
+                })}
+            </DropdownMenuContent>
+        </DropdownMenu>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/Sidebar.tsx

@@ -0,0 +1,211 @@
+'use client';
+
+import { Search } from 'lucide-react';
+import React, { useEffect, useMemo, useState } from 'react';
+
+import {
+    Combobox,
+    Input,
+    Tooltip,
+    TooltipContent,
+    TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ApiEndpoint, OpenApiInfo, SchemaSource } from '../../types';
+import { deduplicateEndpoints } from '../../utils/versionManager';
+import { MethodBadge, ScrollArea } from '../shared/ui';
+import { endpointAnchor } from './anchor';
+import { longestCommonPrefix, sidebarLabel, sidebarTooltip } from './sidebarLabel';
+
+type Group = {
+    category: string;
+    endpoints: ApiEndpoint[];
+    /** Longest ``/``-aligned prefix shared by every endpoint in this group.
+     *  Stripped from labels that fall back to showing the path. */
+    commonPrefix: string;
+};
+
+const METHOD_ORDER: Record<string, number> = {
+    GET: 0, POST: 1, PUT: 2, PATCH: 3, DELETE: 4,
+};
+
+function groupEndpoints(list: ApiEndpoint[]): Group[] {
+    const map = new Map<string, ApiEndpoint[]>();
+    for (const ep of list) {
+        const arr = map.get(ep.category) ?? [];
+        arr.push(ep);
+        map.set(ep.category, arr);
+    }
+    const groups: Group[] = Array.from(map.entries()).map(([category, endpoints]) => ({
+        category,
+        endpoints: [...endpoints].sort((a, b) => {
+            const byPath = a.path.localeCompare(b.path);
+            if (byPath !== 0) return byPath;
+            return (METHOD_ORDER[a.method] ?? 99) - (METHOD_ORDER[b.method] ?? 99);
+        }),
+        commonPrefix: longestCommonPrefix(endpoints.map((e) => e.path)),
+    }));
+    // Alphabetical, but "Other" sinks to the bottom.
+    groups.sort((a, b) => {
+        if (a.category === 'Other') return 1;
+        if (b.category === 'Other') return -1;
+        return a.category.localeCompare(b.category);
+    });
+    return groups;
+}
+
+export interface DocsSidebarProps {
+    info: OpenApiInfo | null;
+    endpoints: ApiEndpoint[];
+    schemas: SchemaSource[];
+    currentSchemaId: string | null;
+    onSchemaChange: (id: string) => void;
+    activeEndpointId: string | null;
+    selectedVersion: string;
+    onNavigate: (anchor: string) => void;
+}
+
+export function DocsSidebar({
+    info,
+    endpoints,
+    schemas,
+    currentSchemaId,
+    onSchemaChange,
+    activeEndpointId,
+    selectedVersion,
+    onNavigate,
+}: DocsSidebarProps) {
+    const [search, setSearch] = useState('');
+    const [debounced, setDebounced] = useState('');
+
+    useEffect(() => {
+        const id = setTimeout(() => setDebounced(search), 120);
+        return () => clearTimeout(id);
+    }, [search]);
+
+    const filteredGroups = useMemo(() => {
+        let list = deduplicateEndpoints(endpoints, selectedVersion);
+        if (debounced) {
+            const q = debounced.toLowerCase();
+            list = list.filter((e) =>
+                e.summary.toLowerCase().includes(q) ||
+                e.name.toLowerCase().includes(q) ||
+                e.description.toLowerCase().includes(q) ||
+                e.path.toLowerCase().includes(q),
+            );
+        }
+        return groupEndpoints(list);
+    }, [endpoints, debounced, selectedVersion]);
+
+    const schemaOptions = useMemo(
+        () => schemas.map((s) => ({ value: s.id, label: s.name })),
+        [schemas],
+    );
+    const hasMultipleSchemas = schemas.length > 1;
+    const apiTitle = info?.title ?? 'API Reference';
+
+    return (
+        <aside className="flex flex-col min-h-0 border-r bg-muted/10">
+            {/* Brand row */}
+            <div className="shrink-0 border-b px-4 h-12 flex items-center gap-2">
+                <span className="text-[13px] font-semibold text-foreground truncate">
+                    {apiTitle}
+                </span>
+                {info?.version && (
+                    <span className="font-mono text-[10px] text-muted-foreground/70 shrink-0">
+                        v{info.version}
+                    </span>
+                )}
+            </div>
+
+            {/* Controls */}
+            <div className="shrink-0 border-b px-3 py-3 space-y-2">
+                {hasMultipleSchemas && (
+                    <Combobox
+                        options={schemaOptions}
+                        value={currentSchemaId ?? ''}
+                        onValueChange={(id) => id && onSchemaChange(id)}
+                        placeholder="Select API"
+                        searchPlaceholder="Search APIs…"
+                        emptyText="No APIs found"
+                        className="w-full h-8 text-xs"
+                    />
+                )}
+                <div className="relative">
+                    <Search className="absolute left-2.5 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-muted-foreground/50 pointer-events-none" />
+                    <Input
+                        placeholder="Search endpoints…"
+                        value={search}
+                        onChange={(e: React.ChangeEvent<HTMLInputElement>) => setSearch(e.target.value)}
+                        className="pl-8 h-8 text-xs"
+                    />
+                </div>
+            </div>
+
+            <ScrollArea>
+                {filteredGroups.length === 0 ? (
+                    <div className="py-10 px-4 text-center text-xs text-muted-foreground">
+                        {debounced
+                            ? `No endpoints match "${debounced}"`
+                            : 'No endpoints in this schema'}
+                    </div>
+                ) : (
+                    <nav className="py-2">
+                        {filteredGroups.map((group) => (
+                            <div key={group.category} className="mb-4 last:mb-2">
+                                <div className="px-4 py-1.5 text-[10px] font-semibold uppercase tracking-[0.14em] text-muted-foreground/50 select-none">
+                                    {group.category}
+                                </div>
+                                <div>
+                                    {group.endpoints.map((ep) => {
+                                        const anchor = endpointAnchor(ep);
+                                        const isActive = activeEndpointId === anchor;
+                                        const label = sidebarLabel(ep, group.commonPrefix);
+                                        const tooltip = sidebarTooltip(ep);
+                                        // Summary → sans-serif (reads like an outline).
+                                        // Path-tail fallback → mono (reads like code).
+                                        const useMono = !ep.summary;
+                                        return (
+                                            <Tooltip key={`${ep.method}-${ep.path}`} delayDuration={350}>
+                                                <TooltipTrigger asChild>
+                                                    <button
+                                                        onClick={() => onNavigate(anchor)}
+                                                        aria-current={isActive ? 'location' : undefined}
+                                                        className={cn(
+                                                            'relative group w-full text-left flex items-center gap-2 pl-4 pr-3 py-1.5 transition-colors',
+                                                            isActive
+                                                                ? 'bg-primary/10 text-foreground'
+                                                                : 'hover:bg-muted/40 text-foreground/75 hover:text-foreground',
+                                                        )}
+                                                    >
+                                                        {isActive && (
+                                                            <span className="absolute left-0 top-1 bottom-1 w-0.5 rounded-r bg-primary" />
+                                                        )}
+                                                        <MethodBadge method={ep.method} />
+                                                        <span
+                                                            className={cn(
+                                                                'truncate leading-tight flex-1 min-w-0',
+                                                                useMono ? 'font-mono text-[11px]' : 'text-[12px]',
+                                                                isActive && 'text-foreground font-medium',
+                                                            )}
+                                                        >
+                                                            {label}
+                                                        </span>
+                                                    </button>
+                                                </TooltipTrigger>
+                                                <TooltipContent side="right" align="center" className="font-mono text-[11px]">
+                                                    {tooltip}
+                                                </TooltipContent>
+                                            </Tooltip>
+                                        );
+                                    })}
+                                </div>
+                            </div>
+                        ))}
+                    </nav>
+                )}
+            </ScrollArea>
+        </aside>
+    );
+}