@djangocfg/ui-tools 2.1.287 → 2.1.290

package/src/tools/OpenapiViewer/components/shared/ResponsePanel/detectContent.ts

@@ -0,0 +1,97 @@
+import type { ContentKind, DetectedContent } from './types';
+
+/** Strip Content-Type parameters (``; charset=utf-8`` etc.) and lower-case. */
+function normaliseContentType(raw: string | null): string | null {
+    if (!raw) return null;
+    const semi = raw.indexOf(';');
+    return (semi === -1 ? raw : raw.slice(0, semi)).trim().toLowerCase();
+}
+
+/** Pull Content-Type out of the headers bag. We accept both plain
+ *  objects (``{ "content-type": "..." }``) and ``Headers``-like shapes
+ *  with a ``.get`` method. The context type is ``any`` so we can't be
+ *  stricter without plumbing a proper type through the response code
+ *  path. */
+function readContentType(headers: unknown): string | null {
+    if (!headers) return null;
+    // Headers instance — use ``.get`` (case-insensitive).
+    if (typeof (headers as Headers).get === 'function') {
+        return (headers as Headers).get('content-type');
+    }
+    // Plain object — look up with case-insensitive key match so both
+    // ``Content-Type`` and ``content-type`` work.
+    if (typeof headers === 'object') {
+        for (const [k, v] of Object.entries(headers as Record<string, unknown>)) {
+            if (k.toLowerCase() === 'content-type') {
+                return typeof v === 'string' ? v : null;
+            }
+        }
+    }
+    return null;
+}
+
+/** Map a normalised MIME type to our short ``ContentKind``. Unknown
+ *  types fall back to ``text`` so PrettyCode still shows something
+ *  sensible (plain text is a valid Prism language). */
+function kindFromContentType(mime: string | null): ContentKind {
+    if (!mime) return 'text';
+    if (mime === 'application/json' || mime.endsWith('+json')) return 'json';
+    if (mime === 'text/html' || mime === 'application/xhtml+xml') return 'html';
+    if (
+        mime === 'application/xml' ||
+        mime === 'text/xml' ||
+        mime.endsWith('+xml')
+    ) return 'xml';
+    if (mime === 'text/css') return 'css';
+    if (
+        mime === 'application/javascript' ||
+        mime === 'text/javascript' ||
+        mime === 'application/x-javascript'
+    ) return 'javascript';
+    return 'text';
+}
+
+/** Heuristic fallback when ``Content-Type`` is missing or opaque.
+ *  Returns ``null`` when nothing firm can be inferred; the caller
+ *  then defaults to ``text``. */
+function kindFromBody(body: string): ContentKind | null {
+    const trimmed = body.trimStart();
+    if (!trimmed) return null;
+    if (trimmed.startsWith('<!DOCTYPE') || /^<html[\s>]/i.test(trimmed)) return 'html';
+    if (trimmed.startsWith('<?xml')) return 'xml';
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        // Cheap validity check — full parse happens in ResponsePanel.
+        try { JSON.parse(trimmed); return 'json'; } catch { /* fall through */ }
+    }
+    return null;
+}
+
+const PRISM_BY_KIND: Record<ContentKind, DetectedContent['prism']> = {
+    json: 'json',
+    // ``markup`` is Prism's HTML/XML grammar — there isn't a separate
+    // ``html`` language. XML piggy-backs on the same tokeniser.
+    html: 'markup',
+    xml: 'markup',
+    css: 'css',
+    javascript: 'javascript',
+    text: 'markup',
+};
+
+/** Detect content kind from headers, falling back to body sniffing
+ *  when the header is missing. Pure function — safe to call inside
+ *  ``useMemo`` deps on the raw body and headers. */
+export function detectContent(headers: unknown, rawBody: string): DetectedContent {
+    const contentType = normaliseContentType(readContentType(headers));
+    const headerKind = kindFromContentType(contentType);
+
+    // If headers say it's text/plain but the body looks like HTML or
+    // JSON, trust the body — a lot of framework 500 pages claim
+    // text/html but some setups default to text/plain for errors.
+    const kind = headerKind === 'text' ? (kindFromBody(rawBody) ?? 'text') : headerKind;
+
+    return {
+        kind,
+        prism: PRISM_BY_KIND[kind],
+        contentType,
+    };
+}

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

