@clidey/dory 1.0.8 → 1.10.0

package/src/mdx/processor.ts

@@ -1,6 +1,6 @@
-import { compile } from '@mdx-js/mdx';
-import { preprocessMdxTags } from '../plugins/sanitize';
-import { getMdxConfig } from '../config/mdx';
+import { compile, createProcessor } from '@mdx-js/mdx';
+import { preprocessMdxSource } from './preprocess.ts';
+import { getMdxConfig } from '../config/mdx.ts';
 
 export interface ProcessMdxOptions {
   isDevelopment?: boolean;
@@ -25,101 +25,63 @@ export async function preprocessMdxContent(
   error?: Error;
 }> {
   try {
-    // Step 0: Strip YAML frontmatter before any processing.
-    // Frontmatter is parsed separately by the frontmatter-generator plugin.
-    let processedContent = content;
-    const frontMatterMatch = processedContent.match(/^---\n([\s\S]*?)\n---\n?/);
-    if (frontMatterMatch) {
-      processedContent = processedContent.slice(frontMatterMatch[0].length);
-    }
-
-    // Step 0b: Strip stray ```yaml metadata blocks that follow frontmatter.
-    // Some content generators produce a second YAML block (```yaml...---) after
-    // the frontmatter. This is a broken code fence (closed with --- instead of ```)
-    // that leaks metadata into the rendered page.
-    const yamlBlockMatch = processedContent.match(/^```yaml\n([\s\S]*?)\n---\n?/);
-    if (yamlBlockMatch) {
-      processedContent = processedContent.slice(yamlBlockMatch[0].length);
-    }
-
-    // Step 1: Apply preprocessor (handles MDX tags, code blocks, etc.)
-    const preprocessor = preprocessMdxTags();
-    
-    if (preprocessor.transform) {
-      const result = preprocessor.transform(processedContent, fileName);
-      if (result && typeof result === 'object' && result.code) {
-        processedContent = result.code;
-      } else if (typeof result === 'string') {
-        processedContent = result;
-      }
-    }
-    
-    // Step 2: Convert URLs in angle brackets to markdown links
-    // Handles cases like <https://example.com> which MDX would interpret as JSX
-    // But preserves them inside code blocks
-    
-    // Process line by line to handle code blocks correctly
-    const lines = processedContent.split('\n');
-    let inCodeBlock = false;
-    
-    processedContent = lines.map(line => {
-      // Check if we're entering or leaving a code block (with optional indentation)
-      if (line.trim().startsWith('```')) {
-        inCodeBlock = !inCodeBlock;
-        return line;
+    const processed = preprocessMdxSource(content, fileName);
+    // Only real top-level ESM declarations register static JSX components.
+    // The browser's embedded runtime does not call this trusted build processor.
+    const importedNames = (source: string) => {
+      const names: string[] = [];
+      let declarations = 0;
+      for (const node of createProcessor().parse(source).children) {
+        if (node.type !== 'mdxjsEsm') continue;
+        for (const statement of node.data?.estree?.body ?? []) {
+          if (statement.type !== 'ImportDeclaration') continue;
+          declarations++;
+          for (const specifier of statement.specifiers) names.push(specifier.local.name);
+        }
       }
-      
-      // Don't process lines inside code blocks
-      if (inCodeBlock) {
-        return line;
-      }
-      
-      // For lines outside code blocks, preserve inline code
-      // More robust regex that handles inline code with potential spaces
-      // Matches: `...` including multi-line content
-      let result = '';
-      let lastIndex = 0;
-      
-      // Find all inline code spans in the line
-      const inlineCodeRegex = /`([^`]+)`/g;
-      let match;
-      
-      while ((match = inlineCodeRegex.exec(line)) !== null) {
-        // Process text before the inline code
-        const beforeCode = line.substring(lastIndex, match.index);
-        result += beforeCode.replace(/<(https?:\/\/[^\s>]+)>/g, '[$1]($1)');
-        
-        // Keep inline code as-is
-        result += match[0];
-        
-        lastIndex = match.index + match[0].length;
+      return { names, declarations };
+    };
+    let importedComponents: string[] = [];
+    if (/^import(?:\s|$)/m.test(processed)) {
+      try {
+        importedComponents = importedNames(processed).names;
+      } catch {
+        // Escaped closing tags can temporarily make imported JSX with props
+        // malformed. Gather provisional names from isolated import declarations.
+        // They are never trusted until the complete document's AST verifies them.
+        const candidates = new Set<string>();
+        const lines = processed.split('\n');
+        let fence = '';
+        for (let index = 0; index < lines.length; index++) {
+          const marker = lines[index].match(/^\s*(`{3,}|~{3,})(.*)$/);
+          if (marker) {
+            if (!fence) fence = marker[1];
+            else if (marker[1][0] === fence[0] && marker[1].length >= fence.length && !marker[2].trim()) fence = '';
+            continue;
+          }
+          if (fence || !/^import(?:\s|$)/.test(lines[index])) continue;
+          for (let end = index; end < lines.length; end++) {
+            try {
+              const result = importedNames(lines.slice(index, end + 1).join('\n'));
+              if (!result.declarations) continue;
+              for (const name of result.names) candidates.add(name);
+              index = end;
+              break;
+            } catch { /* The declaration may span more lines. */ }
+          }
+        }
+        const provisional = preprocessMdxSource(content, fileName, [...candidates]);
+        importedComponents = importedNames(provisional).names;
       }
