@schandlergarcia/sf-web-components 1.9.67 → 1.9.69

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

@@ -1,125 +1 @@
-## Core Conventions
-
-The following conventions apply to all dashboard development in this project.
-
-1. **Write `.tsx` files** in `src/pages/` and update `CommandCenter.tsx` to import the dashboard. This is a TypeScript project — all React components use `.tsx` extension.
-
-2. **Use ONLY library components** from `@/components/library` for all cards, charts, tables, lists, and feeds. The library has 30+ components — there is no reason to hand-roll HTML. See the component table below.
-
-3. **No navigation inside the dashboard.** No `<nav>`, no header bar, no tab bar acting as page-level navigation. The app shell handles navigation. Your dashboard starts with content.
-
-4. **Max 4 MetricCards per row.** Never 5. Split into two rows if needed.
-
-5. **All charts use `ChartCard` + `D3Chart` or `GeoMap`.** No Recharts, no Chart.js, no custom SVG, no canvas, no hand-drawn paths. The only charting tools allowed are `D3Chart` (with `D3ChartTemplates` or a custom `renderChart` function) and `GeoMap`.
-
-6. **Never `npm install` Salesforce packages.** The `@salesforce/*` packages are platform-provided via broken symlinks. They are stubbed in `src/stubs/` and aliased in `vite.config.ts`. Do not try to install them — they don't exist on npm. If you see a TypeScript error about `@salesforce/vite-plugin-webapp-experimental`, ignore it — the build still succeeds via `vite build` (the `tsc` error is in `vite.config.ts` which is handled separately by `tsconfig.node.json`).
-
-## Use Library Components — Not Hand-Rolled HTML Cards
-
-The component library (`@/components/library`) provides pre-built, themed, dark-mode-ready cards for every common dashboard need. Use them instead of writing raw `<div>` cards with custom classes.
-
-### Before writing ANY card-like UI, check this table:
-
-| Need | MUST use | NEVER do |
-|------|----------|----------|
-| 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 | `ActivityCard` or `FeedPanel` | `<div>` with hand-rolled interaction rows |
-| 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 |
-| Status items | `StatusCard` | `<div>` with custom status badges |
-| Text summary | `NarrativeSummary` / `SectionCard` | `<div>` with headings and paragraphs |
-| Alert / callout | `CalloutCard` | Custom banner div |
-
-Every visible section of a dashboard should be a library component. If you're writing `<div className="bg-white border rounded-[10px] shadow-sm p-6">` with content inside, that's a hand-rolled card — use a library component instead.
-
-### Correct example:
-
-```jsx
-import { MetricCard, ListCard, ActivityCard, WidgetCard } from "@/components/library";
-
-// KPIs — use MetricCard
-<MetricCard title="Active Travelers" value={6} subtitle="Currently traveling" />
-
-// List — use ListCard with items array
-<ListCard title="Trip Activity" items={trips.map(t => ({
-  id: t.id, title: t.hotel, description: `${t.city} · ${t.dates}`,
-  status: t.status, avatar: t.travelerInitials
-}))} />
-
-// Activity feed — use ActivityCard
-<ActivityCard title="Eva — Recent Interactions" items={interactions.map(i => ({
-  id: i.id, title: i.traveler, description: i.query,
-  status: i.status, timestamp: i.time
-}))} />
-
-// Stats panel — use WidgetCard
-<WidgetCard title="Company Activity">
-  {/* structured content */}
-</WidgetCard>
-```
-
-### Wrong example (hand-rolled HTML):
-
-```jsx
-// ❌ NEVER DO THIS — this is a hand-rolled card
-<div className="bg-white border border-engine-border rounded-[10px] shadow-sm">
-  <div className="p-6 border-b border-engine-border">
-    <h2 className="text-lg font-semibold">Trip Activity</h2>
-  </div>
-  <div className="p-6 space-y-4">
-    {trips.map(trip => (
-      <div key={trip.id} className="flex gap-4 p-4 rounded-lg border ...">
-        ...
-      </div>
-    ))}
-  </div>
-</div>
-```
-
-## Images
-
-The only image allowed in dashboards is the **company logo**: `src/assets/images/engine_logo.png`. Import it as a module and use it where a logo is needed (nav header, branding, etc.).
-
-```jsx
-import engineLogo from "@/assets/images/engine_logo.png";
-
-<img src={engineLogo} alt="Engine" className="h-8 w-auto" />
-```
-
-- **Do not use external image URLs** (Unsplash, placeholder services, etc.) unless the user explicitly requests images.
-- **Do not use other asset images** (codey-*.png, etc.) unless the user asks for them.
-- **Preserve aspect ratio** — always use `w-auto` with a fixed height, or `h-auto` with a fixed width. Never set both `w-*` and `h-*` to fixed values on the logo or any image, as this distorts the aspect ratio.
-
-```jsx
-// ✅ Correct — aspect ratio preserved
-<img src={engineLogo} alt="Engine" className="h-8 w-auto" />
-<img src={engineLogo} alt="Engine" className="w-24 h-auto" />
-
-// ❌ Wrong — aspect ratio distorted
-<img src={engineLogo} alt="Engine" className="w-8 h-8" />
-<div className="w-8 h-8 bg-black rounded" />  // placeholder box instead of logo
-```
-
-## No Dashboard-Level Navigation
-
-Dashboard pages must NOT include their own `<nav>`, header bar, or top navigation of any kind. Navigation is handled by `appLayout.tsx`. The dashboard renders inside the app shell — adding a nav inside the dashboard creates a duplicate header, which is the most visually obvious mistake.
-
-- ❌ `<nav className="bg-white border-b ...">` inside a dashboard page
-- ❌ A header bar with logo + nav links + user avatar inside the dashboard
-- ❌ Tab bars that act as top-level navigation (Overview, Travelers, Spend, etc.)
-- ❌ `useState("overview")` / `useState("travelers")` to toggle between views — this IS tab navigation even without a `<nav>` element
-- ❌ `{activeView === "overview" && (...)}` / `{activeView === "travelers" && (...)}` — content-swapping IS multi-tab navigation
-- ✅ Dashboard starts directly with content (metrics, then primary content)
-- ✅ If you need sub-sections, use the library `Tabs` component **inside a card** — not as a full-width page-level switcher
-- ✅ Build a single-page dashboard — all content visible by scrolling. Do NOT split into multiple tab "pages" that swap content.
-
-**Self-check:** If your dashboard has `useState` for an "active tab" or "active view" that conditionally renders different page sections, you are building multi-tab navigation. Delete it and put all content on one scrollable page.
-
-**Self-check:** If your dashboard JSX starts with `<nav>`, a sticky tab bar, or a `<div>` that spans the full width with nav links, you are violating this rule. Delete it.
-
-### Why no multi-tab dashboards?
-
-Splitting a dashboard into 5 tab "pages" (Overview, Travelers, Spend, Policy, Eva) means each tab is a separate mini-app. This violates the single-page dashboard pattern. Instead, put **all sections on one scrollable page** using the vertical page structure (metrics → primary content → secondary content). If content is too long, prioritize the most important sections and use cards with `maxBodyHeight` to constrain tall sections.
-
+See SKILL.md — Core Conventions, Library Components, Images, Navigation sections.

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