@@ -0,0 +1,93 @@
+'use client';
+
+import { Loader2, Send, Terminal, WifiOff } from 'lucide-react';
+import { useEffect, useState } from 'react';
+
+import { usePlaygroundContext } from '../../../context/PlaygroundContext';
+import { EmptyState, ScrollArea } from '../ui';
+import { PreviewView } from './PreviewView';
+import { PrettyView } from './PrettyView';
+import { RawView } from './RawView';
+import { StatusBar } from './StatusBar';
+import type { ViewMode } from './types';
+import { useResponseView } from './useResponseView';
+import { ViewTabs } from './ViewTabs';
+
+/** Response panel used by both the sticky ``SlideInPlayground`` and the
+ *  modal ``TryItSheet``. Responsibilities:
+ *    - Empty / loading / network-error gates
+ *    - Three view modes (Pretty / Raw / Preview) with a tab bar
+ *    - Auto-pick the best default view per response type (JSON → Pretty,
+ *      HTML → Preview, everything else → Pretty as the widest-purpose)
+ *
+ *  View mode is local component state rather than context state — it
+ *  should reset when the selected endpoint changes and not leak between
+ *  endpoints. */
+export function ResponsePanel() {
+    const { state } = usePlaygroundContext();
+    const { response, loading, selectedEndpoint } = state;
+
+    const { treeData, rawText, detected } = useResponseView(response?.data, response?.headers);
+    const showPreview = detected.kind === 'html';
+
+    // Default view heuristic: show HTML pages preview-first so the
+    // reader sees the actual rendered server page immediately.
+    // Everything else lands on Pretty.
+    const [mode, setMode] = useState<ViewMode>(showPreview ? 'preview' : 'pretty');
+
+    // Reset the mode when the endpoint or response changes so a
+    // previously-selected tab from a different shape doesn't stick
+    // around (e.g. stuck on Preview when switching from HTML→JSON).
+    useEffect(() => {
+        setMode(showPreview ? 'preview' : 'pretty');
+    }, [selectedEndpoint, response, showPreview]);
+
+    if (loading) {
+        return (
+            <div className="flex items-center justify-center h-full gap-2">
+                <Loader2 className="h-4 w-4 animate-spin text-muted-foreground" />
+                <span className="text-xs text-muted-foreground">Sending…</span>
+            </div>
+        );
+    }
+
+    if (!selectedEndpoint) return <EmptyState icon={Terminal} text="Response will appear here" />;
+    if (!response)         return <EmptyState icon={Send} text='Press "Send Request" to see the response' />;
+
+    const hasError = Boolean(response.error);
+    const hasStatus = response.status != null;
+
+    // Pure network error (no HTTP response at all — CORS, offline, timeout)
+    if (hasError && !hasStatus) {
+        return (
+            <EmptyState
+                icon={WifiOff}
+                text={response.error!}
+                className="text-destructive [&_svg]:text-destructive"
+            />
+        );
+    }
+
+    return (
+        <>
+            <StatusBar response={response} rawText={rawText} contentType={detected.contentType} />
+
+            {/* HTTP-level error body (4xx/5xx — has status but also error flag) */}
+            {hasError && (
+                <div className="shrink-0 mx-4 mt-3 rounded border border-destructive/20 bg-destructive/5 px-3 py-2">
+                    <p className="text-xs text-destructive">{response.error}</p>
+                </div>
+            )}
+
+            <ViewTabs active={mode} onChange={setMode} showPreview={showPreview} />
+
+            <ScrollArea>
+                {mode === 'pretty' && (
+                    <PrettyView treeData={treeData} rawText={rawText} detected={detected} />
+                )}
+                {mode === 'raw' && <RawView rawText={rawText} />}
+                {mode === 'preview' && <PreviewView html={rawText} />}
+            </ScrollArea>
+        </>
+    );
+}

package/src/tools/OpenapiViewer/components/shared/ResponsePanel/types.ts

