@djangocfg/ui-tools 2.1.284 → 2.1.286

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

@@ -0,0 +1,142 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { ApiEndpoint } from '../types';
+
+/**
+ * Per-endpoint draft kept in localStorage so user input survives across
+ * reloads and across switching back-and-forth between endpoints.
+ *
+ * Scoped by ``schemaId`` + ``method`` + ``path`` — two endpoints on the
+ * same path with different methods don't share drafts. Two different
+ * APIs don't collide either.
+ *
+ * Storage shape:
+ *   { parameters: { [name]: string }, requestBody: string }
+ *
+ * Implementation note: we deliberately DO NOT build on top of
+ * ``useLocalStorage`` here. That hook's ``setValue`` callback reference
+ * changes whenever its internal state changes, and when EndpointDraftSync
+ * mirrors context → draft, the chain
+ *   state change ⇒ persist call ⇒ hook state change ⇒ new callback ⇒
+ *   effect rerun ⇒ persist call …
+ * blew up into a maximum-update-depth loop. Writing straight to
+ * ``localStorage`` with a stable ref-based writer breaks the cycle.
+ */
+export interface EndpointDraft {
+    parameters: Record<string, string>;
+    requestBody: string;
+}
+
+const EMPTY_DRAFT: EndpointDraft = { parameters: {}, requestBody: '' };
+
+function storageKey(schemaId: string | null, ep: ApiEndpoint | null): string | null {
+    if (!schemaId || !ep) return null;
+    return `openapi-playground:draft:${schemaId}:${ep.method}:${ep.path}`;
+}
+
+function readDraft(key: string | null): EndpointDraft {
+    if (!key || typeof window === 'undefined') return EMPTY_DRAFT;
+    try {
+        const raw = window.localStorage.getItem(key);
+        if (!raw) return EMPTY_DRAFT;
+        const parsed = JSON.parse(raw) as Partial<EndpointDraft>;
+        return {
+            parameters: parsed?.parameters ?? {},
+            requestBody: typeof parsed?.requestBody === 'string' ? parsed.requestBody : '',
+        };
+    } catch {
+        return EMPTY_DRAFT;
+    }
+}
+
+function writeDraft(key: string | null, value: EndpointDraft): void {
+    if (!key || typeof window === 'undefined') return;
+    try {
+        // Skip writes for empty drafts — reduces storage noise and keeps
+        // "never edited" endpoints out of storage entirely.
+        if (Object.keys(value.parameters).length === 0 && !value.requestBody) {
+            window.localStorage.removeItem(key);
+            return;
+        }
+        window.localStorage.setItem(key, JSON.stringify(value));
+    } catch {
+        // Quota / private mode — silently drop; UI state still works.
+    }
+}
+
+export interface UseEndpointDraftResult {
+    /** Draft snapshot loaded on mount / endpoint change. Does not update
+     *  as the user types — the caller owns the "live" state (context). */
+    draft: EndpointDraft;
+    /** Persist the current parameters. Safe to call on every change;
+     *  writes skip when the endpoint has no key yet. */
+    setParameters: (params: Record<string, string>) => void;
+    setRequestBody: (body: string) => void;
+    /** Wipe the persisted draft for the current endpoint. */
+    reset: () => void;
+}
+
+export function useEndpointDraft(
+    schemaId: string | null,
+    endpoint: ApiEndpoint | null,
+): UseEndpointDraftResult {
+    const key = storageKey(schemaId, endpoint);
+
+    // ``draft`` is reloaded from storage only when the key changes —
+    // not when we write. Writes don't need to come back to us because
+    // the caller keeps the live state and re-reads on key change.
+    const [draft, setDraftSnapshot] = useState<EndpointDraft>(() => readDraft(key));
+
+    // Track the last loaded key so we reload exactly once per endpoint.
+    const loadedKeyRef = useRef<string | null>(key);
+    useEffect(() => {
+        if (loadedKeyRef.current === key) return;
+        loadedKeyRef.current = key;
+        setDraftSnapshot(readDraft(key));
+    }, [key]);
+
+    // Keep a ref of the current key so the writers below stay stable
+    // across renders — React callback identity was the root cause of
+    // the infinite render loop we had before.
+    const keyRef = useRef(key);
+    useEffect(() => {
+        keyRef.current = key;
+    }, [key]);
+
+    // Same for the latest full draft value — both writers need to merge
+    // their field into the last known shape before writing.
+    const latestRef = useRef<EndpointDraft>(draft);
+    useEffect(() => {
+        latestRef.current = draft;
+    }, [draft]);
+
+    const setParameters = useCallback((params: Record<string, string>) => {
+        const next: EndpointDraft = {
+            parameters: params,
+            requestBody: latestRef.current.requestBody,
+        };
+        latestRef.current = next;
+        writeDraft(keyRef.current, next);
+    }, []);
+
+    const setRequestBody = useCallback((body: string) => {
+        const next: EndpointDraft = {
+            parameters: latestRef.current.parameters,
+            requestBody: body,
+        };
+        latestRef.current = next;
+        writeDraft(keyRef.current, next);
+    }, []);
+
+    const reset = useCallback(() => {
+        latestRef.current = EMPTY_DRAFT;
+        if (keyRef.current && typeof window !== 'undefined') {
+            try { window.localStorage.removeItem(keyRef.current); } catch { /* noop */ }
+        }
+        setDraftSnapshot(EMPTY_DRAFT);
+    }, []);
+
+    return { draft, setParameters, setRequestBody, reset };
+}

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

