@djangocfg/ui-tools 2.1.287 → 2.1.290

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

@@ -1,14 +1,17 @@
 'use client';
 
-import React, { useCallback, useRef, useState } from 'react';
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+import { keyBy } from 'lodash-es';
 
 import { Skeleton, TooltipProvider } from '@djangocfg/ui-core/components';
 import { useMediaQuery } from '@djangocfg/ui-core/hooks';
 
 import useOpenApiSchema from '../../hooks/useOpenApiSchema';
+import { useDocsUrlSync, type ParsedHash } from '../../hooks/useDocsUrlSync';
 import { usePlaygroundContext } from '../../context/PlaygroundContext';
 import type { ApiEndpoint } from '../../types';
 import { EndpointDraftSync } from '../shared/EndpointDraftSync';
+import { slugifySchemaId } from './anchor';
 import { DocsSidebar } from './Sidebar';
 import { DocsView, type DocsViewHandle } from './DocsView';
 import { SlideInPlayground } from './SlideInPlayground';
@@ -24,6 +27,12 @@ export const DocsLayout: React.FC = () => {
     // mobile-style ``TryItSheet`` on those viewports.
     const isDesktop = useMediaQuery('(min-width: 1024px)');
     const isMobile = !isDesktop;
+
+    const grouping = config.schemaGrouping ?? 'selector';
+    const preloadAll = grouping === 'sections';
+    const urlSyncEnabled =
+        typeof config.urlSync === 'boolean' ? config.urlSync : Boolean(config.urlSync?.enabled);
+
     const {
         endpoints,
         schemaInfo,
@@ -34,13 +43,16 @@ export const DocsLayout: React.FC = () => {
         schemas,
         currentSchema,
         setCurrentSchema,
+        schemasData,
     } = useOpenApiSchema({
         schemas: config.schemas,
         defaultSchemaId: config.defaultSchemaId,
         baseUrl: config.baseUrl,
+        preloadAll,
     });
 
     const [activeAnchor, setActiveAnchor] = useState<string | null>(null);
+    const [activeSchemaId, setActiveSchemaId] = useState<string | null>(null);
     const [sheetOpen, setSheetOpen] = useState(false);
     const docsRef = useRef<DocsViewHandle | null>(null);
 
@@ -49,6 +61,17 @@ export const DocsLayout: React.FC = () => {
     // semantic — "which endpoint is loaded into the playground".
     const slideOpen = !isMobile && state.selectedEndpoint !== null;
 
+    // Per-schema endpoint map for the sections sidebar. ``keyBy`` makes the
+    // lookup O(1) at render time instead of scanning schemasData in each
+    // CategoryBlock — a win for 10+ schemas.
+    const endpointsBySchema = useMemo<Record<string, ApiEndpoint[]>>(() => {
+        if (grouping !== 'sections') return {};
+        const byId = keyBy(schemasData, (e) => e.source.id);
+        const out: Record<string, ApiEndpoint[]> = {};
+        for (const src of schemas) out[src.id] = byId[src.id]?.endpoints ?? [];
+        return out;
+    }, [grouping, schemasData, schemas]);
+
     const handleTry = useCallback(
         (ep: ApiEndpoint) => {
             setSelectedEndpoint(ep);
@@ -61,18 +84,83 @@ export const DocsLayout: React.FC = () => {
         setSelectedEndpoint(null);
     }, [setSelectedEndpoint]);
 
-    const handleNavigate = useCallback((anchor: string) => {
-        docsRef.current?.scrollToAnchor(anchor);
+    const handleNavigate = useCallback(
+        (anchor: string, schemaId?: string | null) => {
+            // In selector mode a schema switch may be required before the
+            // anchor exists in the DOM — defer the scroll until the next
+            // paint so ``useOpenApiSchema`` has a chance to swap endpoints.
+            if (schemaId && schemaId !== currentSchema?.id && grouping === 'selector') {
+                setCurrentSchema(schemaId);
+                requestAnimationFrame(() => {
+                    docsRef.current?.scrollToAnchor(anchor);
+                });
+                return;
+            }
+            docsRef.current?.scrollToAnchor(anchor);
+        },
+        [currentSchema?.id, grouping, setCurrentSchema],
+    );
+
+    const handleActiveChange = useCallback((anchor: string | null, schemaId: string | null) => {
+        setActiveAnchor(anchor);
+        setActiveSchemaId(schemaId);
     }, []);
-    // Esc handling lives inside SidePanel itself — no duplicate listener.
+
+    // URL sync: read hash on mount / popstate → apply; write hash when
+    // scrollspy updates. Only the *effective* active schema goes into the
+    // hash — in ``selector`` mode it's the combobox value, in ``sections``
+    // mode it's whichever schema the scrollspy is currently inside.
+    const effectiveSchemaId = grouping === 'sections' ? activeSchemaId : currentSchema?.id ?? null;
+
+    const handleHashTarget = useCallback(
+        (target: ParsedHash) => {
+            if (!target.schemaId && !target.anchor) return;
+
+            // Schema-id segment may be either the raw id or a slug — match
+            // both so copy-pasted URLs survive id changes that don't affect
+            // the slug. First match wins.
+            const matched = target.schemaId
+                ? schemas.find((s) => s.id === target.schemaId || slugifySchemaId(s.id) === target.schemaId)
+                : null;
+
+            const needsSchemaSwitch =
+                matched && grouping === 'selector' && matched.id !== currentSchema?.id;
+
+            if (needsSchemaSwitch) {
+                setCurrentSchema(matched.id);
+            }
+
+            if (target.anchor) {
+                const anchor = target.anchor;
+                // Wait one frame when a switch happened so the new DOM exists.
+                if (needsSchemaSwitch) {
+                    requestAnimationFrame(() => {
+                        docsRef.current?.scrollToAnchor(anchor);
+                    });
+                } else {
+                    docsRef.current?.scrollToAnchor(anchor);
+                }
+            }
+        },
+        [schemas, grouping, currentSchema?.id, setCurrentSchema],
+    );
+
+    useDocsUrlSync({
+        enabled: urlSyncEnabled,
+        currentSchemaId: effectiveSchemaId,
+        activeAnchor,
+        onHashTarget: handleHashTarget,
+    });
+
+    // ─── Loading / error branches ─────────────────────────────────────────
 
     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">
+            <div className="grid grid-cols-[260px_1fr] items-start">
+                <div
+                    className="sticky top-[var(--navbar-height,64px)] border-r p-3 space-y-1.5 overflow-y-auto"
+                    style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
+                >
                     {Array.from({ length: 12 }).map((_, i) => (
                         <Skeleton key={i} className="h-8 w-full rounded" />
                     ))}
@@ -105,58 +193,88 @@ export const DocsLayout: React.FC = () => {
         );
     }
 
-    // Mobile/tablet: sidebar + docs only, playground opens in sheet.
+    // ─── Mobile: 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))' }}
-            >
+            <div className="flex flex-col">
                 <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}
-                />
+                {grouping === 'sections' ? (
+                    <DocsView
+                        ref={docsRef}
+                        grouping="sections"
+                        schemasData={schemasData}
+                        selectedVersion={state.selectedVersion}
+                        loadedEndpoint={state.selectedEndpoint}
+                        onTryEndpoint={handleTry}
+                        onActiveChange={handleActiveChange}
+                    />
+                ) : (
+                    <DocsView
+                        ref={docsRef}
+                        info={schemaInfo}
+                        rawSchema={rawSchema}
+                        resolvedBaseUrl={resolvedBaseUrl}
+                        endpoints={endpoints}
+                        selectedVersion={state.selectedVersion}
+                        loadedEndpoint={state.selectedEndpoint}
+                        onTryEndpoint={handleTry}
+                        onActiveChange={handleActiveChange}
+                    />
+                )}
                 <TryItSheet open={sheetOpen} onOpenChange={setSheetOpen} />
             </div>
         );
     }
 
+    // ─── Desktop ──────────────────────────────────────────────────────────
+
     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))' }}
