@elabs-ai/components-ui 4.2.0 → 5.0.0

package/src/components/meter/meter.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+import { forwardRef, type HTMLAttributes } from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/cn";
+
+/**
+ * Meter — a word-sized read-only quantity: a confidence, a share of a
+ * ceiling, "4 of 5 signals held".
+ *
+ * NOT a `Progress` (dedupe audit, 2026-09-18): `Progress` is a
+ * `role="progressbar"` — assistive tech announces it as a task in flight and
+ * it is block-level by design. A meter is the ARIA `meter` role: a scalar
+ * within a known range that is not going anywhere. The two share the visual
+ * recipe (track, fill, an optional reference tick) so a page that mixes them
+ * reads as one system; they differ in semantics, default ink and size.
+ *
+ * - Default fill is `foreground` ink, not `primary`: a quantity is a fact,
+ *   not an action or a status. The status tones exist for the case where the
+ *   quantity IS a verdict (over a ceiling → `destructive`), and a non-default
+ *   tone must be paired with `aria-valuetext` so the state is never color-only.
+ * - `segments` turns the continuous track into a countable strip of discrete
+ *   cells ("|||| 4 of 5"): five facts read better as five marks than as 80%.
+ * - `marker` draws a reference tick (a ceiling, a target) outside the clipped
+ *   track, exactly as `Progress.marker` does; `markerLabel` joins the value
+ *   text so AT hears the reference too.
+ */
+export const meterVariants = cva("relative w-full overflow-hidden rounded-full bg-muted", {
+  variants: {
+    size: {
+      xs: "h-1",
+      sm: "h-2",
+      md: "h-3",
+    },
+  },
+  defaultVariants: { size: "sm" },
+});
+
+export const meterFillVariants = cva("block h-full rounded-full", {
+  variants: {
+    variant: {
+      default: "bg-foreground",
+      success: "bg-success",
+      warning: "bg-warning",
+      destructive: "bg-destructive",
+    },
+  },
+  defaultVariants: { variant: "default" },
+});
+
+export interface MeterProps
+  extends
+    Omit<HTMLAttributes<HTMLDivElement>, "children">,
+    VariantProps<typeof meterVariants>,
+    VariantProps<typeof meterFillVariants> {
+  /** The measured value. Clamped to `[min, max]` for the fill; reported as-is to AT. */
+  value: number;
+  /** Range floor. Default 0. */
+  min?: number;
+  /** Range ceiling. Default 100. */
+  max?: number;
+  /**
+   * Draw the track as this many discrete cells instead of one continuous
+   * fill; the value fills `round((value − min) / (max − min) × segments)` of
+   * them. For "n of m" facts pass `segments={m}` with `max={m}`.
+   */
+  segments?: number;
+  /**
+   * Reference point on the same scale as `value` (a ceiling, a target),
+   * rendered as a thin vertical tick on the track. Unset renders no tick.
+   */
+  marker?: number;
+  /**
+   * What `marker` represents, already localized ("ceiling $500"). Appended to
+   * the accessible value text; a caller-supplied `aria-valuetext` always wins.
+   */
+  markerLabel?: string;
+}
+
+export const Meter = forwardRef<HTMLDivElement, MeterProps>(function Meter(
+  {
+    value,
+    min = 0,
+    max = 100,
+    segments,
+    marker,
+    markerLabel,
+    size,
+    variant,
+    className,
+    "aria-valuetext": ariaValuetext,
+    ...props
+  },
+  ref,
+) {
+  const span = max - min;
+  const fraction = span > 0 ? Math.min(1, Math.max(0, (value - min) / span)) : 0;
+  const hasMarker = typeof marker === "number" && Number.isFinite(marker);
+  const markerFraction = hasMarker
+    ? Math.min(1, Math.max(0, span > 0 ? ((marker as number) - min) / span : 0))
+    : 0;
+  const resolvedValuetext =
+    ariaValuetext ?? (hasMarker && markerLabel ? `${value}, ${markerLabel}` : undefined);
+  const cells =
+    typeof segments === "number" && segments > 0 ? Math.max(1, Math.floor(segments)) : 0;
+  const filledCells = cells ? Math.round(fraction * cells) : 0;
+
+  const track = cells ? (
+    <div
+      ref={ref}
+      aria-valuemax={max}
+      aria-valuemin={min}
+      aria-valuenow={value}
+      aria-valuetext={resolvedValuetext}
+      className={cn(
+        "flex w-full items-stretch gap-px",
+        size === "xs" ? "h-1" : size === "md" ? "h-3" : "h-2",
+        className,
+      )}
+      data-slot="meter"
+      data-variant={variant ?? "default"}
+      role="meter"
+      {...props}
+    >
+      {Array.from({ length: cells }, (_, i) => (
+        <span
+          className={cn(
+            "min-w-0 flex-1 rounded-full",
+            i < filledCells ? meterFillVariants({ variant }) : "bg-muted",
+          )}
+          data-slot="meter-cell"
+          key={i}
+        />
+      ))}
+    </div>
+  ) : (
+    <div
+      ref={ref}
+      aria-valuemax={max}
+      aria-valuemin={min}
+      aria-valuenow={value}
+      aria-valuetext={resolvedValuetext}
+      className={cn(meterVariants({ size }), className)}
+      data-slot="meter"
+      data-variant={variant ?? "default"}
+      role="meter"
+      {...props}
+    >
+      <span
+        className={meterFillVariants({ variant })}
+        data-slot="meter-fill"
+        style={{ width: `${fraction * 100}%` }}
+      />
+    </div>
+  );
+
+  if (!hasMarker || cells) return track;
+
+  return (
+    // Same construction as `Progress.marker`: the tick is a sibling of the
+    // clipped track so it is never cut off, and the wrapper mirrors
+    // `className` so the tick's percentage is measured against the same box.
+    <div className={cn("relative", className)}>
+      {track}
+      <span
+        aria-hidden={markerLabel ? undefined : "true"}
+        className="pointer-events-none absolute -top-0.5 -bottom-0.5 w-0.5 rounded-full bg-foreground"
+        data-slot="meter-marker"
+        style={{ insetInlineStart: `${markerFraction * 100}%` }}
+      />
+    </div>
+  );
+});

