@schandlergarcia/sf-web-components 1.9.45 → 1.9.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,341 @@
1
+ # Improved Dashboard Build Process
2
+
3
+ ## 4-Phase Build Approach
4
+
5
+ Build dashboards in 4 distinct phases with clear separation of concerns:
6
+
7
+ ### Phase 1: Layout & Structure
8
+ **Goal:** Establish layout, spacing, and component placement
9
+ **Output:** Skeleton with placeholders, no real data or logic
10
+
11
+ ### Phase 2: Components & Sample Data
12
+ **Goal:** Build all UI components with realistic mock data
13
+ **Output:** Fully functional UI using hardcoded sample data
14
+
15
+ ### Phase 3: Real Data Integration
16
+ **Goal:** Replace sample data with live Salesforce data
17
+ **Output:** Dashboard connected to real data sources
18
+
19
+ ### Phase 4: Agentforce Integration
20
+ **Goal:** Add AI agent capabilities
21
+ **Output:** Eva agent integrated with chat interface
22
+
23
+ ---
24
+
25
+ ## Example: Engine Travel Command Center
26
+
27
+ ### Prompt 1 — Layout & Structure
28
+
29
+ > Load skills: command-center-builder, command-center-project, component-library, outer-app.
30
+ > Use `docs/engine-command-center-prd.md` as source of truth.
31
+ >
32
+ > **Phase 1: Layout Only**
33
+ >
34
+ > Scaffold the Engine Travel Command Center structure:
35
+ >
36
+ > 1. **Header Layout** - Compact dark header with:
37
+ > - Engine logo placeholder (gray box)
38
+ > - Wordmark placeholder
39
+ > - Theme toggle (functional)
40
+ > - Empty space for ChatBar (Phase 4)
41
+ >
42
+ > 2. **Hero Section** - Full-width map container:
43
+ > - Empty GeoMap component (no markers, no data)
44
+ > - Placeholder for KPI overlays (gray boxes with labels)
45
+ > - Placeholder for flight status strip (gray bar)
46
+ >
47
+ > 3. **Data Panels Grid** - Layout sections with empty cards:
48
+ > - Disruptions panel (left, wide)
49
+ > - Active travelers panel (right, narrow)
50
+ > - Activity feed + chart row
51
+ > - Bookings table section
52
+ > - Policy + spend chart row
53
+ >
54
+ > 4. **Theme Setup** - Update brand palette to Engine teal tokens (section 3 PRD)
55
+ >
56
+ > 5. **File Structure**:
57
+ > - Create `src/pages/EngineDashboard.tsx`
58
+ > - Wire into `CommandCenter.tsx`
59
+ > - Use placeholder cards: `<BaseCard><div className="h-48 bg-slate-100">Section Name</div></BaseCard>`
60
+ >
61
+ > **DO NOT:**
62
+ > - Add any real data or sample data
63
+ > - Build actual components beyond placeholders
64
+ > - Add data fetching logic
65
+ > - Add interactive features beyond theme toggle
66
+ >
67
+ > **Deliverable:** A skeleton dashboard with proper layout, spacing, and placeholder cards that shows the structure.
68
+
69
+ ---
70
+
71
+ ### Prompt 2 — Components & Sample Data
72
+
73
+ > Load skills: command-center-builder, command-center-project, component-library.
74
+ > Refer to `docs/engine-command-center-prd.md` sections 7, 8, and 12.
75
+ >
76
+ > **Phase 2: Build All Components with Sample Data**
77
+ >
78
+ > Replace all placeholders with fully functional components using hardcoded sample data:
79
+ >
80
+ > 1. **Create Sample Data File** - `src/data/engine-sample-data.ts`:
81
+ > - Travelers (10 active travelers with names, flights, hotels)
82
+ > - Flights (8 active flights with routes, status, progress %)
83
+ > - Disruptions (3 weather events, 2 delays, 1 cancellation)
84
+ > - Bookings (20 bookings with all fields)
85
+ > - Policy items (5 compliance items with status)
86
+ > - Eva actions (15 recent actions)
87
+ > - Spend history (12 months of data)
88
+ > - Destination stats (top 10 cities)
89
+ >
90
+ > 2. **Populate Map** - Wire sample data into GeoMap:
91
+ > - Show markers at origin/destination cities
92
+ > - Draw flight arcs with animated progress dots
93
+ > - Add weather overlays for disrupted areas
94
+ > - Add 4 glass KPI overlays (flights, travelers, disruptions, bookings count)
95
+ > - Add flight status strip with colored status chips
96
+ >
97
+ > 3. **Build Disruptions Panel**:
98
+ > - Use ListCard with disruption items
99
+ > - Show severity indicators (red/yellow/blue)
100
+ > - Show affected travelers
101
+ > - Show Eva's actions
102
+ >
103
+ > 4. **Build Active Travelers Panel**:
104
+ > - Use ListCard with expandable traveler cards
105
+ > - Click to expand and show flight, hotel, return date
106
+ > - Use Avatar for traveler photos
107
+ > - Show status chips
108
+ >
109
+ > 5. **Build Activity Feed + Chart**:
110
+ > - Use FeedPanel for Eva activities
111
+ > - Use ChartCard with bar chart of travelers by destination
112
+ >
113
+ > 6. **Build Bookings Table**:
114
+ > - Use TableCard with search, sort, pagination
115
+ > - Show all booking fields from section 12
116
+ > - Add status chips
117
+ >
118
+ > 7. **Build Policy + Spend Charts**:
119
+ > - Use StatusCard for policy compliance
120
+ > - Use ChartCard with line chart of monthly spend
121
+ >
122
+ > 8. **Add Interactivity**:
123
+ > - Click travelers to expand/collapse
124
+ > - Search/filter bookings table
125
+ > - Sort table columns
126
+ > - Hover map markers for tooltips
127
+ >
128
+ > **DO NOT:**
129
+ > - Connect to Salesforce data (use hardcoded data only)
130
+ > - Add data fetching hooks
131
+ > - Add GraphQL queries
132
+ > - Add Agentforce/Eva chat
133
+ >
134
+ > **Deliverable:** A fully functional dashboard with all components working using sample data. Everything should look and feel complete, just not connected to live data yet.
135
+
136
+ ---
137
+
138
+ ### Prompt 3 — Real Data Integration
139
+
140
+ > Load skills: command-center-builder, command-center-project, component-library, using-salesforce-data.
141
+ > Refer to `docs/engine-command-center-prd.md` sections 11 and 13.
142
+ >
143
+ > **Phase 3: Connect to Salesforce Data**
144
+ >
145
+ > Replace sample data with live Salesforce data:
146
+ >
147
+ > 1. **Create Data Hooks** - `src/hooks/`:
148
+ > - `useFlights.ts` - Fetch active flights from Flight__c
149
+ > - `useTravelers.ts` - Fetch travelers from Contact with flight relationships
150
+ > - `useDisruptions.ts` - Fetch disruption cases from Case
151
+ > - `useBookings.ts` - Fetch bookings from Booking__c
152
+ > - `usePolicyItems.ts` - Fetch policy compliance from Policy__c
153
+ > - `useEvaActions.ts` - Fetch Eva activity from Eva_Action__c
154
+ > - `useSpendData.ts` - Fetch spend trends from aggregate query
155
+ >
156
+ > 2. **GraphQL Queries** - For each hook, write GraphQL:
157
+ > - Use @optional on all fields (FLS resilience)
158
+ > - Include all relationships needed
159
+ > - Add proper filters (Active__c = true, etc.)
160
+ > - Use proper Salesforce field names from section 13
161
+ >
162
+ > 3. **Replace Sample Data** - In EngineDashboard.tsx:
163
+ > - Replace hardcoded arrays with hook calls
164
+ > - Add loading states with CardSkeleton
165
+ > - Add error states with EmptyState
166
+ > - Add refresh functionality
167
+ >
168
+ > 4. **Data Transformations** - Create `src/utils/engine-data-transforms.ts`:
169
+ > - Transform Salesforce records to map data format
170
+ > - Calculate KPI values from live data
171
+ > - Aggregate data for charts
172
+ > - Format dates, currencies, percentages
173
+ >
174
+ > 5. **Real-time Updates** - Add DataModeToggle:
175
+ > - Toggle between "sample" (Phase 2 data) and "live" (Salesforce data)
176
+ > - Store preference in localStorage
177
+ > - Show "Last synced" timestamp for live mode
178
+ >
179
+ > 6. **Error Handling**:
180
+ > - Network errors → Show retry button
181
+ > - No data → Show EmptyState with action
182
+ > - Partial data → Show what's available with warning
183
+ >
184
+ > **DO NOT:**
185
+ > - Add Agentforce/Eva chat yet
186
+ > - Add complex AI features
187
+ > - Modify component UI (should look same as Phase 2)
188
+ >
189
+ > **Deliverable:** Dashboard connected to live Salesforce data with loading states, error handling, and ability to toggle between sample/live data for testing.
190
+
191
+ ---
192
+
193
+ ### Prompt 4 — Agentforce Integration
194
+
195
+ > Load skills: command-center-builder, command-center-project, component-library, managing-agentforce-conversation-client.
196
+ > Refer to `docs/engine-command-center-prd.md` sections 9 and 10.
197
+ >
198
+ > **Phase 4: Add Eva Agent**
199
+ >
200
+ > Integrate Agentforce Eva agent:
201
+ >
202
+ > 1. **Add ChatBar to Header**:
203
+ > - Import ChatBar from @/components/library
204
+ > - Position in header (right side, before theme toggle)
205
+ > - Add keyboard shortcut (Cmd+K / Ctrl+K)
206
+ > - Add starter suggestions:
207
+ > - "Which travelers are affected by disruptions?"
208
+ > - "Show me all delayed flights"
209
+ > - "What's Eva doing right now?"
210
+ > - "Summarize today's travel status"
211
+ >
212
+ > 2. **Configure Eva Agent**:
213
+ > - Use Agentforce Eva agent ID from PRD section 9
214
+ > - Configure context: current user, visible data, dashboard state
215
+ > - Add tool calls for dashboard actions:
216
+ > - View traveler details
217
+ > - Filter bookings
218
+ > - Export data
219
+ > - Refresh data
220
+ >
221
+ > 3. **Add Salesforce Signals**:
222
+ > - Header: "Powered by Salesforce Data Cloud" badge
223
+ > - Traveler cards: "View in Salesforce" links → open Contact record
224
+ > - Booking rows: "View in Salesforce" links → open Booking__c record
225
+ > - Success toasts on actions: "Updated by Eva" with undo option
226
+ > - Live sync indicator with timestamp
227
+ >
228
+ > 4. **Eva Integration Points**:
229
+ > - ChatBar can filter visible data
230
+ > - ChatBar can expand specific travelers
231
+ > - ChatBar can open specific bookings
232
+ > - ChatBar can trigger refreshes
233
+ > - ChatBar shows contextual suggestions based on current view
234
+ >
235
+ > 5. **Testing Mode**:
236
+ > - If no Eva agent configured, show mock responses
237
+ > - Add "Configure Eva" EmptyState in ChatBar
238
+ > - Link to Agentforce setup docs
239
+ >
240
+ > **Deliverable:** Fully functional dashboard with Eva agent integrated, able to answer questions about travel data and perform dashboard actions.
241
+
242
+ ---
243
+
244
+ ## Why This Works
245
+
246
+ ### Clear Phases
247
+ Each phase has a single focus:
248
+ 1. Structure → Can review layout before building components
249
+ 2. Components → Can test UX/interactions before data complexity
250
+ 3. Data → Can focus on data fetching/transformation without UI changes
251
+ 4. Agent → Can add AI on top of working dashboard
252
+
253
+ ### Easy Testing
254
+ - Phase 1: Review layout, spacing, branding
255
+ - Phase 2: Test all interactions, edge cases with known data
256
+ - Phase 3: Test loading states, errors, real data shapes
257
+ - Phase 4: Test agent responses, tool calls
258
+
259
+ ### Easy Debugging
260
+ - UI issues? → Phase 2
261
+ - Data issues? → Phase 3
262
+ - Agent issues? → Phase 4
263
+
264
+ ### Easy Iterations
265
+ - Don't like layout? → Go back to Phase 1
266
+ - Component not working? → Fix in Phase 2 with sample data
267
+ - Data mapping wrong? → Fix Phase 3 transforms
268
+ - Agent not helpful? → Improve Phase 4 prompts
269
+
270
+ ### Can Stop Early
271
+ - Need just the UI mockup? → Stop after Phase 2
272
+ - Don't have Salesforce yet? → Stop after Phase 2
273
+ - Don't need AI? → Stop after Phase 3
274
+
275
+ ---
276
+
277
+ ## Phase Checklist Template
278
+
279
+ ### Phase 1: Layout ✓
280
+ - [ ] Header structure
281
+ - [ ] Hero section containers
282
+ - [ ] Data panel grid
283
+ - [ ] Placeholder cards in place
284
+ - [ ] Theme/branding applied
285
+ - [ ] Proper spacing and responsive layout
286
+
287
+ ### Phase 2: Components ✓
288
+ - [ ] Sample data file created
289
+ - [ ] All components built
290
+ - [ ] All interactions working
291
+ - [ ] All visualizations working
292
+ - [ ] Charts rendering with sample data
293
+ - [ ] Table search/sort/pagination working
294
+ - [ ] Dashboard looks and feels complete
295
+
296
+ ### Phase 3: Data ✓
297
+ - [ ] All data hooks created
298
+ - [ ] All GraphQL queries working
299
+ - [ ] Loading states added
300
+ - [ ] Error states handled
301
+ - [ ] Data transformations working
302
+ - [ ] Live/sample toggle working
303
+ - [ ] Real data rendering correctly
304
+
305
+ ### Phase 4: Agent ✓
306
+ - [ ] ChatBar in header
307
+ - [ ] Eva agent configured
308
+ - [ ] Starter suggestions working
309
+ - [ ] Agent can answer questions
310
+ - [ ] Tool calls working
311
+ - [ ] Salesforce signals added
312
+ - [ ] Links to Salesforce records working
313
+
314
+ ---
315
+
316
+ ## Benefits Over Original Approach
317
+
318
+ ### Original Approach Issues:
319
+ - Mixed layout + components + data in early prompts
320
+ - Hard to debug what phase an issue is from
321
+ - No clear stopping point
322
+ - Can't test UI without data
323
+ - Can't review structure before building
324
+
325
+ ### New Approach Benefits:
326
+ - Clear separation of concerns
327
+ - Each phase builds on previous
328
+ - Easy to identify issue source
329
+ - Can demo/test after each phase
330
+ - Can iterate on each phase independently
331
+ - Stakeholders can provide feedback earlier
332
+
333
+ ---
334
+
335
+ ## Notes
336
+
337
+ - **Always use sample data mode in Phase 2** - DataModeProvider should default to "sample"
338
+ - **Keep Phase 2 data file** - Useful for testing and demos
339
+ - **Test Phase 3 with sample toggle** - Easy to compare live vs sample
340
+ - **Phase 4 is optional** - Many dashboards don't need AI
341
+ - **Can split Phase 2** - If many components, do 2a (map/KPIs) and 2b (panels/tables)
package/CHANGELOG.md CHANGED
@@ -73,6 +73,66 @@ Between versions 1.9.29 and 1.9.42, a critical inconsistency existed that broke
73
73
 
