@schandlergarcia/sf-web-components 1.0.0

package/.a4drules/skills/building-data-visualization/implementation/donut-chart.md

@@ -0,0 +1,181 @@
+# Donut / Pie Chart — Implementation Guide
+
+Requires **recharts** (install from the web app directory; see SKILL.md Step 2).
+
+---
+
+## Data structure
+
+Charts expect an array of objects with `name`, `value`, and `color`:
+
+```ts
+interface ChartData {
+  name: string;
+  value: number;
+  color: string;
+}
+```
+
+---
+
+## Donut chart component
+
+Create at `components/DonutChart.tsx`:
+
+```tsx
+import React from "react";
+import { PieChart, Pie, Cell, ResponsiveContainer } from "recharts";
+import { Card } from "@/components/ui/card";
+
+interface ChartData {
+  name: string;
+  value: number;
+  color: string;
+}
+
+interface DonutChartProps {
+  title: string;
+  data: ChartData[];
+}
+
+export const DonutChart: React.FC<DonutChartProps> = ({ title, data }) => {
+  const total = data.reduce((sum, item) => sum + item.value, 0);
+  const mainPercentage = total > 0 ? Math.round((data[0]?.value / total) * 100) : 0;
+
+  return (
+    <Card className="p-4 border-gray-200 shadow-sm flex flex-col">
+      <h3 className="text-sm font-medium text-primary mb-2 uppercase tracking-wide">
+        {title}
+      </h3>
+
+      <div className="relative flex items-center justify-center">
+        <ResponsiveContainer width="100%" height={300}>
+          <PieChart>
+            <Pie
+              data={data}
+              cx="50%"
+              cy="50%"
+              innerRadius={70}
+              outerRadius={110}
+              paddingAngle={2}
+              dataKey="value"
+            >
+              {data.map((entry, index) => (
+                <Cell key={`cell-${index}`} fill={entry.color} />
+              ))}
+            </Pie>
+          </PieChart>
+        </ResponsiveContainer>
+
+        {/* Center label */}
+        <div className="absolute inset-0 flex items-center justify-center">
+          <div className="text-center">
+            <div className="text-5xl font-bold text-primary">{mainPercentage}%</div>
+          </div>
+        </div>
+      </div>
+
+      {/* Legend */}
+      <div className="mt-6 grid grid-cols-2 gap-3">
+        {data.map((item, index) => (
+          <div key={index} className="flex items-center gap-2">
+            <div className="w-3 h-3 rounded-full" style={{ backgroundColor: item.color }} />
+            <span className="text-sm text-gray-700">{item.name}</span>
+          </div>
+        ))}
+      </div>
+    </Card>
+  );
+};
+```
+
+---
+
+## Key Recharts concepts
+
+| Component | Purpose |
+|-----------|---------|
+| `ResponsiveContainer` | Wraps chart to make it fill its parent's width |
+| `PieChart` | Chart container for pie/donut |
+| `Pie` | The data ring; `innerRadius` > 0 makes it a donut |
+| `Cell` | Individual segment; accepts `fill` color |
+| `paddingAngle` | Gap between segments (degrees) |
+
+### Donut vs Pie
+
+| Property | Donut | Pie |
+|----------|-------|-----|
+| `innerRadius` | `> 0` (e.g. `70`) | `0` |
+| Center label | Yes, positioned absolutely | Not typical |
+
+---
+
+## Preparing chart data from raw records
+
+Transform API data into the `ChartData[]` format before passing to the chart:
+
+```tsx
+const CATEGORIES = ["Plumbing", "HVAC", "Electrical"] as const;
+const OTHER_LABEL = "Other";
+const COLORS = ["#7C3AED", "#EC4899", "#14B8A6", "#06B6D4"];
+
+const chartData = useMemo(() => {
+  const counts: Record<string, number> = {};
+  CATEGORIES.forEach((c) => (counts[c] = 0));
+  counts[OTHER_LABEL] = 0;
+
+  records.forEach((record) => {
+    const type = record.category;
+    if (CATEGORIES.includes(type as (typeof CATEGORIES)[number])) {
+      counts[type]++;
+    } else {
+      counts[OTHER_LABEL]++;
+    }
+  });
+
+  return [
+    ...CATEGORIES.map((name, i) => ({ name, value: counts[name], color: COLORS[i] })),
+    { name: OTHER_LABEL, value: counts[OTHER_LABEL], color: COLORS[CATEGORIES.length] },
+  ];
+}, [records]);
+```
+
+---
+
+## Color palette recommendations
+
+| Use case | Colors |
+|----------|--------|
+| Categorical (4 items) | `#7C3AED` `#EC4899` `#14B8A6` `#06B6D4` |
+| Status (3 items) | `#22C55E` `#F59E0B` `#EF4444` (green/amber/red) |
+| Sequential | Use opacity variants of one hue: `#7C3AED` at 100%, 75%, 50%, 25% |
+
+Keep chart colors consistent with the app's design system. Define them as constants, not inline values.
+
+---
+
+## Other chart types
+
+For **bar charts** and **line / area charts**, see `bar-line-chart.md` in this directory.
+
+---
+
+## Accessibility
+
+- Always include a text legend (not just colors).
+- Chart should be wrapped in a section with a visible heading.
+- For critical data, provide a text summary or table alternative.
+- Use sufficient color contrast between segments.
+- Consider `prefers-reduced-motion` for chart animations.
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing `ResponsiveContainer` | Chart won't resize; always wrap in `ResponsiveContainer` |
+| Fixed width/height on `PieChart` | Let `ResponsiveContainer` control sizing |
+| No legend | Add a grid legend below the chart |
+| Inline colors | Extract to constants for consistency |
+| No fallback for empty data | Show "No data" message when `data` is empty |