@@ -1,30 +1 @@
-# Dashboard Build Process
-
-## 4-Phase Build
-
-Build dashboards in 4 distinct phases. Each phase has a dedicated instruction file with a code template in `.a4drules/phases/`:
-
-| Phase | File | Goal | Output |
-|-------|------|------|--------|
-| 1 | `phase-1-layout.md` | Layout & structure | Skeleton with placeholders |
-| 2 | `phase-2-components.md` | Components & sample data | Fully functional UI with mock data |
-| 3 | `phase-3-live-data.md` | Real data integration | Dashboard connected to Salesforce |
-| 4 | `phase-4-agent.md` | Agentforce integration | Eva agent + Salesforce signals |
-
-Each phase file is self-contained — it includes the code template, exact imports, and the 5 constraints that matter for that phase. No cross-references needed.
-
-## Why This Works
-
-- Each phase has a single focus
-- Code templates mean less interpretation, faster builds
-- Self-contained files eliminate contradictions
-- Can stop after any phase (Phase 2 is a complete demo on its own)
-
-## Build Prompts
-
-Each phase is triggered by a simple prompt:
-
-- Phase 1: "Scaffold the Engine Travel Command Center skeleton"
-- Phase 2: "Replace placeholders with library components and sample data"
-- Phase 3: "Connect the dashboard to live Salesforce data"
-- Phase 4: "Add Eva ChatBar and Salesforce signals"
+See the PRD (engine-command-center-prd.md) section 13 for the 4-phase build process.

