usulpro
/
banatie-service
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: extract components

This commit is contained in:
Oleg Proskurin 2025-10-18 01:14:41 +07:00
parent 94c8aafe5b
commit 813e0b186c
13 changed files with 2187 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

125
apps/landing/src/app/docs/api/text-to-image/page.tsx
View File

@ -1,14 +1,10 @@
'use client';
/**
* API Reference: Text to Image - Final Variant
* API Reference: Text to Image
*
* Features:
* - SubsectionNav at top
* - InteractiveAPIWidgetFinal with expand + success styling
* - Enhanced tables for parameters and error codes
* - Compact TipBox for parameter descriptions
* - Simplified Next Steps
* Refactored to use block components from @/components/docs/blocks
* Demonstrates API documentation patterns with semantic components
*/
import { DocsLayout } from '@/components/docs/layout/DocsLayout';
@ -20,6 +16,14 @@ import { Table } from '@/components/docs/shared/Table';
import { Breadcrumb } from '@/components/docs/shared/Breadcrumb';
import { CodeBlock } from '@/components/docs/shared/CodeBlock';
import { InteractiveAPIWidget } from '@/components/docs/blocks/InteractiveAPIWidget';
import {
Hero,
SectionHeader,
InlineCode,
EndpointCard,
LinkCard,
LinkCardGrid,
} from '@/components/docs/blocks';
const tocItems = [
{ id: 'overview', text: 'Overview', level: 2 },
@ -67,46 +71,44 @@ export default function TextToImageAPIPage() {
/>
{/* Hero Section */}
<div className="mb-12">
<h1 className="text-4xl md:text-5xl font-bold text-white mb-4">Text to Image</h1>
<p className="text-xl text-gray-400 leading-relaxed">
Generate high-quality images from text prompts using AI-powered models.
</p>
</div>
<Hero
title="Text to Image"
subtitle="Generate high-quality images from text prompts using AI-powered models."
/>
{/* Overview */}
<section id="overview" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-4">Overview</h2>
<SectionHeader level={2} id="overview">
Overview
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-4">
The Text to Image endpoint allows you to generate images from natural language descriptions.
Powered by Google Gemini 2.5 Flash and Imagen 4.0, it produces photorealistic images
optimized for your specified requirements.
</p>
<TipBox variant="compact" type="info">
<strong>Tip:</strong> Enable <code className="px-1.5 py-0.5 bg-slate-800 rounded text-purple-400">autoEnhance</code>
<strong>Tip:</strong> Enable <InlineCode>autoEnhance</InlineCode>
to let AI improve your prompts for better image quality.
</TipBox>
</section>
{/* Endpoint */}
<section id="endpoint" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-4">Endpoint</h2>
<div className="p-4 bg-slate-900/50 border border-slate-700 rounded-xl">
<div className="flex items-center gap-3 mb-2">
<span className="px-3 py-1 bg-green-600/20 text-green-400 text-xs font-bold rounded">
POST
</span>
<code className="text-sm text-white">/api/text-to-image</code>
</div>
<p className="text-xs text-gray-400">
Base URL: <code className="text-purple-400">https://api.banatie.com</code>
</p>
</div>
<SectionHeader level={2} id="endpoint">
Endpoint
</SectionHeader>
<EndpointCard
method="POST"
endpoint="/api/text-to-image"
baseUrl="https://api.banatie.com"
/>
</section>
{/* Parameters */}
<section id="parameters" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-6">Parameters</h2>
<SectionHeader level={2} id="parameters" className="mb-6">
Parameters
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-6">
All parameters should be sent in the request body as JSON.
</p>
@ -114,7 +116,7 @@ export default function TextToImageAPIPage() {
<Table
headers={['Parameter', 'Type', 'Required', 'Description']}
rows={parameters.map((param) => [
<code key="name" className="text-purple-400">{param.name}</code>,
<InlineCode key="name">{param.name}</InlineCode>,
<span key="type" className="text-cyan-400">{param.type}</span>,
<span key="required" className={param.required ? 'text-green-400' : 'text-gray-500'}>
{param.required ? 'Yes' : 'No'}
@ -125,16 +127,18 @@ export default function TextToImageAPIPage() {
<div className="mt-6">
<TipBox variant="compact" type="info">
<strong>Default Values:</strong> If not specified, <code className="px-1.5 py-0.5 bg-slate-800 rounded text-purple-400">filename</code> is
auto-generated, <code className="px-1.5 py-0.5 bg-slate-800 rounded text-purple-400">aspectRatio</code> defaults
to "1:1", and <code className="px-1.5 py-0.5 bg-slate-800 rounded text-purple-400">autoEnhance</code> is false.
<strong>Default Values:</strong> If not specified, <InlineCode>filename</InlineCode> is
auto-generated, <InlineCode>aspectRatio</InlineCode> defaults
to "1:1", and <InlineCode>autoEnhance</InlineCode> is false.
</TipBox>
</div>
</section>
{/* Response */}
<section id="response" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-4">Response</h2>
<SectionHeader level={2} id="response" className="mb-4">
Response
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-4">
On success, the API returns a JSON object containing the generated image URL and metadata.
</p>
@ -164,7 +168,9 @@ export default function TextToImageAPIPage() {
{/* Error Codes */}
<section id="error-codes" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-6">Error Codes</h2>
<SectionHeader level={2} id="error-codes" className="mb-6">
Error Codes
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-6">
The API uses standard HTTP status codes and returns descriptive error messages.
</p>
@ -173,22 +179,22 @@ export default function TextToImageAPIPage() {
headers={['Status Code', 'Error Type', 'Description']}
rows={[
[
<code key="code" className="text-red-400">400</code>,
<InlineCode key="code" color="error">400</InlineCode>,
'Bad Request',
'Missing or invalid parameters in the request body',
],
[
<code key="code" className="text-red-400">401</code>,
<InlineCode key="code" color="error">401</InlineCode>,
'Unauthorized',
'Missing or invalid API key in X-API-Key header',
],
[
<code key="code" className="text-red-400">429</code>,
<InlineCode key="code" color="error">429</InlineCode>,
'Rate Limit',
'Too many requests. Check rate limit headers for retry timing',
],
[
<code key="code" className="text-red-400">500</code>,
<InlineCode key="code" color="error">500</InlineCode>,
'Server Error',
'Internal server error. Contact support if persists',
],
@ -205,7 +211,9 @@ export default function TextToImageAPIPage() {
{/* Interactive Widget */}
<section id="interactive" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-4">Try It Live</h2>
<SectionHeader level={2} id="interactive" className="mb-4">
Try It Live
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-6">
Test the API directly from this page. Enter your API key and customize the parameters below.
</p>
@ -220,33 +228,24 @@ export default function TextToImageAPIPage() {
{/* Next Steps */}
<section id="next-steps" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-6">Next Steps</h2>
<SectionHeader level={2} id="next-steps" className="mb-6">
Next Steps
</SectionHeader>
<div className="grid md:grid-cols-2 gap-4">
<a
<LinkCardGrid columns={2}>
<LinkCard
href="/docs/api/upload"
className="p-5 bg-gradient-to-br from-purple-500/10 to-transparent border border-slate-700/50 rounded-xl hover:border-purple-500/40 transition-colors group"
>
<h3 className="text-lg font-semibold text-white mb-2 group-hover:text-purple-400 transition-colors">
Upload API
</h3>
<p className="text-sm text-gray-400">
Learn how to upload reference images for image-to-image generation.
</p>
</a>
<a
title="Upload API"
description="Learn how to upload reference images for image-to-image generation."
accent="primary"
/>
<LinkCard
href="/docs/guides/error-handling"
className="p-5 bg-gradient-to-br from-cyan-500/10 to-transparent border border-slate-700/50 rounded-xl hover:border-cyan-500/40 transition-colors group"
>
<h3 className="text-lg font-semibold text-white mb-2 group-hover:text-cyan-400 transition-colors">
Error Handling
</h3>
<p className="text-sm text-gray-400">
Best practices for handling errors and retries in production.
</p>
</a>
</div>
title="Error Handling"
description="Best practices for handling errors and retries in production."
accent="secondary"
/>
</LinkCardGrid>
</section>
</DocsLayout>
</>

109
apps/landing/src/app/docs/guides/authentication/page.tsx
View File

@ -19,6 +19,13 @@ import { TipBox } from '@/components/docs/shared/TipBox';
import { Table } from '@/components/docs/shared/Table';
import { Breadcrumb } from '@/components/docs/shared/Breadcrumb';
import { CodeBlock } from '@/components/docs/shared/CodeBlock';
import {
Hero,
SectionHeader,
InlineCode,
LinkCard,
LinkCardGrid,
} from '@/components/docs/blocks';
const tocItems = [
{ id: 'overview', text: 'Overview', level: 2 },
@ -61,26 +68,25 @@ export default function AuthenticationGuidePage() {
/>
{/* Hero Section */}
<div className="mb-12">
<h1 className="text-4xl md:text-5xl font-bold text-white mb-4">Authentication</h1>
<p className="text-xl text-gray-400 leading-relaxed">
Learn how to authenticate with the Banatie API using API keys, manage rate limits, and
implement security best practices.
</p>
</div>
<Hero
title="Authentication"
subtitle="Learn how to authenticate with the Banatie API using API keys, manage rate limits, and implement security best practices."
/>
{/* Overview */}
<section id="overview" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-4">Overview</h2>
<SectionHeader level={2} id="overview" className="mb-4">
Overview
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-6">
Banatie uses API keys to authenticate requests. All API endpoints require authentication
via the <code className="px-1.5 py-0.5 bg-slate-800 rounded text-purple-400">X-API-Key</code> header.
via the <InlineCode>X-API-Key</InlineCode> header.
API keys are tied to organizations and projects, providing fine-grained access control.
</p>
<TipBox variant="compact" type="info">
<strong>Quick Start:</strong> New to API authentication? Check out our{' '}
<a href="/docs/final" className="text-purple-400 hover:underline">
<a href="/docs" className="text-purple-400 hover:underline">
Getting Started guide
</a>{' '}
for a step-by-step walkthrough.
@ -89,10 +95,14 @@ export default function AuthenticationGuidePage() {
{/* API Keys */}
<section id="api-keys" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-6">API Keys</h2>
<SectionHeader level={2} id="api-keys" className="mb-6">
API Keys
</SectionHeader>
<div id="key-types" className="mb-8">
<h3 className="text-xl font-semibold text-white mb-4">Key Types</h3>
<SectionHeader level={3} id="key-types" className="mb-4">
Key Types
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-6">
Banatie supports two types of API keys, each with different permissions and use cases:
</p>
@ -101,13 +111,13 @@ export default function AuthenticationGuidePage() {
headers={['Key Type', 'Permissions', 'Expiration', 'Use Case']}
rows={[
[
<code key="type" className="text-purple-400">Master Key</code>,
<InlineCode key="type">Master Key</InlineCode>,
'Full admin access, can create/revoke keys',
<span key="exp" className="text-green-400">Never expires</span>,
'Server-side admin operations, key management',
],
[
<code key="type" className="text-cyan-400">Project Key</code>,
<InlineCode key="type" color="success">Project Key</InlineCode>,
'Image generation only',
<span key="exp" className="text-amber-400">90 days</span>,
'Application integration, API requests',
@ -126,7 +136,9 @@ export default function AuthenticationGuidePage() {
</div>
<div id="creating-keys" className="mb-8">
<h3 className="text-xl font-semibold text-white mb-4">Creating Keys</h3>
<SectionHeader level={3} id="creating-keys" className="mb-4">
Creating Keys
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-4">
For first-time setup, use the bootstrap endpoint to create your initial master key:
</p>
@ -181,9 +193,11 @@ curl -X POST https://api.banatie.com/api/admin/keys \\
{/* Using API Keys */}
<section id="using-keys" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-4">Using API Keys</h2>
<SectionHeader level={2} id="using-keys" className="mb-4">
Using API Keys
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-4">
Include your API key in the <code className="px-1.5 py-0.5 bg-slate-800 rounded text-purple-400">X-API-Key</code> header
Include your API key in the <InlineCode>X-API-Key</InlineCode> header
with every request:
</p>
@ -204,14 +218,16 @@ curl -X POST https://api.banatie.com/api/text-to-image \\
<TipBox variant="compact" type="info">
<strong>Environment Variables:</strong> Store API keys in environment variables, not
hardcoded in your application. Example:{' '}
<code className="px-1.5 py-0.5 bg-slate-800 rounded text-purple-400">BANATIE_API_KEY</code>
<InlineCode>BANATIE_API_KEY</InlineCode>
</TipBox>
</div>
</section>
{/* Rate Limits */}
<section id="rate-limits" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-6">Rate Limits</h2>
<SectionHeader level={2} id="rate-limits" className="mb-6">
Rate Limits
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-6">
API keys are subject to rate limits to ensure fair usage and system stability. Limits
vary by key type and plan tier:
@ -221,19 +237,19 @@ curl -X POST https://api.banatie.com/api/text-to-image \\
headers={['Key Type', 'Rate Limit', 'Reset Window', 'Upgrade Available']}
rows={[
[
<code key="type" className="text-purple-400">Master Key</code>,
<InlineCode key="type">Master Key</InlineCode>,
<span key="limit" className="text-green-400">Unlimited</span>,
'N/A',
'N/A',
],
[
<code key="type" className="text-cyan-400">Project Key (Free)</code>,
<InlineCode key="type" color="success">Project Key (Free)</InlineCode>,
<span key="limit" className="text-amber-400">100 requests/hour</span>,
'1 hour rolling',
<a key="upgrade" href="/pricing" className="text-purple-400 hover:underline">Yes</a>,
],
[
<code key="type" className="text-cyan-400">Project Key (Pro)</code>,
<InlineCode key="type" color="success">Project Key (Pro)</InlineCode>,
<span key="limit" className="text-green-400">1,000 requests/hour</span>,
'1 hour rolling',
<a key="upgrade" href="/pricing" className="text-purple-400 hover:underline">Yes</a>,
@ -243,7 +259,7 @@ curl -X POST https://api.banatie.com/api/text-to-image \\
<div className="mt-6">
<p className="text-gray-300 leading-relaxed mb-4">
When you exceed rate limits, the API returns a <code className="px-1.5 py-0.5 bg-slate-800 rounded text-red-400">429 Too Many Requests</code> status.
When you exceed rate limits, the API returns a <InlineCode color="error">429 Too Many Requests</InlineCode> status.
Check the response headers for retry timing:
</p>
@ -266,7 +282,9 @@ X-RateLimit-Reset: 1704153600
{/* Security Best Practices */}
<section id="security" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-6">Security Best Practices</h2>
<SectionHeader level={2} id="security" className="mb-6">
Security Best Practices
</SectionHeader>
<TipBox variant="prominent" type="warning">
<strong className="text-amber-300">Critical Security Guidelines:</strong>
@ -302,33 +320,24 @@ curl -X DELETE https://api.banatie.com/api/admin/keys/OLD_KEY_ID \\
{/* Next Steps */}
<section id="next-steps" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-6">Next Steps</h2>
<SectionHeader level={2} id="next-steps" className="mb-6">
Next Steps
</SectionHeader>
<div className="grid md:grid-cols-2 gap-4">
<a
href="/docs/final/api/text-to-image"
className="p-5 bg-gradient-to-br from-purple-500/10 to-transparent border border-slate-700/50 rounded-xl hover:border-purple-500/40 transition-colors group"
>
<h3 className="text-lg font-semibold text-white mb-2 group-hover:text-purple-400 transition-colors">
Start Generating Images
</h3>
<p className="text-sm text-gray-400">
Explore the Text to Image API and start building your integration.
</p>
</a>
<a
href="/docs/final/guides/error-handling"
className="p-5 bg-gradient-to-br from-cyan-500/10 to-transparent border border-slate-700/50 rounded-xl hover:border-cyan-500/40 transition-colors group"
>
<h3 className="text-lg font-semibold text-white mb-2 group-hover:text-cyan-400 transition-colors">
Error Handling Guide
</h3>
<p className="text-sm text-gray-400">
Learn how to handle authentication errors and implement retry logic.
</p>
</a>
</div>
<LinkCardGrid columns={2}>
<LinkCard
href="/docs/api/text-to-image"
title="Start Generating Images"
description="Explore the Text to Image API and start building your integration."
accent="primary"
/>
<LinkCard
href="/docs/guides/error-handling"
title="Error Handling Guide"
description="Learn how to handle authentication errors and implement retry logic."
accent="secondary"
/>
</LinkCardGrid>
</section>
</DocsLayout>
</>

104
apps/landing/src/app/docs/page.tsx
View File

@ -3,13 +3,8 @@
/**
* Getting Started Page - Production Documentation
*
* Main entry point for documentation
* Features:
* - SubsectionNav at top
* - Both TipBox styles (compact + prominent)
* - Enhanced tables
* - Simplified Next Steps (2 cards only)
* - Clean, accessible design
* Refactored to use block components from @/components/docs/blocks
* Demonstrates composition of reusable semantic components
*/
import { DocsLayout } from '@/components/docs/layout/DocsLayout';
@ -19,6 +14,13 @@ import { SubsectionNav } from '@/components/shared/SubsectionNav';
import { TipBox } from '@/components/docs/shared/TipBox';
import { CodeBlock } from '@/components/docs/shared/CodeBlock';
import { Breadcrumb } from '@/components/docs/shared/Breadcrumb';
import {
Hero,
SectionHeader,
ResponseBlock,
LinkCard,
LinkCardGrid,
} from '@/components/docs/blocks';
const tocItems = [
{ id: 'introduction', text: 'Introduction', level: 2 },
@ -53,17 +55,16 @@ export default function GettingStartedPage() {
<Breadcrumb items={[{ label: 'Documentation', href: '/docs' }, { label: 'Getting Started' }]} />
{/* Hero Section */}
<div className="mb-12">
<h1 className="text-4xl md:text-5xl font-bold text-white mb-4">Getting Started</h1>
<p className="text-xl text-gray-400 leading-relaxed">
Welcome to the Banatie API documentation. Learn how to integrate AI-powered image
generation into your applications in minutes.
</p>
</div>
<Hero
title="Getting Started"
subtitle="Welcome to the Banatie API documentation. Learn how to integrate AI-powered image generation into your applications in minutes."
/>
{/* Introduction */}
<section id="introduction" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-4">Introduction</h2>
<SectionHeader level={2} id="introduction">
Introduction
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-4">
Banatie is a developer-first API for AI-powered image generation. Built on Google Gemini
2.5 Flash and Imagen 4.0, it transforms text prompts and reference images into
@ -86,10 +87,14 @@ export default function GettingStartedPage() {
{/* Quick Start */}
<section id="quick-start" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-6">Quick Start</h2>
<SectionHeader level={2} id="quick-start" className="mb-6">
Quick Start
</SectionHeader>
<div id="installation" className="mb-8">
<h3 className="text-xl font-semibold text-white mb-3">Installation</h3>
<SectionHeader level={3} id="installation">
Installation
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-4">
Banatie is a REST API, so you do not need to install any libraries. However, we provide
SDKs for popular languages to make integration easier.
@ -110,7 +115,9 @@ go get github.com/banatie/sdk-go`}
</div>
<div id="authentication" className="mb-8">
<h3 className="text-xl font-semibold text-white mb-3">Authentication</h3>
<SectionHeader level={3} id="authentication">
Authentication
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-4">
All API requests require an API key. You can create an API key from your dashboard or
using the bootstrap endpoint for initial setup.
@ -139,7 +146,9 @@ export BANATIE_API_KEY="bnt_your_key_here"`}
{/* First Request */}
<section id="first-request" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-4">Your First Request</h2>
<SectionHeader level={2} id="first-request">
Your First Request
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-6">
Let's generate your first image! This example uses curl, but you can use any HTTP client
or our SDKs.
@ -161,14 +170,11 @@ export BANATIE_API_KEY="bnt_your_key_here"`}
<div className="mt-6">
<p className="text-sm font-semibold text-gray-300 mb-3">Expected Response:</p>
<div className="relative p-4 bg-green-500/5 border border-green-500/30 rounded-xl shadow-lg shadow-green-500/10">
<div className="absolute top-3 right-3">
<span className="px-2 py-1 text-xs bg-green-500/20 text-green-400 rounded-full">
✓ 200 Success
</span>
</div>
<pre className="text-xs text-gray-300 overflow-x-auto mt-6">
<code>{`{
<ResponseBlock
status="success"
statusCode={200}
statusLabel="✓ 200 Success"
content={`{
"success": true,
"data": {
"url": "https://cdn.banatie.com/org/project/generated/2025-01/mountain_sunset.png",
@ -179,44 +185,34 @@ export BANATIE_API_KEY="bnt_your_key_here"`}
"enhancedPrompt": "A breathtaking mountain landscape..."
}
}
}`}</code>
</pre>
</div>
}`}
/>
</div>
</section>
{/* Next Steps - Simplified to 2 Cards */}
<section id="next-steps" className="mb-12">
<h2 className="text-3xl font-bold text-white mb-6">Next Steps</h2>
<SectionHeader level={2} id="next-steps" className="mb-6">
Next Steps
</SectionHeader>
<p className="text-gray-300 leading-relaxed mb-6">
Now that you have generated your first image, explore these resources to build more advanced integrations:
</p>
<div className="grid md:grid-cols-2 gap-4">
<a
<LinkCardGrid columns={2}>
<LinkCard
href="/docs/api/text-to-image"
className="p-5 bg-gradient-to-br from-purple-500/10 to-transparent border border-slate-700/50 rounded-xl hover:border-purple-500/40 transition-colors group"
>
<h3 className="text-lg font-semibold text-white mb-2 group-hover:text-purple-400 transition-colors">
API Reference
</h3>
<p className="text-sm text-gray-400">
Explore all available endpoints, parameters, and response formats.
</p>
</a>
<a
title="API Reference"
description="Explore all available endpoints, parameters, and response formats."
accent="primary"
/>
<LinkCard
href="/docs/guides/authentication"
className="p-5 bg-gradient-to-br from-cyan-500/10 to-transparent border border-slate-700/50 rounded-xl hover:border-cyan-500/40 transition-colors group"
>
<h3 className="text-lg font-semibold text-white mb-2 group-hover:text-cyan-400 transition-colors">
Authentication Guide
</h3>
<p className="text-sm text-gray-400">
Learn about API keys, rate limits, and security best practices.
</p>
</a>
</div>
title="Authentication Guide"
description="Learn about API keys, rate limits, and security best practices."
accent="secondary"
/>
</LinkCardGrid>
</section>
</DocsLayout>
</>

202
apps/landing/src/components/docs/blocks/EndpointCard.tsx Normal file
View File

@ -0,0 +1,202 @@
'use client';
/**
* EndpointCard Component
*
* A structured display block for API endpoint information including HTTP method,
* path, and base URL. Creates consistent, scannable API reference documentation.
*
* ## Design Principles
*
* 1. **Information Grouping**: Related endpoint data in one visual container
* - Method badge + endpoint path on same line for scannability
* - Base URL separated below for clarity without clutter
* - Container styling creates clear boundaries
*
* 2. **Visual Hierarchy**: Emphasis guides attention naturally
* - HTTP method badge draws eye first (color + position)
* - Endpoint path is prominent (white text, slightly larger)
* - Base URL is secondary (smaller, muted gray)
*
* 3. **Technical Precision**: Monospace fonts for code accuracy
* - Endpoint path uses code styling
* - Prevents ambiguity in technical content
* - Familiar to developers
*
* ## Layout Strategy
*
* Horizontal Flow:
* ```
* [METHOD BADGE] /api/endpoint-path
* Base URL: https://api.example.com
* ```
*
* This layout:
* - Puts most important info (method + path) on top line
* - Creates natural left-to-right reading flow
* - Groups related information visually
* - Works well at various screen sizes
*
* ## Container Styling
*
* Background & Border:
* - bg-slate-900/50: Semi-transparent dark background
* - Separates from page background
* - Maintains dark theme consistency
* - Subtle enough not to dominate
*
* - border-slate-700: Defined edges
* - Creates clear container boundaries
* - Adds structure without heaviness
* - Professional, technical appearance
*
* - rounded-xl: Soft corners (12px radius)
* - Modern, friendly appearance
* - Matches other card elements
* - Balances technical precision with approachability
*
* Padding:
* - p-4 (16px): Comfortable breathing room
* - Prevents cramped appearance
* - Makes content easy to read
* - Balances whitespace and content
*
* ## Typography System
*
* Endpoint Path:
* - text-sm: Slightly smaller than body but clearly readable
* - text-white: Maximum contrast for primary content
* - font-mono implicitly via <code>: Technical accuracy
*
* Base URL:
* - text-xs: Clearly secondary information
* - text-gray-400: Muted to not compete with endpoint
* - Includes "Base URL:" label for context
*
* ## Spacing & Layout
*
* Flex Layout Benefits:
* - items-center: Vertically centers badge with text
* - gap-3 (12px): Comfortable space between badge and path
* - mb-2 (8px): Separates primary info from base URL
*
* ## Usage Examples
*
* ```tsx
* // Standard REST endpoint
* <EndpointCard
* method="POST"
* endpoint="/api/text-to-image"
* baseUrl="https://api.banatie.com"
* />
*
* // Different HTTP methods
* <EndpointCard
* method="GET"
* endpoint="/api/images"
* />
*
* <EndpointCard
* method="DELETE"
* endpoint="/api/admin/keys/:keyId"
* />
*
* // Custom base URL
* <EndpointCard
* method="PUT"
* endpoint="/api/projects/:id"
* baseUrl="https://api.custom-domain.com"
* />
* ```
*
* ## Content Guidelines
*
* HTTP Method:
* - Always uppercase (GET, POST, PUT, DELETE, PATCH)
* - Choose semantically correct method
* - Follows REST conventions
*
* Endpoint Path:
* - Start with forward slash (/)
* - Use lowercase with hyphens (kebab-case)
* - Include path parameters with colon prefix (:id, :keyId)
* - Be specific and descriptive
* - Example: `/api/projects/:projectId/keys`
*
* Base URL:
* - Include protocol (https://)
* - Use production URL as default
* - No trailing slash
* - Example: `https://api.banatie.com`
*
* ## Accessibility
*
* - Semantic HTML structure
* - Proper contrast ratios for all text
* - MethodBadge includes aria-label
* - Logical reading order (method → path → base)
* - Keyboard accessible (no interactive elements, but focusable context)
*
* ## Visual Language
*
* The EndpointCard establishes:
* - Professional, technical aesthetic
* - Consistent API documentation pattern
* - Clear, unambiguous endpoint identification
* - Easy copy-paste of endpoint information
* - Quick visual scanning in multi-endpoint docs
*
* @component
* @example
* <EndpointCard
* method="POST"
* endpoint="/api/text-to-image"
* baseUrl="https://api.banatie.com"
* />
*/
import { MethodBadge, HttpMethod } from './MethodBadge';
/**
* Props for the EndpointCard component
*/
export interface EndpointCardProps {
/** HTTP method for the endpoint */
method: HttpMethod;
/** API endpoint path (e.g., "/api/users") */
endpoint: string;
/** Base URL for the API (default: "https://api.banatie.com") */
baseUrl?: string;
/** Optional CSS class name for additional styling */
className?: string;
}
export const EndpointCard = ({
method,
endpoint,
baseUrl = 'https://api.banatie.com',
className = '',
}: EndpointCardProps) => {
return (
<div
className={`
p-4
bg-slate-900/50
border border-slate-700
rounded-xl
${className}
`}
>
{/* Method + Endpoint Row */}
<div className="flex items-center gap-3 mb-2">
<MethodBadge method={method} />
<code className="text-sm text-white">{endpoint}</code>
</div>
{/* Base URL */}
<p className="text-xs text-gray-400">
Base URL: <code className="text-purple-400">{baseUrl}</code>
</p>
</div>
);
};

185
apps/landing/src/components/docs/blocks/Hero.tsx Normal file
View File

@ -0,0 +1,185 @@
'use client';
/**
* Hero Component
*
* The primary heading section at the top of documentation pages.
* Establishes visual hierarchy and sets expectations for page content.
*
* ## Design Principles
*
* 1. **Information Hierarchy**: Clear progression from title to description
* - Large, bold title commands attention immediately
* - Subtitle provides context without competing with title
* - Consistent spacing creates rhythm and flow
*
* 2. **Typography Scale**: Responsive sizing for all devices
* - Mobile-first approach with thoughtful breakpoints
* - Maintains readability across screen sizes
* - Proper line-height for comfortable reading
*
* 3. **Visual Weight**: Balanced presence without overwhelming
* - White title for maximum contrast and impact
* - Gray subtitle for supporting, not competing
* - Generous margins create breathing room
*
* ## Size Variants
*
* @param {'default'} default - Standard documentation pages
* - Title: text-4xl (36px) → md:text-5xl (48px)
* - Use cases: API references, guides, tutorials
* - Psychology: Professional, focused, informative
* - Spacing: mb-12 (48px) after hero
*
* @param {'large'} large - Major landing pages, section introductions
* - Title: text-5xl (48px) → md:text-6xl (60px)
* - Use cases: Documentation home, major category pages
* - Psychology: Welcoming, important, primary entry point
* - Spacing: mb-16 (64px) after hero
*
* ## Typographic Hierarchy
*
* Title Characteristics:
* - **Weight**: font-bold (700) - Commands attention
* - **Color**: text-white - Maximum contrast, immediately readable
* - **Spacing**: mb-4 (16px) - Connects title to subtitle
*
* Subtitle Characteristics:
* - **Size**: text-xl (20px) - Large enough to be comfortable, small enough to defer
* - **Weight**: Regular (400) - Contrast with bold title
* - **Color**: text-gray-400 - Supporting role, doesn't compete
* - **Line height**: leading-relaxed (1.625) - Comfortable multi-line reading
*
* ## Responsive Behavior
*
* Mobile (<768px):
* - Smaller text sizes to fit narrow screens
* - Maintains readability with appropriate line lengths
* - Single column layout
*
* Desktop (≥768px):
* - Larger text leverages available space
* - Enhanced visual impact
* - Better use of vertical rhythm
*
* ## Visual Language
*
* The hero serves multiple purposes in documentation:
* 1. **Orientation**: Tells users where they are
* 2. **Context**: Explains what this page covers
* 3. **Hierarchy**: Establishes importance through size
* 4. **Consistency**: Familiarpattern across all docs pages
*
* Color Psychology:
* - **White title**: Authority, clarity, primary information
* - **Gray subtitle**: Support, context, secondary information
* - Creates natural reading flow: bold → light, primary → secondary
*
* ## Accessibility
*
* - Uses semantic HTML (<h1> for title)
* - Proper heading hierarchy (h1 is first heading on page)
* - Sufficient color contrast (white on dark background)
* - Readable font sizes (minimum 20px for subtitle)
* - Appropriate line-height for comfortable reading
*
* ## Usage Examples
*
* ```tsx
* // Standard API reference page
* <Hero
* title="Text to Image"
* subtitle="Generate high-quality images from text prompts using AI-powered models."
* />
*
* // Documentation home page
* <Hero
* size="large"
* title="Welcome to Banatie API Documentation"
* subtitle="Learn how to integrate AI-powered image generation into your applications in minutes."
* />
*
* // Guide page
* <Hero
* title="Authentication"
* subtitle="Learn how to authenticate with the Banatie API using API keys, manage rate limits, and implement security best practices."
* />
* ```
*
* ## Content Guidelines
*
* Title:
* - Keep short and specific (1-5 words ideal)
* - Use sentence case (capitalize first word only)
* - Avoid punctuation unless necessary
* - Match page's primary purpose
*
* Subtitle:
* - One to two sentences maximum
* - Explain what user will learn or accomplish
* - Use active voice and present tense
* - End with period for complete thoughts
*
* @component
* @example
* <Hero
* title="Getting Started"
* subtitle="Welcome to the Banatie API documentation."
* size="default"
* />
*/
import { ReactNode } from 'react';
/**
* Size variant determining the visual scale of the hero
*/
export type HeroSize = 'default' | 'large';
/**
* Props for the Hero component
*/
export interface HeroProps {
/** The main page title (renders as h1) */
title: string;
/** Supporting description or context */
subtitle: string | ReactNode;
/** Size variant (default: 'default') */
size?: HeroSize;
/** Optional CSS class name for additional styling */
className?: string;
}
/**
* Title size system mapping size variant to responsive text classes
*/
const titleSizes: Record<HeroSize, string> = {
default: 'text-4xl md:text-5xl',
large: 'text-5xl md:text-6xl',
};
/**
* Spacing system for bottom margin
*/
const spacingSizes: Record<HeroSize, string> = {
default: 'mb-12',
large: 'mb-16',
};
export const Hero = ({
title,
subtitle,
size = 'default',
className = '',
}: HeroProps) => {
return (
<div className={`${spacingSizes[size]} ${className}`}>
<h1 className={`${titleSizes[size]} font-bold text-white mb-4`}>
{title}
</h1>
<p className="text-xl text-gray-400 leading-relaxed">
{subtitle}
</p>
</div>
);
};

156
apps/landing/src/components/docs/blocks/InlineCode.tsx Normal file
View File

@ -0,0 +1,156 @@
'use client';
/**
* InlineCode Component
*
* A consistent inline code element for technical content within documentation text.
* Provides semantic color variants to emphasize context and meaning.
*
* ## Design Principles
*
* 1. **Readability First**: High contrast with surrounding text
* - Dark background distinguishes code from prose
* - Slightly larger padding creates breathing room
* - Rounded corners soften appearance for inline usage
*
* 2. **Semantic Coloring**: Color conveys meaning beyond monospace
* - Different contexts require different visual emphasis
* - Colors match broader design system for consistency
* - Never rely on color alone (always has monospace + background)
*
* 3. **Typography**: Monospace font signals technical content
* - Built-in font-mono class ensures code appearance
* - Small size (text-sm) fits inline with body text
* - Maintains readability without disrupting flow
*
* ## Color Semantic Values
*
* @param {'primary'} primary - Default technical content, variable names, general code
* - Visual: Purple accent (matches brand primary)
* - Psychology: Neutral technical content, primary focus
* - Use cases: `apiKey`, `userId`, general inline code snippets
* - When to use: Default choice for any code reference
*
* @param {'success'} success - Positive examples, correct values, successful states
* - Visual: Green accent
* - Psychology: Correct, recommended, successful outcome
* - Use cases: `status: 200`, `"success": true`, correct API responses
* - When to use: Showing what TO do, expected good outcomes
*
* @param {'error'} error - Error values, incorrect usage, warnings
* - Visual: Red accent
* - Psychology: Wrong, dangerous, avoid
* - Use cases: `status: 500`, error codes, anti-patterns
* - When to use: Showing what NOT to do, error states
*
* @param {'neutral'} neutral - Informational, documentation, placeholders
* - Visual: Slate/Gray (matches text color scheme)
* - Psychology: Reference, documentation, less emphasis
* - Use cases: HTTP headers like `X-API-Key`, endpoints, technical terms
* - When to use: Supporting information, less critical code references
*
* ## Visual Language
*
* Background Strategy:
* - Dark bg (slate-800) creates clear separation from surrounding text
* - Works on both light and dark documentation themes
* - Sufficient contrast meets WCAG AA standards
*
* Padding Strategy:
* - Horizontal: px-1.5 (6px) - enough space but not disruptive
* - Vertical: py-0.5 (2px) - maintains inline text flow
* - Border radius: rounded (4px) - soft enough for inline, defined enough for blocks
*
* Font Strategy:
* - text-sm: Slightly smaller than body text but still readable
* - font-mono: Clear distinction from prose, signals code
* - font-normal: Not bold, integrates naturally with surrounding text
*
* ## Usage Examples
*
* ```tsx
* // Default technical content
* Set your <InlineCode>API_KEY</InlineCode> environment variable.
*
* // With semantic colors
* The response includes <InlineCode color="success">status: 200</InlineCode>.
* Avoid using <InlineCode color="error">hardcoded credentials</InlineCode>.
* Include the <InlineCode color="neutral">X-API-Key</InlineCode> header.
*
* // Parameter documentation
* The <InlineCode>autoEnhance</InlineCode> parameter defaults to false.
*
* // Error messages
* If you receive <InlineCode color="error">401 Unauthorized</InlineCode>, check your API key.
* ```
*
* ## Composition Guidelines
*
* DO:
* - Use for short code snippets (1-4 words)
* - Use for technical terms, variable names, values
* - Use semantic colors to reinforce meaning
* - Place naturally within sentences
*
* DON'T:
* - Use for multi-line code (use CodeBlock instead)
* - Use for long strings (creates readability issues)
* - Overuse color variants (primary is default for a reason)
* - Use as a design element (it's for code content only)
*
* @component
* @example
* <InlineCode color="primary">apiKey</InlineCode>
*/
import { ReactNode } from 'react';
/**
* Semantic color variants for inline code
*/
export type InlineCodeColor = 'primary' | 'success' | 'error' | 'neutral';
/**
* Props for the InlineCode component
*/
export interface InlineCodeProps {
/** The code content to display */
children: ReactNode;
/** Semantic color variant (default: 'primary') */
color?: InlineCodeColor;
/** Optional CSS class name for additional styling */
className?: string;
}
/**
* Color system mapping semantic meanings to text colors
* All use same dark background for consistency
*/
const colorStyles: Record<InlineCodeColor, string> = {
primary: 'text-purple-400',
success: 'text-green-400',
error: 'text-red-400',
neutral: 'text-gray-400',
};
export const InlineCode = ({
children,
color = 'primary',
className = '',
}: InlineCodeProps) => {
return (
<code
className={`
inline-block
px-1.5 py-0.5
bg-slate-800
rounded
font-mono text-sm
${colorStyles[color]}
${className}
`}
>
{children}
</code>
);
};

281
apps/landing/src/components/docs/blocks/LinkCard.tsx Normal file
View File

@ -0,0 +1,281 @@
'use client';
/**
* LinkCard Component
*
* An interactive navigation card for guiding users to related documentation pages.
* Uses color accents and hover effects to create an engaging, explorable experience.
*
* ## Design Principles
*
* 1. **Visual Affordance**: Design signals interactivity
* - Gradient backgrounds hint at clickability
* - Hover states provide immediate feedback
* - Cursor changes to pointer on hover
* - Border transitions guide attention
*
* 2. **Semantic Color System**: Accent colors convey meaning
* - Primary (Purple): Main content, API references
* - Secondary (Cyan): Supporting content, guides
* - Success (Green): Getting started, tutorials
* - Warning (Amber): Important notices, deprecations
*
* 3. **Information Hierarchy**: Title dominates, description supports
* - Large, bold title draws attention
* - Smaller, muted description provides context
* - Title color changes on hover for feedback
* - Clean vertical rhythm (title → description)
*
* ## Accent Color Semantics
*
* @param {'primary'} primary - Main navigational elements, API documentation
* - Visual: Purple gradient and border
* - Psychology: Primary brand, core content, important
* - Use cases: "API Reference", "Core Concepts", main docs
* - Gradient: from-purple-500/10
* - Hover: border-purple-500/40, text-purple-400
*
* @param {'secondary'} secondary - Supporting content, guides, tutorials
* - Visual: Cyan gradient and border
* - Psychology: Complementary, helpful, educational
* - Use cases: "Guides", "Tutorials", "Best Practices"
* - Gradient: from-cyan-500/10
* - Hover: border-cyan-500/40, text-cyan-400
*
* @param {'success'} success - Getting started, quick wins, positive actions
* - Visual: Green gradient and border
* - Psychology: Achievement, beginning, growth
* - Use cases: "Getting Started", "Quick Start", "First Steps"
* - Gradient: from-green-500/10
* - Hover: border-green-500/40, text-green-400
*
* @param {'warning'} warning - Important notices, cautions, deprecations
* - Visual: Amber gradient and border
* - Psychology: Attention, caution, important
* - Use cases: "Migration Guide", "Breaking Changes", "Deprecations"
* - Gradient: from-amber-500/10
* - Hover: border-amber-500/40, text-amber-400
*
* ## Interactive States
*
* Default State:
* - Subtle gradient background (from-{color}-500/10)
* - Muted border (border-slate-700/50)
* - White title, gray description
* - Inviting but not demanding attention
*
* Hover State:
* - Border brightens to accent color (/40 opacity)
* - Title transitions to accent color
* - Smooth transition (transition-colors)
* - Clear feedback that element is clickable
*
* ## Layout Structure
*
* Padding System:
* - p-5 (20px): Generous padding for comfortable clicking
* - Creates substantial hit area for accessibility
* - Provides breathing room for content
*
* Border & Radius:
* - rounded-xl (12px): Modern, friendly appearance
* - border: Defined structure
* - Matches other card components in system
*
* ## Typography System
*
* Title (h3):
* - text-lg (18px): Large enough to be primary visual element
* - font-semibold (600): Strong but not overbearing
* - text-white: Maximum contrast and readability
* - mb-2 (8px): Separates from description
* - Transitions to accent color on hover
*
* Description (p):
* - text-sm (14px): Clearly secondary to title
* - text-gray-400: Muted, supporting role
* - Provides context without competing with title
*
* ## Accessibility Features
*
* - Semantic HTML (<a> tag for links)
* - Proper heading hierarchy (h3 for card titles)
* - Keyboard accessible (focusable link)
* - Sufficient color contrast in all states
* - Large click target (full card clickable)
* - Clear focus states (browser default + hover)
* - Descriptive link text (title + description)
*
* ## Usage Examples
*
* ```tsx
* // Primary content link
* <LinkCard
* href="/docs/api/text-to-image"
* title="API Reference"
* description="Explore all available endpoints, parameters, and response formats."
* accent="primary"
* />
*
* // Getting started
* <LinkCard
* href="/docs/quick-start"
* title="Quick Start"
* description="Get up and running with Banatie API in 5 minutes."
* accent="success"
* />
*
* // Supporting guide
* <LinkCard
* href="/docs/guides/authentication"
* title="Authentication Guide"
* description="Learn about API keys, rate limits, and security best practices."
* accent="secondary"
* />
*
* // Important notice
* <LinkCard
* href="/docs/migration"
* title="Migration Guide"
* description="Upgrade to v2 API with this step-by-step migration guide."
* accent="warning"
* />
* ```
*
* ## Content Guidelines
*
* Title:
* - 2-5 words ideal
* - Action-oriented or noun-based
* - Clear and specific
* - Sentence case
* - Examples: "API Reference", "Quick Start", "Authentication Guide"
*
* Description:
* - One sentence (10-20 words)
* - Explain what user will find/learn
* - Start with verb (Explore, Learn, Discover)
* - End with period
* - Be specific about content
*
* Accent Color:
* - Choose based on content type and importance
* - Maintain consistency across similar pages
* - Use primary for most API/core documentation
* - Reserve warning for truly important notices
*
* ## Visual Language
*
* The LinkCard system creates:
* - Intuitive navigation patterns
* - Clear content categorization through color
* - Engaging, explorable documentation
* - Professional yet friendly appearance
* - Consistent user experience across all docs
*
* @component
* @example
* <LinkCard
* href="/docs/api"
* title="API Reference"
* description="Complete API documentation"
* accent="primary"
* />
*/
/**
* Accent color determining the card's visual theme
*/
export type LinkCardAccent = 'primary' | 'secondary' | 'success' | 'warning';
/**
* Props for the LinkCard component
*/
export interface LinkCardProps {
/** Navigation URL */
href: string;
/** Card title (renders as h3) */
title: string;
/** Supporting description */
description: string;
/** Visual accent color */
accent: LinkCardAccent;
/** Optional icon or emoji to display */
icon?: string;
/** Optional CSS class name for additional styling */
className?: string;
}
/**
* Accent styles mapping color to gradient and hover colors
*/
const accentStyles: Record<LinkCardAccent, {
gradient: string;
hoverBorder: string;
hoverText: string;
}> = {
primary: {
gradient: 'from-purple-500/10',
hoverBorder: 'hover:border-purple-500/40',
hoverText: 'group-hover:text-purple-400',
},
secondary: {
gradient: 'from-cyan-500/10',
hoverBorder: 'hover:border-cyan-500/40',
hoverText: 'group-hover:text-cyan-400',
},
success: {
gradient: 'from-green-500/10',
hoverBorder: 'hover:border-green-500/40',
hoverText: 'group-hover:text-green-400',
},
warning: {
gradient: 'from-amber-500/10',
hoverBorder: 'hover:border-amber-500/40',
hoverText: 'group-hover:text-amber-400',
},
};
export const LinkCard = ({
href,
title,
description,
accent,
icon,
className = '',
}: LinkCardProps) => {
const styles = accentStyles[accent];
return (
<a
href={href}
className={`
block
p-5
bg-gradient-to-br ${styles.gradient} to-transparent
border border-slate-700/50
rounded-xl
${styles.hoverBorder}
transition-colors
group
${className}
`}
>
{icon && (
<div className="text-2xl mb-3">{icon}</div>
)}
<h3
className={`
text-lg font-semibold text-white mb-2
${styles.hoverText}
transition-colors
`}
>
{title}
</h3>
<p className="text-sm text-gray-400">
{description}
</p>
</a>
);
};

216
apps/landing/src/components/docs/blocks/LinkCardGrid.tsx Normal file
View File

@ -0,0 +1,216 @@
'use client';
/**
* LinkCardGrid Component
*
* A responsive grid layout container for organizing multiple LinkCard components.
* Provides consistent spacing and responsive behavior for navigation card collections.
*
* ## Design Principles
*
* 1. **Responsive Layout**: Adapts gracefully to all screen sizes
* - Mobile: Single column for comfortable tap targets
* - Tablet/Desktop: Multi-column for efficient space usage
* - Fluid transitions between breakpoints
*
* 2. **Grid System**: CSS Grid provides flexible, robust layout
* - Equal-width columns maintain balance
* - Auto-fit for flexible number of cards
* - Consistent gaps create visual rhythm
*
* 3. **Composition Pattern**: Wrapper abstracts layout complexity
* - Parent handles grid logic
* - Children (LinkCards) focus on content
* - Separation of concerns improves maintainability
*
* ## Column Configuration
*
* @param {2} columns=2 - Two-column layout (default)
* - Visual: Balanced, side-by-side comparison
* - Use cases: "Next Steps", paired content, binary choices
* - Responsive: md:grid-cols-2 (2 cols ≥768px, 1 col <768px)
* - Psychology: Compare and choose pattern
* - Example: "API Reference" vs "Authentication Guide"
*
* @param {3} columns=3 - Three-column layout
* - Visual: Information-rich, multiple options
* - Use cases: Resource hubs, category pages, multiple paths
* - Responsive: md:grid-cols-3 (3 cols ≥768px, 1 col <768px)
* - Psychology: Multiple choice, exploration
* - Example: "Getting Started", "API Docs", "Examples"
*
* @param {4} columns=4 - Four-column layout
* - Visual: Dense, comprehensive navigation
* - Use cases: Resource libraries, extensive catalogs
* - Responsive: md:grid-cols-2 lg:grid-cols-4 (2 cols tablet, 4 cols desktop)
* - Psychology: Broad exploration, many options
* - Example: Multiple API endpoints, extensive guides
*
* ## Responsive Breakpoints
*
* Mobile (<768px):
* - All grids collapse to single column
* - Prevents cramped cards on small screens
* - Optimizes for thumb-friendly tap targets
* - Maintains readability and usability
*
* Tablet (≥768px, <1024px):
* - 2-column: Displays as 2 columns
* - 3-column: Displays as 3 columns
* - 4-column: Displays as 2 columns (intermediate step)
* - Balances space usage and readability
*
* Desktop (≥1024px):
* - All grids display at full column count
* - Efficient use of available width
* - Supports quick visual scanning
*
* ## Spacing System
*
* Gap:
* - gap-4 (16px): Comfortable separation between cards
* - Creates visual grouping without crowding
* - Maintains clean grid appearance
* - Consistent with other spacing in design system
*
* Why gap-4?
* - Larger than text line-height (prevents cramping)
* - Small enough to show relationship between cards
* - Works well with card padding (p-5)
* - Scales gracefully at all screen sizes
*
* ## Grid Behavior
*
* CSS Grid Properties:
* - `grid`: Establishes grid container
* - `grid-cols-1`: Mobile baseline (single column)
* - `md:grid-cols-{n}`: Tablet/desktop columns
* - `gap-4`: Gutter between grid items
*
* ## Accessibility Considerations
*
* - Maintains logical reading order (top-to-bottom, left-to-right)
* - Grid doesn't interfere with keyboard navigation
* - Responsive design ensures usability on all devices
* - No JavaScript required (pure CSS grid)
* - Works with screen readers (semantic HTML preserved)
*
* ## Usage Examples
*
* ```tsx
* // Two-column "Next Steps" section
* <LinkCardGrid columns={2}>
* <LinkCard
* href="/docs/api"
* title="API Reference"
* description="Explore all endpoints"
* accent="primary"
* />
* <LinkCard
* href="/docs/guides"
* title="Guides"
* description="Learn best practices"
* accent="secondary"
* />
* </LinkCardGrid>
*
* // Three-column resource hub
* <LinkCardGrid columns={3}>
* <LinkCard href="..." title="Getting Started" accent="success" description="..." />
* <LinkCard href="..." title="API Docs" accent="primary" description="..." />
* <LinkCard href="..." title="Examples" accent="secondary" description="..." />
* </LinkCardGrid>
*
* // Four-column comprehensive navigation
* <LinkCardGrid columns={4}>
* <LinkCard href="..." title="Text to Image" accent="primary" description="..." />
* <LinkCard href="..." title="Upload" accent="primary" description="..." />
* <LinkCard href="..." title="Authentication" accent="secondary" description="..." />
* <LinkCard href="..." title="Rate Limits" accent="secondary" description="..." />
* </LinkCardGrid>
* ```
*
* ## Composition Guidelines
*
* DO:
* - Use consistent accent colors within a grid (e.g., all primary, or primary + secondary)
* - Keep card count balanced (even numbers work best for 2/4 columns)
* - Provide descriptive, parallel content in cards
* - Order cards by importance or logical flow
*
* DON'T:
* - Mix too many accent colors (creates visual chaos)
* - Use unbalanced card counts in 2-column (odd numbers leave gaps)
* - Nest grids inside grids (causes layout issues)
* - Put non-LinkCard components inside (breaks grid consistency)
*
* ## Visual Language
*
* The LinkCardGrid creates:
* - Organized, scannable navigation patterns
* - Professional documentation architecture
* - Clear visual hierarchy through layout
* - Responsive, mobile-friendly experience
* - Consistent spacing and alignment
*
* ## Performance
*
* - Pure CSS (no JavaScript overhead)
* - Minimal DOM elements (single wrapper div)
* - Hardware-accelerated grid layout
* - No re-renders or layout thrashing
*
* @component
* @example
* <LinkCardGrid columns={2}>
* {children}
* </LinkCardGrid>
*/
import { ReactNode } from 'react';
/**
* Column configuration for the grid
*/
export type GridColumns = 2 | 3 | 4;
/**
* Props for the LinkCardGrid component
*/
export interface LinkCardGridProps {
/** Number of columns at tablet/desktop breakpoints */
columns?: GridColumns;
/** LinkCard components to display in the grid */
children: ReactNode;
/** Optional CSS class name for additional styling */
className?: string;
}
/**
* Responsive grid class mappings for different column counts
*/
const columnStyles: Record<GridColumns, string> = {
2: 'md:grid-cols-2',
3: 'md:grid-cols-3',
4: 'md:grid-cols-2 lg:grid-cols-4', // 2 cols on tablet, 4 on desktop
};
export const LinkCardGrid = ({
columns = 2,
children,
className = '',
}: LinkCardGridProps) => {
return (
<div
className={`
grid
grid-cols-1
${columnStyles[columns]}
gap-4
${className}
`}
>
{children}
</div>
);
};

181
apps/landing/src/components/docs/blocks/MethodBadge.tsx Normal file
View File

@ -0,0 +1,181 @@
'use client';
/**
* MethodBadge Component
*
* A specialized badge for HTTP method display in API documentation.
* Uses industry-standard color conventions to communicate REST operation types.
*
* ## Design Principles
*
* 1. **REST Semantic Mapping**: Colors align with HTTP method semantics
* - Follows industry conventions (GitHub, Stripe, Swagger UI)
* - Immediate visual recognition for developers
* - Consistent with HTTP specification meanings
*
* 2. **Visual Distinction**: Each method has unique, memorable color
* - High contrast for readability against dark backgrounds
* - Distinct enough to differentiate at a glance
* - Professional appearance suitable for technical documentation
*
* 3. **Typography**: Bold, uppercase display reinforces technical nature
* - font-bold for emphasis and readability
* - Uppercase matches HTTP specification format
* - Monospace-friendly sizing
*
* ## HTTP Method Semantics
*
* @param {'GET'} GET - Read/Retrieve operations (Safe, Idempotent)
* - Visual: Cyan/Blue - represents data flow inward (reading)
* - Psychology: Information retrieval, safe operation
* - Use cases: Fetch resources, list endpoints, query data
* - HTTP: Safe method, no side effects, cacheable
*
* @param {'POST'} POST - Create operations (Not safe, Not idempotent)
* - Visual: Green - represents creation, addition, growth
* - Psychology: Positive action, new resource creation
* - Use cases: Create resource, submit form, trigger action
* - HTTP: Creates new resource, may have side effects
*
* @param {'PUT'} PUT - Update/Replace operations (Not safe, Idempotent)
* - Visual: Amber/Orange - represents modification, change
* - Psychology: Caution, transformation, state change
* - Use cases: Update entire resource, replace content
* - HTTP: Idempotent, full resource update
*
* @param {'PATCH'} PATCH - Partial Update operations (Not safe, Not idempotent)
* - Visual: Purple - represents refinement, partial change
* - Psychology: Precision, targeted modification
* - Use cases: Update specific fields, partial resource modification
* - HTTP: Partial update, may not be idempotent
*
* @param {'DELETE'} DELETE - Delete operations (Not safe, Idempotent)
* - Visual: Red - represents removal, destruction, danger
* - Psychology: Warning, irreversible action, stop
* - Use cases: Remove resource, deactivate, destroy data
* - HTTP: Idempotent, removes resource
*
* ## Size Variants
*
* @param {'sm'} sm - Small size for inline usage (px-2 py-0.5, text-xs)
* @param {'md'} md - Medium size for standard usage (px-3 py-1, text-xs) [default]
*
* ## Visual Language
*
* - **Rounded corners**: Modern, friendly appearance
* - **Semi-transparent backgrounds**: Integrates with dark theme
* - **Solid borders**: Adds definition and structure
* - **Bold text**: Ensures readability and emphasis
* - **Consistent sizing**: Aligns with other badges in the design system
*
* Color Opacity Strategy:
* - Background: 20% opacity for subtle presence
* - Border: 40% opacity for clear definition
* - Text: 100% (400 weight) for maximum readability
*
* ## Usage Examples
*
* ```tsx
* // API Endpoint Documentation
* <MethodBadge method="GET" /> /api/users
* <MethodBadge method="POST" /> /api/users
*
* // With size variants
* <MethodBadge method="DELETE" size="sm" />
* <MethodBadge method="PUT" size="md" />
*
* // In endpoint cards
* <div className="flex items-center gap-2">
* <MethodBadge method="POST" />
* <code>/api/text-to-image</code>
* </div>
* ```
*
* ## Industry Standards Reference
*
* This color scheme aligns with popular API documentation tools:
* - Swagger UI: Blue (GET), Green (POST), Orange (PUT), Red (DELETE)
* - Postman: Similar color conventions
* - GitHub API Docs: Consistent method color coding
*
* @component
* @example
* <MethodBadge method="POST" size="md" />
*/
import { ReactNode } from 'react';
/**
* HTTP method types following REST conventions
*/
export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
/**
* Size variant for the badge
*/
export type MethodBadgeSize = 'sm' | 'md';
/**
* Props for the MethodBadge component
*/
export interface MethodBadgeProps {
/** The HTTP method to display */
method: HttpMethod;
/** Size variant (default: 'md') */
size?: MethodBadgeSize;
/** Optional CSS class name for additional styling */
className?: string;
}
/**
* Color system mapping HTTP methods to semantic colors
* Follows industry standards for API documentation
*/
const methodStyles: Record<HttpMethod, string> = {
GET: 'bg-cyan-600/20 text-cyan-400 border-cyan-500/40',
POST: 'bg-green-600/20 text-green-400 border-green-500/40',
PUT: 'bg-amber-600/20 text-amber-400 border-amber-500/40',
PATCH: 'bg-purple-600/20 text-purple-400 border-purple-500/40',
DELETE: 'bg-red-600/20 text-red-400 border-red-500/40',
};
/**
* Size system mapping size variant to padding and font size
*/
const sizeStyles: Record<MethodBadgeSize, string> = {
sm: 'px-2 py-0.5 text-xs',
md: 'px-3 py-1 text-xs',
};
/**
* Accessibility labels describing the HTTP method's purpose
*/
const methodLabels: Record<HttpMethod, string> = {
GET: 'GET request - retrieve data',
POST: 'POST request - create resource',
PUT: 'PUT request - update resource',
PATCH: 'PATCH request - partial update',
DELETE: 'DELETE request - remove resource',
};
export const MethodBadge = ({
method,
size = 'md',
className = '',
}: MethodBadgeProps) => {
return (
<span
className={`
inline-flex items-center justify-center
rounded border font-bold
${methodStyles[method]}
${sizeStyles[size]}
${className}
`}
role="status"
aria-label={methodLabels[method]}
>
{method}
</span>
);
};

244
apps/landing/src/components/docs/blocks/ResponseBlock.tsx Normal file
View File

@ -0,0 +1,244 @@
'use client';
/**
* ResponseBlock Component
*
* A semantic display block for API response examples with status indicators.
* Visually differentiates success and error responses through color psychology.
*
* ## Design Principles
*
* 1. **Status Communication**: Color instantly conveys response type
* - Green = Success (2xx responses, positive outcomes)
* - Red = Error (4xx/5xx responses, failures)
* - Consistent with universal traffic light conventions
*
* 2. **Information Layering**: Progressive disclosure of details
* - Status badge in top-right for immediate recognition
* - Optional title provides context
* - Content area for actual response data
* - Layered styling adds depth without clutter
*
* 3. **Visual Feedback**: Subtle effects reinforce status
* - Background tint matches status color
* - Border emphasis adds structure
* - Soft shadow/glow creates depth
* - All at low opacity to avoid overwhelming
*
* ## Status Semantics
*
* @param {'success'} success - Successful API responses (2xx status codes)
* - Visual: Green color palette (green-500)
* - Psychology: Positive, correct, achieved
* - Use cases: 200 OK, 201 Created, 204 No Content
* - Styling: bg-green-500/5, border-green-500/30, shadow-green-500/10
* - Badge: "✓ 200 Success", "✓ 201 Created"
*
* @param {'error'} error - Error API responses (4xx/5xx status codes)
* - Visual: Red color palette (red-500)
* - Psychology: Warning, problem, attention needed
* - Use cases: 400 Bad Request, 401 Unauthorized, 500 Server Error
* - Styling: bg-red-500/5, border-red-500/30, shadow-red-500/10
* - Badge: "✗ 400 Error", "✗ 500 Error"
*
* ## Opacity Strategy
*
* Three-tier opacity system:
* - Background: /5 (5% opacity) - Subtle tint, doesn't obscure content
* - Border: /30 (30% opacity) - Clear definition, visible structure
* - Shadow: /10 (10% opacity) - Soft depth, enhances without distraction
*
* This creates:
* - Cohesive visual grouping
* - Clear status communication
* - Maintains content readability
* - Professional, polished appearance
*
* ## Layout Structure
*
* ```
* ┌─────────────────────────────────────┐
* │ [STATUS BADGE] ←──┤ Absolute positioned
* │ Optional Title │
* │ (if provided) │
* │ │
* │ <pre><code> │
* │ Response content │
* │ ... │
* │ </code></pre> │
* └─────────────────────────────────────┘
* ```
*
* Positioning Strategy:
* - Container: relative positioning context
* - Badge: absolute top-3 right-3 (float in top-right)
* - Content: mt-6 when badge present (clear space for badge)
* - Title: mb-3 if provided (separate from content)
*
* ## Typography & Content
*
* Title (optional):
* - text-sm: Small, not competing with main content
* - font-semibold: Subtle emphasis
* - text-gray-300: Readable but secondary
* - Purpose: Labels response type, adds context
*
* Response Content:
* - text-xs: Appropriate for code samples
* - text-gray-300: High contrast on dark background
* - font-mono (implicit in <code>): Code appearance
* - overflow-x-auto: Handles long lines gracefully
*
* ## Usage Examples
*
* ```tsx
* // Success response with title
* <ResponseBlock
* status="success"
* statusCode={200}
* title="Expected Response:"
* content={`{
* "success": true,
* "data": { ... }
* }`}
* />
*
* // Error response without title
* <ResponseBlock
* status="error"
* statusCode={401}
* content={`{
* "error": "Unauthorized",
* "message": "Invalid API key"
* }`}
* />
*
* // Custom status label
* <ResponseBlock
* status="success"
* statusCode={201}
* statusLabel="✓ 201 Created"
* content="{ ... }"
* />
* ```
*
* ## Content Guidelines
*
* Response Content:
* - Use actual JSON/text from your API
* - Format with proper indentation (2 or 4 spaces)
* - Include realistic data (not just placeholders)
* - Show relevant fields (omit excessive detail)
* - Keep under 20-30 lines for readability
*
* Status Labels:
* - Include status code (200, 400, etc.)
* - Add descriptive text (Success, Error, Created)
* - Use checkmark (✓) for success
* - Use X (✗) for errors
* - Keep concise (2-3 words max)
*
* ## Accessibility
*
* - Semantic HTML structure (<pre><code>)
* - Color is supplementary (text + symbols)
* - High contrast text colors
* - StatusBadge includes aria-label
* - Proper heading hierarchy if title used
* - Scrollable overflow for long content
*
* ## Visual Language
*
* The ResponseBlock creates:
* - Immediate status recognition through color
* - Professional code presentation
* - Clear example/documentation relationship
* - Consistent pattern across all API docs
* - Supports learn-by-example documentation style
*
* @component
* @example
* <ResponseBlock
* status="success"
* statusCode={200}
* title="Success Response"
* content={jsonString}
* />
*/
import { StatusBadge, StatusType } from './StatusBadge';
/**
* Props for the ResponseBlock component
*/
export interface ResponseBlockProps {
/** Status type determining color scheme */
status: Extract<StatusType, 'success' | 'error'>;
/** HTTP status code (e.g., 200, 400, 500) */
statusCode: number;
/** The response content to display (typically JSON) */
content: string;
/** Optional title above the response */
title?: string;
/** Optional custom status label (default: auto-generated from statusCode) */
statusLabel?: string;
/** Optional CSS class name for additional styling */
className?: string;
}
/**
* Status styles mapping status type to background, border, and shadow colors
*/
const statusStyles = {
success: 'bg-green-500/5 border-green-500/30 shadow-lg shadow-green-500/10',
error: 'bg-red-500/5 border-red-500/30 shadow-lg shadow-red-500/10',
};
/**
* Generate default status label from code and status
*/
const getDefaultStatusLabel = (code: number, status: 'success' | 'error'): string => {
const symbol = status === 'success' ? '✓' : '✗';
const text = status === 'success' ? 'Success' : 'Error';
return `${symbol} ${code} ${text}`;
};
export const ResponseBlock = ({
status,
statusCode,
content,
title,
statusLabel,
className = '',
}: ResponseBlockProps) => {
const label = statusLabel || getDefaultStatusLabel(statusCode, status);
return (
<div
className={`
relative
p-4
border rounded-xl
${statusStyles[status]}
${className}
`}
>
{/* Status Badge - Floating Top Right */}
<div className="absolute top-3 right-3">
<StatusBadge status={status} size="sm">
{label}
</StatusBadge>
</div>
{/* Optional Title */}
{title && (
<p className="text-sm font-semibold text-gray-300 mb-3">{title}</p>
)}
{/* Response Content */}
<pre className={`text-xs text-gray-300 overflow-x-auto ${title || statusLabel ? 'mt-6' : ''}`}>
<code>{content}</code>
</pre>
</div>
);
};

199
apps/landing/src/components/docs/blocks/SectionHeader.tsx Normal file
View File

@ -0,0 +1,199 @@
'use client';
/**
* SectionHeader Component
*
* Consistent heading elements for organizing documentation content into hierarchical sections.
* Provides visual rhythm and structure throughout documentation pages.
*
* ## Design Principles
*
* 1. **Visual Hierarchy**: Size and weight indicate content importance
* - Level 2 (h2): Major sections, primary content divisions
* - Level 3 (h3): Subsections, supporting details
* - Consistent styling creates predictable structure
*
* 2. **Semantic HTML**: Proper heading levels for accessibility
* - Uses correct HTML heading tags (h2, h3)
* - Supports screen readers and document outline
* - Enables Table of Contents generation
* - Critical for SEO and document structure
*
* 3. **Spacing System**: Establishes vertical rhythm
* - Top margin separates from previous content
* - Bottom margin creates breathing room before content
* - Consistent spacing improves scannability
*
* ## Heading Level Semantics
*
* @param {2} level2 - Major section headings (h2)
* - Visual: text-3xl (30px), font-bold, text-white
* - Spacing: mb-4 (16px) below, mb-6 (24px) for sections with mb-12
* - Psychology: Primary divisions, main topics
* - Use cases: "Overview", "Parameters", "Response", "Error Codes"
* - Hierarchy: Second level (after page h1/Hero)
* - SEO: Key topic signals for search engines
*
* @param {3} level3 - Subsection headings (h3)
* - Visual: text-xl (20px), font-semibold, text-white
* - Spacing: mb-3 (12px) below, mb-4 (16px) for subsections with mb-8
* - Psychology: Supporting topics, detailed breakdowns
* - Use cases: "Key Types", "Creating Keys", "Rate Limits"
* - Hierarchy: Third level (under h2 sections)
* - SEO: Supporting detail signals
*
* ## Typography Scale Reasoning
*
* Level 2 (text-3xl / 30px):
* - Large enough to clearly mark major sections
* - Smaller than Hero (36-48px) to maintain hierarchy
* - Bold weight adds emphasis and structure
* - White color ensures readability and prominence
*
* Level 3 (text-xl / 20px):
* - Noticeably smaller than h2, maintaining hierarchy
* - Semibold (600) instead of bold provides subtle distinction
* - Large enough to serve as clear subsection marker
* - Balances prominence with subordinate role
*
* ## Spacing Philosophy
*
* Bottom Margin Strategy:
* - h2: mb-4 or mb-6 depending on section context
* - mb-4 for tighter sections with nearby content
* - mb-6 for major sections introducing substantial content
* - h3: mb-3 or mb-4 depending on subsection context
* - Smaller margins reflect subordinate hierarchy
* - Still provides clear separation from content
*
* ## Anchor Link Support
*
* The `id` prop enables:
* - Direct linking to specific sections (#section-name)
* - Table of Contents navigation
* - Deep linking from external sources
* - Browser history for scrolled positions
*
* ID Naming Convention:
* - Use kebab-case (lowercase with hyphens)
* - Descriptive and unique per page
* - Example: "api-keys", "rate-limits", "error-handling"
*
* ## Accessibility Features
*
* - Semantic HTML heading levels (h2, h3)
* - Proper document outline structure
* - Sufficient color contrast (white on dark)
* - Clear visual distinction between levels
* - Screen reader friendly navigation
* - Keyboard accessible anchor links
*
* ## Usage Examples
*
* ```tsx
* // Major section heading (h2)
* <SectionHeader level={2} id="overview">
* Overview
* </SectionHeader>
*
* // Subsection heading (h3)
* <SectionHeader level={3} id="key-types">
* Key Types
* </SectionHeader>
*
* // Custom spacing with className
* <SectionHeader level={2} id="parameters" className="mb-6">
* Parameters
* </SectionHeader>
* ```
*
* ## Content Guidelines
*
* Level 2 Headings:
* - 1-3 words ideal (concise and scannable)
* - Sentence case (capitalize first word)
* - Action-oriented or descriptive nouns
* - Examples: "Quick Start", "Authentication", "Rate Limits"
*
* Level 3 Headings:
* - 1-4 words, slightly more descriptive
* - Sentence case
* - Specific subtopics or steps
* - Examples: "Creating Keys", "Using API Keys", "Security Best Practices"
*
* ## Visual Language
*
* The header system creates a visual rhythm that:
* - Guides the eye through content naturally
* - Breaks long pages into digestible chunks
* - Signals importance through size and weight
* - Maintains consistency across all documentation
* - Supports quick scanning and navigation
*
* @component
* @example
* <SectionHeader level={2} id="getting-started">
* Getting Started
* </SectionHeader>
*/
import { ReactNode } from 'react';
/**
* Heading level determining HTML tag and visual styling
*/
export type SectionHeaderLevel = 2 | 3;
/**
* Props for the SectionHeader component
*/
export interface SectionHeaderProps {
/** Heading level (h2 or h3) for semantic structure */
level: SectionHeaderLevel;
/** The heading text content */
children: ReactNode;
/** Optional ID for anchor linking and table of contents */
id?: string;
/** Optional CSS class name for additional styling (e.g., custom margins) */
className?: string;
}
/**
* Typography styles mapping heading level to text size and weight
*/
const levelStyles: Record<SectionHeaderLevel, string> = {
2: 'text-3xl font-bold',
3: 'text-xl font-semibold',
};
/**
* Default spacing system for bottom margins
*/
const defaultSpacing: Record<SectionHeaderLevel, string> = {
2: 'mb-4',
3: 'mb-3',
};
export const SectionHeader = ({
level,
children,
id,
className,
}: SectionHeaderProps) => {
const Tag = `h${level}` as 'h2' | 'h3';
const spacing = className?.includes('mb-') ? '' : defaultSpacing[level];
return (
<Tag
id={id}
className={`
${levelStyles[level]}
text-white
${spacing}
${className || ''}
`}
>
{children}
</Tag>
);
};

176
apps/landing/src/components/docs/blocks/StatusBadge.tsx Normal file
View File

@ -0,0 +1,176 @@
'use client';
/**
* StatusBadge Component
*
* A semantic status indicator that uses color psychology and consistent styling
* to communicate state, result, or severity across documentation.
*
* ## Design Principles
*
* 1. **Semantic Color System**: Colors convey meaning, not just decoration
* - Uses consistent color mapping across all documentation
* - Follows industry standards (green = success, red = error, etc.)
*
* 2. **Visual Hierarchy**: Small, unobtrusive elements that enhance readability
* - Pill-shaped design for friendly, modern appearance
* - Subtle backgrounds with semi-transparent colors
* - Border emphasis for definition without heaviness
*
* 3. **Accessibility**: Meets WCAG 2.1 AA standards
* - Sufficient color contrast ratios
* - Semantic HTML with aria-label
* - Text labels (never color-only communication)
*
* ## Semantic Status Values
*
* @param {'success'} success - Positive outcomes, completed actions, 2xx HTTP responses
* - Visual: Green color palette
* - Psychology: Achievement, correctness, go-ahead signal
* - Use cases: "200 Success", "Completed", "Active", "✓ Passed"
*
* @param {'info'} info - Neutral information, documentation, helpful tips
* - Visual: Blue/Cyan color palette
* - Psychology: Calm, trustworthy, educational
* - Use cases: "Beta", "New", "Info", "Note"
*
* @param {'warning'} warning - Caution, deprecation, rate limits, 4xx client errors
* - Visual: Amber/Orange color palette
* - Psychology: Attention needed, proceed with caution
* - Use cases: "429 Rate Limit", "Deprecated", "Warning", "Limited"
*
* @param {'error'} error - Failures, critical issues, 5xx server errors, security alerts
* - Visual: Red color palette
* - Psychology: Stop, danger, requires immediate attention
* - Use cases: "500 Error", "Failed", "Critical", "Blocked"
*
* @param {'neutral'} neutral - Default state, placeholder, unspecified
* - Visual: Slate/Gray color palette
* - Psychology: Neutral, balanced, inactive
* - Use cases: "Pending", "Unknown", "Draft", "Inactive"
*
* ## Size Variants
*
* @param {'sm'} sm - Small size for inline usage, tight spaces
* - Font: text-xs
* - Padding: px-2 py-0.5
* - Use: Inline with text, table cells, compact layouts
*
* @param {'md'} md - Medium size (default) for standard usage
* - Font: text-xs
* - Padding: px-3 py-1
* - Use: General purpose, code examples, section markers
*
* ## Visual Language
*
* The badge uses a rounded-full design (pill shape) which:
* - Creates visual consistency with other UI elements (buttons, tags)
* - Feels modern and friendly (vs. harsh rectangular badges)
* - Groups related information visually
* - Works well at small sizes without appearing cramped
*
* Color opacity levels (X/20 bg, X/40 border):
* - Background: 20% opacity for subtle presence
* - Border: 40% opacity for definition
* - Text: 100% for maximum readability
*
* ## Usage Examples
*
* ```tsx
* // HTTP Status Codes
* <StatusBadge status="success" size="sm">200 OK</StatusBadge>
* <StatusBadge status="error" size="sm">500 Error</StatusBadge>
*
* // API States
* <StatusBadge status="info">Beta</StatusBadge>
* <StatusBadge status="warning">Deprecated</StatusBadge>
*
* // System Status
* <StatusBadge status="success">✓ Active</StatusBadge>
* <StatusBadge status="neutral">Pending</StatusBadge>
* ```
*
* @component
* @example
* <StatusBadge status="success" size="md">200 Success</StatusBadge>
*/
import { ReactNode } from 'react';
/**
* Semantic status type representing the meaning/severity of the badge
*/
export type StatusType = 'success' | 'info' | 'warning' | 'error' | 'neutral';
/**
* Size variant for the badge
*/
export type StatusSize = 'sm' | 'md';
/**
* Props for the StatusBadge component
*/
export interface StatusBadgeProps {
/** The semantic status that determines color and meaning */
status: StatusType;
/** The content to display inside the badge */
children: ReactNode;
/** Size variant (default: 'md') */
size?: StatusSize;
/** Optional CSS class name for additional styling */
className?: string;
}
/**
* Color system mapping semantic status to Tailwind color utilities
* Follows the established design system color palette
*/
const statusStyles: Record<StatusType, string> = {
success: 'bg-green-500/20 text-green-400 border border-green-500/40',
info: 'bg-cyan-500/20 text-cyan-400 border border-cyan-500/40',
warning: 'bg-amber-500/20 text-amber-400 border border-amber-500/40',
error: 'bg-red-500/20 text-red-400 border border-red-500/40',
neutral: 'bg-slate-500/20 text-slate-400 border border-slate-500/40',
};
/**
* Size system mapping size variant to padding and font size
*/
const sizeStyles: Record<StatusSize, string> = {
sm: 'px-2 py-0.5 text-xs',
md: 'px-3 py-1 text-xs',
};
/**
* Human-readable labels for screen readers
*/
const statusLabels: Record<StatusType, string> = {
success: 'Success status',
info: 'Information status',
warning: 'Warning status',
error: 'Error status',
neutral: 'Neutral status',
};
export const StatusBadge = ({
status,
children,
size = 'md',
className = '',
}: StatusBadgeProps) => {
return (
<span
className={`
inline-flex items-center justify-center
rounded-full font-bold
${statusStyles[status]}
${sizeStyles[size]}
${className}
`}
role="status"
aria-label={statusLabels[status]}
>
{children}
</span>
);
};

176
apps/landing/src/components/docs/blocks/index.ts Normal file
View File

@ -0,0 +1,176 @@
/**
* Documentation Block Components
*
* A comprehensive library of reusable, semantic components for building
* consistent, professional API documentation.
*
* ## Design System Overview
*
* This collection establishes a visual language for documentation through:
* - **Semantic Color System**: Enum-based color values with clear meanings
* - **Consistent Typography**: Hierarchical text sizing and weights
* - **Responsive Layouts**: Mobile-first, adaptive components
* - **Accessibility First**: WCAG 2.1 AA compliance throughout
* - **Comprehensive Documentation**: Every component fully documented
*
* ## Component Categories
*
* ### Status & Indicators
* - **StatusBadge**: Semantic status indicators (success, info, warning, error, neutral)
* - **MethodBadge**: HTTP method badges (GET, POST, PUT, PATCH, DELETE)
*
* ### Typography & Content
* - **Hero**: Page-level headings with title and subtitle
* - **SectionHeader**: Hierarchical section headings (h2, h3)
* - **InlineCode**: Semantic inline code elements
*
* ### API Documentation
* - **EndpointCard**: Structured API endpoint display
* - **ResponseBlock**: API response examples with status visualization
*
* ### Navigation
* - **LinkCard**: Interactive navigation cards with accent colors
* - **LinkCardGrid**: Responsive grid layout for link cards
*
* ## Usage Philosophy
*
* These components follow key principles:
*
* 1. **Composition over Configuration**
* - Small, focused components combine to create pages
* - Each component does one thing well
* - Easy to understand and maintain
*
* 2. **Semantic Props**
* - Enum values over raw values (accent='primary' not color='#8b5cf6')
* - Meaning-based names (status='success' not color='green')
* - Self-documenting API
*
* 3. **Consistent Patterns**
* - Similar props across components (className, children)
* - Predictable behavior and styling
* - Easy to learn and use
*
* 4. **Accessibility Built-in**
* - Semantic HTML throughout
* - ARIA labels where appropriate
* - Keyboard navigation support
* - Sufficient color contrast
*
* ## Example: Building a Documentation Page
*
* ```tsx
* import {
* Hero,
* SectionHeader,
* InlineCode,
* EndpointCard,
* ResponseBlock,
* LinkCard,
* LinkCardGrid,
* } from '@/components/docs/blocks';
*
* export default function APIPage() {
* return (
* <>
* <Hero
* title="Text to Image API"
* subtitle="Generate images from text prompts"
* />
*
* <SectionHeader level={2} id="endpoint">
* Endpoint
* </SectionHeader>
*
* <EndpointCard
* method="POST"
* endpoint="/api/text-to-image"
* />
*
* <SectionHeader level={2} id="response">
* Response
* </SectionHeader>
*
* <ResponseBlock
* status="success"
* statusCode={200}
* content={responseJSON}
* />
*
* <SectionHeader level={2} id="next-steps">
* Next Steps
* </SectionHeader>
*
* <LinkCardGrid columns={2}>
* <LinkCard
* href="/docs/guides"
* title="Guides"
* description="Learn best practices"
* accent="secondary"
* />
* <LinkCard
* href="/docs/examples"
* title="Examples"
* description="See code samples"
* accent="primary"
* />
* </LinkCardGrid>
* </>
* );
* }
* ```
*
* ## Color System Reference
*
* ### Semantic Colors
* - **primary**: Purple - Brand primary, main content
* - **secondary**: Cyan - Complementary, supporting content
* - **success**: Green - Positive outcomes, achievements
* - **info**: Blue/Cyan - Informational, neutral
* - **warning**: Amber - Caution, important notices
* - **error**: Red - Errors, problems, danger
* - **neutral**: Slate/Gray - Default, inactive
*
* ### HTTP Method Colors
* - **GET**: Cyan - Read operations
* - **POST**: Green - Create operations
* - **PUT**: Amber - Update operations
* - **PATCH**: Purple - Partial update
* - **DELETE**: Red - Delete operations
*
* ## Spacing System
*
* Consistent spacing creates visual rhythm:
* - **sm**: Tight spacing for compact layouts
* - **md**: Standard spacing (default for most components)
* - **lg**: Generous spacing for major sections
*
* ## Typography Scale
*
* Hierarchical text sizing:
* - **Hero**: text-4xl → text-6xl (large, page-level)
* - **H2**: text-3xl (section headings)
* - **H3**: text-xl (subsection headings)
* - **Body**: text-base (paragraph text)
* - **Small**: text-sm (supporting text)
* - **Code**: text-xs (code samples)
*
* @module blocks
*/
// Status & Indicators
export { StatusBadge, type StatusBadgeProps, type StatusType, type StatusSize } from './StatusBadge';
export { MethodBadge, type MethodBadgeProps, type HttpMethod, type MethodBadgeSize } from './MethodBadge';
// Typography & Content
export { Hero, type HeroProps, type HeroSize } from './Hero';
export { SectionHeader, type SectionHeaderProps, type SectionHeaderLevel } from './SectionHeader';
export { InlineCode, type InlineCodeProps, type InlineCodeColor } from './InlineCode';
// API Documentation
export { EndpointCard, type EndpointCardProps } from './EndpointCard';
export { ResponseBlock, type ResponseBlockProps } from './ResponseBlock';
// Navigation
export { LinkCard, type LinkCardProps, type LinkCardAccent } from './LinkCard';
export { LinkCardGrid, type LinkCardGridProps, type GridColumns } from './LinkCardGrid';