package/.a4drules/skills/building-data-visualization/implementation/stat-card.md

@@ -0,0 +1,150 @@
+# Stat Card — Implementation Guide
+
+## What is a stat card
+
+A stat card displays a single KPI metric with an optional trend indicator. Used on dashboards to show at-a-glance numbers like "Total Properties: 42 (+10%)".
+
+---
+
+## Component interface
+
+```ts
+interface StatCardProps {
+  title: string;
+  value: number | string;
+  trend?: {
+    value: number;
+    isPositive: boolean;
+  };
+  subtitle?: string;
+  onClick?: () => void;
+}
+```
+
+---
+
+## StatCard component
+
+Create at `components/StatCard.tsx`:
+
+```tsx
+import React from "react";
+import { Card } from "@/components/ui/card";
+import { TrendingUp, TrendingDown } from "lucide-react";
+
+interface StatCardProps {
+  title: string;
+  value: number | string;
+  trend?: {
+    value: number;
+    isPositive: boolean;
+  };
+  subtitle?: string;
+  onClick?: () => void;
+}
+
+export const StatCard: React.FC<StatCardProps> = ({ title, value, trend, subtitle, onClick }) => {
+  return (
+    <Card
+      className={`p-4 border-gray-200 shadow-sm relative ${
+        onClick ? "cursor-pointer hover:shadow-lg transition-shadow" : ""
+      }`}
+      onClick={onClick}
+    >
+      <div className="space-y-1">
+        <p className="text-sm font-medium text-muted-foreground uppercase tracking-wide">{title}</p>
+        <div className="flex items-baseline gap-3">
+          <p className="text-4xl font-bold text-primary">{value}</p>
+          {trend && (
+            <span
+              className={`inline-flex items-center gap-1 px-2.5 py-0.5 rounded-full text-sm font-medium ${
+                trend.isPositive
+                  ? "bg-emerald-100 text-emerald-800"
+                  : "bg-pink-100 text-pink-800"
+              }`}
+            >
+              {trend.isPositive ? (
+                <TrendingUp className="w-4 h-4" />
+              ) : (
+                <TrendingDown className="w-4 h-4" />
+              )}
+              {Math.abs(trend.value)}%
+            </span>
+          )}
+        </div>
+        {subtitle && <p className="text-sm text-muted-foreground mt-1">{subtitle}</p>}
+      </div>
+    </Card>
+  );
+};
+```
+
+This version uses Lucide icons (`TrendingUp`/`TrendingDown`) instead of custom SVGs for portability across projects.
+
+---
+
+## Layout: stat card grid
+
+Display stat cards in a responsive grid:
+
+```tsx
+<div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+  <StatCard
+    title="Total Properties"
+    value={metrics.totalProperties}
+    trend={{ value: 10, isPositive: true }}
+    subtitle="Last month total 38"
+  />
+  <StatCard
+    title="Units Available"
+    value={metrics.unitsAvailable}
+    trend={{ value: 5, isPositive: false }}
+    subtitle="Last month total 12/42"
+  />
+  <StatCard
+    title="Occupied Units"
+    value={metrics.occupiedUnits}
+    trend={{ value: 8, isPositive: true }}
+    subtitle="Last month total 27"
+  />
+</div>
+```
+
+---
+
+## Computing trend values
+
+Calculate trends from current vs previous period:
+
+```ts
+const trends = useMemo(() => {
+  const previousTotal = metrics.totalProperties - Math.round(metrics.totalProperties * 0.1);
+  const trendPercent = previousTotal > 0
+    ? Math.round(((metrics.totalProperties - previousTotal) / previousTotal) * 100)
+    : 0;
+
+  return {
+    value: Math.abs(trendPercent),
+    isPositive: trendPercent >= 0,
+  };
+}, [metrics]);
+```
+
+---
+
+## Trend badge color conventions
+
+| Trend | Background | Text | Meaning |
+|-------|------------|------|---------|
+| Positive (up) | `bg-emerald-100` | `text-emerald-800` | Growth, improvement |
+| Negative (down) | `bg-pink-100` | `text-pink-800` | Decline, concern |
+| Neutral | `bg-gray-100` | `text-gray-600` | No change |
+
+---
+
+## Accessibility
+
+- Card uses `cursor-pointer` and `hover:shadow-lg` only when `onClick` is provided.
+- Trend icons have implicit meaning from color + direction icon.
+- Stat values use large, bold text for visibility.
+- Title uses `uppercase tracking-wide` for visual hierarchy without heading tags (appropriate in a card grid).

