@clidey/dory 1.0.8 → 1.10.0

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

package/src/mdx/preprocess.ts

@@ -0,0 +1,61 @@
+import { preprocessMdxTags } from '../plugins/sanitize.ts';
+
+/** Browser-safe preprocessing shared by the static build and embedded runtime. */
+export function preprocessMdxSource(content: string, fileName = 'content.mdx', importedComponents: readonly string[] = []): string {
+  let processed = content;
+  const frontmatter = processed.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (frontmatter) processed = processed.slice(frontmatter[0].length);
+
+  // The page frame already renders the frontmatter title. Remove only its
+  // matching Markdown heading; headings in examples and other titles survive.
+  const rawTitle = frontmatter?.[1].match(/^title:\s*(.+?)\s*$/m)?.[1];
+  let title = rawTitle;
+  if (rawTitle?.startsWith('"')) {
+    try { title = JSON.parse(rawTitle) as string; } catch { /* Keep unfamiliar YAML unchanged. */ }
+  } else if (rawTitle?.startsWith("'") && rawTitle.endsWith("'")) {
+    title = rawTitle.slice(1, -1).replace(/''/g, "'");
+  }
+  if (title) {
+    let fence = '';
+    let removed = false;
+    processed = processed.split('\n').filter(line => {
+      const delimiter = line.trim().match(/^(`{3,}|~{3,})/);
+      if (delimiter) {
+        if (!fence) fence = delimiter[1];
+        else if (delimiter[1][0] === fence[0] && delimiter[1].length >= fence.length) fence = '';
+        return true;
+      }
+      if (fence || removed) return true;
+      const heading = line.match(/^#\s+(.+?)\s*#*\s*$/);
+      if (heading?.[1] !== title) return true;
+      removed = true;
+      return false;
+    }).join('\n');
+  }
+
+  const strayYaml = processed.match(/^```yaml\n([\s\S]*?)\n---\n?/);
+  if (strayYaml) processed = processed.slice(strayYaml[0].length);
+
+  const transformed = preprocessMdxTags(importedComponents).transform(processed, fileName);
+  processed = typeof transformed === 'string' ? transformed : transformed?.code ?? processed;
+
+  let inCodeBlock = false;
+  return processed.split('\n').map(line => {
+    if (line.trim().startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+      return line;
+    }
+    if (inCodeBlock) return line;
+
+    let output = '';
+    let lastIndex = 0;
+    const inlineCode = /`([^`]+)`/g;
+    let match: RegExpExecArray | null;
+    while ((match = inlineCode.exec(line)) !== null) {
+      output += line.slice(lastIndex, match.index).replace(/<(https?:\/\/[^\s>]+)>/g, '[$1]($1)');
+      output += match[0];
+      lastIndex = match.index + match[0].length;
+    }
+    return output + line.slice(lastIndex).replace(/<(https?:\/\/[^\s>]+)>/g, '[$1]($1)');
+  }).join('\n');
+}

package/src/mdx/processor.test.ts

@@ -1,47 +1,145 @@
-import { describe, it, expect } from 'vitest';
-import { preprocessMdxContent } from './processor';
+import { describe, it, expect, test } from 'vitest';
+import { preprocessMdxContent, processMdxContent } from './processor';
+import { preprocessMdxSource } from './preprocess';
 
-async function run(input: string): Promise<string> {
-  const result = await preprocessMdxContent(input);
+const source = `import Demo, { Button as DemoButton } from './example.tsx';
+import * as Controls from './controls.tsx';
+
+<Demo />
+<DemoButton>Try it</DemoButton>
+<Controls.Toggle />
+`;
+
+test('trusted static MDX preserves default, aliased and namespace component imports', async () => {
+  const result = await processMdxContent(source);
+  expect(result.success).toBe(true);
+  expect(result.processedContent).toContain('<Demo />');
+  expect(result.processedContent).toContain('<DemoButton>Try it</DemoButton>');
+  expect(result.processedContent).toContain('<Controls.Toggle />');
+  expect(result.processedContent).not.toContain('`<Demo');
+});
+
+test('imports shown in code fences do not authorize unknown JSX components', async () => {
+  const result = await preprocessMdxContent("```tsx\nimport Demo from './example.tsx';\n```\n\n<Demo />");
   expect(result.success).toBe(true);
-  return result.processedContent!;
-}
+  expect(result.processedContent).toContain('`<Demo />`');
+});
+
+test('unimported components keep the existing text behavior in static MDX', async () => {
+  const result = await preprocessMdxContent("import Demo from './example.tsx';\n\n<Demo />\n<Unregistered />");
+  expect(result.processedContent).toContain('<Demo />');
+  expect(result.processedContent).toContain('`<Unregistered />`');
+});
+
+test('embedded preprocessing does not trust component names from MDX imports', () => {
+  const result = preprocessMdxSource(source);
+  expect(result).toContain('`<Demo />`');
+  expect(result).toContain('`<Controls.Toggle />`');
+});
+
+test('malformed import syntax reports a compile error instead of bypassing preprocessing', async () => {
+  const result = await preprocessMdxContent('import { Broken from "./example.tsx";\n\n<Broken />');
+  expect(result.success).toBe(false);
+  expect(result.error).toBeInstanceOf(Error);
+});
+
+
+test('imported components with props coexist with nested JSX and prose placeholders', async () => {
+  const result = await processMdxContent(`import Demo, { Child } from './example.tsx';
+
+<Demo start={0}><Child /></Demo>
+
+Replace <token> with your key.
+`);
+  expect(result.success).toBe(true);
+  expect(result.processedContent).toContain('<Demo start={0}><Child /></Demo>');
+});
+
+test('multiline imports work while tilde-fenced imports stay inert', async () => {
+  const result = await processMdxContent(`import {
+  Button as DemoButton,
+} from './example.tsx';
+
+<DemoButton>Try it</DemoButton>
 
-describe('preprocessMdxContent', () => {
+~~~tsx
+import Unregistered from './other.tsx';
+~~~
+
+<Unregistered />
+`);
+  expect(result.success).toBe(true);
+  expect(result.processedContent).toContain('<DemoButton>Try it</DemoButton>');
+  expect(result.processedContent).toContain('`<Unregistered />`');
+});
+
+
+describe('existing preprocessing behavior', () => {
   it('strips YAML frontmatter', async () => {
-    const output = await run('---\ntitle: Hello\n---\n# Heading\n');
-    expect(output).not.toContain('title: Hello');
-    expect(output).toContain('# Heading');
+    const result = await preprocessMdxContent('---\ntitle: Hello\n---\n# Heading\n');
+    expect(result.success).toBe(true);
+    expect(result.processedContent).not.toContain('title: Hello');
+    expect(result.processedContent).toContain('# Heading');
   });
-
-  it('converts URLs in angle brackets to markdown links', async () => {
-    const output = await run('Visit <https://example.com/docs> now');
-    expect(output).toBe('Visit [https://example.com/docs](https://example.com/docs) now');
+  it('converts angle bracket URLs while preserving fenced and inline code', async () => {
+    const result = await preprocessMdxContent('Visit <https://example.com/docs> now');
+    expect(result.processedContent).toBe('Visit [https://example.com/docs](https://example.com/docs) now');
+    const fenced = '```\ncurl <https://example.com>\n```\n';
+    expect((await preprocessMdxContent(fenced)).processedContent).toBe(fenced);
+    const inline = 'Use `<https://example.com>` here';
+    expect((await preprocessMdxContent(inline)).processedContent).toBe(inline);
   });
+});
 
-  it('preserves angle-bracket URLs inside fenced code blocks', async () => {
-    const input = '```\ncurl <https://example.com>\n```\n';
-    expect(await run(input)).toBe(input);
-  });
+test('preserves original fence-state behavior across multiple code blocks', async () => {
+  const input = ['```', '<https://in-block.com>', '```', '<https://outside.com>', '```', '<https://in-block-2.com>', '```'].join('\n');
+  const result = await preprocessMdxContent(input);
+  expect(result.success).toBe(true);
+  expect(result.processedContent).toContain('<https://in-block.com>');
+  expect(result.processedContent).toContain('<https://in-block-2.com>');
+  expect(result.processedContent).toContain('[https://outside.com](https://outside.com)');
+});
 
-  it('preserves angle-bracket URLs inside inline code', async () => {
-    const input = 'run `curl <https://example.com>` locally';
-    expect(await run(input)).toBe(input);
-  });
 
-  it('tracks code-block state across multiple fences', async () => {
-    const input = [
-      '```',
-      '<https://in-block.com>',
-      '```',
-      '<https://outside.com>',
-      '```',
-      '<https://in-block-2.com>',
-      '```',
-    ].join('\n');
-    const output = await run(input);
-    expect(output).toContain('<https://in-block.com>');
-    expect(output).toContain('<https://in-block-2.com>');
-    expect(output).toContain('[https://outside.com](https://outside.com)');
-  });
+test('comments, multiline code spans and exported strings do not register fake imports', async () => {
+  for (const prefix of [
+    "{/*\nimport Demo from './demo.tsx';\n*/}",
+    "`example\nimport Demo from './demo.tsx';\nexample`",
+    "export const example = `\nimport Demo from './demo.tsx';\n`;",
+  ]) {
+    const result = await preprocessMdxContent(prefix + '\n\n<Demo />');
+    expect(result.success).toBe(true);
+    expect(result.processedContent).toContain('`<Demo />`');
+  }
+});
+
+test('import-looking prose without an MDX ESM declaration does not register names', async () => {
+  const result = await processMdxContent("import\nDemo from './demo.tsx';\n\n<Demo />");
+  expect(result.success).toBe(true);
+  expect(result.processedContent).toContain('`<Demo />`');
+});
+
+
+test('provisional names are AST-verified alongside real JSX with props', async () => {
+  const input = [
+    "import Real from './real.tsx';",
+    '',
+    '<Real count={0}>Try it</Real>',
+    '',
+    '{/*',
+    "import Fake from './fake.tsx';",
+    '*/}',
+    '',
+    'export const example = `',
+    "import StringFake from './fake.tsx';",
+    '`;',
+    '',
+    '<Fake />',
+    '<StringFake />',
+  ].join('\n');
+  const result = await processMdxContent(input);
+  expect(result.success).toBe(true);
+  expect(result.processedContent).toContain('<Real count={0}>Try it</Real>');
+  expect(result.processedContent).toContain('`<Fake />`');
+  expect(result.processedContent).toContain('`<StringFake />`');
 });