@djangocfg/ui-tools 2.1.285 → 2.1.287

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

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

@@ -0,0 +1,101 @@
+'use client';
+
+import React from 'react';
+
+import { SidePanel } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { usePlaygroundContext } from '../../context/PlaygroundContext';
+import { RequestPanel } from '../shared/RequestPanel';
+import { ResponsePanel } from '../shared/ResponsePanel';
+import { SendButton } from '../shared/SendButton';
+import { MethodBadge, Panel, relativePath } from '../shared/ui';
+
+interface SlideInPlaygroundProps {
+    open: boolean;
+    onClose: () => void;
+}
+
+// Width when only Request is visible vs. when Response is also rendered.
+// ``clamp(min, preferred, max)`` lets the panel scale with the viewport
+// instead of sitting at a fixed size that looks tiny on ultra-wide or
+// cramped on laptops.
+//
+// Narrow (Request only) — form content, no need to ever exceed ~480px.
+//   1280 viewport → 384  | 1440 → 432 | 1920 → 480 (cap) | 2560 → 480 (cap)
+//
+// Wide (Request + Response) — response can be huge JSON/HTML; give it room.
+//   1280 → 768 | 1440 → 864 | 1920 → 1152 | 2560 → 1280 (cap) | 3840 → 1280 (cap)
+//
+// Transition between the two values is animated by SidePanel.Content
+// (both ``transform`` and ``width`` listed there). clamp() interpolates
+// smoothly during that transition, no extra plumbing needed.
+const WIDTH_NARROW = 'clamp(380px, 30vw, 480px)';
+const WIDTH_WIDE = 'clamp(720px, 60vw, 1280px)';
+
+/**
+ * Right-side slide-in playground. Two-column layout appears once the
+ * user has a response in hand — before that, only the Request form is
+ * shown and the panel stays narrow so docs have room to breathe.
+ *
+ * State transitions:
+ *   - no endpoint        ⇒ panel not rendered
+ *   - endpoint, no resp  ⇒ narrow (Request only)
+ *   - endpoint + loading ⇒ wide (Request + Response spinner)
+ *   - endpoint + resp    ⇒ wide (Request + Response)
+ *
+ * Selecting a different endpoint clears ``response`` in the reducer,
+ * so the panel smoothly collapses back to narrow.
+ */
+export function SlideInPlayground({ open, onClose }: SlideInPlaygroundProps) {
+    const { state } = usePlaygroundContext();
+    const ep = state.selectedEndpoint;
+    const showResponse = state.response !== null || state.loading;
+    const width = showResponse ? WIDTH_WIDE : WIDTH_NARROW;
+
+    return (
+        <SidePanel open={open} onOpenChange={(v) => !v && onClose()} side="right">
+            <SidePanel.Content width={width} className="max-w-[95vw]">
+                <SidePanel.Header>
+                    <SidePanel.Title>Playground</SidePanel.Title>
+                    {ep && (
+                        <div className="flex items-center gap-2 min-w-0 flex-1">
+                            <MethodBadge method={ep.method} />
+                            <code className="font-mono text-[11px] text-muted-foreground truncate">
+                                {relativePath(ep.path)}
+                            </code>
+                        </div>
+                    )}
+                    <SidePanel.Close className="ml-auto" />
+                </SidePanel.Header>
+
+                {/* Body: 1 or 2 columns depending on whether we have a
+                    response to show. ``divide-x`` gives a 1px seam
+                    between the panes so they read as distinct surfaces. */}
+                <SidePanel.Body
+                    className={cn(
+                        'overflow-hidden grid divide-x transition-[grid-template-columns] duration-250',
+                        showResponse
+                            ? 'grid-cols-[minmax(0,1fr)_minmax(0,1fr)]'
+                            : 'grid-cols-1',
+                    )}
+                >
+                    <Panel>
+                        <RequestPanel />
+                    </Panel>
+                    {showResponse && (
+                        <Panel>
+                            <ResponsePanel />
+                        </Panel>
+                    )}
+                </SidePanel.Body>
+
+                {ep && (
+                    <SidePanel.Footer className="px-4 py-3">
+                        <SendButton />
+                    </SidePanel.Footer>
+                )}
+            </SidePanel.Content>
+        </SidePanel>
+    );
+}

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

