@djangocfg/ui-tools 2.1.289 → 2.1.291

package/src/tools/OpenapiViewer/README.md

@@ -101,6 +101,9 @@ OpenapiViewer/
 ├── utils/
 │   ├── url.ts                   # UrlBuilder + path/query/baseUrl helpers
 │   ├── schemaExport.ts          # Dereferenced/compact/markdown export for LLMs
+│   ├── sampler.ts               # Schema → example value (openapi-sampler wrap)
+│   ├── operationToHar.ts        # ApiEndpoint → HAR request shape
+│   ├── codeSamples.ts           # HAR → curl / fetch / python / … renderers
 │   ├── formatters.ts            # HTTP status / method helpers, JSON validation
 │   ├── versionManager.ts
 │   ├── apiKeyManager.ts
@@ -110,28 +113,126 @@ OpenapiViewer/
     ├── index.ts                 # Re-exports DocsLayout
     ├── DocsLayout/              # Default (only) layout
     │   ├── index.tsx            # Root: sidebar + docs + slide-in playground
-    │   ├── Sidebar.tsx          # Grouped endpoint list, scrollspy highlight
     │   ├── DocsView.tsx         # Longread scroll container + scrollspy
-    │   ├── EndpointDoc.tsx      # One endpoint as a prose section + fields table
     │   ├── ApiIntroSection.tsx  # Top intro + Copy-for-AI dropdown
     │   ├── SchemaCopyMenu.tsx   # Per-schema copy flavours
     │   ├── SlideInPlayground.tsx# Right slide-in overlay
     │   ├── TryItSheet.tsx       # Mobile/tablet fallback via ResponsiveSheet
     │   ├── anchor.ts            # Stable section anchors for deep-linking
     │   ├── grouping.ts          # Shared group+sort used by sidebar and docs
-    │   ├── schemaFields.ts      # JSON Schema → flat field rows
-    │   └── sidebarLabel.ts      # Common-prefix strip + tooltip helpers
+    │   ├── schemaFields.ts      # JSON Schema → flat field rows (legacy helper)
+    │   ├── sidebarLabel.ts      # Common-prefix strip + tooltip helpers
+    │   │
+    │   ├── Sidebar/             # Grouped endpoint list + toolbar
+    │   │   ├── index.tsx        # Orchestrator
+    │   │   ├── types.ts         # VM types + METHOD_FILTERS
+    │   │   ├── buildVM.ts       # Pure view-model builders (flat + sections)
+    │   │   ├── useDebouncedValue.ts
+    │   │   ├── BrandHeader.tsx  # Title + version + Copy-for-AI
+    │   │   ├── Toolbar.tsx      # Schema combobox + search + method chips
+    │   │   ├── SearchInput.tsx
+    │   │   ├── MethodChips.tsx
+    │   │   ├── SidebarBody.tsx  # flat vs sections switch
+    │   │   ├── SchemaSection.tsx
+    │   │   ├── CategoryBlock.tsx
+    │   │   └── EndpointRow.tsx
+    │   │
+    │   └── EndpointDoc/         # One endpoint as a prose card
+    │       ├── index.tsx        # Orchestrator: header + sections
+    │       ├── types.ts         # SectionId union
+    │       ├── context.tsx      # Identity context (endpointId + method)
+    │       │
+    │       ├── store/           # Zustand — open sections + active code tab
+    │       │   ├── index.ts     # create() + sessionStorage persist
+    │       │   └── selectors.ts
+    │       │
+    │       ├── hooks/
+    │       │   └── useSectionHash.ts  # #section=<id>.<sec> deep-link router
+    │       │
+    │       ├── Header/          # Meta row (badge + actions + Try it) + path
+    │       │   ├── index.tsx
+    │       │   ├── MetaActions.tsx    # Copy link / markdown / expand all
+    │       │   ├── MethodBadge.tsx
+    │       │   └── PathDisplay.tsx
+    │       │
+    │       ├── Section/         # Collapsible section wrapper
+    │       │   ├── index.tsx
+    │       │   ├── SectionHeader.tsx  # Chevron + title + badge + anchor
+    │       │   └── defaults.ts        # Per-method open-by-default rules
+    │       │
+    │       ├── Parameters/      # Path + Query parameters block
+    │       │   ├── index.tsx
+    │       │   ├── ParamGroup.tsx
+    │       │   └── ParamRow.tsx
+    │       │
+    │       ├── RequestBody/     # Body preview
+    │       │   └── index.tsx
+    │       │
+    │       ├── SchemaFields/    # Tree-view of JSON Schema properties
+    │       │   ├── index.tsx
+    │       │   ├── FieldRow.tsx
+    │       │   ├── buildTree.ts
+    │       │   └── types.ts
+    │       │
+    │       ├── Responses/       # Status-code rows + example body
+    │       │   ├── index.tsx
+    │       │   ├── ResponseRow.tsx
+    │       │   ├── ResponseBody.tsx
+    │       │   └── StatusTag.tsx
+    │       │
+    │       └── CodeSamples/     # Language tabs + generated snippet
+    │           ├── index.tsx
+    │           ├── LanguageTabs.tsx
+    │           └── useCodeSnippet.ts
     │
     └── shared/                  # Panels reused by SlideInPlayground + TryItSheet
         ├── RequestPanel.tsx
