feat: add MetricCard component for dashboard KPIs

.changeset/metriccard-component.md

@@ -0,0 +1,16 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Add `MetricCard` component for dashboard KPI summaries (title, value, optional trend and description).
+
+```tsx
+import { MetricCard } from "@tailor-platform/app-shell";
+
+<MetricCard
+  title="Net total payment"
+  value="$1,500.00"
+  trend={{ direction: "up", value: "+5%" }}
+  description="vs last month"
+/>;
+```

docs/components/metric-card.md

@@ -0,0 +1,76 @@
+---
+title: MetricCard
+description: Compact card for dashboard KPI summaries with title, value, optional trend and description
+---
+
+# MetricCard
+
+`MetricCard` is a presentational card for displaying a single KPI (key performance indicator) on dashboards. It shows a small title, a prominent value, and optionally a trend indicator and supplementary description text. In v1 the component is static (no click handler or internal actions).
+
+## Import
+
+```tsx
+import { MetricCard } from "@tailor-platform/app-shell";
+```
+
+## Basic Usage
+
+```tsx
+<MetricCard
+  title="Net total payment"
+  value="$1,500.00"
+  trend={{ direction: "up", value: "+5%" }}
+  description="vs last month"
+/>
+```
+
+## Props
+
+| Prop          | Type                                                        | Default      | Description                                                                                                            |
+| ------------- | ----------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `title`       | `string`                                                    | **Required** | Short title / header (e.g. "Net total", "Revenue")                                                                     |
+| `value`       | `React.ReactNode`                                           | **Required** | Main value (string, number, or custom content)                                                                         |
+| `trend`       | `{ direction: "up" \| "down" \| "neutral"; value: string }` | -            | Optional trend (e.g. "+12%", "-5%", "0%")                                                                              |
+| `description` | `string`                                                    | -            | Optional supplementary text (e.g. "vs last month", "this week"). Empty strings are treated as absent and not rendered. |
+| `icon`        | `React.ReactNode`                                           | -            | Optional icon in the title row                                                                                         |
+| `className`   | `string`                                                    | -            | Additional CSS classes for the card root                                                                               |
+
+## Trend Directions
+
+- **up** — Positive change (success styling, e.g. green).
+- **down** — Negative change (destructive styling, e.g. red).
+- **neutral** — No change or neutral (muted styling).
+
+```tsx
+<MetricCard
+  title="Revenue"
+  value="$2,400"
+  trend={{ direction: "up", value: "+12%" }}
+  description="vs last month"
+/>
+
+<MetricCard
+  title="Costs"
+  value="$800"
+  trend={{ direction: "down", value: "-5%" }}
+  description="vs last quarter"
+/>
+
+<MetricCard
+  title="Balance"
+  value="$0"
+  trend={{ direction: "neutral", value: "0%" }}
+/>
+```
+
+## With Icon
+
+```tsx
+<MetricCard title="Total orders" value="142" icon={<OrderIcon />} description="this week" />
+```
+
+## Related
+
+- [Layout](./layout.md) — Page layout for placing MetricCards in a grid.
+- [DescriptionCard](./description-card.md) — Structured key-value cards for detail views.
+- [Badge](./badge.md) — Status badges that can complement metric displays.

examples/app-module/src/custom-module.tsx

@@ -21,6 +21,7 @@ import {
   Select,
   Combobox,
   Autocomplete,
+  MetricCard,
   type Guard,
 } from "@tailor-platform/app-shell";
 import type { SVGProps } from "react";
@@ -159,6 +160,57 @@ const actionPanelDemoResource = defineResource({
   component: ActionPanelDemoPage,
 });
 