74
74
  ---
75
75
 
76
+ ## [1.9.47] - 2026-04-01
77
+
78
+ ### Fixed
79
+ - **scripts/reset-command-center.sh** - Now removes ALL custom pages, not just files matching `*Dashboard*` pattern
80
+ - Issue: `EngineCommandCenter.tsx` wasn't removed because it doesn't match `*Dashboard*` pattern
81
+ - Cause: Script only looked for `*Dashboard*.jsx` and `*Dashboard*.tsx` files
82
+ - Fix: Changed logic to remove all `.jsx` and `.tsx` files in `src/pages/` except template files
83
+ - Template files (kept): `Home.tsx`, `Search.tsx`, `NotFound.tsx`, `BlankDashboard.tsx`
84
+ - Now removes: `EngineCommandCenter.tsx`, `MyDashboard.tsx`, `CustomPage.tsx`, etc.
85
+
86
+ ### Changed
87
+ - Reset script message updated from "Removing custom dashboards..." to "Removing custom pages..." to better reflect behavior
88
+ - Added explicit keep-list of template files for clarity
89
+
90
+ ### Technical Details
91
+ Previous pattern:
92
+ ```bash
93
+ for f in src/pages/*Dashboard*.jsx src/pages/*Dashboard*.tsx; do
94
+ ```
95
+
96
+ New approach:
97
+ ```bash
98
+ KEEP_FILES=("Home.tsx" "Search.tsx" "NotFound.tsx" "BlankDashboard.tsx")
99
+ # Remove all .jsx/.tsx except templates
100
+ ```
101
+
102
+ ---
103
+
104
+ ## [1.9.46] - 2026-04-01
105
+
106
+ ### Added
107
+ - **.a4drules/skills/command-center-builder/improved-build-process.md** - New 4-phase build methodology
108
+ - **Phase 1: Layout & Structure** - Skeleton with placeholders only
109
+ - **Phase 2: Components & Sample Data** - Fully functional UI with mock data
110
+ - **Phase 3: Real Data Integration** - Connect to live Salesforce data
111
+ - **Phase 4: Agentforce Integration** - Add Eva agent capabilities
112
+
113
+ ### Benefits of New Approach
114
+ - **Clear separation of concerns** - Each phase has single focus
115
+ - **Easy testing** - Can test each phase independently
116
+ - **Easy debugging** - Know which phase an issue is from
117
+ - **Can stop early** - Don't need all 4 phases for every project
118
+ - **Better feedback loop** - Stakeholders can review after each phase
119
+ - **Easier iterations** - Can go back and fix specific phase
120
+
121
+ ### Documentation
122
+ - Complete prompts for all 4 phases with Engine Travel example
123
+ - Phase checklists for tracking progress
124
+ - Clear DO NOT sections to prevent mixing concerns
125
+ - Comparison with original approach showing benefits
126
+
127
+ ### Purpose
128
+ Provides a structured, incremental approach to building command center dashboards instead of mixing layout, components, data, and AI in early phases. Makes it easier to:
129
+ - Review structure before building components
130
+ - Test UI/UX before data complexity
131
+ - Add data without changing UI
132
+ - Add AI on top of working dashboard
133
+
134
+ ---
135
+
76
136
  ## [1.9.45] - 2026-04-01
