@hilum/ui 0.1.1

package/src/components/__tests__/display.test.tsx

@@ -0,0 +1,262 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+  CardMedia,
+} from "../card";
+import { Avatar, AvatarFallback, AvatarImage, AvatarWithStatus } from "../avatar";
+import { AvatarStack } from "../avatar-stack";
+import { StatCard } from "../stat-card";
+import { Notification } from "../notification";
+import { MediaObject } from "../media-object";
+
+/* ------------------------------------------------------------------ */
+/* Card                                                                 */
+/* ------------------------------------------------------------------ */
+
+describe("Card", () => {
+  it("renders children", () => {
+    render(<Card>Content</Card>);
+    expect(screen.getByText("Content")).toBeInTheDocument();
+  });
+
+  it("carries data-slot attribute", () => {
+    const { container } = render(<Card>Content</Card>);
+    expect(container.firstChild).toHaveAttribute("data-slot", "card");
+  });
+
+  it("renders all variants without error", () => {
+    const variants = ["default", "muted", "ghost"] as const;
+    for (const variant of variants) {
+      const { unmount } = render(<Card variant={variant}>Card</Card>);
+      expect(screen.getByText("Card")).toBeInTheDocument();
+      unmount();
+    }
+  });
+
+  it("composes sub-components correctly", () => {
+    render(
+      <Card>
+        <CardHeader>
+          <CardTitle>Title</CardTitle>
+          <CardDescription>Description</CardDescription>
+        </CardHeader>
+        <CardContent>Body</CardContent>
+        <CardFooter>Footer</CardFooter>
+      </Card>,
+    );
+    expect(screen.getByText("Title")).toBeInTheDocument();
+    expect(screen.getByText("Description")).toBeInTheDocument();
+    expect(screen.getByText("Body")).toBeInTheDocument();
+    expect(screen.getByText("Footer")).toBeInTheDocument();
+  });
+
+  it("renders CardMedia", () => {
+    const { container } = render(<CardMedia data-testid="media" />);
+    expect(container.querySelector('[data-slot="card-media"]')).toBeInTheDocument();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Avatar                                                               */
+/* ------------------------------------------------------------------ */
+
+describe("Avatar", () => {
+  it("renders with fallback text", () => {
+    render(
+      <Avatar>
+        <AvatarFallback>JD</AvatarFallback>
+      </Avatar>,
+    );
+    expect(screen.getByText("JD")).toBeInTheDocument();
+  });
+
+  it("renders all sizes without error", () => {
+    const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
+    for (const size of sizes) {
+      const { unmount } = render(
+        <Avatar size={size}>
+          <AvatarFallback>X</AvatarFallback>
+        </Avatar>,
+      );
+      expect(screen.getByText("X")).toBeInTheDocument();
+      unmount();
+    }
+  });
+
+  it("renders AvatarImage with alt text", () => {
+    render(
+      <Avatar>
+        <AvatarImage src="https://example.com/avatar.jpg" alt="User avatar" />
+        <AvatarFallback>JD</AvatarFallback>
+      </Avatar>,
+    );
+    // AvatarFallback shows when image fails — just check it's in the DOM
+    expect(screen.getByText("JD")).toBeInTheDocument();
+  });
+});
+
+describe("AvatarWithStatus", () => {
+  it("renders children", () => {
+    render(
+      <AvatarWithStatus>
+        <AvatarFallback>AB</AvatarFallback>
+      </AvatarWithStatus>,
+    );
+    expect(screen.getByText("AB")).toBeInTheDocument();
+  });
+
+  it("renders status indicator when status is provided", () => {
+    const statuses = ["online", "offline", "busy", "away"] as const;
+    for (const status of statuses) {
+      const { unmount } = render(
+        <AvatarWithStatus status={status}>
+          <AvatarFallback>X</AvatarFallback>
+        </AvatarWithStatus>,
+      );
+      expect(screen.getByText("X")).toBeInTheDocument();
+      unmount();
+    }
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* AvatarStack                                                          */
+/* ------------------------------------------------------------------ */
+
+describe("AvatarStack", () => {
+  const avatars = [{ name: "Alice" }, { name: "Bob" }, { name: "Carol" }];
+
+  it("renders all avatars by default", () => {
+    render(<AvatarStack avatars={avatars} />);
+    expect(screen.getByTitle("Alice")).toBeInTheDocument();
+    expect(screen.getByTitle("Bob")).toBeInTheDocument();
+    expect(screen.getByTitle("Carol")).toBeInTheDocument();
+  });
+
+  it("shows overflow count when max is set", () => {
+    render(<AvatarStack avatars={avatars} max={2} />);
+    expect(screen.getByText("+1")).toBeInTheDocument();
+  });
+
+  it("renders all sizes without error", () => {
+    const sizes = ["sm", "md", "lg"] as const;
+    for (const size of sizes) {
+      const { unmount } = render(<AvatarStack avatars={[{ name: "A" }]} size={size} />);
+      expect(screen.getByTitle("A")).toBeInTheDocument();
+      unmount();
+    }
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* StatCard                                                             */
+/* ------------------------------------------------------------------ */
+
+describe("StatCard", () => {
+  it("renders label and value", () => {
+    render(<StatCard label="Total Users" value="1,234" />);
+    expect(screen.getByText("Total Users")).toBeInTheDocument();
+    expect(screen.getByText("1,234")).toBeInTheDocument();
+  });
+
+  it("renders trend when provided", () => {
+    render(<StatCard label="Revenue" value="$10k" trend={{ value: "+12%", direction: "up" }} />);
+    expect(screen.getByText("+12%")).toBeInTheDocument();
+  });
+
+  it("renders all trend directions without error", () => {
+    const directions = ["up", "down", "neutral"] as const;
+    for (const direction of directions) {
+      const { unmount } = render(
+        <StatCard label="L" value="V" trend={{ value: "5%", direction }} />,
+      );
+      expect(screen.getByText("5%")).toBeInTheDocument();
+      unmount();
+    }
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Notification                                                         */
+/* ------------------------------------------------------------------ */
+
+describe("Notification", () => {
+  it("renders title", () => {
+    render(<Notification title="File uploaded" />);
+    expect(screen.getByText("File uploaded")).toBeInTheDocument();
+  });
+
+  it("renders description when provided", () => {
+    render(<Notification title="Done" description="Your export is ready." />);
+    expect(screen.getByText("Your export is ready.")).toBeInTheDocument();
+  });
+
+  it("renders close button when onClose is provided", () => {
+    render(<Notification title="Alert" onClose={() => {}} />);
+    expect(screen.getByRole("button", { name: /close/i })).toBeInTheDocument();
+  });
+
+  it("renders actions when provided", () => {
+    render(
+      <Notification
+        title="Update available"
+        actions={[{ label: "Install" }, { label: "Dismiss", variant: "ghost" }]}
+      />,
+    );
+    expect(screen.getByText("Install")).toBeInTheDocument();
+    expect(screen.getByText("Dismiss")).toBeInTheDocument();
+  });
+
+  it("renders all variants without error", () => {
+    const variants = ["default", "success", "error", "warning", "info"] as const;
+    for (const variant of variants) {
+      const { unmount } = render(<Notification title="T" variant={variant} />);
+      expect(screen.getByText("T")).toBeInTheDocument();
+      unmount();
+    }
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* MediaObject                                                          */
+/* ------------------------------------------------------------------ */
+
+describe("MediaObject", () => {
+  it("renders media and content", () => {
+    render(
+      <MediaObject media={<img alt="thumb" src="" />}>
+        <p>Content text</p>
+      </MediaObject>,
+    );
+    expect(screen.getByAltText("thumb")).toBeInTheDocument();
+    expect(screen.getByText("Content text")).toBeInTheDocument();
+  });
+
+  it('renders mediaPosition="right" without error', () => {
+    render(
+      <MediaObject media={<span>icon</span>} mediaPosition="right">
+        Content
+      </MediaObject>,
+    );
+    expect(screen.getByText("Content")).toBeInTheDocument();
+  });
+
+  it("renders all gap options without error", () => {
+    const gaps = ["sm", "md", "lg"] as const;
+    for (const gap of gaps) {
+      const { unmount } = render(
+        <MediaObject media={<span />} gap={gap}>
+          Body
+        </MediaObject>,
+      );
+      expect(screen.getByText("Body")).toBeInTheDocument();
+      unmount();
+    }
+  });
+});

package/src/components/__tests__/feedback.test.tsx

@@ -0,0 +1,138 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Alert, AlertTitle, AlertDescription } from "../alert";
+import { Progress } from "../progress";
+import { Steps } from "../steps";
+import { EmptyState } from "../empty-state";
+import type { Step } from "../steps";
+
+/* ------------------------------------------------------------------ */
+/* Alert                                                                */
+/* ------------------------------------------------------------------ */
+
+describe("Alert", () => {
+  it('renders with role="alert"', () => {
+    render(<Alert>Message</Alert>);
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+  });
+
+  it("renders sub-components together", () => {
+    render(
+      <Alert>
+        <AlertTitle>Warning</AlertTitle>
+        <AlertDescription>Something went wrong.</AlertDescription>
+      </Alert>,
+    );
+    expect(screen.getByText("Warning")).toBeInTheDocument();
+    expect(screen.getByText("Something went wrong.")).toBeInTheDocument();
+  });
+
+  it("renders all variants without error", () => {
+    const variants = ["default", "info", "success", "warning", "destructive"] as const;
+    for (const variant of variants) {
+      const { unmount } = render(<Alert variant={variant}>Alert</Alert>);
+      expect(screen.getByRole("alert")).toBeInTheDocument();
+      unmount();
+    }
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Progress                                                             */
+/* ------------------------------------------------------------------ */
+
+describe("Progress", () => {
+  it("renders with a progressbar role", () => {
+    render(<Progress value={50} />);
+    expect(screen.getByRole("progressbar")).toBeInTheDocument();
+  });
+
+  it("reflects the correct value", () => {
+    render(<Progress value={75} />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute("aria-valuenow", "75");
+  });
+
+  it("renders at 0%", () => {
+    render(<Progress value={0} />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute("aria-valuenow", "0");
+  });
+
+  it("renders at 100%", () => {
+    render(<Progress value={100} />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute("aria-valuenow", "100");
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Steps                                                                */
+/* ------------------------------------------------------------------ */
+
+const STEPS: Step[] = [
+  { name: "Cart", status: "complete" },
+  { name: "Shipping", status: "current" },
+  { name: "Payment", status: "upcoming" },
+];
+
+describe("Steps", () => {
+  it("renders all step names in circles variant (default)", () => {
+    render(<Steps steps={STEPS} />);
+    expect(screen.getByText("Cart")).toBeInTheDocument();
+    expect(screen.getByText("Shipping")).toBeInTheDocument();
+    expect(screen.getByText("Payment")).toBeInTheDocument();
+  });
+
+  it("renders bullets variant without error", () => {
+    render(<Steps steps={STEPS} variant="bullets" />);
+    expect(screen.getByRole("navigation", { name: /progress/i })).toBeInTheDocument();
+  });
+
+  it("renders progress variant without error", () => {
+    render(<Steps steps={STEPS} variant="progress" />);
+    expect(screen.getByText("Cart")).toBeInTheDocument();
+  });
+
+  it("bullets variant shows step count", () => {
+    render(<Steps steps={STEPS} variant="bullets" />);
+    expect(screen.getByText(/Step 2 of 3/i)).toBeInTheDocument();
+  });
+
+  it("renders with descriptions in circles variant", () => {
+    const stepsWithDesc: Step[] = [
+      { name: "Step 1", description: "First step", status: "complete" },
+      { name: "Step 2", status: "current" },
+    ];
+    render(<Steps steps={stepsWithDesc} />);
+    expect(screen.getByText("First step")).toBeInTheDocument();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* EmptyState                                                           */
+/* ------------------------------------------------------------------ */
+
+describe("EmptyState", () => {
+  it("renders the title", () => {
+    render(<EmptyState title="No results found" />);
+    expect(screen.getByText("No results found")).toBeInTheDocument();
+  });
+
+  it("renders description when provided", () => {
+    render(<EmptyState title="Empty" description="Try a different search." />);
+    expect(screen.getByText("Try a different search.")).toBeInTheDocument();
+  });
+
+  it("renders action button with label", () => {
+    render(<EmptyState title="Empty" action={{ label: "Add item" }} />);
+    expect(screen.getByRole("button", { name: "Add item" })).toBeInTheDocument();
+  });
+
+  it("renders action as anchor when href is provided", () => {
+    render(<EmptyState title="Empty" action={{ label: "Create", href: "/new" }} />);
+    expect(screen.getByRole("link", { name: "Create" })).toHaveAttribute("href", "/new");
+  });
+
+  it("renders icon when provided", () => {
+    render(<EmptyState title="Empty" icon={<span data-testid="icon">📭</span>} />);
+    expect(screen.getByTestId("icon")).toBeInTheDocument();
+  });
+});

package/src/components/__tests__/form.test.tsx

@@ -0,0 +1,297 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+import { Checkbox } from "../checkbox";
+import { RadioGroup, RadioGroupItem } from "../radio-group";
+import { Switch } from "../switch";
+import { Slider } from "../slider";
+import { InputNumber } from "../input-number";
+import { InputGroup } from "../input-group";
+import { Field } from "../field";
+import { NativeSelect, NativeSelectOption } from "../native-select";
+import { RadioCards } from "../radio-card";
+
+/* ------------------------------------------------------------------ */
+/* Checkbox                                                             */
+/* ------------------------------------------------------------------ */
+
+describe("Checkbox", () => {
+  it("renders a checkbox button", () => {
+    render(<Checkbox />);
+    expect(screen.getByRole("checkbox")).toBeInTheDocument();
+  });
+
+  it("is unchecked by default", () => {
+    render(<Checkbox />);
+    expect(screen.getByRole("checkbox")).not.toBeChecked();
+  });
+
+  it("is disabled when disabled prop is set", () => {
+    render(<Checkbox disabled />);
+    expect(screen.getByRole("checkbox")).toBeDisabled();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* RadioGroup                                                           */
+/* ------------------------------------------------------------------ */
+
+describe("RadioGroup", () => {
+  it("renders radio buttons", () => {
+    render(
+      <RadioGroup defaultValue="a">
+        <RadioGroupItem value="a" id="a" />
+        <RadioGroupItem value="b" id="b" />
+      </RadioGroup>,
+    );
+    expect(screen.getAllByRole("radio")).toHaveLength(2);
+  });
+
+  it("marks default value as checked", () => {
+    render(
+      <RadioGroup defaultValue="first">
+        <RadioGroupItem value="first" id="first" />
+        <RadioGroupItem value="second" id="second" />
+      </RadioGroup>,
+    );
+    const radios = screen.getAllByRole("radio");
+    expect(radios[0]).toBeChecked();
+    expect(radios[1]).not.toBeChecked();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Switch                                                               */
+/* ------------------------------------------------------------------ */
+
+describe("Switch", () => {
+  it("renders a switch button", () => {
+    render(<Switch />);
+    expect(screen.getByRole("switch")).toBeInTheDocument();
+  });
+
+  it("is off by default", () => {
+    render(<Switch />);
+    expect(screen.getByRole("switch")).toHaveAttribute("data-state", "unchecked");
+  });
+
+  it("toggles on click", async () => {
+    const user = userEvent.setup();
+    render(<Switch />);
+    const sw = screen.getByRole("switch");
+    await user.click(sw);
+    expect(sw).toHaveAttribute("data-state", "checked");
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Slider                                                               */
+/* ------------------------------------------------------------------ */
+
+describe("Slider", () => {
+  it("renders a slider", () => {
+    render(<Slider defaultValue={[50]} />);
+    expect(screen.getByRole("slider")).toBeInTheDocument();
+  });
+
+  it("shows the provided value", () => {
+    render(<Slider defaultValue={[25]} min={0} max={100} />);
+    expect(screen.getByRole("slider")).toHaveAttribute("aria-valuenow", "25");
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* InputNumber                                                          */
+/* ------------------------------------------------------------------ */
+
+describe("InputNumber", () => {
+  it("renders an input with the given value", () => {
+    render(<InputNumber value={42} onChange={() => {}} />);
+    expect(screen.getByRole("textbox")).toHaveValue("42");
+  });
+
+  it("displays unit suffix", () => {
+    render(<InputNumber value={100} onChange={() => {}} unit="px" />);
+    expect(screen.getByText("px")).toBeInTheDocument();
+  });
+
+  it("calls onChange with incremented value when increment button clicked", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<InputNumber value={10} onChange={onChange} step={1} />);
+    await user.click(screen.getByRole("button", { name: /increment/i }));
+    expect(onChange).toHaveBeenCalledWith(11);
+  });
+
+  it("calls onChange with decremented value when decrement button clicked", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<InputNumber value={10} onChange={onChange} step={1} />);
+    await user.click(screen.getByRole("button", { name: /decrement/i }));
+    expect(onChange).toHaveBeenCalledWith(9);
+  });
+
+  it("clamps to max on increment", async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    render(<InputNumber value={10} onChange={onChange} max={10} />);
+    await user.click(screen.getByRole("button", { name: /increment/i }));
+    expect(onChange).toHaveBeenCalledWith(10);
+  });
+
+  it("hides steppers when hideSteppers is true", () => {
+    render(<InputNumber value={5} onChange={() => {}} hideSteppers />);
+    expect(screen.queryByRole("button", { name: /increment/i })).not.toBeInTheDocument();
+  });
+
+  it("renders with precision", () => {
+    render(<InputNumber value={3.14} onChange={() => {}} precision={2} />);
+    expect(screen.getByRole("textbox")).toHaveValue("3.14");
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* InputGroup                                                           */
+/* ------------------------------------------------------------------ */
+
+describe("InputGroup", () => {
+  it("renders a plain input when no addons", () => {
+    render(<InputGroup placeholder="Enter text" />);
+    expect(screen.getByRole("textbox")).toBeInTheDocument();
+  });
+
+  it("renders leading addon text", () => {
+    render(<InputGroup leadingAddon="https://" placeholder="domain.com" />);
+    expect(screen.getByText("https://")).toBeInTheDocument();
+  });
+
+  it("renders trailing addon text", () => {
+    render(<InputGroup trailingAddon=".com" placeholder="domain" />);
+    expect(screen.getByText(".com")).toBeInTheDocument();
+  });
+
+  it("renders error state", () => {
+    const { container } = render(<InputGroup error />);
+    // Error icon is rendered inside
+    expect(container.querySelector("input")).toBeInTheDocument();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* Field                                                                */
+/* ------------------------------------------------------------------ */
+
+describe("Field", () => {
+  it("renders label and children", () => {
+    render(
+      <Field label="Email" htmlFor="email">
+        <input id="email" type="email" />
+      </Field>,
+    );
+    expect(screen.getByLabelText("Email")).toBeInTheDocument();
+  });
+
+  it("renders hint text", () => {
+    render(
+      <Field label="Username" hint="Must be unique">
+        <input />
+      </Field>,
+    );
+    expect(screen.getByText("Must be unique")).toBeInTheDocument();
+  });
+
+  it("renders error over hint when both provided", () => {
+    render(
+      <Field label="Field" hint="Hint" error="This is required">
+        <input />
+      </Field>,
+    );
+    expect(screen.getByText("This is required")).toBeInTheDocument();
+    expect(screen.queryByText("Hint")).not.toBeInTheDocument();
+  });
+
+  it("renders required asterisk", () => {
+    const { container } = render(
+      <Field label="Name" required>
+        <input />
+      </Field>,
+    );
+    expect(container.querySelector("span")).toHaveTextContent("*");
+  });
+
+  it("renders cornerHint", () => {
+    render(
+      <Field label="Password" cornerHint="Optional">
+        <input />
+      </Field>,
+    );
+    expect(screen.getByText("Optional")).toBeInTheDocument();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* NativeSelect                                                         */
+/* ------------------------------------------------------------------ */
+
+describe("NativeSelect", () => {
+  it("renders a combobox", () => {
+    render(
+      <NativeSelect>
+        <NativeSelectOption value="a">Option A</NativeSelectOption>
+        <NativeSelectOption value="b">Option B</NativeSelectOption>
+      </NativeSelect>,
+    );
+    expect(screen.getByRole("combobox")).toBeInTheDocument();
+    expect(screen.getByText("Option A")).toBeInTheDocument();
+    expect(screen.getByText("Option B")).toBeInTheDocument();
+  });
+
+  it("is disabled when disabled prop is set", () => {
+    render(
+      <NativeSelect disabled>
+        <NativeSelectOption value="x">X</NativeSelectOption>
+      </NativeSelect>,
+    );
+    expect(screen.getByRole("combobox")).toBeDisabled();
+  });
+});
+
+/* ------------------------------------------------------------------ */
+/* RadioCards                                                           */
+/* ------------------------------------------------------------------ */
+
+describe("RadioCards", () => {
+  const options = [
+    { value: "plan-a", label: "Basic" },
+    { value: "plan-b", label: "Pro" },
+    { value: "plan-c", label: "Enterprise" },
+  ];
+
+  it("renders all option labels", () => {
+    render(<RadioCards options={options} />);
+    expect(screen.getByText("Basic")).toBeInTheDocument();
+    expect(screen.getByText("Pro")).toBeInTheDocument();
+    expect(screen.getByText("Enterprise")).toBeInTheDocument();
+  });
+
+  it("marks the selected option as checked", () => {
+    render(<RadioCards options={options} value="plan-b" />);
+    const proBtn = screen.getByRole("radio", { name: "Pro" });
+    expect(proBtn).toHaveAttribute("aria-checked", "true");
+  });
+
+  it("calls onValueChange when an option is clicked", () => {
+    const onValueChange = vi.fn();
+    render(<RadioCards options={options} onValueChange={onValueChange} />);
+    fireEvent.click(screen.getByRole("radio", { name: "Enterprise" }));
+    expect(onValueChange).toHaveBeenCalledWith("plan-c");
+  });
+
+  it("does not call onValueChange for disabled options", () => {
+    const onValueChange = vi.fn();
+    const opts = [{ value: "x", label: "Disabled", disabled: true }];
+    render(<RadioCards options={opts} onValueChange={onValueChange} />);
+    fireEvent.click(screen.getByRole("radio", { name: "Disabled" }));
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+});