@schandlergarcia/sf-web-components 1.9.48 → 1.9.52

package/.a4drules/skills/component-library/SKILL.md

@@ -1,13 +1,16 @@
 ---
 name: component-library
-description: Complete reference for the Command Center component library. Every component, its exact props, data shapes, and when to use it. This is the authoritative source — do not guess prop names or data formats.
+description: >-
+  Complete reference for the Command Center component library. Every component,
+  its exact props, data shapes, and when to use it. This is the authoritative
+  source — do not guess prop names or data formats.
 ---
 
-# Component Library Reference
+# Component Library
 
 Location: `src/components/library/`. Barrel export: `@/components/library`.
 
-Vendored from command-center-starter. **Do not modify library files.**
+Vendored from command-center-starter. Do not modify library files.
 
 ## Import Pattern
 
@@ -23,33 +26,1003 @@ import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
 import type { MetricCardProps } from "@/components/library";
 ```
 
-## Documentation Structure
+---
+
+## When to Use Each Component
+
+| I need to show… | Use this | NOT this |
+|---|---|---|
+| A single KPI number | `MetricCard` | Custom div with big number |
+| A row of 2–4 KPIs | Grid of `MetricCard` | `MetricsStrip` (for compact inline) |
+| A data table | `TableCard` | `<table>` HTML |
+| A scrollable item list | `ListCard` | Custom divs with `.map()` |
+| An activity log with status icons | `ActivityCard` | ListCard (no status icons) |
+| A chart (line, bar) | `ChartCard` + `D3Chart` | Raw `<svg>` |
+| A donut/pie chart | `ChartCard` + `D3Chart` + custom renderChart | Any chart library |
+| A world map with markers | `GeoMap` (direct, no ChartCard wrapper) | react-simple-maps |
+| A callout/alert banner | `CalloutCard` | Custom colored div |
+| A section heading | `SectionCard` | `<h2>` with custom styling |
+| A multi-section panel | `WidgetCard` | Nested divs |
+| Custom interactive content (expand/collapse, inline details) | `WidgetCard` (single section with arbitrary JSX) | Hand-rolled `<div className="bg-white border rounded...">` |
+| System health status | `StatusCard` | Custom status badges |
+| A sidebar feed | `FeedPanel` | Custom scrollable div |
+| A command-palette AI chat | `ChatBar` | ChatPanel (that's for full-page) |
+| A full-page AI chat | `ChatPanel` | ChatBar |
+| Action buttons | `ActionList` or `UIButton` | Raw `<button>` |
+| Loading placeholder | `CardSkeleton` | Custom skeleton divs |
+| Empty state | `EmptyState` | Custom centered text |
+| A form dialog | `FormModal` | Raw `Modal` + custom form |
+| Inline form | `FormRenderer` + `useFormState` | Manual state + raw inputs |
+| Filter bar with search/select/toggle | `FilterBar` | Custom filter UI |
+| Progress indicator (linear) | `ProgressBar` | Custom div with width% |
+| Progress indicator (circular) | `ProgressCircle` | Custom SVG circle |
+| Collapsible sections | `Accordion` | Custom show/hide divs |
+| Side panel / drawer | `Drawer` | Custom fixed-position div |
+| Dropdown menu | `Dropdown` | Custom popover |
+| Tooltip | `Tooltip` | Custom hover div |
+| Toast notification | `toast()` function | Custom notification div |
+| Keyboard shortcut display | `Kbd` | Custom `<kbd>` element |
+| Scrollable container with fade | `ScrollShadow` | Custom overflow div |
+| Tab switching inside a card | `Tabs` | Custom tab implementation |
+
+---
+
+## Card Components
+
+### MetricCard
+**When:** Display a single KPI value (revenue, count, percentage).
+
+```jsx
+<MetricCard
+  title="Active Travelers"       // label
+  value={6}                       // main display value (any)
+  subtitle="Currently on trips"   // secondary text
+  change="+5.2%"                  // change amount string
+  changeType="positive"           // "positive" | "negative" | "neutral"
+  icon={<UsersIcon className="h-5 w-5 text-engine-teal" />}
+  color="default"                 // "default" | "primary" | "success" | "warning" | "danger"
+  trend="vs last month"           // trend label text
+  layout="default"                // "default" | "compact"
+  footer={<span>...</span>}       // bottom content
+  actions={<button>...</button>}  // top-right actions
+  loading={false}
+/>
+```
+**Mistakes:** ❌ `changeValue` → use `change`. ❌ `trend="positive"` → `trend` is a label, use `changeType`.
+
+### ChartCard
+**When:** Wrap a D3Chart visualization in a titled card.
+
+```jsx
+<ChartCard
+  title="Spend Trend"
+  subtitle="Last 30 days"
+  height={280}                    // container height px (default 280)
+  chart={<D3Chart ... />}         // ReactNode — the chart (REQUIRED, via prop not children)
+  legend={<div>...</div>}         // below chart
+  chartType="Line Chart"          // chip label
+  filters={<SelectFilter ... />}  // header filters
+  timeRange={{ current: "30d", options: ["7d","30d","90d"], onChange: fn }}
+/>
+```
+**Critical:** Pass chart via `chart={}` prop. Height sets CSS on container — match with D3Chart `height`.
+**Do NOT use for GeoMap** — GeoMap renders directly without a card wrapper.
+**Do NOT pass Recharts/Chart.js components** — only `D3Chart` is allowed.
+
+### TableCard
+**When:** Display tabular data with sorting, search, pagination.
+
+```jsx
+<TableCard
+  title="Travelers"
+  subtitle="6 active"
+  data={[{ id: "1", name: "Maya", cost: 2840, status: "Active" }]}
+  columns={[
+    { key: "name", label: "Name" },
+    { key: "cost", label: "Cost", type: "currency" },
+    { key: "status", label: "Status", render: (value, row) => <span>{value}</span> },
+  ]}
+  searchable       // shows search input
+  sortable         // clickable column headers
+  paginated        // pagination controls
+  pageSize={10}
+  rowActions={(row) => <button>View</button>}
+  onRowSelect={(row) => console.log(row)}
+  emptyMessage="No travelers found."
+/>
+```
+**Column types:** `"currency"` | `"percentage"` | `"number"` — auto-formatted, use before custom `render`.
+**`render` receives `(value, row)`** — NOT `(row)`. `value` = `row[column.key]`.
+
+### ListCard
+**When:** Display a scrollable list of items with avatars, status badges, timestamps.
+
+```jsx
+<ListCard
+  title="Active Trips"
+  items={[{
+    id: "1",
+    title: "Hotel Zephyr",          // or `name`
+    description: "San Francisco · Mar 23–26",
+    status: "Checked In",           // shown as badge
+    timestamp: "2 min ago",         // string or Date
+    avatar: undefined,                // omit to auto-generate initials from title/name
+    // avatar: "https://example.com/photo.jpg",  // URL string → renders <img>
+    // avatar: <Avatar initials="MR" />,          // ReactNode → renders inside circle
+    value: "$2,840",                // right-aligned
+    unit: "USD",                    // after value
+  }]}
+  maxBodyHeight={300}               // enables scroll (string or number)
+  showAvatars={true}
+  showStatus={true}
+  showTimestamp={true}
+  dense={false}
+  divided={true}
+  onItemClick={(item, index) => {}}
+  itemActions={(item, index) => <button>View</button>}
+  emptyMessage="No items."
+/>
+```
+
+### ActivityCard
+**When:** Show an activity log with animated status icons (working, pending, complete, error).
+
+```jsx
+<ActivityCard
+  title="Today's Activity"
+  actions={[                        // ⚠️ prop is "actions" NOT "items"
+    {
+      id: "1",                      // REQUIRED
+      status: "complete",           // REQUIRED: "working" | "pending" | "complete" | "error"
+      title: "Maya checked in",     // or `action` as fallback
+      subtitle: "Hotel Zephyr · SF",
+      timestamp: "2 min ago",       // or `startedAt`
+    },
+  ]}
+/>
+```
+**Returns `null`** if actions is empty. **No `maxBodyHeight`** — for scrollable feeds use `ListCard` instead.
+Status icons: `"complete"` → green check, `"working"` → spinning (indigo), `"pending"` → clock, `"error"` → red exclamation.
+
+### CalloutCard
+**When:** Highlight an alert, warning, or important notice.
+
+```jsx
+<CalloutCard
+  title="Late booking penalty"
+  tone="warning"                    // "neutral" | "success" | "warning" | "danger" | "info"
+  icon={<ExclamationTriangleIcon className="h-5 w-5" />}
+  message={                         // ⚠️ use `message` NOT children
+    <div>
+      <p>Priya Nair — Booking 2 days before departure</p>
+      <button onClick={handleApprove}>Approve</button>
+    </div>
+  }
+/>
+```
+**Mistakes:** ❌ `variant` → use `tone`. ❌ Children → use `message` prop.
+
+### SectionCard
+**When:** Display a prominent section heading or divider.
+
+```jsx
+<SectionCard
+  title="Eva · Agentforce Agent"
+  description="Powered by Agentforce"
+  label="LIVE"                      // small pill badge
+  variant="default"                 // "default" | "primary" | "secondary" | "accent"
+  size="md"                         // "sm" | "md" | "lg" | "xl"
+  isDark={false}
+/>
+```
+
+### WidgetCard
+**When:** Display multiple content sections in one card, OR wrap arbitrary custom interactive content (expand/collapse lists, inline detail panels, custom layouts) that doesn't fit other card types.
+
+**This is the go-to card when you need custom JSX inside a card container.** Each section's `content` accepts arbitrary React nodes — use this instead of hand-rolling `<div className="bg-white border rounded ...">`.
+
+**CRITICAL: WidgetCard does NOT accept children.** All content MUST go through the `sections` prop. If you write `<WidgetCard><div>...</div></WidgetCard>`, the children are silently ignored and the card renders "No sections." instead.
+
+**Padding:** BaseCard already applies `p-4` around all content (header + body). Do NOT add extra `p-5`, `p-6`, etc. to your `header` or section `content` — it will cause double padding. If you need edge-to-edge content inside a section (like a divided list), use negative margins or set `padding="none"` on the card.
+
+```jsx
+// ❌ WRONG — children are ignored, shows "No sections."
+<WidgetCard>
+  <div>This content will NOT render</div>
+</WidgetCard>
+
+// ✅ CORRECT — content goes in sections prop
+<WidgetCard
+  sections={[{ id: "main", content: <div>This content WILL render</div> }]}
+/>
+
+// Multi-section panel
+<WidgetCard
+  header={<div>Custom header</div>}
+  sections={[
+    { id: "1", title: "Section A", content: <div>...</div>, actions: <button>...</button> },
+    { id: "2", title: "Section B", content: <div>...</div> },
+  ]}
+  footer={<div>Footer</div>}
+  divided={true}                    // border between sections
+  collapsible={false}
+/>
+
+// Single-section wrapper for custom interactive content (e.g., expandable list)
+// NOTE: BaseCard already applies p-4 padding — do NOT add extra p-* to header/section content
+<WidgetCard
+  header={<h2 className="text-lg font-semibold text-engine-text">Active Travelers</h2>}
+  sections={[{
+    id: "travelers",
+    content: (
+      <div className="divide-y divide-engine-border">
+        {travelers.map(t => (
+          <div key={t.id} onClick={() => toggle(t.id)}>
+            {/* collapsed row + expanded details — any JSX works here */}
+          </div>
+        ))}
+      </div>
+    ),
+  }]}
+/>
+```
+
+### StatusCard
+**When:** Show system health or service status with colored indicators.
+
+```jsx
+<StatusCard
+  title="System Health"
+  status="operational"              // "operational" | "degraded" | "outage" | "maintenance"
+  items={[
+    { id: "1", title: "API", status: "operational" },
+    { id: "2", title: "Database", status: "degraded", description: "High latency" },
+  ]}
+  layout="list"                     // "list" | "grid" | "timeline"
+  showProgress={true}               // shows % operational bar
+/>
+```
+Status aliases: `"ok"/"healthy"/"up"` → `"operational"`, `"warn"` → `"degraded"`, `"down"/"critical"` → `"outage"`.
+
+### FeedPanel
+**When:** Sidebar-style scrollable feed with fixed header.
+
+```jsx
+<FeedPanel title="Notifications" subtitle="3 new" width={320}>
+  {children}
+</FeedPanel>
+```
+
+### MetricsStrip
+**When:** Compact horizontal row of metrics (inline, not cards).
+
+```jsx
+<MetricsStrip
+  title="Overview"
+  metrics={[
+    { label: "Users", value: "1,234", trend: "+5%" },
+    { label: "Revenue", value: "$45K", trend: "-2%" },
+  ]}
+  collapsible={false}
+/>
+```
+
+### ActionList
+**When:** Row of action buttons.
+
+```jsx
+<ActionList
+  title="Quick Actions"
+  actions={[{ label: "Approve" }, { label: "Deny" }, { label: "Defer" }]}
+  onAction={(action) => console.log(action.label)}
+/>
+```
+
+---
+
+## Chart Components
+
+### D3Chart
+**When:** Render any D3 visualization inside a ChartCard.
+
+```jsx
+<D3Chart
+  data={dataArray}
+  renderChart={D3ChartTemplates.lineChart}  // function — NOT template prop
+  options={{ xKey: "x", yKey: "y", stroke: "#5BC8C8" }}
+  responsive={true}
+  height={280}
+/>
+```
+**`renderChart` signature:** `(svgEl, data, { width, height }, options) => void`
+
+### D3ChartTemplates
+
+Only **two** built-in templates:
+
+**`lineChart`** — `{ xKey, yKey, stroke, strokeWidth, margin, showAxes, showGrid }`
+- Data: `[{ x: 1, y: 100 }]` — **numeric x required**
+
+**`groupedBarChart`** — `{ xKey, groups, colors, barRadius, margin, yFormat, showGrid }`
+- Data: `[{ x: "Jan", Hotels: 12000, Flights: 8000 }]` — **categorical x**
+
+For donut, horizontal bar, area chart, etc. → write a custom `renderChart(svgEl, data, dims)` function using d3.
+
+### GeoMap
+**When:** Show a world map with markers, flight arcs, and overlays.
+
+```jsx
+<GeoMap
+  markers={[{ id: "sf", lon: -122.4, lat: 37.8, active: true, label: "SF" }]}
+  arcs={[{ id: "a1", from: [-122.4, 37.8], to: [-74.0, 40.7], progress: 0.65 }]}
+  overlays={[{ id: "wx1", center: [-97.7, 30.3], radius: 3 }]}
+  initialBounds={{ sw: [-130, 24], ne: [-65, 50], padding: 30 }}
+  theme="dark"
+  width={960} height={480}
+  zoomable
+  className="h-full w-full"
+/>
+```
+**Do NOT wrap in ChartCard.** Render directly in `<div className="relative overflow-hidden rounded-xl h-[300px]">`.
+Arc `danger: true` renders in red. Arc `progress` (0–1) shows animated dot along route.
+
+---
+
+## UI Primitives
+
+### UIButton
+```jsx
+<UIButton variant="primary" size="md" onClick={fn} disabled={false} fullWidth={false}>Label</UIButton>
+```
+Variants: `"primary"` | `"secondary"` | `"outline"` | `"ghost"`. Sizes: `"sm"` | `"md"` | `"lg"`.
+
+### UIText
+```jsx
+<UIText as="p" size="md" weight="medium" muted={false}>Text content</UIText>
+```
+Sizes: `"xs"` | `"sm"` | `"md"` | `"lg"` | `"xl"` | `"xxl"`. Weights: `"regular"` | `"medium"` | `"bold"`.
+
+### UIChip
+```jsx
+<UIChip tone="success" size="xs">Active</UIChip>
+```
+Tones: `"neutral"` | `"primary"` | `"success"` | `"warning"` | `"danger"`. Sizes: `"xs"` | `"sm"`.
+
+### Avatar
+```jsx
+<Avatar src="url" name="Maya R" size="md" tone="slate" />
+<Avatar initials="MR" size="sm" />
+<Avatar icon={<UsersIcon />} size="lg" tone="brand" />
+```
+Sizes: `"xs"` | `"sm"` | `"md"` | `"lg"`. Auto-generates initials from `name` if no `src`/`initials`/`icon`.
+
+### Spinner
+```jsx
+<Spinner size="md" tone="brand" label="Loading" />
+```
+Tones: `"brand"` | `"white"` | `"muted"` | `"current"`.
+
+### EmptyState
+```jsx
+<EmptyState icon={<RocketIcon />} heading="Nothing here" body="Add some data" action={<UIButton>Add</UIButton>} size="md" />
+```
+
+### UICard
+```jsx
+<UICard padding="p-5">{children}</UICard>
+```
+
+### UIContainer
+```jsx
+<UIContainer title="Section" subtitle="Description" actions={<button>Add</button>} empty={false} emptyText="Nothing yet">{children}</UIContainer>
+```
+
+### UIInput
+```jsx
+<UIInput placeholder="Enter text..." value={val} onChange={fn} type="text" />
+```
+
+### UIToggle
+```jsx
+<UIToggle label="Dark mode" />
+```
+Integrates with AppThemeProvider automatically.
+
+---
+
+## Filters
+
+### FilterBar
+```jsx
+<FilterBar
+  filters={[
+    { id: "search", type: "search", placeholder: "Search..." },
+    { id: "status", type: "select", label: "Status", options: ["All", "Active"] },
+    { id: "flagged", type: "toggle", label: "Flagged only" },
+  ]}
+  values={{ search: "", status: "All", flagged: false }}
+  onChange={(filterId, value) => {}}   // ⚠️ receives (filterId, value) NOT full state
+  onReset={() => {}}
+  layout="inline"                     // "inline" | "stacked"
+/>
+```
+
+---
+
+## Chat
+
+### ChatBar (command palette — use on dashboards)
+```jsx
+<ChatBar
+  title="Eva · Travel Assistant"
+  placeholder="Ask Eva..."
+  suggestions={["Show spend", "Who has flags?", "Active trips"]}
+  onSend={async (userMsg, allMessages, helpers) => {
+    // Return message object to add to chat:
+    return { role: "assistant", content: "Here's what I found..." };
+    // Or stream: helpers.addMessage, helpers.appendChunk, helpers.setStreaming
+  }}
+/>
+```
+
+### ChatPanel (full-page chat)
+```jsx
+<ChatPanel
+  title="AI Assistant"
+  onSend={async (userMsg, allMessages, helpers) => {
+    return { role: "assistant", content: "Reply" };
+  }}
+  suggestions={["Help me with...", "Show me..."]}
+  welcomeTitle="How can I help?"
+  welcomeSubtitle="Ask anything about your data."
+  showHeader={true}
+/>
+```
+
+### useChatState (standalone hook)
+```jsx
+import { useChatState } from "@/components/library";
+const chat = useChatState({ onSend: async (msg, history, helpers) => ({ role: "assistant", content: "Reply" }) });
+// chat.messages, chat.sendMessage(text), chat.isLoading, chat.clearMessages, chat.retryLast
+```
+
+---
+
+## Data
+
+### useDataSource (DEFAULT export)
+```jsx
+import useDataSource from "@/components/library/data/useDataSource";
+const data = useDataSource({ sample: SAMPLE_DATA, live: fetchLiveFn });
+```
+⚠️ **Default export** — `import { useDataSource }` will fail silently.
+
+### DataModeProvider
+Wraps app. Provides `useDataMode()` → `{ mode, isSample, isLive, toggle, setMode }`.
+
+---
+
+## Layout & Skeletons
+
+### PageContainer
+```jsx
+<PageContainer>{children}</PageContainer>
+```
+Centered `max-w-6xl` wrapper with padding.
+
+### CardSkeleton
+```jsx
+<CardSkeleton lines={3} />
+```
+Animated placeholder card for loading states.
+
+---
+
+## Forms
+
+### FormRenderer
+```jsx
+<FormRenderer
+  sections={[{ id: "s1", title: "Details", fields: [
+    { id: "name", type: "text", label: "Name", required: true },
+    { id: "dept", type: "select", label: "Department", options: ["Sales", "Eng"] },
+  ]}]}
+  values={{ name: "", dept: "" }}
+  errors={{}}
+  touched={{}}
+  onFieldChange={(fieldId, value) => {}}
+  onFieldBlur={(fieldId) => {}}
+/>
+```
+Field types: `text`, `email`, `url`, `number`, `date`, `textarea`, `select`, `radio`, `checkbox`, `checkboxGroup`, `toggle`.
+
+### FormModal
+**When:** Open a modal dialog with a schema-driven form (create or edit records).
+
+```jsx
+<FormModal
+  isOpen={showModal}
+  onClose={() => setShowModal(false)}
+  title="New Traveler"
+  subtitle="Add a traveler to the system"
+  sections={formSections}              // same schema as FormRenderer
+  initialValues={{ name: "Maya" }}     // prefill for edit mode; omit for create
+  onSubmit={async (values) => {}}      // async — modal auto-closes on success
+  submitLabel="Save"                   // default "Save"
+  cancelLabel="Cancel"                 // default "Cancel"
+  size="lg"                            // "sm" | "md" | "lg" | "xl"
+  destructive={false}                  // red submit button for deletions
+  minSubmitMs={4000}                   // min spinner duration ms
+/>
+```
+Renders via `createPortal` over a backdrop. Escape key dismisses. Wraps FormRenderer + useFormState internally.
+
+### FormSection & FormField
+Lower-level building blocks used by FormRenderer. Rarely needed directly.
+
+```jsx
+// FormSection — renders a titled group of fields in 2-col grid
+<FormSection section={sectionSchema} values={vals} errors={errs} touched={touched}
+  onFieldChange={(id, val) => {}} onFieldBlur={(id) => {}} />
+
+// FormField — renders a single labeled input
+<FormField field={fieldDef} value={val} error={errMsg} touched={true}
+  onChange={(val) => {}} onBlur={() => {}} />
+```
+
+### useFormState
+**When:** Manage form state without FormModal (inline forms, custom layouts).
+
+```jsx
+const form = useFormState({
+  initialValues: { name: "", dept: "" },
+  sections: formSections,              // schema — used for defaults + validation
+  onSubmit: async (values) => {},
+  minSubmitMs: 4000,                   // default 4000
+});
+
+// form.values, form.errors, form.touched
+// form.isDirty, form.isValid, form.isSubmitting
+// form.setValue(id, value), form.setValues(obj)
+// form.setTouched(id), form.validate(), form.reset()
+// form.handleSubmit(e)  — async, validates first, enforces minSubmitMs
+```
+Builds defaults from schema: `checkboxGroup` → `[]`, `toggle`/`checkbox` → `false`, others → `""`. Supports custom validators via `field.validate(value, allValues)`.
+
+---
+
+## Individual Filter Components
+
+FilterBar composes these internally, but they can also be used standalone:
+
+### SearchFilter
+```jsx
+<SearchFilter
+  value={searchText}
+  onChange={(text) => setSearchText(text)}
+  placeholder="Search travelers..."
+  className="w-64"
+/>
+```
+Text input with magnifying glass icon and clear button.
+
+### SelectFilter
+```jsx
+<SelectFilter
+  value={status}
+  onChange={(val) => setStatus(val)}
+  options={["All", "Active", "Inactive"]}   // or [{ value: "active", label: "Active" }]
+  label="Status"
+  placeholder="Select..."
+/>
+```
+Dropdown select. Value `"all"` skips filtering.
+
+### ToggleFilter
+```jsx
+<ToggleFilter
+  value={flaggedOnly}
+  onChange={(isActive) => setFlaggedOnly(isActive)}
+  label="Flagged only"
+/>
+```
+
+---
+
+## Data Utilities
+
+### DataModeToggle
+**When:** Place in the app header to let users switch between sample and live data.
+
+```jsx
+<DataModeToggle className="ml-4" />
+```
+Pill button switching between "Sample" (beaker icon, amber) and "Live" (signal icon, emerald). Reads/writes to `DataModeProvider` context.
+
+### usePageFilters
+**When:** Complete filtering + sorting state for a data page.
+
+```jsx
+const {
+  values,              // current filter values
+  setFilter,           // (filterId, value) => void
+  resetFilters,        // () => void
+  sort,                // { key, direction } | null
+  setSort,             // (key, direction) => void
+  toggleSort,          // (key) => void — cycles asc → desc → null
+  filteredData,        // data after filters
+  sortedData,          // data after filters + sort (pass this to components)
+  activeFilterCount,   // number of non-default filters
+} = usePageFilters({
+  data: rawData,
+  filters: [
+    { id: "search", type: "search", keys: ["name", "city"] },
+    { id: "status", type: "select", key: "status", defaultValue: "all" },
+    { id: "flagged", type: "toggle", key: "isFlagged", matchValue: true },
+    { id: "dates", type: "dateRange", key: "createdAt" },
+  ],
+  defaultSort: { key: "name", direction: "asc" },
+});
+```
+Pass `sortedData` (not `filteredData`) to components. Disable `TableCard.searchable` when FilterBar provides search.
+
+### filterUtils (pure functions)
+```jsx
+import { filterBySearch, filterByValue, filterByToggle, filterByDateRange, sortByKey, applyFilters } from "@/components/library";
+
+filterBySearch(data, "maya", ["name", "city"])       // case-insensitive multi-key
+filterByValue(data, "status", "Active")              // exact match; skips "all"/""/ null
+filterByToggle(data, "isFlagged", true, true)        // when active, match key to value
+filterByDateRange(data, "createdAt", { start, end }) // date range inclusion
+sortByKey(data, "name", "asc")                       // "asc" | "desc"; handles null, numbers, strings
+applyFilters(data, filterDefs, filterValues)          // apply all filters declaratively
+```
+
+---
+
+## Chat Sub-Components
+
+ChatBar and ChatPanel compose these internally, but they can be used standalone for custom chat layouts:
+
+### ChatMessageList
+```jsx
+<ChatMessageList
+  messages={messages}
+  isLoading={true}                     // shows "Thinking" indicator
+  isStreaming={false}                   // shows "Generating" indicator
+  suggestions={["Show spend", "Top travelers"]}
+  onSuggestion={(text) => sendMessage(text)}
+  renderAvatar={(msg) => <Avatar ... />}  // optional per-message avatar
+/>
+```
+Scrollable message area with auto-scroll to latest message.
+
+### ChatMessage
+```jsx
+<ChatMessage
+  message={{ id: "1", role: "assistant", content: "Here's what I found...",
+    components: [<MetricCard ... />],  // inline rendered components
+    toolCalls: [{ name: "search", status: "complete", result: "..." }],
+    isStreaming: false, timestamp: "2:30 PM" }}
+  avatar={<Avatar icon={<CpuChipIcon />} />}
+/>
+```
+Renders a single message bubble. Assistant messages format markdown (code blocks, bold, italic, inline code). System messages render as centered alerts.
+
+### ChatInput
+```jsx
+<ChatInput
+  onSend={(content) => handleSend(content)}
+  disabled={false}
+  isLoading={isProcessing}             // shows stop button instead of send
+  onStop={() => cancelRequest()}
+  placeholder="Type a message..."
+  maxRows={6}                          // max visible rows before scroll
+/>
+```
+Auto-resizing textarea. Enter sends, Shift+Enter = newline.
+
+### ChatTypingIndicator
+```jsx
+<ChatTypingIndicator label="Thinking" />
+```
+Animated three-dot bouncing indicator with AI icon.
+
+### ChatSuggestions
+```jsx
+<ChatSuggestions
+  suggestions={["Show spend", "Active trips"]}
+  onSelect={(text) => sendMessage(text)}
+/>
+```
+Row of sparkle-icon pill buttons for quick prompts. Returns null if empty.
+
+### ChatToolCall
+```jsx
+<ChatToolCall
+  toolCall={{ id: "tc1", name: "queryRecords", args: { object: "Trip__c" },
+    status: "complete", result: "Found 6 records" }}
+/>
+```
+Collapsible tool execution step. Status icons: spinner (running), check (complete), X (error). Color-coded by status.
+
+### ChatWelcome
+```jsx
+<ChatWelcome
+  title="How can I help?"
+  subtitle="Ask me anything about your travel data."
+  suggestions={["Show spend", "Active trips"]}
+  onSuggestion={(text) => sendMessage(text)}
+  icon={<CpuChipIcon className="h-8 w-8" />}
+/>
+```
+Full-screen welcome state shown before first message.
+
+---
+
+## BaseCard
+
+Foundation primitive that all card components extend. Rarely used directly — prefer MetricCard, ListCard, etc.
+
+```jsx
+<BaseCard
+  header={<div>Title area</div>}
+  body={<div>Content</div>}           // or use children
+  footer={<div>Footer</div>}
+  variant="default"                    // "default" | "metric" | "chart" | "table" | "widget" | "status"
+  size="md"                            // min-height: "xs" | "sm" | "md" | "lg" | "xl" | "full"
+  padding="default"                    // "none" | "xs" | "sm" | "default" | "lg" | "xl"
+  shadow={true}
+  radius="2xl"
+  border={true}
+  isHoverable={false}                  // lift on hover
+  isPressable={false}                  // interactive button (requires onPress)
+  isLoading={false}                    // animated skeleton pulse
+  isDisabled={false}
+  isSelected={false}                   // ring-2 brand highlight
+  onPress={() => {}}
+  className=""
+  headerClassName=""
+  bodyClassName=""
+  footerClassName=""
+/>
+```
+
+---
+
+## HeroUI Wrapper Components
+
+Thin wrappers around `@heroui/react` components, pre-scoped for the command center's theme. Import from `@/components/library`. Use compound sub-component pattern with dot notation.
+
+### Navigation & Layout
 
-This skill is split into focused sub-files for easier navigation:
+#### Tabs
+```jsx
+import { Tabs } from "@/components/library";
 
