@ammarkhalidfarooq/dashboard-package 0.6.127 → 0.6.129

package/README.md

@@ -1,305 +1,305 @@
-# @ammarkhalidfarooq/dashboard-package
-
-A reusable React Dashboard component library.
-
-## Installation
-
-```bash
-npm install @ammarkhalidfarooq/dashboard-package
-```
-
-Peer dependencies are required in your app:
-
-- `react`, `react-dom`
-- `@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled`
-- `apexcharts`, `react-apexcharts`
-
-## Usage
-
-### Full Dashboard
-
-```jsx
-import React from "react";
-import { Dashboard } from "@ammarkhalidfarooq/dashboard-package";
-
-const App = () => {
-  return <Dashboard />;
-};
-
-export default App;
-```
-
-### RenderChartCard (tree-shakeable)
-
-Import only the chart card bundle — avoids pulling in the full dashboard:
-
-```jsx
-import RenderChartCard from "@ammarkhalidfarooq/dashboard-package/RenderChartCard";
-```
-
-Or import from the main entry:
-
-```jsx
-import { RenderChartCard } from "@ammarkhalidfarooq/dashboard-package";
-```
-
-**Example:**
-
-```jsx
-import { useState } from "react";
-import Grid from "@mui/material/Grid";
-import RenderChartCard from "@ammarkhalidfarooq/dashboard-package/RenderChartCard";
-
-const chartItem = {
-  label: "Revenue per Visitor",
-  value: "$5.12",
-  subtitle: "Last 30 days · daily aggregation",
-  trend: "18% vs last month",
-  data: [3000, 4500, 4200, 5800, 5200, 7100, 8500, 9200, 5000],
-  categories: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep"],
-};
-
-const App = () => {
-  const [metric, setMetric] = useState("Revenue");
-
-  return (
-    <Grid container spacing={3}>
-      <RenderChartCard
-        item={chartItem}
-        index={0}
-        isPremium
-        md={6}
-        metric={metric}
-        setMetric={setMetric}
-      />
-    </Grid>
-  );
-};
-
-export default App;
-```
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `item` | `object` | — | Chart config (see below) |
-| `index` | `number` | — | Unique index for the chart |
-| `isPrimary` | `boolean` | `false` | Uses a taller chart area |
-| `isPremium` | `boolean` | `false` | Premium card layout with trend badge |
-| `metric` | `string` | — | Active metric label (e.g. `"Revenue"`) |
-| `setMetric` | `function` | — | Metric change handler |
-| `md` | `number` | `4` | Grid column width on `md` breakpoint |
-| `type` | `string` | `"area"` | Chart type (`"area"`, `"bar"`, `"donut"`, etc.) |
-| `sx` | `object` | `{}` | MUI `sx` overrides for the grid item wrapper |
-| `cardSx` | `object` | `{}` | MUI `sx` overrides for the card container |
-| `contentSx` | `object` | `{}` | MUI `sx` overrides for the card content area |
-
-**`item` shape (common fields):**
-
-```js
-{
-  label: "Revenue per Visitor",       // Card title
-  value: "$5.12",                     // Main metric value
-  subtitle: "Last 30 days",           // Optional subtitle (premium layout)
-  trend: "18% vs last month",         // Optional trend badge (premium layout)
-  data: [3000, 4500, 4200],           // Single-series chart data
-  categories: ["Jan", "Feb", "Mar"],  // X-axis labels
-  series: [{ name: "Paid Ads", data: [...] }], // Multi-series (optional)
-  stacked: false,                     // Stack series (optional)
-  showSelector: false,                // Show metric dropdown (optional)
-  hideControls: false,                // Hide menu / show legend only (optional)
-  height: 250,                        // Chart height override (optional)
-  type: "area",                       // Per-card chart type override (optional)
-  colors: ["#6366F1", "#10B981"],     // Custom chart colors (optional)
-  footer: { left: "Total", right: "$12k" }, // Optional footer row
-}
-```
-
-### ActiveCampaignsCard (tree-shakeable)
-
-A configurable table card — used for channel performance, active campaigns, and similar ranked lists.
-
-```jsx
-import ActiveCampaignsCard from "@ammarkhalidfarooq/dashboard-package/ActiveCampaignsCard";
-```
-
-Or import from the main entry:
-
-```jsx
-import { ActiveCampaignsCard } from "@ammarkhalidfarooq/dashboard-package";
-```
-
-**Channel performance example:**
-
-```jsx
-import ActiveCampaignsCard from "@ammarkhalidfarooq/dashboard-package/ActiveCampaignsCard";
-
-const channelRows = [
-  {
-    id: "M",
-    avatarBg: "#4267B2",
-    name: "Meta Ads",
-    val1: "$32,800",
-    val2: "$112,400",
-    val3: "3.4x",
-    val4: "$340",
-    type: "trend",
-    trendType: "up",
-    trendLabel: "Improving",
-    highlightVal3: true,
-    val3Color: "#22C55E",
-  },
-  {
-    id: "G",
-    avatarBg: "#4285F4",
-    name: "Google Ads",
-    val1: "$28,200",
-    val2: "$78,300",
-    val3: "2.8x",
-    val4: "$385",
-    type: "trend",
-    trendType: "up",
-    trendLabel: "Improving",
-    highlightVal3: true,
-    val3Color: "#22C55E",
-  },
-];
-
-const App = () => (
-  <ActiveCampaignsCard
-    title="Channel performance"
-    subtitle="Ad platforms ranked by ROAS"
-    columns={["channel", "spend", "revenue", "ROAS", "CPA", "trend"]}
-    gridTemplateColumns="2.2fr 1fr 1fr 0.8fr 0.8fr 1.2fr"
-    height="100%"
-    rows={channelRows}
-  />
-);
-
-export default App;
-```
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `string` | `"Active campaigns"` | Card title |
-| `subtitle` | `string` | `"Live fundraisers ranked by velocity"` | Card subtitle |
-| `actionLabel` | `string` | — | Optional top-right action link text |
-| `columns` | `string[]` | `["Campaign", "Raised", "Progress", "Donors", "Avg gift"]` | Table header labels |
-| `rows` | `object[]` | `[]` | Table row data (see below) |
-| `gridTemplateColumns` | `string` | `"3fr 1fr 1.5fr 0.8fr 1fr"` | CSS grid column template |
-| `height` | `string` | — | Card height (e.g. `"100%"`) |
-| `compact` | `boolean` | `false` | Smaller typography and spacing |
-| `sx` | `object` | `{}` | MUI `sx` overrides for the root card container |
-| `headerSx` | `object` | `{}` | MUI `sx` overrides for the title / subtitle header row |
-| `tableSx` | `object` | `{}` | MUI `sx` overrides for the scrollable table area |
-
-**`row` shape:**
-
-```js
-// Channel performance / trend table (6 columns)
-{
-  id: "M",                    // Avatar label (optional)
-  avatarBg: "#4267B2",        // Avatar background color
-  name: "Meta Ads",           // Row label
-  val1: "$32,800",            // Column 2 (spend / raised)
-  val2: "$112,400",           // Column 3 when type !== "progress"
-  val3: "3.4x",               // Column 4 (ROAS / donors)
-  val4: "$340",               // Column 5 (CPA / avg gift)
-  type: "trend",              // "trend" | "progress" — controls column 3 & 6
-  trendType: "up",            // "up" | "down" (when type is "trend")
-  trendLabel: "Improving",    // Trend badge text
-  highlightVal3: true,        // Highlight column 4 value
-  val3Color: "#22C55E",       // Highlight color for column 4
-}
-
-// Campaign progress table (5 columns)
-{
-  id: "1",
-  name: "Ramadan Appeal",
-  val1: "$45,200",
-  type: "progress",
-  progress: 72,
-  progressColor: "rgb(99, 99, 230)",
-  val3: "1,240",
-  val4: "$36.45",
-  status: "Live",
-  statusBg: "#DCFCE7",
-  statusColor: "#166534",
-}
-```
-
-### MetricCard (tree-shakeable)
-
-A compact KPI card with icon, value, and caption — used for selectable overview metrics.
-
-```jsx
-import MetricCard from "@ammarkhalidfarooq/dashboard-package/MetricCard";
-```
-
-Or import from the main entry:
-
-```jsx
-import { MetricCard } from "@ammarkhalidfarooq/dashboard-package";
-```
-
-**Example:**
-
-```jsx
-import { useState } from "react";
-import { PaidOutlined as DollarIcon } from "@mui/icons-material";
-import MetricCard from "@ammarkhalidfarooq/dashboard-package/MetricCard";
-
-const App = () => {
-  const [active, setActive] = useState("Total Raised");
-
-  return (
-    <MetricCard
-      title="Total Raised"
-      value="$124,500"
-      caption="12.4% vs last month"
-      icon={<DollarIcon />}
-      active={active === "Total Raised"}
-      onClick={() => setActive("Total Raised")}
-    />
-  );
-};
-
-export default App;
-```
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `title` | `string` | — | Card label |
-| `value` | `string` | — | Main metric value |
-| `caption` | `string` | — | Subtitle / trend text below the value |
-| `icon` | `ReactNode` | — | Icon shown in the top-right avatar |
-| `active` | `boolean` | `false` | Highlights the card as selected |
-| `warning` | `boolean` | `false` | Warning border and icon styling |
-| `error` | `boolean` | `false` | Error border and caption styling |
-| `onClick` | `function` | — | Click handler (e.g. select metric) |
-| `sx` | `object` | `{}` | MUI `sx` overrides for the root card container |
-| `titleSx` | `object` | `{}` | MUI `sx` overrides for the title text |
-| `valueSx` | `object` | `{}` | MUI `sx` overrides for the main value text |
-| `captionSx` | `object` | `{}` | MUI `sx` overrides for the caption text |
-| `avatarSx` | `object` | `{}` | MUI `sx` overrides for the icon avatar |
-
-## Development
-
-To preview the component locally:
-
-```bash
-npm run dev
-```
-
-To build the package:
-
-```bash
-npm run build
-```
-
-The build outputs ESM and CommonJS bundles in the `dist` folder, including separate `RenderChartCard`, `ActiveCampaignsCard`, and `MetricCard` bundles for tree-shaking.
+# @ammarkhalidfarooq/dashboard-package
+
+A reusable React Dashboard component library.
+
+## Installation
+
+```bash
+npm install @ammarkhalidfarooq/dashboard-package
+```
+
+Peer dependencies are required in your app:
+
+- `react`, `react-dom`
+- `@mui/material`, `@mui/icons-material`, `@emotion/react`, `@emotion/styled`
+- `apexcharts`, `react-apexcharts`
+
+## Usage
+
+### Full Dashboard
+
+```jsx
+import React from "react";
+import { Dashboard } from "@ammarkhalidfarooq/dashboard-package";
+
+const App = () => {
+  return <Dashboard />;
+};
+
+export default App;
+```
+
+### RenderChartCard (tree-shakeable)
+
+Import only the chart card bundle — avoids pulling in the full dashboard:
+
+```jsx
+import RenderChartCard from "@ammarkhalidfarooq/dashboard-package/RenderChartCard";
+```
+
+Or import from the main entry:
+
+```jsx
+import { RenderChartCard } from "@ammarkhalidfarooq/dashboard-package";
+```
+
+**Example:**
+
+```jsx
+import { useState } from "react";
+import Grid from "@mui/material/Grid";
+import RenderChartCard from "@ammarkhalidfarooq/dashboard-package/RenderChartCard";
+
+const chartItem = {
+  label: "Revenue per Visitor",
+  value: "$5.12",
+  subtitle: "Last 30 days · daily aggregation",
+  trend: "18% vs last month",
+  data: [3000, 4500, 4200, 5800, 5200, 7100, 8500, 9200, 5000],
+  categories: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep"],
+};
+
+const App = () => {
+  const [metric, setMetric] = useState("Revenue");
+
+  return (
+    <Grid container spacing={3}>
+      <RenderChartCard
+        item={chartItem}
+        index={0}
+        isPremium
+        md={6}
+        metric={metric}
+        setMetric={setMetric}
+      />
+    </Grid>
+  );
+};
+
+export default App;
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `item` | `object` | — | Chart config (see below) |
+| `index` | `number` | — | Unique index for the chart |
+| `isPrimary` | `boolean` | `false` | Uses a taller chart area |
+| `isPremium` | `boolean` | `false` | Premium card layout with trend badge |
+| `metric` | `string` | — | Active metric label (e.g. `"Revenue"`) |
+| `setMetric` | `function` | — | Metric change handler |
+| `md` | `number` | `4` | Grid column width on `md` breakpoint |
+| `type` | `string` | `"area"` | Chart type (`"area"`, `"bar"`, `"donut"`, etc.) |
+| `sx` | `object` | `{}` | MUI `sx` overrides for the grid item wrapper |
+| `cardSx` | `object` | `{}` | MUI `sx` overrides for the card container |
+| `contentSx` | `object` | `{}` | MUI `sx` overrides for the card content area |
+
+**`item` shape (common fields):**
+
+```js
+{
+  label: "Revenue per Visitor",       // Card title
+  value: "$5.12",                     // Main metric value
+  subtitle: "Last 30 days",           // Optional subtitle (premium layout)
+  trend: "18% vs last month",         // Optional trend badge (premium layout)
+  data: [3000, 4500, 4200],           // Single-series chart data
+  categories: ["Jan", "Feb", "Mar"],  // X-axis labels
+  series: [{ name: "Paid Ads", data: [...] }], // Multi-series (optional)
+  stacked: false,                     // Stack series (optional)
+  showSelector: false,                // Show metric dropdown (optional)
+  hideControls: false,                // Hide menu / show legend only (optional)
+  height: 250,                        // Chart height override (optional)
+  type: "area",                       // Per-card chart type override (optional)
+  colors: ["#6366F1", "#10B981"],     // Custom chart colors (optional)
+  footer: { left: "Total", right: "$12k" }, // Optional footer row
+}
+```
+
+### ActiveCampaignsCard (tree-shakeable)
+
+A configurable table card — used for channel performance, active campaigns, and similar ranked lists.
+
+```jsx
+import ActiveCampaignsCard from "@ammarkhalidfarooq/dashboard-package/ActiveCampaignsCard";
+```
+
+Or import from the main entry:
+
+```jsx
+import { ActiveCampaignsCard } from "@ammarkhalidfarooq/dashboard-package";
+```
+
+**Channel performance example:**
+
+```jsx
+import ActiveCampaignsCard from "@ammarkhalidfarooq/dashboard-package/ActiveCampaignsCard";
+
+const channelRows = [
+  {
+    id: "M",
+    avatarBg: "#4267B2",
+    name: "Meta Ads",
+    val1: "$32,800",
+    val2: "$112,400",
+    val3: "3.4x",
+    val4: "$340",
+    type: "trend",
+    trendType: "up",
+    trendLabel: "Improving",
+    highlightVal3: true,
+    val3Color: "#22C55E",
+  },
+  {
+    id: "G",
+    avatarBg: "#4285F4",
+    name: "Google Ads",
+    val1: "$28,200",
+    val2: "$78,300",
+    val3: "2.8x",
+    val4: "$385",
+    type: "trend",
+    trendType: "up",
+    trendLabel: "Improving",
+    highlightVal3: true,
+    val3Color: "#22C55E",
+  },
+];
+
+const App = () => (
+  <ActiveCampaignsCard
+    title="Channel performance"
+    subtitle="Ad platforms ranked by ROAS"
+    columns={["channel", "spend", "revenue", "ROAS", "CPA", "trend"]}
+    gridTemplateColumns="2.2fr 1fr 1fr 0.8fr 0.8fr 1.2fr"
+    height="100%"
+    rows={channelRows}
+  />
+);
+
+export default App;
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `"Active campaigns"` | Card title |
+| `subtitle` | `string` | `"Live fundraisers ranked by velocity"` | Card subtitle |
+| `actionLabel` | `string` | — | Optional top-right action link text |
+| `columns` | `string[]` | `["Campaign", "Raised", "Progress", "Donors", "Avg gift"]` | Table header labels |
+| `rows` | `object[]` | `[]` | Table row data (see below) |
+| `gridTemplateColumns` | `string` | `"3fr 1fr 1.5fr 0.8fr 1fr"` | CSS grid column template |
+| `height` | `string` | — | Card height (e.g. `"100%"`) |
+| `compact` | `boolean` | `false` | Smaller typography and spacing |
+| `sx` | `object` | `{}` | MUI `sx` overrides for the root card container |
+| `headerSx` | `object` | `{}` | MUI `sx` overrides for the title / subtitle header row |
+| `tableSx` | `object` | `{}` | MUI `sx` overrides for the scrollable table area |
+
+**`row` shape:**
+
+```js
+// Channel performance / trend table (6 columns)
+{
+  id: "M",                    // Avatar label (optional)
+  avatarBg: "#4267B2",        // Avatar background color
+  name: "Meta Ads",           // Row label
+  val1: "$32,800",            // Column 2 (spend / raised)
+  val2: "$112,400",           // Column 3 when type !== "progress"
+  val3: "3.4x",               // Column 4 (ROAS / donors)
+  val4: "$340",               // Column 5 (CPA / avg gift)
+  type: "trend",              // "trend" | "progress" — controls column 3 & 6
+  trendType: "up",            // "up" | "down" (when type is "trend")
+  trendLabel: "Improving",    // Trend badge text
+  highlightVal3: true,        // Highlight column 4 value
+  val3Color: "#22C55E",       // Highlight color for column 4
+}
+
+// Campaign progress table (5 columns)
+{
+  id: "1",
+  name: "Ramadan Appeal",
+  val1: "$45,200",
+  type: "progress",
+  progress: 72,
+  progressColor: "rgb(99, 99, 230)",
+  val3: "1,240",
+  val4: "$36.45",
+  status: "Live",
+  statusBg: "#DCFCE7",
+  statusColor: "#166534",
+}
+```
+
+### MetricCard (tree-shakeable)
+
+A compact KPI card with icon, value, and caption — used for selectable overview metrics.
+
+```jsx
+import MetricCard from "@ammarkhalidfarooq/dashboard-package/MetricCard";
+```
+
+Or import from the main entry:
+
+```jsx
+import { MetricCard } from "@ammarkhalidfarooq/dashboard-package";
+```
+
+**Example:**
+
+```jsx
+import { useState } from "react";
+import { PaidOutlined as DollarIcon } from "@mui/icons-material";
+import MetricCard from "@ammarkhalidfarooq/dashboard-package/MetricCard";
+
+const App = () => {
+  const [active, setActive] = useState("Total Raised");
+
+  return (
+    <MetricCard
+      title="Total Raised"
+      value="$124,500"
+      caption="12.4% vs last month"
+      icon={<DollarIcon />}
+      active={active === "Total Raised"}
+      onClick={() => setActive("Total Raised")}
+    />
+  );
+};
+
+export default App;
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | — | Card label |
+| `value` | `string` | — | Main metric value |
+| `caption` | `string` | — | Subtitle / trend text below the value |
+| `icon` | `ReactNode` | — | Icon shown in the top-right avatar |
+| `active` | `boolean` | `false` | Highlights the card as selected |
+| `warning` | `boolean` | `false` | Warning border and icon styling |
+| `error` | `boolean` | `false` | Error border and caption styling |
+| `onClick` | `function` | — | Click handler (e.g. select metric) |
+| `sx` | `object` | `{}` | MUI `sx` overrides for the root card container |
+| `titleSx` | `object` | `{}` | MUI `sx` overrides for the title text |
+| `valueSx` | `object` | `{}` | MUI `sx` overrides for the main value text |
+| `captionSx` | `object` | `{}` | MUI `sx` overrides for the caption text |
+| `avatarSx` | `object` | `{}` | MUI `sx` overrides for the icon avatar |
+
+## Development
+
+To preview the component locally:
+
+```bash
+npm run dev
+```
+
+To build the package:
+
+```bash
+npm run build
+```
+
+The build outputs ESM and CommonJS bundles in the `dist` folder, including separate `RenderChartCard`, `ActiveCampaignsCard`, and `MetricCard` bundles for tree-shaking.