@stackwright-pro/pulse 0.2.0 → 0.2.1-alpha.0

package/README.md

@@ -20,6 +20,7 @@ pnpm add @stackwright-pro/pulse
 ```
 
 **Peer Dependencies:**
+
 ```bash
 pnpm add react react-dom @tanstack/react-query
 ```
@@ -33,10 +34,7 @@ import { Pulse, PulseIndicator } from '@stackwright-pro/pulse';
 
 function EquipmentPanel() {
   return (
-    <Pulse
-      fetcher={() => fetch('/api/equipment').then(r => r.json())}
-      interval={5000}
-    >
+    <Pulse fetcher={() => fetch('/api/equipment').then((r) => r.json())} interval={5000}>
       {(equipment, meta) => (
         <>
           <PulseIndicator meta={meta} />
@@ -64,7 +62,7 @@ const EquipmentSchema = z.object({
 function EquipmentPanel() {
   return (
     <Pulse
-      fetcher={() => fetch('/api/equipment').then(r => r.json())}
+      fetcher={() => fetch('/api/equipment').then((r) => r.json())}
       schema={EquipmentSchema}
       interval={5000}
     >
@@ -88,8 +86,8 @@ function CustomEquipmentPanel() {
       maxStaleAge={60000}
       loadingState={<SkeletonLoader />}
       errorState={(meta) => (
-        <ErrorBanner 
-          message="Failed to load equipment" 
+        <ErrorBanner
+          message="Failed to load equipment"
           lastUpdated={meta.lastUpdated}
           onRetry={meta.refetch}
         />
@@ -147,27 +145,27 @@ function CustomEquipmentPanel() {
 ```tsx
 interface PulseProps<T> {
   // Core
-  fetcher: () => Promise<T>;           // Your data fetching function
+  fetcher: () => Promise<T>; // Your data fetching function
   children: (data: T, meta: PulseMeta) => React.ReactNode;
-  
+
   // Polling config
-  interval?: number;                   // Poll interval in ms (default: 5000, min: 1000)
-  enabled?: boolean;                   // Enable/disable polling (default: true)
-  retryCount?: number;                 // Number of retries on error (default: 3)
-  refetchOnWindowFocus?: boolean;      // Refetch on window focus (default: true)
-  
+  interval?: number; // Poll interval in ms (default: 5000, min: 1000)
+  enabled?: boolean; // Enable/disable polling (default: true)
+  retryCount?: number; // Number of retries on error (default: 3)
+  refetchOnWindowFocus?: boolean; // Refetch on window focus (default: true)
+
   // State thresholds (in milliseconds)
-  staleThreshold?: number;             // Show stale warning (default: 30000)
-  maxStaleAge?: number;                // Show error state (default: 60000)
-  
+  staleThreshold?: number; // Show stale warning (default: 30000)
+  maxStaleAge?: number; // Show error state (default: 60000)
+
   // Validation
-  schema?: ZodSchema<T>;               // Optional Zod schema
-  
+  schema?: ZodSchema<T>; // Optional Zod schema
+
   // Custom state UI
   loadingState?: React.ReactNode;
   errorState?: React.ReactNode | ((meta: PulseMeta) => React.ReactNode);
   emptyState?: React.ReactNode;
-  showStaleDataOnError?: boolean;       // Show data during error (default: true)
+  showStaleDataOnError?: boolean; // Show data during error (default: true)
 }
 ```
 
@@ -175,12 +173,12 @@ interface PulseProps<T> {
 
 ```tsx
 interface PulseMeta {
-  lastUpdated: Date;        // Timestamp of last successful fetch
-  isStale: boolean;         // Data older than staleThreshold
-  isError: boolean;        // Data older than maxStaleAge or fetch failed
-  isLoading: boolean;      // Currently fetching
-  errorCount: number;      // Number of consecutive errors
-  refetch: () => void;     // Manual refresh trigger
+  lastUpdated: Date; // Timestamp of last successful fetch
+  isStale: boolean; // Data older than staleThreshold
+  isError: boolean; // Data older than maxStaleAge or fetch failed
+  isLoading: boolean; // Currently fetching
+  errorCount: number; // Number of consecutive errors
+  refetch: () => void; // Manual refresh trigger
   state: 'loading' | 'live' | 'stale' | 'error';
 }
 ```
@@ -189,14 +187,14 @@ interface PulseMeta {
 
 ```tsx
 interface PulseIndicatorProps {
-  meta: PulseMeta;                              // Required meta object
-  showSeconds?: boolean;                       // Show "Xs ago" (default: true)
-  className?: string;                           // Additional CSS classes
+  meta: PulseMeta; // Required meta object
+  showSeconds?: boolean; // Show "Xs ago" (default: true)
+  className?: string; // Additional CSS classes
   labels?: {
-    live?: string;                              // Custom live label
-    syncing?: string;                           // Custom syncing label
-    stale?: string;                             // Custom stale label
-    error?: string;                             // Custom error label
+    live?: string; // Custom live label
+    syncing?: string; // Custom syncing label
+    stale?: string; // Custom stale label
+    error?: string; // Custom error label
   };
 }
 ```
@@ -228,12 +226,12 @@ const result = usePulse<T>({
 
 The `fetcher` prop accepts **any** async function. This makes Pulse work with:
 
-| Source | Example Fetcher |
-|--------|-----------------|
+| Source       | Example Fetcher                                |
+| ------------ | ---------------------------------------------- |
 | REST/OpenAPI | `() => fetch('/api/data').then(r => r.json())` |
-| WebSocket | `() => websocket.nextMessage()` |
-| GraphQL | `() => client.query({ query: MY_QUERY })` |
-| SSE | `() => eventSource.nextEvent()` |
+| WebSocket    | `() => websocket.nextMessage()`                |
+| GraphQL      | `() => client.query({ query: MY_QUERY })`      |
+| SSE          | `() => eventSource.nextEvent()`                |
 
 See [SOURCE_ADAPTERS.md](./docs/SOURCE_ADAPTERS.md) for planned first-party adapter documentation.
 
@@ -343,6 +341,333 @@ For a full working demo, see [examples/marine-logistics-demo/src/pages/dashboard
 
 See [docs/SOURCE_ADAPTERS.md](./docs/SOURCE_ADAPTERS.md) for planned adapter documentation.
 
+## Collection Binding (Phase 3 - Killer Pro Feature)
+
+The collection binding system connects **OpenAPI data** → **Prebuild** → **Pulse** → **Dashboard Components** for a complete live data experience.
+
+### Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                           DASHBOARD OTTER                                │
+│  Generates YAML with {{ collection.field }} template syntax              │
+└─────────────────────────────────┬────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                          stackwright.yml                                 │
+│  integrations:                                                            │
+│    - name: logistics-api                                                  │
+│      spec: ./openapi.yaml                                                │
+│      collections:                                                         │
+│        - endpoint: /equipment                                            │
+└─────────────────────────────────┬────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                         PREBUILD (pnpm prebuild)                          │
+│  OpenAPIPlugin generates:                                                 │
+│  - src/generated/logistics-api/provider.ts (CollectionProvider)         │
+│  - src/generated/logistics-api/schemas.ts (Zod schemas)                   │
+│  - src/generated/logistics-api/types.ts (TypeScript types)               │
+└─────────────────────────────────┬────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                     PulseCollectionProvider                              │
+│  Wraps dashboard with live collection context                            │
+│  - Creates fetchers from prebuild providers                              │
+│  - Polls at configured intervals (5s, 30s, 300s, etc.)                   │
+│  - Provides data via React context                                       │
+└─────────────────────────────────┬────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    Pulse-Enabled Components                              │
+│  MetricCardPulse, DataTablePulse, StatusBadgePulse                       │
+│  - Auto-bind to collection data                                          │
+│  - Support template syntax {{ collection.field }}                        │
+│  - Built-in aggregation (count, sum, avg)                                │
+│  - Live indicator with stale/error states                                │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+### Quick Start
+
+#### 1. Configure OpenAPI in `stackwright.yml`
+
+```yaml
+integrations:
+  - name: logistics-api
+    spec: ./openapi.yaml
+    auth:
+      type: bearer
+      token: ${API_TOKEN}
+    collections:
+      - endpoint: /equipment
+        slug_field: id
+      - endpoint: /locations
+        slug_field: id
+```
+
+#### 2. Run Prebuild
+
+```bash
+pnpm prebuild
+# Generates src/generated/logistics-api/*
+```
+
+#### 3. Use Pulse Components in Pages
+
+```yaml
+# pages/dashboard/content.yml
+content:
+  meta:
+    title: 'Live Equipment Dashboard'
+
+  content_items:
+    # Wrap with Pulse provider for live data
+    - type: pulse_provider
+      label: equipment-live
+      collections:
+        - name: equipment
+          endpoint: /api/equipment
+          refreshInterval: 5000
+      items:
+        - type: grid
+          columns: 4
+          items:
+            - type: metric_card_pulse
+              collection: equipment
+              field: items.length
+              label: 'Total Equipment'
+              icon: Truck
+
+            - type: metric_card_pulse
+              collection: equipment
+              field: items
+              label: 'Active'
+              aggregate: count
+              aggregateField: status
+              filter: '{"status": "active"}'
+              icon: CheckCircle
+
+    - type: data_table_pulse
+      collection: equipment
+      columns:
+        - field: id
+          header: ID
+          sortable: true
+        - field: name
+          header: Name
+        - field: status
+          header: Status
+          type: badge
+      sortBy: name
+      sortDirection: asc
+      limit: 20
+```
+
+### Component Reference
+
+### `pulse_provider`
+
+Wraps content with live collection data. All child Pulse components automatically bind to these collections.
+
+```yaml
+- type: pulse_provider
+  label: equipment-live
+  collections:
+    - name: equipment # Collection name for binding
+      endpoint: /api/equipment # OpenAPI endpoint
+      refreshInterval: 5000 # Poll every 5 seconds
+      filter: # Optional server-side filter
+        status: active
+  items:
+    # Child components here
+```
+
+Props:
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | string | Unique identifier |
+| `collections` | CollectionBinding[] | Collections to fetch |
+| `collections[].name` | string | Collection name for binding |
+| `collections[].endpoint` | string | API endpoint path |
+| `collections[].refreshInterval` | number | Poll interval in ms (default: 5000) |
+| `collections[].filter` | object | Server-side filter params |
+
+### `metric_card_pulse`
+
+KPI card with auto-bound live data.
+
+```yaml
+- type: metric_card_pulse
+  collection: equipment # Collection to bind
+  field: items.length # Field or expression
+  label: 'Total Equipment' # Display label
+  icon: Truck # Icon name
+  aggregate: count # Optional: count, sum, avg
+  aggregateField: status # Field for aggregation
+  filter: '{"status": "active"}' # Optional: filter items
+```
+
+Props:
+| Prop | Type | Description |
+|------|------|-------------|
+| `collection` | string | Collection name |
+| `field` | string | Field path (supports dots) |
+| `label` | string | Card label |
+| `icon` | ReactNode | Icon component |
+| `color` | string | Accent color (hex) |
+| `trend` | 'up' \| 'down' \| 'stable' | Trend direction |
+| `trendValue` | string | Trend display value |
+| `aggregate` | 'count' \| 'sum' \| 'avg' | Aggregate function |
+| `aggregateField` | string | Field for aggregation |
+| `filter` | string | JSON filter string |
+
+### `data_table_pulse`
+
+Sortable table with live data binding.
+
+```yaml
+- type: data_table_pulse
+  collection: equipment
+  columns:
+    - field: id
+      header: ID
+      sortable: true
+    - field: name
+      header: Name
+    - field: status
+      header: Status
+      type: badge
+  sortBy: name
+  sortDirection: asc
+  limit: 20
+```
+
+Props:
+| Prop | Type | Description |
+|------|------|-------------|
+| `collection` | string | Collection name |
+| `columns` | Column[] | Column definitions |
+| `sortBy` | string | Field to sort by |
+| `sortDirection` | 'asc' \| 'desc' | Sort direction |
+| `filter` | string | JSON filter string |
+| `limit` | number | Max items to show |
+| `onRowClick` | function | Row click handler |
+| `emptyMessage` | string | Empty state message |
+
+### `status_badge_pulse`
+
+Status indicator with live data binding.
+
+```yaml
+- type: status_badge_pulse
+  collection: equipment
+  field: items[0].status
+  label: 'System Status'
+  pulse: true
+```
+
+Props:
+| Prop | Type | Description |
+|------|------|-------------|
+| `collection` | string | Collection name |
+| `field` | string | Status field path |
+| `label` | string | Display label |
+| `pulse` | boolean | Show pulse animation |
+| `statusMap` | object | Custom value → status mapping |
+
+### Hooks
+
+For custom component integration:
+
+```tsx
+import {
+  usePulseCollections, // Full context
+  useCollection, // Single collection
+  useCollectionField, // Specific field
+  useTemplateResolution, // Resolve templates
+  resolveTemplate, // Static template resolver
+} from '@stackwright-pro/pulse';
+
+// Get full context
+const { collections, isLoading, getField } = usePulseCollections();
+
+// Get single collection
+const equipment = useCollection('equipment');
+// Returns: { items, count, meta, ... }
+
+// Get specific field
+const count = useCollectionField('equipment', 'items.length');
+
+// Resolve template anywhere
+const templateResolution = useTemplateResolution();
+const value = templateResolution('{{ equipment.count }}');
+```
+
+### Template Syntax
+
+The `{{ collection.field }}` syntax is automatically resolved:
+
+| Pattern      | Example                         | Result                |
+| ------------ | ------------------------------- | --------------------- |
+| Count        | `{{ equipment.count }}`         | Number of items       |
+| Array length | `{{ equipment.items.length }}`  | Array size            |
+| Nested field | `{{ equipment.items[0].name }}` | First item's name     |
+| Aggregate    | `{{ equipment.status.active }}` | Count of active items |
+
+### ISR Intervals
+
+Configure refresh intervals based on data freshness needs:
+
+| Interval | Use Case      | Example            |
+| -------- | ------------- | ------------------ |
+| 5000ms   | Real-time     | Live dashboard     |
+| 30000ms  | Near-realtime | Status updates     |
+| 300000ms | Hourly        | Reports, summaries |
+
+### Error Handling
+
+Pulse components handle errors gracefully:
+
+```tsx
+// With error state
+<DataTablePulse
+  collection="equipment"
+  columns={columns}
+  fallback={<ErrorBanner />}
+/>
+
+// With stale data (continue showing data during errors)
+<MetricCardPulse
+  collection="equipment"
+  field="count"
+  showStaleData={true}
+/>
+```
+
+### Complete Example
+
+See the marine-logistics demo for a full working example:
+
+```bash
+pnpm prebuild  # Generate providers
+pnpm dev       # Start dev server
+```
+
+The dashboard will show live-updating KPI cards and data tables with auto-refresh!
+
+### Future: Real-time Providers
+
+Coming soon:
+
+- `createWebSocketFetcher()` - WebSocket adapter
+- `createSSEFetcher()` - Server-Sent Events adapter
+- `createGraphQLFetcher()` - GraphQL polling adapter
+
 ## License
 
-PROPRIETARY - All rights reserved.
+PROPRIETARY - All rights reserved.

package/dist/collectionData-3ZJA4PEZ.mjs

@@ -0,0 +1,10 @@
+// src/collection/collectionData.ts
+async function getCollectionData(collection) {
+  console.warn(
+    `[collectionData] Stub called for collection: ${collection}. Run prebuild to generate real data fetchers.`
+  );
+  return [];
+}
+export {
+  getCollectionData
+};

package/dist/index.d.mts

@@ -230,4 +230,82 @@ declare class PulseValidationError extends Error {
     }[];
 }
 
-export { Pulse, PulseEmptyState, PulseErrorState, PulseIndicator, type PulseIndicatorProps, PulseLoadingState, type PulseMeta, type PulseOptions, type PulseProps, PulseStaleState, type PulseState, PulseSyncingState, PulseValidationError, createPulseValidator, usePulse, useStreaming };
+interface CollectionBinding {
+    collection: string;
+    endpoint: string;
+    slugField?: string;
+    refreshInterval?: number;
+    schema?: unknown;
+}
+interface CollectionData {
+    items: unknown[];
+    count: number;
+    meta: PulseMeta;
+    [key: string]: unknown;
+}
+interface PulseCollectionContextValue {
+    collections: Record<string, CollectionData>;
+    isLoading: boolean;
+    getCollection: (name: string) => CollectionData | null;
+    getField: (collection: string, field: string) => unknown;
+}
+declare function resolveTemplate(template: string, collections: Record<string, CollectionData>): unknown;
+declare function PulseCollectionProvider({ collections: collectionConfigs, children, fallback, }: {
+    collections: CollectionBinding[];
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function usePulseCollections(): PulseCollectionContextValue;
+declare function useCollection(collectionName: string): CollectionData | null;
+declare function useCollectionField(collectionName: string, field: string): unknown;
+declare function useTemplateResolution(): (template: string) => unknown;
+
+interface MetricCardPulseProps {
+    /** Collection name to bind to */
+    collection: string;
+    /** Field to display (supports {{ collection.field }} syntax) */
+    field: string;
+    /** Static label override */
+    label?: string;
+    /** Icon to show */
+    icon?: React.ReactNode;
+    /** Color for the card accent */
+    color?: string;
+    /** Trend direction: 'up' | 'down' | 'stable' */
+    trend?: 'up' | 'down' | 'stable';
+    /** Static trend value override */
+    trendValue?: string;
+    /** Aggregate function for array data: 'count' | 'sum' | 'avg' */
+    aggregate?: 'count' | 'sum' | 'avg';
+    /** Path within items to use for aggregation */
+    aggregateField?: string;
+}
+/**
+ * MetricCard with live data binding to collections
+ *
+ * Examples:
+ * ```yaml
+ * - type: metric_card_pulse
+ *   collection: equipment
+ *   field: items.length  # count of equipment
+ *   label: "Total Equipment"
+ *   icon: Truck
+ * ```
+ */
+declare function MetricCardPulse({ collection, field, label, icon, color, trend, trendValue, aggregate, aggregateField, }: MetricCardPulseProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Register Pulse collection binding components
+ *
+ * Call this AFTER registerDisplayComponents() in _app.tsx:
+ * ```ts
+ * import { registerDisplayComponents } from '@stackwright-pro/display-components';
+ * import { registerPulseComponents } from '@stackwright-pro/pulse';
+ *
+ * registerDisplayComponents();
+ * registerPulseComponents();
+ * ```
+ */
+declare function registerPulseComponents(): void;
+
+export { type CollectionBinding, MetricCardPulse, Pulse, type PulseCollectionContextValue, PulseCollectionProvider, PulseEmptyState, PulseErrorState, PulseIndicator, type PulseIndicatorProps, PulseLoadingState, type PulseMeta, type PulseOptions, type PulseProps, PulseStaleState, type PulseState, PulseSyncingState, PulseValidationError, createPulseValidator, registerPulseComponents, resolveTemplate, useCollection, useCollectionField, usePulse, usePulseCollections, useStreaming, useTemplateResolution };

package/dist/index.d.ts

@@ -230,4 +230,82 @@ declare class PulseValidationError extends Error {
     }[];
 }
 
-export { Pulse, PulseEmptyState, PulseErrorState, PulseIndicator, type PulseIndicatorProps, PulseLoadingState, type PulseMeta, type PulseOptions, type PulseProps, PulseStaleState, type PulseState, PulseSyncingState, PulseValidationError, createPulseValidator, usePulse, useStreaming };
+interface CollectionBinding {
+    collection: string;
+    endpoint: string;
+    slugField?: string;
+    refreshInterval?: number;
+    schema?: unknown;
+}
+interface CollectionData {
+    items: unknown[];
+    count: number;
+    meta: PulseMeta;
+    [key: string]: unknown;
+}
+interface PulseCollectionContextValue {
+    collections: Record<string, CollectionData>;
+    isLoading: boolean;
+    getCollection: (name: string) => CollectionData | null;
+    getField: (collection: string, field: string) => unknown;
+}
+declare function resolveTemplate(template: string, collections: Record<string, CollectionData>): unknown;
+declare function PulseCollectionProvider({ collections: collectionConfigs, children, fallback, }: {
+    collections: CollectionBinding[];
+    children: React.ReactNode;
+    fallback?: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function usePulseCollections(): PulseCollectionContextValue;
+declare function useCollection(collectionName: string): CollectionData | null;
+declare function useCollectionField(collectionName: string, field: string): unknown;
+declare function useTemplateResolution(): (template: string) => unknown;
+
+interface MetricCardPulseProps {
+    /** Collection name to bind to */
+    collection: string;
+    /** Field to display (supports {{ collection.field }} syntax) */
+    field: string;
+    /** Static label override */
+    label?: string;
+    /** Icon to show */
+    icon?: React.ReactNode;
+    /** Color for the card accent */
+    color?: string;
+    /** Trend direction: 'up' | 'down' | 'stable' */
+    trend?: 'up' | 'down' | 'stable';
+    /** Static trend value override */
+    trendValue?: string;
+    /** Aggregate function for array data: 'count' | 'sum' | 'avg' */
+    aggregate?: 'count' | 'sum' | 'avg';
+    /** Path within items to use for aggregation */
+    aggregateField?: string;
+}
+/**
+ * MetricCard with live data binding to collections
+ *
+ * Examples:
+ * ```yaml
+ * - type: metric_card_pulse
+ *   collection: equipment
+ *   field: items.length  # count of equipment
+ *   label: "Total Equipment"
+ *   icon: Truck
+ * ```
+ */
+declare function MetricCardPulse({ collection, field, label, icon, color, trend, trendValue, aggregate, aggregateField, }: MetricCardPulseProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Register Pulse collection binding components
+ *
+ * Call this AFTER registerDisplayComponents() in _app.tsx:
+ * ```ts
+ * import { registerDisplayComponents } from '@stackwright-pro/display-components';
+ * import { registerPulseComponents } from '@stackwright-pro/pulse';
+ *
+ * registerDisplayComponents();
+ * registerPulseComponents();
+ * ```
+ */
+declare function registerPulseComponents(): void;
+
+export { type CollectionBinding, MetricCardPulse, Pulse, type PulseCollectionContextValue, PulseCollectionProvider, PulseEmptyState, PulseErrorState, PulseIndicator, type PulseIndicatorProps, PulseLoadingState, type PulseMeta, type PulseOptions, type PulseProps, PulseStaleState, type PulseState, PulseSyncingState, PulseValidationError, createPulseValidator, registerPulseComponents, resolveTemplate, useCollection, useCollectionField, usePulse, usePulseCollections, useStreaming, useTemplateResolution };