@djangocfg/ui-tools 2.1.285 → 2.1.287

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

@@ -0,0 +1,137 @@
+'use client';
+
+import React, { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import type { ApiEndpoint, OpenApiInfo, OpenApiSchema } from '../../types';
+import { deduplicateEndpoints } from '../../utils/versionManager';
+import { ApiIntroSection } from './ApiIntroSection';
+import { EndpointDoc } from './EndpointDoc';
+import { endpointAnchor } from './anchor';
+
+export interface DocsViewHandle {
+    scrollToAnchor: (anchor: string) => void;
+}
+
+interface DocsViewProps {
+    info: OpenApiInfo | null;
+    rawSchema: OpenApiSchema | null;
+    resolvedBaseUrl?: string;
+    endpoints: ApiEndpoint[];
+    selectedVersion: string;
+    loadedEndpoint: ApiEndpoint | null;
+    onTryEndpoint: (ep: ApiEndpoint) => void;
+    onActiveChange: (anchor: string | null) => void;
+}
+
+export const DocsView = React.forwardRef<DocsViewHandle, DocsViewProps>(function DocsView(
+    {
+        info,
+        rawSchema,
+        resolvedBaseUrl,
+        endpoints,
+        selectedVersion,
+        loadedEndpoint,
+        onTryEndpoint,
+        onActiveChange,
+    },
+    ref,
+) {
+    const scrollRef = useRef<HTMLDivElement | null>(null);
+
+    const visibleEndpoints = useMemo(
+        () => deduplicateEndpoints(endpoints, selectedVersion),
+        [endpoints, selectedVersion],
+    );
+
+    // Scroll a given section into view. Imperative handle so the
+    // sidebar (not a descendant) can trigger this without props drilling.
+    const scrollToAnchor = useCallback((anchor: string) => {
+        const root = scrollRef.current;
+        if (!root) return;
+        const el = root.querySelector<HTMLElement>(`[data-endpoint-anchor="${anchor}"]`);
+        if (!el) return;
+        el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }, []);
+
+    React.useImperativeHandle(ref, () => ({ scrollToAnchor }), [scrollToAnchor]);
+
+    // Scrollspy: pick the topmost endpoint section whose top is near the
+    // upper third of the viewport. Runs on every scroll event (rAF-throttled)
+    // — an IntersectionObserver has flaky behaviour for "which one is active"
+    // when several sections overlap the root margin band at once.
+    useEffect(() => {
+        const root = scrollRef.current;
+        if (!root) return;
+
+        let rafId = 0;
+        let lastActive: string | null = null;
+
+        const compute = () => {
+            rafId = 0;
+            const sections = root.querySelectorAll<HTMLElement>('[data-endpoint-anchor]');
+            if (sections.length === 0) return;
+            const rootTop = root.getBoundingClientRect().top;
+            const threshold = rootTop + root.clientHeight * 0.25;
+            let active: string | null = null;
+            for (const s of Array.from(sections)) {
+                const top = s.getBoundingClientRect().top;
+                if (top <= threshold) {
+                    active = s.dataset.endpointAnchor ?? null;
+                } else {
+                    break;
+                }
+            }
+            if (active !== lastActive) {
+                lastActive = active;
+                onActiveChange(active);
+            }
+        };
+
+        const onScroll = () => {
+            if (rafId) return;
+            rafId = requestAnimationFrame(compute);
+        };
+
+        compute();
+        root.addEventListener('scroll', onScroll, { passive: true });
+        return () => {
+            root.removeEventListener('scroll', onScroll);
+            if (rafId) cancelAnimationFrame(rafId);
+        };
+    }, [visibleEndpoints, onActiveChange]);
+
+    return (
+        <div ref={scrollRef} className="flex-1 overflow-y-auto min-h-0">
+            <div className="mx-auto w-full max-w-[860px] px-6 md:px-10 lg:px-14 py-12">
+                {info && (
+                    <ApiIntroSection
+                        info={info}
+                        schema={rawSchema}
+                        endpoints={visibleEndpoints}
+                        resolvedBaseUrl={resolvedBaseUrl}
+                    />
+                )}
+                {visibleEndpoints.length === 0 ? (
+                    <div className="py-16 text-center text-sm text-muted-foreground">
+                        No endpoints to display.
+                    </div>
+                ) : (
+                    <div className="divide-y divide-border/60">
+                        {visibleEndpoints.map((ep) => {
+                            const isLoaded =
+                                loadedEndpoint?.method === ep.method && loadedEndpoint?.path === ep.path;
+                            return (
+                                <EndpointDoc
+                                    key={`${ep.method}-${ep.path}`}
+                                    endpoint={ep}
+                                    isLoadedInPlayground={isLoaded}
+                                    onTryIt={() => onTryEndpoint(ep)}
+                                />
+                            );
+                        })}
+                    </div>
+                )}
+            </div>
+        </div>
+    );
+});

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