@elabs-ai/components-ui 4.0.0

package/src/components/copyable-value/copyable-value.tsx

@@ -0,0 +1,101 @@
+"use client";
+
+/**
+ * CopyableValue — shown short, copied exact.
+ *
+ * Numbers across the library are formatted COMPACT by default (`1.5M`, `$820`),
+ * because the surfaces they appear on — a KPI tile, an axis tick, a chart in a
+ * chat bubble — have no room for `50012102.632741`. That is only defensible if
+ * the exact value stays reachable, so this renders the compact string as a real
+ * `<button>` that puts the unrounded one on the clipboard.
+ *
+ * Why a button and not a tooltip: a chart tooltip is `pointer-events-none` (it
+ * must not swallow the `mousemove` that drives the crosshair), so it can carry
+ * text but never an interaction. A button is reachable by mouse, by keyboard,
+ * and by touch — all three, with no bespoke affordance.
+ */
+
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { useCopyToClipboard } from "../../lib/use-copy-to-clipboard";
+import { useLocale } from "../locale-provider";
+
+export interface CopyableValueProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "value" | "children"
+> {
+  /**
+   * The EXACT text written to the clipboard — the unrounded, un-abbreviated
+   * value. Not locale-formatted by this component: a copied number is usually
+   * on its way into a spreadsheet or a query.
+   */
+  value: string;
+  /** What the reader sees. Defaults to `value`. */
+  children?: ReactNode;
+  /**
+   * Overrides the screen-reader hint appended to the visible text. The
+   * accessible name is always `<visible text> + <hint>`, which keeps WCAG 2.5.3
+   * (Label in Name) satisfied — voice-control users can say what they read.
+   */
+  hint?: string;
+  /** ms the "Copied" confirmation stays. Default: 1500. */
+  resetAfterMs?: number;
+}
+
+/**
+ * A value that copies its exact form on click.
+ *
+ * ```tsx
+ * <CopyableValue value="50012102.632741">50M</CopyableValue>
+ * ```
+ */
+export const CopyableValue = forwardRef<HTMLButtonElement, CopyableValueProps>(
+  function CopyableValue(
+    { value, children, hint, resetAfterMs, className, onClick, ...props },
+    ref,
+  ) {
+    const { t } = useLocale();
+    const { copied, copy } = useCopyToClipboard(
+      resetAfterMs === undefined ? undefined : { resetAfterMs },
+    );
+
+    return (
+      <>
+        <button
+          data-slot="copyable-value"
+          data-copied={copied ? "" : undefined}
+          ref={ref}
+          type="button"
+          {...props}
+          className={cn(
+            // Reads as text, behaves as a control: the dotted underline is the
+            // only resting affordance, so a value inside a heading or a KPI
+            // still looks like a value, not a link.
+            "inline-flex items-baseline gap-1 rounded-sm underline decoration-dotted decoration-muted-foreground underline-offset-4",
+            "hover:decoration-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            "transition-colors duration-fast ease-standard motion-reduce:transition-none",
+            className,
+          )}
+          onClick={(event) => {
+            onClick?.(event);
+            if (!event.defaultPrevented) {
+              void copy(value);
+            }
+          }}
+        >
+          {children ?? value}
+          <span className="sr-only">{hint ?? t("ui.copyableValue.hint")}</span>
+        </button>
+        {/*
+          One live region per control, always mounted: an `aria-live` region
+          inserted at the same moment its text appears is frequently missed by
+          screen readers (ARIA22), so the region exists from first paint and
+          only its contents change.
+        */}
+        <span aria-live="polite" className="sr-only" role="status">
+          {copied ? t("ui.copyableValue.copied") : ""}
+        </span>
+      </>
+    );
+  },
+);

package/src/components/copyable-value/index.ts

@@ -0,0 +1 @@
+export { CopyableValue, type CopyableValueProps } from "./copyable-value";

package/src/components/date-picker/date-picker.stories.tsx

