@schandlergarcia/sf-web-components 1.9.77 → 1.9.78

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.
@@ -2,6 +2,16 @@
2
2
 
3
3
  The dashboard is built in **3 phases**, one per user prompt. Each phase adds a layer. Do NOT build ahead — only build what the current phase asks for.
4
4
 
5
+ ## General Rules for All Phases
6
+
7
+ 1. **Phase 1 writes new files. Phases 2 and 3 make surgical edits.** Phase 2 and 3 should NEVER rewrite `EngineDashboard.tsx` from scratch — use targeted edits (add imports, update specific lines, insert JSX blocks). Rewriting the entire file risks losing Phase 1 work and takes 60+ seconds vs seconds per edit.
8
+
9
+ 2. **Don't read files you don't need.** The patterns for `useDataSource`, `DataModeProvider`, `DataModeToggle`, and library components are documented in this skill. Only read files that contain project-specific code you need to understand (e.g., the dashboard you're editing, the live data file for its shape).
10
+
11
+ 3. **Don't run `npm run build` during the build.** Vite handles JSX/TSX regardless of TypeScript errors. Pre-existing TS7016 errors are normal.
12
+
13
+ 4. **STOP and ASK before creating Salesforce metadata.** When the build guide says "suggest" a custom field, platform event, or Apex class — you must present the suggestion to the user and WAIT for confirmation. Do NOT create the file until the user says yes. This is a scripted demo moment.
14
+
5
15
  ---
6
16
 
7
17
  ## Phase 1 — Build the Dashboard (sample data only)
@@ -35,52 +45,119 @@ The dashboard is built in **3 phases**, one per user prompt. Each phase adds a l
35
45
 
36
46
  ## Phase 2 — Connect to Live Data
37
47
 
38
- **What to build:**
39
- - Import `useEngineLiveData` from `src/hooks/useEngineLiveData.ts`
40
- - Wire `live` prop on every `useDataSource` call:
41
- ```tsx
42
- const live = useEngineLiveData();
43
- const markers = useDataSource({ sample: MAP_MARKERS, live: live.mapMarkers });
44
- const arcs = useDataSource({ sample: MAP_ARCS, live: live.mapArcs });
45
- ```
46
- - Update KPI overlays to use active metrics:
47
- ```tsx
48
- const activeMetrics = live.loading ? METRICS : live.metrics;
49
- ```
50
-
51
- **What to do after wiring:**
52
- - Proactively suggest creating `Flight__c.Weather_Impact__c` custom field
53
- - If confirmed, create SFDX XML from PRD section 14a and deploy
48
+ **How to work:** Make surgical edits to the existing `EngineDashboard.tsx`. Do NOT rewrite the file.
49
+
50
+ **Files to read first (only these):**
51
+ 1. `src/pages/EngineDashboard.tsx` — the Phase 1 dashboard you're editing
52
+ 2. `src/data/engine-live-data.js` or `src/hooks/useEngineLiveData.ts` — to see the live data shape
53
+
54
+ **Do NOT read:** `useDataSource.js`, `DataModeProvider.jsx`, or any library component source. The patterns are right here:
55
+
56
+ **Edits to make (in order):**
57
+
58
+ 1. **Add import** at the top of EngineDashboard.tsx:
59
+ ```tsx
60
+ import useEngineLiveData from "@/hooks/useEngineLiveData";
61
+ ```
62
+
63
+ 2. **Add hook call** inside the component, near the top:
64
+ ```tsx
65
+ const live = useEngineLiveData();
66
+ ```
67
+
68
+ 3. **Update every `useDataSource` call** to pass live data:
69
+ ```tsx
70
+ // Before (Phase 1):
71
+ const markers = useDataSource({ sample: MAP_MARKERS, live: [] });
72
+ // After (Phase 2):
73
+ const markers = useDataSource({ sample: MAP_MARKERS, live: live.mapMarkers });
74
+ ```
75
+ Do this for markers, arcs, travelers, flights, escalations, disruptions, spendData — whatever the dashboard uses.
76
+
77
+ 4. **Update KPI derivations** to react to active data:
78
+ ```tsx
79
+ const activeMetrics = live.loading ? SAMPLE_METRICS : live.metrics;
80
+ ```
81
+ Then use `activeMetrics` in KPI overlays instead of hardcoded sample constants.
82
+
83
+ That's 4 targeted edits. Not a full rewrite.
84
+
85
+ **No UI toggle.** Data mode (sample vs live) is controlled by `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts`, not by a visible toggle in the dashboard. Do NOT add `DataModeToggle` to the UI.
86
+
87
+ **After wiring — STOP and suggest (do not create yet):**
88
+
89
+ Say something like: *"I notice Flight__c doesn't have a field to track weather impact on individual flights. A Weather_Impact__c picklist would help the dashboard filter storm-affected flights. Want me to create it?"*
90
+
91
+ Only create `Flight__c.Weather_Impact__c` (PRD section 14a) AFTER the user confirms.
54
92
 
55
93
  **What NOT to build:**
56
94
  - No ChatBar or Eva — that's Phase 3
57
95
  - No platform events or Apex — that's Phase 3
96
+ - Do NOT rewrite EngineDashboard.tsx from scratch
97
+ - Do NOT read library component source files
98
+ - Do NOT run `npm run build` between edits
58
99
 
59
100
  ---
60
101
 
61
102
  ## Phase 3 — Add Agentforce
62
103
 
63
- **What to build:**
64
- - `ChatBar` between the map and data panels:
65
- ```tsx
66
- <div className="px-4 pt-4">
67
- <ChatBar
68
- title="Eva"
69
- placeholder="Ask Eva anything about travelers, bookings, policy, or spend…"
70
- suggestions={CHAT_SUGGESTIONS}
71
- onSend={handleChat}
72
- />
73
- </div>
74
- ```
75
- - Suggestions: weather warning, rebooking policy, notify travelers, create support case
76
- - `handleChat` mock response at module scope
77
- - `AgentforceConversationClient` with `agentId="0Xxa5000000relhCAA"` and `agentLabel="Eva"`
78
-
79
- **What to do after adding Eva:**
80
- - Proactively suggest creating `Travel_Disruption_Alert__e` platform event
81
- - If confirmed, create SFDX XML from PRD section 14b and deploy
82
- - Then suggest creating `TravelDisruptionEventService` Apex class
83
- - If confirmed, create from PRD section 14c and deploy
104
+ **How to work:** Make surgical edits to the existing `EngineDashboard.tsx`. Do NOT rewrite the file.
105
+
106
+ **Files to read first (only these):**
107
+ 1. `src/pages/EngineDashboard.tsx` — the current dashboard
108
+
109
+ **Edits to make (in order):**
110
+
111
+ 1. **Add ChatBar import** (if not already imported from the barrel):
112
+ ```tsx
113
+ import { ChatBar } from "@/components/library";
114
+ ```
115
+
116
+ 2. **Add chat suggestions constant** at module scope:
117
+ ```tsx
118
+ const CHAT_SUGGESTIONS = [
119
+ "Are any travelers affected by the Denver weather?",
120
+ "What's our rebooking policy for weather delays?",
121
+ "Notify all travelers on disrupted flights",
122
+ "Create a support case for the SFO→JFK cancellation",
123
+ ];
124
+ ```
125
+
126
+ 3. **Add handleChat function** at module scope:
127
+ ```tsx
128
+ const handleChat = (msg: string) => ({ text: `Looking into: "${msg}"…` });
129
+ ```
130
+
131
+ 4. **Insert ChatBar JSX** between the map section and the data panels:
132
+ ```tsx
133
+ <div className="px-4 pt-4">
134
+ <ChatBar
135
+ title="Eva"
136
+ placeholder="Ask Eva anything about travelers, bookings, policy, or spend…"
137
+ suggestions={CHAT_SUGGESTIONS}
138
+ onSend={handleChat}
139
+ />
140
+ </div>
141
+ ```
142
+
143
+ 5. **Add AgentforceConversationClient** with `agentId="0Xxa5000000relhCAA"` and `agentLabel="Eva"`
144
+
145
+ **After adding Eva — STOP and suggest (do not create yet):**
146
+
147
+ Say: *"The dashboard tracks disruptions in real time. I can create a Travel_Disruption_Alert__e platform event so disruption data can be published to the Salesforce event bus. Want me to set it up?"*
148
+
149
+ Only create the platform event (PRD section 14b) AFTER the user confirms.
150
+
151
+ **After the platform event — STOP and suggest again:**
152
+
153
+ Say: *"Now I'll write an Apex service class to publish disruption records to that event bus. Want me to create it?"*
154
+
155
+ Only create `TravelDisruptionEventService` (PRD section 14c) AFTER the user confirms.
156
+
157
+ **What NOT to build without asking:**
158
+ - Do NOT create platform events or Apex classes without user confirmation
159
+ - Do NOT rewrite EngineDashboard.tsx from scratch
160
+ - Do NOT read library component source files
84
161
 
85
162
  ---
86
163
 
@@ -88,11 +165,13 @@ The dashboard is built in **3 phases**, one per user prompt. Each phase adds a l
88
165
 
89
166
  | | Phase 1 | Phase 2 | Phase 3 |
90
167
  |---|---------|---------|---------|
91
- | Dashboard layout & panels | Build | — | — |
168
+ | Dashboard layout & panels | Write new file | — | — |
92
169
  | Sample data | Wire | — | — |
93
- | Live data | Skip | Wire | — |
94
- | Custom field metadata | Skip | Suggest | — |
95
- | ChatBar (Eva) | Skip | Skip | Build |
96
- | AgentforceConversationClient | Skip | Skip | Build |
97
- | Platform event | Skip | Skip | Suggest |
98
- | Apex service | Skip | Skip | Suggest |
170
+ | Live data | Skip | Surgical edits | — |
171
+ | Custom field metadata | Skip | Suggest → wait | — |
172
+ | ChatBar (Eva) | Skip | Skip | Surgical edit |
173
+ | AgentforceConversationClient | Skip | Skip | Surgical edit |
174
+ | Platform event | Skip | Skip | Suggest → wait |
175
+ | Apex service | Skip | Skip | Suggest → wait |
176
+
177
+ **Note:** Data mode (sample vs live) is controlled by `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts`. There is no UI toggle — do NOT add `DataModeToggle` to the dashboard.
@@ -1,18 +1,28 @@
1
1
  # Efficient Build Process
2
2
 
3
+ ## The #1 Rule: Phase 1 Writes, Phases 2-3 Edit
4
+
5
+ - **Phase 1** creates `EngineDashboard.tsx` from scratch (Write). Also writes CommandCenter.tsx, Home.tsx, edits routes.tsx.
6
+ - **Phase 2** makes ~5 surgical edits to the existing dashboard (StrReplace / targeted edits). Never rewrites the file.
7
+ - **Phase 3** makes ~4 surgical edits to the existing dashboard (StrReplace / targeted edits). Never rewrites the file.
8
+
9
+ Rewriting a 400+ line file from scratch takes 60 seconds, risks losing prior work, and can introduce regressions. Surgical edits take seconds each and preserve everything.
10
+
3
11
  ## Speed Rules
4
12
 
5
13
  1. **Load only 2 files before building:** the PRD and this skill (command-center-builder). Do NOT load component-library, command-center-project, or outer-app skills — they add latency and aren't needed for the initial build.
6
14
 
7
- 2. **Do NOT read component source files.** The props for every component (GeoMap, BaseCard, Avatar, ChartCard, D3Chart, etc.) are documented in this skill and the PRD. Reading `GeoMap.jsx`, `BaseCard.jsx`, etc. wastes time and produces no new information.
15
+ 2. **Do NOT read component source files.** The props for every component (GeoMap, BaseCard, Avatar, ChartCard, D3Chart, etc.) are documented in this skill and the PRD. Reading `GeoMap.jsx`, `BaseCard.jsx`, `useDataSource.js`, `DataModeProvider.jsx`, etc. wastes time and produces no new information.
8
16
 
9
- 3. **Write the dashboard in one pass.** Plan the full file before writing. Do not write a partial dashboard and iterate — write the complete component with all imports, data, and JSX in a single Write call.
17
+ 3. **Phase 1: Write the dashboard in one pass.** Plan the full file before writing. Do not write a partial dashboard and iterate — write the complete component with all imports, data, and JSX in a single Write call. Then write all 4 files without stopping.
10
18
 
11
- 4. **Write all 4 files without stopping.** After the dashboard, immediately write CommandCenter.tsx, Home.tsx, and edit routes.tsx. Do not run build commands between files.
19
+ 4. **Phases 2-3: Make targeted edits only.** Read the existing dashboard, then make specific edits (add imports, update lines, insert JSX blocks). Do NOT use Write to replace the entire file.
12
20
 
13
21
  5. **Do NOT run `npm run build`, `npm run dev`, `tsc`, or `npm run validate:dashboard` during the build.** These waste time. The Vite build handles JSX/TSX regardless of TypeScript errors, and pre-existing TS7016 errors (from untyped .jsx library files) are normal.
14
22
 
15
- ## File Write Order
23
+ 6. **STOP and ASK before creating metadata.** Custom fields, platform events, and Apex classes are scripted demo moments. Suggest them, wait for "yes," then create. Never just create them.
24
+
25
+ ## Phase 1 File Write Order
16
26
 
17
27
  ```
18
28
  1. src/pages/EngineDashboard.tsx ← full dashboard, one pass
@@ -21,12 +31,37 @@
21
31
  4. src/routes.tsx ← edit index route label to "Dashboard"
22
32
  ```
23
33
 
34
+ ## Phase 2 Edit Order
35
+
36
+ ```
37
+ 1. Add useEngineLiveData import
38
+ 2. Add const live = useEngineLiveData() hook call
39
+ 3. Update each useDataSource({ sample, live: [] }) → live: live.xxx
40
+ 4. Update KPI derivations to use activeMetrics
41
+ → STOP — suggest Weather_Impact__c, wait for confirmation
42
+ ```
43
+
44
+ No DataModeToggle in the UI — data mode is controlled by `dataStrategy.ts` on the backend.
45
+
46
+ ## Phase 3 Edit Order
47
+
48
+ ```
49
+ 1. Add ChatBar import (if not in barrel import)
50
+ 2. Add CHAT_SUGGESTIONS constant + handleChat function
51
+ 3. Insert <ChatBar /> JSX between map and data panels
52
+ 4. Add AgentforceConversationClient
53
+ → STOP — suggest platform event, wait for confirmation
54
+ → STOP — suggest Apex class, wait for confirmation
55
+ ```
56
+
24
57
  ## Common Time Wasters
25
58
 
26
59
  | Waste | Fix |
27
60
  |-------|-----|
28
61
  | Loading 4-5 skills before starting | Load only command-center-builder + PRD |
29
- | Reading GeoMap.jsx, Avatar.jsx, BaseCard.jsx source | Props are in this skill — trust the docs |
30
- | Running `npm run build` after writing | Don't Vite handles it, TS errors are pre-existing |
62
+ | Reading GeoMap.jsx, Avatar.jsx, useDataSource.js source | Props/patterns are in this skill — trust the docs |
63
+ | Rewriting EngineDashboard.tsx from scratch in Phase 2/3 | Make 5 surgical edits, not a 454-line rewrite |
64
+ | Running `npm run build` between edits | Don't — Vite handles it, TS errors are pre-existing |
31
65
  | Fixing imports iteratively (wrong icon names, wrong exports) | Check the PRD and this skill for exact import names before writing |
32
66
  | Writing Home.tsx with Account Search content | REPLACE it with the 3-line CommandCenter wrapper (see WIRING section) |
67
+ | Creating metadata without asking | STOP, suggest, wait for "yes" — it's a scripted demo moment |
package/CHANGELOG.md CHANGED
@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.9.78] - 2026-04-04
9
+
10
+ ### Fixed
11
+ - **Phase 2 rewrites entire dashboard** — Agent was writing a brand new 454-line file instead of making ~4 surgical edits. Build guide and PRD now enforce "Phase 1 writes, Phases 2-3 edit" with explicit edit lists
12
+ - **Agent creates metadata without asking** — Agent was creating custom fields/platform events/Apex without waiting for user confirmation. All phases now say "STOP and suggest — wait for yes" with scripted dialogue
13
+ - **Agent reads 6+ files before starting Phase 2** — Now limited to reading only the dashboard and live data file; library component source files are explicitly prohibited
14
+ - **DataModeToggle in the UI** — Removed from all Phase 2 instructions. Data mode is controlled by `ENABLE_SAMPLE_DATA_CACHE` in `dataStrategy.ts`, not a visible toggle
15
+
16
+ ### Changed
17
+ - **Build guide (`getting-started.md`)** — Full rewrite with surgical edit instructions for Phases 2-3, explicit "files to read" and "do NOT read" lists, "STOP and ASK" enforcement for metadata creation
18
+ - **Efficient build process (`improved-build-process.md`)** — Added "#1 Rule: Phase 1 Writes, Phases 2-3 Edit", phase-specific edit orders, metadata ask-before-creating rule
19
+ - **PRD Prompt 2** — Added "What the agent must NOT do" section, removed DataModeToggle, reworded user prompt to remove "toggle" language
20
+ - **PRD Prompt 3** — Added "What the agent must NOT do" section, enforced stop-and-ask pattern for each metadata creation
21
+
8
22
  ## [1.9.77] - 2026-04-04
