@schandlergarcia/sf-web-components 1.9.63 → 1.9.65

package/.a4drules/features/pre-code-checklist.md

@@ -1,215 +1,26 @@
----
-paths:
-  - "**/pages/*.tsx"
-  - "**/components/pages/*.tsx"
----
+# Pre-Code Checklist
 
-# Pre-Code Checklist (MANDATORY)
+This is a reference checklist. For build instructions, use the phase files in `.a4drules/phases/`.
 
-Before writing any code for command center dashboards, verify these requirements from the PRD and skills.
+## Before creating a dashboard file
 
-## FIRST: Read These Files
+- [ ] File path: `src/pages/DashboardName.tsx` (NOT `src/components/pages/`)
+- [ ] File extension: `.tsx` (NOT `.jsx`)
+- [ ] Imports: `@/components/library` only (NOT `@/components/ui/`, NOT `lucide-react`)
+- [ ] Theme hook: `import { useThemeMode } from "@/components/library/theme/AppThemeProvider"`
+- [ ] Data hook: `import useDataSource from "@/components/library/data/useDataSource"` (default export)
 
-**Before writing a single line of code, read these files:**
-1. `.a4drules/skills/component-library/SKILL.md` (lines 15-40) - Import Pattern section
-2. `engine-command-center-prd.md` - Phase 1 Placeholder Rules section
-3. This file - Phase 1 Code Template section
+## Color Reference
 
