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

package/dist/src/components/combobox/combobox.d.ts

@@ -51,12 +51,25 @@ export declare function ComboboxChip({ children, removeProps, ...props }: Combob
     removeProps?: ComboboxPrimitive.ChipRemove.Props;
 }): React.ReactElement;
 export declare function ComboboxChipRemove(props: ComboboxPrimitive.ChipRemove.Props): React.ReactElement;
-type ComboboxBaseProps<TItem = unknown> = Omit<ComboboxPrimitive.Root.Props<TItem, boolean>, "items" | "itemToStringLabel" | "itemToStringValue" | "children" | "multiple" | "onValueChange" | "value" | "defaultValue"> & {
+type ComboboxId = 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 ComboboxId;
+} ? I : TItem extends {
+    value: infer V extends ComboboxId;
+} ? V : TItem extends ComboboxId ? TItem : string;
+type ComboboxBaseProps<TItem = unknown, TId extends ComboboxId = InferId<TItem>> = Omit<ComboboxPrimitive.Root.Props<TItem, boolean>, "items" | "itemToStringLabel" | "itemToStringValue" | "children" | "multiple" | "onValueChange" | "value" | "defaultValue" | "isItemEqualToValue"> & {
     items: readonly TItem[];
     /** Returns the display text for an item. Used for filter matching, ARIA, and the trigger input. 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 as the hidden form value when `name` is set. Defaults to `item.id`, `item.value`, or the stringified primitive. */
-    getId?: (item: TItem) => string;
+    /** Returns a stable id for an item. Used as the controlled `value`, React key, and hidden form value. Defaults to `item.id`, `item.value`, or the stringified primitive. */
+    getId?: (item: TItem) => TId;
     renderItem?: (item: TItem) => React.ReactNode;
     placeholder?: string;
     emptyText?: string;
@@ -83,16 +96,22 @@ type ComboboxBaseProps<TItem = unknown> = Omit<ComboboxPrimitive.Root.Props<TIte
         empty?: string;
     };
 };