package/src/components/metric-card/index.ts

@@ -1 +1,6 @@
-export { MetricCard, type MetricCardProps, type MetricCardEmphasis } from "./metric-card";
+export {
+  MetricCard,
+  type MetricCardProps,
+  type MetricCardEmphasis,
+  type MetricCardSize,
+} from "./metric-card";

package/src/components/metric-card/metric-card.stories.tsx

@@ -224,3 +224,66 @@ export const Loading: Story = {
     loading: true,
   },
 };
+
+/**
+ * Stand-in trend line. `ui` never imports `charts`, so a real app passes
+ * `<Sparkline …/>` from `@elabs-ai/components-charts` into the same slot.
+ */
+function TrendStub() {
+  return (
+    <svg
+      aria-hidden="true"
+      className="h-8 w-full text-primary"
+      viewBox="0 0 100 32"
+      preserveAspectRatio="none"
+    >
+      <polyline
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        points="0,26 20,22 40,24 60,14 80,12 100,4"
+      />
+    </svg>
+  );
+}
+
+/** `size="sm"` — label + value only, for the smallest sheet tiles (RM-072). */
+export const SizeSmall: Story = {
+  args: {
+    size: "sm",
+    label: "Active users",
+    value: "24,512",
+    delta: "12.4%",
+    deltaDirection: "up",
+    sparkline: <TrendStub />,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("24,512")).toBeInTheDocument();
+    await expect(canvas.queryByText("12.4%")).toBeNull();
+  },
+};
+
+/** The `sparkline` slot sits directly under the value (RM-072). */
+export const WithSparklineSlot: Story = {
+  args: {
+    label: "Active users",
+    value: "24,512",
+    delta: "12.4%",
+    deltaDirection: "up",
+    description: "Last 30 days",
+    sparkline: <TrendStub />,
+  },
+};
+
+/** `size="lg"` — the kpi value rung with room for the trend slot (RM-072). */
+export const SizeLarge: Story = {
+  args: {
+    size: "lg",
+    label: "Active users",
+    value: "24,512",
+    delta: "12.4%",
+    deltaDirection: "up",
+    sparkline: <TrendStub />,
+  },
+};

package/src/components/metric-card/metric-card.test.tsx

@@ -195,4 +195,87 @@ describe("MetricCard", () => {
       expect(screen.getByText("50M")).toBeInTheDocument();
     });
   });
