@marlinjai/clearify 1.5.2 → 1.6.0

package/src/theme/components/OpenAPIPage.tsx

@@ -1,14 +1,104 @@
-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';
 
+import React, { useEffect } from 'react';
+import { ApiHeader } from './openapi/ApiHeader.js';
+import { TagGroup } from './openapi/TagGroup.js';
+
+const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch'] as const;
+
 export default function OpenAPIPage() {
-  const basePath = config.openapi?.basePath ?? '/api';
+  const spec = openapiSpec as Record<string, any> | null;
+
+  // Scroll to hash anchor on mount and hash change
+  useEffect(() => {
+    const scrollToHash = () => {
+      const hash = window.location.hash.slice(1); // remove #
+      if (!hash) return;
+      // Small delay to ensure DOM is rendered
+      setTimeout(() => {
+        const el = document.getElementById(hash);
+        if (el) {
+          el.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        }
+      }, 100);
+    };
+
+    scrollToHash();
+    window.addEventListener('hashchange', scrollToHash);
+    return () => window.removeEventListener('hashchange', scrollToHash);
+  }, []);
+
+  if (!spec) {
+    return (
+      <div style={{
+        border: '1px solid var(--clearify-border)',
+        borderRadius: 'var(--clearify-radius)',
+        padding: '2rem',
+        textAlign: 'center',
+        color: 'var(--clearify-text-secondary)',
+        fontSize: '0.875rem',
+      }}>
+        No OpenAPI spec provided. Set <code style={{ fontFamily: 'var(--font-mono)' }}>openapi.spec</code> in your Clearify config.
+      </div>
+    );
+  }
+
+  // Determine base URL from spec or config
+  const baseUrl = spec.servers?.[0]?.url ?? 'http://localhost:3000';
+
+  // Group operations by tag
+  const paths = spec.paths ?? {};
+  const tagMap = new Map<string, { tag: string; description?: string; operations: Array<{ method: string; path: string; operation: Record<string, any> }> }>();
+  const tagDescriptions = new Map<string, string>();
+
+  if (Array.isArray(spec.tags)) {
+    for (const t of spec.tags) {
+      if (t.name && t.description) tagDescriptions.set(t.name, t.description);
+    }
+  }
+
+  for (const [pathStr, pathItem] of Object.entries(paths)) {
+    if (!pathItem || typeof pathItem !== 'object') continue;
+
+    for (const method of HTTP_METHODS) {
+      const operation = (pathItem as Record<string, any>)[method];
+      if (!operation || typeof operation !== 'object') continue;
+
+      const tags: string[] = Array.isArray(operation.tags) && operation.tags.length > 0
+        ? [operation.tags[0]]
+        : ['Default'];
+
+      for (const tag of tags) {
+        if (!tagMap.has(tag)) {
+          tagMap.set(tag, { tag, description: tagDescriptions.get(tag), operations: [] });
+        }
+        tagMap.get(tag)!.operations.push({ method: method.toUpperCase(), path: pathStr, operation });
+      }
+    }
+  }
+
+  // Sort: "Default" last, others alphabetical
+  const tagGroups = [...tagMap.values()].sort((a, b) => {
+    if (a.tag === 'Default') return 1;
+    if (b.tag === 'Default') return -1;
+    return a.tag.localeCompare(b.tag);
+  });
+
   return (
-    <div className="clearify-openapi-page" style={{ margin: '0 -1.5rem', maxWidth: 'none' }}>
-      <OpenAPI spec={openapiSpec} hideSidebar={true} pathRouting={{ basePath }} />
+    <div className="clearify-openapi-page" style={{ maxWidth: 'none' }}>
+      <ApiHeader spec={spec} />
+      {tagGroups.map((group) => (
+        <TagGroup
+          key={group.tag}
+          tag={group.tag}
+          description={group.description}
+          operations={group.operations}
+          baseUrl={baseUrl}
+        />
+      ))}
     </div>
   );
 }

package/src/theme/components/openapi/ApiHeader.tsx

