@clidey/dory 0.30.0 → 0.31.0

package/src/mdx/mermaid.tsx

@@ -0,0 +1,147 @@
+import { ExclamationTriangleIcon } from '@heroicons/react/24/outline'
+import classNames from 'classnames'
+import { useEffect, useMemo, useRef, useState } from 'preact/compat'
+
+function fixNodeLabelsWithSpecialChars(content: string): string {
+    // Pattern to match node definitions with brackets containing special characters
+    // Matches: NodeId[text content] where text content has special chars and isn't already quoted
+    const nodePattern = /(\w+)\[([^\]"]*[(),\s][^\]"]*)\]/g;
+    
+    return content.replace(nodePattern, (match, nodeId, labelContent) => {
+        // Only wrap in quotes if not already quoted and contains special characters
+        if (!labelContent.startsWith('"') || !labelContent.endsWith('"')) {
+            return `${nodeId}["${labelContent}"]`;
+        }
+        return match;
+    });
+}
+
+export function MermaidRenderer({ content }: { content: string }) {
+    const mermaidRef = useRef<HTMLDivElement>(null)
+    const [isFullscreen, setIsFullscreen] = useState(false)
+    const [isLoaded, setIsLoaded] = useState(false)
+    const [error, setError] = useState<string | null>(null)
+    const [isValid, setIsValid] = useState<boolean | null>(null)
+
+    const diagramId = useMemo(() => `mermaid-${btoa(content).replace(/[^a-zA-Z0-9]/g, '').substring(0, 10)}`, [content])
+
+    useEffect(() => {
+        let mounted = true
+
+        const renderMermaid = async () => {
+            try {
+                const mermaid = (await import('mermaid')).default
+                
+                if (!mounted || !mermaidRef.current) return
+
+                mermaid.initialize({
+                    startOnLoad: true,
+                    theme: 'base',
+                    themeVariables: {
+                        fontSize: '14px',
+                        nodePadding: 20,
+                        notePadding: 15,
+                        padding: 10,
+                        nodeBorderRadius: 8,
+                    },
+                    flowchart: {
+                        nodeSpacing: 50,
+                        rankSpacing: 80,
+                        padding: 20,
+                        useMaxWidth: true,
+                    },
+                })
+
+                if (mermaidRef.current) {
+                    mermaidRef.current.innerHTML = ''
+                }
+
+                const contentWithoutStyle = content
+                    .replace(/^\s*style .*$/gm, '')
+                    .replace(/^\s*classDef .*$/gm, '')
+                    .replace(/^\s*class .*$/gm, '');
+
+                // Fix node labels with special characters by wrapping them in quotes
+                const processedContent = fixNodeLabelsWithSpecialChars(contentWithoutStyle);
+
+                // Validate the mermaid syntax first
+                try {
+                    await mermaid.parse(processedContent)
+                    setIsValid(true)
+                } catch (parseError) {
+                    setIsValid(false)
+                    if (mounted) {
+                        setError(parseError instanceof Error ? parseError.message : 'Invalid diagram syntax')
+                    }
+                    return
+                }
+              
+                const { svg } = await mermaid.render(diagramId, processedContent);
+
+                if (mounted && mermaidRef.current) {
+                    mermaidRef.current.innerHTML = svg
+                    setIsLoaded(true)
+                }
+            } catch (err) {
+                console.error('Mermaid rendering error:', err)
+                if (mounted) {
+                    setIsValid(false)
+                    setError(err instanceof Error ? err.message : 'Failed to render diagram')
+                }
+            }
+        }
+
+        renderMermaid()
+
+        return () => {
+            mounted = false
+        }
+    }, [content, diagramId])
+
+    const toggleFullscreen = () => {
+        setIsFullscreen(!isFullscreen)
+    }
+
+    if (error || isValid === false) {
+        return (
+            <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" />
+                    </div>
+                    <h3 className="text-lg font-semibold text-red-700 dark:text-red-300 mb-2">
+                        Diagram Syntax 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.
+                    </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">
+                            {error}
+                        </p>
+                    </div>
+                </div>
+            </div>
+        )
+    }
+
+    return (
+        <div className="mermaid-wrapper my-8">
+            {!isLoaded && (
+                <div className="flex items-center justify-center py-8 text-gray-400">
+                    <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-blue-500"></div>
+                    <span className="ml-2">Loading diagram...</span>
+                </div>
+            )}
+            <div
+                ref={mermaidRef}
+                className={classNames('mermaid cursor-pointer transition-all duration-300 rounded-lg p-4 bg-white', {
+                    'fixed inset-0 z-50 bg-black/90 flex items-center justify-center backdrop-blur-sm': isFullscreen,
+                    'opacity-0': !isLoaded,
+                    'opacity-100': isLoaded,
+                })}
+                onClick={toggleFullscreen}
+            />
+        </div>
+    )
+}

