@clidey/dory 1.0.8 → 1.9.0

package/src/mdx/icon-names.ts

@@ -0,0 +1,60 @@
+import { iconSourceVariants } from './icon-source-variants'
+
+// Keep common names used by existing Dory documents working after the icon migration.
+const aliases: Record<string, string> = {
+  activity: 'progress',
+  'alert-triangle': 'warning',
+  'bar-chart': 'chart',
+  box: 'packages',
+  'chart-column': 'chart',
+  'chevrons-down-up': 'up-down',
+  'circle-alert': 'alert-circle',
+  'circle-check': 'check-circle',
+  'code-2': 'code',
+  'columns-2': 'columns',
+  'columns-3': 'columns',
+  'file-json': 'file-code',
+  'external-link': 'external',
+  github: 'code',
+  'git-branch': 'branch',
+  'git-fork': 'branch',
+  'git-pull-request': 'branch',
+  hammer: 'settings',
+  image: 'file-image',
+  'layout-dashboard': 'dashboard',
+  layers: 'layout',
+  'list-ordered': 'list',
+  'message-square': 'chat',
+  'maximize-2': 'fullscreen',
+  map: 'globe',
+  package: 'packages',
+  palette: 'layout',
+  'play-circle': 'play',
+  'share-2': 'share',
+  'settings-2': 'settings',
+  'shield-check': 'shield',
+  'sliders-horizontal': 'sliders',
+  sparkles: 'ai',
+  'square-terminal': 'terminal',
+  plug: 'integration',
+  tag: 'price-tag',
+  heart: 'star',
+  rocket: 'promote',
+  zap: 'bolt',
+}
+
+function normalize(name: string) {
+  const kebab = name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/_/g, '-').toLowerCase()
+  return aliases[kebab] ?? kebab
+}
+
+/** Compatibility names accepted by Dory's MDX Icon component. */
+export function resolveIconName(name: string): string {
+  const [source, sourceName] = name.split('/', 2)
+  if (sourceName) {
+    if (source !== 'community' && source !== 'enterprise-core' && source !== 'enterprise') return name
+    const normalized = normalize(sourceName)
+    return iconSourceVariants[`${source}/${normalized}`] ?? normalized
+  }
+  return normalize(name)
+}

package/src/mdx/icon-source-variants.ts