-        ├── ResponsePanel.tsx
         ├── SendButton.tsx
         ├── BodyFormEditor.tsx   # Recursive JSON-Schema form renderer
         ├── EndpointDraftSync.tsx# Headless draft ↔ context sync
         ├── EndpointResetButton.tsx
-        └── ui.tsx               # MethodBadge, StatusBadge, Panel, atoms
+        ├── ui.tsx               # MethodBadge, StatusBadge, Panel, atoms
+        │
+        └── ResponsePanel/       # Response viewer with Pretty / Raw / Preview tabs
+            ├── index.tsx        # Orchestrator + mode state + guards
+            ├── types.ts         # ViewMode + ContentKind
+            ├── detectContent.ts # Content-Type → Prism language inference
+            ├── useResponseView.ts
+            ├── StatusBar.tsx    # Status / size / duration / Copy
+            ├── ViewTabs.tsx
+            ├── PrettyView.tsx   # JsonTree or syntax-highlighted code
+            ├── RawView.tsx      # Plain <pre>
+            └── PreviewView.tsx  # Sandboxed iframe for HTML responses
 ```
 
+## Endpoint doc — sections & deep-linking
+
+Each endpoint card splits into four collapsible sections: **Parameters**,
+**Request body**, **Code samples**, **Responses**. Defaults are
+method-aware — GET opens Parameters + Responses, POST/PUT/PATCH opens
+Request body + Responses, etc. User overrides are persisted per
+endpoint in `sessionStorage` (zustand `persist` middleware) so a tab you
+opened once stays open as you scroll.
+
+A hover-revealed anchor button on each section header copies a shareable
+URL like `…#section=ep-get-api-v3-pet-findbystatus.responses` —
+following that link lands on the endpoint, expands the referenced
+section, and scrolls it into view.
+
+## Response panel — Pretty / Raw / Preview
+
+The response panel picks a default view based on `Content-Type`:
+
+- **JSON** → `Pretty` (interactive JsonTree)
+- **HTML** → `Preview` (sandboxed iframe, scripts disabled) with `Pretty`
+  as the syntax-highlighted source fallback
+- **XML / CSS / JS / text** → `Pretty` using Prism
+- Everything has a **Raw** tab for a literal `<pre>` dump
+
+The HTML preview detects single-page-app shells (empty `<body>` + mount
+div + `<script>`) and shows an explanatory empty-state instead of a
+blank iframe, since scripts can't run in the sandbox.
+
 ## Config Reference
 
 ```ts
@@ -145,6 +246,13 @@ interface PlaygroundConfig {
   /** Optional API keys for the X-API-Key picker. */
   apiKeys?: ApiKey[];
   apiKeysLoading?: boolean;
+  /** Layout mode. ``'selector'`` (default) shows one schema at a time,
+   *  picked via a Combobox. ``'sections'`` flattens every schema into
+   *  the longread as top-level sections. */
+  schemaGrouping?: 'selector' | 'sections';
+  /** Sync the active endpoint anchor to ``window.location.hash`` as
+   *  the user scrolls (sections mode). Default: off. */
+  urlSync?: boolean;
 }
 
 interface SchemaSource {

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

@@ -13,7 +13,21 @@ interface ApiIntroSectionProps {
     resolvedBaseUrl?: string;
 }
 
+interface BaseUrlRow {
+    url: string;
+    description?: string;
+}
+
 export function ApiIntroSection({ info, schema, endpoints, resolvedBaseUrl }: ApiIntroSectionProps) {
+    // Prefer the *resolved* base URL whenever we have one — that's the
+    // URL actual requests target, not the raw ``servers[0].url`` from
+    // the spec (which can be a bare path like ``/api/v3``). Fall back
+    // to the spec's ``servers`` list so specs that document multiple
+    // servers keep showing all of them.
+    const baseUrlRows: BaseUrlRow[] = resolvedBaseUrl
+        ? [{ url: resolvedBaseUrl, description: info.servers?.[0]?.description }]
+        : (info.servers ?? []).map((s) => ({ url: s.url, description: s.description }));
+
     return (
         <section className="pb-10 mb-10 border-b">
             <div className="flex items-start justify-between gap-4 flex-wrap">
@@ -38,20 +52,20 @@ export function ApiIntroSection({ info, schema, endpoints, resolvedBaseUrl }: Ap
                 </div>
             )}
 
-            {info.servers && info.servers.length > 0 && (
+            {baseUrlRows.length > 0 && (
                 <div className="mt-6 space-y-2">
                     <h4 className="text-[10px] font-semibold uppercase tracking-wider text-muted-foreground/60">
                         Base URL
                     </h4>
                     <div className="space-y-1.5">
-                        {info.servers.map((s, i) => (
-                            <div key={`${s.url}-${i}`} className="flex items-baseline gap-2 flex-wrap">
+                        {baseUrlRows.map((row, i) => (
+                            <div key={`${row.url}-${i}`} className="flex items-baseline gap-2 flex-wrap">
                                 <code className="font-mono text-xs px-2 py-1 rounded bg-muted border">
-                                    {s.url}
+                                    {row.url}
                                 </code>
-                                {s.description && (
+                                {row.description && (
                                     <span className="text-xs text-muted-foreground">
-                                        {s.description}
+                                        {row.description}
                                     </span>
                                 )}
                             </div>

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

@@ -14,6 +14,7 @@ import {
 import { deduplicateEndpoints } from '../../utils/versionManager';
 import { ApiIntroSection } from './ApiIntroSection';
 import { EndpointDoc } from './EndpointDoc';
+import { useSectionHashRouter } from './EndpointDoc/hooks/useSectionHash';
 import { SchemaCopyMenu } from './SchemaCopyMenu';
 
 export interface DocsViewHandle {
@@ -150,6 +151,11 @@ export const DocsView = React.forwardRef<DocsViewHandle, DocsViewProps>(function
     const scrollTargetRef = useRef<ScrollTarget | null>(null);
     const { onActiveChange } = props;
 
+    // ``#section=<endpointId>.<sectionId>`` shareable deep-links —
+    // opens the referenced section in the store and scrolls it in.
+    // Idempotent, attaches a single hashchange listener.
+    useSectionHashRouter();
+
     // Resolve the real scroll container once the ref is attached. In
     // standalone pages that's ``window``; inside an ``overflow-auto``
     // shell (dev playground, modal) it's the wrapping DIV.

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/CodeSamples/LanguageTabs.tsx

@@ -0,0 +1,36 @@
+'use client';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { CODE_SAMPLE_TARGETS, type CodeSampleTargetId } from '../../../../utils/codeSamples';
+
+interface LanguageTabsProps {
+    activeId: CodeSampleTargetId;
+    onChange: (id: CodeSampleTargetId) => void;
+}
+
+/** Horizontal tab strip for switching between cURL/JS/Python/… The
+ *  strip scrolls horizontally on narrow viewports rather than wrapping
+ *  to a second line so the adjacent code block keeps its vertical
+ *  rhythm. */
+export function LanguageTabs({ activeId, onChange }: LanguageTabsProps) {
+    return (
+        <div className="flex items-center gap-1 overflow-x-auto -mx-1 px-1">
+            {CODE_SAMPLE_TARGETS.map((t) => (
+                <button
+                    key={t.id}
+                    type="button"
+                    onClick={() => onChange(t.id)}
+                    className={cn(
+                        'shrink-0 h-7 px-2.5 rounded text-xs font-medium transition-colors',
+                        activeId === t.id
+                            ? 'bg-muted text-foreground'
+                            : 'text-muted-foreground/70 hover:text-foreground hover:bg-muted/50',
+                    )}
+                >
+                    {t.label}
+                </button>
+            ))}
+        </div>
+    );
+}

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

@@ -0,0 +1,56 @@
+'use client';
+
+import PrettyCode from '../../../../../PrettyCode';
+import type { ApiEndpoint } from '../../../../types';
+import { useEndpointDocContext } from '../context';
+import { useEndpointDocStore } from '../store';
+import { useActiveCodeTab } from '../store/selectors';
+import { LanguageTabs } from './LanguageTabs';
+import { useCodeSnippet } from './useCodeSnippet';
+
+interface CodeSamplesProps {
+    endpoint: ApiEndpoint;
+    /** Optional body to include in generated snippets. When omitted we
+     *  use ``endpoint.requestBody?.example`` if present, so the snippet
+     *  shows a realistic payload out of the box. */
+    body?: string;
+    /** Parameter values to substitute into the URL. Missing path params
+     *  fall back to ``{name}`` placeholders so the snippet still
+     *  illustrates the shape. */
+    parameters?: Record<string, string>;
+    /** Extra headers to include in snippets (e.g. a picked API key). */
+    headers?: Record<string, string>;
+    /** Base URL override — falls back to ``endpoint.path`` which
+     *  already has the resolved base URL prepended by the extractor. */
+    baseUrl?: string;
+}
+
+/** Code samples block: language tab bar + highlighted snippet. The
+ *  outer Section wrapper (collapsible) lives one level up; this
+ *  component is always "open" from its own perspective. */
+export function CodeSamples({ endpoint, body, parameters, headers, baseUrl }: CodeSamplesProps) {
+    const { endpointId } = useEndpointDocContext();
+    const activeId = useActiveCodeTab(endpointId);
+    const setCodeTab = useEndpointDocStore((s) => s.setCodeTab);
+
+    const { snippet, prism } = useCodeSnippet({
+        endpoint,
+        body,
+        parameters,
+        headers,
+        baseUrl,
+        activeId,
+    });
+
+    return (
+        <div className="space-y-2.5">
+            <LanguageTabs activeId={activeId} onChange={(id) => setCodeTab(endpointId, id)} />
+            <PrettyCode
+                data={snippet}
+                language={prism as never}
+                isCompact
+                maxLines={20}
+            />
+        </div>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/CodeSamples/useCodeSnippet.ts

@@ -0,0 +1,77 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import type { ApiEndpoint } from '../../../../types';
+import {
+    CODE_SAMPLE_TARGETS,
+    renderSnippet,
+    type CodeSampleTargetId,
+} from '../../../../utils/codeSamples';
+import { buildHarRequest } from '../../../../utils/operationToHar';
+import { resolveAbsolute } from '../../../../utils/url';
+
+interface UseCodeSnippetInput {
+    endpoint: ApiEndpoint;
+    body?: string;
+    parameters?: Record<string, string>;
+    headers?: Record<string, string>;
+    baseUrl?: string;
+    activeId: CodeSampleTargetId;
+}
+
+interface UseCodeSnippetResult {
+    /** Fully-rendered snippet string. Always present — falls back to an
+     *  "unavailable" message if the generator returns null, so the
+     *  consumer can always mount ``PrettyCode``. */
+    snippet: string;
+    /** Prism language id matching ``activeId`` — passed to PrettyCode so
+     *  it picks the right highlighter. */
+    prism: string;
+}
+
+/** Encapsulates HAR build + snippet render + memoisation for the Code
+ *  Samples block. Kept as a hook (rather than inline ``useMemo`` blocks
+ *  in the component) so unit tests can exercise the snippet pipeline
+ *  independently of React rendering. */
+export function useCodeSnippet({
+    endpoint,
+    body,
+    parameters,
+    headers,
+    baseUrl,
+    activeId,
+}: UseCodeSnippetInput): UseCodeSnippetResult {
+    const effectiveBody = body ?? endpoint.requestBody?.example;
+
+    // Build the HAR once per input change — every tab rebuilds its
+    // snippet from this shared request shape.
+    //
+    // ``endpoint.path`` already carries the schema's ``servers[0].url``
+    // (joined upstream in ``useOpenApiSchema``). Usually that's a path
+    // like ``/api/v3/pet`` — good enough for same-origin fetch, wrong
+    // for curl/python/go which need a runnable absolute URL. We hand
+    // off to ``resolveAbsolute`` so the snippet is copy-pasteable from
+    // a terminal without the user having to edit the host in manually.
+    //
+    // Priority: explicit ``baseUrl`` prop > resolved origin > bare path.
+    const har = useMemo(() => {
+        const h = buildHarRequest({
+            endpoint,
+            body: effectiveBody,
+            parameters,
+            headers,
+            baseUrl,
+        });
+        return baseUrl ? h : { ...h, url: resolveAbsolute(h.url) };
+    }, [endpoint, effectiveBody, parameters, headers, baseUrl]);
+
+    return useMemo(() => {
+        const target = CODE_SAMPLE_TARGETS.find((t) => t.id === activeId)!;
+        const code = renderSnippet(har, activeId);
+        return {
+            snippet: code ?? `// Snippet for ${target.label} is unavailable for this request.`,
+            prism: target.prism,
+        };
+    }, [har, activeId]);
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Header/MetaActions.tsx

