@schandlergarcia/sf-web-components 1.9.28 → 1.9.30

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

@@ -1,16 +1,13 @@
 ---
 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
+# Component Library Reference
 
 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
 
@@ -26,1003 +23,33 @@ import { useThemeMode } from "@/components/library/theme/AppThemeProvider";
 import type { MetricCardProps } from "@/components/library";
 ```
 
----
-
-## 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
+## Documentation Structure
 
-#### Tabs
-```jsx
-import { Tabs } from "@/components/library";
+This skill is split into focused sub-files for easier navigation:
 
-<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");
-```
+| 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 |
 
-### Feedback
+## Quick Start Workflow
 
-#### 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.
-
----
+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)
 
-## Do Not
+## Critical Rules
 
-- 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
+- **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