pxengine 0.1.143 → 0.1.144

package/README.md

@@ -2,7 +2,7 @@
 
 > **Shadcn-based UI component library for agent-driven interfaces**
 
-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.
+A UI component library built on top of shadcn/ui, published to npm as **`pxengine`**, designed specifically for agent-driven interfaces: LLM agents emit a JSON schema, and `PXEngineRenderer` maps it to a React component. Components follow Atomic Design principles and are optimized for schema-driven rendering. Primary consumer is `pxengine-builder`, which links it locally (`"pxengine": "file:../@pxengine-ui"`).
 
 ---
 
@@ -11,10 +11,10 @@ A premium UI component library built on top of shadcn/ui, designed specifically
 `@pxengine-ui` provides a robust foundation for building modern dashboard and AI-integrated applications:
 
 - **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.
+- **Themeable via CSS variables** - No hardcoded palette. Components read `--px-*`/host CSS custom properties at render time (falling back to internal purple/indigo defaults when a consumer doesn't supply them), so a dark-gold host app (like `pxengine-builder`) and a light one render the same components on entirely different themes with zero component changes.
+- **Agent-First** - Fully schema-driven atoms and molecules ready for AI generation via `PXEngineRenderer`.
+- **Atomic Design** - 52 Atoms and 60+ Composed Molecules across two domains (generic dashboard + creator discovery).
+- **Zero Configuration** - Inherits Tailwind config and CSS variables from the host application; the host just needs `"node_modules/pxengine/**/*.{js,ts,jsx,tsx}"` in its Tailwind `content` array or production builds purge all pxengine classes.
 
 ---
 
@@ -23,13 +23,17 @@ A premium UI component library built on top of shadcn/ui, designed specifically
 ```
 @pxengine-ui/
 ├── src/
-│   ├── atoms/               # Foundation UI (Button, Input, Slider, etc.)
+│   ├── atoms/               # Foundation UI (Button, Input, Slider, etc.) — 52 components
 │   ├── molecules/           # Composed Patterns
-│   │   ├── generic/         # Cross-domain dashboard widgets
-│   │   └── creator-discovery/ # Niche-specific for creator search
+│   │   ├── generic/         # Cross-domain dashboard widgets (~48 components)
+│   │   └── creator-discovery/ # Niche-specific for creator search (~16 components)
 │   ├── types/               # Schema & Component definitions
 │   └── lib/                 # Shared utilities
-└── dist/                    # Compiled assets & Registry
+├── scripts/
+│   ├── generate-metadata.ts          # Builds dist/registry.json (component catalog for agents)
+│   └── generate-molecule-registry.ts # Builds the molecule-only registry
+├── tailwind-preset.js        # Shared Tailwind preset re-exported for consumers
+└── dist/                    # Compiled assets (tsup: CJS + ESM + DTS) & Registry
 ```
 
 ---
@@ -38,7 +42,7 @@ A premium UI component library built on top of shadcn/ui, designed specifically
 
 ### Atoms (Foundation Primitives)
 
-40+ accessible atoms wrapping Radix-based shadcn components:
+52 accessible atoms wrapping Radix-based shadcn components:
 
 - **Forms**: Input, Checkbox, RadioGroup, Select, Switch, Slider, Textarea, Toggle.
 - **Navigation**: DropdownMenu, ContextMenu, Pagination, Breadcrumb, Tabs, Command.
@@ -48,25 +52,25 @@ A premium UI component library built on top of shadcn/ui, designed specifically
 
 ### Molecules (High-Level Patterns)
 
-#### Generic Dashboard
+#### Generic Dashboard (`src/molecules/generic/`)
 
-- **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.
+Cross-domain widgets, including job-card families for long-running agent work (`ResearchReportJobCard`, `PresentationJobCard`, `WebSearchJobCard` — share layout/state conventions via `job-card-shared/`), data/table components (`DataGrid`, `DataTableCard`, `TablePagination`), integration cards (`GitHubConnectCard`, `GitHubRepoHealthCard`, `GoogleSheetsCard`, `GoogleSheetsConnectCard`), and general dashboard primitives:
 
-#### Creator Discovery
+- **StatsGrid** / **KPIStatsCard**: Data visualization with trends & icons.
+- **EmptyState**, **LoadingOverlay**: Placeholder/loading states.
+- **FilterBar**, **FileUpload**, **TagCloud**, **FormCard**, **DynamicFormCard**, **EditableField**: Input & filtering patterns.
+- **ChecklistCard**, **ApprovalCard**, **ConfirmationCard**, **PollCard**: Decision/workflow patterns.
+- **CampaignBriefCard**, **ChannelPlanCard**, **BudgetAllocCard**, **CalendarEventCard**: Campaign-planning widgets.
+
+#### Creator Discovery (`src/molecules/creator-discovery/`)
 
 - **CreatorGridCard**: Detailed discovery card with banner and metrics.
-- **AudienceMetricCard**: Specialized progress-based demographics.
+- **AudienceMetricCard** / **AudienceDemographicsCard**: 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.
+- **CreatorProfileSummary**, **CreatorSearchBox**, **CreatorWidget**, **CreatorActionHeader**: Search & profile patterns.
+- **PlatformIconGroup**, **GrowthChartCard**, **TopPostsGrid**: Reach & performance summaries.
+- **SearchSpecCard**, **MCQCard**, **CampaignSeedCard**, **CampaignConceptCard**: Agent-driven intake/spec patterns.
 
 ---
 
@@ -74,10 +78,10 @@ A premium UI component library built on top of shadcn/ui, designed specifically
 
 ### Registry-Driven Rendering
 
-The library generates a `registry.json` that includes component metadata and schemas, allowing agents to understand what they can render.
+`npm run build` runs `generate-metadata` automatically (`tsup.config.ts`'s `onSuccess` hook), producing `dist/registry.json` — component metadata + schemas so agents (the server's `ui_generator`/`widget_builder` agents) know what they can render. **Never hand-edit `dist/registry.json`** — it's derived output; if a new molecule isn't showing up in agent suggestions, rebuild and confirm the registry picked it up. `PXEngineRenderer` (exported from the package root) maps a schema's `type` field to a React component via a discriminated-union registry — adding a new molecule requires registering its `type` string there or it silently won't render.
 
 ```tsx
-import { PXEngineRenderer } from "@/components/PXEngineRenderer";
+import { PXEngineRenderer } from "pxengine";
 
 const schema = {
   type: "stats-grid",
@@ -113,20 +117,20 @@ import { CreatorGridCard } from "pxengine";
 
 ## Design System
 
-The library uses a specific high-end aesthetic:
+Components are **theme-agnostic by design** — they read CSS custom properties (`--px-*`, plus the host's own tokens) at render time rather than hardcoding a palette, so `cn()` (re-exported from `pxengine`, not `clsx`, for consumers) composes host classes on top of component defaults. A few atoms (e.g. `AvatarAtom`) fall back to internal indigo/purple/slate defaults (`var(--px-bg-color, var(--purple50))`) when a host doesn't supply theme vars — that fallback palette is NOT what most consumers actually see. `pxengine-builder`, the primary consumer, supplies a dark, gold-accented theme (`--gold: #C0AE82`, `surface.chat #0A0A0A` → `surface.elevated #1E1E1F`, see its README) via `globals.css`, and every pxengine component renders on that theme with zero component-level changes.
 
-- **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`.
+- **Backdrop**: Uses `backdrop-blur-md` for overlay/glass surfaces where the host theme calls for it.
 - **Shadows**: Subtle, layered soft shadows for depth.
 
 ---
 
 ## Tech Stack
 
-- **Framework**: React 18+ (Vite/tsup build)
-- **Styling**: Tailwind CSS + `class-variance-authority`
-- **Primitives**: Radix UI
-- **Animations**: Framer Motion
-- **Icons**: Lucide React
-- **Data**: Recharts / Zod
+- **Framework**: React (peer dep `^18.0.0 || ^19.0.0`; primary consumer runs 19) — built with **tsup** (CJS + ESM + `.d.ts`), not Vite
+- **Styling**: Tailwind CSS + `class-variance-authority` + `tailwind-preset.js` (shared preset re-exported for consumers)
+- **Primitives**: Radix UI (via shadcn/ui)
+- **Animations**: Framer Motion (peer dep, external — not bundled)
+- **Icons**: Lucide React (bundled into the build via `tsup`'s `noExternal`, along with `date-fns`, `@date-fns/tz`, `react-day-picker`)
+- **Charts**: Highcharts + `highcharts-react-official`, and Recharts — all peer deps, external
+- **Data/validation**: Zod

package/dist/registry.json

@@ -1,7 +1,7 @@
 {
   "name": "@pxengine/ui",
   "version": "1.0.0",
-  "lastUpdated": "2026-08-13T05:57:59.865Z",
+  "lastUpdated": "2026-08-13T10:11:51.826Z",
   "components": {
     "AccordionAtom": {
       "name": "AccordionAtom",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pxengine",
-  "version": "0.1.143",
+  "version": "0.1.144",
   "type": "module",
   "description": "Shadcn-based UI component library for agent-driven interfaces",
   "main": "./dist/index.cjs",