@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/components/select/select.stories.tsx

@@ -0,0 +1,352 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useArgs } from "storybook/preview-api";
+import { Button } from "../button";
+import { Field } from "../field";
+import { Form as LibraryForm } from "../form";
+import {
+  Select,
+  SelectGroup,
+  SelectGroupLabel,
+  SelectItem,
+  SelectPopup,
+  SelectRoot,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "./select";
+
+interface Animal {
+  label: string;
+  value: string;
+}
+
+const animals: Animal[] = [
+  { label: "Cat", value: "cat" },
+  { label: "Dog", value: "dog" },
+  { label: "Bird", value: "bird" },
+  { label: "Rabbit", value: "rabbit" },
+  { label: "Fish", value: "fish" },
+  { label: "Reptile", value: "reptile" },
+  { label: "Snake", value: "snake" },
+  { label: "Turtle", value: "turtle" },
+];
+
+/**
+ * Single-selection dropdown built on Base UI. Items shaped as `{ id, name }`,
+ * `{ label, value }`, or plain strings/numbers work with no extra props. Provide
+ * `getLabel` / `getId` for custom object shapes, or `renderItem` to control the
+ * content inside each option — the checkmark indicator is always appended on the right.
+ *
+ * Exposes `onValueChange` that receives the full item object (or `null`).
+ * For controlled usage, pass `value` + `onValueChange` together.
+ * Use `SelectRoot` + primitives for full structural control.
+ */
+const meta: Meta<typeof Select> = {
+  title: "Components/Select",
+  component: Select,
+  parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <div className="w-64">
+        <Story />
+      </div>
+    ),
+  ],
+  argTypes: {
+    onValueChange: { control: false },
+    getLabel: { control: false },
+    getId: { control: false },
+    getDisabled: { control: false },
+    renderItem: { control: false },
+    classNames: { control: false },
+  },
+  args: {
+    items: animals,
+    placeholder: "Select an animal",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Select>;
+
+export const Default: Story = {};
+
+/**
+ * `className` styles the trigger. `classNames` exposes the `popup` and
+ * `item` slots.
+ */
+export const WithClassNames: Story = {
+  args: {
+    classNames: {
+      popup: "min-w-56",
+      item: "font-mono",
+    },
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+/**
+ * `alignItemWithTrigger` controla cómo posiciona Base UI el popup respecto al trigger.
+ *
+ * - **Default (`false`)**: el popup aparece debajo del trigger como un combo común.
+ *   Es el comportamiento esperado cuando hay muchos items o cuando el popup no debería
+ *   crecer hasta llenar el viewport intentando alinear el item seleccionado con el trigger.
+ * - **`true`**: Base UI intenta alinear el item seleccionado con el trigger y expande
+ *   el popup hacia arriba y abajo. Útil para listas cortas con un valor preseleccionado,
+ *   estilo `<select>` nativo de macOS.
+ *
+ * Es un cambio estructural — usá `SelectRoot` + `SelectPopup` directamente
+ * para activarlo:
+ *
+ * ```tsx
+ * <SelectRoot>
+ *   <SelectTrigger><SelectValue /></SelectTrigger>
+ *   <SelectPopup alignItemWithTrigger>…</SelectPopup>
+ * </SelectRoot>
+ * ```
+ */
+export const AlignItemWithTrigger: Story = {
+  render: () => {
+    const years = Array.from({ length: 40 }, (_, i) => {
+      const year = 1990 + i;
+      return { label: String(year), value: String(year) };
+    });
+    const preselected = years[20];
+
+    return (
+      <div className="flex flex-col gap-6">
+        <div className="flex flex-col gap-1">
+          <span className="text-muted-foreground text-xs">
+            Default (alignItemWithTrigger=false)
+          </span>
+          <Select items={years} defaultValue={preselected} />
+        </div>
+        <div className="flex flex-col gap-1">
+          <span className="text-muted-foreground text-xs">
+            alignItemWithTrigger=true
+          </span>
+          <SelectRoot defaultValue={preselected.value}>
+            <SelectTrigger>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectPopup alignItemWithTrigger>
+              {years.map((y) => (
+                <SelectItem key={y.value} value={y.value}>
+                  {y.label}
+                </SelectItem>
+              ))}
+            </SelectPopup>
+          </SelectRoot>
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * `getDisabled` receives a predicate `(item) => boolean` to disable individual
+ * options. Items with a `disabled: true` property are disabled automatically
+ * without passing this prop.
+ *
+ * A disabled item is skipped during keyboard navigation and cannot be selected,
+ * but it remains visible in the list at reduced opacity.
+ */
+export const DisabledItem: Story = {
+  render: () => {
+    const items = [
+      { label: "Cat", value: "cat" },
+      { label: "Dog", value: "dog" },
+      { label: "Bird", value: "bird" },
+      { label: "Rabbit", value: "rabbit" },
+      { label: "Fish", value: "fish" },
+    ];
+
+    return (
+      <Select
+        items={items}
+        getDisabled={(item) => item.value === "bird" || item.value === "fish"}
+        placeholder="Select an animal"
+      />
+    );
+  },
+};
+
+/**
+ * `getLabel` and `getId` accept functions so they work with any object shape.
+ * For common shapes (`{ id, name }`, `{ label, value }`, primitives) the
+ * defaults resolve everything without passing either function.
+ */
+export const CustomObject: Story = {
+  render: () => {
+    const items = [
+      { key: "cat", name: "Cat", emoji: "🐱" },
+      { key: "dog", name: "Dog", emoji: "🐶" },
+      { key: "bird", name: "Bird", emoji: "🐦" },
+    ];
+
+    return (
+      <Select
+        items={items}
+        getLabel={(a) => a.name}
+        getId={(a) => a.key}
+        placeholder="Select an animal"
+      />
+    );
+  },
+};
+
+/**
+ * `multiple` enables multi-selection. The trigger shows selected labels as a
+ * comma-separated list with automatic truncation. Use `value: TItem[]` and
+ * `onValueChange: (value: TItem[]) => void` for controlled usage — the discriminated
+ * union ensures type safety between single and multiple modes.
+ */
+export const Multiple: Story = {
+  render: () => (
+    <Select items={animals} multiple placeholder="Select animals" />
+  ),
+};
+
+/**
+ * `renderItem` customizes the content inside each option. The checkmark
+ * indicator is always rendered by the item wrapper on the right.
+ */
+export const CustomRender: Story = {
+  render: () => {
+    const items = [
+      { key: "cat", name: "Cat", emoji: "🐱" },
+      { key: "dog", name: "Dog", emoji: "🐶" },
+      { key: "bird", name: "Bird", emoji: "🐦" },
+    ];
+
+    return (
+      <Select
+        items={items}
+        getLabel={(a) => a.name}
+        getId={(a) => a.key}
+        renderItem={(a) => (
+          <span className="flex items-center gap-2">
+            <span>{a.emoji}</span>
+            <span>{a.name}</span>
+          </span>
+        )}
+        placeholder="Select an animal"
+      />
+    );
+  },
+};
+
+/**
+ * `onValueChange` receives the full item object (or `null`).
+ * `value` accepts the item object directly — no string conversion needed.
+ */
+export const Controlled: Story = {
+  render: (args) => {
+    const [{ value }, updateArgs] = useArgs();
+    return (
+      <div className="flex flex-col gap-4">
+        <Select
+          {...args}
+          value={value ?? null}
+          onValueChange={(item) => updateArgs({ value: item })}
+        />
+        <p className="text-sm text-muted-foreground">
+          Selected: {value ? (value as Animal).label : "none"}
+        </p>
+      </div>
+    );
+  },
+};
+
+export const Form: Story = {
+  name: "Form",
+  render: () => (
+    <LibraryForm className="space-y-1" onSubmit={console.log}>
+      <Field name="animal" label="Animal">
+        <Select<Animal>
+          items={animals}
+          placeholder="Select an animal"
+          required
+        />
+      </Field>
+      <Button type="submit">Submit</Button>
+    </LibraryForm>
+  ),
+};
+
+/**
+ * Use `SelectRoot` + primitives for full structural control: custom grouping,
+ * separators, and arbitrary content inside items.
+ *
+ * `SelectGroupLabel` must always be placed inside a `SelectGroup`.
+ *
+ * ```tsx
+ * <SelectRoot>
+ *   <SelectTrigger>
+ *     <SelectValue placeholder="…" />
+ *   </SelectTrigger>
+ *   <SelectPopup>
+ *     <SelectGroup>
+ *       <SelectGroupLabel>Group A</SelectGroupLabel>
+ *       <SelectItem value="a1">Item A1</SelectItem>
+ *     </SelectGroup>
+ *     <SelectSeparator />
+ *     <SelectGroup>
+ *       <SelectGroupLabel>Group B</SelectGroupLabel>
+ *       <SelectItem value="b1">Item B1</SelectItem>
+ *     </SelectGroup>
+ *   </SelectPopup>
+ * </SelectRoot>
+ * ```
+ */
+export const Grouped: Story = {
+  render: () => (
+    <SelectRoot>
+      <SelectTrigger>
+        <SelectValue placeholder="Select a pet" />
+      </SelectTrigger>
+      <SelectPopup>
+        <SelectGroup>
+          <SelectGroupLabel>Mammals</SelectGroupLabel>
+          <SelectItem value="cat">Cat</SelectItem>
+          <SelectItem value="dog">Dog</SelectItem>
+          <SelectItem value="rabbit">Rabbit</SelectItem>
+        </SelectGroup>
+        <SelectSeparator />
+        <SelectGroup>
+          <SelectGroupLabel>Other</SelectGroupLabel>
+          <SelectItem value="bird">Bird</SelectItem>
+          <SelectItem value="fish">Fish</SelectItem>
+          <SelectItem value="reptile" disabled>
+            Reptile
+          </SelectItem>
+        </SelectGroup>
+      </SelectPopup>
+    </SelectRoot>
+  ),
+};
+
+export const Primitive: Story = {
+  render: () => (
+    <SelectRoot>
+      <SelectTrigger>
+        <SelectValue placeholder="Select a theme" />
+      </SelectTrigger>
+      <SelectPopup>
+        <SelectItem value="light">Light</SelectItem>
+        <SelectItem value="dark">Dark</SelectItem>
+        <SelectSeparator />
+        <SelectGroup>
+          <SelectGroupLabel>Advanced</SelectGroupLabel>
+          <SelectItem value="system">System</SelectItem>
+          <SelectItem value="custom" disabled>
+            Custom
+          </SelectItem>
+        </SelectGroup>
+      </SelectPopup>
+    </SelectRoot>
+  ),
+};

package/src/components/select/select.test.tsx

@@ -0,0 +1,357 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import {
+  Select,
+  SelectButton,
+  SelectGroup,
+  SelectGroupLabel,
+  SelectItem,
+  SelectLabel,
+  SelectPopup,
+  SelectRoot,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+} from "./select";
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+const fruits = [
+  { id: "1", name: "Apple" },
+  { id: "2", name: "Banana" },
+  { id: "3", name: "Cherry" },
+];
+
+function slot(name: string) {
+  return document.querySelector(`[data-slot="${name}"]`);
+}
+
+// ─── Primitives: data-slot ────────────────────────────────────────────────────
+
+describe("Select primitives — data-slots", () => {
+  it("SelectTrigger renders data-slot=select-trigger", () => {
+    render(
+      <SelectRoot>
+        <SelectTrigger />
+      </SelectRoot>,
+    );
+    expect(slot("select-trigger")).toBeInTheDocument();
+  });
+
+  it("SelectValue renders data-slot=select-value", () => {
+    render(
+      <SelectRoot>
+        <SelectTrigger>
+          <SelectValue placeholder="Pick" />
+        </SelectTrigger>
+      </SelectRoot>,
+    );
+    expect(slot("select-value")).toBeInTheDocument();
+  });
+
+  it("SelectButton renders data-slot=select-button with type=button by default", () => {
+    render(
+      <SelectRoot>
+        <SelectButton>Open</SelectButton>
+      </SelectRoot>,
+    );
+    const btn = slot("select-button") as HTMLButtonElement;
+    expect(btn).toBeInTheDocument();
+    expect(btn.type).toBe("button");
+  });
+
+  it("SelectButton omits type when render prop is provided", () => {
+    render(
+      <SelectRoot>
+        <SelectButton render={<div data-testid="custom-render" />} />
+      </SelectRoot>,
+    );
+    expect(screen.getByTestId("custom-render")).toBeInTheDocument();
+  });
+
+  it("SelectLabel renders data-slot=select-label", () => {
+    render(
+      <SelectRoot>
+        <SelectLabel>Label</SelectLabel>
+        <SelectTrigger />
+      </SelectRoot>,
+    );
+    expect(slot("select-label")).toHaveTextContent("Label");
+  });
+
+  it("SelectSeparator renders data-slot=select-separator", () => {
+    render(
+      <SelectRoot defaultOpen>
+        <SelectTrigger />
+        <SelectPopup>
+          <SelectItem value="a">A</SelectItem>
+          <SelectSeparator className="sep-cls" />
+          <SelectItem value="b">B</SelectItem>
+        </SelectPopup>
+      </SelectRoot>,
+    );
+    const sep = slot("select-separator");
+    expect(sep).toBeInTheDocument();
+    expect(sep).toHaveClass("sep-cls");
+  });
+
+  it("SelectGroup renders data-slot=select-group", () => {
+    render(
+      <SelectRoot defaultOpen>
+        <SelectTrigger />
+        <SelectPopup>
+          <SelectGroup className="grp">
+            <SelectGroupLabel>Fruits</SelectGroupLabel>
+            <SelectItem value="a">A</SelectItem>
+          </SelectGroup>
+        </SelectPopup>
+      </SelectRoot>,
+    );
+    expect(slot("select-group")).toHaveClass("grp");
+    expect(slot("select-group-label")).toHaveTextContent("Fruits");
+  });
+
+  it("SelectItem renders data-slot=select-item", () => {
+    render(
+      <SelectRoot defaultOpen>
+        <SelectTrigger />
+        <SelectPopup>
+          <SelectItem value="apple">Apple</SelectItem>
+        </SelectPopup>
+      </SelectRoot>,
+    );
+    expect(slot("select-item")).toBeInTheDocument();
+  });
+
+  it("SelectTrigger merges className", () => {
+    render(
+      <SelectRoot>
+        <SelectTrigger className="custom-trigger" />
+      </SelectRoot>,
+    );
+    expect(slot("select-trigger")).toHaveClass("custom-trigger");
+  });
+});
+
+// ─── Composite Select — rendering ─────────────────────────────────────────────
+
+describe("Select composite — rendering", () => {
+  it("renders trigger with data-slot=select-trigger", () => {
+    render(<Select items={fruits} />);
+    expect(slot("select-trigger")).toBeInTheDocument();
+  });
+
+  it("shows placeholder in the trigger", () => {
+    render(<Select items={fruits} placeholder="Pick a fruit" />);
+    expect(slot("select-trigger")).toHaveTextContent("Pick a fruit");
+  });
+
+  it("shows items in popup when defaultOpen", () => {
+    render(<Select items={fruits} defaultOpen />);
+    const options = screen.getAllByRole("option");
+    expect(options.map((o) => o.textContent)).toContain("Apple");
+    expect(options).toHaveLength(fruits.length);
+  });
+
+  it("uses renderItem to customize item content", () => {
+    render(
+      <Select
+        items={fruits}
+        defaultOpen
+        renderItem={(item) => (
+          <span data-testid="custom-item">{item.name}!</span>
+        )}
+      />,
+    );
+    const custom = screen.getAllByTestId("custom-item");
+    expect(custom[0]).toHaveTextContent("Apple!");
+  });
+
+  it("applies classNames.popup and classNames.item", () => {
+    render(
+      <Select
+        items={fruits}
+        defaultOpen
+        classNames={{ popup: "popup-cls", item: "item-cls" }}
+      />,
+    );
+    expect(slot("select-list")).toHaveClass("popup-cls");
+    expect(slot("select-item")).toHaveClass("item-cls");
+  });
+
+  it("applies className to the trigger", () => {
+    render(<Select items={fruits} className="trigger-cls" />);
+    expect(slot("select-trigger")).toHaveClass("trigger-cls");
+  });
+});
+
+// ─── Composite Select — item shape defaults ───────────────────────────────────
+
+describe("Select defaultGetLabel / defaultGetId", () => {
+  it("handles { id, name } items", () => {
+    render(<Select items={fruits} defaultOpen />);
+    expect(screen.getByRole("option", { name: "Apple" })).toBeInTheDocument();
+  });
+
+  it("handles { label, value } items", () => {
+    const opts = [
+      { label: "One", value: "1" },
+      { label: "Two", value: "2" },
+    ];
+    render(<Select items={opts} defaultOpen />);
+    expect(screen.getByRole("option", { name: "One" })).toBeInTheDocument();
+  });
+
+  it("handles { title } items", () => {
+    const opts = [{ title: "Alpha" }, { title: "Beta" }];
+    render(<Select items={opts} defaultOpen />);
+    expect(screen.getByRole("option", { name: "Alpha" })).toBeInTheDocument();
+  });
+
+  it("handles plain string items", () => {
+    render(<Select items={["x", "y", "z"]} defaultOpen />);
+    expect(screen.getByRole("option", { name: "x" })).toBeInTheDocument();
+  });
+
+  it("handles plain number items", () => {
+    render(<Select items={[1, 2, 3]} defaultOpen />);
+    expect(screen.getByRole("option", { name: "1" })).toBeInTheDocument();
+  });
+
+  it("falls back to String(item) for objects without known keys", () => {
+    const weird = [{ foo: "bar" }];
+    render(<Select items={weird} defaultOpen />);
+    const options = screen.getAllByRole("option");
+    expect(options).toHaveLength(1);
+  });
+
+  it("respects custom getLabel and getId", () => {
+    const opts = [
+      { code: "AR", country: "Argentina" },
+      { code: "BR", country: "Brazil" },
+    ];
+    render(
+      <Select
+        items={opts}
+        defaultOpen
+        getLabel={(o) => o.country}
+        getId={(o) => o.code}
+      />,
+    );
+    expect(
+      screen.getByRole("option", { name: "Argentina" }),
+    ).toBeInTheDocument();
+  });
+});
+
+// ─── Composite Select — disabled ──────────────────────────────────────────────
+
+describe("Select disabled items", () => {
+  it("disables items via default getDisabled (item.disabled=true)", () => {
+    const items = [
+      { id: "1", name: "Active" },
+      { id: "2", name: "Disabled", disabled: true },
+    ];
+    render(<Select items={items} defaultOpen />);
+    const disabledItem = document.querySelector(
+      '[data-slot="select-item"][data-disabled]',
+    );
+    expect(disabledItem).toBeInTheDocument();
+  });
+
+  it("uses custom getDisabled", () => {
+    const items = [
+      { id: "1", name: "Active", blocked: false },
+      { id: "2", name: "Blocked", blocked: true },
+    ];
+    render(
+      <Select items={items} defaultOpen getDisabled={(item) => item.blocked} />,
+    );
+    expect(
+      document.querySelector('[data-slot="select-item"][data-disabled]'),
+    ).toBeInTheDocument();
+  });
+});
+
+// ─── Composite Select — value / onChange ─────────────────────────────────────
+
+describe("Select onValueChange", () => {
+  it("fires onValueChange with selected item object (single)", async () => {
+    const onChange = vi.fn();
+    render(<Select items={fruits} defaultOpen onValueChange={onChange} />);
+
+    await userEvent.click(screen.getByRole("option", { name: "Banana" }));
+
+    expect(onChange).toHaveBeenCalledOnce();
+    expect(onChange.mock.calls[0][0]).toEqual({ id: "2", name: "Banana" });
+  });
+
+  it("accepts null as a controlled value without crashing", () => {
+    // The null branch in handleChange fires when Base UI passes null (e.g. programmatic
+    // clear). The composite does not expose a clear control, so we verify the component
+    // is stable with value={null} (the internal path is guarded against missing items).
+    expect(() =>
+      render(<Select items={fruits} value={null} onValueChange={vi.fn()} />),
+    ).not.toThrow();
+    expect(slot("select-trigger")).toBeInTheDocument();
+  });
+
+  it("fires onValueChange with array of items (multiple mode)", async () => {
+    const onChange = vi.fn();
+    render(
+      <Select
+        multiple
+        items={fruits}
+        defaultOpen
+        defaultValue={[]}
+        onValueChange={onChange}
+      />,
+    );
+
+    await userEvent.click(screen.getByRole("option", { name: "Apple" }));
+
+    expect(onChange).toHaveBeenCalledOnce();
+    expect(onChange.mock.calls[0][0]).toEqual([fruits[0]]);
+  });
+
+  it("maps multiple selection back to item objects", async () => {
+    const onChange = vi.fn();
+    render(
+      <Select
+        multiple
+        items={fruits}
+        defaultOpen
+        defaultValue={[fruits[0]]}
+        onValueChange={onChange}
+      />,
+    );
+
+    await userEvent.click(screen.getByRole("option", { name: "Banana" }));
+
+    expect(onChange).toHaveBeenCalled();
+    const selected: typeof fruits = onChange.mock.calls[0][0];
+    expect(selected.some((i) => i.name === "Banana")).toBe(true);
+  });
+});
+
+// ─── Composite Select — controlled value ─────────────────────────────────────
+
+describe("Select controlled value", () => {
+  it("reflects a controlled single value", () => {
+    render(<Select items={fruits} value={fruits[1]} />);
+    expect(slot("select-trigger")).toHaveTextContent("Banana");
+  });
+
+  it("reflects a controlled multiple value", () => {
+    render(
+      <Select multiple items={fruits} defaultValue={[fruits[0], fruits[2]]} />,
+    );
+    expect(slot("select-trigger")).toBeInTheDocument();
+  });
+
+  it("uses defaultValue for uncontrolled single", () => {
+    render(<Select items={fruits} defaultValue={fruits[2]} />);
+    expect(slot("select-trigger")).toHaveTextContent("Cherry");
+  });
+});