@marlinjai/clearify 1.5.3 → 1.6.0

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>
+  );
+}

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

@@ -0,0 +1,134 @@
+import React from 'react';
+
+interface Parameter {
+  name: string;
+  in: string;
+  required?: boolean;
+  schema?: Record<string, any>;
+  description?: string;
+  deprecated?: boolean;
+}
+
+interface ParameterTableProps {
+  parameters: Parameter[];
+}
+
+const LOCATION_ORDER = ['path', 'query', 'header', 'cookie'];
+
+export function ParameterTable({ parameters }: ParameterTableProps) {
+  if (!parameters || parameters.length === 0) return null;
+
+  // Group by location
+  const grouped = new Map<string, Parameter[]>();
+  for (const param of parameters) {
+    const loc = param.in ?? 'query';
+    const existing = grouped.get(loc);
+    if (existing) existing.push(param);
+    else grouped.set(loc, [param]);
+  }
+
+  const sortedGroups = [...grouped.entries()].sort(
+    ([a], [b]) => LOCATION_ORDER.indexOf(a) - LOCATION_ORDER.indexOf(b)
+  );
+
+  return (
+    <div style={{ marginTop: '0.75rem' }}>
+      {sortedGroups.map(([location, params]) => (
+        <div key={location} style={{ marginBottom: '0.75rem' }}>
+          <div style={{
+            fontSize: '0.6875rem',
+            fontWeight: 600,
+            textTransform: 'uppercase' as const,
+            letterSpacing: '0.05em',
+            color: 'var(--clearify-text-tertiary)',
+            marginBottom: '0.375rem',
+          }}>
+            {location} parameters
+          </div>
+          <div style={{
+            border: '1px solid var(--clearify-border)',
+            borderRadius: 'var(--clearify-radius)',
+            overflow: 'hidden',
+          }}>
+            {params.map((param, i) => (
+              <div
+                key={param.name}
+                className="clearify-param-row"
+                style={{
+                  padding: '0.625rem 0.875rem',
+                  borderBottom: i < params.length - 1 ? '1px solid var(--clearify-border)' : undefined,
+                  transition: 'background-color 0.15s ease',
+                }}
+              >
+                <div style={{ display: 'flex', alignItems: 'center', gap: '0.5rem', flexWrap: 'wrap' }}>
+                  <span style={{
+                    fontFamily: 'var(--font-mono)',
+                    fontSize: '0.8125rem',
+                    fontWeight: 600,
+                    color: param.deprecated ? 'var(--clearify-text-tertiary)' : 'var(--clearify-text)',
+                    textDecoration: param.deprecated ? 'line-through' : undefined,
+                  }}>
+                    {param.name}
+                  </span>
+                  {param.schema?.type && (
+                    <span style={{
+                      fontFamily: 'var(--font-mono)',
+                      fontSize: '0.75rem',
+                      color: 'var(--clearify-text-tertiary)',
+                    }}>
+                      {param.schema.type}
+                    </span>
+                  )}
+                  {param.required && (
+                    <span className="clearify-required-badge" style={{
+                      fontSize: '0.6875rem',
+                      fontWeight: 600,
+                      textTransform: 'uppercase' as const,
+                      letterSpacing: '0.04em',
+                      color: '#d97706',
+                    }}>
+                      required
+                    </span>
+                  )}
+                  {param.deprecated && (
+                    <span style={{ fontSize: '0.6875rem', color: 'var(--clearify-text-tertiary)' }}>deprecated</span>
+                  )}
+                </div>
+                {param.description && (
+                  <div style={{
+                    fontSize: '0.8125rem',
+                    color: 'var(--clearify-text-secondary)',
+                    marginTop: '0.25rem',
+                    lineHeight: 1.5,
+                  }}>
+                    {param.description}
+                  </div>
+                )}
+                {param.schema?.enum && (
+                  <div style={{ display: 'flex', gap: '0.375rem', flexWrap: 'wrap', marginTop: '0.375rem' }}>
+                    {param.schema.enum.map((val: any, j: number) => (
+                      <span key={j} style={{
+                        fontFamily: 'var(--font-mono)',
+                        fontSize: '0.75rem',
+                        background: 'var(--clearify-bg-secondary)',
+                        border: '1px solid var(--clearify-border)',
+                        borderRadius: '4px',
+                        padding: '0.1rem 0.4rem',
+                      }}>
+                        {String(val)}
+                      </span>
+                    ))}
+                  </div>
+                )}
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+      <style>{`
+        .clearify-param-row:hover { background-color: var(--clearify-bg-secondary) !important; }
+        .dark .clearify-required-badge { color: #fbbf24 !important; }
+      `}</style>
+    </div>
+  );
+}