@marlinjai/clearify 1.5.2 → 1.6.0

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

@@ -0,0 +1,105 @@
+import React, { useState } from 'react';
+import { OperationCard } from './OperationCard.js';
+
+interface TagGroupProps {
+  tag: string;
+  description?: string;
+  operations: Array<{ method: string; path: string; operation: Record<string, any> }>;
+  baseUrl: string;
+}
+
+/** Build an anchor ID matching the sidebar navigation pattern */
+function operationAnchorId(tag: string, method: string, path: string): string {
+  const slug = `${method.toLowerCase()}${path.replace(/[{}]/g, '')}`;
+  return `tag/${encodeURIComponent(tag)}/${slug}`;
+}
+
+export function TagGroup({ tag, description, operations, baseUrl }: TagGroupProps) {
+  const [expanded, setExpanded] = useState(true);
+
+  return (
+    <div
+      id={`tag/${encodeURIComponent(tag)}`}
+      style={{ marginBottom: '2rem' }}
+    >
+      {/* Tag header */}
+      <button
+        onClick={() => setExpanded(!expanded)}
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: '0.625rem',
+          width: '100%',
+          background: 'none',
+          border: 'none',
+          cursor: 'pointer',
+          padding: '0.5rem 0',
+          textAlign: 'left',
+          fontFamily: 'var(--font-sans)',
+        }}
+      >
+        <svg
+          width="18"
+          height="18"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          style={{
+            flexShrink: 0,
+            transform: expanded ? 'rotate(90deg)' : 'rotate(0deg)',
+            transition: 'transform 0.2s cubic-bezier(0.4, 0, 0.2, 1)',
+            color: 'var(--clearify-text-secondary)',
+          }}
+        >
+          <polyline points="9 18 15 12 9 6" />
+        </svg>
+        <span style={{
+          fontSize: '1.25rem',
+          fontWeight: 700,
+          color: 'var(--clearify-text)',
+          letterSpacing: '-0.02em',
+        }}>
+          {tag}
+        </span>
+        <span style={{
+          fontSize: '0.75rem',
+          color: 'var(--clearify-text-tertiary)',
+          fontFamily: 'var(--font-mono)',
+        }}>
+          {operations.length} endpoint{operations.length !== 1 ? 's' : ''}
+        </span>
+      </button>
+
+      {description && (
+        <div style={{
+          fontSize: '0.875rem',
+          color: 'var(--clearify-text-secondary)',
+          marginBottom: '0.75rem',
+          paddingLeft: '2.125rem',
+          lineHeight: 1.6,
+        }}>
+          {description}
+        </div>
+      )}
+
+      {/* Operations */}
+      {expanded && (
+        <div style={{ animation: 'clearify-fade-in 0.2s ease-out' }}>
+          {operations.map(({ method, path, operation }) => (
+            <OperationCard
+              key={`${method}-${path}`}
+              method={method}
+              path={path}
+              operation={operation}
+              baseUrl={baseUrl}
+              anchorId={operationAnchorId(tag, method, path)}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/theme/components/openapi/generate-snippets.ts

@@ -0,0 +1,102 @@
+interface SnippetInput {
+  method: string;
+  path: string;
+  baseUrl: string;
+  parameters?: Array<{ name: string; in: string; required?: boolean; schema?: { type?: string } }>;
+  requestBody?: Record<string, any>;
+  security?: Array<Record<string, string[]>>;
+}
+
+export function generateSnippets(input: SnippetInput): { label: string; code: string }[] {
+  const { method, path, baseUrl, parameters = [], requestBody, security } = input;
+  const upper = method.toUpperCase();
+  const url = `${baseUrl}${path}`;
+
+  // Replace path params with placeholder values
+  const urlWithParams = url.replace(/\{(\w+)\}/g, ':$1');
+
+  const hasBody = !!requestBody;
+  const bodySchema = requestBody?.content?.['application/json']?.schema;
+  const bodyExample = bodySchema ? generateExample(bodySchema) : null;
+  const bodyJson = bodyExample ? JSON.stringify(bodyExample, null, 2) : null;
+
+  const hasAuth = security && security.length > 0;
+  const authHeader = hasAuth ? 'Authorization: Bearer YOUR_TOKEN' : '';
+
+  const queryParams = parameters.filter(p => p.in === 'query');
+  const queryString = queryParams.length > 0
+    ? '?' + queryParams.map(p => `${p.name}=VALUE`).join('&')
+    : '';
+
+  // curl
+  const curlParts = [`curl -X ${upper} '${urlWithParams}${queryString}'`];
+  if (hasAuth) curlParts.push(`  -H '${authHeader}'`);
+  if (hasBody) {
+    curlParts.push("  -H 'Content-Type: application/json'");
+    curlParts.push(`  -d '${bodyJson}'`);
+  }
+  const curl = curlParts.join(' \\\n');
+
+  // JavaScript fetch
+  const fetchHeaders: string[] = [];
+  if (hasAuth) fetchHeaders.push(`    'Authorization': 'Bearer YOUR_TOKEN'`);
+  if (hasBody) fetchHeaders.push(`    'Content-Type': 'application/json'`);
+
+  let jsParts = `const response = await fetch('${urlWithParams}${queryString}', {\n  method: '${upper}',\n`;
+  if (fetchHeaders.length > 0) {
+    jsParts += `  headers: {\n${fetchHeaders.join(',\n')}\n  },\n`;
+  }
+  if (hasBody) {
+    jsParts += `  body: JSON.stringify(${bodyJson}),\n`;
+  }
+  jsParts += '});\n\nconst data = await response.json();';
+
+  // Python requests
+  let pyParts = `import requests\n\n`;
+  pyParts += `response = requests.${method.toLowerCase()}(\n    '${urlWithParams}${queryString}'`;
+  if (hasAuth || hasBody) pyParts += ',';
+  pyParts += '\n';
+  if (hasAuth) {
+    pyParts += `    headers={'Authorization': 'Bearer YOUR_TOKEN'}`;
+    if (hasBody) pyParts += ',';
+    pyParts += '\n';
+  }
+  if (hasBody) {
+    pyParts += `    json=${bodyJson},\n`;
+  }
+  pyParts += ')\n\ndata = response.json()';
+
+  return [
+    { label: 'curl', code: curl },
+    { label: 'JavaScript', code: jsParts },
+    { label: 'Python', code: pyParts },
+  ];
+}
+
+/** Generate a minimal example object from a JSON Schema */
+function generateExample(schema: Record<string, any>): any {
+  if (schema.example !== undefined) return schema.example;
+
+  switch (schema.type) {
+    case 'string':
+      return schema.enum?.[0] ?? schema.default ?? 'string';
+    case 'number':
+    case 'integer':
+      return schema.default ?? schema.minimum ?? 0;
+    case 'boolean':
+      return schema.default ?? true;
+    case 'array':
+      return schema.items ? [generateExample(schema.items)] : [];
+    case 'object': {
+      const obj: Record<string, any> = {};
+      if (schema.properties) {
+        for (const [key, prop] of Object.entries(schema.properties)) {
+          obj[key] = generateExample(prop as Record<string, any>);
+        }
+      }
+      return obj;
+    }
+    default:
+      return null;
+  }
+}

package/src/theme/components/openapi/index.ts

@@ -0,0 +1,8 @@
+export { ApiHeader } from './ApiHeader.js';
+export { TagGroup } from './TagGroup.js';
+export { OperationCard } from './OperationCard.js';
+export { ParameterTable } from './ParameterTable.js';
+export { SchemaViewer } from './SchemaViewer.js';
+export { CodeExamples } from './CodeExamples.js';
+export { ResponseList } from './ResponseList.js';
+export { MethodBadge } from './MethodBadge.js';

package/src/theme/styles/globals.css

@@ -361,3 +361,8 @@ a:hover {
   0% { background-position: -200% 0; }
   100% { background-position: 200% 0; }
 }
+
+/* ─── OpenAPI page layout ─── */
+.clearify-openapi-page {
+  max-width: none;
+}