pxengine 0.1.7 → 0.1.10

package/README.md

@@ -2,29 +2,19 @@
 
 > **Shadcn-based UI component library for agent-driven interfaces**
 
-A standalone UI component library built on top of shadcn/ui, designed specifically for agent-driven user interfaces. Components follow Atomic Design principles and are distributed via copy-paste (shadcn-style).
+A premium UI component library built on top of shadcn/ui, designed specifically for agent-driven user interfaces and creator discovery platforms. Components follow Atomic Design principles and are optimized for schema-driven rendering.
 
 ---
 
 ## Overview
 
-`@pxengine-ui` is a component library that:
+`@pxengine-ui` provides a robust foundation for building modern dashboard and AI-integrated applications:
 
-- **Builds on shadcn/ui** - Uses shadcn components as atoms (base layer)
-- **Follows Atomic Design** - Atoms (shadcn) → Molecules → Organisms
-- **Agent-First** - Designed for schema-driven, agent-generated UIs
-- **Copy-Paste Distribution** - Like shadcn, components are copied into your project
-- **TypeScript-First** - Full type safety across the stack
-- **Theme-Aware** - Inherits from your existing theme system
-
----
-
-## Documentation
-
-- **[Architecture](./docs/architecture.md)** - System design, folder structure, design decisions
-- **[Conventions](./docs/conventions.md)** - Naming, coding standards, best practices
-- **[Getting Started](./docs/getting-started.md)** - Setup and usage guide
-- **[Component Catalog](./docs/component-catalog.md)** - Visual reference for all components
+- **Built on shadcn/ui** - Industry-standard base layer using Radix UI primitives.
+- **Vibrant & Premium** - Custom design system with glassmorphism, smooth gradients, and rich micro-interactions.
+- **Agent-First** - Fully schema-driven atoms ready for AI generation.
+- **Atomic Design** - 40+ Atoms and 18+ Composed Molecules.
+- **Zero Configuration** - Inherits Tailwind config and CSS variables from the host application.
 
 ---
 
@@ -32,144 +22,111 @@ A standalone UI component library built on top of shadcn/ui, designed specifical
 
 ```
 @pxengine-ui/
-├── docs/                    # Documentation
 ├── src/
-│   ├── atoms/              # Shadcn components (base layer)
-│   ├── molecules/          # Composed components
-│   │   ├── creator-discovery/  # Domain-specific
-│   │   └── generic/            # Reusable
-│   ├── lib/                # Utilities
-│   ├── types/              # Shared types
-│   └── index.ts
-├── config/                 # Tailwind preset, tsconfig
-└── package.json
+│   ├── atoms/               # Foundation UI (Button, Input, Slider, etc.)
+│   ├── molecules/           # Composed Patterns
+│   │   ├── generic/         # Cross-domain dashboard widgets
+│   │   └── creator-discovery/ # Niche-specific for creator search
+│   ├── types/               # Schema & Component definitions
+│   └── lib/                 # Shared utilities
+└── dist/                    # Compiled assets & Registry
 ```
 
 ---
 
-## Component Hierarchy
+## Component Catalog
 
-### **Atoms** (Shadcn Components)
+### Atoms (Foundation Primitives)
 
-Base UI primitives from shadcn/ui:
+40+ accessible atoms wrapping Radix-based shadcn components:
 
-- Button, Input, Label, Checkbox, Select, Slider, Card, etc.
-- Fully accessible (Radix UI primitives)
-- Styled with Tailwind CSS
+- **Forms**: Input, Checkbox, RadioGroup, Select, Switch, Slider, Textarea, Toggle.
+- **Navigation**: DropdownMenu, ContextMenu, Pagination, Breadcrumb, Tabs, Command.
+- **Overlay**: Dialog, AlertDialog, Drawer, Sheet, Popover, Tooltip.
+- **Display**: Card, Badge, Avatar, Accordion, AspectRatio, Skeleton, Separator, Progress.
+- **Specialized**: Resizable Panels, InputOTP, Kbd (Keyboard shortcuts).
 
-### **Molecules** (Composed Components)
+### Molecules (High-Level Patterns)
 
-Built by combining atoms:
+#### Generic Dashboard
 
-- **Creator Discovery**: CampaignSeedCard, SearchSpecCard, MCQRenderer
-- **Generic**: EditableField, FormCard, ActionButton
+- **StatsGrid**: Data visualization with trends & icons.
+- **EmptyState**: Premium placeholder for empty results.
+- **LoadingOverlay**: Glassmorphism backdrop with progress.
+- **FilterBar**: Search + Multi-chip filtering.
+- **FileUpload**: Drag-and-drop zone.
+- **TagCloud**: Interactive interest clusters.
+- **FormCard**: Schema-driven editable forms.
 
