@marlinjai/clearify 1.5.0

package/src/theme/components/Card.tsx

@@ -0,0 +1,103 @@
+import React from 'react';
+import { Link } from 'react-router-dom';
+
+interface CardProps {
+  title: string;
+  description?: string;
+  icon?: string;
+  href?: string;
+  children?: React.ReactNode;
+}
+
+export function Card({ title, description, icon, href, children }: CardProps) {
+  const content = (
+    <div
+      style={{
+        border: '1px solid var(--clearify-border)',
+        borderRadius: 'var(--clearify-radius-lg)',
+        padding: '1.375rem',
+        transition: 'all 0.2s cubic-bezier(0.4, 0, 0.2, 1)',
+        cursor: href ? 'pointer' : 'default',
+        height: '100%',
+        background: 'var(--clearify-bg)',
+        position: 'relative',
+        overflow: 'hidden',
+      }}
+      className="clearify-card"
+    >
+      {icon && (
+        <div
+          style={{
+            fontSize: '1.25rem',
+            marginBottom: '0.625rem',
+            width: 36,
+            height: 36,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            borderRadius: 'var(--clearify-radius-sm)',
+            background: 'var(--clearify-gradient-subtle)',
+            border: '1px solid var(--clearify-border)',
+          }}
+        >
+          {icon}
+        </div>
+      )}
+      <div style={{ fontWeight: 600, marginBottom: '0.25rem', fontSize: '0.9375rem', letterSpacing: '-0.01em' }}>
+        {title}
+      </div>
+      {description && (
+        <div style={{ fontSize: '0.8125rem', color: 'var(--clearify-text-secondary)', lineHeight: 1.55 }}>
+          {description}
+        </div>
+      )}
+      {children && <div style={{ marginTop: '0.625rem', fontSize: '0.8125rem' }}>{children}</div>}
+
+      <style>{`
+        .clearify-card:hover {
+          border-color: var(--clearify-border-strong) !important;
+          box-shadow: var(--clearify-shadow) !important;
+          transform: translateY(-1px);
+        }
+      `}</style>
+    </div>
+  );
+
+  if (href) {
+    if (href.startsWith('/')) {
+      return <Link to={href} style={{ textDecoration: 'none', color: 'inherit' }}>{content}</Link>;
+    }
+    return <a href={href} target="_blank" rel="noopener noreferrer" style={{ textDecoration: 'none', color: 'inherit' }}>{content}</a>;
+  }
+
+  return content;
+}
+
+interface CardGroupProps {
+  cols?: number;
+  children: React.ReactNode;
+}
+
+export function CardGroup({ cols = 2, children }: CardGroupProps) {
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gridTemplateColumns: `repeat(${cols}, 1fr)`,
+        gap: '0.875rem',
+        marginBottom: '1.5rem',
+      }}
+      className="clearify-card-group"
+    >
+      {children}
+
+      <style>{`
+        @media (max-width: 640px) {
+          .clearify-card-group {
+            grid-template-columns: 1fr !important;
+          }
+        }
+      `}</style>
+    </div>
+  );
+}

package/src/theme/components/CodeGroup.tsx

