@boxcustodia/library 2.0.0-alpha.30 → 2.0.0-alpha.32

package/src/components/pagination/pagination.tsx

@@ -9,7 +9,6 @@ import {
   MoreHorizontal,
 } from "lucide-react";
 import {
-  ChangeEvent,
   ComponentProps,
   ComponentType,
   createContext,
@@ -21,6 +20,7 @@ import {
 import { DOTS, useRangePagination } from "../../hooks";
 import { cn } from "../../lib";
 import { Button } from "../button";
+import { Select, type SelectProps } from "../select";
 import { PAGINATION_SIZES, PageSize } from "./pagination.model";
 
 type GetPageHref = (state: { page: number; pageSize: number }) => string;
@@ -522,10 +522,12 @@ export function PaginationRange({
   );
 }
 
-interface PaginationSizeSelectProps
-  extends Omit<ComponentProps<"select">, "value" | "onChange"> {
+type PaginationSizeSelectProps = Omit<
+  SelectProps<{ label: string; value: PageSize }, PageSize>,
+  "items" | "value" | "defaultValue" | "onValueChange" | "multiple"
+> & {
   sizes?: readonly PageSize[] | PageSize[];
-}
+};
 
 export function PaginationSizeSelect({
   sizes = PAGINATION_SIZES,
@@ -534,30 +536,29 @@ export function PaginationSizeSelect({
 }: PaginationSizeSelectProps) {
   const { pageSize, setPageSize, goTo } = usePaginationContext();
 
-  const handleChange = (event: ChangeEvent<HTMLSelectElement>) => {
-    const next = Number(event.target.value) as PageSize;
-    setPageSize(next);
+  const handleChange = (value: PageSize) => {
+    setPageSize(value);
     goTo(1);
   };
 
+  const sizesOptions = sizes.map((size) => ({
+    label: String(size),
+    value: size,
+  }));
+
   return (
-    <select
+    <Select
+      items={sizesOptions}
       data-slot="pagination-size-select"
       value={pageSize}
-      onChange={handleChange}
+      onValueChange={(value) => value != null && handleChange(value)}
       className={cn(
         "border border-input rounded-md w-fit min-w-[3rem] bg-background p-2 ring-offset-background",
         "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
         className,
       )}
       {...props}
-    >
-      {sizes.map((size) => (
-        <option key={size} value={size} data-slot="pagination-size-option">
-          {size}
-        </option>
-      ))}
-    </select>
+    />
   );
 }
 

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

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
-import { useArgs } from "storybook/preview-api";
+import { useState } from "react";
 import { Button } from "../button";
 import { Field } from "../field";
 import { Form as LibraryForm } from "../form";
@@ -122,7 +122,7 @@ export const AlignItemWithTrigger: Story = {
           <span className="text-muted-foreground text-xs">
             Default (alignItemWithTrigger=false)
           </span>
-          <Select items={years} defaultValue={preselected} />
+          <Select items={years} defaultValue={preselected.value} />
         </div>
         <div className="flex flex-col gap-1">
           <span className="text-muted-foreground text-xs">
@@ -200,9 +200,9 @@ export const CustomObject: Story = {
 
 /**
  * `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.
+ * comma-separated list with automatic truncation. Use `value: TId[]` and
+ * `onValueChange: (ids: TId[], items: TItem[]) => void` for controlled usage —
+ * the discriminated union ensures type safety between single and multiple modes.
  */
 export const Multiple: Story = {
   render: () => (
@@ -240,21 +240,23 @@ export const CustomRender: Story = {
 };
 
 /**
- * `onValueChange` receives the full item object (or `null`).
- * `value` accepts the item object directly — no string conversion needed.
+ * `onValueChange` reports the selected **id first** and the resolved **item
+ * second**. `value` is the id (whatever `getId` returns). Hold only the id in state.
  */
 export const Controlled: Story = {
-  render: (args) => {
-    const [{ value }, updateArgs] = useArgs();
+  render: () => {
+    const [value, setValue] = useState<string | null>(null);
+    const selected = animals.find((a) => a.value === value) ?? null;
     return (
       <div className="flex flex-col gap-4">
         <Select
-          {...args}
-          value={value ?? null}
-          onValueChange={(item) => updateArgs({ value: item })}
+          items={animals}
+          value={value}
+          onValueChange={(id) => setValue(id)}
+          placeholder="Select an animal"
         />
         <p className="text-sm text-muted-foreground">
-          Selected: {value ? (value as Animal).label : "none"}
+          Selected: {selected ? selected.label : "none"}
         </p>
       </div>
     );
@@ -277,6 +279,42 @@ export const Form: Story = {
   ),
 };
 
+/**
+ * Controlled by **id** — the common form case where you hold only the id in
+ * state, not the whole object. An external button resets the id to `null` and
+ * the trigger falls back to `placeholder`.
+ *
+ * Pass `value` + `onValueChange` together. Setting `value={null}` clears the
+ * selection; passing only `value={null}` (no `onValueChange`) would switch the
+ * component to uncontrolled mode.
+ */
+export const Clearable: Story = {
+  render: () => {
+    const [id, setId] = useState<string | null>(null);
+    return (
+      <div className="flex flex-col gap-4">
+        <Select
+          items={animals}
+          value={id}
+          onValueChange={(next) => setId(next)}
+          placeholder="Select an animal"
+        />
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          onClick={() => setId(null)}
+        >
+          Clear
+        </Button>
+        <p className="text-muted-foreground text-sm">
+          Selected: {id ?? "none"}
+        </p>
+      </div>
+    );
+  },
+};
+
 /**
  * Use `SelectRoot` + primitives for full structural control: custom grouping,
  * separators, and arbitrary content inside items.

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

@@ -1,5 +1,6 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
+import * as React from "react";
 import { describe, expect, it, vi } from "vitest";
 import {
   Select,
@@ -277,14 +278,15 @@ describe("Select disabled items", () => {
 // ─── Composite Select — value / onChange ─────────────────────────────────────
 
 describe("Select onValueChange", () => {
-  it("fires onValueChange with selected item object (single)", async () => {
+  it("reports id first, then the resolved item (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" });
+    expect(onChange.mock.calls[0][0]).toBe("2");
+    expect(onChange.mock.calls[0][1]).toEqual({ id: "2", name: "Banana" });
   });
 
   it("accepts null as a controlled value without crashing", () => {
@@ -297,7 +299,7 @@ describe("Select onValueChange", () => {
     expect(slot("select-trigger")).toBeInTheDocument();
   });
 
-  it("fires onValueChange with array of items (multiple mode)", async () => {
+  it("reports ids first, then items (multiple mode)", async () => {
     const onChange = vi.fn();
     render(
       <Select
@@ -312,7 +314,8 @@ describe("Select onValueChange", () => {
     await userEvent.click(screen.getByRole("option", { name: "Apple" }));
 
     expect(onChange).toHaveBeenCalledOnce();
-    expect(onChange.mock.calls[0][0]).toEqual([fruits[0]]);
+    expect(onChange.mock.calls[0][0]).toEqual(["1"]);
+    expect(onChange.mock.calls[0][1]).toEqual([fruits[0]]);
   });
 
   it("maps multiple selection back to item objects", async () => {
@@ -322,7 +325,7 @@ describe("Select onValueChange", () => {
         multiple
         items={fruits}
         defaultOpen
-        defaultValue={[fruits[0]]}
+        defaultValue={["1"]}
         onValueChange={onChange}
       />,
     );
@@ -330,28 +333,123 @@ describe("Select onValueChange", () => {
     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);
+    const ids: string[] = onChange.mock.calls[0][0];
+    const items: typeof fruits = onChange.mock.calls[0][1];
+    expect(ids).toContain("2");
+    expect(items.some((i) => i.name === "Banana")).toBe(true);
   });
 });
 
-// ─── Composite Select — controlled value ─────────────────────────────────────
+// ─── Composite Select — controlled value (id-first) ──────────────────────────
 
-describe("Select controlled value", () => {
-  it("reflects a controlled single value", () => {
-    render(<Select items={fruits} value={fruits[1]} />);
+describe("Select controlled value (id-first)", () => {
+  it("reflects a controlled multiple value", () => {
+    render(<Select multiple items={fruits} defaultValue={["1", "3"]} />);
+    expect(slot("select-trigger")).toBeInTheDocument();
+  });
+
+  it("clears the trigger after selecting a value and resetting to null", async () => {
+    function Wrapper() {
+      const [id, setId] = React.useState<string | null>(null);
+      return (
+        <>
+          <Select
+            items={fruits}
+            value={id}
+            onValueChange={(next) => setId(next)}
+            placeholder="Pick a fruit"
+          />
+          <button type="button" onClick={() => setId(null)}>
+            Clear
+          </button>
+        </>
+      );
+    }
+
+    render(<Wrapper />);
+
+    expect(slot("select-trigger")).toHaveTextContent("Pick a fruit");
+
+    await userEvent.click(slot("select-trigger")!);
+    await userEvent.click(screen.getByRole("option", { name: "Banana" }));
+
+    expect(slot("select-trigger")).toHaveTextContent("Banana");
+
+    await userEvent.click(screen.getByRole("button", { name: "Clear" }));
+
+    expect(slot("select-trigger")).toHaveTextContent("Pick a fruit");
+    expect(slot("select-trigger")).not.toHaveTextContent("Banana");
+  });
+
+  it("reflects a controlled id string (single)", () => {
+    render(<Select items={fruits} value="2" />);
     expect(slot("select-trigger")).toHaveTextContent("Banana");
   });
 
-  it("reflects a controlled multiple value", () => {
+  it("uses an id string as defaultValue (uncontrolled)", () => {
+    render(<Select items={fruits} defaultValue="3" />);
+    expect(slot("select-trigger")).toHaveTextContent("Cherry");
+  });
+
+  it("reflects controlled ids for multiple", () => {
+    render(<Select multiple items={fruits} value={["1", "3"]} />);
+    expect(slot("select-trigger")).toBeInTheDocument();
+  });
+
+  it("matches a numeric id via custom getId and returns it as a number", async () => {
+    const numeric = [
+      { id: 1, name: "Aumentar retención" },
+      { id: 2, name: "Reducir churn" },
+    ];
+    const onChange = vi.fn();
     render(
-      <Select multiple items={fruits} defaultValue={[fruits[0], fruits[2]]} />,
+      <Select
+        items={numeric}
+        getId={(o) => o.id}
+        value={2}
+        defaultOpen
+        onValueChange={onChange}
+      />,
     );
+
+    // value={2} (number) resolves to the matching item
+    expect(slot("select-trigger")).toHaveTextContent("Reducir churn");
+
+    await userEvent.click(
+      screen.getByRole("option", { name: "Aumentar retención" }),
+    );
+
+    // id comes back as the original number type, not stringified
+    expect(onChange.mock.calls[0][0]).toBe(1);
+    expect(onChange.mock.calls[0][1]).toEqual(numeric[0]);
+  });
+
+  it("rejects an item object as value at compile time", () => {
+    // @ts-expect-error — value is id-first; passing the item must not compile.
+    render(<Select items={fruits} value={fruits[1]} />);
     expect(slot("select-trigger")).toBeInTheDocument();
   });
+});
 
-  it("uses defaultValue for uncontrolled single", () => {
-    render(<Select items={fruits} defaultValue={fruits[2]} />);
-    expect(slot("select-trigger")).toHaveTextContent("Cherry");
+// ─── Composite Select — duplicate id warning ─────────────────────────────────
+
+describe("Select duplicate id warning", () => {
+  it("warns in dev when items collide on the same id", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    // `{ title }` items have no id/value → defaultGetId collapses them all to
+    // "[object Object]", a silent collision this warning surfaces.
+    render(<Select items={[{ title: "Alpha" }, { title: "Beta" }]} />);
+
+    expect(warn).toHaveBeenCalledOnce();
+    expect(warn.mock.calls[0][0]).toContain("[Select]");
+    warn.mockRestore();
+  });
+
+  it("does not warn when ids are unique", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    render(<Select items={fruits} />);
+
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
   });
 });

package/src/components/select/select.tsx

@@ -295,15 +295,33 @@ function defaultGetDisabled(item: unknown): boolean {
   return false;
 }
 
-type SelectBaseProps<TItem = unknown> = Omit<
+/** Identifier an item can be addressed by. */
+type SelectId = string | number;
+
+/**
+ * Infers the id type from the shape of an item, mirroring `defaultGetId`'s
+ * lookup order (`id` before `value`, then the primitive itself). Lets the
+ * common case — `{ id, name }`, `{ label, value }`, or plain primitives — drive
+ * `value` / `onValueChange` typing with no explicit `getId`. Falls back to
+ * `string` for shapes `defaultGetId` can't address.
+ */
+type InferId<TItem> = TItem extends { id: infer I extends SelectId }
+  ? I
+  : TItem extends { value: infer V extends SelectId }
+    ? V
+    : TItem extends SelectId
+      ? TItem
+      : string;
+
+type SelectBaseProps<TItem, TId extends SelectId> = Omit<
   SelectPrimitive.Root.Props<string, false>,
   "children" | "onValueChange" | "value" | "defaultValue" | "items" | "multiple"
 > & {
   items: readonly TItem[];
   /** Returns the display text for an item. Used for the trigger value and ARIA. Defaults to `item.label`, `item.name`, `item.title`, or the stringified primitive. */
   getLabel?: (item: TItem) => string;
-  /** Returns a stable string identifier for an item. Used as the React key and the underlying option value. Defaults to `item.id`, `item.value`, or the stringified primitive. */
-  getId?: (item: TItem) => string;
+  /** Returns a stable identifier for an item — `string` or `number`. Used as the option value and to match against `value`. Its return type drives the `value` / `onValueChange` id type. Defaults to `item.id`, `item.value`, or the stringified primitive. */
+  getId?: (item: TItem) => TId;
   /** Returns whether an item should be disabled. Defaults to `item.disabled === true`. */
   getDisabled?: (item: TItem) => boolean;
   renderItem?: (item: TItem) => React.ReactNode;
@@ -320,18 +338,27 @@ type SelectBaseProps<TItem = unknown> = Omit<
   };
 };
 
-export type SelectProps<TItem = unknown> =
-  | (SelectBaseProps<TItem> & {
+export type SelectProps<
+  TItem = unknown,
+  TId extends SelectId = InferId<TItem>,
+> =
+  | (SelectBaseProps<TItem, TId> & {
       multiple?: false;
-      value?: TItem | null;
-      defaultValue?: TItem | null;
-      onValueChange?: (value: TItem | null) => void;
+      /** Controlled selection. The id (whatever `getId` returns — `string` or `number`), or `null` when cleared. */
+      value?: TId | null;
+      /** Uncontrolled initial selection. The id (whatever `getId` returns). */
+      defaultValue?: TId | null;
+      /** Called on change with the selected id first, then the resolved item (both `null` when cleared). */
+      onValueChange?: (id: TId | null, item: TItem | null) => void;
     })
-  | (SelectBaseProps<TItem> & {
+  | (SelectBaseProps<TItem, TId> & {
       multiple: true;
-      value?: TItem[];
-      defaultValue?: TItem[];
-      onValueChange?: (value: TItem[]) => void;
+      /** Controlled selection. The ids (whatever `getId` returns). */
+      value?: ReadonlyArray<TId>;
+      /** Uncontrolled initial selection. The ids (whatever `getId` returns). */
+      defaultValue?: ReadonlyArray<TId>;
+      /** Called on change with the selected ids first, then the resolved items. */
+      onValueChange?: (ids: TId[], items: TItem[]) => void;
     });
 
 /**
@@ -340,14 +367,20 @@ export type SelectProps<TItem = unknown> =
  * Items shaped as `{ id, name }`, `{ label, value }`, or plain strings/numbers
  * work with no extra props. For other shapes, provide `getLabel` and/or `getId`.
  *
+ * `value` / `defaultValue` accept the id only (whatever `getId` returns —
+ * `string` or `number`). `onValueChange` always reports the id first and the
+ * resolved item second, so it wires directly into react-hook-form
+ * (`onValueChange={field.onChange}`) while still exposing the full item when
+ * you need to render it.
+ *
  * `renderItem` customizes the content **inside** each `SelectItem` (the
  * checkmark indicator is always rendered by the item wrapper).
  *
  * Use `SelectRoot` + primitives directly when you need full structural
  * control beyond what `className` + `classNames` slots offer.
  */
-export function Select<TItem = unknown>(
-  allProps: SelectProps<TItem>,
+export function Select<TItem = unknown, TId extends SelectId = InferId<TItem>>(
+  allProps: SelectProps<TItem, TId>,
 ): React.ReactElement {
   const {
     items,
@@ -365,51 +398,78 @@ export function Select<TItem = unknown>(
     icon,
     "aria-invalid": ariaInvalid,
     ...rest
-  } = allProps as SelectBaseProps<TItem> & {
+  } = allProps as SelectBaseProps<TItem, TId> & {
     multiple?: boolean;
-    onValueChange?: (value: any) => void;
+    onValueChange?: (id: any, item: any) => void;
     value?: any;
     defaultValue?: any;
     "aria-invalid"?: React.AriaAttributes["aria-invalid"];
   };
 
   const getLabel: (item: TItem) => string = getLabelProp ?? defaultGetLabel;
-  const getId: (item: TItem) => string = getIdProp ?? defaultGetId;
+  const getId = (getIdProp ?? defaultGetId) as (item: TItem) => TId;
   const getDisabled: (item: TItem) => boolean =
     getDisabledProp ?? defaultGetDisabled;
 
+  // Base UI matches the selected value against item values by `Object.is`, so
+  // the composite keys every option by a normalized string. `value` arrives as
+  // the id (string or number); `String(...)` normalizes both to that same key,
+  // so matching stays stable across string/number ids.
+  const itemKey = (item: TItem): string => String(getId(item));
+  const findByKey = (key: string): TItem | null =>
+    items.find((i) => itemKey(i) === key) ?? null;
+
+  // Warn (dev only, once) when two items resolve to the same id — e.g. objects
+  // with only a `title` and no `id`/`value`, which collapse to "[object Object]".
+  const warnedRef = React.useRef(false);
+  if (process.env.NODE_ENV !== "production" && !warnedRef.current) {
+    const seen = new Set<string>();
+    const dupes = new Set<string>();
+    for (const item of items) {
+      const key = itemKey(item);
+      if (seen.has(key)) dupes.add(key);
+      seen.add(key);
+    }
+    if (dupes.size > 0) {
+      warnedRef.current = true;
+      console.warn(
+        `[Select] Multiple items resolve to the same id (${[...dupes].join(", ")}). ` +
+          "Provide a `getId` that returns a unique value per item.",
+      );
+    }
+  }
+
   const stringValue = multiple
-    ? (value as TItem[] | undefined)?.map(getId)
-    : value != null
-      ? getId(value as TItem)
-      : undefined;
+    ? (value as ReadonlyArray<TId> | undefined)?.map((v) => String(v as TId))
+    : value == null
+      ? (value as null | undefined)
+      : String(value as TId);
 
   const stringDefaultValue = multiple
-    ? (defaultValue as TItem[] | undefined)?.map(getId)
-    : defaultValue != null
-      ? getId(defaultValue as TItem)
-      : undefined;
+    ? (defaultValue as ReadonlyArray<TId> | undefined)?.map((v) =>
+        String(v as TId),
+      )
+    : defaultValue == null
+      ? undefined
+      : String(defaultValue as TId);
 
   const handleChange = (stringVal: string | string[] | null) => {
     if (multiple) {
-      const vals = (stringVal as string[]) ?? [];
-      const found = vals
-        .map((sv) => items.find((i) => getId(i) === sv) ?? null)
-        .filter(Boolean) as TItem[];
-      onValueChange?.(found);
+      const keys = (stringVal as string[]) ?? [];
+      const found = keys.map(findByKey).filter(Boolean) as TItem[];
+      onValueChange?.(found.map(getId), found);
     } else {
       if (stringVal == null) {
-        onValueChange?.(null);
+        onValueChange?.(null, null);
         return;
       }
-      const item =
-        items.find((i) => getId(i) === (stringVal as string)) ?? null;
-      onValueChange?.(item);
+      const item = findByKey(stringVal as string);
+      onValueChange?.(item ? getId(item) : null, item);
     }
   };
 
   const itemToStringLabel = (stringVal: string) => {
-    const item = items.find((i) => getId(i) === stringVal);
+    const item = findByKey(stringVal);
     return item ? getLabel(item) : stringVal;
   };
 
@@ -435,8 +495,8 @@ export function Select<TItem = unknown>(
       <SelectPopup className={classNames?.popup}>
         {items.map((item) => (
           <SelectItem
-            key={getId(item)}
-            value={getId(item)}
+            key={itemKey(item)}
+            value={itemKey(item)}
             disabled={getDisabled(item)}
             className={classNames?.item}
           >

package/src/hooks/use-pagination/use-pagination.test.tsx

@@ -324,6 +324,32 @@ describe("usePagination — Controllable Page", () => {
     expect(onPageChange).toHaveBeenCalledWith(3);
   });
 
+  it("Scenario 21b — onPageChange fires when controlled prop diverges from internal state then user navigates back to page 1", () => {
+    // Regression: if the page prop is updated externally (no internal navigation),
+    // pageState stays at its default (1). A subsequent goTo(1) calls setPageState(1)
+    // which is a React no-op → useEffect never fires → onPageChange silently skipped.
+    const onPageChange = vi.fn();
+    let controlledPage = 1;
+    const { result, rerender } = renderHook(() =>
+      usePagination({
+        totalItems: 100,
+        defaultPageSize: 10,
+        page: controlledPage,
+        onPageChange,
+      }),
+    );
+
+    // Parent externally jumps to page 5 — no internal navigation, pageState stays 1
+    controlledPage = 5;
+    rerender();
+    expect(result.current.page).toBe(5);
+    onPageChange.mockClear();
+
+    // User clicks "First" — should fire onPageChange(1)
+    act(() => result.current.goTo(1));
+    expect(onPageChange).toHaveBeenCalledWith(1);
+  });
+
   it("Scenario 22 — onPageChange NOT fired on mount", () => {
     const onPageChange = vi.fn();
     renderHook(() =>

package/src/hooks/use-pagination/use-pagination.ts

@@ -136,6 +136,7 @@ export function usePagination({
 
   // Refs so memoized actions read live values without stale closures
   const pageRef = useLatestRef(page);
+  const pageStateRef = useLatestRef(pageState);
   const pageSizeRef = useLatestRef(pageSize);
   const pageCountRef = useLatestRef(pageCount);
   const onPageChangeRef = useLatestRef(onPageChange);
@@ -186,6 +187,14 @@ export function usePagination({
     const applyPage = (target: number) => {
       const clamped = clampPage(target, pageCountRef.current);
       if (clamped === pageRef.current) return; // no-op for same page
+      // In controlled mode, pageState may already equal `clamped` (diverged from
+      // pageProp), so setPageState would be a no-op and the useEffect that fires
+      // onPageChange would never run. Mirror the same direct-fire pattern used in
+      // setPageSize to guarantee the callback reaches the consumer.
+      if (pageStateRef.current === clamped) {
+        lastEmittedPageRef.current = clamped;
+        onPageChangeRef.current?.(clamped);
+      }
       setPageState(clamped);
     };