-            >
+            <div className="grid grid-cols-[260px_minmax(0,1fr)] items-start">
                 <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}
-                />
+                <div
+                    className="sticky top-[var(--navbar-height,64px)]"
+                    style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
+                >
+                    <DocsSidebar
+                        info={schemaInfo}
+                        endpoints={endpoints}
+                        schemas={schemas}
+                        currentSchemaId={currentSchema?.id ?? null}
+                        onSchemaChange={setCurrentSchema}
+                        activeEndpointId={activeAnchor}
+                        selectedVersion={state.selectedVersion}
+                        onNavigate={handleNavigate}
+                        grouping={grouping}
+                        endpointsBySchema={endpointsBySchema}
+                        rawSchema={rawSchema}
+                        resolvedBaseUrl={resolvedBaseUrl}
+                    />
+                </div>
+                {grouping === 'sections' ? (
+                    <DocsView
+                        ref={docsRef}
+                        grouping="sections"
+                        schemasData={schemasData}
+                        selectedVersion={state.selectedVersion}
+                        loadedEndpoint={state.selectedEndpoint}
+                        onTryEndpoint={handleTry}
+                        onActiveChange={handleActiveChange}
+                    />
+                ) : (
+                    <DocsView
+                        ref={docsRef}
+                        info={schemaInfo}
+                        rawSchema={rawSchema}
+                        resolvedBaseUrl={resolvedBaseUrl}
+                        endpoints={endpoints}
+                        selectedVersion={state.selectedVersion}
+                        loadedEndpoint={state.selectedEndpoint}
+                        onTryEndpoint={handleTry}
+                        onActiveChange={handleActiveChange}
+                    />
+                )}
                 {/* SidePanel renders into <body> via portal, so it floats
                     above the whole layout (sidebar + navbar included). */}
                 <SlideInPlayground open={slideOpen} onClose={handleCloseSlide} />