@@ -0,0 +1,79 @@
+import React, { useState, Children, isValidElement } from 'react';
+
+interface CodeGroupProps {
+  children: React.ReactNode;
+}
+
+export function CodeGroup({ children }: CodeGroupProps) {
+  const [active, setActive] = useState(0);
+  const blocks = Children.toArray(children).filter(isValidElement);
+
+  const labels = blocks.map((block, i) => {
+    if (isValidElement(block)) {
+      const pre = block as React.ReactElement<any>;
+      const lang = pre.props?.['data-language'] ??
+        pre.props?.className?.match(/language-(\w+)/)?.[1] ??
+        `Tab ${i + 1}`;
+      return lang;
+    }
+    return `Tab ${i + 1}`;
+  });
+
+  return (
+    <div
+      style={{
+        marginBottom: '1.25rem',
+        border: '1px solid var(--clearify-border)',
+        borderRadius: 'var(--clearify-radius)',
+        overflow: 'hidden',
+        background: 'var(--clearify-bg)',
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          borderBottom: '1px solid var(--clearify-border)',
+          backgroundColor: 'var(--clearify-bg-secondary)',
+          padding: '0 0.25rem',
+          gap: '0.125rem',
+        }}
+      >
+        {labels.map((label, i) => {
+          const isActive = active === i;
+          return (
+            <button
+              key={i}
+              onClick={() => setActive(i)}
+              style={{
+                padding: '0.5rem 0.875rem',
+                background: 'none',
+                border: 'none',
+                borderBottom: isActive ? '2px solid var(--clearify-primary)' : '2px solid transparent',
+                cursor: 'pointer',
+                fontSize: '0.75rem',
+                fontWeight: isActive ? 600 : 400,
+                color: isActive ? 'var(--clearify-primary)' : 'var(--clearify-text-tertiary)',
+                textTransform: 'uppercase',
+                letterSpacing: '0.03em',
+                transition: 'color 0.15s, border-color 0.15s',
+                fontFamily: 'var(--font-mono)',
+              }}
+              className="clearify-codegroup-btn"
+            >
+              {label}
+            </button>
+          );
+        })}
+      </div>
+      <div>
+        {blocks[active]}
+      </div>
+
+      <style>{`
+        .clearify-codegroup-btn:hover {
+          color: var(--clearify-text) !important;
+        }
+      `}</style>
+    </div>
+  );
+}

package/src/theme/components/Columns.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+
+interface ColumnsProps {
+  cols?: 2 | 3 | 4;
+  children: React.ReactNode;
+}
+
+export function Columns({ cols = 2, children }: ColumnsProps) {
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gridTemplateColumns: `repeat(${cols}, 1fr)`,
+        gap: '1.5rem',
+        marginBottom: '1.5rem',
+      }}
+      className="clearify-columns"
+    >
+      {children}
+
+      <style>{`
+        @media (max-width: 768px) {
+          .clearify-columns {
+            grid-template-columns: 1fr !important;
+          }
+        }
+      `}</style>
+    </div>
+  );
+}
+
+interface ColumnProps {
+  children: React.ReactNode;
+}
+
+export function Column({ children }: ColumnProps) {
+  return (
+    <div style={{ minWidth: 0 }}>
+      {children}
+    </div>
+  );
+}

package/src/theme/components/Frame.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+
+interface FrameProps {
+  children: React.ReactNode;
+  caption?: string;
+}
+
+export function Frame({ children, caption }: FrameProps) {
+  return (
+    <figure
+      style={{
+        margin: '0 0 1.5rem 0',
+        padding: 0,
+      }}
+    >
+      <div
+        style={{
+          border: '1px solid var(--clearify-border)',
+          borderRadius: 'var(--clearify-radius-lg)',
+          overflow: 'hidden',
+          boxShadow: 'var(--clearify-shadow)',
+          background: 'var(--clearify-bg)',
+        }}
+        className="clearify-frame"
+      >
+        {children}
+      </div>
+      {caption && (
+        <figcaption
+          style={{
+            marginTop: '0.5rem',
+            fontSize: '0.8125rem',
+            color: 'var(--clearify-text-secondary)',
+            textAlign: 'center',
+            lineHeight: 1.5,
+          }}
+        >
+          {caption}
+        </figcaption>
+      )}
+
+      <style>{`
+        .clearify-frame .clearify-prose img,
+        .clearify-frame img {
+          border: none !important;
+          border-radius: 0 !important;
+          margin: 0 !important;
+          box-shadow: none !important;
+          display: block;
+          width: 100%;
+        }
+      `}</style>
+    </figure>
+  );
+}

package/src/theme/components/Mermaid.tsx