package/src/mdx/open-api.tsx

@@ -0,0 +1,311 @@
+import { useState } from "preact/hooks"
+import { APIGroup } from "./api"
+import { APIPlayground, PlayButton, type Server } from "./api-playground"
+import { Fence } from "./fence"
+import { Tag } from "./tag"
+import { Col, Row } from "./text"
+import { Sheet, SheetContent, SheetHeader, SheetTitle, Button } from "@clidey/ux"
+
+export function Properties({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="my-2">
+      <ul
+        role="list"
+        className="m-0 max-w-[calc(var(--container-lg)-(--spacing(8)))] list-none divide-y divide-zinc-900/5 p-0 dark:divide-white/10"
+      >
+        {children}
+      </ul>
+    </div>
+  )
+}
+
+export function Property({
+  name,
+  children,
+  type,
+  required = false,
+}: {
+  name: string
+  children: React.ReactNode
+  type?: string
+  required?: boolean
+}) {
+  return (
+    <div className="m-0 px-0 first:pt-0 last:pb-0">
+      <div className="my-4 flex flex-wrap items-center gap-x-3 gap-2">
+        <div className="flex gap-2 items-center grow">
+          <Tag className="px-4 py-1">{name}</Tag>
+          <p className="font-mono text-xs text-zinc-400 dark:text-zinc-500">
+            {type}
+          </p>
+          <div className="flex grow justify-end ">
+            {required && <span className="text-rose-400 ml-1 text-xs">Required</span>}
+          </div>
+        </div>
+        <p className="w-full flex-none [&>:first-child]:mt-0 [&>:last-child]:mb-0 text-xs text-muted-foreground">
+          {children}
+        </p>
+      </div>
+    </div>
+  )
+}
+
+interface ParamFieldProps {
+  body: string;
+  type: string;
+  default?: string | number;
+  required?: boolean;
+  children: React.ReactNode;
+}
+
+export function ParamField({ body, type, default: defaultValue, required, children }: ParamFieldProps) {
+  return (
+    <Property name={body} type={type} required={required}>
+      {children}
+      {defaultValue != null && (
+        <span className="text-gray-500 ml-1">(default: {defaultValue})</span>
+      )}
+    </Property>
+  );
+}
+
+interface ResponseFieldProps {
+  name: string;
+  type: string;
+  required?: boolean;
+  children: React.ReactNode;
+}
+
+export function ResponseField({ name, type, required, children }: ResponseFieldProps) {
+  return (
+    <Property name={name} type={type} required={required}>
+      {children}
+    </Property>
+  );
+}
+
+interface Schema {
+  $ref?: string;
+  type?: string;
+  items?: Schema;
+  properties?: Record<string, Schema>;
+  required?: boolean;
+  description?: string;
+  default?: string | number;
+}
+
+interface Components {
+  schemas?: Record<string, Schema>;
+}
+
+interface Parameter {
+  name: string;
+  schema?: Schema;
+  required?: boolean;
+  description?: string;
+}
+
+interface Content {
+  schema?: Schema;
+}
+
+interface RequestBody {
+  description?: string;
+  content?: {
+    'application/json'?: Content;
+  };
+}
+
+interface Response {
+  content?: {
+    'application/json'?: Content;
+  };
+}
+
+interface PathMethod {
+  description?: string;
+  parameters?: Parameter[];
+  requestBody?: RequestBody;
+  responses: Record<string, Response>;
+}
+
+export interface OpenAPIJson {
+  paths: Record<string, Record<string, PathMethod>>;
+  components: Components;
+  servers?: Server[];
+}
+
+function resolveSchema(schema: Schema | undefined, components: Components): Schema {
+  if (!schema) return {};
+
+  if (schema.$ref) {
+    const refPath = schema.$ref.replace(/^#\/components\/schemas\//, '');
+    return resolveSchema(components.schemas?.[refPath], components);
+  }
+
+  if (schema.type === 'array' && schema.items) {
+    return {
+      ...schema,
+      items: resolveSchema(schema.items, components)
+    };
+  }
+
+  if (schema.properties) {
+    const resolvedProps: Record<string, Schema> = {};
+    for (const [key, value] of Object.entries(schema.properties)) {
+      resolvedProps[key] = resolveSchema(value, components);
+    }
+    return {
+      ...schema,
+      properties: resolvedProps
+    };
+  }
+
+  return schema;
+}
+
+export function OpenAPI({ openAPIJson, method: selectedMethod, path: selectedPath }: { openAPIJson: OpenAPIJson, method: string, path: string }) {
+  const { paths, components } = openAPIJson;
+  const [showPlayground, setShowPlayground] = useState(false);
+
+  const handleShowPlayground = () => {
+    setShowPlayground(true);
+  }
+
+  return (
+    <div className="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>
+      {Object.entries(paths).map(([path, methods]) => {
+        if (path !== selectedPath) {
+          return null;
+        }
+
+        return (
+          <div key={path} className="my-8">
+            {Object.entries(methods).map(([method, details]) => {
+            const { description, parameters, requestBody, responses } = details;
+            const methodUpper = method.toUpperCase();
+
+            if (methodUpper !== selectedMethod) {
+              return null;
+            }
+
+            return (
+              <Row key={`${method}-${path}`} cols={2} className="gap-0">
+                <Col>
+                  <h2 className="flex items-center mt-4">
+                    <Tag variant="medium" className="mr-2 py-1 px-4 rounded-lg">{methodUpper}</Tag>
+                    <span className="ml-2 font-mono">{path}</span>
+                  </h2>
+
+                  {description && <p>{description}</p>}
+
+                  {parameters && parameters.length > 0 && (
+                    <div className="mt-4">
+                      <h3 className="font-bold">Parameters</h3>
+                      <Properties>
+                        {parameters.map((param) => (
+                          <ParamField 
+                            key={param.name}
+                            body={param.name}
+                            type={param.schema?.type ?? 'string'}
+                            required={param.required}
+                            default={param.schema?.default}
+                          >
+                            {param.description}
+                          </ParamField>
+                        ))}
+                      </Properties>
+                    </div>
+                  )}
+                  {requestBody && (
+                    <div className="mt-4">
+                      <h3 className="font-bold">Request Body</h3>
+                      <p>{requestBody.description}</p>
+                      {requestBody.content?.['application/json']?.schema && (
+                        (() => {
+                          const resolvedSchema = resolveSchema(requestBody.content['application/json'].schema, components);
+                          return (
+                            <Properties>
+                              {Object.entries(resolvedSchema.properties || {}).map(([propName, prop]) => (
+                                <ParamField
+                                  key={propName}
+                                  body={propName}
+                                  type={prop.type ?? 'string'}
+                                  required={prop.required}
+                                  default={prop.default}
+                                >
+                                  {prop.description}
+                                </ParamField>
+                              ))}
+                            </Properties>
+                          );
+                        })()
+                      )}
+                    </div>
+                  )}
+                  {components?.schemas && (
+                    <div>
+                      <h3 className="font-bold">Schemas</h3>
+                      {Object.entries(components.schemas).filter(([, schema]) => schema.properties).map(([name, schema]) => (
+                        <div key={name} className="mt-8">
+                          <h4>{name}</h4>
+                          <Properties>
+                            {Object.entries(schema.properties || {}).map(([propName, prop]) => (
+                              <ResponseField
+                                key={propName}
+                                name={propName}
+                                type={prop.type ?? 'string'}
+                                required={prop.required}
+                              >
+                                {prop.description}
+                              </ResponseField>
+                            ))}
+                          </Properties>
+                        </div>
+                      ))}
+                    </div>
+                  )}
+                </Col>
+                <Col sticky>
+                  <Button
+                    onClick={handleShowPlayground}
+                    className='ml-auto mt-3 flex items-center gap-2'>
+                      Try
+                    <PlayButton className="h-4 w-4" />
+                  </Button>
+                  <APIGroup title="Request" tag={methodUpper} label={path}>
+                    {Object.entries(responses).map(([code, response]) => (
+                      <div key={code} title={code}>
+                        {response.content?.['application/json']?.schema && (() => {
+                          const resolvedSchema = resolveSchema(response.content['application/json'].schema, components);
+                          return (
+                            <Fence language="json">
+                                {JSON.stringify(resolvedSchema, null, 2)}
+                            </Fence>
+                          );
+                        })()}
+                      </div>
+                    ))}
+                  </APIGroup>
+                </Col>
+              </Row>
+            )
+          })}
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/mdx/processor.ts

@@ -0,0 +1,174 @@
+import { compile } from '@mdx-js/mdx';
+import { preprocessMdxTags } from '../plugins/sanitize';
+import { getMdxConfig } from '../config/mdx';
+
+export interface ProcessMdxOptions {
+  isDevelopment?: boolean;
+  fileName?: string;
+}
+
+/**
+ * SINGLE SOURCE OF TRUTH for MDX preprocessing.
+ * 
+ * This processor is used by:
+ * - CLI verify:content command (bin/dory.ts) - full processing + compilation
+ * - Vite build via unified-mdx-plugin.ts - preprocessing only
+ * 
+ * ALL MDX processing steps should be added here to ensure consistency.
+ */
+export async function preprocessMdxContent(
+  content: string,
+  fileName: string = 'content.mdx'
+): Promise<{
+  success: boolean;
+  processedContent?: string;
+  error?: Error;
+}> {
+  try {
+    // Step 1: Apply preprocessor (handles MDX tags, code blocks, etc.)
+    const preprocessor = preprocessMdxTags();
+    let processedContent = content;
+    
+    if (preprocessor.transform) {
+      const result = preprocessor.transform(content, 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;
+      }
+      
+      // 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;
+      }
+      
+      // 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
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error as Error
+    };
+  }
+}
+
+/**
+ * Process and compile MDX content through the full pipeline.
+ * Used by CLI commands that need the compiled output.
+ */
+export async function processMdxContent(
+  content: string, 
+  options: ProcessMdxOptions = {}
+): Promise<{ 
+  success: boolean; 
+  compiled?: any; 
+  error?: Error;
+  processedContent?: string;
+}> {
+  const { isDevelopment = false, fileName = 'content.mdx' } = options;
+  
+  try {
+    // Step 1: Preprocess
+    const preprocessResult = await preprocessMdxContent(content, fileName);
+    if (!preprocessResult.success) {
+      return {
+        success: false,
+        error: preprocessResult.error
+      };
+    }
+    
+    const processedContent = preprocessResult.processedContent || content;
+    
+    // Step 2: Compile MDX with the same config as main build
+    const mdxConfig = getMdxConfig(isDevelopment);
+    const compiled = await compile(processedContent, {
+      ...mdxConfig,
+    });
+    
+    return {
+      success: true,
+      compiled,
+      processedContent
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: error as Error
+    };
+  }
+}
+
+/**
+ * Verify MDX content can be compiled without errors.
+ * Uses the same processing pipeline as processMdxContent.
+ */
+export async function verifyMdxContent(
+  content: string,
+  fileName?: string
+): Promise<{ valid: boolean; error?: Error }> {
+  const result = await processMdxContent(content, { fileName });
+  
+  if (result.success) {
+    return { valid: true };
+  } else {
+    return { 
+      valid: false, 
+      error: result.error 
+    };
+  }
+}

package/src/mdx/source.tsx

@@ -0,0 +1,58 @@
+type PathRange = {
+    path: string;
+    range?: string;
+};
+
+type SourceProps = {
+    url: string;
+    branch?: string;
+    paths: PathRange[];
+};
+
+export const Source = ({ url, branch = "main", paths }: SourceProps) => {
+    const createSourceUrl = (path: string, range?: string) => {
+        if (!range) {
+            if (url.includes('github.com')) {
+                return `${url}/blob/${branch}/${path}`;
+            } else if (url.includes('bitbucket.org')) {
+                return `${url}/src/${branch}/${path}`;
+            } else if (url.includes('gitlab.com')) {
+                return `${url}/-/blob/${branch}/${path}`;
+            }
+            return url;
+        }
+
+        const [start, end] = range.split('-');
+
+        if (url.includes('github.com')) {
+            return `${url}/blob/${branch}/${path}#L${start}${end ? `-L${end}` : ''}`;
+        } else if (url.includes('bitbucket.org')) {
+            return `${url}/src/${branch}/${path}#lines-${start}${end ? `:${end}` : ''}`;
+        } else if (url.includes('gitlab.com')) {
+            return `${url}/-/blob/${branch}/${path}#L${range.replace('-', '-')}`;
+        }
+
+        return url;
+    };
+
+    return (
+        <div>
+            <p className="text-sm text-slate-900 dark:text-white">Sources:</p>
+            <ul className="list-none pl-0 flex flex-wrap gap-2 mt-2">
+                {paths.map(({ path, range }) => (
+                    <li key={path + (range || '')}>
+                        <a
+                            href={createSourceUrl(path, range)}
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            className="rounded px-3 py-1 font-mono text-sm text-slate-700 dark:text-slate-400 hover:opacity-80 transition-colors border border-slate-200 dark:border-slate-700"
+                        >
+                            {path}
+                            {range && <span className="ml-2 opacity-70">{range}</span>}
+                        </a>
+                    </li>
+                ))}
+            </ul>
+        </div>
+    );
+};