@djangocfg/ui-tools 2.1.289 → 2.1.290

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

@@ -0,0 +1,45 @@
+'use client';
+
+import { Search, X } from 'lucide-react';
+import React from 'react';
+
+import { Input } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+interface SearchInputProps {
+    value: string;
+    onChange: (v: string) => void;
+    placeholder?: string;
+}
+
+/** Search field with a leading icon and a trailing clear button. The
+ *  clear button only appears when there's something to clear so the
+ *  idle state reads as a single clean input rather than "icon + input
+ *  + mystery button". */
+export function SearchInput({ value, onChange, placeholder }: SearchInputProps) {
+    return (
+        <div className="relative">
+            <Search className="absolute left-2.5 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-muted-foreground/50 pointer-events-none" />
+            <Input
+                placeholder={placeholder ?? 'Search endpoints…'}
+                value={value}
+                onChange={(e: React.ChangeEvent<HTMLInputElement>) => onChange(e.target.value)}
+                className="pl-8 pr-7 h-8 text-xs"
+            />
+            {value && (
+                <button
+                    type="button"
+                    onClick={() => onChange('')}
+                    aria-label="Clear search"
+                    className={cn(
+                        'absolute right-1.5 top-1/2 -translate-y-1/2 h-5 w-5 rounded',
+                        'inline-flex items-center justify-center',
+                        'text-muted-foreground/50 hover:text-foreground hover:bg-muted transition-colors',
+                    )}
+                >
+                    <X className="h-3 w-3" />
+                </button>
+            )}
+        </div>
+    );
+}

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

@@ -0,0 +1,50 @@
+'use client';
+
+import { CategoryBlock } from './CategoryBlock';
+import { SchemaSection } from './SchemaSection';
+import type { NavigateFn, SidebarBodyVM } from './types';
+
+interface SidebarBodyProps {
+    body: SidebarBodyVM;
+    onNavigate: NavigateFn;
+}
+
+/** Scrollable body of the sidebar. Picks the rendering strategy based
+ *  on ``body.kind`` — flat category list for single-schema mode,
+ *  nested schema sections for multi-schema mode — and falls back to
+ *  a centred empty-state message when the filter pipeline yields no
+ *  rows. */
+export function SidebarBody({ body, onNavigate }: SidebarBodyProps) {
+    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-1.5">
+                {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-1.5">
+            {body.sections.map((section) => (
+                <SchemaSection key={section.sourceId} section={section} onNavigate={onNavigate} />
+            ))}
+        </nav>
+    );
+}

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/shared/ResponsePanel/PrettyView.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import JsonTree from '../../../../JsonTree';
+import PrettyCode from '../../../../PrettyCode';
+import type { DetectedContent } from './types';
+
+// JsonTree config — same shape as the interactive docs example view
+// but with ``showActionButtons: false`` because the copy button in the
+// StatusBar already covers that flow.
+const JSON_TREE_CONFIG = {
+    maxAutoExpandDepth: 2,
+    maxAutoExpandArrayItems: 10,
+    maxAutoExpandObjectKeys: 5,
+    maxStringLength: 200,
+    collectionLimit: 50,
+    showCollectionInfo: true,
+    showExpandControls: true,
+    showActionButtons: false,
+    preserveKeyOrder: true,
+    className: 'border-0 rounded-none',
+} as const;
+
+interface PrettyViewProps {
+    /** Parsed JSON tree when the body was JSON. */
+    treeData: unknown;
+    /** Pre-stringified body — used by the code-highlight branch for
+     *  non-JSON payloads. */
+    rawText: string;
+    detected: DetectedContent;
+}
+
+/** "Pretty" view — rich-rendering branch. JSON renders as ``JsonTree``;
+ *  anything else goes through ``PrettyCode`` in ``plain`` variant so it
+ *  flows naturally inside the panel's ``ScrollArea`` — no internal
+ *  scroll, no floating toolbar fighting the surrounding layout. */
+export function PrettyView({ treeData, rawText, detected }: PrettyViewProps) {
+    if (detected.kind === 'json' && treeData != null) {
+        return <JsonTree title="Response Body" data={treeData} config={JSON_TREE_CONFIG} />;
+    }
+    if (!rawText) {
+        return (
+            <div className="py-10 text-center text-xs text-muted-foreground">
+                Empty response body
+            </div>
+        );
+    }
+    return (
+        <PrettyCode
+            data={rawText}
+            language={detected.prism}
+            variant="plain"
+            isCompact
+        />
+    );
+}