77
137
 
78
138
  ### Fixed
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@schandlergarcia/sf-web-components",
3
- "version": "1.9.45",
3
+ "version": "1.9.47",
4
4
  "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -34,24 +34,42 @@ echo "║ Reset App → Baseline State ║"
34
34
  echo "╚════════════════════════════════════════════════╝"
35
35
  echo ""
36
36
 
37
- # ── 1. Remove custom dashboard pages (keep library & workspace) ─────────────
37
+ # ── 1. Remove custom dashboard/page files (keep templates) ─────────────────
38
38
 
39
- echo "→ Removing custom dashboards…"
39
+ echo "→ Removing custom pages…"
40
+
41
+ # List of template files that should NOT be removed
42
+ KEEP_FILES=("Home.tsx" "Search.tsx" "NotFound.tsx" "BlankDashboard.tsx")
40
43
 
41
44
  removed=0
42
- for f in src/pages/*Dashboard*.jsx src/pages/*Dashboard*.tsx; do
43
- if [ -f "$f" ]; then
44
- # Don't remove BlankDashboard.tsx (it's the template)
45
- if [[ "$(basename "$f")" != "BlankDashboard.tsx" ]]; then
46
- rm "$f"
47
- echo " ✓ Removed $(basename "$f")"
48
- removed=$((removed + 1))
45
+
46
+ # Remove all .jsx and .tsx files in src/pages/ except templates
47
+ if [ -d "src/pages" ]; then
48
+ for f in src/pages/*.jsx src/pages/*.tsx; do
49
+ if [ -f "$f" ]; then
50
+ filename="$(basename "$f")"
51
+
52
+ # Check if this file should be kept
53
+ should_keep=false
54
+ for keep in "${KEEP_FILES[@]}"; do
55
+ if [[ "$filename" == "$keep" ]]; then
56
+ should_keep=true
57
+ break
58
+ fi
59
+ done
60
+
61
+ # Remove if not in keep list
62
+ if [ "$should_keep" = false ]; then
63
+ rm "$f"
64
+ echo " ✓ Removed $(basename "$f")"
65
+ removed=$((removed + 1))
66
+ fi
49
67
  fi
50
- fi
51
- done
68
+ done
69
+ fi
52
70
 
53
71
  if [ "$removed" -eq 0 ]; then
54
- echo " (no custom dashboards found)"
72
+ echo " (no custom pages found)"
55
73
  fi
56
74
  echo ""
57
75