@@ -0,0 +1,119 @@
+import React from 'react';
+
+interface ApiHeaderProps {
+  spec: Record<string, any>;
+}
+
+export function ApiHeader({ spec }: ApiHeaderProps) {
+  const info = spec.info ?? {};
+  const servers = spec.servers ?? [];
+  const securitySchemes = spec.components?.securitySchemes ?? {};
+  const schemeEntries = Object.entries(securitySchemes);
+
+  return (
+    <div style={{
+      marginBottom: '2rem',
+      paddingBottom: '1.5rem',
+      borderBottom: '1px solid var(--clearify-border)',
+    }}>
+      {/* Title + Version */}
+      <div style={{ display: 'flex', alignItems: 'center', gap: '0.75rem', flexWrap: 'wrap' }}>
+        <h1 style={{
+          fontSize: '1.75rem',
+          fontWeight: 800,
+          color: 'var(--clearify-text)',
+          letterSpacing: '-0.035em',
+          lineHeight: 1.2,
+          margin: 0,
+        }}>
+          {info.title ?? 'API Reference'}
+        </h1>
+        {info.version && (
+          <span style={{
+            fontFamily: 'var(--font-mono)',
+            fontSize: '0.75rem',
+            fontWeight: 600,
+            color: 'var(--clearify-primary)',
+            background: 'var(--clearify-primary-soft)',
+            padding: '0.15rem 0.5rem',
+            borderRadius: '4px',
+          }}>
+            v{info.version}
+          </span>
+        )}
+        <span style={{
+          fontFamily: 'var(--font-mono)',
+          fontSize: '0.6875rem',
+          color: 'var(--clearify-text-tertiary)',
+        }}>
+          OAS {spec.openapi ?? '3.0'}
+        </span>
+      </div>
+
+      {/* Description */}
+      {info.description && (
+        <p style={{
+          fontSize: '0.9375rem',
+          color: 'var(--clearify-text-secondary)',
+          marginTop: '0.5rem',
+          lineHeight: 1.6,
+          maxWidth: '60ch',
+        }}>
+          {info.description}
+        </p>
+      )}
+
+      {/* Server + Auth row */}
+      <div style={{ display: 'flex', gap: '1rem', flexWrap: 'wrap', marginTop: '0.875rem' }}>
+        {/* Server URL */}
+        {servers.length > 0 && (
+          <div style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: '0.375rem',
+            fontSize: '0.8125rem',
+          }}>
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" style={{ color: 'var(--clearify-text-tertiary)' }}>
+              <rect x="2" y="2" width="20" height="8" rx="2" ry="2" />
+              <rect x="2" y="14" width="20" height="8" rx="2" ry="2" />
+              <line x1="6" y1="6" x2="6.01" y2="6" />
+              <line x1="6" y1="18" x2="6.01" y2="18" />
+            </svg>
+            <span style={{ fontFamily: 'var(--font-mono)', color: 'var(--clearify-text-secondary)' }}>
+              {servers[0].url}
+            </span>
+          </div>
+        )}
+
+        {/* Auth schemes */}
+        {schemeEntries.map(([name, scheme]: [string, any]) => (
+          <div
+            key={name}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: '0.375rem',
+              fontSize: '0.8125rem',
+            }}
+          >
+            <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" style={{ color: 'var(--clearify-text-tertiary)' }}>
+              <rect x="3" y="11" width="18" height="11" rx="2" ry="2" />
+              <path d="M7 11V7a5 5 0 0 1 10 0v4" />
+            </svg>
+            <span style={{
+              fontFamily: 'var(--font-mono)',
+              fontSize: '0.75rem',
+              color: 'var(--clearify-text-secondary)',
+              background: 'var(--clearify-bg-secondary)',
+              padding: '0.1rem 0.4rem',
+              borderRadius: '4px',
+              border: '1px solid var(--clearify-border)',
+            }}>
+              {scheme.type === 'http' ? `${scheme.scheme} (${scheme.bearerFormat ?? 'token'})` : `${scheme.type}: ${name}`}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/theme/components/openapi/CodeExamples.tsx

@@ -0,0 +1,100 @@
+import React, { useState, useMemo, useRef } from 'react';
+import { generateSnippets } from './generate-snippets.js';
+
+interface CodeExamplesProps {
+  method: string;
+  path: string;
+  baseUrl: string;
+  parameters?: any[];
+  requestBody?: Record<string, any>;
+  security?: Array<Record<string, string[]>>;
+}
+
+export function CodeExamples({ method, path, baseUrl, parameters, requestBody, security }: CodeExamplesProps) {
+  const [activeTab, setActiveTab] = useState(0);
+  const [copied, setCopied] = useState(false);
+  const codeRef = useRef<HTMLPreElement>(null);
+
+  const snippets = useMemo(
+    () => generateSnippets({ method, path, baseUrl, parameters, requestBody, security }),
+    [method, path, baseUrl, parameters, requestBody, security]
+  );
+
+  const handleCopy = async () => {
+    const text = codeRef.current?.textContent ?? snippets[activeTab]?.code ?? '';
+    await navigator.clipboard.writeText(text);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  };
+
+  return (
+    <div style={{
+      border: '1px solid var(--clearify-border)',
+      borderRadius: 'var(--clearify-radius)',
+      overflow: 'hidden',
+      background: '#1e1e2e',
+    }}>
+      <div style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        borderBottom: '1px solid rgba(255,255,255,0.08)',
+        padding: '0 0.5rem',
+      }}>
+        <div style={{ display: 'flex', gap: '0.125rem' }}>
+          {snippets.map((tab, i) => (
+            <button
+              key={tab.label}
+              onClick={() => setActiveTab(i)}
+              style={{
+                fontFamily: 'var(--font-mono)',
+                fontSize: '0.75rem',
+                fontWeight: i === activeTab ? 600 : 400,
+                padding: '0.5rem 0.625rem',
+                background: 'none',
+                border: 'none',
+                borderBottom: i === activeTab ? '2px solid #818cf8' : '2px solid transparent',
+                color: i === activeTab ? '#e2e8f0' : '#94a3b8',
+                cursor: 'pointer',
+                transition: 'color 0.15s ease',
+              }}
+            >
+              {tab.label}
+            </button>
+          ))}
+        </div>
+        <button
+          onClick={handleCopy}
+          style={{
+            background: 'none',
+            border: '1px solid rgba(255,255,255,0.1)',
+            borderRadius: '4px',
+            padding: '0.2rem 0.5rem',
+            cursor: 'pointer',
+            fontSize: '0.6875rem',
+            color: copied ? '#818cf8' : '#94a3b8',
+            fontFamily: 'var(--font-sans)',
+            transition: 'all 0.15s ease',
+          }}
+        >
+          {copied ? 'Copied!' : 'Copy'}
+        </button>
+      </div>
+      <pre
+        ref={codeRef}
+        style={{
+          padding: '1rem 1.25rem',
+          margin: 0,
+          fontFamily: 'var(--font-mono)',
+          fontSize: '0.8125rem',
+          lineHeight: 1.7,
+          color: '#e2e8f0',
+          overflow: 'auto',
+          maxHeight: '400px',
+        }}
+      >
+        <code>{snippets[activeTab]?.code ?? ''}</code>
+      </pre>
+    </div>
+  );
+}