+// ============================================================================
+// DEMO: MetricCard (KPI row)
+// ============================================================================
+
+const MetricCardDemoPage = () => (
+  <Layout>
+    <Layout.Header title="MetricCard Demo" />
+    <Layout.Column>
+      <p className="astw:text-sm astw:text-muted-foreground astw:mb-4">
+        Dashboard KPI cards: title, value, optional trend and description.
+      </p>
+      <div className="astw:flex astw:flex-row astw:flex-wrap astw:gap-4">
+        <div className="astw:min-w-[200px] astw:flex-1">
+          <MetricCard
+            title="Net total"
+            value="$1,500.00"
+            trend={{ direction: "up", value: "+5%" }}
+            description="vs last month"
+          />
+        </div>
+        <div className="astw:min-w-[200px] astw:flex-1">
+          <MetricCard
+            title="Discount total"
+            value="$120.00"
+            trend={{ direction: "down", value: "-2%" }}
+            description="vs last month"
+          />
+        </div>
+        <div className="astw:min-w-[200px] astw:flex-1">
+          <MetricCard
+            title="Orders"
+            value="42"
+            trend={{ direction: "neutral", value: "0%" }}
+            description="this week"
+            icon={<ZapIcon style={{ width: 14, height: 14 }} />}
+          />
+        </div>
+        <div className="astw:min-w-[200px] astw:flex-1">
+          <MetricCard title="Revenue (MTD)" value="$8,200" description="vs last month" />
+        </div>
+      </div>
+    </Layout.Column>
+  </Layout>
+);
+
+const metricCardDemoResource = defineResource({
+  path: "metric-card-demo",
+  meta: { title: "MetricCard Demo" },
+  component: MetricCardDemoPage,
+});
+
 // ============================================================================
 // DEMO: Purchase Order Detail Page
 // ============================================================================