@@ -0,0 +1,42 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { DatePicker } from "./date-picker";
+const meta = {
+  title: "Forms/DatePicker",
+  component: DatePicker,
+  tags: ["autodocs"],
+  argTypes: {
+    value: {
+      description: "Controlled selected date.",
+      control: false,
+      table: { category: "State" },
+    },
+    placeholder: {
+      description: "Text shown in the trigger when no date is selected.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    onValueChange: {
+      description: "Called when the selected date changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the trigger button.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof DatePicker>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+export const Default: Story = {
+  // Opens the calendar popover and confirms the grid is visible.
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const trigger = canvas.getByRole("button");
+    await userEvent.click(trigger);
+    const body = within(canvasElement.ownerDocument.body);
+    const grid = await body.findByRole("grid");
+    await expect(grid).toBeInTheDocument();
+  },
+};

package/src/components/date-picker/date-picker.tsx

@@ -0,0 +1,49 @@
+import { useState } from "react";
+import { Calendar as CalendarIcon } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { Button } from "../button";
+import { Calendar } from "../calendar";
+import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+
+export interface DatePickerProps {
+  value?: Date;
+  onValueChange?: (date?: Date) => void;
+  placeholder?: string;
+  className?: string;
+}
+
+/** Single-date picker (Popover + Calendar). Controlled or uncontrolled. */
+export function DatePicker({
+  value,
+  onValueChange,
+  placeholder = "Pick a date",
+  className,
+}: DatePickerProps) {
+  const [internal, setInternal] = useState<Date | undefined>(undefined);
+  const date = value ?? internal;
+  const setDate = (d?: Date) => (onValueChange ? onValueChange(d) : setInternal(d));
+  const label = date
+    ? new Intl.DateTimeFormat(undefined, { dateStyle: "medium" }).format(date)
+    : placeholder;
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          className={cn(
+            "w-56 justify-start gap-2 text-start font-normal",
+            !date && "text-muted-foreground",
+            className,
+          )}
+        >
+          <CalendarIcon className="size-4" />
+          {label}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0" align="start">
+        <Calendar mode="single" selected={date} onSelect={setDate} autoFocus />
+      </PopoverContent>
+    </Popover>
+  );
+}

package/src/components/date-picker/index.ts

@@ -0,0 +1 @@
+export { DatePicker, type DatePickerProps } from "./date-picker";

package/src/components/date-range-picker/date-range-picker.stories.tsx