@@ -0,0 +1,99 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { useTheme } from '../ThemeProvider.js';
+
+let idCounter = 0;
+
+interface MermaidProps {
+  children: string;
+}
+
+export function Mermaid({ children }: MermaidProps) {
+  // SSR: render a plain code block as fallback (mermaid requires DOM)
+  if (typeof window === 'undefined') {
+    return <pre><code className="language-mermaid">{children}</code></pre>;
+  }
+
+  const { theme } = useTheme();
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [svg, setSvg] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function render() {
+      try {
+        const mermaid = (await import('mermaid')).default;
+        mermaid.initialize({
+          startOnLoad: false,
+          theme: theme === 'dark' ? 'dark' : 'default',
+          securityLevel: 'loose',
+        });
+
+        const id = `mermaid-${Date.now()}-${idCounter++}`;
+        const { svg: renderedSvg } = await mermaid.render(id, children);
+
+        if (!cancelled) {
+          setSvg(renderedSvg);
+          setError(null);
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : 'Failed to render diagram');
+          setSvg(null);
+        }
+      }
+    }
+
+    render();
+    return () => { cancelled = true; };
+  }, [children, theme]);
+
+  if (error) {
+    return (
+      <div
+        style={{
+          border: '1px solid var(--clearify-border)',
+          borderRadius: '0.5rem',
+          padding: '1rem',
+          marginBottom: '1rem',
+          backgroundColor: 'var(--clearify-bg-secondary)',
+          color: '#ef4444',
+          fontSize: '0.875rem',
+        }}
+      >
+        <strong>Mermaid Error:</strong> {error}
+        <pre style={{ marginTop: '0.5rem', whiteSpace: 'pre-wrap', opacity: 0.7 }}>{children}</pre>
+      </div>
+    );
+  }
+
+  if (!svg) {
+    return (
+      <div
+        style={{
+          border: '1px solid var(--clearify-border)',
+          borderRadius: '0.5rem',
+          padding: '2rem',
+          marginBottom: '1rem',
+          textAlign: 'center',
+          color: 'var(--clearify-text-secondary)',
+        }}
+      >
+        Loading diagram...
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={containerRef}
+      style={{
+        marginBottom: '1rem',
+        display: 'flex',
+        justifyContent: 'center',
+      }}
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}

package/src/theme/components/MermaidStatic.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import mermaidSvgs from 'virtual:clearify/mermaid-svgs';
+
+interface MermaidStaticProps {
+  diagramHash: string;
+}
+
+export function MermaidStatic({ diagramHash }: MermaidStaticProps) {
+  const data = mermaidSvgs[diagramHash];
+
+  if (!data) {
+    return (
+      <div style={{
+        border: '1px solid var(--clearify-border)',
+        borderRadius: '0.5rem',
+        padding: '1rem',
+        marginBottom: '1rem',
+        color: '#ef4444',
+        fontSize: '0.875rem',
+      }}>
+        Missing pre-rendered diagram: {diagramHash}
+      </div>
+    );
+  }
+
+  return (
+    <div className="clearify-mermaid-container" style={{ marginBottom: '1rem', display: 'flex', justifyContent: 'center' }}>
+      <div className="clearify-mermaid-light" dangerouslySetInnerHTML={{ __html: data.lightSvg }} />
+      <div className="clearify-mermaid-dark" dangerouslySetInnerHTML={{ __html: data.darkSvg }} />
+    </div>
+  );
+}

package/src/theme/components/OpenAPI.tsx

@@ -0,0 +1,160 @@
+import React, { useMemo } from 'react';
+import { useTheme } from '../ThemeProvider.js';
+
+interface OpenAPIProps {
+  /** Inline spec as a parsed object or raw string (JSON/YAML). Falls back to config-based spec. */
+  spec?: string | Record<string, unknown>;
+  /** URL to fetch the OpenAPI spec from at runtime */
+  url?: string;
+  /** Hide the built-in Scalar sidebar (default: true, since Clearify has its own sidebar) */
+  hideSidebar?: boolean;
+  /** Hide the dark mode toggle (default: true, Clearify controls dark mode) */
+  hideDarkModeToggle?: boolean;
+  /** Hide the search (default: true, Clearify has its own search) */
+  hideSearch?: boolean;
+  /** Layout style: 'modern' or 'classic' */
+  layout?: 'modern' | 'classic';
+  /** Enable Scalar's path-based routing. Pass { basePath: '/api' } or true for default '/api'. */
+  pathRouting?: { basePath: string } | boolean;
+}
+
+// SSR guard: Scalar requires DOM
+const LazyApiReference = typeof window !== 'undefined'
+  ? React.lazy(() =>
+      import('@scalar/api-reference-react').then((mod) => ({
+        default: mod.ApiReferenceReact,
+      }))
+    )
+  : null;
+
+export function OpenAPI({
+  spec,
+  url,
+  hideSidebar = true,
+  hideDarkModeToggle = true,
+  hideSearch = true,
+  layout = 'modern',
+  pathRouting,
+}: OpenAPIProps) {
+  const { theme } = useTheme();
+
+  const resolvedSpec = spec ?? null;
+
+  const configuration = useMemo(() => {
+    const config: Record<string, unknown> = {
+      // Use 'none' theme so Clearify's CSS variable bridge takes full control
+      theme: 'none',
+      forceDarkModeState: theme === 'dark' ? 'dark' : 'light',
+      hideDarkModeToggle,
+      showSidebar: !hideSidebar,
+      hideSearch,
+      layout,
+      withDefaultFonts: false,
+      customCss: SCALAR_CUSTOM_CSS,
+    };
+
+    if (pathRouting) {
+      config.pathRouting = pathRouting === true
+        ? { basePath: '/api' }
+        : pathRouting;
+    }
+
+    if (url) {
+      config.url = url;
+    } else if (typeof resolvedSpec === 'string') {
+      config.content = resolvedSpec;
+    } else if (resolvedSpec && typeof resolvedSpec === 'object') {
+      config.content = resolvedSpec;
+    }
+
+    return config;
+  }, [resolvedSpec, url, theme, hideSidebar, hideDarkModeToggle, hideSearch, layout, pathRouting]);
+
+  // No spec provided via props, config, or URL
+  if (!url && !resolvedSpec) {
+    return (
+      <div
+        style={{
+          border: '1px solid var(--clearify-border)',
+          borderRadius: 'var(--clearify-radius)',
+          padding: '1.5rem',
+          color: 'var(--clearify-text-secondary)',
+          fontSize: '0.875rem',
+        }}
+      >
+        <strong>OpenAPI:</strong> No spec provided. Pass a <code>spec</code> or <code>url</code> prop,
+        or set <code>openapi.spec</code> in your Clearify config.
+      </div>
+    );
+  }
+
+  // SSR fallback
+  if (typeof window === 'undefined' || !LazyApiReference) {
+    return (
+      <div
+        style={{
+          border: '1px solid var(--clearify-border)',
+          borderRadius: 'var(--clearify-radius)',
+          padding: '2rem',
+          textAlign: 'center',
+          color: 'var(--clearify-text-secondary)',
+        }}
+      >
+        Loading API Reference...
+      </div>
+    );
+  }
+
+  return (
+    <div className="clearify-openapi-container">
+      <React.Suspense
+        fallback={
+          <div
+            style={{
+              border: '1px solid var(--clearify-border)',
+              borderRadius: 'var(--clearify-radius)',
+              padding: '2rem',
+              textAlign: 'center',
+              color: 'var(--clearify-text-secondary)',
+            }}
+          >
+            Loading API Reference...
+          </div>
+        }
+      >
+        <LazyApiReference configuration={configuration} />
+      </React.Suspense>
+    </div>
+  );
+}
+
+/** Custom CSS to integrate Scalar with Clearify's design tokens */
+const SCALAR_CUSTOM_CSS = `
+  .scalar-app {
+    --scalar-font: var(--font-sans);
+    --scalar-font-code: var(--font-mono);
+
+    --scalar-color-1: var(--clearify-text);
+    --scalar-color-2: var(--clearify-text-secondary);
+    --scalar-color-3: var(--clearify-text-tertiary);
+
+    --scalar-color-accent: var(--clearify-primary);
+
+    --scalar-background-1: var(--clearify-bg);
+    --scalar-background-2: var(--clearify-bg-secondary);
+    --scalar-background-3: var(--clearify-bg-tertiary);
+
+    --scalar-border-color: var(--clearify-border-strong);
+
+    --scalar-radius: var(--clearify-radius-sm);
+    --scalar-radius-lg: var(--clearify-radius);
+
+    --scalar-shadow-1: var(--clearify-shadow-sm);
+    --scalar-shadow-2: var(--clearify-shadow);
+  }
+
+  .scalar-app .section {
+    padding-left: 0;
+    padding-right: 0;
+  }
+`;

package/src/theme/components/OpenAPIPage.tsx

@@ -0,0 +1,16 @@
+import { OpenAPI } from './OpenAPI.js';
+// @ts-expect-error virtual module
+import config from 'virtual:clearify/config';
+// @ts-expect-error virtual module
+import openapiSpec from 'virtual:clearify/openapi-spec';
+
+export default function OpenAPIPage() {
+  const basePath = config.openapi?.basePath ?? '/api';
+  return (
+    <div className="clearify-openapi-page" style={{ margin: '0 -1.5rem', maxWidth: 'none' }}>
+      <OpenAPI spec={openapiSpec} hideSidebar={true} pathRouting={{ basePath }} />
+    </div>
+  );
+}
+
+export const frontmatter = { title: 'API Reference', description: 'API documentation' };

package/src/theme/components/Steps.tsx

@@ -0,0 +1,76 @@
+import React, { Children, isValidElement } from 'react';
+
+interface StepProps {
+  title?: string;
+  children: React.ReactNode;
+}
+
+export function Step({ title, children }: StepProps) {
+  return (
+    <div>
+      {title && (
+        <div style={{ fontWeight: 600, marginBottom: '0.25rem', letterSpacing: '-0.01em' }}>
+          {title}
+        </div>
+      )}
+      <div style={{ color: 'var(--clearify-text-secondary)', fontSize: '0.9375rem', lineHeight: 1.6 }}>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+interface StepsProps {
+  children: React.ReactNode;
+}
+
+export function Steps({ children }: StepsProps) {
+  const steps = Children.toArray(children).filter(isValidElement);
+
+  return (
+    <div style={{ marginBottom: '1.75rem' }}>
+      {steps.map((step, i) => (
+        <div key={i} style={{ display: 'flex', gap: '1rem', position: 'relative' }}>
+          {/* Vertical connector line */}
+          {i < steps.length - 1 && (
+            <div
+              style={{
+                position: 'absolute',
+                left: 15,
+                top: 36,
+                bottom: 0,
+                width: 1,
+                background: 'var(--clearify-border-strong)',
+              }}
+            />
+          )}
+          {/* Step number with gradient */}
+          <div
+            style={{
+              width: 32,
+              height: 32,
+              borderRadius: '50%',
+              background: 'var(--clearify-gradient)',
+              color: '#fff',
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              fontSize: '0.8125rem',
+              fontWeight: 700,
+              flexShrink: 0,
+              position: 'relative',
+              zIndex: 1,
+              boxShadow: '0 2px 8px rgba(99, 102, 241, 0.2)',
+            }}
+          >
+            {i + 1}
+          </div>
+          {/* Step content */}
+          <div style={{ flex: 1, paddingBottom: '1.75rem', paddingTop: '0.25rem' }}>
+            {step}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}