@djangocfg/ui-tools 2.1.284 → 2.1.286

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

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

@@ -0,0 +1,121 @@
+/**
+ * Flatten a JSON Schema node into a flat list of (name, type, required,
+ * description) rows, ready to feed into the existing parameter table.
+ *
+ * Rules:
+ *   - ``type: object``  → one row per property.
+ *   - ``type: array``   → recurse into items; prefix each row with ``[].``
+ *                         so the caller sees "[].username string" etc.
+ *   - Nested objects    → dot-joined path: ``category.name``. We expand
+ *                         one level; deeper graphs get a single summary
+ *                         row ("category.* (object)") to keep the table
+ *                         readable.
+ *
+ * This is a presentation helper — not a full form generator. It powers
+ * the read-only fields table shown in the docs longread.
+ */
+
+type JsonSchemaNode = Record<string, unknown> & {
+    type?: string;
+    properties?: Record<string, JsonSchemaNode>;
+    required?: string[];
+    items?: JsonSchemaNode;
+    enum?: unknown[];
+    description?: string;
+    format?: string;
+};
+
+export interface SchemaField {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+}
+
+const MAX_DEPTH = 2;
+
+function describeType(node: JsonSchemaNode): string {
+    if (!node.type && node.properties) return 'object';
+    const base = node.type || 'any';
+    if (base === 'array') {
+        const itemType = node.items ? describeType(node.items) : 'any';
+        return `array<${itemType}>`;
+    }
+    if (Array.isArray(node.enum) && node.enum.length > 0) {
+        return `${base} enum`;
+    }
+    if (node.format) return `${base} (${node.format})`;
+    return base;
+}
+
+export function schemaToFields(
+    schema: JsonSchemaNode | undefined,
+    prefix = '',
+    depth = 0,
+): SchemaField[] {
+    if (!schema || depth > MAX_DEPTH) return [];
+
+    // Unwrap arrays: show the inner item's fields, prefixed with ``[]``.
+    if (schema.type === 'array') {
+        if (!schema.items) {
+            return [{ name: prefix || '[]', type: 'array', required: false }];
+        }
+        const inner = schemaToFields(schema.items, prefix ? `${prefix}[]` : '[]', depth);
+        if (inner.length === 0) {
+            return [
+                {
+                    name: prefix || '[]',
+                    type: describeType(schema),
+                    required: false,
+                    description: schema.description,
+                },
+            ];
+        }
+        return inner;
+    }
+
+    // Primitives and unknown — single row.
+    if (schema.type !== 'object' && !schema.properties) {
+        return [
+            {
+                name: prefix || '(body)',
+                type: describeType(schema),
+                required: false,
+                description: schema.description,
+            },
+        ];
+    }
+
+    // Objects — one row per property, recurse for nested objects/arrays.
+    const required = new Set(schema.required ?? []);
+    const rows: SchemaField[] = [];
+    const props = schema.properties ?? {};
+    for (const [key, node] of Object.entries(props)) {
+        const fullName = prefix ? `${prefix}.${key}` : key;
+        const isRequired = required.has(key);
+
+        const isNestedExpandable =
+            (node.type === 'object' && node.properties) ||
+            (node.type === 'array' && node.items);
+
+        if (isNestedExpandable && depth < MAX_DEPTH) {
+            // Leaf summary row for the parent itself (so the user sees
+            // its description) + recurse for inner fields.
+            rows.push({
+                name: fullName,
+                type: describeType(node),
+                required: isRequired,
+                description: node.description,
+            });
+            rows.push(...schemaToFields(node, fullName, depth + 1));
+        } else {
+            rows.push({
+                name: fullName,
+                type: describeType(node),
+                required: isRequired,
+                description: node.description,
+            });
+        }
+    }
+    return rows;
+}

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

@@ -0,0 +1,60 @@
+import type { ApiEndpoint } from '../../types';
+
+/**
+ * Given a list of full endpoint paths, return the longest ``/``-aligned
+ * prefix they all share. Used to strip the redundant group prefix
+ * (``/api/v3/pet``) from sidebar labels so the meaningful tail is visible.
+ *
+ * Works on full URLs too — if every path begins with the same origin,
+ * the origin is part of the common prefix and gets stripped.
+ */
+export function longestCommonPrefix(paths: string[]): string {
+    if (paths.length === 0) return '';
+    if (paths.length === 1) return '';
+
+    const segments = paths.map((p) => p.split('/'));
+    const minLen = Math.min(...segments.map((s) => s.length));
+
+    const shared: string[] = [];
+    for (let i = 0; i < minLen; i++) {
+        const first = segments[0]![i];
+        if (segments.every((s) => s[i] === first)) {
+            shared.push(first!);
+        } else {
+            break;
+        }
+    }
+    // Don't strip everything — we always want at least a leading "/" or
+    // the method on the visible side. If the group has one endpoint,
+    // the caller guards with paths.length check already.
+    const joined = shared.join('/');
+    // Trim trailing slash so the tail is clean (``/foo`` not ``foo``).
+    return joined;
+}
+
+/**
+ * Compute the label to show in the sidebar for a given endpoint.
+ *
+ * Priority:
+ *   1. ``ep.summary`` — human-readable, from OpenAPI ``operation.summary``.
+ *   2. The tail of ``ep.path`` after stripping the group's common prefix.
+ *   3. Full ``ep.path`` if the group has a single endpoint (no prefix to strip).
+ */
+export function sidebarLabel(ep: ApiEndpoint, groupCommonPrefix: string): string {
+    if (ep.summary) return ep.summary;
+
+    if (groupCommonPrefix && ep.path.startsWith(groupCommonPrefix)) {
+        const tail = ep.path.slice(groupCommonPrefix.length) || '/';
+        return tail;
+    }
+    return relativePath(ep.path);
+}
+
+function relativePath(full: string): string {
+    try { return new URL(full).pathname; } catch { return full; }
+}
+
+/** Tooltip text: always the definitive ``METHOD relative/path``. */
+export function sidebarTooltip(ep: ApiEndpoint): string {
+    return `${ep.method} ${relativePath(ep.path)}`;
+}

package/src/tools/OpenapiViewer/components/index.ts

@@ -1,5 +1,8 @@
 /**
- * Playground Components
+ * OpenapiViewer — component exports.
+ * Only ``DocsLayout`` remains; the legacy 3-column ``PlaygroundLayout``
+ * has been removed. Shared panels live under ``./shared`` and are
+ * consumed by the docs layout + its mobile sheet.
  */
 
-export { PlaygroundLayout } from './PlaygroundLayout';
+export { DocsLayout } from './DocsLayout';