📚 Comprehensive Documentation Suite (Mil-Spec/IBM Redbook Style)
INVESTOR DOCUMENTATION: - INVESTOR_BRIEF.md: Executive summary, capacity metrics, architecture overview - PLATFORM_CAPABILITIES.md: 5 modules, 27 subcomponents catalog - TECHNICAL_ARCHITECTURE.md: Mermaid diagrams, data flows, extension points CTO/SENIOR DEV ONBOARDING: - CTO_ONBOARDING.md: System overview, security model, operational runbook - DEVELOPER_GUIDE.md: Clone→Run→Deploy workflow, debugging - API_REFERENCE.md: 30+ endpoints with request/response specs - DATABASE_SCHEMA.md: 30+ tables in Harris Matrix order - COMPONENT_LIBRARY.md: 182 React components catalog REFERENCE: - GLOSSARY.md: 70+ platform terms defined - ADMIN_PAGES_GUIDE.md: 66 admin pages by module Style: BLUF format, zero marketing fluff, high-density tables
This commit is contained in:
cawcenter
325
docs/COMPONENT_LIBRARY.md
Normal file
325
docs/COMPONENT_LIBRARY.md
Normal file
@@ -0,0 +1,325 @@
|
||||
# COMPONENT LIBRARY: Spark Platform UI Catalog
|
||||
|
||||
> **BLUF**: 182 React components in 14 directories. Admin (95 files), Blocks (25 files), UI (18 files).
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Organization
|
||||
|
||||
```
|
||||
frontend/src/components/
|
||||
├── admin/ # 95 files - Dashboard components
|
||||
├── analytics/ # 4 files - Analytics widgets
|
||||
├── assembler/ # 8 files - Article assembly
|
||||
├── automations/ # 1 file - Workflow automation
|
||||
├── blocks/ # 25 files - Page builder blocks
|
||||
├── collections/ # 1 file - Generic collection UI
|
||||
├── debug/ # 1 file - Debug utilities
|
||||
├── engine/ # 4 files - Rendering engine
|
||||
├── factory/ # 9 files - Content Factory
|
||||
├── intelligence/ # 7 files - Intelligence Library
|
||||
├── layout/ # 1 file - Layout components
|
||||
├── providers/ # 1 file - React providers
|
||||
├── testing/ # 7 files - Test utilities
|
||||
└── ui/ # 18 files - Shadcn primitives
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Admin Components
|
||||
|
||||
Location: `frontend/src/components/admin/`
|
||||
|
||||
### 2.1 Intelligence Managers
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| AvatarIntelligenceManager | `intelligence/AvatarIntelligenceManager.tsx` | Avatar CRUD + stats |
|
||||
| GeoIntelligenceManager | `intelligence/GeoIntelligenceManager.tsx` | Map + location CRUD |
|
||||
| SpintaxManager | `intelligence/SpintaxManager.tsx` | Dictionary editor |
|
||||
| CartesianManager | `intelligence/CartesianManager.tsx` | Pattern builder |
|
||||
| PatternAnalyzer | `intelligence/PatternAnalyzer.tsx` | Pattern testing |
|
||||
| OfferBlocksManager | `intelligence/OfferBlocksManager.tsx` | Offer template CRUD |
|
||||
| IntelligenceDashboard | `intelligence/IntelligenceDashboard.tsx` | Module overview |
|
||||
|
||||
### 2.2 Factory Components
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| KanbanBoard | `factory/KanbanBoard.tsx` | Drag-drop workflow |
|
||||
| ArticleWorkbench | `factory/ArticleWorkbench.tsx` | Article editing |
|
||||
| BulkGrid | `factory/BulkGrid.tsx` | Multi-select operations |
|
||||
| JobsMonitor | `factory/JobsMonitor.tsx` | Queue status |
|
||||
| SendToFactoryButton | `factory/SendToFactoryButton.tsx` | Factory trigger |
|
||||
|
||||
### 2.3 SEO Components
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| CampaignWizard | `seo/CampaignWizard.tsx` | Campaign creation wizard |
|
||||
| ArticleList | `seo/ArticleList.tsx` | Article table |
|
||||
| HeadlineGenerator | `seo/HeadlineGenerator.tsx` | Headline permutation UI |
|
||||
| FragmentsManager | `seo/FragmentsManager.tsx` | Fragment CRUD |
|
||||
| ArticleEditor | `seo/ArticleEditor.tsx` | Single article edit |
|
||||
| ArticlePreview | `seo/ArticlePreview.tsx` | Preview renderer |
|
||||
|
||||
### 2.4 Sites Components
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| SitesManager | `sites/SitesManager.tsx` | Site list + actions |
|
||||
| SiteEditor | `sites/SiteEditor.tsx` | Site settings |
|
||||
| SiteDashboard | `sites/SiteDashboard.tsx` | Site overview |
|
||||
| PagesList | `sites/PagesList.tsx` | Page management |
|
||||
| NavigationEditor | `sites/NavigationEditor.tsx` | Menu builder |
|
||||
| ThemeSettings | `sites/ThemeSettings.tsx` | Theme configuration |
|
||||
|
||||
### 2.5 Content Components
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| PageEditor | `content/PageEditor.tsx` | Block-based editor |
|
||||
| PostEditor | `content/PostEditor.tsx` | Blog post editor |
|
||||
| ContentFactoryDashboard | `content/ContentFactoryDashboard.tsx` | Factory overview |
|
||||
| VisualBlockEditor | `content/VisualBlockEditor.tsx` | Visual editor |
|
||||
|
||||
### 2.6 System Components
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| SystemMonitor | `system/SystemMonitor.tsx` | Health dashboard |
|
||||
| SystemStatusBar | `system/SystemStatusBar.tsx` | Status indicator |
|
||||
| SettingsManager | `SettingsManager.tsx` | Platform settings |
|
||||
| LogViewer | `system/LogViewer.tsx` | Work log viewer |
|
||||
| WPImporter | `import/WPImporter.tsx` | WordPress import |
|
||||
| JumpstartWizard | `jumpstart/JumpstartWizard.tsx` | Quick site setup |
|
||||
|
||||
### 2.7 Testing Components
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| TestRunner | `testing/TestRunner.tsx` | Test executor |
|
||||
| TestResults | `testing/TestResults.tsx` | Results display |
|
||||
| ConnectionTester | `testing/ConnectionTester.tsx` | API tests |
|
||||
|
||||
---
|
||||
|
||||
## 3. Block Components
|
||||
|
||||
Location: `frontend/src/components/blocks/`
|
||||
|
||||
### Page Builder Blocks
|
||||
|
||||
| Block | File | Description |
|
||||
|-------|------|-------------|
|
||||
| HeroBlock | `HeroBlock.tsx` | Full-width header with CTA |
|
||||
| RichTextBlock | `RichTextBlock.tsx` | SEO-optimized prose |
|
||||
| ColumnsBlock | `ColumnsBlock.tsx` | Multi-column layout |
|
||||
| MediaBlock | `MediaBlock.tsx` | Image/video with caption |
|
||||
| StepsBlock | `StepsBlock.tsx` | Numbered process |
|
||||
| QuoteBlock | `QuoteBlock.tsx` | Testimonial/blockquote |
|
||||
| GalleryBlock | `GalleryBlock.tsx` | Image grid |
|
||||
| FAQBlock | `FAQBlock.tsx` | Accordion with schema.org |
|
||||
| PostsBlock | `PostsBlock.tsx` | Blog listing |
|
||||
| FormBlock | `FormBlock.tsx` | Lead capture form |
|
||||
| CTABlock | `CTABlock.tsx` | Call-to-action |
|
||||
| MapBlock | `MapBlock.tsx` | Embedded map |
|
||||
| CardBlock | `CardBlock.tsx` | Card layout |
|
||||
| DividerBlock | `DividerBlock.tsx` | Section separator |
|
||||
| SpacerBlock | `SpacerBlock.tsx` | Vertical spacing |
|
||||
| HeaderBlock | `HeaderBlock.tsx` | Section header |
|
||||
| ListBlock | `ListBlock.tsx` | Bullet/numbered list |
|
||||
| TableBlock | `TableBlock.tsx` | Data table |
|
||||
| CodeBlock | `CodeBlock.tsx` | Code snippet |
|
||||
| EmbedBlock | `EmbedBlock.tsx` | External embed |
|
||||
|
||||
### Block Renderer
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| BlockRenderer | `engine/BlockRenderer.tsx` | JSON → component mapper |
|
||||
| BlockWrapper | `engine/BlockWrapper.tsx` | Styling container |
|
||||
|
||||
---
|
||||
|
||||
## 4. UI Components (Shadcn-style)
|
||||
|
||||
Location: `frontend/src/components/ui/`
|
||||
|
||||
### Form Controls
|
||||
|
||||
| Component | File | Usage |
|
||||
|-----------|------|-------|
|
||||
| Button | `button.tsx` | `<Button variant="default">` |
|
||||
| Input | `input.tsx` | `<Input type="text">` |
|
||||
| Textarea | `textarea.tsx` | `<Textarea rows={4}>` |
|
||||
| Select | `select.tsx` | `<Select><SelectItem>` |
|
||||
| Switch | `switch.tsx` | `<Switch checked={}>` |
|
||||
| Slider | `slider.tsx` | `<Slider value={}>` |
|
||||
| Label | `label.tsx` | `<Label htmlFor="">` |
|
||||
|
||||
### Layout
|
||||
|
||||
| Component | File | Usage |
|
||||
|-----------|------|-------|
|
||||
| Card | `card.tsx` | `<Card><CardHeader>...` |
|
||||
| Dialog | `dialog.tsx` | `<Dialog><DialogContent>` |
|
||||
| Sheet | `sheet.tsx` | `<Sheet><SheetContent>` |
|
||||
| Table | `table.tsx` | `<Table><TableRow>` |
|
||||
| Tabs | `tabs.tsx` | `<Tabs><TabsContent>` |
|
||||
| Separator | `separator.tsx` | `<Separator>` |
|
||||
|
||||
### Feedback
|
||||
|
||||
| Component | File | Usage |
|
||||
|-----------|------|-------|
|
||||
| Toast | `toast.tsx` | `toast({ title, description })` |
|
||||
| Tooltip | `tooltip.tsx` | `<Tooltip><TooltipContent>` |
|
||||
| DropdownMenu | `dropdown-menu.tsx` | `<DropdownMenu><DropdownMenuItem>` |
|
||||
|
||||
---
|
||||
|
||||
## 5. Analytics Components
|
||||
|
||||
Location: `frontend/src/components/analytics/`
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| MetricsDashboard | `MetricsDashboard.tsx` | Analytics overview |
|
||||
| ChartWidget | `ChartWidget.tsx` | Data visualization |
|
||||
| StatCard | `StatCard.tsx` | Single metric display |
|
||||
|
||||
---
|
||||
|
||||
## 6. Engine Components
|
||||
|
||||
Location: `frontend/src/components/engine/`
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| BlockRenderer | `BlockRenderer.tsx` | Renders JSON blocks |
|
||||
| PageRenderer | `PageRenderer.tsx` | Full page rendering |
|
||||
| ArticleRenderer | `ArticleRenderer.tsx` | Article display |
|
||||
| PreviewFrame | `PreviewFrame.tsx` | Preview container |
|
||||
|
||||
---
|
||||
|
||||
## 7. Automations Components
|
||||
|
||||
Location: `frontend/src/components/automations/`
|
||||
|
||||
| Component | File | Purpose |
|
||||
|-----------|------|---------|
|
||||
| AutomationBuilder | `AutomationBuilder.tsx` | Workflow editor |
|
||||
|
||||
---
|
||||
|
||||
## 8. Usage Examples
|
||||
|
||||
### Using Admin Components
|
||||
|
||||
```tsx
|
||||
import { SitesManager } from '@/components/admin/sites/SitesManager';
|
||||
|
||||
export default function SitesPage() {
|
||||
return <SitesManager client:load />;
|
||||
}
|
||||
```
|
||||
|
||||
### Using UI Components
|
||||
|
||||
```tsx
|
||||
import { Button } from '@/components/ui/button';
|
||||
import { Card, CardHeader, CardContent } from '@/components/ui/card';
|
||||
|
||||
function MyComponent() {
|
||||
return (
|
||||
<Card>
|
||||
<CardHeader>Title</CardHeader>
|
||||
<CardContent>
|
||||
<Button variant="default">Click</Button>
|
||||
</CardContent>
|
||||
</Card>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Using Blocks
|
||||
|
||||
```tsx
|
||||
import { BlockRenderer } from '@/components/engine/BlockRenderer';
|
||||
|
||||
function PageContent({ blocks }) {
|
||||
return <BlockRenderer blocks={blocks} />;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Design System
|
||||
|
||||
### Colors (Titanium Pro)
|
||||
|
||||
| Name | Value | Usage |
|
||||
|------|-------|-------|
|
||||
| Background | `#09090b` (zinc-950) | Page background |
|
||||
| Primary | `#eab308` (yellow-500) | Accent, buttons |
|
||||
| Success | `#22c55e` (green-500) | Positive actions |
|
||||
| Accent | `#a855f7` (purple-500) | Highlights |
|
||||
| Text | `#ffffff` / `#94a3b8` | Primary / secondary |
|
||||
|
||||
### Typography
|
||||
|
||||
| Element | Class |
|
||||
|---------|-------|
|
||||
| Heading 1 | `text-4xl font-bold` |
|
||||
| Heading 2 | `text-2xl font-semibold` |
|
||||
| Body | `text-base text-slate-300` |
|
||||
| Small | `text-sm text-slate-400` |
|
||||
|
||||
### Spacing
|
||||
|
||||
| Size | Value | Usage |
|
||||
|------|-------|-------|
|
||||
| xs | `4px` | Tight padding |
|
||||
| sm | `8px` | Compact spacing |
|
||||
| md | `16px` | Standard spacing |
|
||||
| lg | `24px` | Section spacing |
|
||||
| xl | `32px` | Large sections |
|
||||
|
||||
---
|
||||
|
||||
## 10. Component Creation Guidelines
|
||||
|
||||
### File Structure
|
||||
|
||||
```tsx
|
||||
// components/admin/MyFeature/MyComponent.tsx
|
||||
|
||||
import { useState } from 'react';
|
||||
import { Button } from '@/components/ui/button';
|
||||
|
||||
interface MyComponentProps {
|
||||
data: MyType;
|
||||
onAction?: () => void;
|
||||
}
|
||||
|
||||
export function MyComponent({ data, onAction }: MyComponentProps) {
|
||||
const [state, setState] = useState(false);
|
||||
|
||||
return (
|
||||
<div className="p-4 bg-zinc-900 rounded-lg">
|
||||
{/* Component content */}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
| Type | Convention | Example |
|
||||
|------|------------|---------|
|
||||
| Component | PascalCase | `MyComponent.tsx` |
|
||||
| Hook | camelCase, use-prefix | `useMyHook.ts` |
|
||||
| Utility | camelCase | `formatDate.ts` |
|
||||
| Type | PascalCase | `MyComponentProps` |
|
||||
Reference in New Issue
Block a user