@djangocfg/ui-tools 2.1.285 → 2.1.287

package/src/tools/OpenapiViewer/components/shared/EndpointDraftSync.tsx

@@ -0,0 +1,108 @@
+'use client';
+
+import React, { useEffect, useRef } from 'react';
+
+import { usePlaygroundContext } from '../../context/PlaygroundContext';
+import { useEndpointDraft } from '../../hooks/useEndpointDraft';
+
+interface EndpointDraftSyncProps {
+    /** Active schema id (so drafts don't bleed between different APIs).
+     *  When null — drafts are disabled (hook returns empty draft, writes
+     *  are no-ops). Pass the current schema's ``id`` from useOpenApiSchema. */
+    schemaId: string | null;
+}
+
+/**
+ * Headless component: keeps ``RequestPanel`` state mirrored with a
+ * per-endpoint draft in localStorage.
+ *
+ * Flow:
+ *   1. On endpoint change ⇒ read draft ⇒ push into context state.
+ *   2. On context state change (user edits params/body) ⇒ write draft.
+ *
+ * Step 1 is gated by a ref so "just-loaded" drafts don't immediately
+ * trigger step 2. Step 2 additionally compares against a serialised
+ * snapshot of the last persisted value so a re-render without a real
+ * value change doesn't touch storage.
+ *
+ * Had an infinite-render-loop bug here earlier: the persist callbacks
+ * were driven by ``useLocalStorage`` whose setter identity changed on
+ * every internal state update, so depending on them from an effect
+ * created a cycle. Fixed by making ``useEndpointDraft``'s writers
+ * stable (ref-based), and by gating writes with value comparison below.
+ */
+export function EndpointDraftSync({ schemaId }: EndpointDraftSyncProps) {
+    const { state, setParameters, setRequestBody, setActiveSchemaId } = usePlaygroundContext();
+    const ep = state.selectedEndpoint;
+
+    // Mirror schemaId into context so other components (e.g. the Reset
+    // button in RequestPanel) can read it without receiving props from
+    // a parent they don't own.
+    useEffect(() => {
+        setActiveSchemaId(schemaId);
+    }, [schemaId, setActiveSchemaId]);
+
+    const { draft, setParameters: persistParams, setRequestBody: persistBody } =
+        useEndpointDraft(schemaId, ep);
+
+    const lastLoadedKeyRef = useRef<string | null>(null);
+    const lastPersistedParamsRef = useRef<string>('');
+    const lastPersistedBodyRef = useRef<string>('');
+    const currentKey = ep ? `${ep.method}|${ep.path}` : null;
+
+    // Step 1 — hydrate context from draft on endpoint switch.
+    //
+    // IMPORTANT: only apply fields that actually exist in the saved draft.
+    // SELECT_ENDPOINT in the reducer pre-fills ``requestBody`` with an
+    // auto-generated schema example, and ``parameters`` with ``{}``.
+    // If we blindly overwrite those with an empty draft we wipe the
+    // example before the user ever sees it. Tracked via a bug: opening
+    // POST /pet showed ``{"key":"value"}`` instead of the Pet example.
+    useEffect(() => {
+        if (!ep || !currentKey) {
+            lastLoadedKeyRef.current = null;
+            return;
+        }
+        if (lastLoadedKeyRef.current === currentKey) return;
+        lastLoadedKeyRef.current = currentKey;
+
+        const hasStoredParams =
+            draft.parameters && Object.keys(draft.parameters).length > 0;
+        const hasStoredBody = typeof draft.requestBody === 'string' && draft.requestBody !== '';
+
+        if (hasStoredParams) {
+            setParameters(draft.parameters);
+            lastPersistedParamsRef.current = JSON.stringify(draft.parameters);
+        } else {
+            // Keep whatever the reducer put there; mirror it into the
+            // "last persisted" ref so step-2 treats it as a baseline.
+            lastPersistedParamsRef.current = JSON.stringify(state.parameters);
+        }
+
+        if (hasStoredBody) {
+            setRequestBody(draft.requestBody);
+            lastPersistedBodyRef.current = draft.requestBody;
+        } else {
+            lastPersistedBodyRef.current = state.requestBody;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [currentKey]);
+
+    // Step 2 — persist user edits.
+    useEffect(() => {
+        if (!ep || lastLoadedKeyRef.current !== currentKey) return;
+        const serialised = JSON.stringify(state.parameters);
+        if (serialised === lastPersistedParamsRef.current) return;
+        lastPersistedParamsRef.current = serialised;
+        persistParams(state.parameters);
+    }, [state.parameters, ep, currentKey, persistParams]);
+
+    useEffect(() => {
+        if (!ep || lastLoadedKeyRef.current !== currentKey) return;
+        if (state.requestBody === lastPersistedBodyRef.current) return;
+        lastPersistedBodyRef.current = state.requestBody;
+        persistBody(state.requestBody);
+    }, [state.requestBody, ep, currentKey, persistBody]);
+
+    return null;
+}

package/src/tools/OpenapiViewer/components/shared/EndpointResetButton.tsx

@@ -0,0 +1,50 @@
+'use client';
+
+import { RotateCcw } from 'lucide-react';
+import React, { useCallback } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { usePlaygroundContext } from '../../context/PlaygroundContext';
+import { useEndpointDraft } from '../../hooks/useEndpointDraft';
+
+/**
+ * "Reset" ghost button for the current endpoint's draft.
+ *
+ * Wipes both the in-memory context state (parameters + body) and the
+ * persisted localStorage entry. We call reset() *after* clearing the
+ * context so the EndpointDraftSync effect that mirrors state → storage
+ * doesn't immediately re-create a now-empty draft with an empty object
+ * (benign, but uglier in storage).
+ */
+export function EndpointResetButton() {
+    const { state, setParameters, setRequestBody } = usePlaygroundContext();
+    const ep = state.selectedEndpoint;
+    const { reset } = useEndpointDraft(state.activeSchemaId, ep);
+
+    const hasDraft =
+        Object.keys(state.parameters).length > 0 || state.requestBody.length > 0;
+
+    const onClick = useCallback(() => {
+        setParameters({});
+        setRequestBody('');
+        reset();
+    }, [setParameters, setRequestBody, reset]);
+
+    if (!ep || !hasDraft) return null;
+
+    return (
+        <button
+            type="button"
+            onClick={onClick}
+            title="Reset parameters & body (keeps auth)"
+            className={cn(
+                'inline-flex items-center gap-1 text-[10px] text-muted-foreground',
+                'hover:text-foreground transition-colors',
+            )}
+        >
+            <RotateCcw className="h-2.5 w-2.5" />
+            Reset
+        </button>
+    );
+}

package/src/tools/OpenapiViewer/components/{PlaygroundLayout → shared}/RequestPanel.tsx

@@ -1,13 +1,11 @@
 'use client';
 
-import { Key, Loader2, Send, Sparkles, Terminal } from 'lucide-react';
-import React, { useMemo } from 'react';
+import { Key, Send, Sparkles, Terminal } from 'lucide-react';
+import React, { useCallback, useMemo } from 'react';
 
 import {
-    Button,
     Combobox,
     type ComboboxOption,
-    CopyButton,
     Input,
     Textarea,
 } from '@djangocfg/ui-core/components';
@@ -16,13 +14,14 @@ import { cn } from '@djangocfg/ui-core/lib';
 import PrettyCode from '../../../PrettyCode';
 import { usePlaygroundContext } from '../../context/PlaygroundContext';
 import { findApiKeyById, isValidJson, parseRequestHeaders } from '../../utils';
+import { resolveAbsolute } from '../../utils/url';
+import { BodyFormEditor } from './BodyFormEditor';
+import { EndpointResetButton } from './EndpointResetButton';
 import {
     CollapsibleSection,
     EmptyState,
-    MethodBadge,
     ScrollArea,
     SectionLabel,
-    StatusBadge,
     relativePath,
 } from './ui';
 
@@ -107,13 +106,15 @@ export function RequestPanel() {
 
     const curlCommand = useMemo(() => {
         if (!state.requestUrl) return '';
+        // Resolve to an absolute URL so the snippet is runnable from a
+        // shell. The live ``fetch`` inside the playground resolves the
+        // relative form itself via the browser; copy-pasting to curl
+        // doesn't get that treatment.
+        const absoluteUrl = resolveAbsolute(state.requestUrl);
         const apiKey = state.selectedApiKey ? findApiKeyById(apiKeys, state.selectedApiKey) : null;
         const hdrs = parseRequestHeaders(state.requestHeaders);
-        // Use ``secret`` (the raw key) for the cURL header — matches
-        // what the playground sends over the wire. Fall back to
-        // ``id`` for legacy callers still on the old ApiKey shape.
         if (apiKey) hdrs['X-API-Key'] = apiKey.secret || apiKey.id;
-        let cmd = `curl -X ${state.requestMethod} "${state.requestUrl}"`;
+        let cmd = `curl -X ${state.requestMethod} "${absoluteUrl}"`;
         Object.entries(hdrs).forEach(([k, v]) => { cmd += ` \\\n  -H "${k}: ${v}"`; });
         if (state.requestBody && state.requestMethod !== 'GET' && isJsonValid) {
             cmd += ` \\\n  -d '${state.requestBody}'`;
@@ -132,14 +133,19 @@ export function RequestPanel() {
 
     // ── Derived ───────────────────────────────────────────────────────────────
     const isSendDisabled = state.loading || !state.requestUrl || !isJsonValid;
-    const displayUrl     = state.requestUrl || ep?.path || '';
+    // Show the absolute URL in the meta row so the user sees exactly
+    // what will go over the wire — same rewrite we do for cURL.
+    const displayUrl     = resolveAbsolute(state.requestUrl || ep?.path || '');
     const hasBody        = ep?.method !== 'GET';
     const bodyType       = ep?.requestBody?.type ?? '';
     const hasPathParams  = pathParams.length > 0;
     const hasQueryParams = queryParams.length > 0;
     const hasCurl        = Boolean(curlCommand);
     const epPath         = ep ? relativePath(ep.path) : '';
-    const urlChanged     = displayUrl !== epPath;
+    // Show the URL meta row only when it differs from the endpoint's
+    // template shape — i.e. the user has substituted path params or the
+    // URL host is worth showing explicitly.
+    const urlChanged     = displayUrl !== '' && displayUrl !== epPath;
 
     // ── Early return ──────────────────────────────────────────────────────────
     if (!ep) {
@@ -149,29 +155,25 @@ export function RequestPanel() {
     // ── Render ────────────────────────────────────────────────────────────────
     return (
         <>
-            {/* Endpoint header */}
-            <div className="shrink-0 border-b px-4 py-3 bg-muted/20 space-y-1.5">
-                <div className="flex items-center gap-2">
-                    <MethodBadge method={ep.method} />
-                    <span className="font-mono text-xs text-foreground/70 truncate min-w-0 flex-1">{epPath}</span>
-                    <Button
-                        onClick={sendRequest}
-                        disabled={isSendDisabled}
-                        size="sm"
-                        className="shrink-0 gap-1.5 h-7 text-xs px-3"
-                    >
-                        {state.loading
-                            ? <><Loader2 className="h-3 w-3 animate-spin" /> Sending…</>
-                            : <><Send className="h-3 w-3" /> Send</>
-                        }
-                    </Button>
+            {/* Inline meta row — shows the effective URL when it differs
+                from the endpoint's path template (e.g. after substituting
+                path parameters), plus the Reset action. We dropped the
+                full endpoint header because the containing surface (SidePanel
+                in docs layout, column header in classic layout) already
+                shows the method + path, and duplicating the Send button
+                next to a full-width Send at the bottom read as confusing. */}
+            {(urlChanged || ep) && (
+                <div className="shrink-0 border-b px-4 py-2 bg-muted/10 flex items-center gap-2 min-h-[28px]">
+                    {urlChanged ? (
+                        <span className="font-mono text-[10px] text-muted-foreground/60 break-all leading-snug truncate min-w-0 flex-1">
+                            {displayUrl}
+                        </span>
+                    ) : (
+                        <span className="flex-1" />
+                    )}
+                    <EndpointResetButton />
                 </div>
-                {urlChanged && (
-                    <div className="font-mono text-[10px] text-muted-foreground/50 break-all leading-snug pl-0.5">
-                        {displayUrl}
-                    </div>
-                )}
-            </div>
+            )}
 
             {/* Scrollable fields */}
             <ScrollArea className="px-4 py-3 space-y-3">
@@ -181,41 +183,14 @@ export function RequestPanel() {
 
                 {/* Body */}
                 {hasBody && (
-                    <div className="space-y-1.5">
-                        <div className="flex items-center justify-between gap-2">
-                            <div className="flex items-baseline gap-2">
-                                <SectionLabel>Body</SectionLabel>
-                                {bodyType && (
-                                    <span className="text-[10px] text-muted-foreground/40 font-mono">{bodyType}</span>
-                                )}
-                            </div>
-                            {isJsonValid && state.requestBody && (
-                                <button
-                                    type="button"
-                                    onClick={() => {
-                                        try {
-                                            setRequestBody(JSON.stringify(JSON.parse(state.requestBody), null, 2));
-                                        } catch {}
-                                    }}
-                                    className="inline-flex items-center gap-1 text-[10px] text-muted-foreground hover:text-foreground transition-colors"
-                                >
-                                    <Sparkles className="h-2.5 w-2.5" />
-                                    Format
-                                </button>
-                            )}
-                        </div>
-                        <Textarea
-                            placeholder={'{\n  "key": "value"\n}'}
-                            value={state.requestBody}
-                            onChange={(e) => setRequestBody(e.target.value)}
-                            className={cn(
-                                'font-mono text-[11px] min-h-[90px] resize-y',
-                                !isJsonValid && 'border-destructive focus-visible:ring-destructive/30',
-                            )}
-                            rows={4}
-                        />
-                        {!isJsonValid && <p className="text-[10px] text-destructive">Invalid JSON</p>}
-                    </div>
+                    <BodySection
+                        schema={ep.requestBody?.schema}
+                        bodyType={bodyType}
+                        bodyDescription={ep.requestBody?.description}
+                        value={state.requestBody}
+                        onChange={setRequestBody}
+                        isJsonValid={isJsonValid}
+                    />
                 )}
 
                 {/* Auth & Headers — collapsed by default */}
@@ -273,7 +248,8 @@ export function RequestPanel() {
                     </div>
                 </CollapsibleSection>
 
-                {/* cURL — collapsed by default */}
+                {/* cURL — collapsed by default. PrettyCode has its own
+                    hover-toolbar with Copy, so no duplicate action here. */}
                 {hasCurl && (
                     <CollapsibleSection
                         label={
@@ -282,30 +258,141 @@ export function RequestPanel() {
                                 cURL
                             </span>
                         }
-                        action={
-                            <CopyButton value={curlCommand} variant="ghost" size="sm" className="h-5 px-2 text-[10px] text-muted-foreground">
-                                Copy
-                            </CopyButton>
-                        }
                     >
-                        <div className="rounded-md overflow-hidden mt-2">
-                            <PrettyCode data={curlCommand} language="bash" isCompact />
+                        <div className="mt-2">
+                            <PrettyCode
+                                data={curlCommand}
+                                language="bash"
+                                isCompact
+                                maxLines={50}
+                            />
                         </div>
                     </CollapsibleSection>
                 )}
 
-                <div className="h-1" />
+                {/* Bottom breathing room — the Send footer lives outside
+                    this component (in SlideInPlayground / TryItSheet),
+                    so we just leave a little space so the last section
+                    doesn't crash against the container edge. */}
+                <div className="h-4" />
             </ScrollArea>
+        </>
+    );
+}
 
-            {/* Send footer */}
-            <div className="shrink-0 border-t px-4 py-3 bg-background/95 backdrop-blur-sm">
-                <Button onClick={sendRequest} disabled={isSendDisabled} size="sm" className="w-full gap-2 h-9">
-                    {state.loading
-                        ? <><Loader2 className="h-3.5 w-3.5 animate-spin" /> Sending…</>
-                        : <><Send className="h-3.5 w-3.5" /> Send Request</>
-                    }
-                </Button>
+// ─── Body section ─────────────────────────────────────────────────────────────
+
+interface BodySectionProps {
+    schema: Record<string, unknown> | undefined;
+    bodyType: string;
+    bodyDescription?: string;
+    /** JSON-serialised body kept in context. Form edits are re-serialised
+     *  before being written back so one source of truth survives across
+     *  the two view modes. */
+    value: string;
+    onChange: (raw: string) => void;
+    isJsonValid: boolean;
+}
+
+type BodyViewMode = 'form' | 'json';
+
+function BodySection({ schema, bodyType, bodyDescription, value, onChange, isJsonValid }: BodySectionProps) {
+    // Default to form view when we have a schema to drive it. Fall back
+    // to raw JSON for schemaless endpoints (or binary bodies, etc.).
+    const hasSchema = !!schema;
+    const [mode, setMode] = React.useState<BodyViewMode>(hasSchema ? 'form' : 'json');
+
+    // Parse the context's JSON string once per value change so the form
+    // sees a structured object. Invalid JSON is tolerated — the form
+    // simply shows empty fields until the user fixes it.
+    const parsed = React.useMemo(() => {
+        if (!value) return null;
+        try { return JSON.parse(value); } catch { return null; }
+    }, [value]);
+
+    const handleFormChange = useCallback(
+        (next: unknown) => {
+            onChange(JSON.stringify(next, null, 2));
+        },
+        [onChange],
+    );
+
+    return (
+        <div className="space-y-2">
+            <div className="flex items-center justify-between gap-2 flex-wrap">
+                <div className="flex items-baseline gap-2 min-w-0">
+                    <SectionLabel>Body</SectionLabel>
+                    {bodyType && (
+                        <span className="text-[10px] text-muted-foreground/40 font-mono">{bodyType}</span>
+                    )}
+                    {bodyDescription && (
+                        <span className="text-[10px] text-muted-foreground/60 truncate">{bodyDescription}</span>
+                    )}
+                </div>
+                {hasSchema && (
+                    <div className="inline-flex rounded-md border overflow-hidden text-[10px]">
+                        <ModeButton active={mode === 'form'} onClick={() => setMode('form')}>Form</ModeButton>
+                        <ModeButton active={mode === 'json'} onClick={() => setMode('json')}>JSON</ModeButton>
+                    </div>
+                )}
+                {mode === 'json' && isJsonValid && value && (
+                    <button
+                        type="button"
+                        onClick={() => {
+                            try { onChange(JSON.stringify(JSON.parse(value), null, 2)); } catch { /* noop */ }
+                        }}
+                        className="inline-flex items-center gap-1 text-[10px] text-muted-foreground hover:text-foreground transition-colors"
+                    >
+                        <Sparkles className="h-2.5 w-2.5" />
+                        Format
+                    </button>
+                )}
             </div>
-        </>
+
+            {mode === 'form' && hasSchema ? (
+                <BodyFormEditor
+                    schema={schema as Record<string, unknown>}
+                    value={parsed}
+                    onChange={handleFormChange}
+                />
+            ) : (
+                <>
+                    <Textarea
+                        placeholder={'{\n  "key": "value"\n}'}
+                        value={value}
+                        onChange={(e) => onChange(e.target.value)}
+                        className={cn(
+                            'font-mono text-[11px] min-h-[90px] resize-y',
+                            !isJsonValid && 'border-destructive focus-visible:ring-destructive/30',
+                        )}
+                        rows={4}
+                    />
+                    {!isJsonValid && <p className="text-[10px] text-destructive">Invalid JSON</p>}
+                </>
+            )}
+        </div>
+    );
+}
+
+function ModeButton({
+    active, onClick, children,
+}: {
+    active: boolean;
+    onClick: () => void;
+    children: React.ReactNode;
+}) {
+    return (
+        <button
+            type="button"
+            onClick={onClick}
+            className={cn(
+                'px-2 py-0.5 font-medium transition-colors',
+                active
+                    ? 'bg-primary/10 text-foreground'
+                    : 'text-muted-foreground hover:text-foreground',
+            )}
+        >
+            {children}
+        </button>
     );
 }

package/src/tools/OpenapiViewer/components/shared/SendButton.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import { AlertCircle, Loader2, Send } from 'lucide-react';
+import React, { useMemo } from 'react';
+
+import { Button } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { usePlaygroundContext } from '../../context/PlaygroundContext';
+import { isValidJson } from '../../utils';
+import { UrlBuilder } from '../../utils/url';
+
+interface SendButtonProps {
+    className?: string;
+}
+
+/**
+ * Standalone Send button that reads from and acts on the playground
+ * context. Disabled + explainer-banner when required inputs are missing.
+ *
+ * Validation rules (in order — first failure wins the banner text):
+ *   1. Required path/query parameters must be non-empty.
+ *   2. Path template must be fully substituted (no leftover ``{name}``).
+ *   3. Request body, when present, must be valid JSON.
+ *
+ * We validate on the client so the user isn't punished with a 404 from
+ * the server for a trivially detectable mistake (e.g. empty ``{petId}``).
+ */
+export function SendButton({ className }: SendButtonProps) {
+    const { state, sendRequest } = usePlaygroundContext();
+
+    const ep = state.selectedEndpoint;
+
+    // Single source of truth for URL-level validation lives in UrlBuilder.
+    // Recomputing every render is cheap (pure string work).
+    const builder = useMemo(
+        () => (ep ? new UrlBuilder(ep, state.parameters) : null),
+        [ep, state.parameters],
+    );
+    const missingRequired = builder?.missingRequired() ?? [];
+    const unsubstituted = builder?.unfilledPlaceholders() ?? [];
+
+    const isJsonValid = state.requestBody ? isValidJson(state.requestBody) : true;
+
+    const blockers: string[] = [];
+    if (missingRequired.length > 0) {
+        blockers.push(
+            `Fill required parameter${missingRequired.length > 1 ? 's' : ''}: ${missingRequired.join(', ')}`,
+        );
+    } else if (unsubstituted.length > 0) {
+        blockers.push(`URL still has unfilled placeholder${unsubstituted.length > 1 ? 's' : ''}: ${unsubstituted.map((n) => `{${n}}`).join(', ')}`);
+    }
+    if (!isJsonValid) blockers.push('Request body is not valid JSON');
+
+    const disabled =
+        state.loading ||
+        !state.requestUrl ||
+        blockers.length > 0;
+
+    const tooltip = blockers.length > 0 ? blockers.join('\n') : undefined;
+
+    return (
+        <div className={cn('space-y-2', className)}>
+            {blockers.length > 0 && (
+                <div className="flex items-start gap-2 rounded-md border border-amber-500/25 bg-amber-500/[0.06] px-3 py-2 text-[11px] text-amber-600 dark:text-amber-400">
+                    <AlertCircle className="h-3.5 w-3.5 shrink-0 mt-px" />
+                    <span className="leading-snug">{blockers[0]}</span>
+                </div>
+            )}
+            <Button
+                onClick={sendRequest}
+                disabled={disabled}
+                size="sm"
+                title={tooltip}
+                className="w-full gap-2 h-9"
+            >
+                {state.loading ? (
+                    <>
+                        <Loader2 className="h-3.5 w-3.5 animate-spin" />
+                        Sending…
+                    </>
+                ) : (
+                    <>
+                        <Send className="h-3.5 w-3.5" />
+                        Send Request
+                    </>
+                )}
+            </Button>
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/{PlaygroundLayout → shared}/ui.tsx

@@ -1,7 +1,8 @@
 'use client';
 
 /**
- * Shared primitive UI components used across all PlaygroundLayout panels.
+ * Shared primitive UI components used by the playground panels
+ * (Request, Response) in both the slide-in and mobile-sheet surfaces.
  * Keep this file free of any business logic or context reads.
  */
 
@@ -33,9 +34,9 @@ export function getStatusStyle(status: number): string {
     return 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border-emerald-500/25';
 }
 
-export function relativePath(full: string): string {
-    try { return new URL(full).pathname; } catch { return full; }
-}
+// ``relativePath`` lives in utils/url.ts now — re-exported here so every
+// component that used to import it from ``./ui`` keeps working.
+export { relativePath } from '../../utils/url';
 
 // ─── Atoms ────────────────────────────────────────────────────────────────────