@@ -0,0 +1,57 @@
+'use client';
+
+import React from 'react';
+
+import {
+    ResponsiveSheet,
+    ResponsiveSheetContent,
+    ResponsiveSheetHeader,
+    ResponsiveSheetTitle,
+} from '@djangocfg/ui-core/components';
+
+import { usePlaygroundContext } from '../../context/PlaygroundContext';
+import { RequestPanel } from '../shared/RequestPanel';
+import { ResponsePanel } from '../shared/ResponsePanel';
+import { SendButton } from '../shared/SendButton';
+
+interface TryItSheetProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Mobile/tablet fallback: the slide-in playground doesn't fit, so we
+ * open Request + Response inside a ResponsiveSheet (bottom drawer on
+ * mobile, side sheet on desktop). Response stays hidden until a
+ * request has been sent — matching the desktop ``SlideInPlayground``
+ * behaviour.
+ */
+export function TryItSheet({ open, onOpenChange }: TryItSheetProps) {
+    const { state } = usePlaygroundContext();
+    const showResponse = state.response !== null || state.loading;
+
+    return (
+        <ResponsiveSheet open={open} onOpenChange={onOpenChange}>
+            <ResponsiveSheetContent className="sm:max-w-xl flex flex-col h-full p-0">
+                <ResponsiveSheetHeader className="px-4 py-3 border-b shrink-0">
+                    <ResponsiveSheetTitle className="text-sm">Playground</ResponsiveSheetTitle>
+                </ResponsiveSheetHeader>
+                <div className="flex-1 min-h-0 flex flex-col divide-y">
+                    <div className={showResponse ? 'flex-1 min-h-0 flex flex-col' : 'flex-1 min-h-0 flex flex-col'}>
+                        <RequestPanel />
+                    </div>
+                    {showResponse && (
+                        <div className="flex-1 min-h-0 flex flex-col">
+                            <ResponsePanel />
+                        </div>
+                    )}
+                </div>
+                {state.selectedEndpoint && (
+                    <div className="shrink-0 border-t px-4 py-3 bg-background/95 backdrop-blur-sm">
+                        <SendButton />
+                    </div>
+                )}
+            </ResponsiveSheetContent>
+        </ResponsiveSheet>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/anchor.ts

@@ -0,0 +1,11 @@
+import type { ApiEndpoint } from '../../types';
+
+export function endpointAnchor(ep: Pick<ApiEndpoint, 'method' | 'path'>): string {
+  const slug = ep.path
+    .replace(/^https?:\/\/[^/]+/, '')
+    .replace(/[{}]/g, '')
+    .replace(/[^a-zA-Z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+  return `ep-${ep.method.toLowerCase()}-${slug}`;
+}

package/src/tools/OpenapiViewer/components/DocsLayout/grouping.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared grouping / sort for the docs layout.
+ *
+ * Sidebar and the docs longread MUST use the same order — otherwise
+ * scrollspy highlights jump around as the user scrolls (the sidebar's
+ * ordered list doesn't match the visual order of sections in the docs).
+ * This module is the single source of truth for that ordering.
+ */
+
+import type { ApiEndpoint } from '../../types';
+import { longestCommonPrefix } from './sidebarLabel';
+
+export type EndpointGroup = {
+    category: string;
+    endpoints: ApiEndpoint[];
+    /** Longest ``/``-aligned prefix shared by every endpoint in this
+     *  group. Used by the sidebar to strip the redundant group prefix
+     *  from fallback labels. */
+    commonPrefix: string;
+};
+
+const METHOD_ORDER: Record<string, number> = {
+    GET: 0,
+    POST: 1,
+    PUT: 2,
+    PATCH: 3,
+    DELETE: 4,
+};
+
+/**
+ * Stable, deterministic ordering so two different renders with the
+ * same endpoint list always produce the same visual sequence.
+ *
+ * Groups: alphabetical by tag/category, with ``Other`` pinned to the
+ * bottom (spec-less endpoints should not steal the top slot).
+ *
+ * Within a group: endpoints sorted by path first (so related resources
+ * cluster), then by HTTP method (read → write → delete).
+ */
+export function groupEndpoints(list: ApiEndpoint[]): EndpointGroup[] {
+    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: EndpointGroup[] = 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)),
+    }));
+
+    groups.sort((a, b) => {
+        if (a.category === 'Other') return 1;
+        if (b.category === 'Other') return -1;
+        return a.category.localeCompare(b.category);
+    });
+    return groups;
+}
+
+/** Flatten grouped endpoints back into a linear list that preserves
+ *  group order + within-group order. This is the canonical order for
+ *  both the sidebar and the docs longread. */
+export function flattenGrouped(groups: EndpointGroup[]): ApiEndpoint[] {
+    return groups.flatMap((g) => g.endpoints);
+}

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