@@ -0,0 +1,102 @@
+/** Published UX names for source-specific variants in the older Dory icon API. */
+export const iconSourceVariants: Record<string, string> = {
+  'enterprise-core/banknotes': 'banknotes-alt',
+  'enterprise-core/calendar': 'calendar-alt',
+  'enterprise-core/check-circle': 'check-circle-alt',
+  'enterprise-core/chevron-down': 'chevron-down-alt',
+  'enterprise-core/chevron-left': 'chevron-left-alt',
+  'enterprise-core/chevron-right': 'chevron-right-alt',
+  'enterprise-core/chevron-up': 'chevron-up-alt',
+  'enterprise-core/clock': 'clock-alt',
+  'enterprise-core/code': 'code-alt',
+  'enterprise-core/copy': 'copy-alt',
+  'enterprise-core/download': 'download-alt',
+  'enterprise-core/file-text': 'file-text-alt',
+  'enterprise-core/globe': 'globe-alt',
+  'enterprise-core/grid': 'grid-alt',
+  'enterprise-core/hash': 'hash-alt',
+  'enterprise-core/help': 'help-alt',
+  'enterprise-core/home': 'home-alt',
+  'enterprise-core/list': 'list-alt',
+  'enterprise-core/mail': 'mail-alt',
+  'enterprise-core/moon': 'moon-alt',
+  'enterprise-core/play': 'play-alt',
+  'enterprise-core/plus': 'plus-alt',
+  'enterprise-core/plus-circle': 'plus-circle-alt',
+  'enterprise-core/search': 'search-alt',
+  'enterprise-core/secret': 'secret-alt',
+  'enterprise-core/settings': 'settings-alt',
+  'enterprise-core/sidebar': 'sidebar-alt',
+  'enterprise-core/signout': 'signout-alt',
+  'enterprise-core/source': 'source-alt',
+  'enterprise-core/sun': 'sun-alt',
+  'enterprise-core/trash': 'trash-alt',
+  'enterprise-core/upload': 'upload-alt',
+  'enterprise/arrow-right': 'arrow-right-alt',
+  'enterprise/bag': 'bag-alt',
+  'enterprise/bell': 'bell-alt',
+  'enterprise/calculator': 'calculator-alt',
+  'enterprise/calendar': 'calendar-alt-2',
+  'enterprise/card': 'card-alt',
+  'enterprise/chat': 'chat-alt',
+  'enterprise/check': 'check-alt',
+  'enterprise/checkbox': 'select-all',
+  'enterprise/chevron-down': 'chevron-down-alt-2',
+  'enterprise/chevron-left': 'chevron-left-alt-2',
+  'enterprise/chevron-right': 'chevron-right-alt-2',
+  'enterprise/chevron-up': 'chevron-up-alt-2',
+  'enterprise/clipboard': 'clipboard-alt',
+  'enterprise/clock': 'clock-alt-2',
+  'enterprise/close': 'close-alt',
+  'enterprise/cloud': 'cloud-alt',
+  'enterprise/columns': 'columns-alt',
+  'enterprise/copy': 'copy-alt-2',
+  'enterprise/customer': 'user',
+  'enterprise/dashboard': 'dashboard-alt',
+  'enterprise/download': 'download-alt-2',
+  'enterprise/edit': 'edit-alt',
+  'enterprise/external': 'external-alt',
+  'enterprise/eye': 'eye-alt',
+  'enterprise/eye-off': 'eye-off-alt',
+  'enterprise/file': 'file-alt',
+  'enterprise/file-text': 'file-text-alt-2',
+  'enterprise/filter': 'filter-alt',
+  'enterprise/folder': 'folder-alt',
+  'enterprise/formula': 'formula-alt',
+  'enterprise/globe': 'globe-alt-2',
+  'enterprise/group': 'folder-alt',
+  'enterprise/hash': 'hash-alt-2',
+  'enterprise/help': 'help-alt-2',
+  'enterprise/home': 'home-alt-2',
+  'enterprise/info': 'info-alt',
+  'enterprise/link': 'link-alt',
+  'enterprise/lock': 'lock-alt',
+  'enterprise/mail': 'mail-alt-2',
+  'enterprise/menu': 'menu-alt',
+  'enterprise/minus': 'minus-alt',
+  'enterprise/monitor': 'monitor-alt',
+  'enterprise/moon': 'moon-alt-2',
+  'enterprise/more-v': 'more-v-alt',
+  'enterprise/order': 'order-alt',
+  'enterprise/plus': 'plus-alt-2',
+  'enterprise/redo': 'redo-alt',
+  'enterprise/refresh': 'refresh-alt',
+  'enterprise/save': 'save-alt',
+  'enterprise/scan': 'scan-alt',
+  'enterprise/search': 'search-alt-2',
+  'enterprise/send': 'send-alt',
+  'enterprise/settings': 'settings-alt-2',
+  'enterprise/share': 'share-alt',
+  'enterprise/sidebar': 'sidebar-alt-2',
+  'enterprise/sliders': 'sliders-alt',
+  'enterprise/star': 'star-alt',
+  'enterprise/store': 'store-alt',
+  'enterprise/sun': 'sun-alt-2',
+  'enterprise/table': 'table-alt',
+  'enterprise/toggle': 'toggle-alt',
+  'enterprise/trash': 'trash-alt-2',
+  'enterprise/undo': 'undo-alt',
+  'enterprise/upload': 'upload-alt-2',
+  'enterprise/users': 'users-alt',
+  'enterprise/warning': 'warning-alt',
+}

package/src/mdx/icon.tsx

@@ -1,80 +1,19 @@
-import { library } from '@fortawesome/fontawesome-svg-core'
-import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
-import * as solidIcons from '@fortawesome/free-solid-svg-icons'
-import * as regularIcons from '@fortawesome/free-regular-svg-icons'
-import * as brandIcons from '@fortawesome/free-brands-svg-icons'
+import { CatalogIcon } from '@clidey/ux'
+import { resolveIconName } from './icon-names'
 import classNames from 'classnames'
-import * as LucideIcons from 'lucide-react'
 
