@elabs-ai/components-ui 4.0.0

package/src/components/menubar/menubar.tsx

@@ -0,0 +1,198 @@
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type ElementRef,
+  type HTMLAttributes,
+} from "react";
+import * as MenubarPrimitive from "@radix-ui/react-menubar";
+import { Check, ChevronRight, Circle } from "lucide-react";
+import { cn } from "../../lib/cn";
+
+// Pure re-exports (not `const X = Primitive.Y`) so tsc need not emit a portable
+// type name for these — avoids TS2742 against transitive @radix-ui/react-context.
+export {
+  Menu as MenubarMenu,
+  Group as MenubarGroup,
+  Portal as MenubarPortal,
+  Sub as MenubarSub,
+  RadioGroup as MenubarRadioGroup,
+} from "@radix-ui/react-menubar";
+
+export const Menubar = forwardRef<
+  ElementRef<typeof MenubarPrimitive.Root>,
+  ComponentPropsWithoutRef<typeof MenubarPrimitive.Root>
+>(function Menubar({ className, ...props }, ref) {
+  return (
+    <MenubarPrimitive.Root
+      ref={ref}
+      className={cn("flex h-9 items-center gap-1 rounded-md bg-card p-1 shadow-ring-sm", className)}
+      {...props}
+    />
+  );
+});
+
+export const MenubarTrigger = forwardRef<
+  ElementRef<typeof MenubarPrimitive.Trigger>,
+  ComponentPropsWithoutRef<typeof MenubarPrimitive.Trigger>
+>(function MenubarTrigger({ className, ...props }, ref) {
+  return (
+    <MenubarPrimitive.Trigger
+      ref={ref}
+      className={cn(
+        "flex cursor-default select-none items-center rounded-sm px-3 py-1 text-sm font-medium outline-none transition-colors duration-fast focus:bg-accent data-[state=open]:bg-accent",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export const MenubarContent = forwardRef<
+  ElementRef<typeof MenubarPrimitive.Content>,
+  ComponentPropsWithoutRef<typeof MenubarPrimitive.Content>
+>(function MenubarContent(
+  { className, align = "start", alignOffset = -4, sideOffset = 8, ...props },
+  ref,
+) {
+  return (
+    <MenubarPrimitive.Portal>
+      <MenubarPrimitive.Content
+        ref={ref}
+        align={align}
+        alignOffset={alignOffset}
+        sideOffset={sideOffset}
+        className={cn(
+          "z-50 min-w-[12rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-ring-md",
+          "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95",
+          "data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
+          className,
+        )}
+        {...props}
+      />
+    </MenubarPrimitive.Portal>
+  );
+});
+
+export const MenubarItem = forwardRef<
+  ElementRef<typeof MenubarPrimitive.Item>,
+  ComponentPropsWithoutRef<typeof MenubarPrimitive.Item> & { inset?: boolean }
+>(function MenubarItem({ className, inset, ...props }, ref) {
+  return (
+    <MenubarPrimitive.Item
+      ref={ref}
+      className={cn(
+        "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none transition-colors duration-fast focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+        inset && "ps-8",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export const MenubarSubTrigger = forwardRef<
+  ElementRef<typeof MenubarPrimitive.SubTrigger>,
+  ComponentPropsWithoutRef<typeof MenubarPrimitive.SubTrigger> & { inset?: boolean }
+>(function MenubarSubTrigger({ className, inset, children, ...props }, ref) {
+  return (
+    <MenubarPrimitive.SubTrigger
+      ref={ref}
+      className={cn(
+        "flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none transition-colors duration-fast focus:bg-accent data-[state=open]:bg-accent",
+        inset && "ps-8",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <ChevronRight className="ms-auto size-4" />
+    </MenubarPrimitive.SubTrigger>
+  );
+});
+
+export const MenubarSubContent = forwardRef<
+  ElementRef<typeof MenubarPrimitive.SubContent>,
+  ComponentPropsWithoutRef<typeof MenubarPrimitive.SubContent>
+>(function MenubarSubContent({ className, ...props }, ref) {
+  return (
+    <MenubarPrimitive.SubContent
+      ref={ref}
+      className={cn(
+        "z-50 min-w-[8rem] overflow-hidden rounded-md bg-popover p-1 text-popover-foreground shadow-ring-md",
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95",
+        "data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export const MenubarCheckboxItem = forwardRef<
+  ElementRef<typeof MenubarPrimitive.CheckboxItem>,
+  ComponentPropsWithoutRef<typeof MenubarPrimitive.CheckboxItem>
+>(function MenubarCheckboxItem({ className, children, checked, ...props }, ref) {
+  return (
+    <MenubarPrimitive.CheckboxItem
+      ref={ref}
+      checked={checked}
+      className={cn(
+        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-sm outline-none transition-colors duration-fast focus:bg-accent",
+        className,
+      )}
+      {...props}
+    >
+      <span className="absolute start-2 flex size-3.5 items-center justify-center">
+        <MenubarPrimitive.ItemIndicator>
+          <Check className="size-4" />
+        </MenubarPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </MenubarPrimitive.CheckboxItem>
+  );
+});
+
+export const MenubarRadioItem = forwardRef<
+  ElementRef<typeof MenubarPrimitive.RadioItem>,
+  ComponentPropsWithoutRef<typeof MenubarPrimitive.RadioItem>
+>(function MenubarRadioItem({ className, children, ...props }, ref) {
+  return (
+    <MenubarPrimitive.RadioItem
+      ref={ref}
+      className={cn(
+        "relative flex cursor-default select-none items-center rounded-sm py-1.5 ps-8 pe-2 text-sm outline-none transition-colors duration-fast focus:bg-accent",
+        className,
+      )}
+      {...props}
+    >
+      <span className="absolute start-2 flex size-3.5 items-center justify-center">
+        <MenubarPrimitive.ItemIndicator>
+          <Circle className="size-2 fill-current" />
+        </MenubarPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </MenubarPrimitive.RadioItem>
+  );
+});
+
+export const MenubarSeparator = forwardRef<
+  ElementRef<typeof MenubarPrimitive.Separator>,
+  ComponentPropsWithoutRef<typeof MenubarPrimitive.Separator>
+>(function MenubarSeparator({ className, ...props }, ref) {
+  return (
+    <MenubarPrimitive.Separator
+      ref={ref}
+      className={cn("-mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  );
+});
+
+export function MenubarShortcut({ className, ...props }: HTMLAttributes<HTMLSpanElement>) {
+  return (
+    <span
+      className={cn("ms-auto text-xs tracking-widest text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}

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

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

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

@@ -0,0 +1,224 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { MetricCard } from "./metric-card";
+
+const meta = {
+  title: "Core/MetricCard",
+  component: MetricCard,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The canonical KPI tile, owned by @elabs-ai/components-ui (ADR 0012). @elabs-ai/components-charts re-exports this exact " +
+          "component as Charts/MetricCard — they are the same component, so import from @elabs-ai/components-ui for app " +
+          "UI, or from @elabs-ai/components-charts when already in a charts context. Don't fork a second KPI tile.",
+      },
+    },
+  },
+  argTypes: {
+    label: {
+      description: "Tile label — the metric name shown above the value.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    value: {
+      description: "Primary metric value (string or ReactNode).",
+      control: "text",
+      table: { category: "Content" },
+    },
+    description: {
+      description: "Secondary context line under the value.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    delta: {
+      description: 'Signed change string, e.g. "+12.4%". Direction colors it.',
+      control: "text",
+      table: { category: "Content" },
+    },
+    deltaDirection: {
+      description: "Direction of the delta — drives the arrow glyph and polarity color.",
+      control: { type: "radio" },
+      options: ["up", "down", "neutral"],
+      table: { category: "State" },
+    },
+    positiveIsGood: {
+      description: "Flip to false for metrics where increase is unfavorable (e.g. churn).",
+      control: "boolean",
+      table: { category: "Behavior" },
+    },
+    emphasis: {
+      description:
+        "`headline` uses the larger kpi text rung; `default` is the calm intermediate rung.",
+      control: { type: "radio" },
+      options: ["default", "headline"],
+      table: { category: "Appearance" },
+    },
+    icon: {
+      description: "Optional icon node shown to the right of the label.",
+      control: false,
+      table: { category: "Content" },
+    },
+    visual: {
+      description: "Optional inline visual (e.g. sparkline) shown under value/description.",
+      control: false,
+      table: { category: "Content" },
+    },
+    evidence: {
+      description:
+        "Optional grounding footer — connects a figure to its source (e.g. EvidenceChip).",
+      control: false,
+      table: { category: "Content" },
+    },
+    loading: {
+      description: "Loading vs ready — renders a layout-shaped skeleton at the same box height.",
+      control: "boolean",
+      table: { category: "State" },
+    },
+    announceLoading: {
+      description:
+        "Whether this tile announces its own loading state (set false when composed inside a container, e.g. MetricGrid, that already announces once).",
+      control: "boolean",
+      table: { category: "State" },
+    },
+  },
+} satisfies Meta<typeof MetricCard>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    label: "Active users",
+    value: "24,512",
+    delta: "12.4%",
+    deltaDirection: "up",
+  },
+};
+
+export const WithDescription: Story = {
+  args: {
+    label: "Monthly Revenue",
+    value: "$84.2k",
+    description: "vs $80.9k last month",
+    delta: "4.1%",
+    deltaDirection: "up",
+  },
+};
+
+export const DeltaDown: Story = {
+  args: {
+    label: "Churn Rate",
+    value: "1.8%",
+    description: "0.3 pp worse than target",
+    delta: "0.3%",
+    deltaDirection: "down",
+    positiveIsGood: false,
+  },
+};
+
+export const DeltaUnfavorable: Story = {
+  args: {
+    label: "Open tickets",
+    value: "37",
+    description: "15 unassigned",
+    delta: "+9",
+    deltaDirection: "up",
+    positiveIsGood: false,
+  },
+};
+
+export const Neutral: Story = {
+  args: {
+    label: "Sessions",
+    value: "100",
+    delta: "0%",
+    deltaDirection: "neutral",
+  },
+};
+
+export const NoMetrics: Story = {
+  args: {
+    label: "Open gaps",
+    value: "2",
+    description: "in progress",
+  },
+};
+
+// emphasis="headline" — the answer-leading KPI rung (#191, research 11 §B.5):
+// size/weight/space only, the polarity color system is unchanged.
+export const Headline: Story = {
+  args: {
+    emphasis: "headline",
+    label: "Net revenue retention",
+    value: "118%",
+    delta: "+4.2pp",
+    deltaDirection: "up",
+  },
+};
+
+export const WithEvidence: Story = {
+  args: {
+    label: "Enterprise churn",
+    value: "1.8%",
+    delta: "0.4pp",
+    deltaDirection: "down",
+    positiveIsGood: false,
+    evidence: <span>Grounded in 3 sources</span>,
+  },
+};
+
+/**
+ * A NUMERIC `value` is compacted for reading and stays reachable in full: the
+ * tile renders its value as a real button that copies the exact figure. The
+ * accessible name carries the tile's own label, so two tiles that compact to the
+ * same string are still told apart by a screen reader.
+ */
+export const NumericValue: Story = {
+  args: {
+    label: "Revenue",
+    value: 50012102.632741,
+    delta: "8.1%",
+    deltaDirection: "up",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // Compacted for reading…
+    await expect(canvas.getByText("50M")).toBeInTheDocument();
+    // …and the exact figure is one keyboard-reachable control away.
+    await expect(
+      canvas.getByRole("button", { name: /50M\s+Revenue, Copy exact value/i }),
+    ).toBeInTheDocument();
+  },
+};
+
+/** `valueFormat="number"` is the escape hatch — full grouped digits, no copy control. */
+export const NumericUncompacted: Story = {
+  args: {
+    label: "Open tickets",
+    value: 1284,
+    valueFormat: "number",
+  },
+};
+
+/** Currency and percent read the same numeric seam. */
+export const NumericCurrency: Story = {
+  args: {
+    label: "Pipeline",
+    value: 4820000,
+    valueFormat: "currency",
+    currency: "EUR",
+  },
+};
+
+/** Loading vs ready (#268) — a layout-shaped skeleton at the same box height as `Default`. */
+export const Loading: Story = {
+  args: {
+    label: "Active users",
+    value: "24,512",
+    delta: "12.4%",
+    deltaDirection: "up",
+    loading: true,
+  },
+};

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

@@ -0,0 +1,198 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MetricCard } from "./metric-card";
+
+describe("MetricCard", () => {
+  it("renders label and value", () => {
+    render(<MetricCard label="Revenue" value="$42,000" />);
+    expect(screen.getByText("Revenue")).toBeInTheDocument();
+    expect(screen.getByText("$42,000")).toBeInTheDocument();
+  });
+
+  it("renders description when passed", () => {
+    render(<MetricCard label="Revenue" value="$42,000" description="vs $40k last month" />);
+    expect(screen.getByText("vs $40k last month")).toBeInTheDocument();
+  });
+
+  it("does not render description when omitted", () => {
+    render(<MetricCard label="Revenue" value="$42,000" />);
+    expect(screen.queryByRole("paragraph")).not.toBeInTheDocument();
+  });
+
+  it("renders delta text when provided", () => {
+    render(<MetricCard label="Users" value="1,234" delta="+12.4%" deltaDirection="up" />);
+    expect(screen.getByText(/12\.4%/)).toBeInTheDocument();
+  });
+
+  it("renders an optional visual slot", () => {
+    render(<MetricCard label="Sales" value="99" visual={<div data-testid="sparkline" />} />);
+    expect(screen.getByTestId("sparkline")).toBeInTheDocument();
+  });
+
+  it("renders an optional icon slot", () => {
+    render(
+      <MetricCard label="Orders" value="7" icon={<svg data-testid="icon" aria-hidden="true" />} />,
+    );
+    expect(screen.getByTestId("icon")).toBeInTheDocument();
+  });
+
+  // Polarity (good/bad) must survive monochrome themes via a non-color channel:
+  // a stable data-polarity hook + AT aria-label.
+  it("marks a favorable delta with data-polarity=good and a favorable AT label", () => {
+    render(
+      <MetricCard label="Revenue" value="$1M" delta="+12.4%" deltaDirection="up" positiveIsGood />,
+    );
+    const el = screen.getByLabelText("up +12.4%, favorable");
+    expect(el).toHaveAttribute("data-polarity", "good");
+  });
+
+  it("marks an unfavorable delta with data-polarity=bad and an unfavorable AT label", () => {
+    render(
+      <MetricCard
+        label="Open tickets"
+        value="42"
+        delta="+5"
+        deltaDirection="up"
+        positiveIsGood={false}
+      />,
+    );
+    const el = screen.getByLabelText("up +5, unfavorable");
+    expect(el).toHaveAttribute("data-polarity", "bad");
+  });
+
+  it("marks a neutral delta with data-polarity=neutral", () => {
+    render(<MetricCard label="Sessions" value="100" delta="0%" deltaDirection="neutral" />);
+    const el = screen.getByText(/0%/).closest("[data-polarity]");
+    expect(el).toHaveAttribute("data-polarity", "neutral");
+  });
+
+  // emphasis axis (#191, research 11 §B.5 KPI-1): size/weight/space only — the
+  // headline rung is text-kpi; default stays on the calm intermediate rung.
+  it("renders the calm default value rung by default", () => {
+    render(<MetricCard label="Revenue" value="$1M" />);
+    const value = screen.getByText("$1M");
+    expect(value.className).toContain("text-2xl");
+    expect(value.className).not.toContain("text-kpi");
+  });
+
+  it("renders the headline kpi rung for emphasis=headline", () => {
+    render(<MetricCard emphasis="headline" label="Revenue" value="$1M" />);
+    const value = screen.getByText("$1M");
+    expect(value.className).toContain("text-kpi");
+    expect(value.className).not.toContain("text-2xl");
+  });
+
+  it("renders an optional evidence footer slot (#191, KPI-3)", () => {
+    render(
+      <MetricCard
+        label="Revenue"
+        value="$1M"
+        evidence={<span data-testid="evidence">3 sources</span>}
+      />,
+    );
+    expect(screen.getByTestId("evidence")).toBeInTheDocument();
+  });
+
+  // Loading vs ready (#268): a layout-shaped skeleton replaces the value/label/delta
+  // text, and the region announces once via a single role="status" live region.
+  describe("loading", () => {
+    it("renders a skeleton instead of the label/value/delta text", () => {
+      render(
+        <MetricCard label="Revenue" value="$42,000" delta="+12.4%" deltaDirection="up" loading />,
+      );
+      expect(screen.queryByText("Revenue")).not.toBeInTheDocument();
+      expect(screen.queryByText("$42,000")).not.toBeInTheDocument();
+      expect(screen.queryByText(/12\.4%/)).not.toBeInTheDocument();
+    });
+
+    it("renders exactly one status live region for the not-ready state", () => {
+      render(
+        <MetricCard label="Revenue" value="$42,000" delta="+12.4%" deltaDirection="up" loading />,
+      );
+      expect(screen.getAllByRole("status")).toHaveLength(1);
+    });
+
+    it("renders the real content (no status region) when not loading", () => {
+      render(<MetricCard label="Revenue" value="$42,000" />);
+      expect(screen.getByText("Revenue")).toBeInTheDocument();
+      expect(screen.queryByRole("status")).not.toBeInTheDocument();
+    });
+
+    it("suppresses its own live region when announceLoading is false (composed in a grid)", () => {
+      render(<MetricCard announceLoading={false} label="Revenue" loading value="$42,000" />);
+      expect(screen.queryByRole("status")).not.toBeInTheDocument();
+    });
+  });
+
+  // A KPI tile is a small box; `50012102.632741` does not fit in one. Numbers
+  // are compacted by default and the exact figure stays one click away. Every
+  // OTHER ReactNode passes through untouched — that is what makes the new
+  // default safe for the call sites that already format their own strings.
+  describe("value formatting", () => {
+    it("compacts a numeric value by default", () => {
+      render(<MetricCard label="Revenue" value={50012102.632741} />);
+      expect(screen.getByRole("button")).toHaveTextContent("50M");
+    });
+
+    it("leaves a pre-formatted string byte-identical", () => {
+      render(<MetricCard label="Revenue" value="$42,000" />);
+      expect(screen.getByText("$42,000")).toBeInTheDocument();
+      // No control, because there is nothing shortened to restore.
+      expect(screen.queryByRole("button")).not.toBeInTheDocument();
+    });
+
+    it("passes an element through untouched", () => {
+      render(<MetricCard label="Revenue" value={<span data-testid="custom">≈ 50M</span>} />);
+      expect(screen.getByTestId("custom")).toBeInTheDocument();
+      expect(screen.queryByRole("button")).not.toBeInTheDocument();
+    });
+
+    it("prints every digit for valueFormat=number", () => {
+      render(<MetricCard label="Revenue" value={1500000} valueFormat="number" />);
+      expect(screen.getByText("1,500,000")).toBeInTheDocument();
+    });
+
+    it("renders currency with the requested code", () => {
+      render(<MetricCard currency="EUR" label="Revenue" value={1234} valueFormat="currency" />);
+      expect(screen.getByRole("button")).toHaveTextContent("€");
+    });
+
+    it("hands a function full control and offers no copy affordance", () => {
+      render(
+        <MetricCard label="Revenue" value={1234} valueFormat={(n) => <span>~{n} units</span>} />,
+      );
+      expect(screen.getByText(/~1234 units/)).toBeInTheDocument();
+      expect(screen.queryByRole("button")).not.toBeInTheDocument();
+    });
+
+    it("offers the exact value on click when the display was shortened", () => {
+      render(<MetricCard label="Revenue" value={50012102.632741} />);
+      expect(screen.getByRole("button", { name: /50M.*Copy exact value/i })).toBeInTheDocument();
+    });
+
+    it("offers no copy affordance when the display already IS the exact value", () => {
+      // 42 renders as "42" — a button around an unshortened number is noise.
+      render(<MetricCard label="Orders" value={42} />);
+      expect(screen.queryByRole("button")).not.toBeInTheDocument();
+    });
+
+    // Two tiles in a grid can compact to the same display; the label is a
+    // sibling node, so without it in the hint both buttons announce alike.
+    it("names the copy button after the metric it belongs to", () => {
+      render(
+        <>
+          <MetricCard label="Revenue" value={1234567} />
+          <MetricCard label="Pipeline" value={1234567} />
+        </>,
+      );
+      expect(screen.getByRole("button", { name: /1\.2M.*Revenue/i })).toBeInTheDocument();
+      expect(screen.getByRole("button", { name: /1\.2M.*Pipeline/i })).toBeInTheDocument();
+    });
+
+    it("can be opted out of with copyExactValue={false}", () => {
+      render(<MetricCard copyExactValue={false} label="Revenue" value={50012102.632741} />);
+      expect(screen.queryByRole("button")).not.toBeInTheDocument();
+      expect(screen.getByText("50M")).toBeInTheDocument();
+    });
+  });
+});