package/src/theme/components/openapi/MethodBadge.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+
+const METHOD_STYLES: Record<string, { bg: string; color: string; darkColor: string }> = {
+  GET:    { bg: 'rgba(5, 150, 105, 0.12)',  color: '#059669', darkColor: '#34d399' },
+  POST:   { bg: 'rgba(37, 99, 235, 0.12)',  color: '#2563eb', darkColor: '#60a5fa' },
+  PUT:    { bg: 'rgba(217, 119, 6, 0.12)',   color: '#d97706', darkColor: '#fbbf24' },
+  DELETE: { bg: 'rgba(220, 38, 38, 0.12)',   color: '#dc2626', darkColor: '#f87171' },
+  PATCH:  { bg: 'rgba(124, 58, 237, 0.12)',  color: '#7c3aed', darkColor: '#a78bfa' },
+};
+
+interface MethodBadgeProps {
+  method: string;
+}
+
+export function MethodBadge({ method }: MethodBadgeProps) {
+  const upper = method.toUpperCase();
+  const style = METHOD_STYLES[upper] ?? { bg: 'rgba(0,0,0,0.06)', color: 'inherit', darkColor: 'inherit' };
+
+  return (
+    <>
+      <span
+        className={`clearify-method-badge clearify-method-${upper.toLowerCase()}`}
+        style={{
+          fontFamily: 'var(--font-mono)',
+          fontSize: '0.6875rem',
+          fontWeight: 700,
+          letterSpacing: '0.04em',
+          textTransform: 'uppercase' as const,
+          padding: '0.15rem 0.5rem',
+          borderRadius: '4px',
+          lineHeight: 1.5,
+          display: 'inline-block',
+          background: style.bg,
+          color: style.color,
+        }}
+      >
+        {upper}
+      </span>
+      <style>{`
+        .dark .clearify-method-get { color: ${METHOD_STYLES.GET.darkColor} !important; }
+        .dark .clearify-method-post { color: ${METHOD_STYLES.POST.darkColor} !important; }
+        .dark .clearify-method-put { color: ${METHOD_STYLES.PUT.darkColor} !important; }
+        .dark .clearify-method-delete { color: ${METHOD_STYLES.DELETE.darkColor} !important; }
+        .dark .clearify-method-patch { color: ${METHOD_STYLES.PATCH.darkColor} !important; }
+      `}</style>
+    </>
+  );
+}

