@schandlergarcia/sf-web-components 1.0.0

package/.a4drules/skills/building-data-visualization/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: building-data-visualization
+description: Adds data visualization components (charts, stat cards, KPI metrics) to React pages using Recharts. Use when the user asks to add a chart, graph, donut chart, pie chart, bar chart, stat card, KPI metric, dashboard visualization, or analytics component to the web application.
+---
+
+# Data Visualization
+
+## When to Use
+
+Use this skill when:
+- Adding charts (donut, pie, bar, line, area) to a dashboard or analytics page
+- Displaying KPI/metric stat cards with trend indicators
+- Building a dashboard layout with mixed chart types and summary cards
+
+---
+
+## Step 1 — Determine the visualization type
+
+Identify what the user needs:
+
+- **Donut / pie chart** — categorical breakdown (e.g. issue types, status distribution)
+- **Bar chart** — comparison across categories or time periods
+- **Line / area chart** — trends over time
+- **Stat card** — single KPI metric with optional trend indicator
+- **Combined dashboard** — stat cards + one or more charts
+
+If unclear, ask:
+
+> "What data should the chart display, and would a donut chart, bar chart, line chart, or stat cards work best?"
+
+---
+
+## Step 2 — Install dependencies
+
+All chart types in this skill use **recharts**. Install once from the web app directory:
+
+```bash
+npm install recharts
+```
+
+Recharts is built on D3 and provides declarative React components. No additional CSS is needed.
+
+---
+
+## Step 3 — Choose implementation path
+
+Read the corresponding guide:
+
+- **Bar chart** — read `implementation/bar-line-chart.md` (categorical data)
+- **Line / area chart** — read `implementation/bar-line-chart.md` (time-series data)
+- **Donut / pie chart** — read `implementation/donut-chart.md`
+- **Stat card with trend** — read `implementation/stat-card.md`
+- **Dashboard layout** — read `implementation/dashboard-layout.md`
+
+---
+
+## Verification
+
+Before completing:
+
+1. Chart renders with correct data and colors.
+2. Chart is responsive (resizes with container).
+3. Legend labels match the data categories.
+4. Stat card trends display correct positive/negative indicators.
+5. Run from the web app directory:
+
+```bash
+cd force-app/main/default/webapplications/<appName> && npm run lint && npm run build
+```
+
+- **Lint:** MUST result in 0 errors.
+- **Build:** MUST succeed.

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