-// Map types to icon sets and FontAwesome prefixes
-const iconSets = {
-  solid: solidIcons,
-  regular: regularIcons,
-  brands: brandIcons,
-}
-
-const prefixes = {
-  solid: 'fas',
-  regular: 'far',
-  brands: 'fab',
-} as const
-
-export function Icon({
-  icon,
-  iconType = 'solid',
-  color = '',
-  size = 24,
-  className,
-  ...rest
-}: {
+export function Icon({ icon, color, size = 24, className, style, ...rest }: {
   icon: string
-  iconType?: keyof typeof iconSets
   color?: string
   size?: number
 } & Omit<React.ComponentPropsWithoutRef<'svg'>, 'color'>) {
-  // Convert kebab-case or snake_case to PascalCase (for Lucide and FA variable names)
-  const pascalCase = icon
-    .replace(/[-_](.)/g, (_, group1) => group1.toUpperCase())
-    .replace(/^(.)/, (_, group1) => group1.toUpperCase())
-
-  // --- Try Lucide First ---
-  const LucideComponent = LucideIcons[pascalCase as keyof typeof LucideIcons] as any
-  if (LucideComponent) {
-    return (
-      <LucideComponent
-        className={classNames("inline-block align-[-0.2em] stroke-black dark:stroke-white", className)}
-        color={color}
-        size={size}
-        {...rest}
-      />
-    )
-  }
-
-  // --- Try Font Awesome ---
-  // Fall back to the brands set: Lucide 1.x removed all brand icons
-  // (github, twitter, npm, ...), which live only in FA brands.
-  const iconKey = `fa${pascalCase}`
-  const setsToTry: Array<keyof typeof iconSets> =
-    iconType === 'brands' ? ['brands'] : [iconType, 'brands']
-
-  for (const setName of setsToTry) {
-    const faSet = iconSets[setName] ?? solidIcons
-    const faIcon = faSet[iconKey as keyof typeof faSet]
-
-    if (faIcon && typeof faIcon === 'object' && 'iconName' in faIcon) {
-      library.add(faIcon)
-      return (
-        <FontAwesomeIcon
-          icon={[prefixes[setName] || 'fas', faIcon.iconName] as any}
-          className={classNames("inline-block align-[-0.2em] stroke-black dark:stroke-white", className)}
-          color={color as any}
-          size={size as any}
-          {...rest as any}
-        />
-      )
-    }
-  }
-
-  console.warn(`⚠️ Icon not found: "${icon}" (converted to ${iconKey}) in ${iconType}`)
-  return null // or return a default/fallback icon if preferred
+  return (
+    <CatalogIcon
+      name={resolveIconName(icon)}
+      style={{ color, ...(typeof style === 'object' && style !== null ? style : {}) }}
+      size={size}
+      className={classNames('inline-block align-[-0.2em]', className)}
+      {...rest}
+    />
+  )
 }

package/src/mdx/latex.tsx

@@ -1,4 +1,5 @@
-import { ExclamationTriangleIcon } from '@heroicons/react/24/outline'
+import { CatalogIcon } from '@clidey/ux'
+
 import { useEffect, useRef, useState } from 'react'
 
 function extractText(node: React.ReactNode): string {
@@ -73,7 +74,7 @@ export function Latex({ children, inline = false }: LatexProps) {
       <div className="my-4">
         <div className="flex flex-col items-center justify-center py-12 px-6 text-center bg-gradient-to-br from-red-50 to-red-100 dark:from-red-900/20 dark:to-red-800/20 border-2 border-dashed border-red-300 dark:border-red-700 rounded-lg">
           <div className="w-16 h-16 mb-4 flex items-center justify-center bg-red-100 dark:bg-red-900/30 rounded-full">
-            <ExclamationTriangleIcon className="w-8 h-8 text-red-500" />
+            <CatalogIcon name="warning" className="w-8 h-8 text-red-500" />
           </div>
           <h3 className="text-lg font-semibold text-red-700 dark:text-red-300 mb-2">
             LaTeX Rendering Error

package/src/mdx/mdx.tsx

@@ -22,7 +22,7 @@ export { UnorderedList as ul, OrderedList as ol, ListItem as li } from './list';
 export { UnorderedList, OrderedList, ListItem } from './list';
 export { AsyncAPI } from './async-api';
 export { Source } from './source';
-export { Specimen, SpecimenProps } from './specimen';
+export { Specimen, SpecimenProps, Prop } from './specimen';
 export { Chip, ChipGroup } from './chip';
 export { Tabs, Tab } from './tabs';
 export { IconGrid } from './icon-grid';

package/src/mdx/mermaid.tsx

@@ -1,4 +1,5 @@
-import { ExclamationTriangleIcon } from '@heroicons/react/24/outline'
+import { CatalogIcon } from '@clidey/ux'
+
 import classNames from 'classnames'
 import { useEffect, useMemo, useRef, useState } from 'preact/compat'
 
@@ -31,7 +32,7 @@ function paletteThemeVariables() {
     const v = (name: string) => css.getPropertyValue(name).trim()
     return {
         fontFamily: v('--font-body') || 'inherit',
-        fontSize: '13px',
+        fontSize: '14px',
         background: v('--card'),
         mainBkg: v('--accent'),
         primaryColor: v('--accent'),
@@ -114,6 +115,9 @@ export function MermaidRenderer({ content }: { content: string }) {
         let mounted = true
 
         const renderMermaid = async () => {
+            setError(null)
+            setIsValid(null)
+            setIsLoaded(false)
             try {
                 const mermaid = (await import('mermaid')).default
                 
@@ -122,6 +126,7 @@ export function MermaidRenderer({ content }: { content: string }) {
                 mermaid.initialize({
                     startOnLoad: false,
                     theme: 'base',
+                    look: 'classic',
                     themeVariables: paletteThemeVariables(),
                     flowchart: {
                         nodeSpacing: 50,
@@ -164,7 +169,6 @@ export function MermaidRenderer({ content }: { content: string }) {
             } catch (err) {
                 console.error('Mermaid rendering error:', err)
                 if (mounted) {
-                    setIsValid(false)
                     setError(err instanceof Error ? err.message : 'Failed to render diagram')
                 }
             }
@@ -186,13 +190,15 @@ export function MermaidRenderer({ content }: { content: string }) {
             <div className="mermaid-wrapper my-8">
                 <div className="flex flex-col items-center justify-center py-12 px-6 text-center bg-gradient-to-br from-red-50 to-red-100 dark:from-red-900/20 dark:to-red-800/20 border-2 border-dashed border-red-300 dark:border-red-700 rounded-lg">
                     <div className="w-16 h-16 mb-4 flex items-center justify-center bg-red-100 dark:bg-red-900/30 rounded-full">
-                        <ExclamationTriangleIcon className="w-8 h-8 text-red-500" />
+                        <CatalogIcon name="warning" className="w-8 h-8 text-red-500" />
                     </div>
                     <h3 className="text-lg font-semibold text-red-700 dark:text-red-300 mb-2">
-                        Diagram Syntax Error
+                        {isValid === false ? 'Diagram Syntax Error' : 'Diagram Load Error'}
                     </h3>
                     <p className="text-red-600 dark:text-red-400 mb-4 max-w-md">
-                        The Mermaid diagram contains invalid syntax and cannot be rendered.
+                        {isValid === false
+                            ? 'The Mermaid diagram contains invalid syntax and cannot be rendered.'
+                            : 'The diagram could not be loaded. Please reload the page.'}
                     </p>
                     <div className="bg-red-50 dark:bg-red-900/30 border border-red-200 dark:border-red-800 rounded-md p-3 max-w-md">
                         <p className="text-sm text-red-700 dark:text-red-300 font-mono break-all">

package/src/mdx/open-api.tsx

@@ -1,12 +1,13 @@
-import { Button, Sheet, SheetContent, SheetHeader, SheetTitle } from "@clidey/ux"
+import { CatalogIcon, Button } from "@clidey/ux"
 import classNames from "classnames"
-import { Check, ChevronRight, Copy, Play } from "lucide-react"
+
 import { h } from "preact"
 import { useState } from "preact/hooks"
-import { APIPlayground, type Server } from "./api-playground"
+import type { Server } from "./api-playground"
 import { CodeFrame, CodeGroup } from "./code"
 import { Fence, Pre } from "./fence"
 import { Tag } from "./tag"
+import { TryItPanel, type TryItField } from "./try-it-panel"
 
 // ---------------------------------------------------------------------------
 // Field list used by the API pages and exposed to MDX as Properties/Property.
@@ -178,6 +179,11 @@ function exampleOf(schema: Schema, depth = 0): unknown {
   }
 }
 
+/** Short type for a form field: `enum` rather than `enum<string>`. */
+function fieldType(schema: Schema): string {
+  return schema.enum ? 'enum' : schema.type ?? 'object'
+}
+
 function describeDefault(schema: Schema, description?: string): string | undefined {
   if (description) return description
   if (schema.description) return schema.description
@@ -223,17 +229,17 @@ function ChildAttributes({ schema, components }: { schema: Schema; components: C
   const count = Object.keys(schema.properties ?? {}).length
   if (count === 0) return null
   return (
-    <div className="mt-3">
+    <div className="mt-3 overflow-hidden rounded-lg border border-[var(--border)]">
       <button
         type="button"
         onClick={() => setOpen((v) => !v)}
         aria-expanded={open}
-        className="flex w-full items-center gap-2 rounded-lg border border-[var(--border)] bg-muted px-4 py-2.5 text-left text-sm font-medium text-foreground"
+        className="flex w-full items-center gap-2 bg-muted px-4 py-2.5 text-left text-sm font-medium text-foreground"
       >
-        <ChevronRight aria-hidden="true" className={classNames('h-3.5 w-3.5 transition-transform', { 'rotate-90': open })} />
+        <CatalogIcon name="chevron-right" aria-hidden="true" className={classNames('h-3.5 w-3.5 transition-transform', { 'rotate-90': open })} />
         {open ? 'Hide' : 'Show'} {count} child attribute{count === 1 ? '' : 's'}
       </button>
-      {open && <div className="pl-4"><SchemaFields schema={schema} components={components} /></div>}
+      {open && <div className="px-4"><SchemaFields schema={schema} components={components} /></div>}
     </div>
   )
 }
@@ -247,7 +253,7 @@ function CopyUrl({ value }: { value: string }) {
       onClick={() => navigator.clipboard.writeText(value).then(() => { setCopied(true); setTimeout(() => setCopied(false), 1000) })}
       className="rounded-md p-1.5 text-muted-foreground transition hover:bg-muted hover:text-foreground"
     >
-      {copied ? <Check className="h-3.5 w-3.5" /> : <Copy className="h-3.5 w-3.5" />}
+      {copied ? <CatalogIcon name="check" className="h-3.5 w-3.5" /> : <CatalogIcon name="copy" className="h-3.5 w-3.5" />}
     </button>
   )
 }
@@ -299,6 +305,32 @@ function ResponseTabs({ responses, components }: { responses: PathMethod['respon
   )
 }
 
+// Longest line of the cURL `-d` body before it continues on the next line.
+const CURL_BODY_WIDTH = 44
+
+/** `-d` lines for cURL, breaking a flat JSON object across lines so it reads without wrapping. */
+function curlBody(body: unknown): string[] {
+  const json = JSON.stringify(body)
+  if (body === null || typeof body !== 'object' || Array.isArray(body) || json.length <= CURL_BODY_WIDTH) {
+    return [`  -d '${json}'`]
+  }
+  const lines: string[] = []
+  let line = ''
+  for (const [key, value] of Object.entries(body)) {
+    const entry = `${JSON.stringify(key)}:${JSON.stringify(value)}`
+    if (line && line.length + entry.length + 1 > CURL_BODY_WIDTH) {
+      lines.push(`${line},`)
+      line = entry
+    } else {
+      line = line ? `${line},${entry}` : entry
+    }
+  }
+  lines.push(line)
+  return lines.map((text, index) =>
+    `${index === 0 ? "  -d '{" : '      '}${text}${index === lines.length - 1 ? "}'" : ''}`
+  )
+}
+
 /** cURL / JavaScript / Python samples generated from the operation. */
 function RequestSamples({ method, url, headers, body }: { method: string; url: string; headers: Record<string, string>; body?: unknown }) {
   const headerLines = Object.entries(headers)
@@ -306,7 +338,7 @@ function RequestSamples({ method, url, headers, body }: { method: string; url: s
   const curl = [
     `curl -X ${method} ${url} \\`,
     ...headerLines.map(([key, value]) => `  -H "${key}: ${value}" \\`),
-    ...(json ? [`  -d '${json}'`] : []),
+    ...(json ? curlBody(body) : []),
   ].join('\n').replace(/ \\$/, '')
   const js = [
     `const response = await fetch("${url}", {`,
@@ -384,20 +416,39 @@ export function OpenAPI({ openAPIJson, method: selectedMethod, path: selectedPat
   }
   if (bodySchema) headers['Content-Type'] = 'application/json'
 
+  const parameterFields: TryItField[] = parameters.flatMap((param) => {
+    if (param.in === 'cookie') return []
+    const schema = resolveSchema(param.schema, components)
+    const value = schema.example ?? schema.default
+    return [{ name: param.name, type: fieldType(schema), value: value === undefined ? '' : String(value), in: param.in ?? 'query' }]
+  })
+  const bodyFields: TryItField[] = Object.entries(bodySchema?.properties ?? {}).map(([name, raw]) => {
+    const schema = resolveSchema(raw, components)
+    const value = exampleOf(schema)
+    return { name, type: fieldType(schema), value: typeof value === 'string' ? value : JSON.stringify(value) }
+  })
+  const authInputs: TryItField[] = schemes.flatMap((scheme) => {
+    const header = authHeader(scheme)
+    if (!header) return []
+    return [{ name: header[0], type: 'header', value: header[1].replace(/\$\w+$/, '') }]
+  })
+
   return (
     <div className="dory-api max-w-none w-full">
-      <Sheet open={showPlayground} onOpenChange={setShowPlayground} modal={true}>
-        <SheetContent side="bottom" className="h-[90vh] w-full overflow-y-auto p-8">
-          <SheetHeader className="p-0">
-            <SheetTitle>API Playground</SheetTitle>
-          </SheetHeader>
-          <APIPlayground method={selectedMethod} url={selectedPath} servers={openAPIJson.servers} />
-        </SheetContent>
-      </Sheet>
-
-      {operation.description && <p className="dory-lead -mt-4 mb-6">{operation.description}</p>}
-
-      <div className="not-prose flex items-center gap-3 rounded-lg border border-[var(--border)] bg-card py-2 pl-3 pr-2">
+      <TryItPanel
+        open={showPlayground}
+        onOpenChange={setShowPlayground}
+        method={selectedMethod}
+        path={selectedPath}
+        servers={openAPIJson.servers ?? []}
+        parameters={parameterFields}
+        body={bodyFields}
+        auth={authInputs}
+      />
+
+      {operation.description && <p className="dory-lead -mt-4! mb-6">{operation.description}</p>}
+
+      <div className="not-prose flex max-w-[45rem] items-center gap-3 rounded-lg border border-[var(--border)] bg-card py-2 pl-3 pr-2">
         <Tag>{selectedMethod}</Tag>
         <span className="min-w-0 flex-1 truncate font-mono text-sm">
           <span className="text-muted-foreground">{serverUrl}</span>
@@ -405,63 +456,68 @@ export function OpenAPI({ openAPIJson, method: selectedMethod, path: selectedPat
         </span>
         <CopyUrl value={fullUrl} />
         <Button onClick={() => setShowPlayground(true)} className="flex items-center gap-1.5 bg-[var(--primary)] text-white hover:bg-[var(--primary)]/90">
-          <Play className="h-3 w-3 fill-current" />
+          <CatalogIcon name="play" className="h-3 w-3 fill-current" />
           Try it
         </Button>
       </div>
 
-      {schemes.length > 0 && (
-        <>
-          <SectionTitle>Authorization</SectionTitle>
-          <Properties>
-            {schemes.map((scheme, index) => {
-              const header = authHeader(scheme)
-              const name = header?.[0] ?? scheme.name ?? scheme.type
-              const location = scheme.type === 'apiKey' ? scheme.in ?? 'header' : 'header'
-              return (
-                <Property key={index} name={name} type={`${location} · string`} required>
-                  {scheme.description ?? (scheme.type === 'http' ? `${scheme.scheme === 'basic' ? 'Basic' : 'Bearer'} token.` : 'API key.')}
-                </Property>
-              )
-            })}
-          </Properties>
-        </>
-      )}
-
-      {parameters.length > 0 && (
-        <>
-          <SectionTitle>Parameters</SectionTitle>
-          <Properties>
-            {parameters.map((param) => {
-              const schema = resolveSchema(param.schema, components)
-              return (
-                <Property key={`${param.in}-${param.name}`} name={param.name} type={`${param.in ?? 'query'} · ${typeLabel(schema)}`} required={param.required} defaultValue={schema.default}>
-                  {describeDefault(schema, param.description)}
-                </Property>
-              )
-            })}
-          </Properties>
-        </>
-      )}
-
-      {bodySchema && (
-        <>
-          <SectionTitle note="application/json">Body</SectionTitle>
-          {operation.requestBody?.description && <p className="mt-2 text-sm text-muted-foreground">{operation.requestBody.description}</p>}
-          <SchemaFields schema={bodySchema} components={components} />
-        </>
-      )}
-
-      {responseSchema && (
-        <>
-          <SectionTitle>Response</SectionTitle>
-          <SchemaFields schema={responseSchema} components={components} />
-        </>
-      )}
-
-      <div className="mt-8">
-        <RequestSamples method={selectedMethod} url={fullUrl} headers={headers} body={bodySchema ? exampleOf(bodySchema) : undefined} />
-        <ResponseTabs responses={operation.responses} components={components} />
+      <div className="grid gap-x-12 xl:grid-cols-[minmax(0,1fr)_29rem]">
+        <div className="min-w-0">
+          {schemes.length > 0 && (
+            <>
+              <SectionTitle>Authorization</SectionTitle>
+              <Properties>
+                {schemes.map((scheme, index) => {
+                  const header = authHeader(scheme)
+                  const name = header?.[0] ?? scheme.name ?? scheme.type
+                  const location = scheme.type === 'apiKey' ? scheme.in ?? 'header' : 'header'
+                  return (
+                    <Property key={index} name={name} type={`${location} · string`} required>
+                      {scheme.description ?? (scheme.type === 'http' ? `${scheme.scheme === 'basic' ? 'Basic' : 'Bearer'} token.` : 'API key.')}
+                    </Property>
+                  )
+                })}
+              </Properties>
+            </>
+          )}
+
+          {parameters.length > 0 && (
+            <>
+              <SectionTitle>Parameters</SectionTitle>
+              <Properties>
+                {parameters.map((param) => {
+                  const schema = resolveSchema(param.schema, components)
+                  return (
+                    <Property key={`${param.in}-${param.name}`} name={param.name} type={`${param.in ?? 'query'} · ${typeLabel(schema)}`} required={param.required} defaultValue={schema.default}>
+                      {describeDefault(schema, param.description)}
+                    </Property>
+                  )
+                })}
+              </Properties>
+            </>
+          )}
+
+          {bodySchema && (
+            <>
+              <SectionTitle note="application/json">Body</SectionTitle>
+              {operation.requestBody?.description && <p className="mt-2 text-sm text-muted-foreground">{operation.requestBody.description}</p>}
+              <SchemaFields schema={bodySchema} components={components} />
+            </>
+          )}
+
+          {responseSchema && (
+            <>
+              <SectionTitle>Response</SectionTitle>
+              <SchemaFields schema={responseSchema} components={components} />
+            </>
+          )}
+        </div>
+
+        {/* Samples sit beside the fields on wide screens and follow the reader down the page. */}
+        <aside className="mt-10 min-w-0 xl:sticky xl:top-20 xl:self-start">
+          <RequestSamples method={selectedMethod} url={fullUrl} headers={headers} body={bodySchema ? exampleOf(bodySchema) : undefined} />
+          <ResponseTabs responses={operation.responses} components={components} />
+        </aside>
       </div>
     </div>
   )

package/src/mdx/preprocess.test.ts

@@ -0,0 +1,16 @@
+import { expect, test } from 'vitest';
+import { preprocessMdxSource } from './preprocess';
+
+test('page title is rendered by the page frame without repeating in MDX', () => {
+  const result = preprocessMdxSource('---\ntitle: "Installation"\n---\n# Installation\n\n## Setup\nInstall it.');
+  expect(result).not.toMatch(/^# Installation$/m);
+  expect(result).toContain('## Setup');
+  expect(result).toContain('Install it.');
+});
+
+test('keeps code examples, distinct headings and pages without a frontmatter title', () => {
+  const result = preprocessMdxSource('---\ntitle: Guide\n---\n```md\n# Guide\n```\n# A different heading');
+  expect(result).toContain('```md\n# Guide\n```');
+  expect(result).toContain('# A different heading');
+  expect(preprocessMdxSource('# Guide')).toContain('# Guide');
+});