@@ -3,27 +3,90 @@
 import consola from 'consola';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
-import { ApiEndpoint, OpenApiSchema, SchemaSource, UseOpenApiSchemaReturn } from '../types';
+import { ApiEndpoint, OpenApiInfo, OpenApiSchema, SchemaSource, UseOpenApiSchemaReturn } from '../types';
+import { dereferenceSchema } from '../utils/schemaExport';
+import { joinUrl, resolveBaseUrl } from '../utils/url';
+
+// ─── JSON Schema → example value ──────────────────────────────────────────────
+
+type JsonSchemaNode = Record<string, unknown> & {
+  type?: string;
+  properties?: Record<string, JsonSchemaNode>;
+  required?: string[];
+  items?: JsonSchemaNode;
+  enum?: unknown[];
+  example?: unknown;
+  default?: unknown;
+  format?: string;
+};
+
+/** Walk a JSON Schema and build a realistic-looking example value. */
+function exampleFromSchema(schema: JsonSchemaNode | undefined, depth = 0): unknown {
+  if (!schema || depth > 8) return null;
+
+  // Respect schema-provided examples first — no need to invent a value
+  // when the spec author already did the work.
+  if (schema.example !== undefined) return schema.example;
+  if (schema.default !== undefined) return schema.default;
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
+
+  switch (schema.type) {
+    case 'object': {
+      const out: Record<string, unknown> = {};
+      const props = schema.properties ?? {};
+      for (const [k, v] of Object.entries(props)) {
+        out[k] = exampleFromSchema(v, depth + 1);
+      }
+      return out;
+    }
+    case 'array':
+      return [exampleFromSchema(schema.items, depth + 1)];
+    case 'integer':
+    case 'number':
+      return 0;
+    case 'boolean':
+      return false;
+    case 'string':
+      if (schema.format === 'date-time') return new Date().toISOString();
+      if (schema.format === 'date') return new Date().toISOString().slice(0, 10);
+      if (schema.format === 'email') return 'user@example.com';
+      if (schema.format === 'uri' || schema.format === 'url') return 'https://example.com';
+      if (schema.format === 'uuid') return '00000000-0000-0000-0000-000000000000';
+      return '';
+    default:
+      // No type (or composed schema like allOf/oneOf we don't unpack) —
+      // fall back to an empty object rather than ``null`` so the resulting
+      // JSON is still valid-looking.
+      if (schema.properties) {
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(schema.properties)) {
+          out[k] = exampleFromSchema(v, depth + 1);
+        }
+        return out;
+      }
+      return null;
+  }
+}
 
 // HTTP methods to extract from OpenAPI schema
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const;
 