@@ -0,0 +1,316 @@
+# Bar & Line / Area Chart — Implementation Guide
+
+Requires **recharts** (install from the web app directory; see SKILL.md Step 2).
+
+---
+
+## Data shapes
+
+### Time-series (line / area chart)
+
+Use when data represents a trend over time or ordered sequence.
+
+```ts
+interface TimeSeriesDataPoint {
+  x: string;   // date or label on the x-axis
+  y: number;   // numeric value
+}
+```
+
+Map raw fields to this shape: e.g. `date` → `x`, `revenue` → `y`.
+
+### Categorical (bar chart)
+
+Use when data compares discrete categories.
+
+```ts
+interface CategoricalDataPoint {
+  name: string;   // category label
+  value: number;  // numeric value
+}
+```
+
+Map raw fields to this shape: e.g. `product` → `name`, `sales` → `value`.
+
+### How to decide
+
+| Signal | Type |
+|--------|------|
+| "over time", "trend", date-like keys | Time-series → line chart |
+| "by category", "by X", label-like keys | Categorical → bar chart |
+
+---
+
+## Theme colors
+
+Pick a theme based on the data's sentiment:
+
+| Theme | Stroke / Fill | When to use |
+|-------|---------------|-------------|
+| `green` | `#22c55e` | Growth, gain, positive trend |
+| `red` | `#ef4444` | Decline, loss, negative trend |
+| `neutral` | `#6366f1` | Default or mixed data |
+
+Define colors as constants — do not use inline hex values.
+
+```ts
+const THEME_COLORS = {
+  red: "#ef4444",
+  green: "#22c55e",
+  neutral: "#6366f1",
+} as const;
+
+type ChartTheme = keyof typeof THEME_COLORS;
+```
+
+---
+
+## Line chart component
+
+Create at `components/LineChart.tsx` (or colocate with the page):
+
+```tsx
+import React from "react";
+import {
+  LineChart as RechartsLineChart,
+  Line,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+  ResponsiveContainer,
+} from "recharts";
+
+const THEME_COLORS = {
+  red: "#ef4444",
+  green: "#22c55e",
+  neutral: "#6366f1",
+} as const;
+
+type ChartTheme = keyof typeof THEME_COLORS;
+
+interface TimeSeriesDataPoint {
+  x: string;
+  y: number;
+}
+
+interface TimeSeriesChartProps {
+  data: TimeSeriesDataPoint[];
+  theme?: ChartTheme;
+  title?: string;
+  className?: string;
+}
+
+export function TimeSeriesChart({
+  data,
+  theme = "neutral",
+  title,
+  className = "",
+}: TimeSeriesChartProps) {
+  if (data.length === 0) {
+    return <p className="text-muted-foreground text-center py-8">No data to display</p>;
+  }
+
+  const color = THEME_COLORS[theme];
+
+  return (
+    <div className={className}>
+      {title && (
+        <h3 className="text-sm font-medium text-primary mb-2 uppercase tracking-wide">
+          {title}
+        </h3>
+      )}
+      <ResponsiveContainer width="100%" height={300}>
+        <RechartsLineChart data={data}>
+          <CartesianGrid strokeDasharray="3 3" />
+          <XAxis dataKey="x" />
+          <YAxis />
+          <Tooltip />
+          <Legend />
+          <Line type="monotone" dataKey="y" stroke={color} strokeWidth={2} dot={false} />
+        </RechartsLineChart>
+      </ResponsiveContainer>
+    </div>
+  );
+}
+```
+
+---
+
+## Bar chart component
+
+Create at `components/BarChart.tsx` (or colocate with the page):
+
+```tsx
+import React from "react";
+import {
+  BarChart as RechartsBarChart,
+  Bar,
+  XAxis,
+  YAxis,
+  CartesianGrid,
+  Tooltip,
+  Legend,
+  ResponsiveContainer,
+} from "recharts";
+
+const THEME_COLORS = {
+  red: "#ef4444",
+  green: "#22c55e",
+  neutral: "#6366f1",
+} as const;
+
+type ChartTheme = keyof typeof THEME_COLORS;
+
+interface CategoricalDataPoint {
+  name: string;
+  value: number;
+}
+
+interface CategoricalChartProps {
+  data: CategoricalDataPoint[];
+  theme?: ChartTheme;
+  title?: string;
+  className?: string;
+}
+
+export function CategoricalChart({
+  data,
+  theme = "neutral",
+  title,
+  className = "",
+}: CategoricalChartProps) {
+  if (data.length === 0) {
+    return <p className="text-muted-foreground text-center py-8">No data to display</p>;
+  }
+
+  const color = THEME_COLORS[theme];
+
+  return (
+    <div className={className}>
+      {title && (
+        <h3 className="text-sm font-medium text-primary mb-2 uppercase tracking-wide">
+          {title}
+        </h3>
+      )}
+      <ResponsiveContainer width="100%" height={300}>
+        <RechartsBarChart data={data}>
+          <CartesianGrid strokeDasharray="3 3" />
+          <XAxis dataKey="name" />
+          <YAxis />
+          <Tooltip />
+          <Legend />
+          <Bar dataKey="value" fill={color} radius={[4, 4, 0, 0]} />
+        </RechartsBarChart>
+      </ResponsiveContainer>
+    </div>
+  );
+}
+```
+
+---
+
+## Area chart variant
+
+For a filled area chart (useful for volume-over-time), swap `Line` for `Area`:
+
+```tsx
+import { AreaChart, Area, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from "recharts";
+
+<ResponsiveContainer width="100%" height={300}>
+  <AreaChart data={data}>
+    <CartesianGrid strokeDasharray="3 3" />
+    <XAxis dataKey="x" />
+    <YAxis />
+    <Tooltip />
+    <Area type="monotone" dataKey="y" stroke={color} fill={color} fillOpacity={0.2} />
+  </AreaChart>
+</ResponsiveContainer>
+```
+
+---
+
+## Chart container wrapper
+
+Wrap any chart in a styled card for consistent spacing:
+
+```tsx
+import { Card } from "@/components/ui/card";
+
+interface ChartContainerProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export function ChartContainer({ children, className = "" }: ChartContainerProps) {
+  return (
+    <Card className={`p-4 border-gray-200 shadow-sm ${className}`}>
+      {children}
+    </Card>
+  );
+}
+```
+
+Usage:
+
+```tsx
+<ChartContainer>
+  <TimeSeriesChart data={monthlyData} theme="green" title="Monthly Revenue" />
+</ChartContainer>
+```
+
+---
+
+## Preparing raw data
+
+Map API responses to the expected shape before passing to the chart:
+
+```tsx
+const timeSeriesData = useMemo(
+  () => apiRecords.map((r) => ({ x: r.date, y: r.revenue })),
+  [apiRecords],
+);
+
+const categoricalData = useMemo(
+  () => apiRecords.map((r) => ({ name: r.product, value: r.sales })),
+  [apiRecords],
+);
+```
+
+---
+
+## Key Recharts concepts
+
+| Component | Purpose |
+|-----------|---------|
+| `ResponsiveContainer` | Wraps chart to fill parent width |
+| `CartesianGrid` | Background grid lines |
+| `XAxis` / `YAxis` | Axis labels; `dataKey` maps to the data field |
+| `Tooltip` | Hover info |
+| `Legend` | Series labels |
+| `Line` | Line series; `type="monotone"` for smooth curves |
+| `Bar` | Bar series; `radius` rounds top corners |
+| `Area` | Filled area; `fillOpacity` controls transparency |
+
+---
+
+## 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 the chart stroke/fill and background.
+- Consider `prefers-reduced-motion` for chart animations.
+
+---
+
+## Common mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing `ResponsiveContainer` | Chart won't resize; always wrap |
+| Fixed width/height on chart | Let `ResponsiveContainer` control sizing |
+| No empty-data handling | Show "No data" message when `data.length === 0` |
+| Inline colors | Extract to `THEME_COLORS` constant |
+| Using raw Recharts for every chart type | Use `DonutChart` (see `donut-chart.md`) for pie/donut |