@@ -0,0 +1,151 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import type { DateRange } from "react-day-picker";
+import { DateRangePicker } from "./date-range-picker";
+import type { DateRangePreset } from "./date-range-picker";
+
+const meta = {
+  title: "Forms/DateRangePicker",
+  component: DateRangePicker,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    value: {
+      description: "Controlled date range `{ from, to }`.",
+      control: false,
+      table: { category: "State" },
+    },
+    defaultValue: {
+      description: "Uncontrolled initial date range.",
+      control: false,
+      table: { category: "State" },
+    },
+    presets: {
+      description: "Array of quick-pick preset definitions `{ label, getRange }`.",
+      control: false,
+      table: { category: "Content" },
+    },
+    numberOfMonths: {
+      description: "Number of calendar months to display.",
+      control: "number",
+      table: { category: "Appearance" },
+    },
+    placeholder: {
+      description: "Trigger text when no range is selected.",
+      control: "text",
+      table: { category: "Content" },
+    },
+    onValueChange: {
+      description: "Called when the selected range changes.",
+      control: false,
+      table: { category: "Behavior" },
+    },
+    className: {
+      description: "Additional CSS classes applied to the trigger button.",
+      control: "text",
+      table: { category: "Appearance" },
+    },
+  },
+} satisfies Meta<typeof DateRangePicker>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Default two-month picker with no presets. */
+export const Default: Story = {
+  // Opens the popover and confirms the range calendar grid is visible.
+  play: async ({ canvas, canvasElement, userEvent }) => {
+    const trigger = canvas.getByRole("button");
+    await userEvent.click(trigger);
+    const body = within(canvasElement.ownerDocument.body);
+    // Two-month picker → one grid per month; findByRole (singular) throws.
+    const grids = await body.findAllByRole("grid");
+    await expect(grids[0]).toBeInTheDocument();
+  },
+};
+
+const commonPresets: DateRangePreset[] = [
+  {
+    label: "Today",
+    getRange: () => {
+      const today = new Date();
+      return { from: today, to: today };
+    },
+  },
+  {
+    label: "Last 7 days",
+    getRange: () => {
+      const to = new Date();
+      const from = new Date();
+      from.setDate(from.getDate() - 6);
+      return { from, to };
+    },
+  },
+  {
+    label: "Last 30 days",
+    getRange: () => {
+      const to = new Date();
+      const from = new Date();
+      from.setDate(from.getDate() - 29);
+      return { from, to };
+    },
+  },
+  {
+    label: "This month",
+    getRange: () => {
+      const now = new Date();
+      const from = new Date(now.getFullYear(), now.getMonth(), 1);
+      const to = new Date(now.getFullYear(), now.getMonth() + 1, 0);
+      return { from, to };
+    },
+  },
+];
+
+/** Two-month picker with common quick-pick presets. */
+export const WithPresets: Story = {
+  args: {
+    presets: commonPresets,
+  },
+};
+
+/** Single-month layout. */
+export const SingleMonth: Story = {
+  args: {
+    numberOfMonths: 1,
+  },
+};
+
+/** Pre-selected range via defaultValue. */
+export const Preselected: Story = {
+  args: {
+    defaultValue: {
+      from: new Date(2025, 0, 6),
+      to: new Date(2025, 0, 20),
+    },
+  },
+};
+
+/** Controlled example using useState (defined as a real component to satisfy rules-of-hooks). */
+function ControlledExample() {
+  const [range, setRange] = useState<DateRange | undefined>({
+    from: new Date(2025, 2, 1),
+    to: new Date(2025, 2, 14),
+  });
+  return (
+    <div className="flex flex-col gap-4">
+      <DateRangePicker value={range} onValueChange={setRange} />
+      <p className="text-body text-muted-foreground">
+        {range?.from && range?.to
+          ? `Selected: ${range.from.toLocaleDateString()} – ${range.to.toLocaleDateString()}`
+          : "No range selected"}
+      </p>
+    </div>
+  );
+}
+
+export const Controlled: Story = {
+  render: () => <ControlledExample />,
+};

package/src/components/date-range-picker/date-range-picker.test.tsx

@@ -0,0 +1,62 @@
+/**
+ * Smoke tests for DateRangePicker trigger rendering.
+ *
+ * NOTE: Opening the Radix Popover and interacting with the Calendar is NOT
+ * tested here — Radix Portals do not render in jsdom reliably. Calendar open/
+ * select interaction and accessibility are covered by the Storybook stories
+ * (run via `pnpm --filter @elabs-ai/components-docs test-storybook` or the MCP story tests).
+ */
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { DateRangePicker } from "./date-range-picker";
+
+describe("DateRangePicker", () => {
+  it("renders the placeholder on the trigger when no range is set", () => {
+    render(<DateRangePicker placeholder="Pick a date range" />);
+    expect(screen.getByRole("button", { name: /pick a date range/i })).toBeInTheDocument();
+  });
+
+  it("renders a formatted 'from – to' label for a controlled value", () => {
+    const from = new Date(2025, 0, 6); // Jan 6 2025
+    const to = new Date(2025, 0, 20); // Jan 20 2025
+    render(<DateRangePicker value={{ from, to }} />);
+
+    const button = screen.getByRole("button");
+    // The label should contain an EN DASH between the two dates
+    expect(button.textContent).toMatch(/–/);
+    // Both formatted dates should appear somewhere in the label
+    const formatted = new Intl.DateTimeFormat(undefined, { dateStyle: "medium" });
+    expect(button.textContent).toContain(formatted.format(from));
+    expect(button.textContent).toContain(formatted.format(to));
+  });
+
+  it("renders a partial label with '…' when only 'from' is set", () => {
+    const from = new Date(2025, 3, 1); // Apr 1 2025
+    render(<DateRangePicker value={{ from, to: undefined }} />);
+
+    const button = screen.getByRole("button");
+    expect(button.textContent).toMatch(/–\s*…/);
+    const formatted = new Intl.DateTimeFormat(undefined, { dateStyle: "medium" });
+    expect(button.textContent).toContain(formatted.format(from));
+  });
+
+  it("applies the placeholder text-muted-foreground class when no range", () => {
+    render(<DateRangePicker />);
+    const button = screen.getByRole("button");
+    expect(button.className).toContain("text-muted-foreground");
+  });
+
+  it("does not apply text-muted-foreground when a range is set", () => {
+    const from = new Date(2025, 0, 1);
+    const to = new Date(2025, 0, 15);
+    render(<DateRangePicker value={{ from, to }} />);
+    const button = screen.getByRole("button");
+    expect(button.className).not.toContain("text-muted-foreground");
+  });
+
+  it("merges a custom className onto the trigger button", () => {
+    render(<DateRangePicker className="my-custom-class" />);
+    const button = screen.getByRole("button");
+    expect(button.className).toContain("my-custom-class");
+  });
+});