@@ -0,0 +1,166 @@
+'use client';
+
+import React, { useCallback, useRef, useState } from 'react';
+
+import { Skeleton, TooltipProvider } from '@djangocfg/ui-core/components';
+import { useMediaQuery } from '@djangocfg/ui-core/hooks';
+
+import useOpenApiSchema from '../../hooks/useOpenApiSchema';
+import { usePlaygroundContext } from '../../context/PlaygroundContext';
+import type { ApiEndpoint } from '../../types';
+import { EndpointDraftSync } from '../shared/EndpointDraftSync';
+import { DocsSidebar } from './Sidebar';
+import { DocsView, type DocsViewHandle } from './DocsView';
+import { SlideInPlayground } from './SlideInPlayground';
+import { TryItSheet } from './TryItSheet';
+
+// ─── Root ─────────────────────────────────────────────────────────────────────
+
+export const DocsLayout: React.FC = () => {
+    const { state, config, setSelectedEndpoint } = usePlaygroundContext();
+    // The docs layout has a sidebar + docs column that already eat ~260px
+    // before the slide-in opens. Below 1024px the slide-in (min 720 wide)
+    // leaves docs with <250px — unreadable — so we fall back to the
+    // mobile-style ``TryItSheet`` on those viewports.
+    const isDesktop = useMediaQuery('(min-width: 1024px)');
+    const isMobile = !isDesktop;
+    const {
+        endpoints,
+        schemaInfo,
+        rawSchema,
+        resolvedBaseUrl,
+        loading,
+        error,
+        schemas,
+        currentSchema,
+        setCurrentSchema,
+    } = useOpenApiSchema({
+        schemas: config.schemas,
+        defaultSchemaId: config.defaultSchemaId,
+        baseUrl: config.baseUrl,
+    });
+
+    const [activeAnchor, setActiveAnchor] = useState<string | null>(null);
+    const [sheetOpen, setSheetOpen] = useState(false);
+    const docsRef = useRef<DocsViewHandle | null>(null);
+
+    // Desktop slide-in is driven directly by ``selectedEndpoint``. Keeping a
+    // separate open-state would mean two sources of truth for the same
+    // semantic — "which endpoint is loaded into the playground".
+    const slideOpen = !isMobile && state.selectedEndpoint !== null;
+
+    const handleTry = useCallback(
+        (ep: ApiEndpoint) => {
+            setSelectedEndpoint(ep);
+            if (isMobile) setSheetOpen(true);
+        },
+        [isMobile, setSelectedEndpoint],
+    );
+
+    const handleCloseSlide = useCallback(() => {
+        setSelectedEndpoint(null);
+    }, [setSelectedEndpoint]);
+
+    const handleNavigate = useCallback((anchor: string) => {
+        docsRef.current?.scrollToAnchor(anchor);
+    }, []);
+    // Esc handling lives inside SidePanel itself — no duplicate listener.
+
+    if (loading) {
+        return (
+            <div
+                className="grid grid-cols-[260px_1fr] min-h-0 overflow-hidden"
+                style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
+            >
+                <div className="border-r p-3 space-y-1.5">
+                    {Array.from({ length: 12 }).map((_, i) => (
+                        <Skeleton key={i} className="h-8 w-full rounded" />
+                    ))}
+                </div>
+                <div className="p-8 space-y-4">
+                    <Skeleton className="h-8 w-1/2" />
+                    <Skeleton className="h-4 w-full" />
+                    <Skeleton className="h-4 w-3/4" />
+                    <div className="mt-8 space-y-6">
+                        {Array.from({ length: 3 }).map((_, i) => (
+                            <div key={i} className="space-y-3">
+                                <Skeleton className="h-6 w-1/3" />
+                                <Skeleton className="h-20 w-full" />
+                            </div>
+                        ))}
+                    </div>
+                </div>
+            </div>
+        );
+    }
+
+    if (error) {
+        return (
+            <div
+                className="flex items-center justify-center p-8"
+                style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
+            >
+                <p className="text-sm text-destructive">Failed to load schema: {error}</p>
+            </div>
+        );
+    }
+
+    // Mobile/tablet: sidebar + docs only, playground opens in sheet.
+    if (isMobile) {
+        return (
+            <div
+                className="flex flex-col overflow-hidden"
+                style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
+            >
+                <EndpointDraftSync schemaId={currentSchema?.id ?? null} />
+                <DocsView
+                    ref={docsRef}
+                    info={schemaInfo}
+                    rawSchema={rawSchema}
+                    resolvedBaseUrl={resolvedBaseUrl}
+                    endpoints={endpoints}
+                    selectedVersion={state.selectedVersion}
+                    loadedEndpoint={state.selectedEndpoint}
+                    onTryEndpoint={handleTry}
+                    onActiveChange={setActiveAnchor}
+                />
+                <TryItSheet open={sheetOpen} onOpenChange={setSheetOpen} />
+            </div>
+        );
+    }
+
+    return (
+        <TooltipProvider delayDuration={350}>
+            <div
+                className="grid grid-cols-[260px_minmax(0,1fr)] min-h-0 overflow-hidden"
+                style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
+            >
+                <EndpointDraftSync schemaId={currentSchema?.id ?? null} />
+                <DocsSidebar
+                    info={schemaInfo}
+                    endpoints={endpoints}
+                    schemas={schemas}
+                    currentSchemaId={currentSchema?.id ?? null}
+                    onSchemaChange={setCurrentSchema}
+                    activeEndpointId={activeAnchor}
+                    selectedVersion={state.selectedVersion}
+                    onNavigate={handleNavigate}
+                />
+                <DocsView
+                    ref={docsRef}
+                    info={schemaInfo}
+                    rawSchema={rawSchema}
+                    resolvedBaseUrl={resolvedBaseUrl}
+                    endpoints={endpoints}
+                    selectedVersion={state.selectedVersion}
+                    loadedEndpoint={state.selectedEndpoint}
+                    onTryEndpoint={handleTry}
+                    onActiveChange={setActiveAnchor}
+                />
+                {/* SidePanel renders into <body> via portal, so it floats
+                    above the whole layout (sidebar + navbar included). */}
+                <SlideInPlayground open={slideOpen} onClose={handleCloseSlide} />
+            </div>
+        </TooltipProvider>
+    );
+};