@@ -0,0 +1,26 @@
+import type { Language } from '../../../../PrettyCode';
+
+/** Panels the user can switch between in the response view.
+ *
+ *   - ``pretty``:  structured rendering — JsonTree for JSON, syntax-
+ *                  highlighted code for HTML/XML/CSS/text.
+ *   - ``raw``:     plain ``<pre>`` dump of whatever the server returned.
+ *   - ``preview``: sandboxed iframe for HTML responses (when you want
+ *                  to *see* an error page the server produced rather
+ *                  than read its source). Tab is hidden for non-HTML. */
+export type ViewMode = 'pretty' | 'raw' | 'preview';
+
+/** Content categories derived from the server's ``Content-Type`` header.
+ *  We project the rich MIME type space onto a short enum so the renderer
+ *  and tab-list only have to switch on a handful of values. */
+export type ContentKind = 'json' | 'html' | 'xml' | 'css' | 'javascript' | 'text';
+
+export interface DetectedContent {
+    kind: ContentKind;
+    /** Prism ``Language`` id matching ``kind`` — fed into PrettyCode. */
+    prism: Language;
+    /** Full Content-Type header value, stripped of parameters (e.g.
+     *  ``application/json`` without ``; charset=utf-8``). ``null`` when
+     *  the server didn't send one. */
+    contentType: string | null;
+}

package/src/tools/OpenapiViewer/components/shared/ResponsePanel/useResponseView.ts

@@ -0,0 +1,62 @@
+import { useMemo } from 'react';
+
+import { detectContent } from './detectContent';
+import type { DetectedContent } from './types';
+
+interface UseResponseViewResult {
+    /** Parsed JSON value when the body is JSON, otherwise ``null``.
+     *  JsonTree needs a live object to render properly, so we parse
+     *  once up-front and cache. */
+    treeData: unknown;
+    /** Stringified body, always present when the server returned
+     *  anything. Used by Raw and Pretty-for-text tabs. */
+    rawText: string;
+    /** Content-type + prism language inference. */
+    detected: DetectedContent;
+}
+
+/** Shape the raw response payload into the pieces each view tab
+ *  needs. Exposed as a hook so the component stays thin and the
+ *  normalisation is easy to test in isolation. */
+export function useResponseView(
+    data: unknown,
+    headers: unknown,
+): UseResponseViewResult {
+    return useMemo(() => {
+        if (data == null) {
+            return {
+                treeData: null,
+                rawText: '',
+                detected: detectContent(headers, ''),
+            };
+        }
+
+        // String body — might be JSON-in-a-string or a plain text dump.
+        if (typeof data === 'string') {
+            try {
+                return {
+                    treeData: JSON.parse(data),
+                    rawText: data,
+                    detected: detectContent(headers, data),
+                };
+            } catch {
+                return {
+                    treeData: null,
+                    rawText: data,
+                    detected: detectContent(headers, data),
+                };
+            }
+        }
+
+        // Object body — axios already parsed it. Stringify for Raw/
+        // Preview tabs and treat it as JSON regardless of headers.
+        const stringified = (() => {
+            try { return JSON.stringify(data, null, 2); } catch { return String(data); }
+        })();
+        return {
+            treeData: data,
+            rawText: stringified,
+            detected: detectContent(headers, stringified),
+        };
+    }, [data, headers]);
+}

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

@@ -5,4 +5,6 @@
  */
 
 export { default as useOpenApiSchema } from './useOpenApiSchema';
-export { useMobile } from './useMobile'; 
+export { useMobile } from './useMobile';
+export { useDocsUrlSync, parseDocsHash, buildDocsHash } from './useDocsUrlSync';
+export type { ParsedHash } from './useDocsUrlSync';

package/src/tools/OpenapiViewer/hooks/useDocsUrlSync.ts

