@djangocfg/ui-tools 2.1.289 → 2.1.290

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/context.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import React, { createContext, useContext, useMemo } from 'react';
+
+/** Identity context for a single EndpointDoc subtree.
+ *
+ *  This is NOT a state container — state lives in the zustand store at
+ *  ``./store``. The context only carries per-endpoint *identity* values
+ *  so children (Section, CodeSamples, future ExpandAll button) don't
+ *  have to re-derive them or receive them as repeated props.
+ *
+ *  Why identity-only:
+ *    - One zustand singleton handles state for *all* endpoints on the
+ *      page, keyed by ``endpointId``. Wrapping zustand itself in a
+ *      Provider would defeat that composite-key design.
+ *    - Identity (anchor, HTTP method) is invariant inside an endpoint
+ *      card; deriving it per-child is wasted work and makes the props
+ *      table look noisier than the logic actually is. */
+interface EndpointDocContextValue {
+    /** DOM-safe anchor id for this endpoint — used as the store key
+     *  prefix (``openSections[`${endpointId}:${sectionId}`]``) and as
+     *  the URL hash target for shareable links. */
+    endpointId: string;
+    /** HTTP method (``GET`` / ``POST`` / …). Drives per-method default
+     *  open state for Section. Kept in context so ``defaultSectionOpen``
+     *  doesn't need to be threaded as a prop through every subtree. */
+    method: string;
+}
+
+const EndpointDocContext = createContext<EndpointDocContextValue | null>(null);
+
+interface EndpointDocProviderProps extends EndpointDocContextValue {
+    children: React.ReactNode;
+}
+
+export function EndpointDocProvider({ endpointId, method, children }: EndpointDocProviderProps) {
+    // Memoise the value so every re-render of the parent orchestrator
+    // doesn't invalidate children reading the context — the common
+    // hover/focus state on the header row re-renders EndpointDoc often.
+    const value = useMemo(() => ({ endpointId, method }), [endpointId, method]);
+    return <EndpointDocContext.Provider value={value}>{children}</EndpointDocContext.Provider>;
+}
+
+export function useEndpointDocContext(): EndpointDocContextValue {
+    const ctx = useContext(EndpointDocContext);
+    if (!ctx) {
+        // Treated as a programming error, not a runtime one — if this
+        // fires, something rendered EndpointDoc internals outside the
+        // provider, which means the store keys will collide or be
+        // missing entirely. Loud failure beats silent corruption.
+        throw new Error(
+            '[OpenapiViewer] useEndpointDocContext must be used inside <EndpointDocProvider>.',
+        );
+    }
+    return ctx;
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/hooks/useSectionHash.ts

@@ -0,0 +1,63 @@
+'use client';
+
+import { useEffect } from 'react';
+
+import { useEndpointDocStore } from '../store';
+import { ALL_SECTION_IDS, type SectionId } from '../types';
+
+/** Parse ``#section=<endpointId>.<sectionId>`` out of a hash string.
+ *  Returns ``null`` for any other shape (including the plain
+ *  ``#<endpointId>`` form used elsewhere for scrolling to an endpoint). */
+export function parseSectionHash(hash: string): { endpointId: string; sectionId: SectionId } | null {
+    const raw = hash.startsWith('#') ? hash.slice(1) : hash;
+    if (!raw.startsWith('section=')) return null;
+    const value = raw.slice('section='.length);
+    const dot = value.lastIndexOf('.');
+    if (dot <= 0 || dot === value.length - 1) return null;
+    const endpointId = value.slice(0, dot);
+    const sectionIdCandidate = value.slice(dot + 1);
+    if (!(ALL_SECTION_IDS as readonly string[]).includes(sectionIdCandidate)) return null;
+    return { endpointId, sectionId: sectionIdCandidate as SectionId };
+}
+
+/** Build the shareable hash that opens a specific section. */
+export function buildSectionHash(endpointId: string, sectionId: SectionId): string {
+    return `section=${endpointId}.${sectionId}`;
+}
+
+/** On mount + on hashchange, read ``#section=...``, open that section
+ *  in the store, and scroll its endpoint into view. Runs once per
+ *  hash change, not per endpoint render — the effect lives above the
+ *  per-endpoint level in the tree.
+ *
+ *  Behaviour:
+ *    1. Parse hash. If it isn't our ``section=`` form, bail — the
+ *       browser's own anchor-scrolling handles ``#ep-…`` URLs already.
+ *    2. Open the referenced section in the zustand store so its body
+ *       is visible the moment the user lands.
+ *    3. Scroll the endpoint's ``<section id={endpointId}>`` into view
+ *       on the next frame (after the section body has mounted). */
+export function useSectionHashRouter(): void {
+    const setSectionOpen = useEndpointDocStore((s) => s.setSectionOpen);
+
+    useEffect(() => {
+        if (typeof window === 'undefined') return;
+
+        function apply() {
+            const parsed = parseSectionHash(window.location.hash);
+            if (!parsed) return;
+            setSectionOpen(parsed.endpointId, parsed.sectionId, true);
+            // Defer scroll to let the section body render first —
+            // scrolling a collapsed row lands on the wrong offset
+            // because the body takes vertical space once expanded.
+            requestAnimationFrame(() => {
+                const el = document.getElementById(parsed.endpointId);
+                el?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+            });
+        }
+
+        apply();
+        window.addEventListener('hashchange', apply);
+        return () => window.removeEventListener('hashchange', apply);
+    }, [setSectionOpen]);
+}

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

@@ -0,0 +1,96 @@
+'use client';
+
+import React from 'react';
+
+import type { ApiEndpoint } from '../../../types';
+import { endpointAnchor } from '../anchor';
+import { CodeSamples } from './CodeSamples';
+import { EndpointDocProvider } from './context';
+import { EndpointHeader } from './Header';
+import { Parameters } from './Parameters';
+import { RequestBody } from './RequestBody';
+import { Responses } from './Responses';
+import { Section } from './Section';
+import type { SectionId } from './types';
+
+interface EndpointDocProps {
+    endpoint: ApiEndpoint;
+    /** Is this endpoint currently loaded in the sticky playground? */
+    isLoadedInPlayground: boolean;
+    onTryIt: () => void;
+    /** Scoping prefix for the anchor, so endpoints from different schemas
+     *  don't collide on a single page. Falls back to ``endpoint.schemaId``. */
+    schemaId?: string | null;
+}
+
+/** Card that documents one API endpoint: header + a stack of collapsible
+ *  sections (parameters, request body, responses, code samples). The
+ *  component itself is a thin orchestrator — each child folder owns its
+ *  own rendering concerns and reads the endpoint identity from context. */
+export function EndpointDoc({ endpoint, isLoadedInPlayground, onTryIt, schemaId }: EndpointDocProps) {
+    const scopedSchemaId = schemaId ?? endpoint.schemaId ?? null;
+    const anchor = endpointAnchor(endpoint, scopedSchemaId);
+    const pathParams = endpoint.parameters?.filter((p) => endpoint.path.includes(`{${p.name}}`)) ?? [];
+    const queryParams = endpoint.parameters?.filter((p) => !endpoint.path.includes(`{${p.name}}`)) ?? [];
+
+    const hasParameters = pathParams.length > 0 || queryParams.length > 0;
+    const hasResponses = (endpoint.responses?.length ?? 0) > 0;
+
+    // Collect section ids that actually render so the header's
+    // expand/collapse-all toggle only touches visible sections.
+    // ``codeSamples`` is always present — it synthesises a snippet
+    // even for parameter-less endpoints.
+    const presentSections: SectionId[] = [];
+    if (hasParameters) presentSections.push('parameters');
+    if (endpoint.requestBody) presentSections.push('requestBody');
+    presentSections.push('codeSamples');
+    if (hasResponses) presentSections.push('responses');
+
+    return (
+        <EndpointDocProvider endpointId={anchor} method={endpoint.method}>
+            <section
+                id={anchor}
+                data-endpoint-anchor={anchor}
+                data-schema-id={scopedSchemaId ?? ''}
+                className="scroll-mt-24 py-10 first:pt-0"
+            >
+                <EndpointHeader
+                    endpoint={endpoint}
+                    anchor={anchor}
+                    isLoadedInPlayground={isLoadedInPlayground}
+                    onTryIt={onTryIt}
+                    presentSections={presentSections}
+                />
+
+                <div className="mt-8 space-y-5">
+                    {hasParameters && (
+                        <Section
+                            id="parameters"
+                            title="Parameters"
+                            badge={pathParams.length + queryParams.length}
+                        >
+                            <Parameters pathParams={pathParams} queryParams={queryParams} />
+                        </Section>
+                    )}
+                    {endpoint.requestBody && (
+                        <Section id="requestBody" title="Request body">
+                            <RequestBody body={endpoint.requestBody} />
+                        </Section>
+                    )}
+                    <Section id="codeSamples" title="Code samples">
+                        <CodeSamples endpoint={endpoint} />
+                    </Section>
+                    {hasResponses && (
+                        <Section
+                            id="responses"
+                            title="Responses"
+                            badge={endpoint.responses!.length}
+                        >
+                            <Responses responses={endpoint.responses!} />
+                        </Section>
+                    )}
+                </div>
+            </section>
+        </EndpointDocProvider>
+    );
+}

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

@@ -120,7 +120,13 @@ export function SchemaCopyMenu({ schema, endpoints, baseUrl, variant = 'button'
                     </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>
@@ -150,7 +156,7 @@ export function SchemaCopyMenu({ schema, endpoints, baseUrl, variant = 'button'
                                     </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>
+    );
+}