package/.a4drules/skills/building-react-components/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: building-react-components
+description: Use when editing any React code in the web application — creating or modifying components, pages, layout, headers, footers, or any TSX/JSX files. Follow this skill for add component, add page, header/footer, and general React UI implementation patterns (shadcn UI and Tailwind CSS).
+---
+
+# React Web App (Components, Pages, Layout)
+
+Use this skill whenever you are editing React/TSX code in the web app (creating or modifying components, pages, header/footer, or layout).
+
+## Step 1 — Identify the type of component
+
+Determine which of these three categories the request falls into, then follow the corresponding section below:
+
+- **Page** — user wants a new routed page (e.g. "add a contacts page", "create a dashboard page", "add a settings section")
+- **Header / Footer** — user wants a site-wide header, footer, nav bar, or page footer that appears on every page
+- **Component** — everything else: a widget, card, table, form, dialog, or other UI element placed within an existing page
+
+If it is not immediately clear from the user's message, ask:
+
+> "Are you looking to add a new page, a site-wide header or footer, or a component within an existing page?"
+
+Then follow the matching section.
+
+---
+
+## Clarifying Questions
+
+Ask **one question at a time** and wait for the response before asking the next. Stop when you have enough to build accurately — do not guess or assume.
+
+### For a Page
+
+1. **What is the name and purpose of the page?** (e.g., Contacts, Dashboard, Settings)
+2. **What URL path should it use?** (e.g., `/contacts`, `/dashboard`) — or derive from the page name?
+3. **Should the page appear in the navigation menu?**
+4. **Who can access it?** Public, authenticated users only (`PrivateRoute`), or unauthenticated only (e.g., login — `AuthenticationRoute`)?
+5. **What content or sections should the page include?** (list, form, table, detail view, etc.)
+6. **Does it need to fetch any data?** If so, from where?
+
+### For a Header / Footer
+
+1. **Header, footer, or both?**
+2. **What should the header contain?** (logo/app name, nav links, user avatar, CTA button, etc.)
+3. **What should the footer contain?** (copyright text, links, social icons, etc.)
+4. **Should the header be sticky (fixed to top while scrolling)?**
+5. **Is there a logo or brand name to display?** (or placeholder?)
+6. **Any specific color scheme or style direction?** (dark background, branded primary color, minimal, etc.)
+7. **Should navigation links appear in the header?** If so, which pages?
+
+### For a Component
+
+1. **What should the component do?** (display data, accept input, trigger an action, etc.)
+2. **What page or location should it appear on?**
+3. **Is this shared/reusable across pages, or specific to one feature?** (determines file location)
+4. **What data or props does it need?** (static content, props, fetched data)
+5. **Does it need internal state?** (loading, toggle, form state, etc.)
+6. **Are there any specific shadcn components to use?** (Card, Table, Dialog, Form, etc.)
+7. **Should it appear in a specific layout position?** (full-width, sidebar, inline, etc.)
+
+---
+
+## Implementation
+
+Once you have identified the type and gathered answers to the clarifying questions, read and follow the corresponding implementation guide:
+
+- **Page** — read `implementation/page.md` and follow the instructions there.
+- **Header / Footer** — read `implementation/header-footer.md` and follow the instructions there.
+- **Component** — read `implementation/component.md` and follow the instructions there.
+
+---
+
+## TypeScript Standards
+
+- **Never use `any`** — use proper types, generics, or `unknown` with type guards.
+- **Event handlers:** `(event: React.FormEvent<HTMLFormElement>): void`
+- **State:** `useState<User | null>(null)` — always provide the type parameter.
+- **No unsafe assertions** (`obj as User`). Use type guards:
+  ```typescript
+  function isUser(obj: unknown): obj is User {
+    return typeof obj === 'object' && obj !== null && typeof (obj as User).id === 'string';
+  }
+  ```
+
+---
+
+## Verification (MANDATORY)
+
+Before completing, run from the web app directory `force-app/main/default/webapplications/<appName>/`:
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors.
+- **Build:** MUST succeed (includes TypeScript check).
+
+If either fails, fix the errors and re-run. Do not leave the session with failing quality gates.