@@ -0,0 +1,119 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+
+/** Hash format: ``#<schemaId>/<anchor>``.
+ *  - ``#catalog/ep-get-users`` — specific endpoint in ``catalog`` schema
+ *  - ``#catalog`` — open ``catalog`` schema at its top
+ *  - empty — no initial target, leave viewer at its default
+ *
+ *  We intentionally keep this opinionated and stringly-typed: the host app
+ *  already controls which schemas exist, so there is no room for ambiguity
+ *  beyond the two segments. */
+export interface ParsedHash {
+  schemaId: string | null;
+  anchor: string | null;
+}
+
+export function parseDocsHash(hash: string): ParsedHash {
+  const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+  if (!raw) return { schemaId: null, anchor: null };
+  const [schemaId = null, ...rest] = raw.split('/');
+  const anchor = rest.length > 0 ? rest.join('/') : null;
+  return {
+    schemaId: schemaId || null,
+    anchor: anchor || null,
+  };
+}
+
+export function buildDocsHash(schemaId: string | null, anchor: string | null): string {
+  if (!schemaId && !anchor) return '';
+  if (schemaId && anchor) return `#${schemaId}/${anchor}`;
+  if (schemaId) return `#${schemaId}`;
+  return anchor ? `#${anchor}` : '';
+}
+
+interface UseDocsUrlSyncProps {
+  enabled: boolean;
+  currentSchemaId: string | null;
+  activeAnchor: string | null;
+  /** Called on mount / ``popstate`` / ``hashchange`` with the hash state.
+   *  The consumer is responsible for dispatching into its own handlers
+   *  (switching schema, scrolling to endpoint) in the right order. */
+  onHashTarget: (target: ParsedHash) => void;
+}
+
+/** Two-way sync between browser hash and docs viewer state.
+ *
+ *  - Writes use ``history.replaceState`` so scrollspy-driven updates don't
+ *    pollute the back/forward stack. User-initiated navigation (click on
+ *    sidebar row, schema switch) still lands in history because the click
+ *    itself already did ``pushState`` — or will, via plain anchor hrefs.
+ *  - Reads happen on mount (initial target) and on ``popstate`` /
+ *    ``hashchange`` (Back/Forward / external anchor clicks).
+ *  - When ``enabled`` is false, the hook is a no-op — the viewer stays
+ *    hash-free so you can embed it inside a larger page. */
+export function useDocsUrlSync({
+  enabled,
+  currentSchemaId,
+  activeAnchor,
+  onHashTarget,
+}: UseDocsUrlSyncProps) {
+  // Ignore the very first write — otherwise on mount we'd clobber the
+  // incoming hash with the viewer's empty defaults before ``onHashTarget``
+  // has a chance to apply it.
+  const primedRef = useRef(false);
+  const onHashTargetRef = useRef(onHashTarget);
+  useEffect(() => {
+    onHashTargetRef.current = onHashTarget;
+  }, [onHashTarget]);
+
+  // Read: mount + hashchange/popstate
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+
+    const apply = () => {
+      onHashTargetRef.current(parseDocsHash(window.location.hash));
+    };
+    apply();
+    primedRef.current = true;
+
+    window.addEventListener('hashchange', apply);
+    window.addEventListener('popstate', apply);
+    return () => {
+      window.removeEventListener('hashchange', apply);
+      window.removeEventListener('popstate', apply);
+    };
+  }, [enabled]);
+
+  // Write: whenever the viewer's state changes
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+    if (!primedRef.current) return;
+
+    const next = buildDocsHash(currentSchemaId, activeAnchor);
+    const current = window.location.hash;
+    if (next === current) return;
+
+    // replaceState keeps Back/Forward meaningful — a single scroll-through
+    // the page shouldn't create 50 history entries.
+    const url = next
+      ? `${window.location.pathname}${window.location.search}${next}`
+      : `${window.location.pathname}${window.location.search}`;
+    window.history.replaceState(window.history.state, '', url);
+  }, [enabled, currentSchemaId, activeAnchor]);
+
+  const pushTarget = useCallback(
+    (schemaId: string | null, anchor: string | null) => {
+      if (!enabled || typeof window === 'undefined') return;
+      const next = buildDocsHash(schemaId, anchor);
+      const url = next
+        ? `${window.location.pathname}${window.location.search}${next}`
+        : `${window.location.pathname}${window.location.search}`;
+      window.history.pushState(window.history.state, '', url);
+    },
+    [enabled],
+  );
+
+  return { pushTarget };
+}