@djangocfg/ui-tools 2.1.285 → 2.1.286

package/src/tools/OpenapiViewer/utils/schemaExport.ts

@@ -0,0 +1,206 @@
+/**
+ * Export the current OpenAPI schema in formats friendly for LLM agents.
+ *
+ * Three flavours:
+ *   - raw:      JSON.stringify(schema) — full fidelity, largest.
+ *   - compact:  dereferenced + pruned (no xml/examples, short descriptions,
+ *               no whitespace). Usually 30–50% of raw.
+ *   - markdown: prose summary of endpoints + params + responses. Smallest,
+ *               best for small prompts. Drops response body schemas.
+ *
+ * Per-endpoint markdown is also exported so a Copy-for-AI button on a
+ * single endpoint stays cheap and does not leak unrelated paths.
+ *
+ * ``baseUrl`` resolution is done by the caller; we just substitute the
+ * resolved value into ``servers[0]`` so the copied schema points at the
+ * live API, not at whatever ``schema.servers`` originally held.
+ */
+
+import type { ApiEndpoint, OpenApiSchema } from '../types';
+import { relativePath, resolveBaseUrl } from './url';
+
+// ─── Dereference ──────────────────────────────────────────────────────────────
+
+/**
+ * Walk a JSON object and replace every ``$ref`` with the resolved value.
+ * Shallow circular-ref protection: stops at ``maxDepth`` to avoid infinite
+ * recursion on self-referential schemas (common in recursive OpenAPI types).
+ */
+export function dereferenceSchema(schema: OpenApiSchema, maxDepth = 10): OpenApiSchema {
+    const root = schema as unknown as Record<string, unknown>;
+
+    function resolveRef(ref: string): unknown {
+        // Only handle local refs (#/components/schemas/Foo). External refs are
+        // out of scope — the schema we have in memory is already a single file.
+        if (!ref.startsWith('#/')) return null;
+        const parts = ref.slice(2).split('/');
+        let node: unknown = root;
+        for (const part of parts) {
+            if (node && typeof node === 'object' && part in (node as Record<string, unknown>)) {
+                node = (node as Record<string, unknown>)[part];
+            } else {
+                return null;
+            }
+        }
+        return node;
+    }
+
+    function walk(value: unknown, depth: number): unknown {
+        if (depth > maxDepth) return value;
+        if (Array.isArray(value)) return value.map((v) => walk(v, depth + 1));
+        if (value && typeof value === 'object') {
+            const obj = value as Record<string, unknown>;
+            if (typeof obj.$ref === 'string') {
+                const resolved = resolveRef(obj.$ref);
+                if (resolved === null) return obj;
+                return walk(resolved, depth + 1);
+            }
+            const out: Record<string, unknown> = {};
+            for (const [k, v] of Object.entries(obj)) out[k] = walk(v, depth + 1);
+            return out;
+        }
+        return value;
+    }
+
+    return walk(schema, 0) as OpenApiSchema;
+}
+
+// ─── Pruning helpers ──────────────────────────────────────────────────────────
+
+const NOISY_KEYS = new Set(['xml', 'example', 'examples', 'externalDocs']);
+const MAX_DESCRIPTION_LEN = 500;
+
+/**
+ * In-place-friendly pruner (returns a new tree). Drops keys that only
+ * add bytes without giving the LLM new semantic info, and truncates
+ * very long prose descriptions.
+ */
+function pruneForCompact(value: unknown): unknown {
+    if (Array.isArray(value)) return value.map(pruneForCompact);
+    if (value && typeof value === 'object') {
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+            if (NOISY_KEYS.has(k)) continue;
+            if (k === 'description' && typeof v === 'string' && v.length > MAX_DESCRIPTION_LEN) {
+                out[k] = v.slice(0, MAX_DESCRIPTION_LEN).trimEnd() + '…';
+                continue;
+            }
+            out[k] = pruneForCompact(v);
+        }
+        return out;
+    }
+    return value;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/** Overwrite ``servers[0]`` with the resolved base URL if provided. */
+function withResolvedBaseUrl(schema: OpenApiSchema, baseUrl: string | undefined): OpenApiSchema {
+    if (!baseUrl) return schema;
+    return { ...schema, servers: [{ url: baseUrl }] };
+}
+
+export function toRawJson(schema: OpenApiSchema, baseUrl?: string): string {
+    return JSON.stringify(withResolvedBaseUrl(schema, baseUrl), null, 2);
+}
+
+export function toCompactJson(schema: OpenApiSchema, baseUrl?: string): string {
+    const resolved = dereferenceSchema(withResolvedBaseUrl(schema, baseUrl));
+    const pruned = pruneForCompact(resolved);
+    return JSON.stringify(pruned);
+}
+
+// ─── Markdown ────────────────────────────────────────────────────────────────
+
+
+export function endpointToMarkdown(ep: ApiEndpoint): string {
+    const lines: string[] = [];
+    lines.push(`### ${ep.method} ${ep.path}`);
+    if (ep.description) lines.push(ep.description);
+
+    const pathParams = ep.parameters?.filter((p) => ep.path.includes(`{${p.name}}`)) ?? [];
+    const queryParams = ep.parameters?.filter((p) => !ep.path.includes(`{${p.name}}`)) ?? [];
+
+    if (pathParams.length > 0) {
+        lines.push('', '**Path parameters**');
+        for (const p of pathParams) {
+            const req = p.required ? ' (required)' : '';
+            const desc = p.description ? ` — ${p.description}` : '';
+            lines.push(`- \`${p.name}\`: ${p.type}${req}${desc}`);
+        }
+    }
+    if (queryParams.length > 0) {
+        lines.push('', '**Query parameters**');
+        for (const p of queryParams) {
+            const req = p.required ? ' (required)' : '';
+            const desc = p.description ? ` — ${p.description}` : '';
+            lines.push(`- \`${p.name}\`: ${p.type}${req}${desc}`);
+        }
+    }
+    if (ep.requestBody) {
+        const desc = ep.requestBody.description ? ` — ${ep.requestBody.description}` : '';
+        lines.push('', `**Request body:** ${ep.requestBody.type}${desc}`);
+    }
+    if (ep.responses && ep.responses.length > 0) {
+        lines.push('', '**Responses**');
+        for (const r of ep.responses) {
+            lines.push(`- \`${r.code}\` — ${r.description}`);
+        }
+    }
+    return lines.join('\n');
+}
+
+export function toMarkdown(
+    schema: OpenApiSchema,
+    endpoints: ApiEndpoint[],
+    baseUrl?: string,
+): string {
+    const lines: string[] = [];
+    const info = schema.info;
+    const resolvedBase = resolveBaseUrl({
+        config: baseUrl,
+        fromServers: schema.servers?.[0]?.url,
+    });
+
+    lines.push(`# ${info?.title ?? 'API'}${info?.version ? ` (v${info.version})` : ''}`);
+    if (resolvedBase) lines.push('', `**Base URL:** \`${resolvedBase}\``);
+    if (info?.description) lines.push('', info.description.trim());
+
+    // Group by tag/category for readable output.
+    const grouped = new Map<string, ApiEndpoint[]>();
+    for (const ep of endpoints) {
+        const arr = grouped.get(ep.category) ?? [];
+        arr.push(ep);
+        grouped.set(ep.category, arr);
+    }
+
+    const categories = Array.from(grouped.keys()).sort((a, b) => {
+        if (a === 'Other') return 1;
+        if (b === 'Other') return -1;
+        return a.localeCompare(b);
+    });
+
+    for (const category of categories) {
+        lines.push('', `## ${category}`);
+        const list = grouped.get(category)!;
+        for (const ep of list) {
+            // Use relativePath for section headers to keep markdown compact —
+            // the full URL is already available as "Base URL" above.
+            const displayPath = relativePath(ep.path);
+            const sub = endpointToMarkdown({ ...ep, path: displayPath });
+            lines.push('', sub);
+        }
+    }
+
+    return lines.join('\n');
+}
+
+// ─── Size helper ──────────────────────────────────────────────────────────────
+
+/** Human-readable byte count: ``12.3 KB``, ``480 B``. */
+export function formatBytes(s: string): string {
+    const bytes = new Blob([s]).size;
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+}