+
+  // RM-109: `valueFormat` also accepts the object form (`NumberFormatSpec`).
+  describe("value formatting — object spec form (RM-109)", () => {
+    it("applies decimals + suffix from a spec object", () => {
+      render(
+        <MetricCard label="Conversion" value={12.844} valueFormat={{ decimals: 1, suffix: "%" }} />,
+      );
+      expect(screen.getByText("12.8%")).toBeInTheDocument();
+    });
+
+    it("applies a prefix and forced sign", () => {
+      render(
+        <MetricCard
+          label="Delta"
+          value={1284}
+          valueFormat={{ abbreviate: true, decimals: 1, prefix: "Δ ", sign: "always" }}
+        />,
+      );
+      expect(screen.getByText("Δ +1.3K")).toBeInTheDocument();
+    });
+
+    it("renders string presets byte-identically after the type widened", () => {
+      render(<MetricCard currency="EUR" label="Revenue" value={1234} valueFormat="currency" />);
+      expect(screen.getByRole("button")).toHaveTextContent("€");
+    });
+  });
+
+  describe("size tiers (RM-072)", () => {
+    it("size=sm renders label + value only — no delta row, description or slots", () => {
+      render(
+        <MetricCard
+          size="sm"
+          label="Revenue"
+          value="$42,000"
+          delta="+12.4%"
+          deltaDirection="up"
+          description="vs last month"
+          icon={<svg data-testid="icon" />}
+          sparkline={<svg data-testid="spark" />}
+          visual={<div data-testid="visual" />}
+          evidence={<span>Grounded</span>}
+        />,
+      );
+      expect(screen.getByText("Revenue")).toBeInTheDocument();
+      expect(screen.getByText("$42,000")).toBeInTheDocument();
+      expect(screen.queryByText("+12.4%")).not.toBeInTheDocument();
+      expect(screen.queryByText("vs last month")).not.toBeInTheDocument();
+      expect(screen.queryByTestId("icon")).not.toBeInTheDocument();
+      expect(screen.queryByTestId("spark")).not.toBeInTheDocument();
+      expect(screen.queryByTestId("visual")).not.toBeInTheDocument();
+      expect(screen.queryByText("Grounded")).not.toBeInTheDocument();
+      expect(screen.getByText("$42,000")).toHaveClass("text-title");
+    });
+
+    it("renders the sparkline slot directly under the value, before the description", () => {
+      render(
+        <MetricCard
+          label="Revenue"
+          value="$42,000"
+          description="vs last month"
+          sparkline={<svg data-testid="spark" />}
+        />,
+      );
+      const valueRow = screen.getByText("$42,000").parentElement as HTMLElement;
+      const sparkWrap = screen.getByTestId("spark").parentElement as HTMLElement;
+      expect(valueRow.nextElementSibling).toBe(sparkWrap);
+      expect(sparkWrap.nextElementSibling).toBe(screen.getByText("vs last month"));
+    });
+
+    it("size=lg uses the kpi value rung", () => {
+      render(<MetricCard size="lg" label="Revenue" value="$42,000" />);
+      const value = screen.getByText("$42,000");
+      expect(value).toHaveClass("text-kpi");
+      expect(value).not.toHaveClass("text-2xl");
+    });
+
+    it("default size keeps today's value classes", () => {
+      render(<MetricCard label="Revenue" value="$42,000" />);
+      expect(screen.getByText("$42,000").className).toBe(
+        "tabular-nums text-foreground text-2xl font-semibold tracking-tight",
+      );
+    });
+  });
 });

package/src/components/metric-card/metric-card.tsx

@@ -7,7 +7,34 @@ import { CopyableValue } from "../copyable-value";
 import { Skeleton } from "../skeleton";
 import { useLocale } from "../locale-provider";
 import { cn } from "../../lib/cn";
-import { type NumberFormatKind, numberFormatOptions } from "../../lib/compact-number";
+import {
+  type NumberFormat,
+  type ResolvedNumberFormat,
+  resolveNumberFormat,
+} from "../../lib/compact-number";
+
+/**
+ * Applies a {@link ResolvedNumberFormat}'s `prefix`/`suffix`/`parens` on top
+ * of the plain `Intl` string `formatNumber` produces — the two things Intl
+ * itself cannot render (RM-109). Twin of `formatResolvedChartValue`
+ * (`packages/charts/src/charts/chart-formatters.ts`).
+ */
+function formatResolvedNumber(
+  resolved: ResolvedNumberFormat,
+  formatNumber: (n: number, opts?: Intl.NumberFormatOptions) => string,
+  value: number,
+): string {
+  const numeric = formatNumber(resolved.parens ? Math.abs(value) : value, resolved.options);
+  const signed = resolved.parens && value < 0 ? `(${numeric})` : numeric;
+  return `${resolved.prefix}${signed}${resolved.suffix}`;
+}
+
+/*
+ * ADR 0012: this is the ONE KPI tile — `@elabs-ai/components-charts` re-exports it.
+ * RM-072 adds `size` (sm | md | lg) for dashboard-sheet tiles and a `sparkline`
+ * slot under the value. `ui` never imports `charts`: the host passes the
+ * `<Sparkline …/>` element in.
+ */
 
 /*
  * `emphasis` — size/weight/space ONLY, no new hue (research 11 §B.5 KPI-1/5):
@@ -22,8 +49,14 @@ const metricValueVariants = cva("tabular-nums text-foreground", {
       default: "text-2xl font-semibold tracking-tight",
       headline: "text-kpi",
     },
+    /* `md` adds nothing (today's rungs); `sm`/`lg` override the size via `cn()`. */
+    size: {
+      sm: "text-title",
+      md: "",
+      lg: "text-kpi",
+    },
   },
