@djangocfg/ui-tools 2.1.287 → 2.1.290

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

@@ -0,0 +1,64 @@
+'use client';
+
+import React from 'react';
+
+import { Combobox } from '@djangocfg/ui-core/components';
+
+import type { SchemaSource } from '../../../types';
+import { MethodChips } from './MethodChips';
+import { SearchInput } from './SearchInput';
+import type { MethodFilter } from './types';
+
+interface ToolbarProps {
+    schemas: SchemaSource[];
+    currentSchemaId: string | null;
+    onSchemaChange: (id: string) => void;
+    showSchemaSelector: boolean;
+
+    search: string;
+    onSearchChange: (v: string) => void;
+
+    methodFilter: MethodFilter;
+    onMethodFilterChange: (v: MethodFilter) => void;
+}
+
+/** Filter / control panel of the sidebar. Groups the schema selector,
+ *  search box, and HTTP method chips into a single visually cohesive
+ *  block so they read as "one toolbar" rather than three separate
+ *  affordances stacked on top of each other.
+ *
+ *  Each row is optional in the sense that we only render the schema
+ *  selector when there are multiple schemas to choose between. */
+export function Toolbar({
+    schemas,
+    currentSchemaId,
+    onSchemaChange,
+    showSchemaSelector,
+    search,
+    onSearchChange,
+    methodFilter,
+    onMethodFilterChange,
+}: ToolbarProps) {
+    const schemaOptions = React.useMemo(
+        () => schemas.map((s) => ({ value: s.id, label: s.name })),
+        [schemas],
+    );
+
+    return (
+        <div className="shrink-0 border-b px-3 py-2.5 space-y-2">
+            {showSchemaSelector && (
+                <Combobox
+                    options={schemaOptions}
+                    value={currentSchemaId ?? ''}
+                    onValueChange={(id) => id && onSchemaChange(id)}
+                    placeholder="Select API"
+                    searchPlaceholder="Search APIs…"
+                    emptyText="No APIs found"
+                    className="w-full h-8 text-xs"
+                />
+            )}
+            <SearchInput value={search} onChange={onSearchChange} />
+            <MethodChips value={methodFilter} onChange={onMethodFilterChange} />
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/Sidebar/buildVM.ts

@@ -0,0 +1,126 @@
+import type { ApiEndpoint, OpenApiSchema, SchemaSource } from '../../../types';
+import { deduplicateEndpoints } from '../../../utils/versionManager';
+import { endpointAnchor } from '../anchor';
+import { buildSchemaSections, groupEndpoints, type EndpointGroup } from '../grouping';
+import { sidebarLabel, sidebarTooltip } from '../sidebarLabel';
+import type {
+    CategoryVM,
+    EndpointRowVM,
+    MethodFilter,
+    SchemaSectionVM,
+    SidebarBodyVM,
+} from './types';
+
+// ``OpenApiSchema`` is imported to satisfy the build VM signatures even
+// though we never read it here — re-exported so consumers can reuse
+// the same type surface without another import.
+export type { OpenApiSchema };
+
+export 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,
+    };
+}
+
+function 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;
+}
+
+export 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'),
+    };
+}
+
+export 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'),
+    };
+}

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