package/src/tools/OpenapiViewer/utils/url.ts

@@ -0,0 +1,202 @@
+/**
+ * URL utilities for the OpenAPI playground.
+ *
+ * Consolidated here to avoid the pre-existing split where
+ * ``substituteUrlParameters`` lived in formatters.ts, base URL priority
+ * lived inside ``useOpenApiSchema``, query params were never assembled
+ * at all (that was a bug), and ``resolveAbsoluteUrl`` was tacked on
+ * later.
+ *
+ * Conceptual model: a request URL is built from four layers, highest
+ * priority first:
+ *
+ *   1. An absolute override URL the user pasted (rare — not plumbed
+ *      through the UI today, but the shape supports it).
+ *   2. ``baseUrl`` — from ``SchemaSource.baseUrl`` → ``PlaygroundConfig.baseUrl``
+ *      → ``schema.servers[0].url``.
+ *   3. Endpoint path template (``/pet/{petId}``) + substituted path params.
+ *   4. Query string built from parameters that don't match any path
+ *      placeholder.
+ *
+ * Every helper below lives on one of those layers. ``UrlBuilder`` wires
+ * them together when the caller has all four; individual functions are
+ * exported for cases that only need one step (e.g. ``relativePath``
+ * for display in the sidebar).
+ */
+
+import type { ApiEndpoint } from '../types';
+
+// ─── Path substitution ────────────────────────────────────────────────────────
+
+const PATH_PARAM_RE = /\{([^{}]+)\}/g;
+
+/**
+ * Return the list of ``{name}`` placeholders in a path template.
+ * Preserves order, deduplicates.
+ */
+export function extractPathPlaceholders(template: string): string[] {
+    const seen = new Set<string>();
+    const out: string[] = [];
+    for (const match of template.matchAll(PATH_PARAM_RE)) {
+        const name = match[1]!;
+        if (!seen.has(name)) {
+            seen.add(name);
+            out.push(name);
+        }
+    }
+    return out;
+}
+
+/**
+ * Replace ``{name}`` placeholders with values from ``values``. Values
+ * are URL-path-encoded with ``encodeURIComponent`` — safe for single
+ * segments but escapes ``/`` too. That's intentional: a user typing
+ * ``a/b`` into a path param should get ``a%2Fb`` so the server receives
+ * the intended single segment, not two.
+ *
+ * Values are only substituted when non-empty after trimming.
+ */
+export function substitutePath(template: string, values: Record<string, string>): string {
+    return template.replace(PATH_PARAM_RE, (whole, name) => {
+        const v = values[name];
+        return v && v.trim() !== '' ? encodeURIComponent(v) : whole;
+    });
+}
+
+/** Placeholders that have no non-empty value in ``values``. */
+export function unfilledPlaceholders(
+    template: string,
+    values: Record<string, string>,
+): string[] {
+    return extractPathPlaceholders(template).filter(
+        (name) => !(values[name] ?? '').trim(),
+    );
+}
+
+// ─── Query assembly ───────────────────────────────────────────────────────────
+
+/**
+ * Append a query string to ``url`` from the keys of ``values`` that
+ * are not path placeholders in ``pathTemplate``. Existing query strings
+ * are preserved: new keys are merged, existing keys are overwritten.
+ *
+ * Empty values are skipped (a form field that was left blank does not
+ * become ``?foo=`` on the wire).
+ */
+export function appendQuery(
+    url: string,
+    values: Record<string, string>,
+    pathTemplate: string,
+): string {
+    const pathNames = new Set(extractPathPlaceholders(pathTemplate));
+    const queryEntries = Object.entries(values).filter(
+        ([name, value]) => !pathNames.has(name) && value && value.trim() !== '',
+    );
+    if (queryEntries.length === 0) return url;
+
+    // Split any existing query so we can merge cleanly.
+    const [base, existingQuery = ''] = url.split('?', 2);
+    const params = new URLSearchParams(existingQuery);
+    for (const [k, v] of queryEntries) params.set(k, v);
+    const qs = params.toString();
+    return qs ? `${base}?${qs}` : (base ?? url);
+}
+
+// ─── Absolute / relative ──────────────────────────────────────────────────────
+
+/**
+ * Prepend ``window.location.origin`` when the URL is relative so the
+ * result is runnable from a terminal via curl. No-op on SSR or when
+ * already absolute.
+ */
+export function resolveAbsolute(url: string): string {
+    if (!url) return url;
+    if (/^https?:\/\//i.test(url)) return url;
+    if (typeof window === 'undefined') return url;
+    if (url.startsWith('//')) return `${window.location.protocol}${url}`;
+    if (url.startsWith('/')) return `${window.location.origin}${url}`;
+    return url;
+}
+
+/** Pull just the path out of any URL (absolute or relative). */
+export function relativePath(url: string): string {
+    try { return new URL(url).pathname; } catch { return url; }
+}
+
+/**
+ * Concatenate URL segments with exactly one slash between each. Works
+ * whether inputs have trailing/leading slashes or not.
+ *
+ *   joinUrl('https://api.example.com/', '/v3', 'pet') → 'https://api.example.com/v3/pet'
+ */
+export function joinUrl(...parts: string[]): string {
+    return parts
+        .filter((p) => p !== undefined && p !== null && p !== '')
+        .map((p, i) => {
+            if (i === 0) return String(p).replace(/\/+$/, '');
+            return String(p).replace(/^\/+|\/+$/g, '');
+        })
+        .filter((p) => p !== '')
+        .join('/');
+}
+
+// ─── Base URL resolution ──────────────────────────────────────────────────────
+
+export interface BaseUrlSources {
+    /** Highest priority — per-schema override. */
+    schemaSource?: string;
+    /** Global config-level override. */
+    config?: string;
+    /** Fallback from the OpenAPI document itself. */
+    fromServers?: string;
+}
+
+/**
+ * Apply the documented priority chain:
+ *   ``schemaSource → config → fromServers → ''``.
+ */
+export function resolveBaseUrl(sources: BaseUrlSources): string {
+    return sources.schemaSource || sources.config || sources.fromServers || '';
+}
+
+// ─── UrlBuilder ───────────────────────────────────────────────────────────────
+
+/**
+ * End-to-end builder that takes an endpoint + user-entered parameters
+ * and produces both the fetch URL and a copy-paste-friendly preview.
+ */
+export class UrlBuilder {
+    constructor(
+        private readonly endpoint: ApiEndpoint,
+        private readonly parameters: Record<string, string>,
+    ) {}
+
+    /** What ``fetch()`` receives: substituted path + query string. Origin
+     *  is whatever the endpoint template already had (relative paths
+     *  stay relative so the browser resolves them against the page). */
+    build(): string {
+        const substituted = substitutePath(this.endpoint.path, this.parameters);
+        return appendQuery(substituted, this.parameters, this.endpoint.path);
+    }
+
+    /** Same as ``build()`` but guaranteed absolute — for curl snippets
+     *  and anywhere the URL leaves the browser context. */
+    buildAbsolute(): string {
+        return resolveAbsolute(this.build());
+    }
+
+    /** Names of required path/query params still empty. */
+    missingRequired(): string[] {
+        if (!this.endpoint.parameters) return [];
+        return this.endpoint.parameters
+            .filter((p) => p.required && !(this.parameters[p.name] ?? '').trim())
+            .map((p) => p.name);
+    }
+
+    /** Placeholders in the template with no matching value. Usually a
+     *  superset of ``missingRequired`` — catches schemas that forgot
+     *  to flag a path param as required. */
+    unfilledPlaceholders(): string[] {
+        return unfilledPlaceholders(this.endpoint.path, this.parameters);
+    }
+}

package/src/tools/PrettyCode/PrettyCode.client.tsx

@@ -17,9 +17,15 @@ interface PrettyCodeProps {
   customBg?: string; // Custom background class
   isCompact?: boolean; // Compact mode for smaller font sizes
   scrollIsolation?: boolean; // Block scroll capture until user clicks (default: true)
+  /**
+   * Line count at which the viewer starts to scroll instead of growing.
+   * ``undefined`` (default) = always grows to fit content, no scroll.
+   * Set e.g. ``50`` to cap short snippets inline and scroll long ones.
+   */
+  maxLines?: number;
 }
 
-const PrettyCode = ({ data, language, className, mode, inline = false, customBg, isCompact = false, scrollIsolation }: PrettyCodeProps) => {
+const PrettyCode = ({ data, language, className, mode, inline = false, customBg, isCompact = false, scrollIsolation, maxLines }: PrettyCodeProps) => {
   const containerRef = useRef<HTMLDivElement>(null);
   const t = useAppT();
   const detectedTheme = useResolvedTheme();
@@ -41,6 +47,19 @@ const PrettyCode = ({ data, language, className, mode, inline = false, customBg,
 
   // Convert form object to JSON string with proper formatting
   const contentJson = typeof data === 'string' ? data : JSON.stringify(data || {}, null, 2);
+
+  // Enable scroll only when content exceeds maxLines. Otherwise the block
+  // grows to fit — short snippets feel natural, long ones get a cap.
+  const lineCount = contentJson ? contentJson.split('\n').length : 0;
+  const lineHeightRatio = isCompact ? 1.4 : 1.5;
+  const fontSizePx = isCompact ? 12 : 14;
+  // Vertical padding of the <pre> (top + bottom, in px) — keep in sync
+  // with the padding string below.
+  const verticalPadPx = 16 + 12; // 1rem top + 0.75rem bottom (≈)
+  const shouldScroll = maxLines !== undefined && lineCount > maxLines;
+  const maxHeightPx = maxLines !== undefined
+    ? maxLines * fontSizePx * lineHeightRatio + verticalPadPx
+    : undefined;
   
   // Handle empty content
   if (!contentJson || contentJson.trim() === '') {
@@ -170,13 +189,24 @@ const PrettyCode = ({ data, language, className, mode, inline = false, customBg,
   const borderClass = isDarkMode ? 'border-zinc-700' : 'border-border';
 
   return (
-    <div ref={containerRef} className={`group relative h-full ${bgClass} rounded-lg border ${borderClass} ${className || ''}`}>
-      {/* Toolbar: hidden by default, appears on hover. Absolute overlay so it doesn't shift layout. */}
-      <div className="absolute inset-0 pointer-events-none opacity-0 group-hover:opacity-100 transition-opacity duration-150 z-30">
+    <div
+      ref={containerRef}
+      className={`group relative ${bgClass} rounded-lg border ${borderClass} ${className || ''}`}
+      style={
+        // maxHeight caps growth at ``maxLines`` rows; without maxLines we
+        // let the block grow to fit its content (no scroll).
+        maxHeightPx ? { maxHeight: `${maxHeightPx}px` } : undefined
+      }
+    >
+      {/* Toolbar: hidden by default, appears on hover. Absolute overlay so it doesn't shift layout.
+          scrollIsolation is force-disabled when content fits without scrolling —
+          otherwise the "Click to scroll" prompt shows on a block that has
+          nothing to scroll, which reads as a bug. */}
+      <div className="absolute inset-x-0 top-0 pointer-events-none opacity-0 group-hover:opacity-100 transition-opacity duration-150 z-30">
         <div className="pointer-events-auto">
           <FloatingToolbar
             containerRef={containerRef}
-            scrollIsolation={scrollIsolation}
+            scrollIsolation={shouldScroll ? scrollIsolation : false}
             label={
               <span className="inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-muted/80 text-muted-foreground border border-border/50 backdrop-blur-sm">
                 {displayLanguage}
@@ -188,7 +218,7 @@ const PrettyCode = ({ data, language, className, mode, inline = false, customBg,
         </div>
       </div>
 
-      <div className="h-full overflow-auto">
+      <div className={shouldScroll ? 'h-full overflow-auto' : ''} style={shouldScroll ? { maxHeight: maxHeightPx } : undefined}>
         <Highlight theme={prismTheme} code={contentJson} language={normalizedLanguage as Language}>
           {({ className, style, tokens, getLineProps, getTokenProps }) => {
             // Remove background from Prism theme - we use our own via CSS
@@ -199,9 +229,13 @@ const PrettyCode = ({ data, language, className, mode, inline = false, customBg,
               style={{
                 ...restStyle,
                 margin: 0,
-                padding: '2.5rem 1rem 1rem 1rem',
+                // Top padding gives the hover toolbar room to sit over
+                // the first line without covering it. Before: 2.5rem —
+                // too much empty space on short snippets. Now: 1rem,
+                // toolbar overlays with translucent bg on hover only.
+                padding: '1rem 1rem 0.75rem 1rem',
                 fontSize,
-                lineHeight: isCompact ? 1.4 : 1.5,
+                lineHeight: lineHeightRatio,
                 fontFamily: 'monospace',
                 whiteSpace: 'pre-wrap',
                 wordBreak: 'break-word',

package/src/tools/PrettyCode/index.tsx

@@ -35,6 +35,12 @@ export interface PrettyCodeProps {
   isCompact?: boolean;
   /** Block scroll capture until user clicks (default: true) */
   scrollIsolation?: boolean;
+  /**
+   * Line count above which the block starts scrolling instead of growing.
+   * ``undefined`` (default) = no cap, block grows to fit. Set e.g. ``50``
+   * to inline short snippets and cap long ones.
+   */
+  maxLines?: number;
 }
 
 const PrettyCode: React.FC<PrettyCodeProps> = (props) => {