@@ -0,0 +1,146 @@
+'use client';
+
+import {
+    Check,
+    ChevronsDownUp,
+    ChevronsUpDown,
+    FileCode2,
+    Link2,
+} from 'lucide-react';
+import React, { useCallback, useMemo, useState } from 'react';
+
+import {
+    Tooltip,
+    TooltipContent,
+    TooltipTrigger,
+    SafeTooltipProvider,
+} from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { useEndpointDocContext } from '../context';
+import { sectionKey, useEndpointDocStore } from '../store';
+import type { SectionId } from '../types';
+
+interface MetaActionsProps {
+    anchor: string;
+    endpointMarkdown: string;
+    /** Sections present on this endpoint — expand/collapse acts only
+     *  on visible rows, never on catalogue items the card doesn't render. */
+    presentSections: readonly SectionId[];
+}
+
+interface IconButtonProps {
+    label: string;
+    onClick: () => void;
+    children: React.ReactNode;
+    active?: boolean;
+}
+
+/** Tight 24×24 icon button used across the meta row. Keeps the hit
+ *  target compact so the row reads as a secondary metadata strip, not
+ *  a toolbar that competes with the path for attention. */
+function IconButton({ label, onClick, children, active }: IconButtonProps) {
+    return (
+        <Tooltip>
+            <TooltipTrigger asChild>
+                <button
+                    type="button"
+                    onClick={onClick}
+                    aria-label={label}
+                    className={cn(
+                        'shrink-0 h-6 w-6 inline-flex items-center justify-center rounded',
+                        'text-muted-foreground/60 hover:text-foreground hover:bg-muted transition-colors',
+                        active && 'text-emerald-500 hover:text-emerald-500',
+                    )}
+                >
+                    {children}
+                </button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom" className="text-[11px]">
+                {label}
+            </TooltipContent>
+        </Tooltip>
+    );
+}
+
+/** Inline meta-row actions: copy link · copy markdown · expand/collapse
+ *  all. Actions are always visible (corporate tool pattern) but sized
+ *  down so the path on the next line stays the visual focal point. */
+export function MetaActions({ anchor, endpointMarkdown, presentSections }: MetaActionsProps) {
+    const { endpointId } = useEndpointDocContext();
+    const expandAll = useEndpointDocStore((s) => s.expandAll);
+    const collapseAll = useEndpointDocStore((s) => s.collapseAll);
+    const openSections = useEndpointDocStore((s) => s.openSections);
+
+    const [justCopied, setJustCopied] = useState<'link' | 'md' | null>(null);
+    const flash = useCallback((which: 'link' | 'md') => {
+        setJustCopied(which);
+        setTimeout(() => setJustCopied(null), 1200);
+    }, []);
+
+    const mostlyOpen = useMemo(() => {
+        if (presentSections.length === 0) return false;
+        let openCount = 0;
+        for (const sid of presentSections) {
+            if (openSections[sectionKey(endpointId, sid)]) openCount += 1;
+        }
+        return openCount > presentSections.length / 2;
+    }, [openSections, presentSections, endpointId]);
+
+    const copyLink = useCallback(() => {
+        if (typeof window === 'undefined') return;
+        const url = `${window.location.origin}${window.location.pathname}#${anchor}`;
+        void navigator.clipboard?.writeText(url).then(() => flash('link'));
+    }, [anchor, flash]);
+
+    const copyMarkdown = useCallback(() => {
+        if (typeof window === 'undefined') return;
+        void navigator.clipboard?.writeText(endpointMarkdown).then(() => flash('md'));
+    }, [endpointMarkdown, flash]);
+
+    const toggleAll = useCallback(() => {
+        if (mostlyOpen) collapseAll(endpointId, presentSections);
+        else expandAll(endpointId, presentSections);
+    }, [mostlyOpen, collapseAll, expandAll, endpointId, presentSections]);
+
+    return (
+        <SafeTooltipProvider delayDuration={200}>
+            <div className="flex items-center gap-0.5">
+                <IconButton
+                    label={justCopied === 'link' ? 'Copied!' : 'Copy link to endpoint'}
+                    onClick={copyLink}
+                    active={justCopied === 'link'}
+                >
+                    {justCopied === 'link' ? (
+                        <Check className="h-3.5 w-3.5" />
+                    ) : (
+                        <Link2 className="h-3.5 w-3.5" />
+                    )}
+                </IconButton>
+                <IconButton
+                    label={justCopied === 'md' ? 'Copied!' : 'Copy as Markdown (for AI)'}
+                    onClick={copyMarkdown}
+                    active={justCopied === 'md'}
+                >
+                    {justCopied === 'md' ? (
+                        <Check className="h-3.5 w-3.5" />
+                    ) : (
+                        <FileCode2 className="h-3.5 w-3.5" />
+                    )}
+                </IconButton>
+                {presentSections.length >= 2 && (
+                    <IconButton
+                        label={mostlyOpen ? 'Collapse all sections' : 'Expand all sections'}
+                        onClick={toggleAll}
+                    >
+                        {mostlyOpen ? (
+                            <ChevronsDownUp className="h-3.5 w-3.5" />
+                        ) : (
+                            <ChevronsUpDown className="h-3.5 w-3.5" />
+                        )}
+                    </IconButton>
+                )}
+            </div>
+        </SafeTooltipProvider>
+    );
+}

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Header/MethodBadge.tsx

