@clidey/dory 1.0.8 → 1.10.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.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { createElement } from 'preact';
+import { renderToString } from 'preact-render-to-string';
+import katex from 'katex';
+import { Latex, renderLatexExpression } from './latex';
+
+describe('LaTeX rendering', () => {
+  it('server-renders a readable display fallback with the same client shell', () => {
+    const html = renderToString(createElement(Latex, { children: 'E = mc^2' }));
+    expect(html).toContain('dory-latex not-prose');
+    expect(html).toContain('aria-busy="true"');
+    expect(html).toContain('data-latex-fallback');
+    expect(html).toContain('E = mc^2');
+    expect(html).not.toContain('animate-spin');
+  });
+
+  it('keeps the inline fallback inline and escapes source text', () => {
+    const html = renderToString(createElement(Latex, { inline: true, children: '<img src=x onerror=alert(1)>' }));
+    expect(html).toMatch(/^<span /);
+    expect(html).not.toContain('<div');
+    expect(html).not.toContain('<img');
+    expect(html).toContain('&lt;img');
+  });
+
+  it('renders complex math with KaTeX and the requested mode', () => {
+    const expression = String.raw`\frac{a}{b}`;
+    expect(renderLatexExpression(katex, expression, false)).toContain('katex-display');
+    const inline = renderLatexExpression(katex, expression, true);
+    expect(inline).toContain('mfrac');
+    expect(inline).not.toContain('katex-display');
+  });
+
+  it('does not allow formulas to create trusted links, HTML classes, or image requests', () => {
+    expect(renderLatexExpression(katex, String.raw`\href{javascript:alert(1)}{click}`, true)).not.toMatch(/href=["']javascript:/);
+    expect(renderLatexExpression(katex, String.raw`\htmlClass{injected}{x}`, false)).not.toMatch(/class=["']injected/);
+    expect(renderLatexExpression(katex, String.raw`\includegraphics{https://example.test/tracker.png}`, false)).not.toContain('<img');
+  });
+});

package/src/mdx/latex.tsx

@@ -1,12 +1,13 @@
-import { ExclamationTriangleIcon } from '@heroicons/react/24/outline'
-import { useEffect, useRef, useState } from 'react'
+import { useEffect, useState } from 'preact/hooks'
 
 function extractText(node: React.ReactNode): string {
   if (typeof node === 'string') return node;
   if (typeof node === 'number') return String(node);
   if (!node) return '';
   if (Array.isArray(node)) return node.map(extractText).join('');
-  if (typeof node === 'object' && 'props' in node) return extractText((node as any).props.children);
+  if (typeof node === 'object' && 'props' in node) {
+    return extractText((node as { props: { children?: React.ReactNode } }).props.children);
+  }
   return '';
 }
 
@@ -16,90 +17,67 @@ interface LatexProps {
   inline?: boolean
 }
 
-export function Latex({ children, inline = false }: LatexProps) {
-  const expression = extractText(children).trim();
+type RenderResult = {
+  expression: string
+  inline: boolean
+  html?: string
+  error?: string
+}
 
-  if (typeof window === 'undefined') {
-    return inline ? <code>{expression}</code> : <div className="my-4"><code>{expression}</code></div>
-  }
+/** Only KaTeX produces markup; TeX commands cannot opt into trusted HTML or URLs. */
+export function renderLatexExpression(katex: Pick<typeof import('katex').default, 'renderToString'>, expression: string, inline: boolean): string {
+  return katex.renderToString(expression, {
+    displayMode: !inline,
+    throwOnError: false,
+    trust: false,
+    maxExpand: 1000,
+  })
+}
 
-  const containerRef = useRef<HTMLDivElement>(null)
-  const [error, setError] = useState<string | null>(null)
-  const [isLoading, setIsLoading] = useState(true)
+export function Latex({ children, inline = false }: LatexProps) {
+  const expression = extractText(children).trim()
+  const [result, setResult] = useState<RenderResult | null>(null)
+  // A changed expression immediately shows its own fallback while it loads.
+  const current = result?.expression === expression && result.inline === inline ? result : null
+  const isLoading = current === null
 
   useEffect(() => {
     let mounted = true
-
     const renderLatex = async () => {
       try {
-        setError(null)
-        setIsLoading(true)
-
         const [katexModule] = await Promise.all([
           import('katex'),
           import('katex/dist/katex.min.css'),
         ])
-        const katex = katexModule.default
-
-        if (!mounted || !containerRef.current) return
-
-        katex.render(expression, containerRef.current, {
-          displayMode: !inline,
-          throwOnError: false,
-        })
-        setIsLoading(false)
-      } catch (error) {
-        if (mounted) {
-          console.error('Error rendering LaTeX:', error)
-          setError(error instanceof Error ? error.message : 'Failed to render LaTeX')
-          setIsLoading(false)
-        }
+        const html = renderLatexExpression(katexModule.default, expression, inline)
+        if (mounted) setResult({ expression, inline, html })
+      } catch {
+        if (mounted) setResult({ expression, inline, error: 'The equation could not be rendered.' })
       }
     }
-
     renderLatex()
-
-    return () => {
-      mounted = false
-    }
+    return () => { mounted = false }
   }, [expression, inline])
 
+  // Server rendering and the first browser render use the same readable fallback.
+  // Keep KaTeX lazy, and let Preact own the markup instead of mutating a ref's DOM.
   if (inline) {
-    return <span ref={containerRef as unknown as preact.RefObject<HTMLSpanElement>} className="dory-latex-inline">{isLoading && expression}</span>
-  }
-
-  if (error) {
     return (
-      <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" />
-          </div>
-          <h3 className="text-lg font-semibold text-red-700 dark:text-red-300 mb-2">
-            LaTeX Rendering Error
-          </h3>
-          <p className="text-red-600 dark:text-red-400 mb-4 max-w-md">
-            The LaTeX expression could not 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>
+      <span className="dory-latex-inline" aria-busy={isLoading} title={current?.error}>
+        {current?.html !== undefined
+          ? <span dangerouslySetInnerHTML={{ __html: current.html }} />
+          : <span data-latex-fallback>{expression}</span>}
+      </span>
     )
   }
 
   return (
-    <div className="dory-latex not-prose my-5 rounded-lg border border-[var(--border)] bg-muted/50 px-5 pb-5 pt-3">
+    <div className="dory-latex not-prose my-5 rounded-lg border border-[var(--border)] bg-muted/50 px-5 pb-5 pt-3" aria-busy={isLoading}>
       <span className="block font-mono text-[11px] uppercase tracking-[0.16em] text-muted-foreground">Display</span>
-      {isLoading && (
-        <div className="flex items-center justify-center py-4">
-          <div className="animate-spin rounded-full h-6 w-6 border-b-2 border-[var(--primary)]" />
-        </div>
-      )}
-      <div ref={containerRef} className={isLoading ? 'hidden' : 'mt-3 text-center'} />
+      {current?.html !== undefined
+        ? <div className="mt-3 overflow-x-auto text-center" dangerouslySetInnerHTML={{ __html: current.html }} />
+        : <span data-latex-fallback className="block overflow-x-auto px-2 py-3 text-center font-mono text-sm text-muted-foreground">{expression}</span>}
+      {current?.error && <p role="alert" className="mt-2 text-center text-sm text-destructive">{current.error}</p>}
     </div>
   )
 }

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">