-      
-      // Process remaining text after last inline code (or entire line if no inline code)
-      const remainingText = line.substring(lastIndex);
-      result += remainingText.replace(/<(https?:\/\/[^\s>]+)>/g, '[$1]($1)');
-      
-      return result;
-    }).join('\n');
-    
-    // Step 3: Add any future preprocessing steps here
-    // Example: processedContent = await yourNewPreprocessor(processedContent);
-    // Example: processedContent = removeHTMLComments(processedContent);
-    // Example: processedContent = expandCustomShortcodes(processedContent);
-    // ALL preprocessing added here will automatically apply to:
-    // - CLI commands (verify:content)
-    // - Vite build (pnpm run build)
-    // - Vite dev server (pnpm run dev)
-    
+    }
     return {
       success: true,
-      processedContent
+      processedContent: importedComponents.length
+        ? preprocessMdxSource(content, fileName, importedComponents)
+        : processed,
     };
   } catch (error) {
-    return {
-      success: false,
-      error: error as Error
-    };
+    return { success: false, error: error as Error };
   }
 }
 

package/src/mdx/source.tsx

@@ -1,5 +1,6 @@
+import { CatalogIcon } from '@clidey/ux'
 import classNames from 'classnames'
-import { ExternalLink, File } from 'lucide-react'
+
 import { useEffect, useState } from 'preact/hooks'
 import { Fence } from './fence'
 
@@ -121,7 +122,7 @@ export const Source = ({ url, branch = "main", paths }: SourceProps) => {
                                 : 'border-[var(--border)] bg-muted text-foreground hover:border-[var(--primary)]',
                         )}
                     >
-                        <File aria-hidden="true" className="h-3.5 w-3.5 text-muted-foreground" />
+                        <CatalogIcon name="file" aria-hidden="true" className="h-3.5 w-3.5 text-muted-foreground" />
                         {path}
                         {range && <span className="text-muted-foreground">{range}</span>}
                     </button>