package/.a4drules/skills/command-center-builder/page-layout.md

@@ -1,145 +1 @@
-## Where Dashboards Live & How to Wire Them
-
-- Dashboard page files: `src/pages/` (e.g. `EngineDashboard.tsx`, `FleetDashboard.tsx`)
-- File format: `.tsx` (MUST be TypeScript) — this is a TypeScript project, all React components use `.tsx`.
-- `CommandCenter.tsx` wraps with `AppThemeProvider` + `DataModeProvider` + `Toaster`. **Never recreate these providers in dashboard pages.**
-
-### Wiring a new dashboard (REQUIRED STEPS)
-
-You must do ALL of these or the dashboard will not render correctly:
-
-**Step 1:** Create the dashboard file in `src/pages/`:
-```tsx
-// src/pages/MyDashboard.tsx
-import React from "react";
-import { MetricCard, ListCard, ChartCard, D3Chart } from "@/components/library";
-
-export default function MyDashboard() {
-  return (
-    <div className="space-y-6 p-6">
-      {/* dashboard content using library components */}
-    </div>
-  );
-}
-```
-
-**Step 2:** Update `CommandCenter.tsx` to import and render it:
-```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
-
-export default function CommandCenter() {
-  return (
-    <AppThemeProvider initialMode="light">
-      <DataModeProvider initialMode="sample">
-        <MyDashboard />                   {/* ← change this */}
-        <Toaster position="bottom-right" />
-      </DataModeProvider>
-    </AppThemeProvider>
-  );
-}
-```
-
-**Step 2.5:** Update `Home.tsx` to render `CommandCenter`:
-```tsx
-// src/pages/Home.tsx
-import CommandCenter from "@/components/workspace/CommandCenter";
-
-export default function HomePage() {
-  return <CommandCenter />;
-}
-```
-
-**Step 3:** Update `src/routes.tsx` to make the dashboard the home page. Replace the Search page index route with the Home/CommandCenter route:
-```tsx
-// src/routes.tsx — change the index route
-{
-  index: true,
-  element: <SuspenseWrap><Home /></SuspenseWrap>,
-  handle: { showInNavigation: true, label: 'Dashboard' }
-},
-{
-  path: "search",
-  element: <SuspenseWrap><Search /></SuspenseWrap>,
-  handle: { showInNavigation: true, label: 'Search' }
-},
-```
-
-The `Home` page renders `CommandCenter`, which renders your dashboard. The Search page moves to `/search`.
-
-**Verify:** After writing all files, confirm:
-1. Your dashboard `.tsx` file exists in `src/pages/`
-2. `CommandCenter.tsx` (in `src/components/workspace/`) imports your dashboard (not `BlankDashboard`)
-3. `Home.tsx` (in `src/pages/`) imports and renders `CommandCenter` (not search interface)
-4. `src/routes.tsx` has `Home` as the index route and `Search` at `/search`
-
-## Page Structure
-
-Every page follows this vertical order — never rearrange:
-1. Context (NarrativeSummary or heading) — optional
-2. KPI metrics (MetricsStrip or MetricCard grid) — required for dashboards
-3. Primary content (tables, charts, status)
-4. Secondary content (lists, logs, supporting data) — optional
-5. Actions — optional
-
-Wrap all page content in `<div className="space-y-6">`. Do NOT use `mb-6` between sections — the wrapper handles spacing.
-
-## Layout Grids
-
-Only these grid patterns — do not invent new ones:
-
-- **4 metrics (MAXIMUM per row — never 5 or more):** `grid grid-cols-2 gap-3 lg:grid-cols-4`
-- **3 metrics:** `grid grid-cols-1 gap-3 sm:grid-cols-3`
-- **Wide/narrow split:** `grid grid-cols-1 items-start gap-4 lg:grid-cols-3` with `lg:col-span-2` on the wide side
-- **3-col balanced:** `grid grid-cols-1 items-start gap-4 lg:grid-cols-3`
-- **Equal two-col:** `grid grid-cols-1 items-start gap-4 lg:grid-cols-2`
-- **Full-width:** `<div className="w-full">` — charts with 24+ data points
-
-`gap-4` for content grids, `gap-3` for metric rows. Start `grid-cols-1` (or `grid-cols-2` for metrics) for mobile. Only `sm:` and `lg:` breakpoints unless justified.
-
-**Max 4 KPIs per row — NEVER 5 or more.** If you have 5+ metrics, split into two rows (e.g. 4 + 1, or 3 + 2). Always `items-start` on grids pairing different-height cards. Use `maxBodyHeight={px}` for long card bodies. Actions go in card `actions` slot. Place `FilterBar` near the data it controls.
-
-## Layout Differentiation
-
-Every dashboard needs a unique layout structure and at least one domain-specific "signature element" that couldn't exist in another dashboard. Vary section ordering, grid proportions, density, and visual rhythm.
-
-## Map Layout
-
-**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.
-
-**Default pattern: Map + sidebar at matched height**
-
-```jsx
-<div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
-  <div className="lg:col-span-2 relative overflow-hidden rounded-xl h-[300px]">
-    <GeoMap
-      markers={locations}
-      arcs={arcs}
-      overlays={overlays}
-      initialBounds={{ sw: [-130, 24], ne: [-65, 50], padding: 30 }}
-      theme="dark"
-      width={960}
-      height={480}
-      zoomable
-      className="h-full w-full"
-    />
-  </div>
-  {/* Sidebar card — use maxBodyHeight to match map height */}
-  {/* Map h-[300px] ≈ ListCard maxBodyHeight={236} + ~64px header */}
-  <ListCard title="Activity" items={items} maxBodyHeight={236} showStatus />
-</div>
-```
-
-Key rules:
-- **Do NOT wrap GeoMap in ChartCard** — GeoMap has its own background/borders
-- **Match heights** — set map `h-[Xpx]` and sidebar `maxBodyHeight` so they align. Account for ~64px card header padding.
-- **Use `initialBounds`** to auto-zoom to the region with data: `{ sw: [lonMin, latMin], ne: [lonMax, latMax], padding: 30 }`
-- **Always pass `arcs`** for flight routes and `overlays` for disruption zones — not just markers
-- **Use ListCard** (not ActivityCard) for the sidebar — ListCard supports `maxBodyHeight` for scroll, ActivityCard does not
-- Keep map height at 280–320px — not 400+
-
+See SKILL.md — Wiring, Page Structure, Layout Grids, Map Layout sections.