package/.a4drules/skills/building-data-visualization/implementation/dashboard-layout.md

@@ -0,0 +1,189 @@
+# Dashboard Layout — Implementation Guide
+
+## Anatomy of a dashboard page
+
+A typical dashboard combines stat cards, charts, and data tables:
+
+```
+┌────────────────────────────────────────────────────┐
+│  Search / global action bar                         │
+├──────────┬──────────┬──────────────────────────────┤
+│ Stat 1   │ Stat 2   │ Stat 3                       │
+├──────────┴──────────┴──────┬───────────────────────┤
+│                            │                       │
+│  Data table / list         │  Donut chart          │
+│  (70% width)               │  (30% width)          │
+│                            │                       │
+└────────────────────────────┴───────────────────────┘
+```
+
+---
+
+## Layout implementation
+
+```tsx
+import { PageContainer } from "@/components/layout/PageContainer";
+import { StatCard } from "@/components/StatCard";
+import { DonutChart } from "@/components/DonutChart";
+
+export default function Dashboard() {
+  return (
+    <PageContainer>
+      <div className="max-w-7xl mx-auto space-y-6">
+        {/* Search bar */}
+        <div>{/* global search component */}</div>
+
+        {/* Main content: 70/30 split */}
+        <div className="grid grid-cols-1 lg:grid-cols-[70%_30%] gap-6">
+          <div className="space-y-6">
+            {/* Stat cards row */}
+            <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+              <StatCard title="Metric A" value={42} />
+              <StatCard title="Metric B" value={18} />
+              <StatCard title="Metric C" value={7} />
+            </div>
+
+            {/* Data table */}
+            <div>{/* table component */}</div>
+          </div>
+
+          {/* Sidebar chart */}
+          <div>
+            <DonutChart title="Distribution" data={chartData} />
+          </div>
+        </div>
+      </div>
+    </PageContainer>
+  );
+}
+```
+
+---
+
+## Responsive behavior
+
+| Breakpoint | Layout |
+|------------|--------|
+| Mobile (`< 768px`) | Single column, everything stacked |
+| Tablet (`md`) | Stat cards in 3-col grid, rest stacked |
+| Desktop (`lg`) | 70/30 split for table + chart |
+
+Key Tailwind classes:
+
+```
+grid grid-cols-1 lg:grid-cols-[70%_30%] gap-6
+grid grid-cols-1 md:grid-cols-3 gap-6
+```
+
+---
+
+## Loading state
+
+Show a full-page loading state while dashboard data is being fetched:
+
+```tsx
+if (loading) {
+  return (
+    <PageContainer>
+      <div className="flex items-center justify-center min-h-[400px]">
+        <p className="text-muted-foreground">Loading dashboard…</p>
+      </div>
+    </PageContainer>
+  );
+}
+```
+
+Or use a skeleton layout:
+
+```tsx
+if (loading) {
+  return (
+    <PageContainer>
+      <div className="max-w-7xl mx-auto space-y-6">
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+          {[1, 2, 3].map((i) => (
+            <div key={i} className="h-28 animate-pulse rounded-xl bg-muted" />
+          ))}
+        </div>
+        <div className="grid grid-cols-1 lg:grid-cols-[70%_30%] gap-6">
+          <div className="h-64 animate-pulse rounded-xl bg-muted" />
+          <div className="h-64 animate-pulse rounded-xl bg-muted" />
+        </div>
+      </div>
+    </PageContainer>
+  );
+}
+```
+
+---
+
+## Data fetching pattern
+
+Use `useEffect` with cancellation for dashboard metrics:
+
+```ts
+const [metrics, setMetrics] = useState<Metrics | null>(null);
+const [loading, setLoading] = useState(true);
+
+useEffect(() => {
+  let cancelled = false;
+  (async () => {
+    try {
+      setLoading(true);
+      const data = await fetchDashboardMetrics();
+      if (!cancelled) setMetrics(data);
+    } catch (error) {
+      if (!cancelled) console.error("Error loading metrics:", error);
+    } finally {
+      if (!cancelled) setLoading(false);
+    }
+  })();
+  return () => { cancelled = true; };
+}, []);
+```
+
+---
+
+## Combining multiple data sources
+
+Dashboards often aggregate data from several APIs. Load them in parallel:
+
+```ts
+const [metrics, setMetrics] = useState<Metrics | null>(null);
+const [requests, setRequests] = useState<Request[]>([]);
+const [loading, setLoading] = useState(true);
+
+useEffect(() => {
+  let cancelled = false;
+  Promise.all([fetchMetrics(), fetchRecentRequests()])
+    .then(([metricsData, requestsData]) => {
+      if (!cancelled) {
+        setMetrics(metricsData);
+        setRequests(requestsData);
+      }
+    })
+    .catch((err) => {
+      if (!cancelled) console.error(err);
+    })
+    .finally(() => {
+      if (!cancelled) setLoading(false);
+    });
+  return () => { cancelled = true; };
+}, []);
+```
+
+---
+
+## PageContainer wrapper
+
+A simple wrapper for consistent page padding:
+
+```tsx
+interface PageContainerProps {
+  children: React.ReactNode;
+}
+
+export function PageContainer({ children }: PageContainerProps) {
+  return <div className="p-6">{children}</div>;
+}
+```