-  defaultVariants: { emphasis: "default" },
+  defaultVariants: { emphasis: "default", size: "md" },
 });
 
 const metricContentVariants = cva("space-y-2", {
@@ -32,12 +65,36 @@ const metricContentVariants = cva("space-y-2", {
       default: "p-5",
       headline: "p-6",
     },
+    size: {
+      sm: "space-y-1 p-3",
+      md: "",
+      lg: "p-6",
+    },
+  },
+  defaultVariants: { emphasis: "default", size: "md" },
+});
+
+const metricSparklineVariants = cva("", {
+  variants: {
+    size: {
+      /* never rendered — `sm` drops the slot; kept so the axis is total */
+      sm: "",
+      md: "pt-1",
+      lg: "min-h-12 pt-2",
+    },
   },
-  defaultVariants: { emphasis: "default" },
+  defaultVariants: { size: "md" },
 });
 
 export type MetricCardEmphasis = NonNullable<VariantProps<typeof metricValueVariants>["emphasis"]>;
 
+/**
+ * Tile tier (RM-072). `sm`: label + value only (no icon, delta, description,
+ * sparkline, visual or evidence); `md`: the default tile; `lg`: the kpi value
+ * rung with more room for the `sparkline` slot.
+ */
+export type MetricCardSize = NonNullable<VariantProps<typeof metricValueVariants>["size"]>;
+
 /**
  * How a NUMERIC `value` is rendered. A function takes over completely.
  *
@@ -46,8 +103,15 @@ export type MetricCardEmphasis = NonNullable<VariantProps<typeof metricValueVari
  * away via `CopyableValue`. Anything that is not a `number` (a string, an
  * element) is passed through untouched, so every existing call site is
  * unaffected.
+ *
+ * Also accepts the object form (RM-109, `NumberFormatSpec` —
+ * `{ decimals, abbreviate, sign, prefix, suffix, … }`,
+ * `packages/ui/src/lib/compact-number.ts`) for a tile that needs e.g.
+ * `{ decimals: 1, suffix: "%" }` without hand-formatting the string itself.
+ * The two preset-string cases render byte-for-byte as before this type
+ * widened — only a spec OBJECT argument reaches the new code path.
  */
-export type MetricCardValueFormat = NumberFormatKind | ((value: number) => ReactNode);
+export type MetricCardValueFormat = NumberFormat | ((value: number) => ReactNode);
 
 export interface MetricCardProps
   extends HTMLAttributes<HTMLDivElement>, VariantProps<typeof metricValueVariants> {
@@ -74,8 +138,13 @@ export interface MetricCardProps
   /** Whether "up" is good (green) — flip for metrics where down is good. */
   positiveIsGood?: boolean;
   icon?: ReactNode;
-  /** Optional inline visual (e.g. a sparkline) shown under the value/description. */
+  /** Optional inline visual shown under the value/description. */
   visual?: ReactNode;
+  /**
+   * Trend slot rendered directly under the value (RM-072) — pass a
+   * `<Sparkline …/>` from `@elabs-ai/components-charts`. Hidden at `size="sm"`.
+   */
+  sparkline?: ReactNode;
   /**
    * Optional grounding footer (research 11 §B.5 KPI-3) — connects a cited
    * figure to its source (e.g. an `EvidenceChip` from `@elabs-ai/components-ai`). Rendered
@@ -111,8 +180,10 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
     positiveIsGood = true,
     icon,
     visual,
+    sparkline,
     evidence,
     emphasis,
+    size,
     loading = false,
     announceLoading = true,
     className,
@@ -130,7 +201,11 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
     ? value
     : typeof valueFormat === "function"
       ? valueFormat(value)
-      : formatNumber(value, numberFormatOptions(valueFormat, value, currency));
+      : formatResolvedNumber(
+          resolveNumberFormat(valueFormat, value, currency),
+          formatNumber,
+          value,
+        );
   // Only offer the exact figure when the display actually differs from it —
   // a button around a value that was never shortened is noise.
   const showsExact = isNumeric && String(formattedValue) === String(value);
@@ -152,11 +227,14 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
   // polarity is otherwise invisible to AT. See accessibility.md, #162.
   const directionLabel = deltaDirection === "up" ? "up" : deltaDirection === "down" ? "down" : "";
   const polarityLabel = good === null ? "" : good ? ", favorable" : ", unfavorable";
+  // `sm` is label + value only: every secondary row is dropped (RM-072).
+  const compact = size === "sm";
+  const valueClassName = cn(metricValueVariants({ emphasis, size }));
 
   return (
     <Card ref={ref} className={cn("overflow-hidden", className)} {...props}>
       <CardContent
-        className={metricContentVariants({ emphasis })}
+        className={cn(metricContentVariants({ emphasis, size }))}
         {...(loading && announceLoading ? { role: "status", "aria-live": "polite" as const } : {})}
       >
         {loading && announceLoading ? (
@@ -185,7 +263,7 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
           )}
           {/* `shrink-0`: the icon is a fixed 16px mark, so the LABEL is what
               gives way when the row runs out of width. */}