@@ -0,0 +1,6 @@
+'use client';
+
+// Thin re-export so the Header barrel file stays self-contained. The
+// actual badge lives in ``shared/ui`` because it's used by the sidebar
+// and the playground too — duplicating styles would drift.
+export { MethodBadge } from '../../../shared/ui';

package/src/tools/OpenapiViewer/components/DocsLayout/EndpointDoc/Header/PathDisplay.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+import { relativePath } from '../../../shared/ui';
+
+interface PathDisplayProps {
+    path: string;
+}
+
+/** The endpoint path as the visual focal point of the card. Renders in
+ *  large monospace so readers scanning the page land on it first — the
+ *  path is what distinguishes one endpoint from another, so it should
+ *  be the biggest visible element short of the section title hierarchy.
+ *
+ *  ``relativePath`` strips the resolved base URL so the docs always
+ *  show the API-local path, not an absolute URL cluttered with host
+ *  noise. */
+export function PathDisplay({ path }: PathDisplayProps) {
+    return (
+        <code
+            className="block font-mono text-lg md:text-xl font-semibold text-foreground leading-tight"
+            style={{ overflowWrap: 'anywhere', wordBreak: 'break-word' }}
+        >
+            {relativePath(path)}
+        </code>
+    );
+}

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

@@ -0,0 +1,87 @@
+'use client';
+
+import { Play } from 'lucide-react';
+import React, { useMemo } from 'react';
+
+import { Button } from '@djangocfg/ui-core/components';
+
+import { MarkdownMessage } from '../../../../../../components/markdown';
+import type { ApiEndpoint } from '../../../../types';
+import { endpointToMarkdown } from '../../../../utils/schemaExport';
+import type { SectionId } from '../types';
+import { MetaActions } from './MetaActions';
+import { MethodBadge } from './MethodBadge';
+import { PathDisplay } from './PathDisplay';
+
+interface EndpointHeaderProps {
+    endpoint: ApiEndpoint;
+    anchor: string;
+    isLoadedInPlayground: boolean;
+    onTryIt: () => void;
+    /** Sections actually rendered on this endpoint — drives the
+     *  expand/collapse-all icon in the meta row. */
+    presentSections: readonly SectionId[];
+}
+
+/** Card header, three stacked rows:
+ *   1. Meta — small utility strip: method badge · inline actions · Try-it.
+ *   2. Path — large monospace, the visual focus of the card.
+ *   3. Description — prose, aligned to the left edge under path.
+ *
+ *  Splitting metadata from the path lets the path itself become the
+ *  focal point — readers scan paths when scrolling, not badges. The
+ *  meta row stays compact so it reads as "info about this endpoint"
+ *  rather than "toolbar that competes for attention". */
+export function EndpointHeader({
+    endpoint,
+    anchor,
+    isLoadedInPlayground,
+    onTryIt,
+    presentSections,
+}: EndpointHeaderProps) {
+    // Memoise the markdown dump — only recomputes when the endpoint
+    // reference changes, not on unrelated re-renders of the subtree.
+    const endpointMd = useMemo(() => endpointToMarkdown(endpoint), [endpoint]);
+
+    return (
+        <header className="space-y-3">
+            {/* Row 1 — meta strip. Badge + inline icon actions on the
+                left, primary CTA on the right. Kept tight (24px tall)
+                so it doesn't visually compete with the path row below. */}
+            <div className="flex items-center gap-3 flex-wrap">
+                <div className="flex items-center gap-2 min-w-0">
+                    <MethodBadge method={endpoint.method} />
+                    <MetaActions
+                        anchor={anchor}
+                        endpointMarkdown={endpointMd}
+                        presentSections={presentSections}
+                    />
+                </div>
+                <Button
+                    size="sm"
+                    variant={isLoadedInPlayground ? 'secondary' : 'default'}
+                    onClick={onTryIt}
+                    className="ml-auto h-7 text-xs gap-1.5 px-2.5"
+                >
+                    <Play className="h-3 w-3" />
+                    {isLoadedInPlayground ? 'Loaded' : 'Try it'}
+                </Button>
+            </div>
+
+            {/* Row 2 — path as the visual focal point. Larger and more
+                prominent than it was when competing with the badge
+                and action icons inline. */}
+            <div className="min-w-0">
+                <PathDisplay path={endpoint.path} />
+            </div>
+
+            {/* Row 3 — description, aligned to the left edge under the
+                path. Text-sm so it reads as subtitle, not body copy. */}
+            {endpoint.description && (
+                <div className="text-muted-foreground text-sm">
+                    <MarkdownMessage content={endpoint.description} />
+                </div>
+            )}
+        </header>
+    );
+}