-// Extract endpoints from OpenAPI schema (all methods)
-const extractEndpoints = (schema: OpenApiSchema): ApiEndpoint[] => {
+// Extract endpoints from OpenAPI schema (all methods). ``baseUrl`` is
+// resolved by the caller via ``resolveBaseUrl`` — we just paste it onto
+// the front of each path here.
+const extractEndpoints = (schema: OpenApiSchema, baseUrl: string): ApiEndpoint[] => {
   const endpoints: ApiEndpoint[] = [];
 
   if (!schema.paths) return [];
 
-  // Get base URL from servers
-  const baseUrl = schema.servers && schema.servers.length > 0 ? schema.servers[0].url : '';
-
   for (const [path, methods] of Object.entries(schema.paths)) {
     for (const method of HTTP_METHODS) {
       const op = (methods as any)[method];
       if (!op) continue;
 
       const methodUpper = method.toUpperCase();
-      const description = op.description || op.summary || `${methodUpper} ${path}`;
+      const summary = (op.summary || '').trim();
+      const description = op.description || summary || `${methodUpper} ${path}`;
       const category = op.tags?.[0] || 'Other';
 
       const parameters: Array<{
@@ -59,21 +122,29 @@ const extractEndpoints = (schema: OpenApiSchema): ApiEndpoint[] => {
         }
       }
 
-      // Extract request body info
-      let requestBody: { type: string; description?: string } | undefined;
+      // Extract request body info — keep the dereferenced schema so
+      // downstream UI can render a fields table and generate a starter
+      // example instead of showing an opaque ``object`` / ``array`` tag.
+      let requestBody: ApiEndpoint['requestBody'];
       if (op.requestBody) {
         const content = op.requestBody.content;
         const mediaType = content?.['application/json'] || content?.[Object.keys(content || {})[0]];
+        const rawSchema = mediaType?.schema as JsonSchemaNode | undefined;
         requestBody = {
-          type: mediaType?.schema?.type || 'object',
+          type: rawSchema?.type || 'object',
           description: op.requestBody.description,
+          schema: rawSchema,
+          example: rawSchema
+            ? JSON.stringify(exampleFromSchema(rawSchema), null, 2)
+            : undefined,
         };
       }
 
       const endpoint: ApiEndpoint = {
         name: path.split('/').pop() || path,
         method: methodUpper,
-        path: baseUrl + path,
+        path: baseUrl ? joinUrl(baseUrl, path) : path,
+        summary,
         description,
         category,
         parameters: parameters.length > 0 ? parameters : undefined,
@@ -111,11 +182,15 @@ const fetchSchema = async (url: string): Promise<OpenApiSchema> => {
 interface UseOpenApiSchemaProps {
   schemas: SchemaSource[];
   defaultSchemaId?: string;
+  /** Global base URL override from ``PlaygroundConfig.baseUrl``.
+   *  Per-schema ``SchemaSource.baseUrl`` takes precedence over this. */
+  baseUrl?: string;
 }
 
 export default function useOpenApiSchema({
   schemas,
   defaultSchemaId,
+  baseUrl: configBaseUrl,
 }: UseOpenApiSchemaProps): UseOpenApiSchemaReturn {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -136,13 +211,45 @@ export default function useOpenApiSchema({
     [loadedSchemas, currentSchemaId]
   );
 
+  // Dereference once per schema load so endpoint extraction sees fully
+  // resolved ``$ref`` graphs. The raw schema is still exposed via
+  // ``rawSchema`` for Copy-for-AI (juniors may want to hand the raw
+  // document to an LLM and have it resolve refs itself).
+  const dereferencedSchema = useMemo(
+    () => (currentOpenApiSchema ? dereferenceSchema(currentOpenApiSchema) : null),
+    [currentOpenApiSchema],
+  );
+
+  // Resolve base URL with priority chain. Centralised in ``resolveBaseUrl``
+  // so the same logic is reused by the schema-export utilities.
+  const resolvedBaseUrl = useMemo(
+    () =>
+      resolveBaseUrl({
+        schemaSource: currentSchema?.baseUrl,
+        config: configBaseUrl,
+        fromServers: currentOpenApiSchema?.servers?.[0]?.url,
+      }),
+    [currentSchema?.baseUrl, configBaseUrl, currentOpenApiSchema],
+  );
+
   const endpoints = useMemo(
-    () => (currentOpenApiSchema ? extractEndpoints(currentOpenApiSchema) : []),
-    [currentOpenApiSchema]
+    () => (dereferencedSchema ? extractEndpoints(dereferencedSchema, resolvedBaseUrl) : []),
+    [dereferencedSchema, resolvedBaseUrl]
   );
 
   const categories = useMemo(() => getCategories(endpoints), [endpoints]);
 
+  const schemaInfo = useMemo<OpenApiInfo | null>(() => {
+    if (!currentOpenApiSchema?.info) return null;
+    const { title, version, description } = currentOpenApiSchema.info;
+    return {
+      title,
+      version,
+      description,
+      servers: currentOpenApiSchema.servers,
+    };
+  }, [currentOpenApiSchema]);
+
   // Load schema when current schema changes
   useEffect(() => {
     if (!currentSchema) return;
@@ -206,6 +313,12 @@ export default function useOpenApiSchema({
     categories,
     schemas,
     currentSchema,
+    schemaInfo,
+    rawSchema: currentOpenApiSchema ?? null,
+    // Consumers expect ``undefined`` when no base URL was resolved (for
+    // conditional ``{ baseUrl?: … }`` plumbing). Turn the empty-string
+    // convention from the resolver into undefined at the API boundary.
+    resolvedBaseUrl: resolvedBaseUrl || undefined,
     setCurrentSchema,
     refresh,
   };

package/src/tools/OpenapiViewer/index.tsx

@@ -4,12 +4,10 @@ import React, { lazy, Suspense } from 'react';
 import { PlaygroundProvider } from './context/PlaygroundContext';
 import type { PlaygroundConfig } from './types';
 
-// Lazy load the PlaygroundLayout component
-const PlaygroundLayout = lazy(() =>
-  import('./components/PlaygroundLayout').then((mod) => ({ default: mod.PlaygroundLayout }))
+const DocsLayout = lazy(() =>
+  import('./components/DocsLayout').then((mod) => ({ default: mod.DocsLayout }))
 );
 
-// Loading fallback component
 const LoadingFallback = () => (
   <div className="flex items-center justify-center min-h-[400px]">
     <div className="text-muted-foreground">Loading API Playground...</div>
@@ -24,14 +22,12 @@ export const Playground: React.FC<PlaygroundProps> = ({ config }) => {
   return (
     <PlaygroundProvider config={config}>
       <Suspense fallback={<LoadingFallback />}>
-        <PlaygroundLayout />
+        <DocsLayout />
       </Suspense>
     </PlaygroundProvider>
   );
 };
 
-// Re-export types for convenience
 export type { PlaygroundConfig, SchemaSource } from './types';
 
-// Default export for dynamic import
 export default Playground;

package/src/tools/OpenapiViewer/lazy.tsx

@@ -7,28 +7,20 @@
  * Use this for automatic code-splitting with Suspense fallback.
  *
  * For direct imports without lazy loading, use:
- * import OpenapiViewer from '@djangocfg/ui-tools/openapi'
+ *   import OpenapiViewer from '@djangocfg/ui-tools/openapi'
  */
 
 import * as React from 'react';
-import { createLazyComponent, LoadingFallback } from '../../components';
+import { createLazyComponent } from '../../components';
 import { PlaygroundProvider } from './context/PlaygroundContext';
 import type { ApiKey, PlaygroundConfig, SchemaSource } from './types';
 
-// ============================================================================
-// Types
-// ============================================================================
-
 export interface PlaygroundProps {
   config: PlaygroundConfig;
 }
 
 export type { ApiKey, PlaygroundConfig, SchemaSource };
 
-// ============================================================================
-// OpenAPI Loading Fallback
-// ============================================================================
-
 function OpenapiLoadingFallback() {
   return (
     <div className="flex items-center justify-center min-h-[400px] bg-muted/30 rounded-lg">
@@ -40,31 +32,18 @@ function OpenapiLoadingFallback() {
   );
 }
 
-// ============================================================================
-// Lazy Component (internal)
-// ============================================================================
-
-const LazyPlaygroundLayout = createLazyComponent(
-  () => import('./components/PlaygroundLayout').then((mod) => ({ default: mod.PlaygroundLayout })),
+const LazyDocsLayout = createLazyComponent(
+  () => import('./components/DocsLayout').then((mod) => ({ default: mod.DocsLayout })),
   {
-    displayName: 'LazyPlaygroundLayout',
+    displayName: 'LazyDocsLayout',
     fallback: <OpenapiLoadingFallback />,
   }
 );
 
-// ============================================================================
-// LazyOpenapiViewer
-// ============================================================================
-
-/**
- * LazyOpenapiViewer - Lazy-loaded OpenAPI schema viewer & playground
- *
- * Automatically shows loading state while OpenAPI components load (~400KB)
- */
 export const LazyOpenapiViewer: React.FC<PlaygroundProps> = ({ config }) => {
   return (
     <PlaygroundProvider config={config}>
-      <LazyPlaygroundLayout />
+      <LazyDocsLayout />
     </PlaygroundProvider>
   );
 };

package/src/tools/OpenapiViewer/types.ts

@@ -19,6 +19,9 @@ export interface ApiEndpoint {
   name: string;
   method: string;
   path: string;
+  /** Short human label from OpenAPI ``operation.summary``. Empty when
+   *  the spec provides none. Prefer this for sidebar rows and breadcrumbs. */
+  summary: string;
   description: string;
   category: string;
   parameters?: Array<{
@@ -30,6 +33,12 @@ export interface ApiEndpoint {
   requestBody?: {
     type: string;
     description?: string;
+    /** Dereferenced JSON Schema for the body. Kept so the docs layout
+     *  can render a fields table and the playground can seed the body
+     *  editor with a generated example. */
+    schema?: Record<string, unknown>;
+    /** Pre-generated example JSON ready to drop into a textarea. */
+    example?: string;
   };
   responses?: Array<{
     code: string;
@@ -59,12 +68,23 @@ export interface SchemaSource {
   id: string;
   name: string;
   url: string; // URL to fetch OpenAPI schema from (full URL)
+  /** Per-schema override for the request base URL. Wins over the
+   *  global ``PlaygroundConfig.baseUrl`` and over ``schema.servers[0].url``
+   *  from the OpenAPI document. Use when a single playground hosts
+   *  several APIs that live on different domains. */
+  baseUrl?: string;
 }
 
 // Playground configuration
 export interface PlaygroundConfig {
   schemas: SchemaSource[]; // Array of schema URLs (full URLs from API)
   defaultSchemaId?: string; // Default schema to select
+  /** Global override for the request base URL. Used when the OpenAPI
+   *  document has no ``servers`` entry, or when docs are hosted on a
+   *  different origin than the API. Resolution order (highest wins):
+   *  ``SchemaSource.baseUrl`` → ``PlaygroundConfig.baseUrl`` →
+   *  ``schema.servers[0].url`` → empty string (relative paths). */
+  baseUrl?: string;
   /** Optional API keys the user can pick from in the request panel.
    *  When provided, the playground auto-selects the first one and
    *  syncs the ``X-API-Key`` header from ``ApiKey.secret``. Pass
@@ -101,6 +121,11 @@ export interface PlaygroundState {
   
   // UI state
   sidebarOpen: boolean;
+
+  /** Id of the schema the viewer is currently on. Drives per-endpoint
+   *  draft scoping in localStorage and is pushed in from the layout that
+   *  owns the ``useOpenApiSchema`` hook. ``null`` before first load. */
+  activeSchemaId: string | null;
 }
 
 export type PlaygroundStep = 'endpoints' | 'request' | 'response';
@@ -148,12 +173,23 @@ export interface PlaygroundContextType {
   
   // UI management
   setSidebarOpen: (open: boolean) => void;
+  setActiveSchemaId: (id: string | null) => void;
   
   // Actions
   clearAll: () => void;
   sendRequest: () => Promise<void>;
 }
 
+// Subset of OpenAPI ``info`` surfaced to consumers — lets the docs
+// layout render an intro section (title, version, description) without
+// re-parsing the schema. ``servers`` piggy-backs here for the same reason.
+export interface OpenApiInfo {
+  title: string;
+  version: string;
+  description?: string;
+  servers?: Array<{ url: string; description?: string }>;
+}
+
 // Hook return types
 export interface UseOpenApiSchemaReturn {
   loading: boolean;
@@ -162,6 +198,14 @@ export interface UseOpenApiSchemaReturn {
   categories: string[];
   schemas: SchemaSource[];
   currentSchema: SchemaSource | null;
+  /** Parsed ``info`` from the active schema. ``null`` while loading. */
+  schemaInfo: OpenApiInfo | null;
+  /** Raw parsed OpenAPI document — exposed so consumers can serialise it
+   *  (Copy-for-AI) without re-fetching. ``null`` while loading. */
+  rawSchema: OpenApiSchema | null;
+  /** Base URL used for endpoint paths, after applying priority chain
+   *  (SchemaSource.baseUrl → config.baseUrl → schema.servers[0].url). */
+  resolvedBaseUrl: string | undefined;
   setCurrentSchema: (schemaId: string) => void;
   refresh: () => void;
 } 

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

@@ -46,26 +46,5 @@ export const parseRequestHeaders = (headersString: string): Record<string, strin
   }
 };
 
-// Substitute URL parameters like {id}, {userId}, etc.
-export const substituteUrlParameters = (
-  url: string,
-  parameters: Record<string, string>
-): string => {
-  let substitutedUrl = url;
-
-  Object.entries(parameters).forEach(([key, value]) => {
-    if (value && value.trim() !== '') {
-      // Replace both {key} and %7Bkey%7D patterns (URL encoded version)
-      const patterns = [
-        new RegExp(`\\{${key}\\}`, 'g'),
-        new RegExp(`%7B${key}%7D`, 'gi'),
-      ];
-
-      patterns.forEach((pattern) => {
-        substitutedUrl = substitutedUrl.replace(pattern, encodeURIComponent(value));
-      });
-    }
-  });
-
-  return substitutedUrl;
-};
+// URL helpers moved to ./url.ts — keep this file focused on non-URL
+// formatters (method/status colour maps, JSON validation, header parsing).

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

@@ -6,4 +6,6 @@
 
 export * from './apiKeyManager';
 export * from './versionManager';
-export * from './formatters'; 
+export * from './formatters';
+export * from './schemaExport';
+export * from './url';