@@ -1817,6 +1869,17 @@ export const customPageModule = defineModule({
               View Action Panel Demo
             </Link>
           </p>
+          <p>
+            <Link
+              to="/custom-page/metric-card-demo"
+              style={{
+                color: "hsl(var(--primary))",
+                textDecoration: "underline",
+              }}
+            >
+              View MetricCard Demo (KPI cards)
+            </Link>
+          </p>
           <p>
             <Link
               to="/custom-page/layout-1-column"
@@ -1908,6 +1971,7 @@ export const customPageModule = defineModule({
     adminOnlyResource,
     purchaseOrderDemoResource,
     actionPanelDemoResource,
+    metricCardDemoResource,
     oneColumnLayoutResource,
     twoColumnLayoutResource,
     threeColumnLayoutResource,

packages/core/src/components/metric-card/MetricCard.test.tsx

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+import { MetricCard } from "./MetricCard";
+
+const MockIcon = () => <span data-testid="mock-icon">icon</span>;
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("MetricCard", () => {
+  it("renders required title and value", () => {
+    render(<MetricCard title="Net total" value="$1,500.00" />);
+    expect(screen.getByText("Net total")).toBeDefined();
+    expect(screen.getByText("$1,500.00")).toBeDefined();
+  });
+
+  it("renders optional icon when provided", () => {
+    render(<MetricCard title="Total" value="$100" icon={<MockIcon />} />);
+    expect(screen.getByTestId("mock-icon")).toBeDefined();
+    expect(screen.getByText("Total")).toBeDefined();
+    expect(screen.getByText("$100")).toBeDefined();
+  });
+
+  it("renders trend up with value", () => {
+    render(
+      <MetricCard title="Revenue" value="$2,000" trend={{ direction: "up", value: "+12%" }} />,
+    );
+    expect(screen.getByText("+12%")).toBeDefined();
+    const trendEl = screen.getByText("+12%").closest("[data-direction]");
+    expect(trendEl?.getAttribute("data-direction")).toBe("up");
+  });
+
+  it("renders trend down with value", () => {
+    render(<MetricCard title="Costs" value="$500" trend={{ direction: "down", value: "-5%" }} />);
+    expect(screen.getByText("-5%")).toBeDefined();
+    const trendEl = screen.getByText("-5%").closest("[data-direction]");
+    expect(trendEl?.getAttribute("data-direction")).toBe("down");
+  });
+
+  it("renders trend neutral with value", () => {
+    render(<MetricCard title="Balance" value="$0" trend={{ direction: "neutral", value: "0%" }} />);
+    expect(screen.getByText("0%")).toBeDefined();
+    const trendEl = screen.getByText("0%").closest("[data-direction]");
+    expect(trendEl?.getAttribute("data-direction")).toBe("neutral");
+  });
+
+  it("renders description text when provided", () => {
+    render(<MetricCard title="Sales" value="$3,000" description="vs last month" />);
+    expect(screen.getByText("vs last month")).toBeDefined();
+  });
+
+  it("does not render description when description is empty string", () => {
+    const { container } = render(<MetricCard title="Sales" value="$3,000" description="" />);
+    expect(container.querySelector('[data-slot="metric-card"]')?.children.length).toBe(2);
+  });
+
+  it("renders trend and description together", () => {
+    render(
+      <MetricCard
+        title="Profit"
+        value="$1,200"
+        trend={{ direction: "up", value: "+8%" }}
+        description="vs last quarter"
+      />,
+    );
+    expect(screen.getByText("+8%")).toBeDefined();
+    expect(screen.getByText("vs last quarter")).toBeDefined();
+  });
+
+  it("does not render meta row when trend and description are absent", () => {
+    const { container } = render(<MetricCard title="Title" value="Value" />);
+    expect(container.querySelector('[data-slot="metric-card"]')?.children.length).toBe(2);
+  });
+
+  it("accepts custom className", () => {
+    const { container } = render(
+      <MetricCard title="KPI" value="42" className="custom-metric-card" />,
+    );
+    const card = container.firstChild as HTMLElement;
+    expect(card.className).toContain("custom-metric-card");
+  });
+});

packages/core/src/components/metric-card/MetricCard.tsx

@@ -0,0 +1,94 @@
+import { cn } from "../../lib/utils";
+import type { MetricCardProps, MetricCardTrendDirection } from "./types";
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+const iconSlotClasses =
+  "astw:flex astw:size-4 astw:items-center astw:justify-center astw:shrink-0 astw:text-muted-foreground";
+
+const trendDirectionClasses: Record<MetricCardTrendDirection, string> = {
+  up: "astw:text-green-600 dark:astw:text-green-400",
+  down: "astw:text-red-600 dark:astw:text-red-400",
+  neutral: "astw:text-muted-foreground",
+};
+
+// ============================================================================
+// METRIC CARD
+// ============================================================================
+
+/**
+ * MetricCard — Compact card for dashboard KPI display (title, value, optional trend and description).
+ *
+ * Static display only in v1. Use for summary metrics (e.g. net total, discount total).
+ * Styling follows existing card conventions (bg-card, border, rounded-xl).
+ *
+ * @example
+ * ```tsx
+ * <MetricCard
+ *   title="Net total payment"
+ *   value="$1,500.00"
+ *   trend={{ direction: "up", value: "+5%" }}
+ *   description="vs last month"
+ * />
+ * ```
+ */
+export function MetricCard({ title, value, trend, description, icon, className }: MetricCardProps) {
+  const hasMeta = trend != null || (description != null && description !== "");
+
+  return (
+    <div
+      data-slot="metric-card"
+      className={cn(
+        "astw:min-w-0 astw:w-full astw:bg-card astw:text-card-foreground astw:rounded-xl astw:border astw:px-4 astw:py-4",
+        className,
+      )}
+    >
+      {/* Top row: optional icon + title */}
+      <div className="astw:flex astw:items-center astw:gap-2 astw:mb-6">
+        {icon != null && (
+          <span className={iconSlotClasses} aria-hidden>
+            {icon}
+          </span>
+        )}
+        <span className="astw:text-sm astw:font-medium astw:text-muted-foreground astw:min-w-0 astw:truncate">
+          {title}
+        </span>
+      </div>
+
+      {/* Main value */}
+      <div className="astw:text-2xl astw:font-bold astw:tracking-tight astw:break-words">
+        {value}
+      </div>
+
+      {/* Optional meta row: trend + description */}
+      {hasMeta && (
+        <div className="astw:mt-2 astw:flex astw:items-center astw:gap-2 astw:flex-wrap">
+          {trend != null && (
+            <span
+              className={cn(
+                "astw:text-sm astw:font-medium",
+                trendDirectionClasses[trend.direction],
+              )}
+              data-direction={trend.direction}
+            >
+              {trend.value}
+            </span>
+          )}
+          {description != null && description !== "" && (
+            <span className="astw:text-sm astw:text-muted-foreground astw:truncate">
+              {description}
+            </span>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export default MetricCard;

packages/core/src/components/metric-card/index.ts

@@ -0,0 +1,2 @@
+export { MetricCard, default } from "./MetricCard";
+export type { MetricCardProps } from "./types";