@djangocfg/ui-tools 2.1.286 → 2.1.289

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

@@ -12,60 +12,176 @@ import {
 } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
-import type { ApiEndpoint, OpenApiInfo, SchemaSource } from '../../types';
+import type { ApiEndpoint, OpenApiInfo, OpenApiSchema, SchemaSource } from '../../types';
 import { deduplicateEndpoints } from '../../utils/versionManager';
 import { MethodBadge, ScrollArea } from '../shared/ui';
 import { endpointAnchor } from './anchor';
-import { longestCommonPrefix, sidebarLabel, sidebarTooltip } from './sidebarLabel';
+import { buildSchemaSections, groupEndpoints, type EndpointGroup } from './grouping';
+import { SchemaCopyMenu } from './SchemaCopyMenu';
+import { sidebarLabel, sidebarTooltip } from './sidebarLabel';
 
-type Group = {
-    category: string;
-    endpoints: ApiEndpoint[];
-    /** Longest ``/``-aligned prefix shared by every endpoint in this group.
-     *  Stripped from labels that fall back to showing the path. */
-    commonPrefix: string;
-};
-
-const METHOD_ORDER: Record<string, number> = {
-    GET: 0, POST: 1, PUT: 2, PATCH: 3, DELETE: 4,
-};
-
-function groupEndpoints(list: ApiEndpoint[]): Group[] {
-    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: Group[] = Array.from(map.entries()).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);
-        }),
-        commonPrefix: longestCommonPrefix(endpoints.map((e) => e.path)),
-    }));
-    // Alphabetical, but "Other" sinks to the bottom.
-    groups.sort((a, b) => {
-        if (a.category === 'Other') return 1;
-        if (b.category === 'Other') return -1;
-        return a.category.localeCompare(b.category);
-    });
-    return groups;
-}
+// ─── Public props ────────────────────────────────────────────────────────────
 
 export interface DocsSidebarProps {
     info: OpenApiInfo | null;
+    /** Active-schema endpoints — used by ``selector`` mode. */
     endpoints: ApiEndpoint[];
+    /** All configured schemas (used by both modes). */
     schemas: SchemaSource[];
     currentSchemaId: string | null;
     onSchemaChange: (id: string) => void;
     activeEndpointId: string | null;
     selectedVersion: string;
-    onNavigate: (anchor: string) => void;
+    onNavigate: (anchor: string, schemaId?: string | null) => void;
+    /** Presentation mode. Default: ``selector`` (back-compat). */
+    grouping?: 'selector' | 'sections';
+    /** Required for ``sections`` mode — endpoints grouped by their source
+     *  schema id. The sidebar renders them as two-level sections. */
+    endpointsBySchema?: Record<string, ApiEndpoint[]>;
+    /** Raw active schema + resolved base URL — used by the Copy-for-AI
+     *  dropdown in the brand row. ``null`` disables the button. */
+    rawSchema?: OpenApiSchema | null;
+    resolvedBaseUrl?: string;
+}
+
+/** HTTP methods the sidebar can filter by. Reordered like the docs
+ *  themselves: read, then write. ``ALL`` is a sentinel for no filter. */
+const METHOD_FILTERS = ['ALL', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const;
+type MethodFilter = (typeof METHOD_FILTERS)[number];
+
+// ─── View-model types ────────────────────────────────────────────────────────
+
+interface EndpointRowVM {
+    key: string;
+    anchor: string;
+    schemaId: string | null;
+    label: string;
+    tooltip: string;
+    method: string;
+    /** Summary-less endpoints get a monospace font for the path-tail label. */
+    useMono: boolean;
+    isActive: boolean;
+}
+
+interface CategoryVM {
+    key: string;
+    category: string;
+    rows: EndpointRowVM[];
+}
+
+interface SchemaSectionVM {
+    sourceId: string;
+    sourceName: string;
+    categories: CategoryVM[];
+}
+
+type SidebarBodyVM =
+    | { kind: 'flat'; categories: CategoryVM[]; emptyText: string }
+    | { kind: 'sections'; sections: SchemaSectionVM[]; emptyText: string };
+
+// ─── Pure builders ───────────────────────────────────────────────────────────
+
+function filterEndpoints(
+    list: ApiEndpoint[],
+    query: string,
+    method: MethodFilter,
+): ApiEndpoint[] {
+    let out = list;
+    if (method !== 'ALL') {
+        out = out.filter((e) => e.method === method);
+    }
+    if (query) {
+        const q = query.toLowerCase();
+        out = out.filter(
+            (e) =>
+                e.summary.toLowerCase().includes(q) ||
+                e.name.toLowerCase().includes(q) ||
+                e.description.toLowerCase().includes(q) ||
+                e.path.toLowerCase().includes(q),
+        );
+    }
+    return out;
+}
+
+function buildCategory(
+    group: EndpointGroup,
+    activeEndpointId: string | null,
+    schemaId: string | null,
+    keyPrefix: string,
+): CategoryVM {
+    const rows: EndpointRowVM[] = group.endpoints.map((ep) => {
+        const anchor = endpointAnchor(ep, schemaId ?? ep.schemaId ?? null);
+        return {
+            key: `${ep.method}-${ep.path}`,
+            anchor,
+            schemaId: schemaId ?? ep.schemaId ?? null,
+            label: sidebarLabel(ep, group.commonPrefix),
+            tooltip: sidebarTooltip(ep),
+            method: ep.method,
+            useMono: !ep.summary,
+            isActive: activeEndpointId === anchor,
+        };
+    });
+    return {
+        key: `${keyPrefix}${group.category}`,
+        category: group.category,
+        rows,
+    };
+}
+
+const emptyTextFor = (query: string, method: MethodFilter, defaultText: string): string => {
+    if (query && method !== 'ALL') return `No ${method} endpoints match "${query}"`;
+    if (query) return `No endpoints match "${query}"`;
+    if (method !== 'ALL') return `No ${method} endpoints`;
+    return defaultText;
+};
+
+function buildFlatVM(
+    endpoints: ApiEndpoint[],
+    selectedVersion: string,
+    query: string,
+    method: MethodFilter,
+    activeEndpointId: string | null,
+): SidebarBodyVM {
+    const filtered = filterEndpoints(deduplicateEndpoints(endpoints, selectedVersion), query, method);
+    const groups = groupEndpoints(filtered);
+    return {
+        kind: 'flat',
+        categories: groups.map((g) => buildCategory(g, activeEndpointId, null, '')),
+        emptyText: emptyTextFor(query, method, 'No endpoints in this schema'),
+    };
 }
 
+function buildSectionsVM(
+    schemas: SchemaSource[],
+    endpointsBySchema: Record<string, ApiEndpoint[]>,
+    selectedVersion: string,
+    query: string,
+    method: MethodFilter,
+    activeEndpointId: string | null,
+): SidebarBodyVM {
+    const filteredMap: Record<string, ApiEndpoint[]> = {};
+    for (const src of schemas) {
+        const raw = endpointsBySchema[src.id] ?? [];
+        filteredMap[src.id] = filterEndpoints(deduplicateEndpoints(raw, selectedVersion), query, method);
+    }
+    const rawSections = buildSchemaSections(schemas, filteredMap);
+    const sections: SchemaSectionVM[] = rawSections
+        .filter((s) => s.groups.length > 0)
+        .map((s) => ({
+            sourceId: s.source.id,
+            sourceName: s.source.name,
+            categories: s.groups.map((g) => buildCategory(g, activeEndpointId, s.source.id, `${s.source.id}-`)),
+        }));
+    return {
+        kind: 'sections',
+        sections,
+        emptyText: emptyTextFor(query, method, 'No endpoints in any schema'),
+    };
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
 export function DocsSidebar({
     info,
     endpoints,
@@ -75,28 +191,42 @@ export function DocsSidebar({
     activeEndpointId,
     selectedVersion,
     onNavigate,
+    grouping = 'selector',
+    endpointsBySchema,
+    rawSchema,
+    resolvedBaseUrl,
 }: DocsSidebarProps) {
     const [search, setSearch] = useState('');
     const [debounced, setDebounced] = useState('');
+    const [methodFilter, setMethodFilter] = useState<MethodFilter>('ALL');
 
     useEffect(() => {
         const id = setTimeout(() => setDebounced(search), 120);
         return () => clearTimeout(id);
     }, [search]);
 
-    const filteredGroups = useMemo(() => {
-        let list = deduplicateEndpoints(endpoints, selectedVersion);
-        if (debounced) {
-            const q = debounced.toLowerCase();
-            list = list.filter((e) =>
-                e.summary.toLowerCase().includes(q) ||
-                e.name.toLowerCase().includes(q) ||
-                e.description.toLowerCase().includes(q) ||
-                e.path.toLowerCase().includes(q),
+    const body = useMemo<SidebarBodyVM>(() => {
+        if (grouping === 'sections') {
+            return buildSectionsVM(
+                schemas,
+                endpointsBySchema ?? {},
+                selectedVersion,
+                debounced,
+                methodFilter,
+                activeEndpointId,
             );
         }
-        return groupEndpoints(list);
-    }, [endpoints, debounced, selectedVersion]);
+        return buildFlatVM(endpoints, selectedVersion, debounced, methodFilter, activeEndpointId);
+    }, [
+        grouping,
+        schemas,
+        endpointsBySchema,
+        endpoints,
+        selectedVersion,
+        debounced,
+        methodFilter,
+        activeEndpointId,
+    ]);
 
     const schemaOptions = useMemo(
         () => schemas.map((s) => ({ value: s.id, label: s.name })),
@@ -104,24 +234,36 @@ export function DocsSidebar({
     );
     const hasMultipleSchemas = schemas.length > 1;
     const apiTitle = info?.title ?? 'API Reference';
+    const showCombobox = grouping === 'selector' && hasMultipleSchemas;
+    const copyReady = rawSchema !== null && rawSchema !== undefined && endpoints.length > 0;
 
     return (
-        <aside className="flex flex-col min-h-0 border-r bg-muted/10">
+        <aside className="flex flex-col h-full min-h-0 border-r bg-muted/10">
             {/* Brand row */}
-            <div className="shrink-0 border-b px-4 h-12 flex items-center gap-2">
-                <span className="text-[13px] font-semibold text-foreground truncate">
-                    {apiTitle}
-                </span>
-                {info?.version && (
-                    <span className="font-mono text-[10px] text-muted-foreground/70 shrink-0">
-                        v{info.version}
+            <div className="shrink-0 border-b px-3 h-12 flex items-center gap-2">
+                <div className="flex items-center gap-2 flex-1 min-w-0">
+                    <span className="text-[13px] font-semibold text-foreground truncate">
+                        {apiTitle}
                     </span>
+                    {info?.version && (
+                        <span className="font-mono text-[10px] text-muted-foreground/70 shrink-0">
+                            v{info.version}
+                        </span>
+                    )}
+                </div>
+                {copyReady && (
+                    <SchemaCopyMenu
+                        schema={rawSchema ?? null}
+                        endpoints={endpoints}
+                        baseUrl={resolvedBaseUrl}
+                        variant="icon"
+                    />
                 )}
             </div>
 
             {/* Controls */}
             <div className="shrink-0 border-b px-3 py-3 space-y-2">
-                {hasMultipleSchemas && (
+                {showCombobox && (
                     <Combobox
                         options={schemaOptions}
                         value={currentSchemaId ?? ''}
@@ -141,71 +283,157 @@ export function DocsSidebar({
                         className="pl-8 h-8 text-xs"
                     />
                 </div>
+                <MethodChips value={methodFilter} onChange={setMethodFilter} />
             </div>
 
             <ScrollArea>
-                {filteredGroups.length === 0 ? (
-                    <div className="py-10 px-4 text-center text-xs text-muted-foreground">
-                        {debounced
-                            ? `No endpoints match "${debounced}"`
-                            : 'No endpoints in this schema'}
-                    </div>
-                ) : (
-                    <nav className="py-2">
-                        {filteredGroups.map((group) => (
-                            <div key={group.category} className="mb-4 last:mb-2">
-                                <div className="px-4 py-1.5 text-[10px] font-semibold uppercase tracking-[0.14em] text-muted-foreground/50 select-none">
-                                    {group.category}
-                                </div>
-                                <div>
-                                    {group.endpoints.map((ep) => {
-                                        const anchor = endpointAnchor(ep);
-                                        const isActive = activeEndpointId === anchor;
-                                        const label = sidebarLabel(ep, group.commonPrefix);
-                                        const tooltip = sidebarTooltip(ep);
-                                        // Summary → sans-serif (reads like an outline).
-                                        // Path-tail fallback → mono (reads like code).
-                                        const useMono = !ep.summary;
-                                        return (
-                                            <Tooltip key={`${ep.method}-${ep.path}`} delayDuration={350}>
-                                                <TooltipTrigger asChild>
-                                                    <button
-                                                        onClick={() => onNavigate(anchor)}
-                                                        aria-current={isActive ? 'location' : undefined}
-                                                        className={cn(
-                                                            'relative group w-full text-left flex items-center gap-2 pl-4 pr-3 py-1.5 transition-colors',
-                                                            isActive
-                                                                ? 'bg-primary/10 text-foreground'
-                                                                : 'hover:bg-muted/40 text-foreground/75 hover:text-foreground',
-                                                        )}
-                                                    >
-                                                        {isActive && (
-                                                            <span className="absolute left-0 top-1 bottom-1 w-0.5 rounded-r bg-primary" />
-                                                        )}
-                                                        <MethodBadge method={ep.method} />
-                                                        <span
-                                                            className={cn(
-                                                                'truncate leading-tight flex-1 min-w-0',
-                                                                useMono ? 'font-mono text-[11px]' : 'text-[12px]',
-                                                                isActive && 'text-foreground font-medium',
-                                                            )}
-                                                        >
-                                                            {label}
-                                                        </span>
-                                                    </button>
-                                                </TooltipTrigger>
-                                                <TooltipContent side="right" align="center" className="font-mono text-[11px]">
-                                                    {tooltip}
-                                                </TooltipContent>
-                                            </Tooltip>
-                                        );
-                                    })}
-                                </div>
-                            </div>
-                        ))}
-                    </nav>
-                )}
+                <SidebarBody body={body} onNavigate={onNavigate} />
             </ScrollArea>
         </aside>
     );
 }
+
+function MethodChips({
+    value,
+    onChange,
+}: {
+    value: MethodFilter;
+    onChange: (v: MethodFilter) => void;
+}) {
+    return (
+        <div className="flex items-center gap-1 flex-wrap">
+            {METHOD_FILTERS.map((m) => {
+                const active = value === m;
+                return (
+                    <button
+                        key={m}
+                        type="button"
+                        onClick={() => onChange(m)}
+                        aria-pressed={active}
+                        className={cn(
+                            'px-2 py-0.5 rounded font-mono text-[10px] font-semibold tracking-wide transition-colors border',
+                            active
+                                ? 'bg-primary/15 border-primary/40 text-foreground'
+                                : 'bg-transparent border-border/40 text-muted-foreground hover:text-foreground hover:border-border',
+                        )}
+                    >
+                        {m}
+                    </button>
+                );
+            })}
+        </div>
+    );
+}
+
+// ─── Rendering primitives ────────────────────────────────────────────────────
+
+type NavigateFn = (anchor: string, schemaId?: string | null) => void;
+
+function SidebarBody({ body, onNavigate }: { body: SidebarBodyVM; onNavigate: NavigateFn }) {
+    if (body.kind === 'flat') {
+        if (body.categories.length === 0) {
+            return (
+                <div className="py-10 px-4 text-center text-xs text-muted-foreground">
+                    {body.emptyText}
+                </div>
+            );
+        }
+        return (
+            <nav className="py-2">
+                {body.categories.map((cat) => (
+                    <CategoryBlock key={cat.key} category={cat} onNavigate={onNavigate} />
+                ))}
+            </nav>
+        );
+    }
+
+    if (body.sections.length === 0) {
+        return (
+            <div className="py-10 px-4 text-center text-xs text-muted-foreground">
+                {body.emptyText}
+            </div>
+        );
+    }
+
+    return (
+        <nav className="py-2">
+            {body.sections.map((section) => (
+                <div key={section.sourceId} className="mb-5 last:mb-2">
+                    <div className="px-4 py-2 sticky top-0 z-[1] bg-muted/30 backdrop-blur-[2px] border-b border-border/30">
+                        <span className="text-[11px] font-bold uppercase tracking-[0.12em] text-foreground/80">
+                            {section.sourceName}
+                        </span>
+                    </div>
+                    {section.categories.map((cat) => (
+                        <CategoryBlock key={cat.key} category={cat} onNavigate={onNavigate} />
+                    ))}
+                </div>
+            ))}
+        </nav>
+    );
+}
+
+const CategoryBlock = React.memo(function CategoryBlock({
+    category,
+    onNavigate,
+}: {
+    category: CategoryVM;
+    onNavigate: NavigateFn;
+}) {
+    return (
+        <div className="mb-4 last:mb-2">
+            <div className="px-4 py-1.5 text-[10px] font-semibold uppercase tracking-[0.14em] text-muted-foreground/50 select-none">
+                {category.category}
+            </div>
+            <div>
+                {category.rows.map((row) => (
+                    <EndpointRow key={row.key} row={row} onNavigate={onNavigate} />
+                ))}
+            </div>
+        </div>
+    );
+});
+
+const EndpointRow = React.memo(function EndpointRow({
+    row,
+    onNavigate,
+}: {
+    row: EndpointRowVM;
+    onNavigate: NavigateFn;
+}) {
+    return (
+        <Tooltip delayDuration={350}>
+            <TooltipTrigger asChild>
+                <button
+                    onClick={() => onNavigate(row.anchor, row.schemaId)}
+                    aria-current={row.isActive ? 'location' : undefined}
+                    className={cn(
+                        'relative group w-full text-left flex items-start gap-2 pl-4 pr-3 py-1.5 transition-colors',
+                        row.isActive
+                            ? 'bg-primary/10 text-foreground'
+                            : 'hover:bg-muted/40 text-foreground/75 hover:text-foreground',
+                    )}
+                >
+                    {row.isActive && (
+                        <span className="absolute left-0 top-1 bottom-1 w-0.5 rounded-r bg-primary" />
+                    )}
+                    <span className="shrink-0 mt-[1px]">
+                        <MethodBadge method={row.method} />
+                    </span>
+                    <span
+                        className={cn(
+                            'line-clamp-2 leading-snug flex-1 min-w-0',
+                            row.useMono ? 'font-mono text-[11px] break-all' : 'text-[12px]',
+                            row.isActive && 'text-foreground font-medium',
+                        )}
+                    >
+                        {row.label}
+                    </span>
+                </button>
+            </TooltipTrigger>
+            <TooltipContent side="right" align="center" className="font-mono text-[11px]">
+                {row.tooltip}
+            </TooltipContent>
+        </Tooltip>
+    );
+});

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

@@ -1,11 +1,28 @@
 import type { ApiEndpoint } from '../../types';
 
-export function endpointAnchor(ep: Pick<ApiEndpoint, 'method' | 'path'>): string {
+/** DOM-safe anchor for a single endpoint.
+ *
+ *  Two forms:
+ *  - Scoped (``schemaId`` provided) — ``ep-<schema>-<method>-<slug>``.
+ *    Used in ``sections`` mode where endpoints from different schemas
+ *    coexist on one page and would otherwise collide.
+ *  - Flat — ``ep-<method>-<slug>``. Used in ``selector`` mode where
+ *    only one schema is mounted at a time. */
+export function endpointAnchor(
+  ep: Pick<ApiEndpoint, 'method' | 'path'>,
+  schemaId?: string | null,
+): string {
   const slug = ep.path
     .replace(/^https?:\/\/[^/]+/, '')
     .replace(/[{}]/g, '')
     .replace(/[^a-zA-Z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .toLowerCase();
-  return `ep-${ep.method.toLowerCase()}-${slug}`;
+  const schemaSlug = schemaId ? `${slugifySchemaId(schemaId)}-` : '';
+  return `ep-${schemaSlug}${ep.method.toLowerCase()}-${slug}`;
+}
+
+/** Canonical slug for a schema id — safe for anchors and hash fragments. */
+export function slugifySchemaId(id: string): string {
+  return id.replace(/[^a-zA-Z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
 }

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