@elabs-ai/components-ui 4.2.0 → 5.1.0

package/src/components/meter/index.ts

@@ -0,0 +1 @@
+export { Meter, meterFillVariants, meterVariants, type MeterProps } from "./meter";

package/src/components/meter/meter.stories.tsx

@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Meter } from "./meter";
+
+const meta = {
+  title: "Display/Meter",
+  component: Meter,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A word-sized read-only quantity — a confidence, a share of a ceiling, “4 of 5 signals held”. The ARIA `meter` role, not a `progressbar`: it is a fact within a range, not a task in flight. Default ink is `foreground`; a status tone must be paired with `aria-valuetext` so the state is never colour-only. `segments` draws a countable strip; `marker` draws a reference tick.",
+      },
+    },
+  },
+  argTypes: {
+    value: { control: "number", table: { category: "State" } },
+    min: { control: "number", table: { category: "Behavior" } },
+    max: { control: "number", table: { category: "Behavior" } },
+    segments: { control: "number", table: { category: "Behavior" } },
+    marker: { control: "number", table: { category: "Behavior" } },
+    size: {
+      control: { type: "select" },
+      options: ["xs", "sm", "md"],
+      table: { category: "Appearance" },
+    },
+    variant: {
+      control: { type: "select" },
+      options: ["default", "success", "warning", "destructive"],
+      table: { category: "Appearance" },
+    },
+  },
+  args: { "aria-label": "Share of ceiling", value: 62, className: "w-48" },
+} satisfies Meta<typeof Meter>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** The three heights; `xs` is the inline confidence rung beside a printed percentage. */
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-3">
+      <Meter {...args} size="xs" />
+      <Meter {...args} size="sm" />
+      <Meter {...args} size="md" />
+    </div>
+  ),
+};
+
+/** A quantity that IS a verdict takes a status tone — always with `aria-valuetext`. */
+export const Tones: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-3">
+      <Meter {...args} aria-valuetext="62 of 100" variant="default" />
+      <Meter {...args} aria-valuetext="62 of 100, healthy" variant="success" />
+      <Meter
+        {...args}
+        aria-valuetext="88 of 100, approaching the ceiling"
+        value={88}
+        variant="warning"
+      />
+      <Meter
+        {...args}
+        aria-valuetext="100 of 100, over the ceiling"
+        value={122}
+        variant="destructive"
+      />
+    </div>
+  ),
+};
+
+/** A ceiling drawn as a tick; the fill runs past it in the destructive rung. */
+export const WithMarker: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-3">
+      <Meter {...args} marker={500} markerLabel="ceiling 500" max={800} value={420} />
+      <Meter
+        {...args}
+        aria-valuetext="612 of 500, over the ceiling"
+        marker={500}
+        markerLabel="ceiling 500"
+        max={800}
+        value={612}
+        variant="destructive"
+      />
+    </div>
+  ),
+};
+
+/** “4 of 5 signals held” — five discrete facts drawn as five countable cells. */
+export const Segmented: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-3">
+      <Meter {...args} aria-label="Signals held" max={5} segments={5} value={5} />
+      <Meter {...args} aria-label="Signals held" max={5} segments={5} value={4} />
+      <Meter {...args} aria-label="Signals held" max={5} segments={5} value={2} />
+      <Meter {...args} aria-label="Seats active" max={42} segments={42} size="xs" value={41} />
+    </div>
+  ),
+};

package/src/components/meter/meter.test.tsx

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Meter } from "./meter";
+
+describe("Meter", () => {
+  it("is a meter, not a progressbar, and exposes the range to AT", () => {
+    render(<Meter aria-label="confidence" max={1} value={0.91} />);
+    const el = screen.getByRole("meter", { name: "confidence" });
+    expect(el).toHaveAttribute("aria-valuenow", "0.91");
+    expect(el).toHaveAttribute("aria-valuemin", "0");
+    expect(el).toHaveAttribute("aria-valuemax", "1");
+    expect(screen.queryByRole("progressbar")).toBeNull();
+  });
+
+  it("fills with foreground ink by default — a quantity, not a status", () => {
+    const { container } = render(<Meter aria-label="share" value={40} />);
+    const fill = container.querySelector('[data-slot="meter-fill"]');
+    expect(fill).toHaveClass("bg-foreground");
+    expect(fill).toHaveStyle({ width: "40%" });
+  });
+
+  it.each(["success", "warning", "destructive"] as const)("paints the %s tone", (variant) => {
+    const { container } = render(<Meter aria-label="share" value={40} variant={variant} />);
+    expect(container.querySelector('[data-slot="meter-fill"]')).toHaveClass(`bg-${variant}`);
+  });
+
+  it("clamps the fill but reports the raw value when over the ceiling", () => {
+    const { container } = render(
+      <Meter aria-label="spend" aria-valuetext="$612 of $500, over limit" max={500} value={612} />,
+    );
+    expect(container.querySelector('[data-slot="meter-fill"]')).toHaveStyle({ width: "100%" });
+    expect(screen.getByRole("meter")).toHaveAttribute("aria-valuenow", "612");
+    expect(screen.getByRole("meter")).toHaveAttribute("aria-valuetext", "$612 of $500, over limit");
+  });
+
+  it("renders a countable strip when segments is set", () => {
+    const { container } = render(<Meter aria-label="signals" max={5} segments={5} value={4} />);
+    const cells = container.querySelectorAll('[data-slot="meter-cell"]');
+    expect(cells).toHaveLength(5);
+    expect(cells[3]).toHaveClass("bg-foreground");
+    expect(cells[4]).toHaveClass("bg-muted");
+    expect(container.querySelector('[data-slot="meter-fill"]')).toBeNull();
+  });
+
+  it("draws a marker tick outside the clipped track and joins markerLabel to the value text", () => {
+    const { container } = render(
+      <Meter aria-label="spend" marker={500} markerLabel="ceiling 500" max={800} value={612} />,
+    );
+    const tick = container.querySelector('[data-slot="meter-marker"]') as HTMLElement;
+    expect(tick).not.toBeNull();
+    expect(tick.style.insetInlineStart).toBe("62.5%");
+    expect(tick.parentElement).not.toBe(screen.getByRole("meter"));
+    expect(screen.getByRole("meter")).toHaveAttribute("aria-valuetext", "612, ceiling 500");
+  });
+
+  it("renders no tick and no wrapper when marker is unset", () => {
+    const { container } = render(<Meter aria-label="share" value={40} />);
+    expect(container.querySelector('[data-slot="meter-marker"]')).toBeNull();
+    expect(container.firstElementChild).toBe(screen.getByRole("meter"));
+  });
+});

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",
+      );
+    });
+  });
 });