@schandlergarcia/sf-web-components 1.9.28 → 1.9.30

package/.a4drules/skills/component-library/hero-ui.md

@@ -0,0 +1,211 @@
+## 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
+
+#### Tabs
+```jsx
+import { Tabs } from "@/components/library";
+
+<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");
+```
+
+### Feedback
+
+#### 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.
+
+---
+

package/.a4drules/skills/component-library/ui-primitives.md

@@ -0,0 +1,92 @@
+## 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.
+
+---
+
+## 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=""
+/>
+```
+
+---
+

package/.a4drules/skills/component-library/when-to-use.md

@@ -0,0 +1,39 @@
+## 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 |
+
+---
+