-export type ComboboxProps<TItem = unknown> = (ComboboxBaseProps<TItem> & {
+export type ComboboxProps<TItem = unknown, TId extends ComboboxId = InferId<TItem>> = (ComboboxBaseProps<TItem, TId> & {
     multiple?: false;
-    value?: TItem | null;
-    defaultValue?: TItem | null;
-    onValueChange?: (value: TItem | null) => void;
-}) | (ComboboxBaseProps<TItem> & {
+    /** Controlled selection id. Pass the value returned by `getId` (string or number), not the item object. */
+    value?: TId | null;
+    /** Initial selection id for uncontrolled usage. */
+    defaultValue?: TId | null;
+    /** Called with the selected id and the full item when selection changes. Both are `null` when cleared. */
+    onValueChange?: (id: TId | null, item: TItem | null) => void;
+}) | (ComboboxBaseProps<TItem, TId> & {
     multiple: true;
-    value?: TItem[];
-    defaultValue?: TItem[];
-    onValueChange?: (value: TItem[]) => void;
+    /** Controlled selection ids for multiple mode. Pass the array of values returned by `getId`. */
+    value?: ReadonlyArray<TId>;
+    /** Initial selection ids for uncontrolled multiple mode. */
+    defaultValue?: ReadonlyArray<TId>;
+    /** Called with the array of selected ids and the array of full items when selection changes. */
+    onValueChange?: (ids: TId[], items: TItem[]) => void;
 });
 /**
  * Composite combobox for single and multiple selection.
@@ -109,6 +128,6 @@ export type ComboboxProps<TItem = unknown> = (ComboboxBaseProps<TItem> & {
  * Use `ComboboxRoot` + primitives directly when you need full structural
  * control beyond what escape-hatch props offer.
  */
-export declare function Combobox<TItem = unknown>(allProps: ComboboxProps<TItem>): React.ReactElement;
+export declare function Combobox<TItem = unknown, TId extends ComboboxId = InferId<TItem>>(allProps: ComboboxProps<TItem, TId>): React.ReactElement;
 export declare const useComboboxFilter: typeof ComboboxPrimitive.useFilter;
 export { ComboboxPrimitive };

package/dist/src/components/pagination/pagination.d.ts

@@ -1,5 +1,6 @@
 import { ComponentProps, ComponentType, ElementType, ReactNode } from 'react';
 import { Button } from '../button';
+import { SelectProps } from '../select';
 import { PageSize } from './pagination.model';
 type GetPageHref = (state: {
     page: number;
@@ -116,9 +117,12 @@ interface PaginationRangeProps {
     }) => ReactNode);
 }
 export declare function PaginationRange({ children, className, ...props }: PaginationRangeProps): import("react/jsx-runtime").JSX.Element;
-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 declare function PaginationSizeSelect({ sizes, className, ...props }: PaginationSizeSelectProps): import("react/jsx-runtime").JSX.Element;
 interface PaginationProps extends Omit<PaginationRootProps, "children"> {
     sizes?: readonly PageSize[] | PageSize[] | false;

package/dist/src/components/select/select.d.ts

@@ -29,12 +29,26 @@ export declare function SelectSeparator({ className, ...props }: SelectPrimitive
 export declare function SelectGroup(props: SelectPrimitive.Group.Props): React.ReactElement;
 export declare function SelectGroupLabel(props: SelectPrimitive.GroupLabel.Props): React.ReactElement;
 export declare function SelectLabel({ className, ...props }: SelectPrimitive.Label.Props): React.ReactElement;
-type SelectBaseProps<TItem = unknown> = Omit<SelectPrimitive.Root.Props<string, false>, "children" | "onValueChange" | "value" | "defaultValue" | "items" | "multiple"> & {
+/** 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;
@@ -50,16 +64,22 @@ type SelectBaseProps<TItem = unknown> = Omit<SelectPrimitive.Root.Props<string,
         item?: string;
     };
 };
-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;
-}) | (SelectBaseProps<TItem> & {
+    /** 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, 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;
 });
 /**
  * Composite select for single and multiple selection.
@@ -67,12 +87,18 @@ export type SelectProps<TItem = unknown> = (SelectBaseProps<TItem> & {
  * 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 declare function Select<TItem = unknown>(allProps: SelectProps<TItem>): React.ReactElement;
+export declare function Select<TItem = unknown, TId extends SelectId = InferId<TItem>>(allProps: SelectProps<TItem, TId>): React.ReactElement;
 export { SelectPrimitive };
 export { SelectPopup as SelectContent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boxcustodia/library",
-  "version": "2.0.0-alpha.30",
+  "version": "2.0.0-alpha.32",
   "type": "module",
   "main": "dist/index.cjs.js",
   "module": "dist/index.es.js",

package/src/components/calendar/calendar.tsx

@@ -32,7 +32,7 @@ function CalendarDropdown({
   return (
     <Select
       items={items}
-      value={selected}
+      value={selected?.value ?? null}
       icon={<ChevronDownIcon className={selectTriggerIconClassName} />}
       // Month/year dropdowns are calendar navigation, not form fields. Force
       // off the invalid state so a surrounding invalid Field never paints them
@@ -40,8 +40,8 @@ function CalendarDropdown({
       aria-invalid={false}
       className="py-1 h-7 border-none font-medium! w-fit! [&>span]:capitalize"
       getLabel={(o) => o.label}
-      getId={(o) => String(o.value)}
-      onValueChange={(item) => {
+      getId={(o) => o.value}
+      onValueChange={(_id, item) => {
         if (!onChange || item === null) return;
         onChange({
           target: { value: String(item.value) },

package/src/components/combobox/combobox.stories.tsx

@@ -110,17 +110,20 @@ export const WithClassNames: Story = {
  */
 export const Controlled: Story = {
   render: () => {
-    const [value, setValue] = useState<Item | null>(null);
+    const [value, setValue] = useState<string | null>(null);
     return (
       <div className="flex flex-col gap-4">
         <Combobox<Item>
           items={items}
           placeholder="Select a fruit…"
           value={value}
-          onValueChange={setValue}
+          onValueChange={(id) => setValue(id)}
         />
         <p className="text-sm text-muted-foreground">
-          Selected: {value ? value.label : "none"}
+          Selected:{" "}
+          {value
+            ? (items.find((i) => i.value === value)?.label ?? value)
+            : "none"}
         </p>
       </div>
     );
@@ -142,7 +145,7 @@ export const MultiplePreselected: Story = {
     <Combobox<Item>
       items={items}
       multiple
-      defaultValue={items.slice(0, 7)}
+      defaultValue={items.slice(0, 7).map((i) => i.value)}
       placeholder="Select fruits…"
     />
   ),

package/src/components/combobox/combobox.test.tsx

@@ -51,7 +51,7 @@ describe("Combobox (single mode)", () => {
     expect(options.map((o) => o.textContent)).toEqual(["Banana"]);
   });
 
-  it("fires onValueChange with the selected item object", async () => {
+  it("fires onValueChange with (id, item)", async () => {
     const onValueChange = vi.fn();
     render(
       <Combobox
@@ -66,7 +66,10 @@ describe("Combobox (single mode)", () => {
     await userEvent.type(input, "Cherry");
     await userEvent.click(screen.getByRole("option"));
 
-    expect(onValueChange.mock.calls[0][0]).toEqual({ id: "3", name: "Cherry" });
+    expect(onValueChange.mock.calls[0]).toEqual([
+      "3",
+      { id: "3", name: "Cherry" },
+    ]);
   });
 
   it("shows the default empty text when nothing matches", async () => {
@@ -120,7 +123,7 @@ describe("Combobox (single mode)", () => {
   });
 
   it("reflects a controlled value in the input", () => {
-    render(<Combobox items={items} placeholder="P" value={items[1]} />);
+    render(<Combobox items={items} placeholder="P" value={items[1].id} />);
 
     expect(getInput().value).toBe("Banana");
   });
@@ -178,7 +181,7 @@ describe("Combobox getId / getLabel defaults", () => {
       { label: "One", value: "1" },
       { label: "Two", value: "2" },
     ];
-    render(<Combobox items={opts} placeholder="P" value={opts[0]} />);
+    render(<Combobox items={opts} placeholder="P" value={opts[0].value} />);
 
     expect(getInput().value).toBe("One");
   });
@@ -198,7 +201,7 @@ describe("Combobox getId / getLabel defaults", () => {
       <Combobox
         items={opts}
         placeholder="P"
-        value={opts[1]}
+        value={opts[1].code}
         getLabel={(o) => o.country}
         getId={(o) => o.code}
       />,
@@ -207,11 +210,12 @@ describe("Combobox getId / getLabel defaults", () => {
     expect(getInput().value).toBe("Brazil");
   });
 
-  it("handles { title } shaped items", () => {
+  it("handles { title } shaped items", async () => {
     const opts = [{ title: "First" }, { title: "Second" }];
-    render(<Combobox items={opts} placeholder="P" value={opts[1]} />);
+    render(<Combobox items={opts} placeholder="P" />);
 
-    expect(getInput().value).toBe("Second");
+    await userEvent.click(getInput());
+    expect(screen.getAllByRole("option").length).toBe(2);
   });
 });
 
@@ -222,7 +226,7 @@ describe("Combobox (multiple mode)", () => {
         multiple
         items={items}
         placeholder="P"
-        defaultValue={[items[0], items[1]]}
+        defaultValue={[items[0].id, items[1].id]}
       />,
     );
 
@@ -254,7 +258,7 @@ describe("Combobox (multiple mode)", () => {
         multiple
         items={items}
         placeholder="P"
-        defaultValue={[items[0]]}
+        defaultValue={[items[0].id]}
       />,
     );
 
@@ -281,7 +285,7 @@ describe("Combobox (multiple mode)", () => {
     await userEvent.type(chipsInput, "Apple");
     await userEvent.click(screen.getByRole("option"));
 
-    expect(onValueChange.mock.calls[0][0]).toEqual([items[0]]);
+    expect(onValueChange.mock.calls[0]).toEqual([[items[0].id], [items[0]]]);
   });
 
   it("renders a start addon alongside the chips", () => {
@@ -290,7 +294,7 @@ describe("Combobox (multiple mode)", () => {
         multiple
         items={items}
         placeholder="P"
-        defaultValue={[items[0]]}
+        defaultValue={[items[0].id]}
         startAddon={<span data-testid="chips-addon">#</span>}
       />,
     );
@@ -307,7 +311,7 @@ describe("Combobox Field integration", () => {
           multiple
           items={items}
           placeholder="P"
-          defaultValue={[items[0]]}
+          defaultValue={[items[0].id]}
         />
       </Field>,
     );
@@ -323,7 +327,7 @@ describe("Combobox Field integration", () => {
         multiple
         items={items}
         placeholder="P"
-        defaultValue={[items[0]]}
+        defaultValue={[items[0].id]}
       />,
     );
 
@@ -339,7 +343,7 @@ describe("Combobox Field integration", () => {
           multiple
           items={items}
           placeholder="P"
-          defaultValue={[items[0]]}
+          defaultValue={[items[0].id]}
         />
       </Field>,
     );
@@ -459,3 +463,36 @@ describe("Combobox escape-hatch primitives", () => {
     ).toHaveTextContent("Fruits");
   });
 });
+
+// ─── Type contract ────────────────────────────────────────────────────────────
+
+describe("Combobox type contract", () => {
+  it("rejects an item object as value at compile time", () => {
+    // @ts-expect-error — object must not compile as value
+    render(<Combobox items={items} value={items[0]} />);
+    expect(getInput()).toBeInTheDocument();
+  });
+});
+
+// ─── Duplicate id warning ─────────────────────────────────────────────────────
+
+describe("Combobox 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(<Combobox items={[{ title: "A" }, { title: "B" }]} />);
+
+    expect(warn).toHaveBeenCalledOnce();
+    expect(warn.mock.calls[0][0]).toContain("[Combobox]");
+    warn.mockRestore();
+  });
+
+  it("does not warn when ids are unique", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    render(<Combobox items={items} />);
+
+    expect(warn).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+});

package/src/components/combobox/combobox.tsx

@@ -777,7 +777,27 @@ function ComboboxMultipleTrigger({
   );
 }
 
-type ComboboxBaseProps<TItem = unknown> = Omit<
+type ComboboxId = 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 ComboboxId }
+  ? I
+  : TItem extends { value: infer V extends ComboboxId }
+    ? V
+    : TItem extends ComboboxId
+      ? TItem
+      : string;
+
+type ComboboxBaseProps<
+  TItem = unknown,
+  TId extends ComboboxId = InferId<TItem>,
+> = Omit<
   ComboboxPrimitive.Root.Props<TItem, boolean>,
   | "items"
   | "itemToStringLabel"
@@ -787,12 +807,13 @@ type ComboboxBaseProps<TItem = unknown> = Omit<
   | "onValueChange"
   | "value"
   | "defaultValue"
+  | "isItemEqualToValue"
 > & {
   items: readonly TItem[];
   /** Returns the display text for an item. Used for filter matching, ARIA, and the trigger input. 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 as the hidden form value when `name` is set. Defaults to `item.id`, `item.value`, or the stringified primitive. */
-  getId?: (item: TItem) => string;
+  /** Returns a stable id for an item. Used as the controlled `value`, React key, and hidden form value. Defaults to `item.id`, `item.value`, or the stringified primitive. */
+  getId?: (item: TItem) => TId;
   renderItem?: (item: TItem) => React.ReactNode;
   placeholder?: string;
   emptyText?: string;
@@ -820,18 +841,27 @@ type ComboboxBaseProps<TItem = unknown> = Omit<
   };
 };
 
-export type ComboboxProps<TItem = unknown> =
-  | (ComboboxBaseProps<TItem> & {
+export type ComboboxProps<
+  TItem = unknown,
+  TId extends ComboboxId = InferId<TItem>,
+> =
+  | (ComboboxBaseProps<TItem, TId> & {
       multiple?: false;
-      value?: TItem | null;
-      defaultValue?: TItem | null;
-      onValueChange?: (value: TItem | null) => void;
+      /** Controlled selection id. Pass the value returned by `getId` (string or number), not the item object. */
+      value?: TId | null;
+      /** Initial selection id for uncontrolled usage. */
+      defaultValue?: TId | null;
+      /** Called with the selected id and the full item when selection changes. Both are `null` when cleared. */
+      onValueChange?: (id: TId | null, item: TItem | null) => void;
     })
-  | (ComboboxBaseProps<TItem> & {
+  | (ComboboxBaseProps<TItem, TId> & {
       multiple: true;
-      value?: TItem[];
-      defaultValue?: TItem[];
-      onValueChange?: (value: TItem[]) => void;
+      /** Controlled selection ids for multiple mode. Pass the array of values returned by `getId`. */
+      value?: ReadonlyArray<TId>;
+      /** Initial selection ids for uncontrolled multiple mode. */
+      defaultValue?: ReadonlyArray<TId>;
+      /** Called with the array of selected ids and the array of full items when selection changes. */
+      onValueChange?: (ids: TId[], items: TItem[]) => void;
     });
 
 /**
@@ -849,9 +879,10 @@ export type ComboboxProps<TItem = unknown> =
  * Use `ComboboxRoot` + primitives directly when you need full structural
  * control beyond what escape-hatch props offer.
  */
-export function Combobox<TItem = unknown>(
-  allProps: ComboboxProps<TItem>,
-): React.ReactElement {
+export function Combobox<
+  TItem = unknown,
+  TId extends ComboboxId = InferId<TItem>,
+>(allProps: ComboboxProps<TItem, TId>): React.ReactElement {
   // Cast internally — ComboboxProps discriminated union enforces correctness for consumers.
   // The union can't be spread directly into ComboboxRoot because TypeScript can't resolve
   // which branch is active at the call site.
@@ -871,25 +902,80 @@ export function Combobox<TItem = unknown>(
     showClear = true,
     searchable = true,
     ...rest
-  } = allProps as ComboboxBaseProps<TItem> & {
+  } = allProps as ComboboxBaseProps<TItem, TId> & {
     multiple?: boolean;
-    onValueChange?: (value: any, eventDetails?: any) => void;
+    onValueChange?: (v: any, e?: any) => void;
     value?: any;
     defaultValue?: any;
   };
 
   const getLabel: (item: TItem) => string = getLabelProp ?? defaultGetLabel;
-  const getId: (item: TItem) => string = getIdProp ?? defaultGetId;
+  const getId = (getIdProp ?? defaultGetId) as (item: TItem) => TId;
+
+  // 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(
+        `[Combobox] Multiple items resolve to the same id (${[...dupes].join(", ")}). ` +
+          "Provide a `getId` that returns a unique value per item.",
+      );
+    }
+  }
+
+  const objectValue = multiple
+    ? ((value as ReadonlyArray<TId> | undefined)
+        ?.map((v) => findByKey(String(v)))
+        .filter(Boolean) as TItem[] | undefined)
+    : value == null
+      ? (value as null | undefined)
+      : findByKey(String(value as TId));
+
+  const objectDefaultValue = multiple
+    ? ((defaultValue as ReadonlyArray<TId> | undefined)
+        ?.map((v) => findByKey(String(v)))
+        .filter(Boolean) as TItem[] | undefined)
+    : defaultValue == null
+      ? undefined
+      : findByKey(String(defaultValue as TId));
+
+  const handleChange = (v: TItem | TItem[] | null) => {
+    if (multiple) {
+      const items_ = (v as TItem[]) ?? [];
+      onValueChange?.(items_.map(getId), items_);
+    } else {
+      const item = (v as TItem | null) ?? null;
+      onValueChange?.(item ? getId(item) : null, item);
+    }
+  };
 
   return (
     <ComboboxRoot
       items={items}
       itemToStringLabel={getLabel}
-      itemToStringValue={getId}
+      itemToStringValue={getId as (item: TItem) => string}
       multiple={multiple as boolean}
-      onValueChange={onValueChange}
-      value={value}
-      defaultValue={defaultValue}
+      onValueChange={handleChange as any}
+      value={objectValue as any}
+      defaultValue={objectDefaultValue as any}
+      isItemEqualToValue={(a, b) => itemKey(a) === itemKey(b)}
       autoHighlight
       loopFocus
       {...rest}
@@ -897,7 +983,7 @@ export function Combobox<TItem = unknown>(
       {multiple ? (
         <ComboboxMultipleTrigger
           getLabel={getLabel}
-          getId={getId}
+          getId={getId as (item: any) => string}
           showClear={showClear}
           startAddon={startAddon}
           className={classNames?.chips}

package/src/components/form/form.stories.tsx

@@ -657,7 +657,8 @@ type MemberFormData = z.infer<typeof MemberSchema>;
  * Spread `{...field}` into inputs that accept `value` / `onChange` / `onBlur` / `ref`.
  *
  * Components with a typed item API require manual mapping:
- * - `Select` — `onChange` returns `TItem | null`, extract `.value` for `z.string()` schemas.
+ * - `Select` — `onValueChange` returns `(id, item)`; pass the `id` straight to
+ *   `field.onChange` for `z.string()` schemas (no `.value` extraction needed).
  * - `Checkbox` — uses `checked` / `onCheckedChange`, not `value` / `onChange`.
  */
 export const WithReactHookFormFull: Story = {
@@ -729,7 +730,7 @@ export const WithReactHookFormFull: Story = {
               placeholder="Select a role…"
               {...field}
               value={field.value}
-              onValueChange={(item) => onChange(item?.value)}
+              onValueChange={(id) => onChange(id)}
             />
           )}
         />

package/src/components/pagination/pagination.test.tsx

@@ -1,4 +1,5 @@
-import { fireEvent, render, screen } from "@testing-library/react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { describe, expect, it, vi } from "vitest";
 import {
   Pagination,
@@ -173,7 +174,7 @@ describe("Pagination primitives", () => {
     expect(screen.getByText(/Página 3 de 3/)).toBeInTheDocument();
   });
 
-  it("PaginationSizeSelect changes page size and resets to page 1", () => {
+  it("PaginationSizeSelect changes page size and resets to page 1", async () => {
     render(
       <PaginationRoot defaultPageSize={10} totalItems={50}>
         <PaginationSizeSelect />
@@ -181,9 +182,8 @@ describe("Pagination primitives", () => {
       </PaginationRoot>,
     );
     expect(screen.getByText(/1 - 10 de 50/)).toBeInTheDocument();
-    fireEvent.change(screen.getByRole("combobox"), {
-      target: { value: "25" },
-    });
+    await userEvent.click(screen.getByRole("combobox"));
+    await userEvent.click(screen.getByRole("option", { name: "25" }));
     expect(screen.getByText(/1 - 25 de 50/)).toBeInTheDocument();
   });