package/src/theme/components/openapi/OperationCard.tsx

@@ -0,0 +1,198 @@
+import React from 'react';
+import { MethodBadge } from './MethodBadge.js';
+import { ParameterTable } from './ParameterTable.js';
+import { SchemaViewer } from './SchemaViewer.js';
+import { ResponseList } from './ResponseList.js';
+import { CodeExamples } from './CodeExamples.js';
+
+interface OperationCardProps {
+  method: string;
+  path: string;
+  operation: Record<string, any>;
+  baseUrl: string;
+  anchorId: string;
+}
+
+export function OperationCard({ method, path, operation, baseUrl, anchorId }: OperationCardProps) {
+  const summary = operation.summary ?? operation.description ?? `${method.toUpperCase()} ${path}`;
+  const description = operation.description && operation.description !== summary ? operation.description : null;
+  const parameters = operation.parameters ?? [];
+  const requestBody = operation.requestBody;
+  const responses = operation.responses ?? {};
+  const security = operation.security;
+  const deprecated = !!operation.deprecated;
+
+  const bodySchema = requestBody?.content?.['application/json']?.schema;
+
+  return (
+    <div
+      id={anchorId}
+      style={{
+        border: '1px solid var(--clearify-border)',
+        borderRadius: 'var(--clearify-radius)',
+        overflow: 'hidden',
+        marginBottom: '1rem',
+        transition: 'border-color 0.2s ease, box-shadow 0.2s ease',
+      }}
+      className="clearify-operation-card"
+    >
+      {/* Two-column layout */}
+      <div className="clearify-operation-layout" style={{
+        display: 'grid',
+        gridTemplateColumns: '1fr 1fr',
+        gap: 0,
+      }}>
+        {/* Left column — documentation */}
+        <div style={{
+          padding: '1.25rem 1.5rem',
+          borderRight: '1px solid var(--clearify-border)',
+        }}>
+          {/* Method + Path header */}
+          <div style={{ display: 'flex', alignItems: 'center', gap: '0.625rem', flexWrap: 'wrap' }}>
+            <MethodBadge method={method} />
+            <span style={{
+              fontFamily: 'var(--font-mono)',
+              fontSize: '0.875rem',
+              fontWeight: 500,
+              color: deprecated ? 'var(--clearify-text-tertiary)' : 'var(--clearify-text)',
+              textDecoration: deprecated ? 'line-through' : undefined,
+              letterSpacing: '-0.01em',
+            }}>
+              {path}
+            </span>
+            {deprecated && (
+              <span style={{
+                fontSize: '0.6875rem',
+                fontWeight: 600,
+                textTransform: 'uppercase' as const,
+                color: '#d97706',
+                background: 'rgba(217, 119, 6, 0.1)',
+                padding: '0.1rem 0.4rem',
+                borderRadius: '4px',
+              }}>
+                Deprecated
+              </span>
+            )}
+            {security && security.length > 0 && (
+              <span style={{
+                fontSize: '0.6875rem',
+                color: 'var(--clearify-text-tertiary)',
+                display: 'flex',
+                alignItems: 'center',
+                gap: '0.25rem',
+              }}>
+                <svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                  <rect x="3" y="11" width="18" height="11" rx="2" ry="2" />
+                  <path d="M7 11V7a5 5 0 0 1 10 0v4" />
+                </svg>
+                Auth
+              </span>
+            )}
+          </div>
+
+          {/* Summary */}
+          <div style={{
+            fontSize: '0.9375rem',
+            fontWeight: 600,
+            color: 'var(--clearify-text)',
+            marginTop: '0.625rem',
+            letterSpacing: '-0.01em',
+          }}>
+            {summary}
+          </div>
+
+          {/* Description */}
+          {description && (
+            <div style={{
+              fontSize: '0.8125rem',
+              color: 'var(--clearify-text-secondary)',
+              marginTop: '0.375rem',
+              lineHeight: 1.6,
+            }}>
+              {description}
+            </div>
+          )}
+
+          {/* Parameters */}
+          {parameters.length > 0 && <ParameterTable parameters={parameters} />}
+
+          {/* Request Body */}
+          {bodySchema && (
+            <div style={{ marginTop: '0.75rem' }}>
+              <div style={{
+                fontSize: '0.6875rem',
+                fontWeight: 600,
+                textTransform: 'uppercase' as const,
+                letterSpacing: '0.05em',
+                color: 'var(--clearify-text-tertiary)',
+                marginBottom: '0.375rem',
+              }}>
+                Request Body
+                {requestBody?.required && (
+                  <span className="clearify-required-badge" style={{
+                    marginLeft: '0.5rem',
+                    color: '#d97706',
+                  }}>
+                    required
+                  </span>
+                )}
+              </div>
+              <div style={{
+                border: '1px solid var(--clearify-border)',
+                borderRadius: 'var(--clearify-radius)',
+                padding: '0.625rem 0.875rem',
+              }}>
+                <SchemaViewer schema={bodySchema} />
+              </div>
+            </div>
+          )}
+
+          {/* Responses */}
+          <ResponseList responses={responses} />
+        </div>
+
+        {/* Right column — code examples */}
+        <div style={{
+          padding: '1.25rem 1.5rem',
+          background: 'var(--clearify-bg-secondary)',
+        }}>
+          <div style={{
+            fontSize: '0.6875rem',
+            fontWeight: 600,
+            textTransform: 'uppercase' as const,
+            letterSpacing: '0.05em',
+            color: 'var(--clearify-text-tertiary)',
+            marginBottom: '0.625rem',
+          }}>
+            Examples
+          </div>
+          <CodeExamples
+            method={method}
+            path={path}
+            baseUrl={baseUrl}
+            parameters={parameters}
+            requestBody={requestBody}
+            security={security}
+          />
+        </div>
+      </div>
+
+      <style>{`
+        .clearify-operation-card:hover {
+          border-color: var(--clearify-border-strong) !important;
+          box-shadow: var(--clearify-shadow-sm);
+        }
+        @media (max-width: 900px) {
+          .clearify-operation-layout {
+            grid-template-columns: 1fr !important;
+          }
+          .clearify-operation-layout > div:first-child {
+            border-right: none !important;
+            border-bottom: 1px solid var(--clearify-border) !important;
+          }
+        }
+        .dark .clearify-required-badge { color: #fbbf24 !important; }
+      `}</style>
+    </div>
+  );
+}