@@ -129,7 +130,7 @@ export const Source = ({ url, branch = "main", paths }: SourceProps) => {
             </div>
             <div className="dory-code mt-3 overflow-hidden rounded-lg border border-[var(--border)] bg-card">
                 <div className="flex min-h-10 items-center gap-2 border-b border-[var(--border)] bg-muted px-4">
-                    <File aria-hidden="true" className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+                    <CatalogIcon name="file" aria-hidden="true" className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
                     <p className="mr-auto truncate font-mono text-xs text-foreground">
                         {repo} · {current.path}
                         {current.range && <span className="ml-2 text-muted-foreground">{current.range}</span>}
@@ -141,7 +142,7 @@ export const Source = ({ url, branch = "main", paths }: SourceProps) => {
                         className="inline-flex shrink-0 items-center gap-1 text-xs font-medium text-[var(--primary)] hover:underline"
                     >
                         {openLabel}
-                        <ExternalLink aria-hidden="true" className="h-3 w-3" />
+                        <CatalogIcon name="external" aria-hidden="true" className="h-3 w-3" />
                     </a>
                 </div>
                 {ready ? (

package/src/mdx/specimen.tsx

@@ -1,18 +1,39 @@
-import classNames from 'classnames'
 import { Children, isValidElement } from 'preact/compat'
-import { useState } from 'preact/hooks'
-import { fencePropsOf } from './code'
-import { Pre } from './fence'
+import { Tabs as UxTabs, TabsList, TabsTrigger, TabsContent, cn } from '@clidey/ux'
+import { handleTabKeyDown } from './tabs'
+import { CopyButton, fencePropsOf } from './code'
+import { Fence, Pre } from './fence'
 
-/** Marks the props table inside a Specimen; its children render in the Props tab. */
+/** Props tab body: a PROP / DESCRIPTION header followed by <Prop> rows. */
 export function SpecimenProps({ children }: { children: preact.ComponentChildren }) {
-  return <>{children}</>
+  return (
+    <div className="dory-props">
+      <div className="grid grid-cols-[minmax(0,1fr)_minmax(0,1.7fr)] gap-6 bg-muted px-5 py-2.5 font-mono text-[11px] uppercase tracking-[0.16em] text-muted-foreground">
+        <span>Prop</span>
+        <span>Description</span>
+      </div>
+      {children}
+    </div>
+  )
+}
+
+/** One row of a Specimen's Props tab: mono name with its type underneath, and a description. */
+export function Prop({ name, type, children }: { name: string; type?: string; children: preact.ComponentChildren }) {
+  return (
+    <div className="grid grid-cols-[minmax(0,1fr)_minmax(0,1.7fr)] gap-6 border-t border-[var(--border)] px-5 py-3.5">
+      <div className="min-w-0">
+        <p className="font-mono text-[13px] font-semibold text-foreground">{name}</p>
+        {type && <p className="mt-0.5 font-mono text-xs text-[var(--primary)]">{type}</p>}
+      </div>
+      <div className="text-sm leading-relaxed text-muted-foreground [&_p]:mb-0">{children}</div>
+    </div>
+  )
 }
 
 type SpecimenTab = 'Preview' | 'Code' | 'Props'
 
-function isMdxSource(child: preact.ComponentChild): boolean {
-  return isValidElement(child) && (child as preact.VNode).type === Pre && fencePropsOf(child as preact.JSX.Element).language === 'mdx'
+function isSourceFence(child: preact.ComponentChild): boolean {
+  return isValidElement(child) && (child as preact.VNode).type === Pre && ['mdx', 'tsx', 'jsx'].includes(fencePropsOf(child as preact.JSX.Element).language)
 }
 
 function isPropsBlock(child: preact.ComponentChild): boolean {
@@ -21,49 +42,42 @@ function isPropsBlock(child: preact.ComponentChild): boolean {
 
 /**
  * Framed component example with Preview / Code / Props tabs.
- * An ```mdx fence becomes the Code tab, a <SpecimenProps> block becomes the
+ * An MDX, TSX, or JSX fence becomes the Code tab, a <SpecimenProps> block becomes the
  * Props tab, and everything else is the rendered preview.
  */
-export function Specimen({ label, children }: { label?: string; children: preact.ComponentChildren }) {
+export function Specimen({ label, children, padding = 'default' }: {
+  label?: string
+  children: preact.ComponentChildren
+  /** Use none only when the example supplies its own preview spacing. */
+  padding?: 'default' | 'none'
+}) {
+  const previewClassName = cn('m-0 min-w-0 [&>:first-child]:mt-0 [&>:last-child]:mb-0', padding === 'none' ? 'p-0' : 'p-5 sm:p-6')
   const items = Children.toArray(children)
-  const code = items.filter(isMdxSource)
+  const code = items.filter(isSourceFence)
   const props = items.filter(isPropsBlock)
-  const preview = items.filter((child) => !isMdxSource(child) && !isPropsBlock(child))
+  const preview = items.filter((child) => !isSourceFence(child) && !isPropsBlock(child))
 
   const tabs: SpecimenTab[] = ['Preview']
   if (code.length > 0) tabs.push('Code')
   if (props.length > 0) tabs.push('Props')
 
-  const [active, setActive] = useState<SpecimenTab>('Preview')
-  const panels: Record<SpecimenTab, preact.ComponentChildren[]> = { Preview: preview, Code: code, Props: props }
-
-  return (
-    <div className="dory-specimen not-prose my-5 overflow-hidden rounded-lg border border-[var(--border)] bg-card">
-      <div className="flex min-h-10 items-center justify-between gap-3 border-b border-[var(--border)] py-1.5 pl-4 pr-1.5">
-        <p className="truncate font-mono text-xs text-[var(--primary)]">{label}</p>
-        {tabs.length > 1 && (
-          <div role="tablist" className="flex shrink-0 rounded-md bg-muted p-0.5">
-            {tabs.map((tab) => (
-              <button
-                key={tab}
-                type="button"
-                role="tab"
-                aria-selected={active === tab}
-                onClick={() => setActive(tab)}
-                className={classNames('rounded-[5px] px-2.5 py-1 text-xs font-medium transition', {
-                  'bg-card text-foreground shadow-[0_1px_2px_rgb(14_34_64/0.08)] dark:bg-[var(--border)]': active === tab,
-                  'text-muted-foreground hover:text-foreground': active !== tab,
-                })}
-              >
-                {tab}
-              </button>
-            ))}
-          </div>
-        )}
-      </div>
-      <div role="tabpanel" className="p-5 [&>:first-child]:mt-0 [&>:last-child]:mb-0">
-        {panels[active]}
-      </div>
+  const renderCode = () => code.map((child, index) => {
+    const fence = fencePropsOf(child as preact.JSX.Element)
+    return <div key={index} className="relative max-h-[32rem] overflow-auto px-5 py-4 font-mono text-[12.5px] leading-[1.7]">
+      <Fence language={fence.language} meta={{ ...fence.meta, title: undefined }}>{fence.code}</Fence>
+      <CopyButton code={fence.code} />
     </div>
-  )
+  })
+  if (tabs.length === 1) return <div className="dory-specimen not-prose my-5 overflow-hidden rounded-lg border border-[var(--border)] bg-card"><div className="px-4 py-3 font-mono text-xs text-[var(--primary)]">{label}</div><div data-dory-preview data-padding={padding} className={previewClassName}>{preview}</div></div>
+  return <UxTabs defaultValue="Preview" className="dory-specimen not-prose my-5 gap-0 overflow-hidden rounded-lg border border-[var(--border)] bg-card">
+    <div className="flex min-h-12 flex-wrap items-center justify-between gap-3 border-b border-[var(--border)] py-2 pl-4 pr-2">
+      <p className="truncate font-mono text-xs text-[var(--primary)]">{label}</p>
+      <TabsList aria-label={`${label ?? 'Component'} example views`} onKeyDown={handleTabKeyDown}>
+        {tabs.map(tab => <TabsTrigger key={tab} value={tab}>{tab}</TabsTrigger>)}
+      </TabsList>
+    </div>
+    <TabsContent value="Preview" data-dory-preview data-padding={padding} className={previewClassName}>{preview}</TabsContent>
+    {code.length > 0 && <TabsContent value="Code" className="m-0 p-0">{renderCode()}</TabsContent>}
+    {props.length > 0 && <TabsContent value="Props" className="m-0 p-0">{props}</TabsContent>}
+  </UxTabs>
 }

package/src/mdx/tabs.tsx

@@ -1,39 +1,50 @@
-import classNames from 'classnames'
+import { Tabs as UxTabs, TabsContent, TabsList, TabsTrigger } from '@clidey/ux'
 import { Children, isValidElement } from 'preact/compat'
-import { useState } from 'preact/hooks'
+
+/** Keyboard fallback for UX tabs rendered through Preact compatibility. */
+export function handleTabKeyDown(event: React.KeyboardEvent<HTMLDivElement>) {
+  // Radix roving focus does not handle arrow keys through Preact compat.
+  if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key)) return
+  const tabs = Array.from(event.currentTarget.querySelectorAll<HTMLButtonElement>('[role="tab"]:not([disabled])'))
+  const current = tabs.indexOf(event.target as HTMLButtonElement)
+  if (current < 0 || tabs.length === 0) return
+  event.preventDefault()
+  const next = event.key === 'Home' ? 0 : event.key === 'End' ? tabs.length - 1
+    : (current + (event.key === 'ArrowRight' ? 1 : -1) + tabs.length) % tabs.length
+  tabs[next].focus()
+  tabs[next].click()
+}
 
 /** One tab panel inside <Tabs>. Renders its children when active. */
 export function Tab({ children }: { title: string; children: preact.ComponentChildren }) {
   return <>{children}</>
 }
 
-/** Underlined tab strip for any MDX content, e.g. several diagrams of one thing. */
+/** UX tab strip for any MDX content, e.g. several diagrams of one thing. */
 export function Tabs({ children }: { children: preact.ComponentChildren }) {
   const panels = Children.toArray(children).filter(isValidElement) as preact.VNode<{ title: string }>[]
-  const [active, setActive] = useState(0)
 
   return (
-    <div className="dory-tabs not-prose my-5">
-      <div role="tablist" className="flex gap-5 border-b border-[var(--border)]">
+    <UxTabs defaultValue="0" className="dory-tabs not-prose my-5">
+      <TabsList
+        className="max-w-full justify-start overflow-x-auto"
+        onKeyDown={handleTabKeyDown}
+      >
         {panels.map((panel, index) => (
-          <button
+          <TabsTrigger
             key={index}
-            type="button"
-            role="tab"
-            aria-selected={active === index}
-            onClick={() => setActive(index)}
-            className={classNames('-mb-px border-b-2 pb-2.5 pt-1 text-sm font-medium transition', {
-              'border-[var(--primary)] text-foreground': active === index,
-              'border-transparent text-muted-foreground hover:text-foreground': active !== index,
-            })}
+            value={String(index)}
+            className="whitespace-nowrap"
           >
             {panel.props.title}
-          </button>
+          </TabsTrigger>
         ))}
-      </div>
-      <div role="tabpanel" className="pt-4 [&>:first-child]:mt-0 [&>:last-child]:mb-0">
-        {panels[active]}
-      </div>
-    </div>
+      </TabsList>
+      {panels.map((panel, index) => (
+        <TabsContent key={index} value={String(index)} className="pt-4 [&>:first-child]:mt-0 [&>:last-child]:mb-0">
+          {panel}
+        </TabsContent>
+      ))}
+    </UxTabs>
   )
 }

package/src/mdx/text.tsx

@@ -4,42 +4,42 @@ import classNames from "classnames"
 import { useState } from "preact/hooks"
 
 
-export const h1 = function H1(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+export const h1 = function H1(props: preact.ComponentProps<'h1'>) {
   return <h1 className="dory-h1 font-heading mb-3 mt-10" {...props} />
 }
 
-export const h2 = function H2({ children, ...props }: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+export const h2 = function H2({ children, ...props }: preact.ComponentProps<'h2'>) {
   return (
-    <h2 className="dory-h2 font-heading mb-2 mt-10" {...props}>
+    <h2 className="dory-h2 font-heading mb-4 mt-16" {...props}>
       <span>{children}</span>
       {props.id && <a href={`#${props.id}`} className="dory-anchor" aria-label="Link to this section">#</a>}
     </h2>
   )
 }
 
-export const h3 = function H3(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
-  return <h3 className="dory-h3 font-heading mb-2 mt-7" {...props} />
+export const h3 = function H3(props: preact.ComponentProps<'h3'>) {
+  return <h3 className="dory-h3 font-heading mb-3 mt-10" {...props} />
 }
 
-export const h4 = function H4(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+export const h4 = function H4(props: preact.ComponentProps<'h4'>) {
   return <h4 className="dory-h4 font-heading mb-1.5 mt-5" {...props} />
 }
 
-export const h5 = function H5(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+export const h5 = function H5(props: preact.ComponentProps<'h5'>) {
   return <h5 className="text-lg font-bold mb-2" {...props} />
 }
 
-export const h6 = function H6(props: preact.JSX.HTMLAttributes<HTMLHeadingElement>) {
+export const h6 = function H6(props: preact.ComponentProps<'h6'>) {
   return <h6 className="text-base font-bold mb-2" {...props} />
 }
 
-export const p = function P(props: preact.JSX.HTMLAttributes<HTMLParagraphElement>) {
+export const p = function P(props: preact.ComponentProps<'p'>) {
   return <p className="mb-2 inline-block" {...props} />
 }
 
 export function Row({ children, cols = 1, className }: { children: preact.ComponentChildren, cols?: number, className?: string }) {
   return (
-    <div className={cn(`py-6 grid grid-cols-1 items-start gap-x-16 gap-y-10 xl:max-w-none`, className)} style={{ gridTemplateColumns: `repeat(${cols}, minmax(0, 1fr))` }}>
+    <div className={cn(`dory-row py-6 grid min-w-0 grid-cols-1 items-start gap-6 sm:grid-cols-[repeat(var(--dory-columns),minmax(0,1fr))] xl:max-w-none`, className)} style={{ '--dory-columns': cols }}>
       {children}
     </div>
   )
@@ -58,7 +58,7 @@ export function Col({
 }) {
   return (
     <div
-      className={classNames("[&>:first-child]:mt-0 [&>:last-child]:mb-0", {
+      className={classNames("min-w-0 [&>:first-child]:mt-0 [&>:last-child]:mb-0", {
         'xl:sticky xl:top-24': sticky,
       })}
       style={{