@djangocfg/ui-tools 2.1.287 → 2.1.290

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/store/index.ts

@@ -0,0 +1,133 @@
+'use client';
+
+import { create } from 'zustand';
+import { persist, createJSONStorage } from 'zustand/middleware';
+
+import type { CodeSampleTargetId } from '../../../../utils/codeSamples';
+import type { SectionId } from '../types';
+
+/** Composite key so the same section id (``responses``) can have
+ *  distinct state per endpoint on the page. We don't use Map because
+ *  zustand+persist serialises state to JSON and Map survival there
+ *  requires extra replacer/reviver boilerplate for no real gain. */
+export const sectionKey = (endpointId: string, sectionId: SectionId): string =>
+    `${endpointId}:${sectionId}`;
+
+export interface EndpointDocState {
+    /** ``${endpointId}:${sectionId}`` → open? — ``undefined`` means
+     *  "use the component's ``defaultOpen``"; the store only stores
+     *  user-driven overrides so defaults can change later without
+     *  stale persisted state overriding them. */
+    openSections: Record<string, boolean>;
+    /** Active code-sample tab per endpoint. Keyed on endpoint id only;
+     *  users tend to pick one language and stick with it across the
+     *  whole page, so sharing between endpoints is acceptable UX. */
+    activeCodeTab: Record<string, CodeSampleTargetId>;
+}
+
+export interface EndpointDocActions {
+    toggleSection: (endpointId: string, sectionId: SectionId) => void;
+    setSectionOpen: (endpointId: string, sectionId: SectionId, open: boolean) => void;
+    setCodeTab: (endpointId: string, tab: CodeSampleTargetId) => void;
+    /** Bulk ops — "expand all" / "collapse all" on a single endpoint.
+     *  The component calls these from an action button in the header. */
+    expandAll: (endpointId: string, sectionIds: readonly SectionId[]) => void;
+    collapseAll: (endpointId: string, sectionIds: readonly SectionId[]) => void;
+}
+
+export type EndpointDocStore = EndpointDocState & EndpointDocActions;
+
+const initialState: EndpointDocState = {
+    openSections: {},
+    activeCodeTab: {},
+};
+
+/** Zustand store with sessionStorage persistence. Using sessionStorage
+ *  (not localStorage) so closing the tab clears state — the viewer is
+ *  often embedded in a dashboard and persisting forever would surprise
+ *  users who switched schemas. */
+export const useEndpointDocStore = create<EndpointDocStore>()(
+    persist(
+        (set) => ({
+            ...initialState,
+
+            toggleSection: (endpointId, sectionId) =>
+                set((state) => {
+                    const key = sectionKey(endpointId, sectionId);
+                    const current = state.openSections[key];
+                    return {
+                        openSections: {
+                            ...state.openSections,
+                            // If there's no explicit override yet, the user's
+                            // first click means "flip from the default". We
+                            // assume the default was ``true`` for the most
+                            // common case (bodies/responses) and ``false``
+                            // otherwise; the Section component tracks this
+                            // via its ``defaultOpen`` prop and never calls
+                            // toggle on sections whose defaults match the
+                            // next state.
+                            [key]: current === undefined ? false : !current,
+                        },
+                    };
+                }),
+
+            setSectionOpen: (endpointId, sectionId, open) =>
+                set((state) => ({
+                    openSections: {
+                        ...state.openSections,
+                        [sectionKey(endpointId, sectionId)]: open,
+                    },
+                })),
+
+            setCodeTab: (endpointId, tab) =>
+                set((state) => ({
+                    activeCodeTab: {
+                        ...state.activeCodeTab,
+                        [endpointId]: tab,
+                    },
+                })),
+
+            expandAll: (endpointId, sectionIds) =>
+                set((state) => {
+                    const next = { ...state.openSections };
+                    for (const sid of sectionIds) {
+                        next[sectionKey(endpointId, sid)] = true;
+                    }
+                    return { openSections: next };
+                }),
+
+            collapseAll: (endpointId, sectionIds) =>
+                set((state) => {
+                    const next = { ...state.openSections };
+                    for (const sid of sectionIds) {
+                        next[sectionKey(endpointId, sid)] = false;
+                    }
+                    return { openSections: next };
+                }),
+        }),
+        {
+            name: 'openapi-viewer:endpoint-doc',
+            storage: createJSONStorage(() => {
+                // Guard for SSR / non-browser environments — zustand's
+                // persist middleware calls storage.getItem synchronously
+                // during hydration, and ``sessionStorage`` is undefined
+                // there. Returning a noop keeps SSR snapshots stable.
+                if (typeof window === 'undefined') {
+                    return {
+                        getItem: () => null,
+                        setItem: () => {},
+                        removeItem: () => {},
+                    };
+                }
+                return window.sessionStorage;
+            }),
+            // Only persist user overrides, not the functions. Zustand
+            // serialises everything by default and logs a warning on
+            // non-serialisable values; partialize keeps the payload lean.
+            partialize: (state) => ({
+                openSections: state.openSections,
+                activeCodeTab: state.activeCodeTab,
+            }),
+        },
+    ),
+);

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/store/selectors.ts

