@boxcustodia/library 2.0.0-alpha.31 → 2.0.0-alpha.33

package/dist/hooks/use-pagination/use-pagination.es.js

@@ -1,83 +1,83 @@
-import { useState as b, useRef as P, useEffect as p, useMemo as V } from "react";
-import { useLatestRef as s } from "../internal/use-latest-ref.es.js";
-const Z = 10, $ = 1;
+import { useState as b, useRef as S, useEffect as l, useMemo as Z } from "react";
+import { useLatestRef as o } from "../internal/use-latest-ref.es.js";
+const $ = 10, j = 1;
 function d(e, t) {
   return e <= 0 || Number.isNaN(e) ? (process.env.NODE_ENV !== "production" && (!t || !t.current) && (t && (t.current = !0), console.warn(
     `[usePagination] pageSize must be a positive number, received ${e}. Coercing to 1.`
   )), 1) : Math.floor(e);
 }
-function j(e, t) {
+function k(e, t) {
   return e <= 0 ? 0 : Math.ceil(e / t);
 }
 function N(e, t) {
   return t <= 0 || Number.isNaN(e) ? 1 : Math.min(Math.max(1, Math.floor(e)), t);
 }
-function B({
+function H({
   totalItems: e,
   pageSize: t,
-  defaultPageSize: x = Z,
+  defaultPageSize: x = $,
   onPageSizeChange: A,
   page: L,
-  defaultPage: _ = $,
+  defaultPage: _ = j,
   onPageChange: D,
   onPaginationChange: F
 }) {
-  const [S, l] = b(_), [m, R] = b(x), T = P(!1), u = d(t ?? m, T), o = j(e, u), n = N(L ?? S, o), i = s(n), G = s(u), c = s(o), v = s(D), z = s(A), U = s(F), g = P(!1), h = P(null), E = P(null);
-  p(() => {
-    if (!g.current) return;
-    const r = N(S, c.current);
-    h.current !== r && (h.current = r, v.current?.(r));
-  }, [S]), p(() => {
-    if (!g.current) return;
-    const r = d(m);
-    E.current !== r && (E.current = r, z.current?.(r));
-  }, [m]), p(() => {
-    g.current && U.current?.({ page: n, pageSize: u });
-  }, [n, u]), p(() => {
-    g.current = !0;
+  const [g, m] = b(_), [h, v] = b(x), T = S(!1), c = d(t ?? h, T), i = k(e, c), u = N(L ?? g, i), s = o(u), G = o(g), U = o(c), a = o(i), E = o(D), z = o(A), y = o(F), P = S(!1), p = S(null), R = S(null);
+  l(() => {
+    if (!P.current) return;
+    const r = N(g, a.current);
+    p.current !== r && (p.current = r, E.current?.(r));
+  }, [g]), l(() => {
+    if (!P.current) return;
+    const r = d(h);
+    R.current !== r && (R.current = r, z.current?.(r));
+  }, [h]), l(() => {
+    P.current && y.current?.({ page: u, pageSize: c });
+  }, [u, c]), l(() => {
+    P.current = !0;
   }, []);
-  const y = V(() => {
+  const O = Z(() => {
     const r = (f) => {
-      const a = N(f, c.current);
-      a !== i.current && l(a);
+      const n = N(f, a.current);
+      n !== s.current && (G.current === n && (p.current = n, E.current?.(n)), m(n));
     };
     return {
       goTo: (f) => {
-        c.current <= 0 || r(f);
+        a.current <= 0 || r(f);
       },
       next: () => {
-        i.current >= c.current || r(i.current + 1);
+        s.current >= a.current || r(s.current + 1);
       },
       prev: () => {
-        i.current <= 1 || r(i.current - 1);
+        s.current <= 1 || r(s.current - 1);
       },
       firstPage: () => {
-        c.current <= 0 || r(1);
+        a.current <= 0 || r(1);
       },
       lastPage: () => {
-        c.current <= 0 || r(c.current);
+        a.current <= 0 || r(a.current);
       },
       setPageSize: (f) => {
-        const a = d(f);
-        a !== G.current && (E.current = a, R(a), z.current?.(a), i.current !== 1 && (h.current = 1, v.current?.(1)), l(1));
+        const n = d(f);
+        n !== U.current && (R.current = n, v(n), z.current?.(n), s.current !== 1 && (p.current = 1, E.current?.(1)), m(1));
       }
     };
-  }, [l, R]), M = o <= 0 ? !0 : n <= 1, C = o <= 0 ? !0 : n >= o, O = e <= 0 ? { start: 0, end: 0 } : {
-    start: (n - 1) * u + 1,
-    end: Math.min(n * u, e)
+  }, [m, v]), M = i <= 0 ? !0 : u <= 1, C = i <= 0 ? !0 : u >= i, V = e <= 0 ? { start: 0, end: 0 } : {
+    start: (u - 1) * c + 1,
+    end: Math.min(u * c, e)
   };
   return {
-    page: n,
-    pageSize: u,
-    pageCount: o,
+    page: u,
+    pageSize: c,
+    pageCount: i,
     isFirstPage: M,
     isLastPage: C,
     hasPrevPage: !M,
     hasNextPage: !C,
-    range: O,
-    ...y
+    range: V,
+    ...O
   };
 }
 export {
-  B as usePagination
+  H as usePagination
 };

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

@@ -1,4 +1,5 @@
 import { Combobox as ComboboxPrimitive } from '@base-ui/react/combobox';
+import { InferItemId, ItemId } from '../../utils/internal';
 import * as React from "react";
 export declare const ComboboxContext: React.Context<{
     chipsRef: React.RefObject<Element | null> | null;
@@ -51,20 +52,7 @@ 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 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"> & {
+type ComboboxBaseProps<TItem = unknown, TId extends ItemId = InferItemId<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;
@@ -96,7 +84,7 @@ type ComboboxBaseProps<TItem = unknown, TId extends ComboboxId = InferId<TItem>>
         empty?: string;
     };
 };
-export type ComboboxProps<TItem = unknown, TId extends ComboboxId = InferId<TItem>> = (ComboboxBaseProps<TItem, TId> & {
+export type ComboboxProps<TItem = unknown, TId extends ItemId = InferItemId<TItem>> = (ComboboxBaseProps<TItem, TId> & {
     multiple?: false;
     /** Controlled selection id. Pass the value returned by `getId` (string or number), not the item object. */
     value?: TId | null;
@@ -128,6 +116,6 @@ export type ComboboxProps<TItem = unknown, TId extends ComboboxId = InferId<TIte
  * Use `ComboboxRoot` + primitives directly when you need full structural
  * control beyond what escape-hatch props offer.
  */
-export declare function Combobox<TItem = unknown, TId extends ComboboxId = InferId<TItem>>(allProps: ComboboxProps<TItem, TId>): React.ReactElement;
+export declare function Combobox<TItem = unknown, TId extends ItemId = InferItemId<TItem>>(allProps: ComboboxProps<TItem, TId>): React.ReactElement;
 export declare const useComboboxFilter: typeof ComboboxPrimitive.useFilter;
 export { ComboboxPrimitive };

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

@@ -1,5 +1,6 @@
 import { Select as SelectPrimitive } from '@base-ui/react/select';
 import { useRender } from '@base-ui/react/use-render';
+import { InferItemId, ItemId } from '../../utils/internal';
 import * as React from "react";
 export declare const selectTriggerClasses: string;
 export declare const selectTriggerIconClassName = "-me-1 size-4.5 opacity-80 sm:size-4";
@@ -29,21 +30,7 @@ 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;
-/** 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"> & {
+type SelectBaseProps<TItem, TId extends ItemId> = 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;
@@ -64,7 +51,7 @@ type SelectBaseProps<TItem, TId extends SelectId> = Omit<SelectPrimitive.Root.Pr
         item?: string;
     };
 };
-export type SelectProps<TItem = unknown, TId extends SelectId = InferId<TItem>> = (SelectBaseProps<TItem, TId> & {
+export type SelectProps<TItem = unknown, TId extends ItemId = InferItemId<TItem>> = (SelectBaseProps<TItem, TId> & {
     multiple?: false;
     /** Controlled selection. The id (whatever `getId` returns — `string` or `number`), or `null` when cleared. */
     value?: TId | null;
@@ -99,6 +86,6 @@ export type SelectProps<TItem = unknown, TId extends SelectId = InferId<TItem>>
  * Use `SelectRoot` + primitives directly when you need full structural
  * control beyond what `className` + `classNames` slots offer.
  */
-export declare function Select<TItem = unknown, TId extends SelectId = InferId<TItem>>(allProps: SelectProps<TItem, TId>): React.ReactElement;
+export declare function Select<TItem = unknown, TId extends ItemId = InferItemId<TItem>>(allProps: SelectProps<TItem, TId>): React.ReactElement;
 export { SelectPrimitive };
 export { SelectPopup as SelectContent };

package/dist/src/utils/internal/index.d.ts

@@ -0,0 +1,2 @@
+export type { InferItemId, ItemId } from './item';
+export { defaultGetId, defaultGetLabel } from './item';

package/dist/src/utils/internal/item.d.ts

@@ -0,0 +1,27 @@
+/** Identifier an item can be addressed by. */
+export type ItemId = 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.
+ */
+export type InferItemId<TItem> = TItem extends {
+    id: infer I extends ItemId;
+} ? I : TItem extends {
+    value: infer V extends ItemId;
+} ? V : TItem extends ItemId ? TItem : string;
+/**
+ * Resolves the display text for an item. Defaults to `item.label`, `item.name`,
+ * `item.title`, or the stringified primitive. Always returns a string — labels
+ * are display text.
+ */
+export declare function defaultGetLabel(item: unknown): string;
+/**
+ * Resolves the id for an item, preserving its native type. The internal Base UI
+ * layer keys options by string (callers wrap this in `String(...)`), so keeping
+ * the raw type here lets `onValueChange` hand back a numeric id as a number, not
+ * a string. Defaults to `item.id`, `item.value`, or the stringified primitive.
+ */
+export declare function defaultGetId(item: unknown): ItemId;

package/dist/utils/internal/item.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function t(r){if(r==null)return"";if(typeof r=="string"||typeof r=="number")return String(r);if(typeof r=="object"){const n=r;if("label"in n)return String(n.label);if("name"in n)return String(n.name);if("title"in n)return String(n.title)}return String(r)}function e(r){if(r==null)return"";if(typeof r=="string"||typeof r=="number")return r;if(typeof r=="object"){const n=r;if("id"in n)return n.id;if("value"in n)return n.value}return String(r)}exports.defaultGetId=e;exports.defaultGetLabel=t;

package/dist/utils/internal/item.es.js

@@ -0,0 +1,25 @@
+function t(r) {
+  if (r == null) return "";
+  if (typeof r == "string" || typeof r == "number") return String(r);
+  if (typeof r == "object") {
+    const n = r;
+    if ("label" in n) return String(n.label);
+    if ("name" in n) return String(n.name);
+    if ("title" in n) return String(n.title);
+  }
+  return String(r);
+}
+function e(r) {
+  if (r == null) return "";
+  if (typeof r == "string" || typeof r == "number") return r;
+  if (typeof r == "object") {
+    const n = r;
+    if ("id" in n) return n.id;
+    if ("value" in n) return n.value;
+  }
+  return String(r);
+}
+export {
+  e as defaultGetId,
+  t as defaultGetLabel
+};

package/package.json

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

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

@@ -217,6 +217,31 @@ describe("Combobox getId / getLabel defaults", () => {
     await userEvent.click(getInput());
     expect(screen.getAllByRole("option").length).toBe(2);
   });
+
+  it("returns a numeric id as a number without a custom getId", async () => {
+    const numeric = [
+      { id: 1, name: "Apple" },
+      { id: 2, name: "Banana" },
+    ];
+    const onValueChange = vi.fn();
+    render(
+      <Combobox
+        items={numeric}
+        placeholder="P"
+        onValueChange={onValueChange}
+      />,
+    );
+
+    const input = getInput();
+    await userEvent.click(input);
+    await userEvent.type(input, "Banana");
+    await userEvent.click(screen.getByRole("option"));
+
+    // defaultGetId preserves the native id type — number stays a number,
+    // not a stringified "2".
+    expect(onValueChange.mock.calls[0][0]).toBe(2);
+    expect(typeof onValueChange.mock.calls[0][0]).toBe("number");
+  });
 });
 
 describe("Combobox (multiple mode)", () => {

package/src/components/combobox/combobox.tsx

@@ -6,6 +6,12 @@ import { ChevronsUpDownIcon, XIcon } from "lucide-react";
 import * as React from "react";
 import { useIsomorphicLayoutEffect } from "../../hooks/internal";
 import { cn } from "../../lib";
+import {
+  defaultGetId,
+  defaultGetLabel,
+  type InferItemId,
+  type ItemId,
+} from "../../utils/internal";
 import { useIsInsideFieldRoot } from "../field";
 import { Input, inputBaseClasses } from "../input";
 import { ScrollArea } from "../scroll-area";
@@ -702,29 +708,6 @@ function ComboboxMultipleChipsContent({
 
 // ─── Composite ────────────────────────────────────────────────────────────────
 
-function defaultGetLabel(item: unknown): string {
-  if (item == null) return "";
-  if (typeof item === "string" || typeof item === "number") return String(item);
-  if (typeof item === "object") {
-    const record = item as Record<string, unknown>;
-    if ("label" in record) return String(record.label);
-    if ("name" in record) return String(record.name);
-    if ("title" in record) return String(record.title);
-  }
-  return String(item);
-}
-
-function defaultGetId(item: unknown): string {
-  if (item == null) return "";
-  if (typeof item === "string" || typeof item === "number") return String(item);
-  if (typeof item === "object") {
-    const record = item as Record<string, unknown>;
-    if ("id" in record) return String(record.id);
-    if ("value" in record) return String(record.value);
-  }
-  return String(item);
-}
-
 function ComboboxSingleTrigger({
   placeholder,
   showClear,
@@ -777,26 +760,9 @@ function ComboboxMultipleTrigger({
   );
 }
 
-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>,
+  TId extends ItemId = InferItemId<TItem>,
 > = Omit<
   ComboboxPrimitive.Root.Props<TItem, boolean>,
   | "items"
@@ -843,7 +809,7 @@ type ComboboxBaseProps<
 
 export type ComboboxProps<
   TItem = unknown,
-  TId extends ComboboxId = InferId<TItem>,
+  TId extends ItemId = InferItemId<TItem>,
 > =
   | (ComboboxBaseProps<TItem, TId> & {
       multiple?: false;
@@ -881,7 +847,7 @@ export type ComboboxProps<
  */
 export function Combobox<
   TItem = unknown,
-  TId extends ComboboxId = InferId<TItem>,
+  TId extends ItemId = InferItemId<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

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

@@ -424,6 +424,24 @@ describe("Select controlled value (id-first)", () => {
     expect(onChange.mock.calls[0][1]).toEqual(numeric[0]);
   });
 
+  it("returns a numeric id as a number without a custom getId", async () => {
+    const numeric = [
+      { id: 1, name: "Aumentar retención" },
+      { id: 2, name: "Reducir churn" },
+    ];
+    const onChange = vi.fn();
+    render(<Select items={numeric} defaultOpen onValueChange={onChange} />);
+
+    await userEvent.click(
+      screen.getByRole("option", { name: "Aumentar retención" }),
+    );
+
+    // defaultGetId preserves the native id type — number stays a number,
+    // not a stringified "1".
+    expect(onChange.mock.calls[0][0]).toBe(1);
+    expect(typeof onChange.mock.calls[0][0]).toBe("number");
+  });
+
   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]} />);

package/src/components/select/select.tsx

@@ -10,6 +10,12 @@ import {
 } from "lucide-react";
 import * as React from "react";
 import { cn } from "../../lib";
+import {
+  defaultGetId,
+  defaultGetLabel,
+  type InferItemId,
+  type ItemId,
+} from "../../utils/internal";
 import { inputBaseClasses } from "../input";
 
 // ─── Primitives ───────────────────────────────────────────────────────────────
@@ -266,54 +272,13 @@ export function SelectLabel({
 
 // ─── Composite ────────────────────────────────────────────────────────────────
 
-function defaultGetLabel(item: unknown): string {
-  if (item == null) return "";
-  if (typeof item === "string" || typeof item === "number") return String(item);
-  if (typeof item === "object") {
-    const record = item as Record<string, unknown>;
-    if ("label" in record) return String(record.label);
-    if ("name" in record) return String(record.name);
-    if ("title" in record) return String(record.title);
-  }
-  return String(item);
-}
-
-function defaultGetId(item: unknown): string {
-  if (item == null) return "";
-  if (typeof item === "string" || typeof item === "number") return String(item);
-  if (typeof item === "object") {
-    const record = item as Record<string, unknown>;
-    if ("id" in record) return String(record.id);
-    if ("value" in record) return String(record.value);
-  }
-  return String(item);
-}
-
 function defaultGetDisabled(item: unknown): boolean {
   if (item != null && typeof item === "object" && "disabled" in item)
     return Boolean((item as Record<string, unknown>).disabled);
   return false;
 }
 
-/** 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<
+type SelectBaseProps<TItem, TId extends ItemId> = Omit<
   SelectPrimitive.Root.Props<string, false>,
   "children" | "onValueChange" | "value" | "defaultValue" | "items" | "multiple"
 > & {
@@ -340,7 +305,7 @@ type SelectBaseProps<TItem, TId extends SelectId> = Omit<
 
 export type SelectProps<
   TItem = unknown,
-  TId extends SelectId = InferId<TItem>,
+  TId extends ItemId = InferItemId<TItem>,
 > =
   | (SelectBaseProps<TItem, TId> & {
       multiple?: false;
@@ -379,9 +344,10 @@ export type SelectProps<
  * Use `SelectRoot` + primitives directly when you need full structural
  * control beyond what `className` + `classNames` slots offer.
  */
-export function Select<TItem = unknown, TId extends SelectId = InferId<TItem>>(
-  allProps: SelectProps<TItem, TId>,
-): React.ReactElement {
+export function Select<
+  TItem = unknown,
+  TId extends ItemId = InferItemId<TItem>,
+>(allProps: SelectProps<TItem, TId>): React.ReactElement {
   const {
     items,
     getLabel: getLabelProp,

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);
     };
 

package/src/utils/internal/index.ts

@@ -0,0 +1,2 @@
+export type { InferItemId, ItemId } from "./item";
+export { defaultGetId, defaultGetLabel } from "./item";

package/src/utils/internal/item.ts

@@ -0,0 +1,51 @@
+/** Identifier an item can be addressed by. */
+export type ItemId = 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.
+ */
+export type InferItemId<TItem> = TItem extends { id: infer I extends ItemId }
+  ? I
+  : TItem extends { value: infer V extends ItemId }
+    ? V
+    : TItem extends ItemId
+      ? TItem
+      : string;
+
+/**
+ * Resolves the display text for an item. Defaults to `item.label`, `item.name`,
+ * `item.title`, or the stringified primitive. Always returns a string — labels
+ * are display text.
+ */
+export function defaultGetLabel(item: unknown): string {
+  if (item == null) return "";
+  if (typeof item === "string" || typeof item === "number") return String(item);
+  if (typeof item === "object") {
+    const record = item as Record<string, unknown>;
+    if ("label" in record) return String(record.label);
+    if ("name" in record) return String(record.name);
+    if ("title" in record) return String(record.title);
+  }
+  return String(item);
+}
+
+/**
+ * Resolves the id for an item, preserving its native type. The internal Base UI
+ * layer keys options by string (callers wrap this in `String(...)`), so keeping
+ * the raw type here lets `onValueChange` hand back a numeric id as a number, not
+ * a string. Defaults to `item.id`, `item.value`, or the stringified primitive.
+ */
+export function defaultGetId(item: unknown): ItemId {
+  if (item == null) return "";
+  if (typeof item === "string" || typeof item === "number") return item;
+  if (typeof item === "object") {
+    const record = item as Record<string, unknown>;
+    if ("id" in record) return record.id as ItemId;
+    if ("value" in record) return record.value as ItemId;
+  }
+  return String(item);
+}