-### **Organisms** (Complex Sections)
+#### Creator Discovery
 
-Full UI sections (future):
-
-- CreatorSearchWorkflow, CampaignBuilder, etc.
+- **CreatorGridCard**: Detailed discovery card with banner and metrics.
+- **AudienceMetricCard**: Specialized progress-based demographics.
+- **BrandAffinityGroup**: Visual recently associated brand logos.
+- **ContentPreviewGallery**: Video/Image thumbnail grids.
+- **CreatorProfileSummary**: Compact info row for list views.
+- **PlatformIconGroup**: Social platform reach summary.
+- **SearchSpecCard**: Advanced filter criteria summary.
 
 ---
 
-## Quick Start
-
-### 1. Install Dependencies
-
-```bash
-cd @pxengine-ui
-npm install
-```
+## Usage
 
-### 2. Copy a Component
+### Registry-Driven Rendering
 
-```bash
-# Copy shadcn button atom
-npx shadcn-ui@latest add button
+The library generates a `registry.json` that includes component metadata and schemas, allowing agents to understand what they can render.
 
-# Copy a molecule (future CLI)
-npx pxengine-ui add campaign-seed-card
+```tsx
+import { PXEngineRenderer } from "@/components/PXEngineRenderer";
+
+const schema = {
+  type: "stats-grid",
+  items: [
+    {
+      label: "Total Reach",
+      value: "1.2M",
+      trend: "+12%",
+      trendDirection: "up",
+    },
+  ],
+};
+
+return <PXEngineRenderer schema={schema} />;
 ```
 
-### 3. Use in Your App
+### Direct Component Import
+
+All components are exported for standard React usage:
 
 ```tsx
-import { CampaignSeedCard } from "@/components/pxengine-ui/molecules/CampaignSeedCard";
+import { CreatorGridCard } from "pxengine";
 
-<CampaignSeedCard
-  data={campaignSeed}
-  sessionId="abc123"
-  onProceed={() => handleProceed()}
+<CreatorGridCard
+  name="Jane Doe"
+  handle="janedoe"
+  metrics={[{ label: "Followers", value: "500K" }]}
+  platforms={["Instagram", "TikTok"]}
 />;
 ```
 
 ---
 
-## Distribution Strategy
-
-**Shadcn-Style Copy-Paste**:
-
-1. Components live in `@pxengine-ui/src/`
-2. Copy components into `client/components/pxengine-ui/` when needed
-3. Modify copied components freely
-4. Library serves as source of truth for updates
-
-**Benefits**:
-
-- Full ownership and customization
-- No version conflicts
-- Tree-shaking (only copy what you need)
-- Easy to debug
-
----
-
-## Theme System
+## Design System
 
-The library inherits your existing theme:
+The library uses a specific high-end aesthetic:
 
-- Uses CSS variables from client
-- Tailwind preset extends client config
-- Dark mode support via `class` strategy
-
----
-
-## Component Examples
-
-### CampaignSeedCard
-
-```tsx
-<CampaignSeedCard
-  data={{
-    brand: "Nike",
-    objective: "Brand Awareness",
-    budget_hint: { min: 50000, max: 100000 },
-  }}
-  sessionId="abc123"
-  onProceed={() => handleProceed()}
-  isLatestMessage={true}
-/>
-```
-
-### EditableField
-
-```tsx
-<EditableField
-  label="Brand Name"
-  value={brandName}
-  type="text"
-  isEditing={isEditing}
-  onSave={(newValue) => handleSave(newValue)}
-/>
-```
+- **Colors**: Indigo, Purple, and Slate primary hues.
+- **Border Radius**: Generous `rounded-3xl` and `rounded-[32px]` for major components.
+- **Backdrop**: Heavy use of `backdrop-blur-md` and `bg-white/60`.
+- **Shadows**: Subtle, layered soft shadows for depth.
 
 ---
 
 ## Tech Stack
 
-- **React** 18+ with TypeScript
-- **Shadcn/ui** for base components (atoms)
-- **Radix UI** for accessibility primitives
-- **Tailwind CSS** for styling
-- **Framer Motion** for animations (optional)
-
----
+- **Framework**: React 18+ (Vite/tsup build)
+- **Styling**: Tailwind CSS + `class-variance-authority`
+- **Primitives**: Radix UI
+- **Animations**: Framer Motion
+- **Icons**: Lucide React
+- **Data**: Recharts / Zod