package/src/tools/OpenapiViewer/components/shared/ResponsePanel/PrettyView.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import JsonTree from '../../../../JsonTree';
+import PrettyCode from '../../../../PrettyCode';
+import type { DetectedContent } from './types';
+
+// JsonTree config — same shape as the interactive docs example view
+// but with ``showActionButtons: false`` because the copy button in the
+// StatusBar already covers that flow.
+const JSON_TREE_CONFIG = {
+    maxAutoExpandDepth: 2,
+    maxAutoExpandArrayItems: 10,
+    maxAutoExpandObjectKeys: 5,
+    maxStringLength: 200,
+    collectionLimit: 50,
+    showCollectionInfo: true,
+    showExpandControls: true,
+    showActionButtons: false,
+    preserveKeyOrder: true,
+    className: 'border-0 rounded-none',
+} as const;
+
+interface PrettyViewProps {
+    /** Parsed JSON tree when the body was JSON. */
+    treeData: unknown;
+    /** Pre-stringified body — used by the code-highlight branch for
+     *  non-JSON payloads. */
+    rawText: string;
+    detected: DetectedContent;
+}
+
+/** "Pretty" view — rich-rendering branch. JSON renders as ``JsonTree``;
+ *  anything else goes through ``PrettyCode`` in ``plain`` variant so it
+ *  flows naturally inside the panel's ``ScrollArea`` — no internal
+ *  scroll, no floating toolbar fighting the surrounding layout. */
+export function PrettyView({ treeData, rawText, detected }: PrettyViewProps) {
+    if (detected.kind === 'json' && treeData != null) {
+        return <JsonTree title="Response Body" data={treeData} config={JSON_TREE_CONFIG} />;
+    }
+    if (!rawText) {
+        return (
+            <div className="py-10 text-center text-xs text-muted-foreground">
+                Empty response body
+            </div>
+        );
+    }
+    return (
+        <PrettyCode
+            data={rawText}
+            language={detected.prism}
+            variant="plain"
+            isCompact
+        />
+    );
+}