@@ -0,0 +1,40 @@
+'use client';
+
+import type { CodeSampleTargetId } from '../../../../utils/codeSamples';
+import type { SectionId } from '../types';
+import { sectionKey, useEndpointDocStore } from './index';
+
+/** Read whether a section is open, falling back to ``defaultOpen`` when
+ *  the user hasn't explicitly toggled it. Returning a raw boolean makes
+ *  the caller's conditional rendering trivial. */
+export function useIsSectionOpen(
+    endpointId: string,
+    sectionId: SectionId,
+    defaultOpen: boolean,
+): boolean {
+    return useEndpointDocStore((s) => {
+        const explicit = s.openSections[sectionKey(endpointId, sectionId)];
+        return explicit === undefined ? defaultOpen : explicit;
+    });
+}
+
+/** Read the active code-sample tab for this endpoint, falling back to
+ *  a shared default (``curl``). Falls back at read time rather than at
+ *  write time so changing the default later doesn't require store
+ *  migration. */
+export function useActiveCodeTab(
+    endpointId: string,
+    fallback: CodeSampleTargetId = 'curl',
+): CodeSampleTargetId {
+    return useEndpointDocStore((s) => s.activeCodeTab[endpointId] ?? fallback);
+}
+
+export function useEndpointDocActions() {
+    return useEndpointDocStore((s) => ({
+        toggleSection: s.toggleSection,
+        setSectionOpen: s.setSectionOpen,
+        setCodeTab: s.setCodeTab,
+        expandAll: s.expandAll,
+        collapseAll: s.collapseAll,
+    }));
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Local types for the EndpointDoc folder. Wider OpenAPI types live in
+ * ``../../../types``; this module only declares what's specific to the
+ * docs-view rendering (section identifiers, tab ids, etc.).
+ */
+
+/** Sections a single endpoint card can contain. Section identity is
+ *  stable because zustand stores open/close state keyed by it, and the
+ *  URL hash router references sections by the same id. */
+export type SectionId = 'parameters' | 'requestBody' | 'responses' | 'codeSamples';
+
+export const ALL_SECTION_IDS: readonly SectionId[] = [
+    'parameters',
+    'requestBody',
+    'responses',
+    'codeSamples',
+] as const;

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

@@ -12,6 +12,7 @@ import {
     DropdownMenuSeparator,
     DropdownMenuTrigger,
 } from '@djangocfg/ui-core/components';
+import { toast } from '@djangocfg/ui-core/hooks';
 
 import type { ApiEndpoint, OpenApiSchema } from '../../types';
 import {
@@ -44,6 +45,11 @@ interface SchemaCopyMenuProps {
     /** Resolved base URL that gets embedded into the copy so the AI
      *  receives working URLs, not the ones originally in ``schema.servers``. */
     baseUrl?: string;
+    /** Trigger appearance.
+     *  - ``button`` (default) — labelled pill with icon + chevron.
+     *  - ``icon`` — square ghost button, used in tight spots like the
+     *    sidebar header where there is no room for "Copy for AI". */
+    variant?: 'button' | 'icon';
 }
 
 /**
@@ -52,7 +58,7 @@ interface SchemaCopyMenuProps {
  * dereferencing + stringifying a large schema can be non-trivial — sizes
  * are displayed after the first successful copy, via a tiny cache.
  */
-export function SchemaCopyMenu({ schema, endpoints, baseUrl }: SchemaCopyMenuProps) {
+export function SchemaCopyMenu({ schema, endpoints, baseUrl, variant = 'button' }: SchemaCopyMenuProps) {
     const [sizeCache, setSizeCache] = useState<Partial<Record<Flavour, string>>>({});
     const [justCopied, setJustCopied] = useState<Flavour | null>(null);
     const [open, setOpen] = useState(false);
@@ -73,14 +79,18 @@ export function SchemaCopyMenu({ schema, endpoints, baseUrl }: SchemaCopyMenuPro
         async (flavour: Flavour) => {
             if (!isReady) return;
             const text = build(flavour);
+            const label = FLAVOUR_LABELS[flavour].title;
             try {
                 await navigator.clipboard.writeText(text);
-                setSizeCache((prev) => ({ ...prev, [flavour]: formatBytes(text) }));
+                const size = formatBytes(text);
+                setSizeCache((prev) => ({ ...prev, [flavour]: size }));
                 setJustCopied(flavour);
                 setTimeout(() => setJustCopied(null), 1500);
                 setOpen(false);
-            } catch {
-                // Silent: clipboard perm denied. CopyButton handles the same case.
+                toast.success(`Copied ${label}`, { description: size });
+            } catch (err) {
+                const message = err instanceof Error ? err.message : 'Clipboard permission denied';
+                toast.error('Copy failed', { description: message });
             }
         },
         [build, isReady],
@@ -91,13 +101,32 @@ export function SchemaCopyMenu({ schema, endpoints, baseUrl }: SchemaCopyMenuPro
     return (
         <DropdownMenu open={open} onOpenChange={setOpen}>
             <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="sm" className="h-8 gap-1.5 text-xs" disabled={!isReady}>
-                    <Sparkles className="h-3 w-3" />
-                    Copy for AI
-                    <ChevronDown className="h-3 w-3 opacity-60" />
-                </Button>
+                {variant === 'icon' ? (
+                    <Button
+                        variant="ghost"
+                        size="icon"
+                        className="h-7 w-7 shrink-0"
+                        disabled={!isReady}
+                        title="Copy schema for AI"
+                        aria-label="Copy schema for AI"
+                    >
+                        <Sparkles className="h-3.5 w-3.5" />
+                    </Button>
+                ) : (
+                    <Button variant="outline" size="sm" className="h-8 gap-1.5 text-xs" disabled={!isReady}>
+                        <Sparkles className="h-3 w-3" />
+                        Copy for AI
+                        <ChevronDown className="h-3 w-3 opacity-60" />
+                    </Button>
+                )}
             </DropdownMenuTrigger>
-            <DropdownMenuContent align="end" className="w-72">
+            <DropdownMenuContent
+                side="right"
+                align="start"
+                sideOffset={6}
+                collisionPadding={8}
+                className="w-60 max-w-[calc(100vw-16px)]"
+            >
                 <DropdownMenuLabel className="text-[10px] uppercase tracking-wider text-muted-foreground/70">
                     Copy schema
                 </DropdownMenuLabel>
@@ -127,7 +156,7 @@ export function SchemaCopyMenu({ schema, endpoints, baseUrl }: SchemaCopyMenuPro
                                     </span>
                                 ) : null}
                             </div>
-                            <span className="text-[10px] text-muted-foreground/70 leading-snug">
+                            <span className="text-[10px] text-muted-foreground/70 leading-snug line-clamp-1">
                                 {label.hint}
                             </span>
                         </DropdownMenuItem>

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

@@ -0,0 +1,48 @@
+'use client';
+
+import type { ApiEndpoint, OpenApiInfo, OpenApiSchema } from '../../../types';
+import { SchemaCopyMenu } from '../SchemaCopyMenu';
+
+interface BrandHeaderProps {
+    info: OpenApiInfo | null;
+    /** Used only by ``SchemaCopyMenu`` — displayed label comes from ``info``. */
+    endpoints: ApiEndpoint[];
+    rawSchema?: OpenApiSchema | null;
+    resolvedBaseUrl?: string;
+}
+
+/** Topmost row of the sidebar: API title on the left, tiny version
+ *  tag below it, and the Copy-for-AI menu on the right. The version
+ *  used to sit inline with the title and fought it for space on narrow
+ *  panels — stacking them vertically keeps the title at a readable
+ *  size and the version as quiet metadata. */
+export function BrandHeader({ info, endpoints, rawSchema, resolvedBaseUrl }: BrandHeaderProps) {
+    const apiTitle = info?.title ?? 'API Reference';
+    const copyReady = rawSchema !== null && rawSchema !== undefined && endpoints.length > 0;
+
+    return (
+        <div className="shrink-0 border-b px-3 py-2.5 flex items-start gap-2">
+            <div className="flex-1 min-w-0">
+                <div
+                    className="text-[13px] font-semibold text-foreground leading-tight truncate"
+                    title={apiTitle}
+                >
+                    {apiTitle}
+                </div>
+                {info?.version && (
+                    <div className="font-mono text-[10px] text-muted-foreground/60 leading-tight mt-0.5">
+                        v{info.version}
+                    </div>
+                )}
+            </div>
+            {copyReady && (
+                <SchemaCopyMenu
+                    schema={rawSchema ?? null}
+                    endpoints={endpoints}
+                    baseUrl={resolvedBaseUrl}
+                    variant="icon"
+                />
+            )}
+        </div>
+    );
+}

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

@@ -0,0 +1,33 @@
+'use client';
+
+import React from 'react';
+
+import { EndpointRow } from './EndpointRow';
+import type { CategoryVM, NavigateFn } from './types';
+
+interface CategoryBlockProps {
+    category: CategoryVM;
+    onNavigate: NavigateFn;
+}
+
+/** A labelled group of endpoint rows. The category header is
+ *  deliberately tiny (text-[10px] tracking-wider) — it's a divider, not
+ *  a call to attention. Users who are reading the list want to see the
+ *  endpoint names, not the category prose. */
+export const CategoryBlock = React.memo(function CategoryBlock({
+    category,
+    onNavigate,
+}: CategoryBlockProps) {
+    return (
+        <div className="mb-2.5 last:mb-1">
+            <div className="px-3 pt-3 pb-1 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>
+    );
+});

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

@@ -0,0 +1,73 @@
+'use client';
+
+import React from 'react';
+
+import { Tooltip, TooltipContent, TooltipTrigger } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { MethodBadge } from '../../shared/ui';
+import type { EndpointRowVM, NavigateFn } from './types';
+
+interface EndpointRowProps {
+    row: EndpointRowVM;
+    onNavigate: NavigateFn;
+}
+
+/** One endpoint in the sidebar list. Layout decisions worth calling out:
+ *   - Fixed 52px badge column via CSS grid so ``GET`` / ``POST`` /
+ *     ``PATCH`` all take the same horizontal slot and labels align
+ *     vertically on the left edge. Without this the list looks ragged
+ *     because ``POST`` is wider than ``GET`` and each label starts at
+ *     a different x offset.
+ *   - ``items-baseline`` so the method badge sits on the same visual
+ *     line as the label text, not in its vertical centre.
+ *   - ``py-1`` (not the old ``py-1.5``) for higher list density.
+ *   - Trailing full-stops are trimmed from the label. OpenAPI
+ *     summaries often end in ``.`` which looks like noise in a list.
+ *   - Active state is a single left-edge accent bar + soft tint — no
+ *     big filled background so the method badge still carries the
+ *     colour semantics of the row. */
+export const EndpointRow = React.memo(function EndpointRow({
+    row,
+    onNavigate,
+}: EndpointRowProps) {
+    // Strip a trailing full-stop — OpenAPI ``summary`` routinely ends
+    // in ``.`` which looks like punctuation noise when stacked in a list.
+    const displayLabel = row.label.replace(/\.$/, '');
+
+    return (
+        <Tooltip delayDuration={350}>
+            <TooltipTrigger asChild>
+                <button
+                    onClick={() => onNavigate(row.anchor, row.schemaId)}
+                    aria-current={row.isActive ? 'location' : undefined}
+                    className={cn(
+                        'relative w-full text-left grid grid-cols-[52px_minmax(0,1fr)] items-baseline gap-2 pl-3 pr-3 py-1 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="justify-self-start">
+                        <MethodBadge method={row.method} />
+                    </span>
+                    <span
+                        className={cn(
+                            'line-clamp-2 leading-snug min-w-0',
+                            row.useMono ? 'font-mono text-[11px] break-all' : 'text-[12px]',
+                            row.isActive && 'text-foreground font-medium',
+                        )}
+                    >
+                        {displayLabel}
+                    </span>
+                </button>
+            </TooltipTrigger>
+            <TooltipContent side="right" align="center" className="font-mono text-[11px]">
+                {row.tooltip}
+            </TooltipContent>
+        </Tooltip>
+    );
+});

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

@@ -0,0 +1,43 @@
+'use client';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { METHOD_FILTERS, type MethodFilter } from './types';
+
+interface MethodChipsProps {
+    value: MethodFilter;
+    onChange: (v: MethodFilter) => void;
+}
+
+/** Horizontal filter strip. Scrolls horizontally on narrow widths
+ *  rather than wrapping to a second line — the toolbar stays a fixed
+ *  height so the endpoint list below gets every pixel it can.
+ *
+ *  Active chips use a solid fill (not the outlined-with-tint style
+ *  from the old design) so "this filter is on" reads at a glance
+ *  without the eye having to resolve subtle border colour shifts. */
+export function MethodChips({ value, onChange }: MethodChipsProps) {
+    return (
+        <div className="flex items-center gap-1 overflow-x-auto -mx-1 px-1 pb-px">
+            {METHOD_FILTERS.map((m) => {
+                const active = value === m;
+                return (
+                    <button
+                        key={m}
+                        type="button"
+                        onClick={() => onChange(m)}
+                        aria-pressed={active}
+                        className={cn(
+                            'shrink-0 px-2 h-6 rounded font-mono text-[10px] font-semibold tracking-wide uppercase transition-colors',
+                            active
+                                ? 'bg-foreground text-background'
+                                : 'text-muted-foreground/70 hover:text-foreground hover:bg-muted',
+                        )}
+                    >
+                        {m}
+                    </button>
+                );
+            })}
+        </div>
+    );
+}

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

@@ -0,0 +1,27 @@
+'use client';
+
+import { CategoryBlock } from './CategoryBlock';
+import type { NavigateFn, SchemaSectionVM } from './types';
+
+interface SchemaSectionProps {
+    section: SchemaSectionVM;
+    onNavigate: NavigateFn;
+}
+
+/** One schema block inside ``sections`` grouping mode. Renders a
+ *  sticky header with the schema name so users can tell which API
+ *  they're looking at while scrolling, then the categories below. */
+export function SchemaSection({ section, onNavigate }: SchemaSectionProps) {
+    return (
+        <div className="mb-4 last:mb-2">
+            <div className="px-3 py-1.5 sticky top-0 z-[1] bg-background/95 backdrop-blur-[2px] border-b border-border/40">
+                <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>
+    );
+}

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