9
23
 
10
24
  ### Added
@@ -348,18 +348,28 @@ Build incrementally in 3 prompts. Each prompt builds on the previous result. The
348
348
 
349
349
  ### Prompt 2 — Connect to Salesforce Data
350
350
 
351
- > Now let's connect this to real data. There's a second dataset with different travelers and metrics — hook that up as the "live" data source so when someone toggles from sample to live mode, everything refreshes with the new data. After that, see if there are any data model improvements we should make for tracking weather disruptions.
351
+ > Now let's connect this to real data. There's a second dataset with different travelers and metrics — hook that up as the "live" data source so the dashboard can pull from either dataset depending on the backend config. After that, see if there are any data model improvements we should make for tracking weather disruptions.
352
352
 
353
353
  **What the agent must do:**
354
354
 
355
- 1. Find and use `src/data/engine-live-data.js` and `src/hooks/useEngineLiveData.ts`
356
- 2. Import `useEngineLiveData` and wire each `useDataSource({ sample, live })` call
357
- 3. Update KPI overlays to derive from whichever metrics are active
358
- 4. After wiring, proactively offer to create the `Weather_Impact__c` custom field (section 14a)
355
+ 1. Read only `EngineDashboard.tsx` and the live data file — don't read `useDataSource.js`, `DataModeProvider.jsx`, or other library source files (the patterns are in the build guide)
356
+ 2. Make **surgical edits** to the existing `EngineDashboard.tsx` do NOT rewrite the entire file
357
+ 3. Add `useEngineLiveData` import and hook call
358
+ 4. Update every `useDataSource({ sample, live })` call to pass live data
359
+ 5. Update KPI overlays to derive from whichever metrics are active
360
+ 6. After wiring is complete, **STOP and suggest** the `Weather_Impact__c` custom field — do NOT create it until the user confirms
359
361
 