package/.a4drules/skills/building-react-components/implementation/component.md

@@ -0,0 +1,78 @@
+# Implementation — Component
+
+### Rules
+
+1. **Always use shadcn components** from `@/components/ui` — never build raw HTML equivalents for buttons, inputs, cards, alerts, tabs, tables, or labels.
+2. **All styling via Tailwind** — utility classes only. No inline `style={{}}`, CSS Modules, or other styling systems.
+3. **Use design tokens** — prefer `bg-background`, `text-foreground`, `text-muted-foreground`, `border`, `bg-primary`, `text-destructive`, `rounded-lg` over hardcoded colors.
+4. **Use `cn()`** from `@/lib/utils` for conditional or composable class names.
+5. **TypeScript** — functional components with typed props interface; always accept `className?: string`.
+
+### File Location — Component
+
+| Component type                                 | Location                                 | Export                                   |
+| ---------------------------------------------- | ---------------------------------------- | ---------------------------------------- |
+| Shared UI primitive (reusable across features) | `src/components/ui/` — add to `index.ts` | Named export                             |
+| Feature-specific (e.g., dashboard widget)      | `src/components/<feature>/`              | Named export, import directly where used |
+| Page-level layout element                      | `src/components/layout/`                 | Named export                             |
+
+### Component Structure
+
+```tsx
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui";
+import { cn } from "@/lib/utils";
+
+interface MyComponentProps {
+  title: string;
+  value: string;
+  className?: string;
+}
+
+export function MyComponent({ title, value, className }: MyComponentProps) {
+  return (
+    <Card className={cn("border", className)}>
+      <CardHeader>
+        <CardTitle className="text-sm font-medium">{title}</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <p className="text-2xl font-semibold text-foreground">{value}</p>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+### State and Hooks
+
+- **Local state only:** keep `useState`, `useReducer`, `useRef` inside the component.
+- **Shared or complex state:** extract to a custom hook in `src/hooks/` (prefix with `use`, e.g. `useFormData`). Do this when more than one component needs the state, or when multiple hooks are composed together.
+
+### Adding the Component to a Page
+
+```tsx
+// In the target page file, e.g. src/pages/HomePage.tsx
+import { MyComponent } from "@/components/<feature>/MyComponent";
+
+export default function HomePage() {
+  return (
+    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12">
+      <MyComponent title="Status" value="Active" />
+    </div>
+  );
+}
+```
+
+### Useful Patterns — Component
+
+- **Programmatic navigation:** use `useNavigate` from `react-router`; call `navigate(path)` — consistent with GlobalSearchInput, SearchResultCard, MaintenanceTable, and other components in the web application.
+- **Page container:** `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-12`
+- **Icons:** `lucide-react`; add `aria-hidden="true"` on decorative icons
+- **Focus styles:** use `focus-visible:` variants
+- **Multiple visual variants:** use CVA (`cva`) and `VariantProps`
+- **shadcn import barrel:** `import { Button, Card, Input } from "@/components/ui"`
+
+### Confirm — Component
+
+- Imports use path aliases (`@/`, not deep relative paths)
+- No raw `<button>`, `<input>`, or styled `<div>` where shadcn equivalents exist
+- No inline `style={{}}` — Tailwind only

package/.a4drules/skills/building-react-components/implementation/header-footer.md

@@ -0,0 +1,132 @@
+# Implementation — Header / Footer
+
+### Rules
+
+1. **Edit `appLayout.tsx` only** — header and footer are layout-level concerns. Never add them to individual page files.
+2. **Never modify `routes.tsx` or `app.tsx`** — the router setup must remain intact.
+3. **Create component files in `src/components/layout/`** — the designated location for layout-level components.
+4. **Use the full-height flex column pattern** — wrap layout in `min-h-screen flex flex-col` so footer stays at bottom.
+5. **Use shadcn and Tailwind** — compose from `@/components/ui`; style with Tailwind utility classes and design tokens.
+6. **Use path aliases** — import with `@/components/layout/...` and `@/components/ui`; no deep relative paths.
+7. **Preserve existing content** — if `appLayout.tsx` already has a `<NavigationMenu />` or other shell elements, keep them in place.
+
+### Step 1 — Create the header component (if requested)
+
+Create `src/components/layout/AppHeader.tsx`:
+
+```tsx
+import { cn } from "@/lib/utils";
+
+interface AppHeaderProps {
+  className?: string;
+}
+
+export function AppHeader({ className }: AppHeaderProps) {
+  return (
+    <header
+      className={cn(
+        "w-full border-b bg-background px-4 sm:px-6 lg:px-8 py-4",
+        className,
+      )}
+    >
+      <div className="max-w-7xl mx-auto flex items-center justify-between">
+        <span className="text-lg font-semibold text-foreground">My App</span>
+      </div>
+    </header>
+  );
+}
+```
+
+### Step 2 — Create the footer component (if requested)
+
+Create `src/components/layout/AppFooter.tsx`:
+
+```tsx
+import { cn } from "@/lib/utils";
+
+interface AppFooterProps {
+  className?: string;
+}
+
+export function AppFooter({ className }: AppFooterProps) {
+  return (
+    <footer
+      className={cn(
+        "w-full border-t bg-background px-4 sm:px-6 lg:px-8 py-4",
+        className,
+      )}
+    >
+      <div className="max-w-7xl mx-auto text-center text-sm text-muted-foreground">
+        &copy; {new Date().getFullYear()} My App. All rights reserved.
+      </div>
+    </footer>
+  );
+}
+```
+
+### Step 3 — Edit `appLayout.tsx`
+
+Open `src/appLayout.tsx` — this is the **only file to modify** for layout-level additions. Wrap existing content in a flex column and add header above and footer below `<Outlet />`:
+
+```tsx
+import { Outlet } from "react-router";
+import { AppHeader } from "@/components/layout/AppHeader";
+import { AppFooter } from "@/components/layout/AppFooter";
+// Keep all existing imports unchanged
+
+export default function AppLayout() {
+  return (
+    <div className="min-h-screen flex flex-col bg-background">
+      <AppHeader />
+      {/* Keep any existing NavigationMenu or other shell elements here */}
+      <main className="flex-1">
+        <Outlet />
+      </main>
+      <AppFooter />
+    </div>
+  );
+}
+```
+
+### File Locations — Header / Footer
+
+| Component    | File                                  | Export                         |
+| ------------ | ------------------------------------- | ------------------------------ |
+| Header       | `src/components/layout/AppHeader.tsx` | Named export                   |
+| Footer       | `src/components/layout/AppFooter.tsx` | Named export                   |
+| Layout shell | `src/appLayout.tsx`                   | Default export (edit in place) |
+
+### Why `appLayout.tsx` — Not Pages or Routes
+
+`AppLayout` is the single shell rendered at the root route. Every page is a child rendered via `<Outlet />`. Placing the header and footer here ensures they appear on every page without touching individual pages or the route registry.
+
+```
+AppLayout (appLayout.tsx)
+├── AppHeader          ← renders on every page
+├── NavigationMenu     ← keep if already present
+├── <Outlet />         ← active page renders here
+└── AppFooter          ← renders on every page
+```
+
+### Useful Patterns — Header / Footer
+
+- **Sticky header:** add `sticky top-0 z-50` to the `<header>` element
+- **Separator:** use `<Separator />` from `@/components/ui` instead of `border-b`/`border-t` if a visible divider is preferred
+- **Nav links in header:** use `<Button variant="ghost" asChild>` wrapping a React Router `<Link>`
+- **Icons:** `lucide-react`; add `aria-hidden="true"` on decorative icons
+- **Design tokens:** `bg-background`, `text-foreground`, `text-muted-foreground`, `border`, `bg-primary`
+
+### Mobile hamburger / Menu icon — Must be functional
+
+If the header includes a hamburger or `Menu` icon for mobile:
+
+- **Do not** add a Menu/hamburger icon that does nothing. It must toggle a visible mobile menu.
+- **Required:** (1) State: `const [isOpen, setIsOpen] = useState(false)`. (2) Button: `onClick={() => setIsOpen(!isOpen)}`, `aria-label="Toggle menu"`. (3) Conditional panel: `{isOpen && ( <div>...nav links...</div> )}` with responsive visibility (e.g. `md:hidden`). (4) Close on navigate: each link in the panel should `onClick={() => setIsOpen(false)}`.
+- Implement in `appLayout.tsx` (or the component that owns the header). Use the `Menu` icon from `lucide-react`.
+
+### Confirm — Header / Footer
+
+- Header and footer appear on every page (navigate to at least two routes)
+- Imports use path aliases (`@/components/layout/...`)
+- No inline `style={{}}` — Tailwind only
+- `src/routes.tsx` and `src/app.tsx` are unchanged