-| File | What's Inside | When to Use |
-|------|---------------|-------------|
-| **[when-to-use.md](./when-to-use.md)** | Decision matrix for choosing components | Start here — lookup table for "I need to show..." |
-| **[card-components.md](./card-components.md)** | MetricCard, ChartCard, TableCard, ListCard, ActivityCard, CalloutCard, SectionCard, WidgetCard, StatusCard, FeedPanel, MetricsStrip, ActionList | Building dashboards with KPIs, tables, lists |
-| **[charts.md](./charts.md)** | D3Chart, D3ChartTemplates, GeoMap, Layout & Skeletons | Data visualization — line/bar charts, maps, chart containers |
-| **[ui-primitives.md](./ui-primitives.md)** | UIButton, UIText, UIChip, Avatar, Spinner, EmptyState, UICard, UIContainer, UIInput, UIToggle, BaseCard | Basic UI building blocks and base components |
-| **[forms-filters.md](./forms-filters.md)** | FilterBar, FormModal, FormRenderer, useFormState, Individual filter components | User input — forms, filters, search, date pickers |
-| **[chat-data.md](./chat-data.md)** | ChatBar, ChatPanel, useChatState, useDataSource, DataModeProvider, Chat sub-components, Data utilities | AI chat interfaces and data fetching |
-| **[hero-ui.md](./hero-ui.md)** | HeroUI wrappers: Accordion, Drawer, Dropdown, Tooltip, Modal, ProgressBar, ProgressCircle, Tabs, Kbd, ScrollShadow, Toast | Advanced/composite components from HeroUI library |
-| **[common-mistakes.md](./common-mistakes.md)** | Do Not section — frequent errors | Troubleshooting prop issues |
+<Tabs aria-label="Options" variant="underlined" color="primary">
+  <Tabs.List>
+    <Tabs.Tab id="overview">Overview</Tabs.Tab>
+    <Tabs.Tab id="details">Details</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel id="overview">
+    <div>Overview content</div>
+  </Tabs.Panel>
+  <Tabs.Panel id="details">
+    <div>Details content</div>
+  </Tabs.Panel>
+</Tabs>
+```
+**Critical:** `Tabs.Tab` MUST be inside `Tabs.List` — rendering it directly inside `Tabs` causes a "cannot be rendered outside a collection" error. Content goes in `Tabs.Panel`, not as children of `Tabs.Tab`.
+
+Use **inside cards** for sub-section switching — never as page-level navigation.
+
+#### Accordion
+```jsx
+import { Accordion } from "@/components/library";
+
+<Accordion selectionMode="multiple" variant="bordered">
+  <Accordion.Item key="1" title="Section 1" subtitle="Optional subtitle">
+    <div>Expanded content</div>
+  </Accordion.Item>
+</Accordion>
+```
+
+#### Breadcrumbs
+```jsx
+import { Breadcrumbs } from "@/components/library";
+
+<Breadcrumbs>
+  <Breadcrumbs.Item>Home</Breadcrumbs.Item>
+  <Breadcrumbs.Item>Dashboard</Breadcrumbs.Item>
+  <Breadcrumbs.Item>Current</Breadcrumbs.Item>
+</Breadcrumbs>
+```
+
+#### Separator
+```jsx
+import { Separator } from "@/components/library";
+
+<Separator orientation="horizontal" className="my-4" />
+```
+
+#### Pagination
+```jsx
+import { Pagination } from "@/components/library";
+
+<Pagination total={10} page={currentPage} onChange={setCurrentPage}
+  showControls boundaries={1} siblings={1} />
+```
+
+### Overlays
+
+#### Drawer
+```jsx
+import { Drawer } from "@/components/library";
+
+<Drawer isOpen={open} onOpenChange={setOpen} placement="right" size="md">
+  <Drawer.Content>
+    <Drawer.Header>Title</Drawer.Header>
+    <Drawer.Body>Content</Drawer.Body>
+    <Drawer.Footer>
+      <UIButton onClick={() => setOpen(false)}>Close</UIButton>
+    </Drawer.Footer>
+  </Drawer.Content>
+</Drawer>
+```
+
+#### Modal
+```jsx
+import { Modal } from "@/components/library";
+
+<Modal isOpen={open} onOpenChange={setOpen} size="lg">
+  <Modal.Container>
+    <Modal.Header>Title</Modal.Header>
+    <Modal.Body>Content</Modal.Body>
+    <Modal.Footer>Actions</Modal.Footer>
+  </Modal.Container>
+</Modal>
+```
+For schema-driven forms, prefer `FormModal` over raw `Modal`.
+
+#### Dropdown
+```jsx
+import { Dropdown } from "@/components/library";
+
+<Dropdown>
+  <Dropdown.Trigger>
+    <UIButton>Options</UIButton>
+  </Dropdown.Trigger>
+  <Dropdown.Menu onAction={(key) => console.log(key)}>
+    <Dropdown.Item key="edit">Edit</Dropdown.Item>
+    <Dropdown.Item key="delete" className="text-danger">Delete</Dropdown.Item>
+  </Dropdown.Menu>
+</Dropdown>
+```
+
+#### Tooltip
+```jsx
+import { Tooltip } from "@/components/library";
+
+<Tooltip content="More info" placement="top">
+  <span>Hover me</span>
+</Tooltip>
+```
+
+#### Toast
+```jsx
+import { toast } from "@/components/library";
+
+// Trigger from anywhere (Toast.Provider must be in CommandCenter.tsx — already set up)
+toast.success("Record saved");
+toast.error("Something went wrong");
+toast("Neutral message");
+```
 
-## Quick Start Workflow
+### Feedback
 
-1. **Need to add something to a dashboard?** → Check [when-to-use.md](./when-to-use.md) decision matrix
-2. **Found the component?** → Go to the relevant detail file (e.g., [card-components.md](./card-components.md))
-3. **Copy exact prop names** — do not guess or improvise
-4. **Stuck or getting errors?** → Check [common-mistakes.md](./common-mistakes.md)
+#### Alert
+```jsx
+import { Alert } from "@/components/library";
+
+<Alert color="warning" title="Heads up" description="Check this out" />
+```
+
+#### Badge
+```jsx
+import { Badge } from "@/components/library";
+
+<Badge content="3" color="danger">
+  <BellIcon className="h-5 w-5" />
+</Badge>
+```
+
+#### ProgressBar
+```jsx
+import { ProgressBar } from "@/components/library";
+
+<ProgressBar label="Upload" value={75} maxValue={100} color="primary" showValueLabel />
+```
+
+#### ProgressCircle
+```jsx
+import { ProgressCircle } from "@/components/library";
+
+<ProgressCircle value={60} maxValue={100} color="success" showValueLabel />
+```
+
+#### Meter
+```jsx
+import { Meter } from "@/components/library";
+
+<Meter label="CPU Usage" value={82} maxValue={100} color="warning" />
+```
+
+#### Skeleton
+```jsx
+import { Skeleton } from "@/components/library";
+
+<Skeleton className="h-4 w-3/4 rounded-lg" />
+```
+For card-shaped loading states, prefer `CardSkeleton` over raw `Skeleton`.
+
+### Pickers & Forms
+
+#### Select
+```jsx
+import { Select } from "@/components/library";
+
+<Select label="Department" placeholder="Choose..." selectedKeys={[dept]}
+  onSelectionChange={(keys) => setDept([...keys][0])}>
+  <Select.Item key="sales">Sales</Select.Item>
+  <Select.Item key="eng">Engineering</Select.Item>
+</Select>
+```
+For filter dropdowns, prefer `SelectFilter` or `FilterBar` over raw `Select`.
+
+### Utilities
+
+#### Kbd
+```jsx
+import { Kbd } from "@/components/library";
+
+<Kbd keys={["command"]}>K</Kbd>   // renders ⌘K
+```
+
+#### ScrollShadow
+```jsx
+import { ScrollShadow } from "@/components/library";
+
+<ScrollShadow className="h-[300px]">
+  {longContent}
+</ScrollShadow>
+```
+Adds fade shadows at scroll edges to indicate more content.
+
+---
 
-## Critical Rules
+## Do Not
 
-- **Never modify files in `src/components/library/`** — they are vendored
-- **Always use exact prop names** from these docs — guessing causes runtime errors
-- **Import from `@/components/library`** (barrel) when possible
-- **Use `useDataSource` as default export** — `import useDataSource from "..."`
-- **Only use D3Chart and GeoMap** — no other chart libraries allowed
-- **Check the decision matrix first** — don't reinvent components that already exist
+- Import from individual library files when the barrel exports it
+- Modify vendored library files
+- Import shadcn (`@/components/ui/`) in command center code — shadcn components (`Button`, `Card`, `Input`, `Select`, `Alert`, `Skeleton`, etc.) exist for the outer app only. In command center pages, use the equivalent library component (`UIButton`, `BaseCard`/`WidgetCard`, `UIInput`, `Select`, `Alert`, `Skeleton`, etc. from `@/components/library`)
+- Use Lucide icons (`lucide-react`) in command center code — use Heroicons (`@heroicons/react`) instead
+- `import { useDataSource }` — it's a **default** export
+- Pass `items` to ActivityCard — use `actions`
+- Pass children to CalloutCard — use `message` prop
+- Pass `(row)` to TableCard render — it receives `(value, row)`
+- Use `template` prop on D3Chart — use `renderChart` function reference
+- Wrap GeoMap in ChartCard — render directly in a container div
+- Use ActivityCard for scrollable feeds — use ListCard with `maxBodyHeight`
+- Use raw `Modal` for form dialogs — use `FormModal` instead
+- Use `Tabs` as page-level navigation — only use inside cards for sub-sections
+- Pass `filteredData` to components — use `sortedData` from usePageFilters
+- Use `CardSkeleton` and `Skeleton` interchangeably — `CardSkeleton` for card placeholders, `Skeleton` for inline shapes
+- Recreate form state manually — use `useFormState` hook
+- Use `ChatPanel` on dashboards — use `ChatBar` (command palette style)
+- Pass children to `WidgetCard` — it ignores children and shows "No sections." Use the `sections` prop instead: `<WidgetCard sections={[{ id: "main", content: <div>...</div> }]} />`
+- Add `p-5`, `p-6`, etc. to WidgetCard `header` or section `content` — BaseCard already applies `p-4` padding, so extra padding causes double spacing
+- Pass initials strings as `avatar` in ListCard items — `avatar: "MR"` is treated as an image URL and breaks. Instead, omit `avatar` to auto-generate initials from `title`/`name`, or pass a ReactNode like `<Avatar initials="MR" />`
+- Hand-roll a card container (`<div className="bg-white border rounded ...">`) when `WidgetCard` with a single section can wrap your custom content
+- Use Recharts, Chart.js, or any third-party chart library — only `D3Chart` and `GeoMap` are allowed
+- Dismiss `validate:dashboard` errors as "justified" — every error has a library component fix