@djangocfg/ui-tools 2.1.289 → 2.1.291

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Section/SectionHeader.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { Check, ChevronDown, Link2 } from 'lucide-react';
+import { useState } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useEndpointDocContext } from '../context';
+import { buildSectionHash } from '../hooks/useSectionHash';
+import type { SectionId } from '../types';
+
+interface SectionHeaderProps {
+    /** Section identifier — needed to build the shareable hash link. */
+    sectionId: SectionId;
+    title: string;
+    badge?: number;
+    open: boolean;
+    onToggle: () => void;
+}
+
+/** Clickable header for a collapsible section. The whole row toggles,
+ *  plus a hover-revealed anchor button copies a ``#section=...`` URL so
+ *  users can share a link that lands with this exact section already
+ *  expanded (handled by ``useSectionHashRouter``). */
+export function SectionHeader({ sectionId, title, badge, open, onToggle }: SectionHeaderProps) {
+    const { endpointId } = useEndpointDocContext();
+    const [copied, setCopied] = useState(false);
+
+    const copyHash = (e: React.MouseEvent) => {
+        // Prevent the row toggle — the anchor button must not collapse
+        // the section while the user is copying the link.
+        e.stopPropagation();
+        if (typeof window === 'undefined') return;
+        const hash = buildSectionHash(endpointId, sectionId);
+        const url = `${window.location.origin}${window.location.pathname}#${hash}`;
+        void navigator.clipboard?.writeText(url).then(() => {
+            setCopied(true);
+            setTimeout(() => setCopied(false), 1200);
+        });
+    };
+
+    return (
+        <div
+            className={cn(
+                'group/section w-full flex items-center gap-2 py-1.5 -ml-1 px-1 rounded cursor-pointer',
+                'hover:bg-muted/30 transition-colors',
+            )}
+            onClick={onToggle}
+            role="button"
+            aria-expanded={open}
+            tabIndex={0}
+            onKeyDown={(e) => {
+                if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault();
+                    onToggle();
+                }
+            }}
+        >
+            <ChevronDown
+                className={cn(
+                    'h-3.5 w-3.5 text-muted-foreground/50 transition-transform shrink-0',
+                    !open && '-rotate-90',
+                )}
+            />
+            <h4 className="text-[10px] font-semibold uppercase tracking-[0.12em] text-muted-foreground/80">
+                {title}
+            </h4>
+            {typeof badge === 'number' && badge > 0 && (
+                <span className="font-mono text-[10px] text-muted-foreground/50 tabular-nums">
+                    {badge}
+                </span>
+            )}
+            <button
+                type="button"
+                onClick={copyHash}
+                title="Copy link to this section"
+                className={cn(
+                    'ml-auto shrink-0 p-1 rounded text-muted-foreground/40 hover:text-foreground hover:bg-muted transition-all',
+                    'opacity-0 group-hover/section:opacity-100 focus-visible:opacity-100',
+                    copied && 'opacity-100 text-emerald-500',
+                )}
+            >
+                {copied ? <Check className="h-3 w-3" /> : <Link2 className="h-3 w-3" />}
+            </button>
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Section/defaults.ts

@@ -0,0 +1,27 @@
+import type { SectionId } from '../types';
+
+/** Per-HTTP-method defaults for which sections start open. The goal is
+ *  "the most useful section is already visible" without burying the
+ *  less-important ones entirely.
+ *
+ *  Rationale by method:
+ *    - GET/DELETE: parameters + 2xx response — the request itself has
+ *      no body, so that's what the reader needs to see first.
+ *    - POST/PUT/PATCH: request body + 2xx response — the shape to send
+ *      is the main question; parameters and code samples are
+ *      secondary, available one click away.
+ *    - Other (HEAD/OPTIONS/…): be conservative, open nothing extra
+ *      beyond responses. */
+const DEFAULTS_BY_METHOD: Record<string, Partial<Record<SectionId, boolean>>> = {
+    GET: { parameters: true, responses: true },
+    DELETE: { parameters: true, responses: true },
+    POST: { requestBody: true, responses: true },
+    PUT: { requestBody: true, responses: true },
+    PATCH: { requestBody: true, responses: true },
+};
+
+/** Resolve the default open state for a given (method, section). Falls
+ *  back to ``false`` for unknown combinations. */
+export function defaultSectionOpen(method: string, sectionId: SectionId): boolean {
+    return DEFAULTS_BY_METHOD[method.toUpperCase()]?.[sectionId] ?? false;
+}

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

@@ -0,0 +1,45 @@
+'use client';
+
+import React from 'react';
+
+import { useEndpointDocContext } from '../context';
+import { useEndpointDocStore } from '../store';
+import { useIsSectionOpen } from '../store/selectors';
+import type { SectionId } from '../types';
+import { defaultSectionOpen } from './defaults';
+import { SectionHeader } from './SectionHeader';
+
+interface SectionProps {
+    /** Identifies the section inside the endpoint's card — used as a
+     *  key in zustand + URL hash routing. Must match one of ``SectionId``. */
+    id: SectionId;
+    title: string;
+    /** Optional count badge shown next to the title. */
+    badge?: number;
+    children: React.ReactNode;
+}
+
+/** Collapsible section wrapper. Pulls endpoint identity from
+ *  ``EndpointDocProvider`` so the component API stays at "id + title"
+ *  — the rest is implicit from context. Children render lazily when
+ *  open; a docs page may mount dozens of endpoints × four sections and
+ *  mounting everything eagerly would churn on the first scroll pass. */
+export function Section({ id, title, badge, children }: SectionProps) {
+    const { endpointId, method } = useEndpointDocContext();
+    const defaultOpen = defaultSectionOpen(method, id);
+    const open = useIsSectionOpen(endpointId, id, defaultOpen);
+    const toggleSection = useEndpointDocStore((s) => s.toggleSection);
+
+    return (
+        <div className="space-y-2.5">
+            <SectionHeader
+                sectionId={id}
+                title={title}
+                badge={badge}
+                open={open}
+                onToggle={() => toggleSection(endpointId, id)}
+            />
+            {open && <div>{children}</div>}
+        </div>
+    );
+}

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