@schandlergarcia/sf-web-components 1.9.69 → 1.9.70

package/.a4drules/skills/command-center-builder/SKILL.md

@@ -46,7 +46,7 @@ The component library (`@/components/library`) provides pre-built, themed, dark-
 | KPI / stat | `MetricCard` | `<div className="bg-white border ..."><h3>Total Spend</h3><span>$4,903</span></div>` |
 | List of items | `ListCard` | `<div className="bg-white ..."><div className="space-y-3">` with custom item rows |
 | Activity feed (display only) | `ActivityCard` or `FeedPanel` | `<div>` with hand-rolled interaction rows |
-| Activity feed (with per-item actions) | Custom markup inside `BaseCard` | `ActivityCard` (doesn't support per-item buttons) |
+| **Activity feed (with per-item actions like "Assign to Agent")** | **Custom markup inside `BaseCard`** | **`ActivityCard` (doesn't support per-item buttons — see Engine PRD Section 8a)** |
 | Data table | `TableCard` | `<table>` or custom grid of rows |
 | Stats panel | `WidgetCard` or `SectionCard` | `<div className="bg-white ... p-6">` with label/value pairs |
 | Custom interactive content (expand/collapse, inline details) | `WidgetCard` (sections accept arbitrary JSX) or `ListCard` (with `onItemClick` + `itemActions`) | Hand-rolled `<div>` card with custom expand/collapse logic |
@@ -104,7 +104,7 @@ No `<nav>`, header bar, tab bar, or content-swapping via `useState("activeTab")`
 
 - Dashboard page files: `src/pages/` (e.g. `EngineDashboard.tsx`, `FleetDashboard.tsx`) — **NOT** `src/components/pages/`
 - File format: `.tsx` (MUST be TypeScript) — this is a TypeScript project, all React components use `.tsx`, NEVER `.jsx`.
-- `CommandCenter.tsx` wraps with `AppThemeProvider` + `DataModeProvider` + `Toaster`. **Never recreate these providers in dashboard pages.**
+- `CommandCenter.tsx` wraps with `heroui-scope` div + `AppThemeProvider` + `DataModeProvider` + `Toast.Provider` from `@heroui/react`. **Never recreate these providers in dashboard pages.** When wiring a new dashboard, only change the import — preserve the `heroui-scope` wrapper and `Toast.Provider` exactly as-is. For toasts inside dashboards, use `toast` from `sonner` (not `addToast` from HeroUI).
 
 ### Wiring a new dashboard (REQUIRED STEPS)
 
@@ -125,22 +125,24 @@ export default function MyDashboard() {
 }
 ```
 
-**Step 2:** Update `CommandCenter.tsx` to import and render it:
+**Step 2:** Update `CommandCenter.tsx` to import and render it. Only change the import line — preserve `heroui-scope` and `Toast.Provider`:
 ```tsx
 // src/components/workspace/CommandCenter.tsx
 import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
 import DataModeProvider from "@/components/library/data/DataModeProvider";
-import { Toaster } from "sonner";
-import MyDashboard from "../../pages/MyDashboard";  // ← change this import
+import { Toast } from "@heroui/react";
+import MyDashboard from "../../pages/MyDashboard";  // ← change ONLY this import
 
 export default function CommandCenter() {
   return (
-    <AppThemeProvider initialMode="light">
-      <DataModeProvider initialMode="sample">
-        <MyDashboard />                   {/* ← change this */}
-        <Toaster position="bottom-right" />
-      </DataModeProvider>
-    </AppThemeProvider>
+    <div className="heroui-scope">                   {/* ← preserve this wrapper */}
+      <AppThemeProvider initialMode="light">
+        <DataModeProvider initialMode="sample">
+          <MyDashboard />                             {/* ← change this */}
+          <Toast.Provider placement="bottom end" />   {/* ← preserve this */}
+        </DataModeProvider>
+      </AppThemeProvider>
+    </div>
   );
 }
 ```
@@ -501,7 +503,8 @@ Instead, verify correctness by reviewing the code against the Pre-Completion Che
 - Using `template` prop on D3Chart — use `renderChart={D3ChartTemplates.lineChart}`
 - Passing D3Chart as children to ChartCard — use `chart={<D3Chart ... />}` prop
 - Adding `<nav>` or tab-swapping (`useState("activeTab")`) inside dashboards
-- Recreating providers — `CommandCenter.tsx` already provides them
+- Recreating providers — `CommandCenter.tsx` already provides them. Do not replace `Toast.Provider` with `Toaster` from sonner, and do not remove the `heroui-scope` div
+- Using `addToast` from `@heroui/react` — use `toast` / `toast.success` from `sonner` instead
 - Using `text-black`, `text-white`, `bg-black` — use slate scale
 - Hardcoded data without `useDataSource` — always support sample/live switching
 - `position: fixed` without `createPortal`

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.9.70] - 2026-04-02
+
+### Updated
+- **PRD (engine-command-center-prd.md)** - 5 edits for phasing clarity and toast API:
+  - Section 4 (Architecture): Added explicit rules to preserve `heroui-scope` wrapper and `Toast.Provider` in CommandCenter. Added `toast` from `sonner` as the correct toast API
+  - Section 6 (Header): Added "(Phase 4)" tag to "Powered by Agentforce" badge
+  - Section 8a (Escalations): Added "(Phase 4)" tag to "Assign to Agent" button, noted `toast.success` comes via `sonner`, added instruction to render button with empty `onClick` in Phase 2 and wire toast in Phase 4
+  - Section 10 (Signals): Changed `toast()` and `toast.success()` to include full call examples with "via sonner" annotation
+  - Section 13, Phase 3 prompt: Added file paths for queries and hook, code example showing how to wire `useEngineLiveData()` into `useDataSource({ sample: ..., live: live.xxx })`, clarified hook should match sample data shape
+
+- **Builder skill (SKILL.md)** - 3 edits for toast API and wiring:
+  - Wiring section: Changed description from Toaster to `heroui-scope` + `Toast.Provider` from `@heroui/react`. Added rule to use `toast` from `sonner` for dashboard toasts
+  - Wiring example (Step 2): Replaced sonner Toaster code with actual pattern: `heroui-scope` div, `Toast.Provider` from `@heroui/react`, with comments marking "preserve this" vs "change this"
+  - Component table: Bolded "per-item actions" row and added "see Engine PRD Section 8a" cross-reference
+  - Anti-patterns: Added two entries: (1) don't replace `Toast.Provider` with sonner's `Toaster` or remove `heroui-scope`, (2) don't use `addToast` from HeroUI — use `toast` from `sonner`
+
+**Context:** Clarified phasing tags for Phase 4 features (badge, agent buttons) and documented correct toast API pattern (HeroUI provider + sonner toast function).
+
 ## [1.9.69] - 2026-04-01
 
 ### Fixed

package/data/engine-command-center-prd.md

@@ -50,7 +50,8 @@ Use `brand-*` Tailwind classes for brand elements. Tailwind built-in colors (gre
 ## 4. Architecture
 
 - **Dashboard file:** `src/pages/EngineDashboard.tsx`
-- **Wiring:** `CommandCenter.tsx` imports and renders `EngineDashboard` inside the existing provider stack. Never recreate providers in the dashboard.
+- **Wiring:** `CommandCenter.tsx` imports and renders `EngineDashboard` inside the existing provider stack. Never recreate providers in the dashboard. When updating `CommandCenter.tsx`, only change the dashboard import line — preserve the `heroui-scope` wrapper div and `Toast.Provider` from `@heroui/react` exactly as-is.
+- **Toasts:** Import `toast` from `sonner` in dashboard pages. Use `toast.success("message")` for success toasts and `toast("message")` for informational ones. The `Toast.Provider` in CommandCenter handles rendering — do not add a second `Toaster` or replace the existing provider.
 - **Imports:** Components from `@/components/library`. Theme from `@/components/library/theme/AppThemeProvider`.
 
 ---
@@ -119,7 +120,7 @@ Compact `h-12` sticky header (`bg-slate-900 dark:bg-slate-950`). No ChatBar in t
 
 | Left | Right |
 |------|-------|
-| Engine logo (`GlobeAltIcon` in `bg-brand-600` square) + "ENGINE" wordmark + separator + "Travel Command Center" + "Powered by Agentforce" badge (`bg-brand-900/40 text-brand-400 rounded-full text-[10px]`) | Notification bell (badge count) + theme toggle (sun/moon) |
+| Engine logo (`GlobeAltIcon` in `bg-brand-600` square) + "ENGINE" wordmark + separator + "Travel Command Center" + "Powered by Agentforce" badge (Phase 4: `bg-brand-900/40 text-brand-400 rounded-full text-[10px]`) | Notification bell (badge count) + theme toggle (sun/moon) |
 
 ---
 
@@ -169,7 +170,7 @@ Custom inline panel in BaseCard. Do NOT use ActivityCard — this panel has per-
 Each escalation row:
 - Status icon: `CheckCircleIcon` (complete, green), `ArrowPathIcon` (working, brand), `ClockIcon` (pending, amber)
 - Title + subtitle + timestamp
-- **"Assign to Agent" button** on items where status is NOT `"complete"`: teal button (`bg-brand-600`) with `SparklesIcon` + "Assign to Agent" text. On click: `toast.success("Assigned to Eva")`
+- **"Assign to Agent" button** (Phase 4) on items where status is NOT `"complete"`: teal button (`bg-brand-600`) with `SparklesIcon` + "Assign to Agent" text. On click: `toast.success("Assigned to Eva")` via sonner. In Phase 2, render the button but leave the `onClick` empty — wire the toast in Phase 4.
 
 ```tsx
 <BaseCard>
@@ -292,8 +293,8 @@ Subtle indicators, not banners.
 |--------|----------|
 | "Powered by Agentforce" | Header, next to "Travel Command Center" (small rounded badge) |
 | "View in Salesforce" | Traveler expanded view (micro-link, muted text) |
-| "Salesforce updated" | After rebook/approve actions (`toast()`) |
-| "Assigned to Eva" | After "Assign to Agent" button click (`toast.success()`) |
+| "Salesforce updated" | After rebook/approve actions — `toast("Opening in Salesforce…")` via sonner |
+| "Assigned to Eva" | After "Assign to Agent" button click — `toast.success("Assigned to Eva")` via sonner |
 
 ---
 
@@ -328,7 +329,14 @@ Build in 4 incremental phases.
 
 ### Phase 3: Real Data Integration
 
-> Connect the dashboard to live Salesforce data using GraphQL. Read the sample data file to see which fields are needed, then build queries and hooks for each object. The UI should stay identical — just swap the data source.
+> Connect the dashboard to live Salesforce data using GraphQL. Read the sample data file to see which fields are needed, then build queries in `src/api/engine/queries.ts` and a hook in `src/hooks/useEngineLiveData.ts` for each object. The hook should return the same data shape as the sample data exports. Wire it into the dashboard by populating the `live` prop on each `useDataSource` call:
+>
+> ```tsx
+> const live = useEngineLiveData();
+> const markers = useDataSource({ sample: MAP_MARKERS, live: live.mapMarkers });
+> ```
+>
+> The UI should stay identical — only the data source changes.
 
 ### Phase 4: Agentforce Integration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.69",
+  "version": "1.9.70",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",