package/CHANGELOG.md

@@ -5,7 +5,7 @@ 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.67] - 2026-04-01
+## [1.9.69] - 2026-04-01
 
 ### Fixed
 - **6 data bugs in engine-sample-data.js**:
@@ -17,27 +17,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   6. Updated TXL → BER throughout (Berlin airport code change)
 
 ### Updated
-- **PRD (engine-command-center-prd.md)**:
-  - Fixed "Sarah Chen" → "Priya Patel" in section 8c escalation example
-  - Rewrote section 13 build prompts to sound natural (removed AI coaching language)
-  - Removed "Required skills:" line from header
+- **Global styles** - Added `src/styles/global.css` with Engine brand tokens and command center styling
+
+- **PRD (engine-command-center-prd.md)** - Updated to match actual built dashboard:
+  - Layout diagram now shows 4-section structure: Header → Hero Map → Eva ChatBar → Data Panels (was missing ChatBar section)
+  - Layout classes added Eva: `<div className="px-4 pt-4">` as distinct section
+  - Section 6 (Header): Explicitly says "No ChatBar in the header — Eva lives below the map." Added "Powered by Agentforce" badge description
+  - Section 7 (Hero Map): Added explicit KPI label styling (`text-[10px] font-medium uppercase tracking-wide text-slate-300`) and value/pill/icon specs
+  - Section 8a (Escalations): Replaced ActivityCard with custom inline panel in BaseCard. Added full code example with status icons (CheckCircleIcon/ArrowPathIcon/ClockIcon), conditional "Assign to Agent" buttons, and toast.success
+  - Section 8c (Active Travelers): Added "View in Salesforce" link in expanded detail
+  - Section 9 (Eva): Completely rewritten - ChatBar is now between map and data panels, full-width, with phasing notes (Phase 1 = skip, Phase 4 = add)
+  - Section 10 (Signals): Added "Assigned to Eva" toast row for Assign to Agent button
+  - Phase 4 build prompt: Updated to say "Add Eva below the map as a ChatBar" and mention "Assign to Agent" buttons on open escalations
+  - Applied Option A layout: Escalations + Disruptions in Row 1 (above fold), Active Travelers + Spend in Row 2
+  - Both rows use `lg:grid-cols-3` with left panel at 2/3 width
+  - Removed all "TDX26" and "demo" references
+  - Cut Section 14 "What NOT to Do" entirely
+  - Condensed Phase 1 placeholder rules from 75 to 8 lines
+
+- **Builder skill (SKILL.md)** - Fixed 4 contradictions:
+  - Component table: Split "Activity feed" into two rows: "display only" → ActivityCard, "with per-item actions" → custom markup in BaseCard
+  - Component selection table: Same split applied
+  - AI Chat & Agent section: Added bullet: "Place ChatBar between the hero map and data panels, NOT in the header"
+  - Pre-Completion Checklist: Added exception: panels needing per-item action buttons can use custom markup inside BaseCard
+  - General library component rule: Added exception note for per-item action buttons
+  - Removed wrong-example code blocks, condensed navigation (40 → 2 lines), removed custom renderChart examples, cut anti-patterns (33 → 12 items)
+
+- **Builder skill sub-files** - Replaced with single-line redirects:
+  - 7 files reduced from 630 total lines to 7 lines (100% duplicates eliminated)
+
 - **Simplified .a4drules documentation** - Removed redundancy, contradictions, and AI coaching language:
