@schandlergarcia/sf-web-components 1.9.78 → 1.9.80

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

@@ -43,6 +43,7 @@ export default function HomePage() {
 // src/components/workspace/CommandCenter.tsx
 import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
 import DataModeProvider from "@/components/library/data/DataModeProvider";
+import { ENABLE_SAMPLE_DATA_CACHE } from "@/lib/dataStrategy";
 import { Toast } from "@heroui/react";
 import MyDashboard from "../../pages/MyDashboard";  // ← change ONLY this import
 
@@ -50,7 +51,7 @@ export default function CommandCenter() {
   return (
     <div className="heroui-scope">
       <AppThemeProvider initialMode="light">
-        <DataModeProvider initialMode="sample">
+        <DataModeProvider initialMode={ENABLE_SAMPLE_DATA_CACHE ? "sample" : "live"}>
           <MyDashboard />
           <Toast.Provider placement="bottom end" />
         </DataModeProvider>

package/.a4drules/skills/command-center-builder/getting-started.md

@@ -45,19 +45,23 @@ The dashboard is built in **3 phases**, one per user prompt. Each phase adds a l
 
 ## Phase 2 — Connect to Live Data
 
+**The point of Phase 2:** The dashboard switches from sample data (8 US travelers: Sarah Chen, Marcus Johnson…) to a completely different live dataset (12 global travelers: Raj Kapoor, Sofia Reyes… with a Midwest storm scenario). The user should see different names, different cities, different metrics, and different disruptions.
+
+**How the switch works:** `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` controls which data `useDataSource` returns. `CommandCenter.tsx` reads this flag and passes it to `DataModeProvider`. When the flag is `true` (default), mode is "sample." When `false`, mode is "live" and every `useDataSource` call returns its `live` prop instead.
+
 **How to work:** Make surgical edits to the existing `EngineDashboard.tsx`. Do NOT rewrite the file.
 
 **Files to read first (only these):**
 1. `src/pages/EngineDashboard.tsx` — the Phase 1 dashboard you're editing
-2. `src/data/engine-live-data.js` or `src/hooks/useEngineLiveData.ts` — to see the live data shape
+2. `src/hooks/useEngineLiveData.ts` — to see the live data shape
 
-**Do NOT read:** `useDataSource.js`, `DataModeProvider.jsx`, or any library component source. The patterns are right here:
+**Do NOT read:** `useDataSource.jsx`, `DataModeProvider.jsx`, `dataStrategy.ts`, or any library component source. The patterns are right here.
 
 **Edits to make (in order):**
 
 1. **Add import** at the top of EngineDashboard.tsx:
    ```tsx
-   import useEngineLiveData from "@/hooks/useEngineLiveData";
+   import { useEngineLiveData } from "@/hooks/useEngineLiveData";
    ```
 
 2. **Add hook call** inside the component, near the top:
@@ -80,9 +84,15 @@ The dashboard is built in **3 phases**, one per user prompt. Each phase adds a l
    ```
    Then use `activeMetrics` in KPI overlays instead of hardcoded sample constants.
 
-That's 4 targeted edits. Not a full rewrite.
+5. **Flip the backend switch** — change `src/lib/dataStrategy.ts`:
+   ```tsx
+   export const ENABLE_SAMPLE_DATA_CACHE = false;
+   ```
+   This causes `CommandCenter.tsx` to pass `initialMode="live"` to `DataModeProvider`, and every `useDataSource` call now returns the live prop. The dashboard instantly shows the live dataset on next load.
+
+That's 5 targeted edits. Not a full rewrite.
 
-**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.
+**No UI toggle.** There is no `DataModeToggle` in the dashboard. The switch is `ENABLE_SAMPLE_DATA_CACHE` in `dataStrategy.ts`.
 
 **After wiring — STOP and suggest (do not create yet):**
 
@@ -94,6 +104,7 @@ Only create `Flight__c.Weather_Impact__c` (PRD section 14a) AFTER the user confi
 - No ChatBar or Eva — that's Phase 3
 - No platform events or Apex — that's Phase 3
 - Do NOT rewrite EngineDashboard.tsx from scratch
+- Do NOT add `DataModeToggle` to the UI
 - Do NOT read library component source files
 - Do NOT run `npm run build` between edits
 
@@ -166,12 +177,13 @@ Only create `TravelDisruptionEventService` (PRD section 14c) AFTER the user conf
 | | Phase 1 | Phase 2 | Phase 3 |
 |---|---------|---------|---------|
 | Dashboard layout & panels | Write new file | — | — |
-| Sample data | Wire | — | — |
-| Live data | Skip | Surgical edits | — |
+| Sample data | Wire (`live: []`) | — | — |
+| Live data wiring | Skip | Surgical edits | — |
+| Flip `dataStrategy.ts` to `false` | Skip | Edit | — |
 | Custom field metadata | Skip | Suggest → wait | — |
 | ChatBar (Eva) | Skip | Skip | Surgical edit |
 | AgentforceConversationClient | Skip | Skip | Surgical edit |
 | Platform event | Skip | Skip | Suggest → wait |
 | Apex service | Skip | Skip | Suggest → wait |
 
-**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.
+**Data mode control:** `ENABLE_SAMPLE_DATA_CACHE` in `src/lib/dataStrategy.ts` is the backend switch. `CommandCenter.tsx` reads this flag and passes `initialMode` to `DataModeProvider`. Phase 1 leaves it `true` (sample data). Phase 2 flips it to `false` (live data — different travelers, cities, and metrics). There is no UI toggle.

package/.a4drules/skills/command-center-builder/improved-build-process.md

@@ -34,14 +34,15 @@ Rewriting a 400+ line file from scratch takes 60 seconds, risks losing prior wor
 ## Phase 2 Edit Order
 
 ```
-1. Add useEngineLiveData import
+1. Add useEngineLiveData import to EngineDashboard.tsx
 2. Add const live = useEngineLiveData() hook call
 3. Update each useDataSource({ sample, live: [] }) → live: live.xxx
 4. Update KPI derivations to use activeMetrics
+5. Flip ENABLE_SAMPLE_DATA_CACHE to false in src/lib/dataStrategy.ts
 → STOP — suggest Weather_Impact__c, wait for confirmation
 ```
 
-No DataModeToggle in the UI — data mode is controlled by `dataStrategy.ts` on the backend.
+No UI toggle. The switch is `ENABLE_SAMPLE_DATA_CACHE` in `dataStrategy.ts`. When `false`, `CommandCenter.tsx` passes `initialMode="live"` and every `useDataSource` returns its live prop.
 
 ## Phase 3 Edit Order
 

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.80] - 2026-04-04
+
+### Added
+- **Reset script cleans Salesforce metadata** — `reset-command-center.sh` now removes all Apex classes (`.cls` + `.cls-meta.xml`), custom field XML, and platform event directories from `force-app/main/default/`. Walks up from the webapp root to find the SFDX project structure automatically.
+
+**Context:** Demo phases create Apex classes (Agent*, TCC_*), custom fields (Weather_Impact__c), and platform events (Travel_Disruption_Alert__e) that need to be cleaned up when resetting for a fresh demo run.
+
+## [1.9.79] - 2026-04-04
+
+### Fixed
+- **Data mode switching was broken** — `ENABLE_SAMPLE_DATA_CACHE` in `dataStrategy.ts` was dead code (nothing read it). `useEngineLiveData` was auto-calling `setMode("live")` after 2 seconds via React context, which was fragile and confusing
+- **No visible data change between phases** — Phase 2 should produce visibly different data (12 global travelers vs 8 US travelers, Midwest storm scenario) but the switching mechanism wasn't wired to `dataStrategy.ts`
+
+### Changed
+- **`useEngineLiveData.ts`** — Removed `setMode("sample"/"live")` calls. Hook now just provides the live data; it no longer controls the data mode
+- **`useDataSource.jsx`** — Updated to fall back to sample when live is null/empty, reads mode from `DataModeProvider` context which is now properly controlled by `dataStrategy.ts`
+- **`CommandCenter.tsx` template** — Now imports `ENABLE_SAMPLE_DATA_CACHE` from `@/lib/dataStrategy` and passes `initialMode={ENABLE_SAMPLE_DATA_CACHE ? "sample" : "live"}` to `DataModeProvider`
+- **`dataStrategy.ts` template** — Rewritten comments to explain the Phase 1/Phase 2 connection and how flipping the flag changes the dashboard data
+- **Build guide Phase 2** — Added step 5: "Flip `ENABLE_SAMPLE_DATA_CACHE` to `false`". Added explanation of what changes visually (different names, cities, metrics)
+- **PRD Phase 2** — Added `dataStrategy.ts` flip as step 6 with explanation of the visual change
+- **Efficient build process** — Updated Phase 2 edit order to include the flag flip
+- **SKILL.md** — Updated `CommandCenter.tsx` wiring example to include `ENABLE_SAMPLE_DATA_CACHE` import
+
+**Context:** The data mode switch was supposed to be a backend config (`dataStrategy.ts`) but the flag was disconnected. The actual switching was done by `useEngineLiveData` auto-calling `setMode("live")` after a 2-second delay, which meant the hook controlled both data AND mode — not clean. Now: `dataStrategy.ts` is the single control point, `CommandCenter.tsx` reads it, `DataModeProvider` respects it, and `useDataSource` returns the right data. Phase 2 just flips the flag.
+
 ## [1.9.78] - 2026-04-04
 
 ### Fixed

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

@@ -352,17 +352,18 @@ Build incrementally in 3 prompts. Each prompt builds on the previous result. The
 
 **What the agent must do:**
 
-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)
+1. Read only `EngineDashboard.tsx` and `src/hooks/useEngineLiveData.ts` — don't read `useDataSource.jsx`, `DataModeProvider.jsx`, or other library source files (the patterns are in the build guide)
 2. Make **surgical edits** to the existing `EngineDashboard.tsx` — do NOT rewrite the entire file
 3. Add `useEngineLiveData` import and hook call
 4. Update every `useDataSource({ sample, live })` call to pass live data
 5. Update KPI overlays to derive from whichever metrics are active
-6. After wiring is complete, **STOP and suggest** the `Weather_Impact__c` custom field — do NOT create it until the user confirms
+6. **Flip the backend switch:** change `ENABLE_SAMPLE_DATA_CACHE` from `true` to `false` in `src/lib/dataStrategy.ts` — this makes `CommandCenter.tsx` pass `initialMode="live"` to `DataModeProvider`, so every `useDataSource` call now returns the live prop. The dashboard will show completely different data: 12 global travelers (Raj Kapoor, Sofia Reyes…) instead of 8 US travelers, a Midwest storm scenario, and different metrics.
+7. After wiring is complete, **STOP and suggest** the `Weather_Impact__c` custom field — do NOT create it until the user confirms
 
 **What the agent must NOT do in this prompt:**
 - Do NOT rewrite `EngineDashboard.tsx` from scratch — make targeted edits to the existing Phase 1 file
-- Do NOT read library component source files (`useDataSource.js`, `DataModeProvider.jsx`) — the wiring patterns are in the build guide
-- 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
+- Do NOT read library component source files (`useDataSource.jsx`, `DataModeProvider.jsx`, `dataStrategy.ts`) — the wiring patterns are in the build guide
+- Do NOT add `DataModeToggle` to the UI — there is no UI toggle, the switch is `dataStrategy.ts`
 - Do NOT create the custom field without asking first — suggest it, then wait for "yes"
 - Do NOT add ChatBar, Eva, or any Agentforce integration — that's Prompt 3
 - Do NOT run `npm run build` between edits

package/data/useEngineLiveData.ts

@@ -1,5 +1,4 @@
 import { useState, useEffect } from "react";
-import { useDataMode } from "@/components/library/data/DataModeProvider";
 import * as live from "@/data/engine-live-data";
 
 const SIMULATED_LOAD_MS = 2000;
@@ -18,26 +17,22 @@ export interface EngineLiveData {
 }
 
 /**
- * Simulates fetching live data from Salesforce via GraphQL.
+ * Provides the live dataset for the Engine Travel Command Center.
  *
- * On mount, shows a loading state for ~2 seconds, then resolves with the
- * live dataset and flips the global data mode from "sample" → "live".
- * Every useDataSource call across the dashboard will then return the
- * live prop instead of the sample prop, causing all components to refresh
- * simultaneously with new data.
+ * Simulates a 2-second network fetch, then resolves with all live data.
+ * Does NOT control the data mode — that's handled by ENABLE_SAMPLE_DATA_CACHE
+ * in src/lib/dataStrategy.ts. When the flag is false, every useDataSource call
+ * returns its live prop (which this hook provides) instead of its sample prop.
  */
 export function useEngineLiveData(): EngineLiveData {
   const [loading, setLoading] = useState(true);
-  const { setMode } = useDataMode();
 
   useEffect(() => {
-    setMode("sample");
     const timer = setTimeout(() => {
       setLoading(false);
-      setMode("live");
     }, SIMULATED_LOAD_MS);
     return () => clearTimeout(timer);
-  }, [setMode]);
+  }, []);
 
   return {
     loading,

package/dist/components/library/data/useDataSource.js

@@ -1,13 +1,10 @@
-import { useMemo as u } from "react";
-import { useDataMode as n } from "./DataModeProvider.js";
-function c({ sample: t, live: e }) {
-  const { mode: r } = n();
-  return u(() => {
-    const o = r === "sample" ? t : e;
-    return typeof o == "function" ? o() : o;
-  }, [r, t, e]);
+import { useMemo as n } from "react";
+import { useDataMode as u } from "./DataModeProvider.js";
+function a({ sample: t, live: r }) {
+  const { mode: o } = u();
+  return n(() => o === "live" && r != null && !(Array.isArray(r) && r.length === 0) ? typeof r == "function" ? r() : r : typeof t == "function" ? t() : t, [o, t, r]);
 }
 export {
-  c as default
+  a as default
 };
 //# sourceMappingURL=useDataSource.js.map

package/dist/components/library/data/useDataSource.js.map

@@ -1 +1 @@
-{"version":3,"file":"useDataSource.js","sources":["../../../../src/components/library/data/useDataSource.jsx"],"sourcesContent":["import { useMemo } from \"react\";\nimport { useDataMode } from \"./DataModeProvider\";\n\n/**\n * Select between sample and live data based on the global data mode.\n *\n * Values can be plain data or functions (lazy-evaluated only when active).\n *\n * @param {{ sample: any | () => any, live: any | () => any }} sources\n * @returns {any} the resolved value for the active mode\n *\n * @example\n * // Static data\n * const incidents = useDataSource({\n *   sample: sampleIncidents,\n *   live: fetchedIncidents,\n * });\n *\n * @example\n * // Lazy — factory only runs when that mode is active\n * const metrics = useDataSource({\n *   sample: () => generateSampleMetrics(),\n *   live: () => computeFromAPI(apiData),\n * });\n */\nexport default function useDataSource({ sample, live }) {\n  const { mode } = useDataMode();\n\n  return useMemo(() => {\n    const source = mode === \"sample\" ? sample : live;\n    return typeof source === \"function\" ? source() : source;\n  }, [mode, sample, live]);\n}\n"],"names":["useDataSource","sample","live","mode","useDataMode","useMemo","source"],"mappings":";;AAyBA,SAAwBA,EAAc,EAAE,QAAAC,GAAQ,MAAAC,KAAQ;AACtD,QAAM,EAAE,MAAAC,EAAA,IAASC,EAAA;AAEjB,SAAOC,EAAQ,MAAM;AACnB,UAAMC,IAASH,MAAS,WAAWF,IAASC;AAC5C,WAAO,OAAOI,KAAW,aAAaA,EAAA,IAAWA;AAAA,EACnD,GAAG,CAACH,GAAMF,GAAQC,CAAI,CAAC;AACzB;"}
+{"version":3,"file":"useDataSource.js","sources":["../../../../src/components/library/data/useDataSource.jsx"],"sourcesContent":["import { useMemo } from \"react\";\nimport { useDataMode } from \"./DataModeProvider\";\n\n/**\n * Select between sample and live data based on the global data mode.\n *\n * The mode is controlled by ENABLE_SAMPLE_DATA_CACHE in src/lib/dataStrategy.ts,\n * which CommandCenter.tsx passes to DataModeProvider as initialMode.\n * When the flag is true, mode is \"sample\" and this hook returns the sample prop.\n * When false, mode is \"live\" and this hook returns the live prop.\n *\n * Values can be plain data or functions (lazy-evaluated only when active).\n *\n * @param {{ sample: any | () => any, live: any | () => any }} sources\n * @returns {any} the resolved value for the active mode\n *\n * @example\n * const incidents = useDataSource({\n *   sample: sampleIncidents,\n *   live: fetchedIncidents,\n * });\n */\nexport default function useDataSource({ sample, live }) {\n  const { mode } = useDataMode();\n\n  return useMemo(() => {\n    if (mode === \"live\" && live != null && !(Array.isArray(live) && live.length === 0)) {\n      return typeof live === \"function\" ? live() : live;\n    }\n    return typeof sample === \"function\" ? sample() : sample;\n  }, [mode, sample, live]);\n}\n"],"names":["useDataSource","sample","live","mode","useDataMode","useMemo"],"mappings":";;AAsBA,SAAwBA,EAAc,EAAE,QAAAC,GAAQ,MAAAC,KAAQ;AACtD,QAAM,EAAE,MAAAC,EAAA,IAASC,EAAA;AAEjB,SAAOC,EAAQ,MACTF,MAAS,UAAUD,KAAQ,QAAQ,EAAE,MAAM,QAAQA,CAAI,KAAKA,EAAK,WAAW,KACvE,OAAOA,KAAS,aAAaA,EAAA,IAASA,IAExC,OAAOD,KAAW,aAAaA,EAAA,IAAWA,GAChD,CAACE,GAAMF,GAAQC,CAAI,CAAC;AACzB;"}

package/package.json

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

package/scripts/reset-command-center.sh

@@ -755,7 +755,79 @@ else
   echo "  ⚠ Skipped logo (package logo not found)"
 fi
 
-echo ""
+# ── Clean Salesforce metadata created during the demo ────────────────────────
+
+SFDX_DEFAULT=""
+
+# Walk up from webapp root to find force-app/main/default
+check="$ROOT"
+for i in 1 2 3 4 5; do
+  if [ -d "$check/force-app/main/default" ]; then
+    SFDX_DEFAULT="$check/force-app/main/default"
+    break
+  fi
+  parent="$(dirname "$check")"
+  # Check if we're already inside force-app/main/default
+  if [[ "$check" == */force-app/main/default/* ]]; then
+    SFDX_DEFAULT="${check%%/force-app/main/default/*}/force-app/main/default"
+    break
+  fi
+  check="$parent"
+done
+
+if [ -n "$SFDX_DEFAULT" ]; then
+  echo "→ Cleaning Salesforce metadata…"
+
+  # Remove all Apex classes (.cls and .cls-meta.xml)
+  CLASSES_DIR="$SFDX_DEFAULT/classes"
+  if [ -d "$CLASSES_DIR" ]; then
+    cls_count=$(find "$CLASSES_DIR" -maxdepth 1 -name "*.cls" -o -name "*.cls-meta.xml" 2>/dev/null | wc -l | tr -d ' ')
+    if [ "$cls_count" -gt 0 ]; then
+      rm -f "$CLASSES_DIR"/*.cls "$CLASSES_DIR"/*.cls-meta.xml
+      echo "  ✓ Removed $cls_count Apex class files from classes/"
+    else
+      echo "  ℹ No Apex classes to remove"
+    fi
+  fi
+
+  # Remove custom fields created during the demo (e.g., Weather_Impact__c)
+  OBJECTS_DIR="$SFDX_DEFAULT/objects"
+  if [ -d "$OBJECTS_DIR" ]; then
+    fields_removed=0
+    for fields_dir in "$OBJECTS_DIR"/*/fields; do
+      if [ -d "$fields_dir" ]; then
+        for f in "$fields_dir"/*.field-meta.xml; do
+          if [ -f "$f" ]; then
+            rm "$f"
+            echo "  ✓ Removed $(basename "$f")"
+            fields_removed=$((fields_removed + 1))
+          fi
+        done
+      fi
+    done
+    if [ "$fields_removed" -eq 0 ]; then
+      echo "  ℹ No custom fields to remove"
+    fi
+
+    # Remove platform event directories (e.g., Travel_Disruption_Alert__e/)
+    events_removed=0
+    for evt_dir in "$OBJECTS_DIR"/*__e; do
+      if [ -d "$evt_dir" ]; then
+        rm -rf "$evt_dir"
+        echo "  ✓ Removed platform event $(basename "$evt_dir")"
+        events_removed=$((events_removed + 1))
+      fi
+    done
+    if [ "$events_removed" -eq 0 ]; then
+      echo "  ℹ No platform events to remove"
+    fi
+  fi
+
+  echo ""
+else
+  echo "→ Skipping metadata cleanup (no force-app directory found)"
+  echo ""
+fi
 
 # ── Done ─────────────────────────────────────────────────────────────────────
 
@@ -764,18 +836,15 @@ echo "║   ✓ Reset complete!                             ║"
 echo "║                                                ║"
 echo "║   Restored:                                    ║"
 echo "║     • Engine brand theme (global.css)          ║"
-echo "║       - Teal brand palette (#5BC8C8)           ║"
-echo "║       - Inter font stack                       ║"
-echo "║       - HeroUI Engine theme overrides          ║"
-echo "║     • Engine sample data (engine-sample-data.js)║"
-echo "║     • Engine live data (engine-live-data.js)   ║"
+echo "║     • Engine sample data + live data           ║"
 echo "║     • Live data hook (useEngineLiveData.ts)    ║"
-echo "║     • GraphQL schema (schema.graphql)          ║"
-echo "║     • Engine PRD (engine-command-center-prd.md)║"
-echo "║     • Engine logo (engine_logo.png)            ║"
-echo "║     • Component library (cards, charts, etc.)  ║"
-echo "║     • HeroUI wrappers & theme providers        ║"
-echo "║     • Salesforce SDK stubs for local dev       ║"
+echo "║     • GraphQL schema + PRD + logo              ║"
+echo "║     • Component library + theme providers      ║"
+echo "║                                                ║"
+echo "║   Cleaned:                                     ║"
+echo "║     • Apex classes (force-app classes/)         ║"
+echo "║     • Custom fields (force-app objects/)        ║"
+echo "║     • Platform events (force-app *__e/)         ║"
 echo "║                                                ║"
 echo "║   Layout:                                      ║"
 echo "║     /         → Home (search page)             ║"
@@ -783,9 +852,6 @@ echo "║     /search   → Search (search page)           ║"
 echo "║     Nav bar on Home + Search pages only        ║"
 echo "║                                                ║"
 echo "║   Start building:                              ║"
-echo "║     • For dashboards: Edit BlankDashboard.tsx  ║"
-echo "║       then wire into routes or CommandCenter   ║"
-echo "║     • For search app: Ready to go!             ║"
 echo "║     npm run dev                                 ║"
 echo "╚════════════════════════════════════════════════╝"
 echo ""

package/src/components/library/data/useDataSource.jsx

@@ -4,30 +4,29 @@ import { useDataMode } from "./DataModeProvider";
 /**
  * Select between sample and live data based on the global data mode.
  *
+ * The mode is controlled by ENABLE_SAMPLE_DATA_CACHE in src/lib/dataStrategy.ts,
+ * which CommandCenter.tsx passes to DataModeProvider as initialMode.
+ * When the flag is true, mode is "sample" and this hook returns the sample prop.
+ * When false, mode is "live" and this hook returns the live prop.
+ *
  * Values can be plain data or functions (lazy-evaluated only when active).
  *
  * @param {{ sample: any | () => any, live: any | () => any }} sources
  * @returns {any} the resolved value for the active mode
  *
  * @example
- * // Static data
  * const incidents = useDataSource({
  *   sample: sampleIncidents,
  *   live: fetchedIncidents,
  * });
- *
- * @example
- * // Lazy — factory only runs when that mode is active
- * const metrics = useDataSource({
- *   sample: () => generateSampleMetrics(),
- *   live: () => computeFromAPI(apiData),
- * });
  */
 export default function useDataSource({ sample, live }) {
   const { mode } = useDataMode();
 
   return useMemo(() => {
-    const source = mode === "sample" ? sample : live;
-    return typeof source === "function" ? source() : source;
+    if (mode === "live" && live != null && !(Array.isArray(live) && live.length === 0)) {
+      return typeof live === "function" ? live() : live;
+    }
+    return typeof sample === "function" ? sample() : sample;
   }, [mode, sample, live]);
 }

package/src/templates/lib/dataStrategy.ts.template

@@ -1,42 +1,24 @@
 /**
  * Data Strategy Configuration
  *
- * Controls data sourcing strategy for the application.
+ * Controls which dataset the dashboard displays.
  *
  * ENABLE_SAMPLE_DATA_CACHE:
- * When enabled, the application uses an optimized sample data cache
- * instead of making live API requests. This provides:
- * - Faster load times during development
- * - Consistent data for testing and presentations
- * - Reduced API load
- * - Offline-first capability
+ * - true  → Dashboard shows sample data (default after install)
+ * - false → Dashboard shows live data (different travelers, cities, metrics)
  *
  * HOW IT WORKS:
- * The useDataSource hook checks this flag and returns cached sample
- * data when enabled, or live API data when disabled. This allows
- * seamless switching between data sources without code changes.
+ * CommandCenter.tsx reads this flag and passes initialMode to DataModeProvider:
+ *   initialMode={ENABLE_SAMPLE_DATA_CACHE ? "sample" : "live"}
  *
- * USAGE:
- * Set to false to enable live data fetching from APIs.
- * Set to true to use the local sample data cache.
+ * Every useDataSource({ sample, live }) call returns whichever prop matches
+ * the active mode. When you flip this flag to false, the dashboard instantly
+ * shows the live dataset on next load — no code changes needed.
  *
- * AFFECTED COMPONENTS:
- * All components using useDataSource hook will respect this setting.
+ * USAGE:
+ * Phase 1 (Build the Dashboard): Leave as true — sample data.
+ * Phase 2 (Connect to Live Data): Flip to false — live data with different
+ *   travelers, cities, disruptions, and metrics.
  */
 
 export const ENABLE_SAMPLE_DATA_CACHE = true;
-
-/**
- * Sample data cache is currently ENABLED
- *
- * Benefits:
- * ✓ Instant data loading (no network latency)
- * ✓ No API rate limiting concerns
- * ✓ Consistent data for demos and testing
- * ✓ Works offline
- * ✓ Reduced backend load
- *
- * To enable live API data:
- * 1. Set ENABLE_SAMPLE_DATA_CACHE to false
- * 2. Restart the development server
- */

package/src/templates/workspace/CommandCenter.tsx.template

@@ -1,12 +1,13 @@
 import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
 import DataModeProvider from "@/components/library/data/DataModeProvider";
+import { ENABLE_SAMPLE_DATA_CACHE } from "@/lib/dataStrategy";
 import { Toaster } from "sonner";
 import BlankDashboard from "../pages/BlankDashboard";
 
 export default function CommandCenter() {
   return (
     <AppThemeProvider initialMode="light">
-      <DataModeProvider initialMode="sample">
+      <DataModeProvider initialMode={ENABLE_SAMPLE_DATA_CACHE ? "sample" : "live"}>
         <BlankDashboard />
         <Toaster position="bottom-right" />
       </DataModeProvider>