package/src/components/date-range-picker/date-range-picker.tsx

@@ -0,0 +1,126 @@
+// a2ui.exposed: yes
+"use client";
+
+import { forwardRef, useState } from "react";
+import { Calendar as CalendarIcon } from "lucide-react";
+import type { DateRange } from "react-day-picker";
+import { cn } from "../../lib/cn";
+import { Button } from "../button";
+import { Calendar } from "../calendar";
+import { Popover, PopoverContent, PopoverTrigger } from "../popover";
+
+export type { DateRange };
+
+export interface DateRangePreset {
+  label: string;
+  getRange: () => DateRange;
+}
+
+export interface DateRangePickerProps {
+  value?: DateRange;
+  defaultValue?: DateRange;
+  onValueChange?: (range?: DateRange) => void;
+  presets?: DateRangePreset[];
+  numberOfMonths?: number;
+  placeholder?: string;
+  className?: string;
+}
+
+const fmt = (date: Date) =>
+  new Intl.DateTimeFormat(undefined, { dateStyle: "medium" }).format(date);
+
+function formatRange(range: DateRange | undefined, placeholder: string): string {
+  if (!range) return placeholder;
+  if (range.from && range.to) return `${fmt(range.from)} – ${fmt(range.to)}`;
+  if (range.from) return `${fmt(range.from)} – …`;
+  return placeholder;
+}
+
+/**
+ * Date range picker (Popover + Calendar in range mode).
+ * Supports optional preset quick-picks, controlled or uncontrolled.
+ */
+export const DateRangePicker = forwardRef<HTMLButtonElement, DateRangePickerProps>(
+  function DateRangePicker(
+    {
+      value,
+      defaultValue,
+      onValueChange,
+      presets,
+      numberOfMonths = 2,
+      placeholder = "Pick a date range",
+      className,
+    },
+    ref,
+  ) {
+    const [internal, setInternal] = useState<DateRange | undefined>(defaultValue);
+
+    const isControlled = value !== undefined;
+    const range = isControlled ? value : internal;
+
+    const setRange = (r?: DateRange) => {
+      if (!isControlled) {
+        setInternal(r);
+      }
+      // Always fire the callback so uncontrolled consumers can observe changes
+      onValueChange?.(r);
+    };
+
+    const hasRange = Boolean(range?.from);
+    const label = formatRange(range, placeholder);
+
+    return (
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button
+            ref={ref}
+            variant="outline"
+            aria-haspopup="dialog"
+            className={cn(
+              "w-72 justify-start gap-2 text-start font-normal",
+              !hasRange && "text-muted-foreground",
+              className,
+            )}
+          >
+            <CalendarIcon className="size-4" aria-hidden="true" />
+            {label}
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-auto p-0" align="start">
+          {presets && presets.length > 0 ? (
+            <div className="flex">
+              <div className="flex flex-col gap-1 border-r border-border p-2">
+                {presets.map((preset) => (
+                  <Button
+                    key={preset.label}
+                    variant="ghost"
+                    size="sm"
+                    className="justify-start"
+                    onClick={() => setRange(preset.getRange())}
+                  >
+                    {preset.label}
+                  </Button>
+                ))}
+              </div>
+              <Calendar
+                mode="range"
+                numberOfMonths={numberOfMonths}
+                selected={range}
+                onSelect={setRange}
+                autoFocus
+              />
+            </div>
+          ) : (
+            <Calendar
+              mode="range"
+              numberOfMonths={numberOfMonths}
+              selected={range}
+              onSelect={setRange}
+              autoFocus
+            />
+          )}
+        </PopoverContent>
+      </Popover>
+    );
+  },
+);