360
- **Reference — what the agent should say:**
362
+ **What the agent must NOT do in this prompt:**
363
+ - Do NOT rewrite `EngineDashboard.tsx` from scratch — make targeted edits to the existing Phase 1 file
364
+ - Do NOT read library component source files (`useDataSource.js`, `DataModeProvider.jsx`) — the wiring patterns are in the build guide
365
+ - Do NOT add `DataModeToggle` to the UI — data mode is controlled by `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts`, not a visible toggle
366
+ - Do NOT create the custom field without asking first — suggest it, then wait for "yes"
367
+ - Do NOT add ChatBar, Eva, or any Agentforce integration — that's Prompt 3
368
+ - Do NOT run `npm run build` between edits
369
+
370
+ **Reference — what the agent should say after wiring:**
361
371
 
362
- After wiring the live data: *"I notice `Flight__c` doesn't have a field to track weather impact on individual flights. A `Weather_Impact__c` picklist would help the dashboard filter storm-affected flights. Want me to create it?"* — When confirmed, create the custom field XML from section 14a and deploy it.
372
+ *"I notice `Flight__c` doesn't have a field to track weather impact on individual flights. A `Weather_Impact__c` picklist would help the dashboard filter storm-affected flights. Want me to create it?"* — Only create the custom field XML from section 14a AFTER the user confirms.
363
373
 