-  - `features/engine-dashboard-rule.md` - Rewritten as "Project Conventions" (reduced from 310 to ~65 lines)
+  - `features/engine-dashboard-rule.md` - Rewritten as "Project Conventions" (~65 lines)
   - `features/command-center-dashboard-rule.md` - Rewritten as slim conventions (~30 lines)
-  - `features/pre-code-checklist.md` - Rewritten as "Quick Reference" (~25 lines, removed auto-load)
+  - `features/pre-code-checklist.md` - Rewritten as "Quick Reference" (~25 lines)
   - `features/phase2-data-pattern.md` - Rewritten as "Sample Data" documentation (~20 lines)
-  - `skills/command-center-builder/SKILL.md` - Fixed map contradiction, removed validator contradiction, removed AI coaching language. Description now includes "Engine Travel Command Center", "scaffold", component names for better matching
-  - `skills/command-center-builder/page-layout.md` - Fixed map contradiction, softened wiring language
-  - `skills/command-center-builder/completion-checklist.md` - Removed validator contradiction
-  - `skills/command-center-builder/improved-build-process.md` - Rewritten as methodology description (~30 lines)
-  - `skills/command-center-builder/getting-started.md` - Removed AI coaching language
-  - `skills/command-center-builder/components-styling.md` - Removed (MANDATORY) header
-  - `skills/command-center-builder/charts-visualization.md` - Removed (MANDATORY) header
-  - `skills/command-center-project/SKILL.md` - Fixed file path contradiction (src/components/pages/ → src/pages/). Description now includes "Engine Travel Command Center", tech stack keywords
-  - `skills/command-center-guide/SKILL.md` - Reduced from 270 to ~45 lines (simplified routing guide). Description improved for better matching
-  - `skills/component-library/SKILL.md` - Description now lists all key component names (MetricCard, ChartCard, GeoMap, etc.) for better matching
-
-**Context:** Complete documentation overhaul to eliminate confusion from scattered, contradictory guidance. Removed prescriptive AI coaching language in favor of clear technical conventions. Improved skill descriptions for better discoverability.
+  - `skills/command-center-project/SKILL.md` - Fixed file path contradiction
+  - `skills/command-center-guide/SKILL.md` - Reduced from 270 to ~45 lines
+  - `skills/component-library/SKILL.md` - Description now lists all key component names
+
+**Context:** PRD now accurately reflects the actual built dashboard with Eva ChatBar between map and data panels. Eliminated contradictions about ActivityCard vs custom markup for action buttons.
+
+## [1.9.68] - 2026-04-01
+
+### Updated
+- **Major documentation consolidation** - PRD reduced 39%, builder skill sub-files eliminated duplication, overall .a4drules reduced from ~2000 to ~800 lines
+
+## [1.9.67] - 2026-04-01
+
+### Updated
+- **Skill descriptions** - Improved for better discoverability and matching
 
 ## [1.9.66] - 2026-04-01