@djangocfg/ui-tools 2.1.286 → 2.1.289

package/src/tools/OpenapiViewer/components/DocsLayout/index.tsx

@@ -1,14 +1,17 @@
 'use client';
 
-import React, { useCallback, useRef, useState } from 'react';
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+import { keyBy } from 'lodash-es';
 
 import { Skeleton, TooltipProvider } from '@djangocfg/ui-core/components';
 import { useMediaQuery } from '@djangocfg/ui-core/hooks';
 
 import useOpenApiSchema from '../../hooks/useOpenApiSchema';
+import { useDocsUrlSync, type ParsedHash } from '../../hooks/useDocsUrlSync';
 import { usePlaygroundContext } from '../../context/PlaygroundContext';
 import type { ApiEndpoint } from '../../types';
 import { EndpointDraftSync } from '../shared/EndpointDraftSync';
+import { slugifySchemaId } from './anchor';
 import { DocsSidebar } from './Sidebar';
 import { DocsView, type DocsViewHandle } from './DocsView';
 import { SlideInPlayground } from './SlideInPlayground';
@@ -24,6 +27,12 @@ export const DocsLayout: React.FC = () => {
     // mobile-style ``TryItSheet`` on those viewports.
     const isDesktop = useMediaQuery('(min-width: 1024px)');
     const isMobile = !isDesktop;
+
+    const grouping = config.schemaGrouping ?? 'selector';
+    const preloadAll = grouping === 'sections';
+    const urlSyncEnabled =
+        typeof config.urlSync === 'boolean' ? config.urlSync : Boolean(config.urlSync?.enabled);
+
     const {
         endpoints,
         schemaInfo,
@@ -34,13 +43,16 @@ export const DocsLayout: React.FC = () => {
         schemas,
         currentSchema,
         setCurrentSchema,
+        schemasData,
     } = useOpenApiSchema({
         schemas: config.schemas,
         defaultSchemaId: config.defaultSchemaId,
         baseUrl: config.baseUrl,
+        preloadAll,
     });
 
     const [activeAnchor, setActiveAnchor] = useState<string | null>(null);
+    const [activeSchemaId, setActiveSchemaId] = useState<string | null>(null);
     const [sheetOpen, setSheetOpen] = useState(false);
     const docsRef = useRef<DocsViewHandle | null>(null);
 
@@ -49,6 +61,17 @@ export const DocsLayout: React.FC = () => {
     // semantic — "which endpoint is loaded into the playground".
     const slideOpen = !isMobile && state.selectedEndpoint !== null;
 
+    // Per-schema endpoint map for the sections sidebar. ``keyBy`` makes the
+    // lookup O(1) at render time instead of scanning schemasData in each
+    // CategoryBlock — a win for 10+ schemas.
+    const endpointsBySchema = useMemo<Record<string, ApiEndpoint[]>>(() => {
+        if (grouping !== 'sections') return {};
+        const byId = keyBy(schemasData, (e) => e.source.id);
+        const out: Record<string, ApiEndpoint[]> = {};
+        for (const src of schemas) out[src.id] = byId[src.id]?.endpoints ?? [];
+        return out;
+    }, [grouping, schemasData, schemas]);
+
     const handleTry = useCallback(
         (ep: ApiEndpoint) => {
             setSelectedEndpoint(ep);
@@ -61,18 +84,83 @@ export const DocsLayout: React.FC = () => {
         setSelectedEndpoint(null);
     }, [setSelectedEndpoint]);
 
-    const handleNavigate = useCallback((anchor: string) => {
-        docsRef.current?.scrollToAnchor(anchor);
+    const handleNavigate = useCallback(
+        (anchor: string, schemaId?: string | null) => {
+            // In selector mode a schema switch may be required before the
+            // anchor exists in the DOM — defer the scroll until the next
+            // paint so ``useOpenApiSchema`` has a chance to swap endpoints.
+            if (schemaId && schemaId !== currentSchema?.id && grouping === 'selector') {
+                setCurrentSchema(schemaId);
+                requestAnimationFrame(() => {
+                    docsRef.current?.scrollToAnchor(anchor);
+                });
+                return;
+            }
+            docsRef.current?.scrollToAnchor(anchor);
+        },
+        [currentSchema?.id, grouping, setCurrentSchema],
+    );
+
+    const handleActiveChange = useCallback((anchor: string | null, schemaId: string | null) => {
+        setActiveAnchor(anchor);
+        setActiveSchemaId(schemaId);
     }, []);
-    // Esc handling lives inside SidePanel itself — no duplicate listener.
+
+    // URL sync: read hash on mount / popstate → apply; write hash when
+    // scrollspy updates. Only the *effective* active schema goes into the
+    // hash — in ``selector`` mode it's the combobox value, in ``sections``
+    // mode it's whichever schema the scrollspy is currently inside.
+    const effectiveSchemaId = grouping === 'sections' ? activeSchemaId : currentSchema?.id ?? null;
+
+    const handleHashTarget = useCallback(
+        (target: ParsedHash) => {
+            if (!target.schemaId && !target.anchor) return;
+
+            // Schema-id segment may be either the raw id or a slug — match
+            // both so copy-pasted URLs survive id changes that don't affect
+            // the slug. First match wins.
+            const matched = target.schemaId
+                ? schemas.find((s) => s.id === target.schemaId || slugifySchemaId(s.id) === target.schemaId)
+                : null;
+
+            const needsSchemaSwitch =
+                matched && grouping === 'selector' && matched.id !== currentSchema?.id;
+
+            if (needsSchemaSwitch) {
+                setCurrentSchema(matched.id);
+            }
+
+            if (target.anchor) {
+                const anchor = target.anchor;
+                // Wait one frame when a switch happened so the new DOM exists.
+                if (needsSchemaSwitch) {
+                    requestAnimationFrame(() => {
+                        docsRef.current?.scrollToAnchor(anchor);
+                    });
+                } else {
+                    docsRef.current?.scrollToAnchor(anchor);
+                }
+            }
+        },
+        [schemas, grouping, currentSchema?.id, setCurrentSchema],
+    );
+
+    useDocsUrlSync({
+        enabled: urlSyncEnabled,
+        currentSchemaId: effectiveSchemaId,
+        activeAnchor,
+        onHashTarget: handleHashTarget,
+    });
+
+    // ─── Loading / error branches ─────────────────────────────────────────
 
     if (loading) {
         return (
-            <div
-                className="grid grid-cols-[260px_1fr] min-h-0 overflow-hidden"
-                style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
-            >
-                <div className="border-r p-3 space-y-1.5">
+            <div className="grid grid-cols-[260px_1fr] items-start">
+                <div
+                    className="sticky top-[var(--navbar-height,64px)] border-r p-3 space-y-1.5 overflow-y-auto"
+                    style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
+                >
                     {Array.from({ length: 12 }).map((_, i) => (
                         <Skeleton key={i} className="h-8 w-full rounded" />
                     ))}
@@ -105,58 +193,88 @@ export const DocsLayout: React.FC = () => {
         );
     }
 
-    // Mobile/tablet: sidebar + docs only, playground opens in sheet.
+    // ─── Mobile: sidebar + docs only, playground opens in sheet ───────────
+
     if (isMobile) {
         return (
-            <div
-                className="flex flex-col overflow-hidden"
-                style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
-            >
+            <div className="flex flex-col">
                 <EndpointDraftSync schemaId={currentSchema?.id ?? null} />
-                <DocsView
-                    ref={docsRef}
-                    info={schemaInfo}
-                    rawSchema={rawSchema}
-                    resolvedBaseUrl={resolvedBaseUrl}
-                    endpoints={endpoints}
-                    selectedVersion={state.selectedVersion}
-                    loadedEndpoint={state.selectedEndpoint}
-                    onTryEndpoint={handleTry}
-                    onActiveChange={setActiveAnchor}
-                />
+                {grouping === 'sections' ? (
+                    <DocsView
+                        ref={docsRef}
+                        grouping="sections"
+                        schemasData={schemasData}
+                        selectedVersion={state.selectedVersion}
+                        loadedEndpoint={state.selectedEndpoint}
+                        onTryEndpoint={handleTry}
+                        onActiveChange={handleActiveChange}
+                    />
+                ) : (
+                    <DocsView
+                        ref={docsRef}
+                        info={schemaInfo}
+                        rawSchema={rawSchema}
+                        resolvedBaseUrl={resolvedBaseUrl}
+                        endpoints={endpoints}
+                        selectedVersion={state.selectedVersion}
+                        loadedEndpoint={state.selectedEndpoint}
+                        onTryEndpoint={handleTry}
+                        onActiveChange={handleActiveChange}
+                    />
+                )}
                 <TryItSheet open={sheetOpen} onOpenChange={setSheetOpen} />
             </div>
         );
     }
 
+    // ─── Desktop ──────────────────────────────────────────────────────────
+
     return (
         <TooltipProvider delayDuration={350}>
-            <div
-                className="grid grid-cols-[260px_minmax(0,1fr)] min-h-0 overflow-hidden"
-                style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
-            >
+            <div className="grid grid-cols-[260px_minmax(0,1fr)] items-start">
                 <EndpointDraftSync schemaId={currentSchema?.id ?? null} />
-                <DocsSidebar
-                    info={schemaInfo}
-                    endpoints={endpoints}
-                    schemas={schemas}
-                    currentSchemaId={currentSchema?.id ?? null}
-                    onSchemaChange={setCurrentSchema}
-                    activeEndpointId={activeAnchor}
-                    selectedVersion={state.selectedVersion}
-                    onNavigate={handleNavigate}
-                />
-                <DocsView
-                    ref={docsRef}
-                    info={schemaInfo}
-                    rawSchema={rawSchema}
-                    resolvedBaseUrl={resolvedBaseUrl}
-                    endpoints={endpoints}
-                    selectedVersion={state.selectedVersion}
-                    loadedEndpoint={state.selectedEndpoint}
-                    onTryEndpoint={handleTry}
-                    onActiveChange={setActiveAnchor}
-                />
+                <div
+                    className="sticky top-[var(--navbar-height,64px)]"
+                    style={{ height: 'calc(100dvh - var(--navbar-height, 64px))' }}
+                >
+                    <DocsSidebar
+                        info={schemaInfo}
+                        endpoints={endpoints}
+                        schemas={schemas}
+                        currentSchemaId={currentSchema?.id ?? null}
+                        onSchemaChange={setCurrentSchema}
+                        activeEndpointId={activeAnchor}
+                        selectedVersion={state.selectedVersion}
+                        onNavigate={handleNavigate}
+                        grouping={grouping}
+                        endpointsBySchema={endpointsBySchema}
+                        rawSchema={rawSchema}
+                        resolvedBaseUrl={resolvedBaseUrl}
+                    />
+                </div>
+                {grouping === 'sections' ? (
+                    <DocsView
+                        ref={docsRef}
+                        grouping="sections"
+                        schemasData={schemasData}
+                        selectedVersion={state.selectedVersion}
+                        loadedEndpoint={state.selectedEndpoint}
+                        onTryEndpoint={handleTry}
+                        onActiveChange={handleActiveChange}
+                    />
+                ) : (
+                    <DocsView
+                        ref={docsRef}
+                        info={schemaInfo}
+                        rawSchema={rawSchema}
+                        resolvedBaseUrl={resolvedBaseUrl}
+                        endpoints={endpoints}
+                        selectedVersion={state.selectedVersion}
+                        loadedEndpoint={state.selectedEndpoint}
+                        onTryEndpoint={handleTry}
+                        onActiveChange={handleActiveChange}
+                    />
+                )}
                 {/* SidePanel renders into <body> via portal, so it floats
                     above the whole layout (sidebar + navbar included). */}
                 <SlideInPlayground open={slideOpen} onClose={handleCloseSlide} />

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 };
+}

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[];
+}