364
374
  ---
365
375
 
@@ -369,16 +379,22 @@ After wiring the live data: *"I notice `Flight__c` doesn't have a field to track
369
379
 
370
380
  **What the agent must do:**
371
381
 
372
- 1. Add `ChatBar` with suggestions from section 9, placed between map and data panels
373
- 2. Add `AgentforceConversationClient` with `agentId="0Xxa5000000relhCAA"` and `agentLabel="Eva"`
374
- 3. Proactively offer to create `Travel_Disruption_Alert__e` platform event (section 14b)
375
- 4. After the event, proactively offer to create `TravelDisruptionEventService` Apex class (section 14c)
382
+ 1. Make **surgical edits** to the existing `EngineDashboard.tsx` do NOT rewrite the entire file
383
+ 2. Add `ChatBar` with suggestions from section 9, placed between map and data panels
384
+ 3. Add `AgentforceConversationClient` with `agentId="0Xxa5000000relhCAA"` and `agentLabel="Eva"`
385
+ 4. After adding Eva, **STOP and suggest** the platform event do NOT create it until the user confirms
386
+ 5. After user confirms and platform event is created, **STOP and suggest** the Apex class — do NOT create it until the user confirms
387
+
388
+ **What the agent must NOT do in this prompt:**
389
+ - Do NOT rewrite `EngineDashboard.tsx` from scratch — make targeted edits to the existing Phase 2 file
390
+ - Do NOT create platform events or Apex classes without user confirmation — each is a scripted demo moment where you suggest, wait, then create
391
+ - Do NOT read library component source files
376
392
 