package/src/tools/OpenapiViewer/components/shared/ResponsePanel/PreviewView.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import { Info, ShieldCheck } from 'lucide-react';
+import { useMemo } from 'react';
+
+interface PreviewViewProps {
+    html: string;
+}
+
+/** Heuristic: does ``html`` look like a JS-only single-page app shell?
+ *
+ *  SPAs (Vite, CRA, Next-app dev index) ship a near-empty ``<body>``
+ *  with a mount div + a ``<script type="module">`` that hydrates the
+ *  page at runtime. Previewing those in a ``sandbox=""`` iframe is
+ *  pointless because scripts can't run — the reader sees a blank
+ *  page and assumes preview is broken.
+ *
+ *  We detect this by extracting body content, stripping scripts, and
+ *  checking what's left. If it's basically just a mount div, we show
+ *  an explanatory empty-state instead of an empty iframe. */
+function looksLikeSpaShell(html: string): boolean {
+    const bodyMatch = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+    const bodyContent = (bodyMatch?.[1] ?? html)
+        // Strip all script tags with their contents — runtime-only code
+        // doesn't count as visible markup for this check.
+        .replace(/<script[\s\S]*?<\/script>/gi, '')
+        // Strip comments.
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .trim();
+
+    if (bodyContent.length === 0) return true;
+
+    // A single empty container (``<div id="root"></div>`` and friends)
+    // is the classic SPA mount point. Anything else — including static
+    // server-rendered pages with real content — won't match.
+    const singleEmptyContainer = /^<(div|main|section)[^>]*>\s*<\/\1>$/i;
+    if (singleEmptyContainer.test(bodyContent)) return true;
+
+    return false;
+}
+
+/** Render an HTML response inside a sandboxed iframe so the reader can
+ *  see what the server's error page or template actually looks like.
+ *
+ *  Security model — ``sandbox`` is intentionally **empty**:
+ *    - no ``allow-scripts`` → JavaScript in the response cannot run
+ *    - no ``allow-same-origin`` → the page can't read parent cookies
+ *    - no ``allow-forms`` / ``allow-popups`` → can't phish the user
+ *
+ *  We feed the HTML via ``srcDoc`` (not ``src``) so we never issue a
+ *  network request to render it — the string is already local. */
+export function PreviewView({ html }: PreviewViewProps) {
+    const isSpaShell = useMemo(() => looksLikeSpaShell(html), [html]);
+
+    if (!html) {
+        return (
+            <div className="py-10 text-center text-xs text-muted-foreground">
+                Empty response body
+            </div>
+        );
+    }
+
+    if (isSpaShell) {
+        return (
+            <div className="flex flex-col items-center justify-center py-16 px-6 text-center gap-3 min-h-[400px]">
+                <div className="inline-flex items-center justify-center h-10 w-10 rounded-full bg-muted">
+                    <Info className="h-5 w-5 text-muted-foreground" />
+                </div>
+                <div className="max-w-sm space-y-1.5">
+                    <p className="text-sm font-medium text-foreground">
+                        Looks like a single-page app shell
+                    </p>
+                    <p className="text-xs text-muted-foreground leading-relaxed">
+                        This page renders its content with JavaScript at runtime.
+                        Scripts are disabled in the sandbox, so Preview would show
+                        a blank page. Switch to <strong>Pretty</strong> or{' '}
+                        <strong>Raw</strong> to inspect the HTML source.
+                    </p>
+                </div>
+            </div>
+        );
+    }
+
+    return (
+        <div className="flex flex-col h-full min-h-[400px]">
+            <div className="shrink-0 flex items-center gap-1.5 px-3 py-1.5 bg-muted/30 border-b text-[10px] text-muted-foreground/70">
+                <ShieldCheck className="h-3 w-3" />
+                Sandboxed preview — scripts, forms and popups are disabled
+            </div>
+            {/*
+              * Checker-pattern background so "black on black" responses
+              * still show a clear iframe bounding box, and so readers
+              * can tell the iframe has loaded even if the page itself
+              * is empty / fully transparent.
+              */}
+            <div
+                className="flex-1 min-h-[360px] p-2"
+                style={{
+                    backgroundColor: '#fff',
+                    backgroundImage:
+                        'linear-gradient(45deg, #f3f4f6 25%, transparent 25%), linear-gradient(-45deg, #f3f4f6 25%, transparent 25%), linear-gradient(45deg, transparent 75%, #f3f4f6 75%), linear-gradient(-45deg, transparent 75%, #f3f4f6 75%)',
+                    backgroundSize: '16px 16px',
+                    backgroundPosition: '0 0, 0 8px, 8px -8px, -8px 0px',
+                }}
+            >
+                <iframe
+                    title="Response preview"
+                    srcDoc={html}
+                    sandbox=""
+                    className="w-full h-full min-h-[360px] bg-white border-0 rounded shadow-sm"
+                />
+            </div>
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/shared/ResponsePanel/RawView.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+interface RawViewProps {
+    rawText: string;
+}
+
+/** Verbatim response body. No parsing, no highlighting — readers
+ *  occasionally need to inspect trailing whitespace, escape
+ *  sequences, or a payload that accidentally claims one content type
+ *  and ships another, and the Pretty view hides some of that. */
+export function RawView({ rawText }: RawViewProps) {
+    if (!rawText) {
+        return (
+            <div className="py-10 text-center text-xs text-muted-foreground">
+                Empty response body
+            </div>
+        );
+    }
+    return (
+        <pre className="p-4 text-[11px] font-mono text-foreground/70 whitespace-pre-wrap break-all leading-relaxed">
+            {rawText}
+        </pre>
+    );
+}

package/src/tools/OpenapiViewer/components/shared/ResponsePanel/StatusBar.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+import { CopyButton } from '@djangocfg/ui-core/components';
+
+import type { ApiResponse } from '../../../types';
+import { StatusBadge } from '../ui';
+
+interface StatusBarProps {
+    response: ApiResponse;
+    rawText: string;
+    /** Content-Type label shown inline next to size/duration. ``null``
+     *  when the server didn't send one — we hide the slot instead of
+     *  showing an empty dash. */
+    contentType: string | null;
+}
+
+/** Top strip of the response panel: status badge, statusText, size,
+ *  duration, content-type, copy button. Compact — one line, tabular
+ *  numerals so 1.4 KB and 107ms don't shift as values update. */
+export function StatusBar({ response, rawText, contentType }: StatusBarProps) {
+    const sizeKb = rawText ? `${(rawText.length / 1024).toFixed(1)} KB` : '';
+    const duration = response.duration != null ? `${response.duration}ms` : '';
+    const hasStatus = response.status != null;
+    const hasCopy = Boolean(rawText);
+
+    return (
+        <div className="shrink-0 border-b px-4 py-2 flex items-center justify-between gap-3 bg-muted/20">
+            <div className="flex items-center gap-2 min-w-0">
+                {hasStatus && <StatusBadge status={response.status!} />}
+                {response.statusText && (
+                    <span className="text-xs text-muted-foreground truncate">
+                        {response.statusText}
+                    </span>
+                )}
+                {sizeKb && (
+                    <span className="text-[10px] text-muted-foreground/50 tabular-nums shrink-0">
+                        {sizeKb}
+                    </span>
+                )}
+                {duration && (
+                    <span className="text-[10px] text-muted-foreground/50 tabular-nums shrink-0">
+                        {duration}
+                    </span>
+                )}
+                {contentType && (
+                    <span className="text-[10px] text-muted-foreground/50 font-mono truncate">
+                        {contentType}
+                    </span>
+                )}
+            </div>
+            {hasCopy && (
+                <CopyButton
+                    value={rawText}
+                    variant="ghost"
+                    size="sm"
+                    className="h-6 px-2 text-[10px] text-muted-foreground shrink-0"
+                >
+                    Copy
+                </CopyButton>
+            )}
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/shared/ResponsePanel/ViewTabs.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import type { ViewMode } from './types';
+
+interface ViewTabsProps {
+    active: ViewMode;
+    onChange: (mode: ViewMode) => void;
+    /** When false the Preview tab is hidden — only HTML responses get
+     *  a useful preview, everything else renders the same as Pretty. */
+    showPreview: boolean;
+}
+
+const LABELS: Record<ViewMode, string> = {
+    pretty: 'Pretty',
+    raw: 'Raw',
+    preview: 'Preview',
+};
+
+/** Tab strip for switching between Pretty / Raw / Preview. Matches the
+ *  visual weight of the ``LanguageTabs`` in CodeSamples so the page
+ *  reads as one coherent toolbar system. */
+export function ViewTabs({ active, onChange, showPreview }: ViewTabsProps) {
+    const tabs: ViewMode[] = showPreview ? ['pretty', 'raw', 'preview'] : ['pretty', 'raw'];
+    return (
+        <div className="shrink-0 border-b px-3 py-1.5 flex items-center gap-1">
+            {tabs.map((t) => (
+                <button
+                    key={t}
+                    type="button"
+                    onClick={() => onChange(t)}
+                    className={cn(
+                        'h-6 px-2.5 rounded text-[11px] font-medium transition-colors',
+                        active === t
+                            ? 'bg-muted text-foreground'
+                            : 'text-muted-foreground/70 hover:text-foreground hover:bg-muted/50',
+                    )}
+                >
+                    {LABELS[t]}
+                </button>
+            ))}
+        </div>
+    );
+}