@djangocfg/ui-tools 2.1.287 → 2.1.289

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

@@ -3,7 +3,7 @@
 import consola from 'consola';
 import { useCallback, useEffect, useMemo, useState } from 'react';
 
-import { ApiEndpoint, OpenApiInfo, OpenApiSchema, SchemaSource, UseOpenApiSchemaReturn } from '../types';
+import { ApiEndpoint, LoadedSchemaEntry, OpenApiInfo, OpenApiSchema, SchemaSource, UseOpenApiSchemaReturn } from '../types';
 import { dereferenceSchema } from '../utils/schemaExport';
 import { joinUrl, resolveBaseUrl } from '../utils/url';
 
@@ -73,8 +73,10 @@ const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const;
 
 // 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[] => {
+// the front of each path here. ``schemaId`` is tagged onto every
+// endpoint so downstream consumers (sections-mode sidebar, anchors, URL
+// sync) can correlate endpoints back to their source schema.
+const extractEndpoints = (schema: OpenApiSchema, baseUrl: string, schemaId?: string): ApiEndpoint[] => {
   const endpoints: ApiEndpoint[] = [];
 
   if (!schema.paths) return [];
@@ -150,6 +152,7 @@ const extractEndpoints = (schema: OpenApiSchema, baseUrl: string): ApiEndpoint[]
         parameters: parameters.length > 0 ? parameters : undefined,
         requestBody,
         responses: responses.length > 0 ? responses : undefined,
+        schemaId,
       };
 
       endpoints.push(endpoint);