377
- **Reference — what the agent should say:**
393
+ **Reference — what the agent should say (in sequence, stopping after each):**
378
394
 
379
- 1. After adding Eva: *"The dashboard tracks disruptions in real time. I can create a `Travel_Disruption_Alert__e` platform event so disruption data can be published to the Salesforce event bus — other systems and automation can subscribe to it. Want me to set it up?"* — When confirmed, create the platform event and its fields from section 14b and deploy.
395
+ 1. After adding Eva: *"The dashboard tracks disruptions in real time. I can create a `Travel_Disruption_Alert__e` platform event so disruption data can be published to the Salesforce event bus — other systems and automation can subscribe to it. Want me to set it up?"* — Only create the platform event (section 14b) AFTER the user confirms.
380
396
 
381
- 2. After the platform event: *"Now I'll write an Apex service class to publish disruption records to that event bus. `TravelDisruptionEventService` will take a list of disruptions and fire platform events with the flight number, severity, and description. Want me to create it?"* — When confirmed, create the Apex class from section 14c and deploy.
397
+ 2. After the platform event: *"Now I'll write an Apex service class to publish disruption records to that event bus. `TravelDisruptionEventService` will take a list of disruptions and fire platform events with the flight number, severity, and description. Want me to create it?"* — Only create the Apex class (section 14c) AFTER the user confirms.
382
398
 
383
399
  ---
384
400
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@schandlergarcia/sf-web-components",
3
- "version": "1.9.77",
3
+ "version": "1.9.78",
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",