-**Verify you know:**
-- [ ] Exact import statement for `useThemeMode` hook
-- [ ] What "Phase 1 placeholder" means (data panels ONLY, not entire dashboard)
-- [ ] Which colors are forbidden (`text-white`, `text-black`, `bg-black` without opacity)
-
-## File Creation Checklist
-
-When creating a new dashboard file, confirm:
-
-1. **File path:** `src/pages/DashboardName.tsx` (NOT `src/components/pages/`)
-2. **File extension:** `.tsx` (NOT `.jsx`) — this is a TypeScript project
-3. **Imports:** `@/components/library` ONLY (NOT `@/components/ui/`, NOT `lucide-react`, NOT `recharts`)
-4. **Import names:** Check SKILL.md for exact names — DO NOT guess or invent import names
-   - Theme toggle: `useThemeMode` (NOT `useAppTheme`, NOT `useTheme`)
-   - Data source: `import useDataSource from "..."` (default export, NOT named)
-5. **Colors:** Slate scale ONLY (NOT `text-white`, NOT `text-black`, NOT `bg-black`)
-
-## Phase 1 Code Template
-
-**START WITH THIS EXACT STRUCTURE:**
-
-```tsx
-import { GeoMap, BaseCard } from "@/components/library";
-import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
-import { /* Heroicons */ } from "@heroicons/react/24/outline";
-
-export default function EngineDashboard() {
-  const { mode, toggle } = useThemeMode();
-
-  return (
-    <div className="flex flex-col bg-slate-50 dark:bg-slate-950">
-      {/* Header Bar - h-12, sticky, slate-900 bg */}
-      <header className="sticky top-0 z-50 flex h-12 items-center justify-between border-b border-slate-800 bg-slate-900 px-4">
-        {/* Logo + title with text-slate-50 (NOT text-white) */}
-      </header>
-
-      {/* Hero Map - fixed height h-[520px], GeoMap renders world automatically */}
-      <div className="relative h-[520px]">
-        <GeoMap width={960} height={520} theme={mode === "dark" ? "dark" : "light"} className="h-full w-full" />
-        
-        {/* Glass KPI overlays - positioned absolutely, text-slate-50 */}
-        <div className="absolute left-3 top-3 flex gap-2">
-          {/* 4 KPI divs with border-white/10, bg-black/40, backdrop-blur-md */}
-        </div>
-
-        {/* Flight status strip - positioned absolutely at bottom */}
-        <div className="absolute bottom-3 left-3 right-3 flex gap-2 overflow-x-auto">
-          {/* 4 flight divs with status badges */}
-        </div>
-      </div>
-
-      {/* Data Panels - natural flow, full-page scroll, 4 panels total */}
-      <div className="px-4 py-5">
-        <div className="space-y-6">
-          {/* Row 1: Disruptions (1/3) + Active Travelers (2/3) */}
-          <div className="grid grid-cols-1 items-start gap-4 lg:grid-cols-3">
-            <BaseCard>
-              <div className="flex h-48 items-center justify-center text-slate-400">
-                Disruptions Panel
-              </div>
-            </BaseCard>
-            <div className="lg:col-span-2">
-              <BaseCard>
-                <div className="flex h-48 items-center justify-center text-slate-400">
-                  Active Travelers Panel
-                </div>
-              </BaseCard>
-            </div>
-          </div>
-
-          {/* Row 2: Escalations (1/2) + Monthly Spend Chart (1/2) */}
-          <div className="grid grid-cols-1 items-start gap-4 lg:grid-cols-2">
-            <BaseCard>
-              <div className="flex h-48 items-center justify-center text-slate-400">
-                Escalations Panel
-              </div>
-            </BaseCard>
-            <BaseCard>
-              <div className="flex h-48 items-center justify-center text-slate-400">
-                Travel Spend Panel
-              </div>
-            </BaseCard>
-          </div>
-        </div>
-      </div>
-    </div>
-  );
-}
-```
-
-## During Code Generation Checklist
-
-As you write the dashboard code:
-
-1. **Every card** is a library component (MetricCard, ListCard, WidgetCard, etc.) — NO hand-rolled `<div className="bg-white border rounded...">`
-2. **Every chart** uses `ChartCard` + `D3Chart` or `GeoMap` — NO Recharts, NO Chart.js, NO custom SVG
-3. **Every color** uses semantic classes or slate scale — NO `text-white`, NO `bg-black`, NO hardcoded hex
-4. **Dark mode** on every element — `dark:` variants on all custom styling
-5. **Phase 1 scope - Build COMPLETE layout structure:**
-   - ✅ Outer container: `className="flex flex-col bg-slate-50 dark:bg-slate-950"` (NO `h-screen` - full-page scroll)
-   - ✅ Header bar (logo, title, actions) with slate scale colors (NO text-white)
-   - ✅ Header text: ONLY "ENGINE" + "Travel Command Center" (NO "Powered by..." branding in Phase 1)
-   - ✅ Hero map container: `className="relative h-[520px]"` (fixed height, NOT flex-based)
-   - ✅ Hero map (GeoMap component with NO markers/arcs/overlays PROPS, `className="h-full w-full"`)
-   - ✅ Glass KPI overlays (4 hardcoded KPIs, positioned absolutely over map)
-   - ✅ Flight status strip (4 hardcoded flights, positioned at map bottom)
-   - ✅ Data panels container: `className="px-4 py-5"` (NO `overflow-y-auto`, NO flex constraints - natural flow)
-   - ✅ **4 data panel placeholders** (2 rows: Disruptions/Travelers, Escalations/Destinations) - BaseCard with NO title prop, centered text
-   - ❌ **Phase 1 EXCLUDES:** Salesforce/Data Cloud branding (Phase 4), ChatBar (Phase 4), real data (Phase 2+)
-   - "Placeholder" means data panels below the map, NOT the header/overlays/map
-   - **Full-page scroll:** Entire dashboard scrolls naturally (map scrolls up as user scrolls down)
-
-## After Code Generation Checklist
-
-After writing the dashboard code:
-
-1. **Wiring:**
-   - [ ] `CommandCenter.tsx` imports your dashboard
-   - [ ] `Home.tsx` renders `CommandCenter`
-   - [ ] `routes.tsx` has correct routes
-
-2. **Completion:**
-   - [ ] All files wired correctly
-   - [ ] **DO NOT run `npm run dev` or `npm run validate:dashboard`** - not required for ANY phase completion
-
-## Color Reference (CRITICAL)
-
-**NEVER use these:**
-
-| ❌ FORBIDDEN | ✅ USE INSTEAD | Where |
-|-------------|---------------|-------|
+| Forbidden | Use instead | Where |
+|-----------|------------|-------|
 | `text-white` | `text-slate-50` | Header text, overlay text |
 | `text-black` | `text-slate-900` | Body text (light mode) |
 | `bg-black` | `bg-slate-900` or `bg-black/40` (with opacity) | Backgrounds |