-          {icon ? (
+          {icon && !compact ? (
             <span className="shrink-0 text-muted-foreground [&_svg]:size-4">{icon}</span>
           ) : null}
         </div>
@@ -194,7 +272,7 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
             <Skeleton className={emphasis === "headline" ? "h-9 w-28" : "h-8 w-24"} />
           ) : canCopyExact ? (
             <CopyableValue
-              className={metricValueVariants({ emphasis })}
+              className={valueClassName}
               // Two tiles in one grid can compact to the same display ("$1.2M"),
               // and the visible label is a sibling node the button's name does
               // not include — so without this a screen-reader user tabbing the
@@ -208,9 +286,9 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
               {formattedValue}
             </CopyableValue>
           ) : (
-            <span className={metricValueVariants({ emphasis })}>{formattedValue}</span>
+            <span className={valueClassName}>{formattedValue}</span>
           )}
-          {delta ? (
+          {delta && !compact ? (
             loading ? (
               <Skeleton className="h-4 w-14" />
             ) : (
@@ -227,17 +305,22 @@ export const MetricCard = forwardRef<HTMLDivElement, MetricCardProps>(function M
             )
           ) : null}
         </div>
-        {description ? (
+        {sparkline && !compact ? (
+          <div className={metricSparklineVariants({ size })}>
+            {loading ? <Skeleton className="h-8 w-full" /> : sparkline}
+          </div>
+        ) : null}
+        {description && !compact ? (
           loading ? (
             <Skeleton className="h-3 w-32" />
           ) : (
             <p className="text-meta font-normal text-muted-foreground">{description}</p>
           )
         ) : null}
-        {visual ? (
+        {visual && !compact ? (
           <div className="pt-1">{loading ? <Skeleton className="h-8 w-full" /> : visual}</div>
         ) : null}
-        {evidence ? (
+        {evidence && !compact ? (
           <div className="pt-1 text-meta font-normal text-muted-foreground">
             {loading ? <Skeleton className="h-3 w-24" /> : evidence}
           </div>

package/src/components/nav-user/nav-user.test.tsx

@@ -1,5 +1,6 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { SidebarProvider } from "../sidebar";
 import { NavUser } from "./nav-user";
 
@@ -26,4 +27,25 @@ describe("NavUser", () => {
     );
     expect(screen.getAllByText("JS").length).toBeGreaterThan(0);
   });
+
+  it("opens the account menu with Settings and Sign out", async () => {
+    const onSignOut = vi.fn();
+    render(
+      <Wrapper>
+        <NavUser
+          user={{ name: "Jane Doe", email: "jane@example.com" }}
+          settingsHref="/settings"
+          onSignOut={onSignOut}
+        />
+      </Wrapper>,
+    );
+    const user = userEvent.setup();
+    await user.click(screen.getByRole("button", { name: "Jane Doe jane@example.com" }));
+    expect(await screen.findByRole("menuitem", { name: "Settings" })).toHaveAttribute(
+      "href",
+      "/settings",
+    );
+    await user.click(screen.getByRole("menuitem", { name: "Sign out" }));
+    expect(onSignOut).toHaveBeenCalledTimes(1);
+  });
 });