@djangocfg/ui-tools 2.1.287 → 2.1.289

package/src/tools/OpenapiViewer/components/DocsLayout/grouping.ts

@@ -7,7 +7,9 @@
  * This module is the single source of truth for that ordering.
  */
 
-import type { ApiEndpoint } from '../../types';
+import { groupBy, orderBy, partition, sortBy } from 'lodash-es';
+
+import type { ApiEndpoint, SchemaSource } from '../../types';
 import { longestCommonPrefix } from './sidebarLabel';
 
 export type EndpointGroup = {
@@ -19,6 +21,13 @@ export type EndpointGroup = {
     commonPrefix: string;
 };
 
+/** A schema's worth of categorised endpoints. The outer level of the
+ *  ``sections`` sidebar iterates over these. */
+export type SchemaSection = {
+    source: SchemaSource;
+    groups: EndpointGroup[];
+};
+
 const METHOD_ORDER: Record<string, number> = {
     GET: 0,
     POST: 1,
@@ -27,6 +36,8 @@ const METHOD_ORDER: Record<string, number> = {
     DELETE: 4,
 };
 
+const methodRank = (ep: ApiEndpoint) => METHOD_ORDER[ep.method] ?? 99;
+
 /**
  * Stable, deterministic ordering so two different renders with the
  * same endpoint list always produce the same visual sequence.
@@ -38,29 +49,15 @@ const METHOD_ORDER: Record<string, number> = {
  * cluster), then by HTTP method (read → write → delete).
  */
 export function groupEndpoints(list: ApiEndpoint[]): EndpointGroup[] {
-    const map = new Map<string, ApiEndpoint[]>();
-    for (const ep of list) {
-        const arr = map.get(ep.category) ?? [];
-        arr.push(ep);
-        map.set(ep.category, arr);
-    }
-
-    const groups: EndpointGroup[] = Array.from(map.entries()).map(([category, endpoints]) => ({
+    const byCategory = groupBy(list, 'category');
+    const all: EndpointGroup[] = Object.entries(byCategory).map(([category, endpoints]) => ({
         category,
-        endpoints: [...endpoints].sort((a, b) => {
-            const byPath = a.path.localeCompare(b.path);
-            if (byPath !== 0) return byPath;
-            return (METHOD_ORDER[a.method] ?? 99) - (METHOD_ORDER[b.method] ?? 99);
-        }),
+        endpoints: orderBy(endpoints, ['path', methodRank], ['asc', 'asc']),
         commonPrefix: longestCommonPrefix(endpoints.map((e) => e.path)),
     }));
-
-    groups.sort((a, b) => {
-        if (a.category === 'Other') return 1;
-        if (b.category === 'Other') return -1;
-        return a.category.localeCompare(b.category);
-    });
-    return groups;
+    // "Other" sinks to the bottom regardless of alphabet.
+    const [other, named] = partition(all, (g) => g.category === 'Other');
+    return [...sortBy(named, (g) => g.category.toLowerCase()), ...other];
 }
 
 /** Flatten grouped endpoints back into a linear list that preserves
@@ -69,3 +66,23 @@ export function groupEndpoints(list: ApiEndpoint[]): EndpointGroup[] {
 export function flattenGrouped(groups: EndpointGroup[]): ApiEndpoint[] {
     return groups.flatMap((g) => g.endpoints);
 }
+
+/** Build per-schema sections in the same order as the original
+ *  ``schemas`` array. Schemas with zero endpoints are kept so users see
+ *  an empty-state placeholder instead of "the section silently vanished". */
+export function buildSchemaSections(
+    sources: SchemaSource[],
+    endpointsBySchema: Record<string, ApiEndpoint[]>,
+): SchemaSection[] {
+    return sources.map((source) => ({
+        source,
+        groups: groupEndpoints(endpointsBySchema[source.id] ?? []),
+    }));
+}
+
+/** Flatten schema-sections into a linear endpoint list. Used by scrollspy
+ *  and by the docs longread to render endpoints in the exact same order
+ *  as the sidebar. */
+export function flattenSchemaSections(sections: SchemaSection[]): ApiEndpoint[] {
+    return sections.flatMap((s) => flattenGrouped(s.groups));
+}

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