-| `bg-white` | `bg-slate-50` | Page background (light mode) |
-
-**Exception:** `bg-black/40`, `bg-white/10`, `border-white/10` are allowed (opacity variants for glass effect)
-
-## Verification Checklist
-
-After building, you should see:
-- [ ] Header bar with Engine logo and "Travel Command Center" title
-- [ ] **World map visible** (blue/teal land on dark background OR gray land on light background)
-- [ ] 4 glass KPI boxes in top-left of map (semi-transparent with numbers)
-- [ ] 4 flight status boxes at bottom of map (with colored badges)
-- [ ] **4 white/dark cards below map** (2 rows: row 1 has 1/3 + 2/3 split, row 2 has 1/2 + 1/2 split)
-- [ ] Page scrolls when you scroll the data panels section
-- [ ] Theme toggle works (sun/moon icon in header)
-
-## Quick Reference
-
-| Question | Answer |
-|----------|--------|
-| File path? | `src/pages/EngineDashboard.tsx` |
-| Extension? | `.tsx` (TypeScript) |
-| Import from? | `@/components/library` |
-| Hook import? | `import { useThemeMode } from "@/components/library/theme/AppThemeProvider"` |
-| Colors? | Slate scale (`text-slate-50`, `bg-slate-900`) - NEVER `text-white` |
-| Cards? | Library components (MetricCard, ListCard, etc.) |
-| Charts? | `ChartCard` + `D3Chart` or `GeoMap` |
-| After building? | Wire into CommandCenter/Home/routes - DO NOT run dev server |
-
-## Common Mistakes to Avoid
-
-❌ `src/pages/EngineDashboard.tsx` → ✅ `src/pages/EngineDashboard.tsx`
-❌ `EngineDashboard.jsx` → ✅ `EngineDashboard.tsx`
-❌ `text-white` → ✅ `text-slate-50`
-❌ `bg-black` → ✅ `bg-slate-900`
-❌ `<div className="bg-white border rounded-lg p-4">` → ✅ `<BaseCard>` or `<WidgetCard>`
-❌ `import { Button } from '@/components/ui/button'` → ✅ `import { UIButton } from '@/components/library'`
-❌ `import { useAppTheme } from '@/components/library'` → ✅ `import { useThemeMode } from '@/components/library'`
-❌ `"Powered by Salesforce Data Cloud"` in Phase 1 → ✅ This is Phase 4 only (see PRD Section 10)
-❌ Running `npm run dev` after building → ✅ Not needed - validation is sufficient
-
-## Troubleshooting
-
-**If you get TypeScript error about imports:**
-1. ❌ DO NOT follow "did you mean default import?" suggestion
-2. ✅ READ `.a4drules/skills/component-library/SKILL.md` Import Pattern section
-3. ✅ USE the exact import shown in the docs
-
-**If map doesn't render:**
-1. ✅ Verify container has `style={{ flex: "1.15 1 0", minHeight: 0 }}`
-2. ✅ Verify GeoMap has `className="h-full w-full"`
-3. ✅ GeoMap shows world map automatically - no props needed
-
-**If colors look wrong:**
-1. ✅ Search your code for `text-white` - should be `text-slate-50`
-2. ✅ Search your code for `text-black` - should be `text-slate-900`
-3. ✅ Exception: `bg-black/40` and `border-white/10` (with opacity) are OK
-
-**If data panels don't scroll:**
-1. ✅ Verify data panels container has `overflow-y-auto` className
-2. ✅ Verify it has `style={{ flex: "1 1 0" }}`
 
-## Enforcement
+## After creating the dashboard
 
-This checklist is MANDATORY. Do not skip any step. Verify each item before moving to the next phase.
+- [ ] `CommandCenter.tsx` imports your dashboard
+- [ ] `Home.tsx` renders `CommandCenter`
+- [ ] `routes.tsx` has correct routes
+- [ ] DO NOT run `npm run dev` or `npm run validate:dashboard`

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

@@ -254,7 +254,9 @@ Every dashboard needs a unique layout structure and at least one domain-specific
 
 ## Map Layout
 
-GeoMap should be placed in a **wide/narrow grid** (`lg:grid-cols-3` with `lg:col-span-2`), not full-width hero. Full-width maps dominate the page and waste space.
+**Default pattern:** GeoMap in a **wide/narrow grid** (`lg:grid-cols-3` with `lg:col-span-2`). This works well for dashboards where the map is one of several equal-weight sections.
+
+**If the PRD specifies a "visualization-hero" layout**, the map is full-width hero with glass overlays. The PRD always overrides this default pattern.
 
 **Pattern: Map + sidebar at matched height**
 
@@ -584,37 +586,11 @@ Before finishing a dashboard page, verify ALL of these:
 - [ ] **Imports only from `@/components/library`** — no shadcn, no Lucide, no `cn()`
 - [ ] **Grid patterns match the approved list** — no custom grid layouts
 