@@ -0,0 +1,112 @@
+'use client';
+
+import React, { useMemo, useState } from 'react';
+
+import type { ApiEndpoint, OpenApiInfo, OpenApiSchema, SchemaSource } from '../../../types';
+import { ScrollArea } from '../../shared/ui';
+import { BrandHeader } from './BrandHeader';
+import { buildFlatVM, buildSectionsVM } from './buildVM';
+import { SidebarBody } from './SidebarBody';
+import { Toolbar } from './Toolbar';
+import type { MethodFilter, SidebarBodyVM } from './types';
+import { useDebouncedValue } from './useDebouncedValue';
+
+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, 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;
+}
+
+/** Docs sidebar orchestrator. Thin — each child folder owns its own
+ *  rendering; this file wires props, debounces search, and decides
+ *  which view-model builder to call. */
+export function DocsSidebar({
+    info,
+    endpoints,
+    schemas,
+    currentSchemaId,
+    onSchemaChange,
+    activeEndpointId,
+    selectedVersion,
+    onNavigate,
+    grouping = 'selector',
+    endpointsBySchema,
+    rawSchema,
+    resolvedBaseUrl,
+}: DocsSidebarProps) {
+    const [search, setSearch] = useState('');
+    const [methodFilter, setMethodFilter] = useState<MethodFilter>('ALL');
+    const debouncedSearch = useDebouncedValue(search);
+
+    const body = useMemo<SidebarBodyVM>(() => {
+        if (grouping === 'sections') {
+            return buildSectionsVM(
+                schemas,
+                endpointsBySchema ?? {},
+                selectedVersion,
+                debouncedSearch,
+                methodFilter,
+                activeEndpointId,
+            );
+        }
+        return buildFlatVM(
+            endpoints,
+            selectedVersion,
+            debouncedSearch,
+            methodFilter,
+            activeEndpointId,
+        );
+    }, [
+        grouping,
+        schemas,
+        endpointsBySchema,
+        endpoints,
+        selectedVersion,
+        debouncedSearch,
+        methodFilter,
+        activeEndpointId,
+    ]);
+
+    const hasMultipleSchemas = schemas.length > 1;
+    const showSchemaSelector = grouping === 'selector' && hasMultipleSchemas;
+
+    return (
+        <aside className="flex flex-col h-full min-h-0 border-r bg-muted/10">
+            <BrandHeader
+                info={info}
+                endpoints={endpoints}
+                rawSchema={rawSchema}
+                resolvedBaseUrl={resolvedBaseUrl}
+            />
+            <Toolbar
+                schemas={schemas}
+                currentSchemaId={currentSchemaId}
+                onSchemaChange={onSchemaChange}
+                showSchemaSelector={showSchemaSelector}
+                search={search}
+                onSearchChange={setSearch}
+                methodFilter={methodFilter}
+                onMethodFilterChange={setMethodFilter}
+            />
+            <ScrollArea>
+                <SidebarBody body={body} onNavigate={onNavigate} />
+            </ScrollArea>
+        </aside>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/Sidebar/types.ts

@@ -0,0 +1,42 @@
+import type { ApiEndpoint } from '../../../types';
+
+/** HTTP method filter. ``ALL`` is a sentinel for no filter — using a
+ *  string union (rather than ``string | null``) keeps the filter chips
+ *  and reducer logic type-safe without null juggling. */
+export const METHOD_FILTERS = ['ALL', 'GET', 'POST', 'PUT', 'PATCH', 'DELETE'] as const;
+export type MethodFilter = (typeof METHOD_FILTERS)[number];
+
+export 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 so the tech string is readable against a sea of prose. */
+    useMono: boolean;
+    isActive: boolean;
+}
+
+export interface CategoryVM {
+    key: string;
+    category: string;
+    rows: EndpointRowVM[];
+}
+
+export interface SchemaSectionVM {
+    sourceId: string;
+    sourceName: string;
+    categories: CategoryVM[];
+}
+
+export type SidebarBodyVM =
+    | { kind: 'flat'; categories: CategoryVM[]; emptyText: string }
+    | { kind: 'sections'; sections: SchemaSectionVM[]; emptyText: string };
+
+export type NavigateFn = (anchor: string, schemaId?: string | null) => void;
+
+// Re-exported here so downstream files don't all re-import from the
+// outer ``types`` module for every component prop.
+export type { ApiEndpoint };

package/src/tools/OpenapiViewer/components/DocsLayout/Sidebar/useDebouncedValue.ts

@@ -0,0 +1,14 @@
+import { useEffect, useState } from 'react';
+
+/** Debounce a fast-changing value. Used for the sidebar search box so
+ *  each keystroke doesn't re-run the filter pipeline (endpoint list
+ *  can be hundreds of items long in some specs). 120ms is short
+ *  enough to feel instant while still batching rapid typing. */
+export function useDebouncedValue<T>(value: T, delayMs = 120): T {
+    const [debounced, setDebounced] = useState(value);
+    useEffect(() => {
+        const id = setTimeout(() => setDebounced(value), delayMs);
+        return () => clearTimeout(id);
+    }, [value, delayMs]);
+    return debounced;
+}

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

@@ -71,7 +71,11 @@ export function SlideInPlayground({ open, onClose }: SlideInPlaygroundProps) {
 
                 {/* Body: 1 or 2 columns depending on whether we have a
                     response to show. ``divide-x`` gives a 1px seam
-                    between the panes so they read as distinct surfaces. */}
+                    between the panes so they read as distinct surfaces.
+                    Send button lives inside the Request column so it
+                    reads as an action on the form it belongs to — not
+                    as a page-level footer that ambiguously sat under
+                    the response column too. */}
                 <SidePanel.Body
                     className={cn(
                         'overflow-hidden grid divide-x transition-[grid-template-columns] duration-250',
@@ -82,6 +86,11 @@ export function SlideInPlayground({ open, onClose }: SlideInPlaygroundProps) {
                 >
                     <Panel>
                         <RequestPanel />
+                        {ep && (
+                            <div className="shrink-0 border-t px-4 py-3 bg-background">
+                                <SendButton />
+                            </div>
+                        )}
                     </Panel>
                     {showResponse && (
                         <Panel>
@@ -89,12 +98,6 @@ export function SlideInPlayground({ open, onClose }: SlideInPlaygroundProps) {
                         </Panel>
                     )}
                 </SidePanel.Body>
-
-                {ep && (
-                    <SidePanel.Footer className="px-4 py-3">
-                        <SendButton />
-                    </SidePanel.Footer>
-                )}
             </SidePanel.Content>
         </SidePanel>
     );

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

@@ -36,9 +36,17 @@ export function TryItSheet({ open, onOpenChange }: TryItSheetProps) {
                 <ResponsiveSheetHeader className="px-4 py-3 border-b shrink-0">
                     <ResponsiveSheetTitle className="text-sm">Playground</ResponsiveSheetTitle>
                 </ResponsiveSheetHeader>
+                {/* Send button sits inside the Request section so it
+                    reads as an action on the form, not an ambiguous
+                    page-level footer when Response is also visible. */}
                 <div className="flex-1 min-h-0 flex flex-col divide-y">
-                    <div className={showResponse ? 'flex-1 min-h-0 flex flex-col' : 'flex-1 min-h-0 flex flex-col'}>
+                    <div className="flex-1 min-h-0 flex flex-col">
                         <RequestPanel />
+                        {state.selectedEndpoint && (
+                            <div className="shrink-0 border-t px-4 py-3 bg-background">
+                                <SendButton />
+                            </div>
+                        )}
                     </div>
                     {showResponse && (
                         <div className="flex-1 min-h-0 flex flex-col">
@@ -46,11 +54,6 @@ export function TryItSheet({ open, onOpenChange }: TryItSheetProps) {
                         </div>
                     )}
                 </div>
-                {state.selectedEndpoint && (
-                    <div className="shrink-0 border-t px-4 py-3 bg-background/95 backdrop-blur-sm">
-                        <SendButton />
-                    </div>
-                )}
             </ResponsiveSheetContent>
         </ResponsiveSheet>
     );

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