@@ -185,12 +188,24 @@ interface UseOpenApiSchemaProps {
   /** Global base URL override from ``PlaygroundConfig.baseUrl``.
    *  Per-schema ``SchemaSource.baseUrl`` takes precedence over this. */
   baseUrl?: string;
+  /** When ``true`` the hook fetches every schema in ``schemas`` (not just
+   *  the active one) and exposes them via ``schemasData``. Used by the
+   *  ``sections`` grouping mode — the docs column concatenates endpoints
+   *  from every schema, so they all need to be on the client. Default
+   *  is ``false`` to preserve the original lazy behaviour. */
+  preloadAll?: boolean;
+}
+
+interface SchemaLoadState {
+  loading: boolean;
+  error: string | null;
 }
 
 export default function useOpenApiSchema({
   schemas,
   defaultSchemaId,
   baseUrl: configBaseUrl,
+  preloadAll = false,
 }: UseOpenApiSchemaProps): UseOpenApiSchemaReturn {
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -200,6 +215,10 @@ export default function useOpenApiSchema({
   const [loadedSchemas, setLoadedSchemas] = useState<Map<string, OpenApiSchema>>(
     new Map()
   );
+  // Per-schema loading/error state for ``preloadAll`` — each schema may
+  // succeed or fail independently, and the UI wants to render partial
+  // results while slow/broken ones are still resolving.
+  const [loadStates, setLoadStates] = useState<Map<string, SchemaLoadState>>(new Map());
 
   const currentSchema = useMemo(
     () => schemas.find((s) => s.id === currentSchemaId) || null,
@@ -233,8 +252,11 @@ export default function useOpenApiSchema({
   );
 
   const endpoints = useMemo(
-    () => (dereferencedSchema ? extractEndpoints(dereferencedSchema, resolvedBaseUrl) : []),
-    [dereferencedSchema, resolvedBaseUrl]
+    () =>
+      dereferencedSchema
+        ? extractEndpoints(dereferencedSchema, resolvedBaseUrl, currentSchemaId)
+        : [],
+    [dereferencedSchema, resolvedBaseUrl, currentSchemaId]
   );
 
   const categories = useMemo(() => getCategories(endpoints), [endpoints]);
@@ -250,8 +272,9 @@ export default function useOpenApiSchema({
     };
   }, [currentOpenApiSchema]);
 
-  // Load schema when current schema changes
+  // Load schema when current schema changes (single-schema mode)
   useEffect(() => {
+    if (preloadAll) return;
     if (!currentSchema) return;
 
     // Skip if already loaded
@@ -274,7 +297,103 @@ export default function useOpenApiSchema({
         setError(err instanceof Error ? err.message : 'Failed to load schema');
         setLoading(false);
       });
-  }, [currentSchema, loadedSchemas]);
+  }, [currentSchema, loadedSchemas, preloadAll]);
+
+  // Preload every schema (sections-grouping mode). Each schema is fetched
+  // independently — a slow or broken source doesn't block the rest.
+  useEffect(() => {
+    if (!preloadAll) return;
+    if (schemas.length === 0) {
+      setLoading(false);
+      return;
+    }
+
+    let cancelled = false;
+    const pending = schemas.filter((s) => !loadedSchemas.has(s.id));
+    if (pending.length === 0) {
+      setLoading(false);
+      return;
+    }
+
+    setLoading(true);
+    setLoadStates((prev) => {
+      const next = new Map(prev);
+      for (const s of pending) next.set(s.id, { loading: true, error: null });
+      return next;
+    });
+
+    Promise.allSettled(
+      pending.map((s) =>
+        fetchSchema(s.url).then((schema) => ({ id: s.id, name: s.name, schema })),
+      ),
+    ).then((results) => {
+      if (cancelled) return;
+
+      setLoadedSchemas((prev) => {
+        const next = new Map(prev);
+        for (const r of results) {
+          if (r.status === 'fulfilled') {
+            next.set(r.value.id, r.value.schema);
+            consola.success(`Schema loaded: ${r.value.name}`);
+          }
+        }
+        return next;
+      });
+
+      setLoadStates((prev) => {
+        const next = new Map(prev);
+        results.forEach((r, i) => {
+          const src = pending[i]!;
+          if (r.status === 'fulfilled') {
+            next.set(src.id, { loading: false, error: null });
+          } else {
+            const msg = r.reason instanceof Error ? r.reason.message : 'Failed to load schema';
+            consola.error(`Error loading schema from ${src.url}:`, r.reason);
+            next.set(src.id, { loading: false, error: msg });
+          }
+        });
+        return next;
+      });
+
+      setLoading(false);
+    });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [preloadAll, schemas, loadedSchemas]);
+
+  const schemasData = useMemo<LoadedSchemaEntry[]>(() => {
+    if (!preloadAll) return [];
+    return schemas.map((src) => {
+      const raw = loadedSchemas.get(src.id) ?? null;
+      const deref = raw ? dereferenceSchema(raw) : null;
+      const resolved = resolveBaseUrl({
+        schemaSource: src.baseUrl,
+        config: configBaseUrl,
+        fromServers: raw?.servers?.[0]?.url,
+      });
+      const info: OpenApiInfo | null = raw?.info
+        ? {
+            title: raw.info.title,
+            version: raw.info.version,
+            description: raw.info.description,
+            servers: raw.servers,
+          }
+        : null;
+      const eps = deref ? extractEndpoints(deref, resolved, src.id) : [];
+      const state = loadStates.get(src.id) ?? { loading: !raw, error: null };
+      return {
+        source: src,
+        info,
+        rawSchema: raw,
+        endpoints: eps,
+        resolvedBaseUrl: resolved || undefined,
+        loading: state.loading,
+        error: state.error,
+      };
+    });
+  }, [preloadAll, schemas, loadedSchemas, loadStates, configBaseUrl]);
 
   const setCurrentSchema = useCallback((schemaId: string) => {
     setCurrentSchemaId(schemaId);
@@ -321,5 +440,6 @@ export default function useOpenApiSchema({
     resolvedBaseUrl: resolvedBaseUrl || undefined,
     setCurrentSchema,
     refresh,
+    schemasData,
   };
 }

package/src/tools/OpenapiViewer/types.ts

@@ -19,6 +19,10 @@ export interface ApiEndpoint {
   name: string;
   method: string;
   path: string;
+  /** ID of the schema this endpoint was extracted from. Populated whenever
+   *  endpoints from multiple schemas coexist (``sections`` grouping), so
+   *  sidebar grouping, anchors and URL sync can all tell them apart. */
+  schemaId?: string;
   /** Short human label from OpenAPI ``operation.summary``. Empty when
    *  the spec provides none. Prefer this for sidebar rows and breadcrumbs. */
   summary: string;
@@ -92,6 +96,20 @@ export interface PlaygroundConfig {
    *  a spinner instead of "no keys yet". */
   apiKeys?: ApiKey[];
   apiKeysLoading?: boolean;
+  /** How multiple schemas are presented in the sidebar.
+   *  - ``'selector'`` (default): a Combobox switches between schemas, the
+   *    docs column shows endpoints of the active schema only.
+   *  - ``'sections'``: the Combobox is hidden and every schema becomes a
+   *    top-level heading in the sidebar, with endpoints of all schemas
+   *    rendered back-to-back in the docs column. Scrollspy picks the
+   *    active schema based on what's visible. */
+  schemaGrouping?: 'selector' | 'sections';
+  /** Optional URL-hash sync. When enabled, the viewer reads/writes
+   *  ``#<schemaId>/<anchor>`` on the browser location. Falsy value (the
+   *  default) keeps the viewer hash-free. Set to an object with
+   *  ``{ enabled: true }`` to opt in; future fields (e.g. a custom
+   *  adapter) stay backwards compatible. */
+  urlSync?: boolean | { enabled: boolean };
 }
 
 // Playground state types
@@ -190,6 +208,19 @@ export interface OpenApiInfo {
   servers?: Array<{ url: string; description?: string }>;
 }
 
+/** Per-schema snapshot used by the ``sections`` grouping mode. Mirrors the
+ *  fields that ``UseOpenApiSchemaReturn`` exposes for the active schema,
+ *  but repeated for every loaded schema. */
+export interface LoadedSchemaEntry {
+  source: SchemaSource;
+  info: OpenApiInfo | null;
+  rawSchema: OpenApiSchema | null;
+  endpoints: ApiEndpoint[];
+  resolvedBaseUrl: string | undefined;
+  loading: boolean;
+  error: string | null;
+}
+
 // Hook return types
 export interface UseOpenApiSchemaReturn {
   loading: boolean;
@@ -208,4 +239,8 @@ export interface UseOpenApiSchemaReturn {
   resolvedBaseUrl: string | undefined;
   setCurrentSchema: (schemaId: string) => void;
   refresh: () => void;
-} 
+  /** Populated only when the hook was called with ``preloadAll: true``
+   *  (``sections`` grouping mode). One entry per schema source, in the
+   *  same order as ``schemas``. */
+  schemasData: LoadedSchemaEntry[];
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Find the nearest ancestor that actually scrolls vertically, or
+ * ``window`` when none exists. Handles the common embed scenarios:
+ *
+ * - Standalone page: nothing in the chain scrolls → caller scrolls
+ *   ``window`` and listens to ``window.scroll``.
+ * - Dev playground / modal shell: an intermediate ``overflow-auto``
+ *   container scrolls → caller scrolls that element and listens to
+ *   *its* ``scroll`` events (which do NOT bubble to window).
+ *
+ * A "scrollable" ancestor is one whose computed ``overflow-y`` is
+ * ``auto`` or ``scroll`` AND whose content actually overflows. We bail
+ * before ``document.body`` — ``documentElement`` is represented by
+ * ``window`` in the caller's hot path, so returning the body itself
+ * would double-count the scroll surface.
+ */
+export type ScrollTarget = HTMLElement | Window;
+
+export function getScrollParent(el: HTMLElement | null): ScrollTarget {
+    if (typeof window === 'undefined') return (null as unknown) as Window;
+    if (!el) return window;
+
+    let cur: HTMLElement | null = el.parentElement;
+    while (cur && cur !== document.body && cur !== document.documentElement) {
+        const style = getComputedStyle(cur);
+        const overflowY = style.overflowY;
+        const canScroll =
+            (overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay') &&
+            cur.scrollHeight > cur.clientHeight;
+        if (canScroll) return cur;
+        cur = cur.parentElement;
+    }
+    return window;
+}
+
+/** Top-relative scroll position of the target. */
+export function getScrollTop(target: ScrollTarget): number {
+    return target === window ? window.scrollY : (target as HTMLElement).scrollTop;
+}
+
+/** Visible viewport height of the target. */
+export function getViewportHeight(target: ScrollTarget): number {
+    return target === window ? window.innerHeight : (target as HTMLElement).clientHeight;
+}
+
+/** Y coordinate of the target's top edge, in viewport space. Used to
+ *  translate ``getBoundingClientRect().top`` into target-relative
+ *  coordinates. For ``window`` this is always ``0``. */
+export function getTargetTop(target: ScrollTarget): number {
+    return target === window ? 0 : (target as HTMLElement).getBoundingClientRect().top;
+}
+
+/** Scroll the target so that the given absolute Y lands at its top.
+ *
+ *  For ``window`` we ask the browser to animate smoothly — every engine
+ *  honours that path. Nested ``overflow-auto`` elements are a different
+ *  story: some layouts (e.g. dev-playground shells with flex parents)
+ *  silently drop the animation, leaving the user stuck. Direct
+ *  ``scrollTop`` writes always work, so we use them there — loss of
+ *  animation beats broken navigation. Consumers who want animated
+ *  scrolling inside a custom shell can wrap this function themselves. */
+export function scrollTargetTo(target: ScrollTarget, top: number) {
+    if (target === window) {
+        window.scrollTo({ top, behavior: 'smooth' });
+        return;
+    }
+    (target as HTMLElement).scrollTop = top;
+}