-## Post-Completion Verification (REQUIRED — MUST RUN BEFORE REPORTING DONE)
-
-After building the dashboard, you MUST run the validator and fix ALL errors before reporting the dashboard as complete:
-
-```bash
-# Run from the web app directory
-npm run validate:dashboard
-```
-
-**Do NOT run `npm run build` or `tsc`.** The TypeScript build has known issues with platform-only Salesforce packages that are not relevant to dashboard development. Only run the validator.
-
-The validator (`scripts/validate-dashboard.sh`) automatically checks for:
-- Hand-rolled HTML cards, tables, and SVGs (must use library components)
-- Forbidden colors (`text-black`, `text-white`, `bg-black`)
-- Inline `style={{}}` and `<style>` tags
-- Missing `useDataSource` for sample/live mode
-- Grid layouts with 5+ columns
-- `position: fixed` without `createPortal`
-- shadcn/Lucide imports in command center code
-- Missing `space-y-6` wrappers
-- `.jsx` files where `.tsx` is required (this is a TypeScript project)
-- Dashboard navigation (`<nav>` elements)
-
-**If the validator reports errors, you MUST fix them ALL — zero errors required.** Do not report the dashboard as complete with any errors. Do not dismiss errors as "acceptable", "justified", or "expected". Every error has a fix — usually by switching to the correct library component. The validator exits with code 1 on errors — treat this like a failing test.
+## Post-Completion Verification
 
-**Common validator errors and their fixes:**
-- **Hand-rolled card** → Wrap content in `WidgetCard`, `ListCard`, `BaseCard`, or another library card component. `WidgetCard` with a single section can wrap any arbitrary JSX content.
-- **Forbidden colors** (`text-white`, `bg-black`) → Use slate scale (`text-slate-50`, `bg-slate-900`)
-- **shadcn/Lucide imports** → Replace with library components and Heroicons
+**DO NOT run `npm run validate:dashboard`, `npm run dev`, `npm run build`, or `tsc` during builds.** These waste time and are not required for phase completion.
 
-**Do not skip or ignore the validator.** Do not run `npm run build` or `tsc` — only run `npm run validate:dashboard`.
+Instead, verify correctness by reviewing the code against the Pre-Completion Checklist above. Confirm that all three wiring files are updated (CommandCenter.tsx, Home.tsx, routes.tsx).
 
 ## Anti-Patterns (never do these)
 

package/.a4drules/skills/command-center-builder/completion-checklist.md

@@ -19,37 +19,11 @@ Before finishing a dashboard page, verify ALL of these:
 - [ ] **Imports only from `@/components/library`** — no shadcn, no Lucide, no `cn()`
 - [ ] **Grid patterns match the approved list** — no custom grid layouts
 
-## Post-Completion Verification (REQUIRED — MUST RUN BEFORE REPORTING DONE)
+## Post-Completion Verification
 
-After building the dashboard, you MUST run the validator and fix ALL errors before reporting the dashboard as complete:
+**DO NOT run `npm run validate:dashboard`, `npm run dev`, `npm run build`, or `tsc` during builds.** These waste time and are not required for phase completion.
 
-```bash
-# Run from the web app directory
-npm run validate:dashboard
-```
-
-**Do NOT run `npm run build` or `tsc`.** The TypeScript build has known issues with platform-only Salesforce packages that are not relevant to dashboard development. Only run the validator.
-
-The validator (`scripts/validate-dashboard.sh`) automatically checks for:
-- Hand-rolled HTML cards, tables, and SVGs (must use library components)
-- Forbidden colors (`text-black`, `text-white`, `bg-black`)
-- Inline `style={{}}` and `<style>` tags
-- Missing `useDataSource` for sample/live mode
-- Grid layouts with 5+ columns
-- `position: fixed` without `createPortal`
-- shadcn/Lucide imports in command center code
-- Missing `space-y-6` wrappers
-- `.jsx` files where `.tsx` is required (this is a TypeScript project)
-- Dashboard navigation (`<nav>` elements)
-
-**If the validator reports errors, you MUST fix them ALL — zero errors required.** Do not report the dashboard as complete with any errors. Do not dismiss errors as "acceptable", "justified", or "expected". Every error has a fix — usually by switching to the correct library component. The validator exits with code 1 on errors — treat this like a failing test.
-
-**Common validator errors and their fixes:**
-- **Hand-rolled card** → Wrap content in `WidgetCard`, `ListCard`, `BaseCard`, or another library card component. `WidgetCard` with a single section can wrap any arbitrary JSX content.
-- **Forbidden colors** (`text-white`, `bg-black`) → Use slate scale (`text-slate-50`, `bg-slate-900`)
-- **shadcn/Lucide imports** → Replace with library components and Heroicons
-
-**Do not skip or ignore the validator.** Do not run `npm run build` or `tsc` — only run `npm run validate:dashboard`.
+Instead, verify correctness by reviewing the code against the Pre-Completion Checklist above. Confirm that all three wiring files are updated (CommandCenter.tsx, Home.tsx, routes.tsx).
 
 ## Anti-Patterns (never do these)