package/src/components/date-range-picker/index.ts

@@ -0,0 +1,6 @@
+export {
+  DateRangePicker,
+  type DateRangePickerProps,
+  type DateRangePreset,
+} from "./date-range-picker";
+export type { DateRange } from "react-day-picker";

package/src/components/descriptions/descriptions.stories.tsx

@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Descriptions, DescriptionsItem } from "./descriptions";
+
+const meta = {
+  title: "Layout/Descriptions",
+  component: Descriptions,
+  tags: ["autodocs"],
+  argTypes: {
+    columns: { control: "inline-radio", options: [1, 2, 3] },
+    layout: { control: "inline-radio", options: ["horizontal", "vertical"] },
+  },
+} satisfies Meta<typeof Descriptions>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const items = (
+  <>
+    <DescriptionsItem label="Name">Ada Lovelace</DescriptionsItem>
+    <DescriptionsItem label="Email">ada@example.com</DescriptionsItem>
+    <DescriptionsItem label="Role">Maintainer</DescriptionsItem>
+    <DescriptionsItem label="Records" numeric>
+      1,284
+    </DescriptionsItem>
+    <DescriptionsItem label="Status">Active</DescriptionsItem>
+    <DescriptionsItem label="Last seen">2 hours ago</DescriptionsItem>
+  </>
+);
+
+export const Default: Story = {
+  args: { columns: 1, layout: "horizontal" },
+  render: (args) => <Descriptions {...args}>{items}</Descriptions>,
+};
+
+export const TwoColumns: Story = {
+  args: { columns: 2, layout: "horizontal" },
+  render: (args) => <Descriptions {...args}>{items}</Descriptions>,
+};
+
+export const VerticalThreeColumns: Story = {
+  args: { columns: 3, layout: "vertical" },
+  render: (args) => <Descriptions {...args}>{items}</Descriptions>,
+};

package/src/components/descriptions/descriptions.test.tsx

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Descriptions, DescriptionsItem } from "./descriptions";
+
+describe("Descriptions", () => {
+  it("renders a definition list with dt/dd pairs", () => {
+    render(
+      <Descriptions>
+        <DescriptionsItem label="Name">Ada</DescriptionsItem>
+        <DescriptionsItem label="Role">Maintainer</DescriptionsItem>
+      </Descriptions>,
+    );
+    const term = screen.getByText("Name");
+    expect(term.tagName).toBe("DT");
+    expect(screen.getAllByRole("term")).toHaveLength(2);
+    expect(screen.getByText("Ada").tagName).toBe("DD");
+    expect(screen.getByText("Maintainer")).toBeInTheDocument();
+  });
+
+  it("applies tabular-nums to numeric values", () => {
+    render(
+      <Descriptions>
+        <DescriptionsItem label="Records" numeric>
+          1284
+        </DescriptionsItem>
+      </Descriptions>,
+    );
+    expect(screen.getByText("1284")).toHaveClass("tabular-nums");
+  });
+
+  it("renders a real <dl> element", () => {
+    const { container } = render(
+      <Descriptions>
+        <DescriptionsItem label="Name">Ada</DescriptionsItem>
+      </Descriptions>,
+    );
+    expect(container.querySelector("dl")).not.toBeNull();
+    expect(container.querySelectorAll("dt")).toHaveLength(1);
+    expect(container.querySelectorAll("dd")).toHaveLength(1);
+  });
+});