From fda894ab42fe25bda327c840a040d11f93092f8b Mon Sep 17 00:00:00 2001
From: Rohan Chakraborty <irohan1999@gmail.com>
Date: Mon, 19 Oct 2026 00:28:06 +0530
Subject: [PATCH 1/3] feat: pass a details object to every change callback

---
 .../skills/apsara/references/composition.md   |  2 +
 .../src/content/docs/(overview)/upgrading.mdx | 45 +++++++++++++
 .../docs/ai-elements/chat-panel/props.ts      |  5 +-
 .../docs/ai-elements/prompt-input/props.ts    |  5 +-
 .../docs/ai-elements/reasoning/props.ts       |  5 +-
 .../docs/components/accordion/props.ts        |  7 +-
 .../docs/components/code-block/props.ts       |  5 +-
 .../docs/components/color-picker/index.mdx    |  2 +-
 .../docs/components/color-picker/props.ts     | 11 +++-
 .../content/docs/components/combobox/props.ts | 14 ++--
 .../docs/components/context-menu/props.ts     | 10 ++-
 .../content/docs/components/editor/props.ts   | 10 ++-
 .../docs/components/filter-chip/index.mdx     |  2 +-
 .../docs/components/filter-chip/props.ts      |  4 +-
 .../src/content/docs/components/menu/props.ts | 10 ++-
 .../content/docs/components/select/props.ts   | 12 ++++
 .../content/docs/components/sidebar/props.ts  | 10 ++-
 .../docs/components/textarea/index.mdx        |  2 +-
 .../content/docs/components/textarea/props.ts |  4 +-
 apps/www/src/content/docs/dataview/props.ts   |  5 +-
 .../accordion/__tests__/accordion.test.tsx    | 11 ++++
 .../components/accordion/accordion-root.tsx   | 27 ++++++--
 .../chat-panel/__tests__/chat-panel.test.tsx  |  7 +-
 .../chat-panel/chat-panel-context.tsx         | 10 +--
 .../chat-panel/chat-panel-parts.tsx           |  4 +-
 .../components/chat-panel/chat-panel-root.tsx | 27 ++++++--
 .../chat-panel/chat-panel-trigger.tsx         |  2 +-
 .../code-block/__tests__/code-block.test.tsx  |  7 +-
 .../components/code-block/code-block-misc.tsx |  2 +-
 .../components/code-block/code-block-root.tsx | 26 ++++++--
 .../__tests__/color-picker.test.tsx           | 12 +++-
 .../color-picker/color-picker-alpha.tsx       |  4 +-
 .../color-picker/color-picker-area.tsx        | 47 ++++++++++----
 .../color-picker/color-picker-hue.tsx         | 13 ++--
 .../color-picker/color-picker-input.tsx       | 10 +--
 .../color-picker/color-picker-root.tsx        | 27 ++++++--
 .../combobox/__tests__/combobox.test.tsx      | 33 +++++++---
 .../components/combobox/combobox-input.tsx    |  7 +-
 .../components/combobox/combobox-root.tsx     | 28 ++++++--
 .../context-menu/context-menu-content.tsx     |  2 +-
 .../context-menu/context-menu-root.tsx        | 41 +++++++++---
 .../data-view/__tests__/data-view.test.tsx    | 25 +++++++
 .../data-view/components/view-switcher.tsx    |  8 ++-
 .../react/components/data-view/data-view.tsx  |  9 ++-
 .../components/data-view/data-view.types.tsx  |  9 ++-
 .../editor/core/mention-registry.ts           |  3 +-
 .../editor/core/use-suggestion-menu.ts        | 17 +++--
 .../components/editor/editor-mentions.tsx     |  7 +-
 .../components/editor/editor-slash-menu.tsx   |  7 +-
 .../__tests__/filter-chip.test.tsx            | 48 ++++++++++----
 .../components/filter-chip/filter-chip.tsx    | 65 +++++++++++++++----
 .../components/menu/__tests__/menu.test.tsx   | 10 ++-
 .../react/components/menu/menu-content.tsx    |  2 +-
 packages/react/components/menu/menu-root.tsx  | 46 ++++++++++---
 .../__tests__/prompt-input-mentions.test.tsx  |  7 +-
 .../prompt-input/prompt-input-mentions.tsx    |  3 +-
 .../reasoning/__tests__/reasoning.test.tsx    | 28 ++++++--
 .../react/components/reasoning/reasoning.tsx  | 21 ++++--
 .../select/__tests__/select.test.tsx          | 32 +++++++--
 .../react/components/select/select-root.tsx   | 35 +++++++---
 .../sidebar/__tests__/sidebar.test.tsx        | 25 ++++---
 .../components/sidebar/sidebar-group.tsx      | 12 +++-
 .../react/components/sidebar/sidebar-root.tsx | 24 +++++--
 .../components/sidebar/sidebar-trigger.tsx    |  3 +-
 .../text-area/__tests__/text-area.test.tsx    |  6 +-
 .../react/components/text-area/text-area.tsx  | 10 ++-
 packages/react/shared/change-details.ts       | 30 +++++++++
 67 files changed, 786 insertions(+), 223 deletions(-)
 create mode 100644 packages/react/shared/change-details.ts

diff --git a/.agents/skills/apsara/references/composition.md b/.agents/skills/apsara/references/composition.md
index c6c679642..82ed00651 100644
--- a/.agents/skills/apsara/references/composition.md
+++ b/.agents/skills/apsara/references/composition.md
@@ -65,6 +65,8 @@ const [open, setOpen] = useState(false);
 </Dialog>
 ```
 
+Change callbacks (`onValueChange`, `onOpenChange`, `onInputValueChange`, and the like) take the new value first and a details object second: Base UI's `eventDetails` on components that wrap Base UI, or `details` with the same `reason` and `event` on components that own their state. Component data is a field of that object, for example `details.mode` on `ColorPicker` and `details.operation` on `FilterChip`.
+
 Several overlay roots (`Dialog`, `Menu`, `Popover`, `Tooltip`) also expose `createHandle` for advanced imperative open/close from outside the subtree — use only when a trigger can't live in the same tree.
 
 ## Select
diff --git a/apps/www/src/content/docs/(overview)/upgrading.mdx b/apps/www/src/content/docs/(overview)/upgrading.mdx
index 82f756aad..efbd3ec3f 100644
--- a/apps/www/src/content/docs/(overview)/upgrading.mdx
+++ b/apps/www/src/content/docs/(overview)/upgrading.mdx
@@ -7,6 +7,51 @@ One section per release, newest first, with only the changes that need action
 from you. The full record of every release, features and fixes included, is
 on [GitHub releases](https://github.com/raystack/apsara/releases).
 
+## Unreleased: change callbacks get a details object
+
+Every change callback now passes a second argument after the value. A
+component that wraps Base UI passes Base UI's `eventDetails`. A component that
+keeps its own state passes a `details` object with the same `reason` and
+`event` fields, plus any field of its own.
+
+### 1. Update the three callbacks whose second argument changes
+
+| `onValueChange` | Before | After |
+|---|---|---|
+| `TextArea` | `(value, event)` | `(value, eventDetails)` |
+| `ColorPicker` | `(value, mode)` | `(value, details)` |
+| `FilterChip` | `(value, operation)` | `(value, details)` |
+
+TextArea's `event` was the React `ChangeEvent`. `eventDetails.event` is the
+native event. ColorPicker's mode is `details.mode`, and FilterChip's operation
+is `details.operation`.
+
+```tsx
+// Before
+<ColorPicker onValueChange={(value, mode) => save(value, mode)} />
+<FilterChip onValueChange={(value, operation) => apply(value, operation)} />
+<TextArea onValueChange={(value, event) => track(event.nativeEvent)} />
+
+// After
+<ColorPicker onValueChange={(value, details) => save(value, details.mode)} />
+<FilterChip onValueChange={(value, details) => apply(value, details.operation)} />
+<TextArea onValueChange={(value, eventDetails) => track(eventDetails.event)} />
+```
+
+### 2. Check functions that take a second parameter
+
+These callbacks gain the second argument. Code that reads only the value keeps
+working. If you pass a function that takes a second parameter, check that it
+expects the details object.
+
+- Base UI `eventDetails`: Accordion `onValueChange`, Select `onValueChange`
+  and `onOpenChange`, Combobox `onValueChange` and `onInputValueChange`, Menu
+  and ContextMenu `onInputValueChange`, Sidebar.Group and Reasoning
+  `onOpenChange`.
+- `details`: Sidebar `onOpenChange`, CodeBlock `onCollapseChange`, ChatPanel
+  `onModeChange`, DataView `onViewChange`, and `onOpenChange` on
+  Editor.SlashMenu, Editor.Mentions and PromptInput.Mentions.
+
 ## Unreleased: date filters compare whole days
 
 `DataView`, `DataTable` and `FilterChip` read and compare dates as calendar
diff --git a/apps/www/src/content/docs/ai-elements/chat-panel/props.ts b/apps/www/src/content/docs/ai-elements/chat-panel/props.ts
index 4d98ca0b0..b4171f108 100644
--- a/apps/www/src/content/docs/ai-elements/chat-panel/props.ts
+++ b/apps/www/src/content/docs/ai-elements/chat-panel/props.ts
@@ -21,7 +21,10 @@ export interface ChatPanelProps {
   defaultMode?: 'docked' | 'floating' | 'minimized';
 
   /** Called when the mode changes. */
-  onModeChange?: (mode: 'docked' | 'floating' | 'minimized') => void;
+  onModeChange?: (
+    mode: 'docked' | 'floating' | 'minimized',
+    details: { reason: 'trigger-press'; event: Event }
+  ) => void;
 
   /**
    * Which edge the panel docks to; also picks the corner used by the
diff --git a/apps/www/src/content/docs/ai-elements/prompt-input/props.ts b/apps/www/src/content/docs/ai-elements/prompt-input/props.ts
index c88e7a582..e2b3eed8c 100644
--- a/apps/www/src/content/docs/ai-elements/prompt-input/props.ts
+++ b/apps/www/src/content/docs/ai-elements/prompt-input/props.ts
@@ -199,7 +199,10 @@ export interface PromptInputMentionsProps {
   ) => Promise<PromptInputMentionItem[]>;
 
   /** Called when the menu opens or closes. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (
+    open: boolean,
+    details: { reason: 'none'; event: Event }
+  ) => void;
 
   /** Shown when nothing matches. @defaultValue "No results" */
   emptyMessage?: React.ReactNode;
diff --git a/apps/www/src/content/docs/ai-elements/reasoning/props.ts b/apps/www/src/content/docs/ai-elements/reasoning/props.ts
index 8ba538410..bc651a412 100644
--- a/apps/www/src/content/docs/ai-elements/reasoning/props.ts
+++ b/apps/www/src/content/docs/ai-elements/reasoning/props.ts
@@ -23,7 +23,10 @@ export interface ReasoningProps {
   defaultOpen?: boolean;
 
   /** Called when the panel is opened or closed. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (
+    open: boolean,
+    eventDetails: { reason: 'trigger-press' | 'none'; event: Event }
+  ) => void;
 
   /** Custom CSS class names. */
   className?: string;
diff --git a/apps/www/src/content/docs/components/accordion/props.ts b/apps/www/src/content/docs/components/accordion/props.ts
index cf1ee96fc..720017fd3 100644
--- a/apps/www/src/content/docs/components/accordion/props.ts
+++ b/apps/www/src/content/docs/components/accordion/props.ts
@@ -22,9 +22,12 @@ export interface AccordionRootProps<Value = string> {
   /**
    * Event handler called when the value changes. In single mode it receives `''` when every item closes.
    *
-   * @remarks `(value: Value | '') => void` in single mode, `(value: Value[]) => void` with `multiple`
+   * @remarks `(value: Value | '', eventDetails) => void` in single mode, `(value: Value[], eventDetails) => void` with `multiple`
    */
-  onValueChange?: (value: Value | '' | Value[]) => void;
+  onValueChange?: (
+    value: Value | '' | Value[],
+    eventDetails: { reason: string; event: Event }
+  ) => void;
 
   /**
    * Whether the accordion is disabled
diff --git a/apps/www/src/content/docs/components/code-block/props.ts b/apps/www/src/content/docs/components/code-block/props.ts
index 397d4996d..a891e0fb9 100644
--- a/apps/www/src/content/docs/components/code-block/props.ts
+++ b/apps/www/src/content/docs/components/code-block/props.ts
@@ -43,7 +43,10 @@ export interface CodeBlockProps {
   /**
    * Callback when collapse state changes
    */
-  onCollapseChange?: (collapsed: boolean) => void;
+  onCollapseChange?: (
+    collapsed: boolean,
+    details: { reason: 'trigger-press'; event: Event }
+  ) => void;
 
   /**
    * The code content to display
diff --git a/apps/www/src/content/docs/components/color-picker/index.mdx b/apps/www/src/content/docs/components/color-picker/index.mdx
index e2eaed7c8..443560bda 100644
--- a/apps/www/src/content/docs/components/color-picker/index.mdx
+++ b/apps/www/src/content/docs/components/color-picker/index.mdx
@@ -36,7 +36,7 @@ The picker is composed from an area pad, sliders and an input, so you can drop i
 
 ### Basic usage
 
-An uncontrolled picker. Pass `defaultValue` for the starting color and read changes from `onValueChange`.
+An uncontrolled picker. Pass `defaultValue` for the starting color and read changes from `onValueChange`. Its second argument is a `details` object: `details.mode` is the mode of the emitted string, and `details.reason` tells which control changed it.
 
 <Demo data={basicDemo} />
 
diff --git a/apps/www/src/content/docs/components/color-picker/props.ts b/apps/www/src/content/docs/components/color-picker/props.ts
index f67fdcc4b..67cef1bc8 100644
--- a/apps/www/src/content/docs/components/color-picker/props.ts
+++ b/apps/www/src/content/docs/components/color-picker/props.ts
@@ -12,9 +12,16 @@ export interface ColorPickerProps {
    */
   defaultValue?: string;
   /**
-   * Callback fired when the color value changes.
+   * Callback fired when the color value changes. `details.mode` is the active mode.
    */
-  onValueChange?: (value: string, mode: string) => void;
+  onValueChange?: (
+    value: string,
+    details: {
+      reason: 'track-press' | 'drag' | 'keyboard' | 'input-change' | 'none';
+      event: Event;
+      mode: 'hex' | 'rgb' | 'hsl' | 'oklch';
+    }
+  ) => void;
   /**
    * The initial color mode (hex, rgb, hsl, oklch).
    * @default 'hex'
diff --git a/apps/www/src/content/docs/components/combobox/props.ts b/apps/www/src/content/docs/components/combobox/props.ts
index 6908fd723..aa26f0e2d 100644
--- a/apps/www/src/content/docs/components/combobox/props.ts
+++ b/apps/www/src/content/docs/components/combobox/props.ts
@@ -18,10 +18,13 @@ export interface ComboboxRootProps {
   defaultValue?: string | string[];
 
   /** Callback fired when the value changes.
-   * For single selection: (value: string) => void
-   * For multiple selection: (value: string[]) => void
+   * For single selection: (value: string, eventDetails) => void
+   * For multiple selection: (value: string[], eventDetails) => void
    */
-  onValueChange?: (value: string | string[]) => void;
+  onValueChange?: (
+    value: string | string[],
+    eventDetails: { reason: string; event: Event }
+  ) => void;
 
   /** The controlled input value of the combobox. */
   inputValue?: string;
@@ -30,7 +33,10 @@ export interface ComboboxRootProps {
   defaultInputValue?: string;
 
   /** Callback fired when the input value changes. */
-  onInputValueChange?: (inputValue: string) => void;
+  onInputValueChange?: (
+    inputValue: string,
+    eventDetails: { reason: string; event: Event }
+  ) => void;
 
   /** Whether the combobox is open.
    * @default false
diff --git a/apps/www/src/content/docs/components/context-menu/props.ts b/apps/www/src/content/docs/components/context-menu/props.ts
index e5ac87ed7..fffeee23f 100644
--- a/apps/www/src/content/docs/components/context-menu/props.ts
+++ b/apps/www/src/content/docs/components/context-menu/props.ts
@@ -20,7 +20,10 @@ export interface ContextMenuRootProps {
   defaultInputValue?: string;
 
   /** Callback fired when the search input value changes */
-  onInputValueChange?: (value: string) => void;
+  onInputValueChange?: (
+    value: string,
+    eventDetails: { reason: string; event: Event }
+  ) => void;
 
   /** Control the open state of the menu */
   open?: boolean;
@@ -155,7 +158,10 @@ export interface ContextMenuSubMenuProps {
   defaultInputValue?: string;
 
   /** Callback fired when the search input value changes */
-  onInputValueChange?: (value: string) => void;
+  onInputValueChange?: (
+    value: string,
+    eventDetails: { reason: string; event: Event }
+  ) => void;
 
   /** Control the open state of the submenu */
   open?: boolean;
diff --git a/apps/www/src/content/docs/components/editor/props.ts b/apps/www/src/content/docs/components/editor/props.ts
index ab020f449..b5ae796aa 100644
--- a/apps/www/src/content/docs/components/editor/props.ts
+++ b/apps/www/src/content/docs/components/editor/props.ts
@@ -207,7 +207,10 @@ export interface EditorSlashMenuProps {
   emptyMessage?: React.ReactNode;
 
   /** Observes the menu's open state. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (
+    open: boolean,
+    details: { reason: 'none'; event: Event }
+  ) => void;
 }
 
 export interface EditorMentionsProps {
@@ -250,7 +253,10 @@ export interface EditorMentionsProps {
   loadingRowCount?: number;
 
   /** Observes the menu's open state. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (
+    open: boolean,
+    details: { reason: 'none'; event: Event }
+  ) => void;
 }
 
 export interface EditorMentionItem {
diff --git a/apps/www/src/content/docs/components/filter-chip/index.mdx b/apps/www/src/content/docs/components/filter-chip/index.mdx
index 7558ac6eb..4ee374b8e 100644
--- a/apps/www/src/content/docs/components/filter-chip/index.mdx
+++ b/apps/www/src/content/docs/components/filter-chip/index.mdx
@@ -66,7 +66,7 @@ FilterChip supports custom filter operations through the `operations` prop. When
 
 ### Controlled
 
-Pass `value` with `onValueChange` to own the filter. Do this when the chip drives a query and the value has to survive a refetch or a shared URL.
+Pass `value` with `onValueChange` to own the filter. Do this when the chip drives a query and the value has to survive a refetch or a shared URL. `onValueChange` receives the value and a `details` object, and `details.operation` is the active operation.
 
 <Demo data={controlledDemo} />
 
diff --git a/apps/www/src/content/docs/components/filter-chip/props.ts b/apps/www/src/content/docs/components/filter-chip/props.ts
index 161f1f715..99c6cb2b9 100644
--- a/apps/www/src/content/docs/components/filter-chip/props.ts
+++ b/apps/www/src/content/docs/components/filter-chip/props.ts
@@ -26,7 +26,7 @@ export interface FilterChipProps {
   /** Optional array of operations for the type of filter operation */
   operations?: { label: string; value: string }[];
 
-  /** Callback when the filter value changes; receives the value and the active
+  /** Callback when the filter value changes. `details.operation` is the active
    * operation. For `select` and `multiselect`, the value is the picked
    * option's `value`, with its type kept. For `number`, non-numeric input is
    * rejected and never reported, and the value arrives as a `number`, except
@@ -34,7 +34,7 @@ export interface FilterChipProps {
    * reported as-is so the field stays editable. */
   onValueChange?: (
     value: string | number | boolean | Array<string | number | boolean> | Date,
-    operation: string
+    details: { reason: string; event: Event; operation: string }
   ) => void;
 
   /** Callback when the filter operation changes */
diff --git a/apps/www/src/content/docs/components/menu/props.ts b/apps/www/src/content/docs/components/menu/props.ts
index 632c75f8a..a7cf513cf 100644
--- a/apps/www/src/content/docs/components/menu/props.ts
+++ b/apps/www/src/content/docs/components/menu/props.ts
@@ -20,7 +20,10 @@ export interface MenuRootProps {
   defaultInputValue?: string;
 
   /** Callback fired when the search input value changes */
-  onInputValueChange?: (value: string) => void;
+  onInputValueChange?: (
+    value: string,
+    eventDetails: { reason: string; event: Event }
+  ) => void;
 
   /** Control the open state of the menu */
   open?: boolean;
@@ -157,7 +160,10 @@ export interface MenuSubMenuProps {
   defaultInputValue?: string;
 
   /** Callback fired when the search input value changes */
-  onInputValueChange?: (value: string) => void;
+  onInputValueChange?: (
+    value: string,
+    eventDetails: { reason: string; event: Event }
+  ) => void;
 
   /** Control the open state of the submenu */
   open?: boolean;
diff --git a/apps/www/src/content/docs/components/select/props.ts b/apps/www/src/content/docs/components/select/props.ts
index 80ddce754..75fe36939 100644
--- a/apps/www/src/content/docs/components/select/props.ts
+++ b/apps/www/src/content/docs/components/select/props.ts
@@ -17,6 +17,18 @@ export interface SelectRootProps {
    */
   autocompleteMode?: 'auto' | 'manual';
 
+  /** Callback fired when the value changes. The value is a `string[]` with `multiple`. */
+  onValueChange?: (
+    value: string | string[],
+    eventDetails: { reason: string; event: Event }
+  ) => void;
+
+  /** Callback fired when the popup opens or closes. */
+  onOpenChange?: (
+    open: boolean,
+    eventDetails: { reason: string; event: Event }
+  ) => void;
+
   /** Current search value for autocomplete */
   searchValue?: string;
 
diff --git a/apps/www/src/content/docs/components/sidebar/props.ts b/apps/www/src/content/docs/components/sidebar/props.ts
index 9c8fe01b8..591246ecf 100644
--- a/apps/www/src/content/docs/components/sidebar/props.ts
+++ b/apps/www/src/content/docs/components/sidebar/props.ts
@@ -5,7 +5,10 @@ export interface SidebarRootProps {
   open?: boolean;
 
   /** Callback when expanded/collapsed state changes. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (
+    open: boolean,
+    details: { reason: 'trigger-press' | 'none'; event: Event }
+  ) => void;
 
   /** Default expanded/collapsed state.
    * @default true
@@ -80,7 +83,10 @@ export interface SidebarGroupProps {
   defaultOpen?: boolean;
 
   /** Callback when the group's expanded/collapsed state changes. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (
+    open: boolean,
+    eventDetails: { reason: string; event: Event }
+  ) => void;
 
   /** Optional ReactNode for group icon. */
   leadingIcon?: ReactNode;
diff --git a/apps/www/src/content/docs/components/textarea/index.mdx b/apps/www/src/content/docs/components/textarea/index.mdx
index 4f013617e..6b36770cc 100644
--- a/apps/www/src/content/docs/components/textarea/index.mdx
+++ b/apps/www/src/content/docs/components/textarea/index.mdx
@@ -79,7 +79,7 @@ Pass `value` with `onChange` to own the state, the same contract as a native tex
 
 ### Using `onValueChange`
 
-`onValueChange` is a convenience callback that fires alongside `onChange` and receives just the new string value. Use it when you don't need the full React change event.
+`onValueChange` fires alongside `onChange` with the new string value and an `eventDetails` object, as on `Input`. `eventDetails.event` is the native input event. Use it when you don't need the React change event.
 
 <Demo data={onValueChangeDemo} />
 
diff --git a/apps/www/src/content/docs/components/textarea/props.ts b/apps/www/src/content/docs/components/textarea/props.ts
index 90b2bcb32..49d4d8855 100644
--- a/apps/www/src/content/docs/components/textarea/props.ts
+++ b/apps/www/src/content/docs/components/textarea/props.ts
@@ -31,11 +31,11 @@ export interface TextAreaProps {
 
   /**
    * Convenience callback fired alongside `onChange` with the new string value.
-   * Use this when you only need the value rather than the full event.
+   * `eventDetails.event` is the native input event.
    */
   onValueChange?: (
     value: string,
-    event: React.ChangeEvent<HTMLTextAreaElement>
+    eventDetails: { reason: 'none'; event: Event }
   ) => void;
 
   /** Additional CSS class names. */
diff --git a/apps/www/src/content/docs/dataview/props.ts b/apps/www/src/content/docs/dataview/props.ts
index 39513c39b..4a5374c76 100644
--- a/apps/www/src/content/docs/dataview/props.ts
+++ b/apps/www/src/content/docs/dataview/props.ts
@@ -67,7 +67,10 @@ export interface DataViewProps {
   view?: string;
 
   /** Called when the active view changes. */
-  onViewChange?: (view: string) => void;
+  onViewChange?: (
+    view: string,
+    details: { reason: string; event: Event }
+  ) => void;
 
   /**
    * Optional local resolvers for non-accessor `group_by` keys.
diff --git a/packages/react/components/accordion/__tests__/accordion.test.tsx b/packages/react/components/accordion/__tests__/accordion.test.tsx
index 065c24d6a..74340c25b 100644
--- a/packages/react/components/accordion/__tests__/accordion.test.tsx
+++ b/packages/react/components/accordion/__tests__/accordion.test.tsx
@@ -91,6 +91,17 @@ describe('Accordion', () => {
       expect(trigger).toHaveAttribute('aria-expanded', 'false');
     });
 
+    it('passes eventDetails to onValueChange', () => {
+      const onValueChange = vi.fn();
+      render(<BasicAccordion onValueChange={onValueChange} />);
+
+      fireEvent.click(screen.getByRole('button', { name: ITEM_1_TEXT }));
+      expect(onValueChange).toHaveBeenCalledWith(
+        'item-1',
+        expect.objectContaining({ reason: 'trigger-press' })
+      );
+    });
+
     it('supports keyboard navigation', async () => {
       const user = userEvent.setup();
       render(<BasicAccordion />);
diff --git a/packages/react/components/accordion/accordion-root.tsx b/packages/react/components/accordion/accordion-root.tsx
index 85d4d475d..82cf760be 100644
--- a/packages/react/components/accordion/accordion-root.tsx
+++ b/packages/react/components/accordion/accordion-root.tsx
@@ -18,14 +18,20 @@ type AccordionSingleProps<Value> = AccordionBaseProps<Value> & {
   multiple?: false;
   value?: SingleValue<Value>;
   defaultValue?: NotArray<Value>;
-  onValueChange?: (value: Value | '') => void;
+  onValueChange?: (
+    value: Value | '',
+    eventDetails: AccordionPrimitive.Root.ChangeEventDetails
+  ) => void;
 };
 
 type AccordionMultipleProps<Value> = AccordionBaseProps<Value> & {
   multiple: true;
   value?: Value[];
   defaultValue?: Value[];
-  onValueChange?: (value: Value[]) => void;
+  onValueChange?: (
+    value: Value[],
+    eventDetails: AccordionPrimitive.Root.ChangeEventDetails
+  ) => void;
 };
 
 export type AccordionRootProps<Value = string> =
@@ -65,13 +71,20 @@ export function AccordionRoot<Value = string>({
   onValueChange,
   ...rest
 }: AccordionRootProps<Value>) {
-  const handleValueChange = (newValue: Value[]) => {
-    if (!onValueChange) return;
-
+  const handleValueChange = (
+    newValue: Value[],
+    eventDetails: AccordionPrimitive.Root.ChangeEventDetails
+  ) => {
     if (multiple) {
-      (onValueChange as (v: Value[]) => void)(newValue);
+      (onValueChange as AccordionMultipleProps<Value>['onValueChange'])?.(
+        newValue,
+        eventDetails
+      );
     } else {
-      (onValueChange as (v: Value | '') => void)(newValue[0] ?? '');
+      (onValueChange as AccordionSingleProps<Value>['onValueChange'])?.(
+        newValue[0] ?? '',
+        eventDetails
+      );
     }
   };
 
diff --git a/packages/react/components/chat-panel/__tests__/chat-panel.test.tsx b/packages/react/components/chat-panel/__tests__/chat-panel.test.tsx
index dbbf1d86f..c46b6c9c3 100644
--- a/packages/react/components/chat-panel/__tests__/chat-panel.test.tsx
+++ b/packages/react/components/chat-panel/__tests__/chat-panel.test.tsx
@@ -99,7 +99,10 @@ describe('ChatPanel', () => {
         screen.getByRole('button', { name: 'Minimize chat panel' })
       );
 
-      expect(onModeChange).toHaveBeenCalledWith('minimized');
+      expect(onModeChange).toHaveBeenCalledWith(
+        'minimized',
+        expect.objectContaining({ reason: 'trigger-press' })
+      );
       expect(screen.getByTestId('panel')).toHaveAttribute(
         'data-mode',
         'minimized'
@@ -231,7 +234,7 @@ describe('ChatPanel', () => {
       await user.click(
         screen.getByRole('button', { name: 'Minimize chat panel' })
       );
-      expect(onModeChange).toHaveBeenCalledWith('minimized');
+      expect(onModeChange).toHaveBeenCalledWith('minimized', expect.anything());
       // The parent did not update the prop, so the panel stays docked.
       expect(screen.getByTestId('panel')).toHaveAttribute(
         'data-mode',
diff --git a/packages/react/components/chat-panel/chat-panel-context.tsx b/packages/react/components/chat-panel/chat-panel-context.tsx
index 4e9419452..8a345f971 100644
--- a/packages/react/components/chat-panel/chat-panel-context.tsx
+++ b/packages/react/components/chat-panel/chat-panel-context.tsx
@@ -2,17 +2,19 @@
 
 import type { DraggableSyntheticListeners } from '@dnd-kit/core';
 import { createContext, RefObject, useContext } from 'react';
+import type { ChangeDetails } from '~/shared/change-details';
 
 export type ChatPanelMode = 'docked' | 'floating' | 'minimized';
 export type ChatPanelSide = 'left' | 'right';
+export type ChatPanelModeChangeDetails = ChangeDetails<'trigger-press'>;
 
 export interface ChatPanelContextValue {
   mode: ChatPanelMode;
   side: ChatPanelSide;
-  setMode: (mode: ChatPanelMode) => void;
-  minimize: () => void;
-  restore: () => void;
-  toggleFloating: () => void;
+  setMode: (mode: ChatPanelMode, details: ChatPanelModeChangeDetails) => void;
+  minimize: (event: Event) => void;
+  restore: (event: Event) => void;
+  toggleFloating: (event: Event) => void;
   /** dnd-kit activator ref for the drag handle (the header). */
   dragHandleRef: (element: HTMLElement | null) => void;
   /** dnd-kit activator listeners; undefined while dragging is disabled. */
diff --git a/packages/react/components/chat-panel/chat-panel-parts.tsx b/packages/react/components/chat-panel/chat-panel-parts.tsx
index 0bfb6ebb7..92c577952 100644
--- a/packages/react/components/chat-panel/chat-panel-parts.tsx
+++ b/packages/react/components/chat-panel/chat-panel-parts.tsx
@@ -100,7 +100,7 @@ export function ChatPanelMinimizeTrigger({
   const handleClick = (event: BaseUIEvent<MouseEvent<HTMLButtonElement>>) => {
     onClick?.(event);
     if (event.defaultPrevented) return;
-    minimize();
+    minimize(event.nativeEvent);
   };
 
   return (
@@ -144,7 +144,7 @@ export function ChatPanelExpandTrigger({
   const handleClick = (event: BaseUIEvent<MouseEvent<HTMLButtonElement>>) => {
     onClick?.(event);
     if (event.defaultPrevented) return;
-    toggleFloating();
+    toggleFloating(event.nativeEvent);
   };
 
   const resolvedChildren =
diff --git a/packages/react/components/chat-panel/chat-panel-root.tsx b/packages/react/components/chat-panel/chat-panel-root.tsx
index ec2466ed9..062b8df05 100644
--- a/packages/react/components/chat-panel/chat-panel-root.tsx
+++ b/packages/react/components/chat-panel/chat-panel-root.tsx
@@ -26,11 +26,13 @@ import {
   useRef,
   useState
 } from 'react';
+import { createChangeDetails } from '~/shared/change-details';
 import styles from './chat-panel.module.css';
 import {
   ChatPanelContext,
   type ChatPanelContextValue,
   type ChatPanelMode,
+  type ChatPanelModeChangeDetails,
   type ChatPanelSide
 } from './chat-panel-context';
 
@@ -196,7 +198,10 @@ export interface ChatPanelRootProps extends ComponentProps<'aside'> {
    */
   defaultMode?: ChatPanelMode;
   /** Called when the mode changes. */
-  onModeChange?: (mode: ChatPanelMode) => void;
+  onModeChange?: (
+    mode: ChatPanelMode,
+    details: ChatPanelModeChangeDetails
+  ) => void;
   /**
    * Which edge the panel docks to; also picks the corner used by the
    * floating default position and the minimized trigger.
@@ -345,7 +350,7 @@ export function ChatPanelRoot({
   dragBoundaryRef.current = dragBoundary;
 
   const setMode = useCallback(
-    (next: ChatPanelMode) => {
+    (next: ChatPanelMode, details: ChatPanelModeChangeDetails) => {
       if (next === modeRef.current) return;
       if (modeRef.current !== 'minimized') {
         previousModeRef.current = modeRef.current as Exclude<
@@ -354,7 +359,7 @@ export function ChatPanelRoot({
         >;
       }
       setModeUnwrapped(next);
-      onModeChangeRef.current?.(next);
+      onModeChangeRef.current?.(next, details);
     },
     [setModeUnwrapped]
   );
@@ -685,10 +690,18 @@ export function ChatPanelRoot({
       mode,
       side,
       setMode,
-      minimize: () => setMode('minimized'),
-      restore: () => setMode(previousModeRef.current),
-      toggleFloating: () =>
-        setMode(modeRef.current === 'floating' ? 'docked' : 'floating'),
+      minimize: (event: Event) =>
+        setMode('minimized', createChangeDetails('trigger-press', event)),
+      restore: (event: Event) =>
+        setMode(
+          previousModeRef.current,
+          createChangeDetails('trigger-press', event)
+        ),
+      toggleFloating: (event: Event) =>
+        setMode(
+          modeRef.current === 'floating' ? 'docked' : 'floating',
+          createChangeDetails('trigger-press', event)
+        ),
       bubbleDraggableId,
       bubbleElementRef
     }),
diff --git a/packages/react/components/chat-panel/chat-panel-trigger.tsx b/packages/react/components/chat-panel/chat-panel-trigger.tsx
index 98edeb070..d34b03410 100644
--- a/packages/react/components/chat-panel/chat-panel-trigger.tsx
+++ b/packages/react/components/chat-panel/chat-panel-trigger.tsx
@@ -68,7 +68,7 @@ export function ChatPanelTrigger({
     }
     onClick?.(event);
     if (event.defaultPrevented) return;
-    restore();
+    restore(event.nativeEvent);
   };
 
   const handlePointerDown = (event: PointerEvent<HTMLButtonElement>) => {
diff --git a/packages/react/components/code-block/__tests__/code-block.test.tsx b/packages/react/components/code-block/__tests__/code-block.test.tsx
index ac739451d..1b390649f 100644
--- a/packages/react/components/code-block/__tests__/code-block.test.tsx
+++ b/packages/react/components/code-block/__tests__/code-block.test.tsx
@@ -237,7 +237,10 @@ describe('CodeBlock', () => {
       await user.click(screen.getByText('Hide Code'));
 
       expect(onCollapseChange).toHaveBeenCalledTimes(1);
-      expect(onCollapseChange).toHaveBeenCalledWith(true);
+      expect(onCollapseChange).toHaveBeenCalledWith(
+        true,
+        expect.objectContaining({ reason: 'trigger-press' })
+      );
       expect(screen.getByText('Hide Code')).toBeInTheDocument();
     });
 
@@ -257,7 +260,7 @@ describe('CodeBlock', () => {
       await user.click(screen.getByText('Show Code'));
 
       expect(onCollapseChange).toHaveBeenCalledTimes(1);
-      expect(onCollapseChange).toHaveBeenCalledWith(false);
+      expect(onCollapseChange).toHaveBeenCalledWith(false, expect.anything());
       expect(screen.getByText('Hide Code')).toBeInTheDocument();
     });
 
diff --git a/packages/react/components/code-block/code-block-misc.tsx b/packages/react/components/code-block/code-block-misc.tsx
index ef3c1bb96..b227063db 100644
--- a/packages/react/components/code-block/code-block-misc.tsx
+++ b/packages/react/components/code-block/code-block-misc.tsx
@@ -86,7 +86,7 @@ export function CodeBlockCollapseTrigger({
   return (
     <Button
       onClick={e => {
-        toggleCollapsed();
+        toggleCollapsed(e.nativeEvent);
         onClick?.(e);
       }}
       variant='text'
diff --git a/packages/react/components/code-block/code-block-root.tsx b/packages/react/components/code-block/code-block-root.tsx
index c0097d621..147476bc1 100644
--- a/packages/react/components/code-block/code-block-root.tsx
+++ b/packages/react/components/code-block/code-block-root.tsx
@@ -9,6 +9,10 @@ import {
   useContext,
   useState
 } from 'react';
+import {
+  type ChangeDetails,
+  createChangeDetails
+} from '~/shared/change-details';
 import styles from './code-block.module.css';
 
 interface CodeBlockCommonProps {
@@ -22,7 +26,7 @@ interface CodeBlockContextValue extends CodeBlockCommonProps {
   setValue: (value: string) => void;
   code?: string;
   setCode: (code: string) => void;
-  toggleCollapsed: () => void;
+  toggleCollapsed: (event: Event) => void;
 }
 
 const CodeBlockContext = createContext<CodeBlockContextValue | undefined>(
@@ -37,6 +41,8 @@ export const useCodeBlockContext = () => {
   return context;
 };
 
+export type CodeBlockCollapseChangeDetails = ChangeDetails<'trigger-press'>;
+
 export interface CodeBlockProps
   extends ComponentProps<'div'>,
     CodeBlockCommonProps {
@@ -44,7 +50,10 @@ export interface CodeBlockProps
   maxHeight?: string | number;
   onValueChange?: (value: string) => void;
   defaultCollapsed?: boolean;
-  onCollapseChange?: (value: boolean) => void;
+  onCollapseChange?: (
+    value: boolean,
+    details: CodeBlockCollapseChangeDetails
+  ) => void;
 }
 
 export const CodeBlockRoot = ({
@@ -83,11 +92,14 @@ export const CodeBlockRoot = ({
     [onValueChange, setValueUnwrapped]
   );
 
-  const toggleCollapsed = useCallback(() => {
-    const next = !collapsed;
-    setCollapsedUnwrapped(next);
-    onCollapseChange?.(next);
-  }, [collapsed, onCollapseChange, setCollapsedUnwrapped]);
+  const toggleCollapsed = useCallback(
+    (event: Event) => {
+      const next = !collapsed;
+      setCollapsedUnwrapped(next);
+      onCollapseChange?.(next, createChangeDetails('trigger-press', event));
+    },
+    [collapsed, onCollapseChange, setCollapsedUnwrapped]
+  );
 
   return (
     <CodeBlockContext
diff --git a/packages/react/components/color-picker/__tests__/color-picker.test.tsx b/packages/react/components/color-picker/__tests__/color-picker.test.tsx
index 1a836904f..6e87e31f0 100644
--- a/packages/react/components/color-picker/__tests__/color-picker.test.tsx
+++ b/packages/react/components/color-picker/__tests__/color-picker.test.tsx
@@ -164,11 +164,14 @@ describe('ColorPicker', () => {
       area.hasPointerCapture = vi.fn().mockReturnValue(true);
 
       fireEvent.pointerDown(area, { pointerId: 1, clientX: 0, clientY: 0 });
-      expect(onValueChange).toHaveBeenLastCalledWith('oklch(1 0 0)', 'oklch');
+      expect(onValueChange).toHaveBeenLastCalledWith(
+        'oklch(1 0 0)',
+        expect.objectContaining({ reason: 'track-press', mode: 'oklch' })
+      );
       fireEvent.pointerMove(area, { pointerId: 1, clientX: 50, clientY: 50 });
       expect(onValueChange).toHaveBeenLastCalledWith(
         'oklch(0.5 0.2 0)',
-        'oklch'
+        expect.objectContaining({ reason: 'drag', mode: 'oklch' })
       );
       expect(onPointerDown).toHaveBeenCalledTimes(1);
       expect(onPointerMove).toHaveBeenCalledTimes(1);
@@ -282,7 +285,10 @@ describe('ColorPicker', () => {
       // false means the keydown was default-prevented, so a form won't submit.
       expect(fireEvent.keyDown(input, { key: 'Enter' })).toBe(false);
 
-      expect(onValueChange).toHaveBeenCalledWith('#00FF00', 'hex');
+      expect(onValueChange).toHaveBeenCalledWith(
+        '#00FF00',
+        expect.objectContaining({ reason: 'input-change', mode: 'hex' })
+      );
       expect(input).toHaveValue('#00FF00');
     });
 
diff --git a/packages/react/components/color-picker/color-picker-alpha.tsx b/packages/react/components/color-picker/color-picker-alpha.tsx
index 435500341..02bf571ae 100644
--- a/packages/react/components/color-picker/color-picker-alpha.tsx
+++ b/packages/react/components/color-picker/color-picker-alpha.tsx
@@ -27,7 +27,9 @@ export const ColorPickerAlpha = ({
     <Slider.Root
       className={cx(styles.sliderRoot, className)}
       max={100}
-      onValueChange={value => setColor({ alpha: (value as number) / 100 })}
+      onValueChange={(value, { reason, event }) =>
+        setColor({ alpha: (value as number) / 100 }, reason, event)
+      }
       step={1}
       value={alpha * 100}
       thumbAlignment='edge'
diff --git a/packages/react/components/color-picker/color-picker-area.tsx b/packages/react/components/color-picker/color-picker-area.tsx
index 1dc7c4a3f..7bea3bb37 100644
--- a/packages/react/components/color-picker/color-picker-area.tsx
+++ b/packages/react/components/color-picker/color-picker-area.tsx
@@ -12,7 +12,10 @@ import {
   useRef
 } from 'react';
 import styles from './color-picker.module.css';
-import { useColorPicker } from './color-picker-root';
+import {
+  type ColorPickerChangeReason,
+  useColorPicker
+} from './color-picker-root';
 import {
   CHROMA_MAX,
   clamp01,
@@ -33,24 +36,36 @@ const STEP_LARGE = 0.1;
 
 export type ColorPickerAreaProps = ComponentProps<'div'>;
 
+type ApplyPosition = (
+  x: number,
+  y: number,
+  reason: ColorPickerChangeReason,
+  event: Event
+) => void;
+
 // Pointer capture sends the drag's move events to the pad, so the pad needs
 // no window listeners.
-const getPointerHandlers = (applyPosition: (x: number, y: number) => void) => {
-  const apply = (e: ReactPointerEvent<HTMLDivElement>) => {
+const getPointerHandlers = (applyPosition: ApplyPosition) => {
+  const apply = (
+    e: ReactPointerEvent<HTMLDivElement>,
+    reason: ColorPickerChangeReason
+  ) => {
     const rect = e.currentTarget.getBoundingClientRect();
     applyPosition(
       (e.clientX - rect.left) / rect.width,
-      (e.clientY - rect.top) / rect.height
+      (e.clientY - rect.top) / rect.height,
+      reason,
+      e.nativeEvent
     );
   };
   return {
     onPointerDown: (e: ReactPointerEvent<HTMLDivElement>) => {
       e.preventDefault();
       e.currentTarget.setPointerCapture(e.pointerId);
-      apply(e);
+      apply(e, 'track-press');
     },
     onPointerMove: (e: ReactPointerEvent<HTMLDivElement>) => {
-      if (e.currentTarget.hasPointerCapture(e.pointerId)) apply(e);
+      if (e.currentTarget.hasPointerCapture(e.pointerId)) apply(e, 'drag');
     }
   };
 };
@@ -129,9 +144,13 @@ const OklchArea = (props: ColorPickerAreaProps) => {
   // Shared color-computation path. Takes normalized 0..1 pad coordinates
   // (x = chroma axis, y = lightness axis) and writes them into OKLCH state.
   // Pointer drag and keyboard both go through this so behavior can't diverge.
-  const applyPosition = useCallback(
-    (x: number, y: number) => {
-      setColor({ c: clamp01(x) * CHROMA_MAX, l: 1 - clamp01(y) });
+  const applyPosition = useCallback<ApplyPosition>(
+    (x, y, reason, event) => {
+      setColor(
+        { c: clamp01(x) * CHROMA_MAX, l: 1 - clamp01(y) },
+        reason,
+        event
+      );
     },
     [setColor]
   );
@@ -172,7 +191,7 @@ const OklchArea = (props: ColorPickerAreaProps) => {
           return; // let other keys (Tab, etc.) pass through
       }
       e.preventDefault();
-      applyPosition(x, y);
+      applyPosition(x, y, 'keyboard', e.nativeEvent);
     },
     [applyPosition, chroma, lightness]
   );
@@ -256,14 +275,14 @@ const HslArea = (props: ColorPickerAreaProps) => {
   // (x = saturation axis, y = scaled-lightness axis) and round-trips through
   // hslToOklch into OKLCH state. Pointer drag and keyboard both go through
   // this so behavior can't diverge.
-  const applyPosition = useCallback(
-    (x: number, y: number) => {
+  const applyPosition = useCallback<ApplyPosition>(
+    (x, y, reason, event) => {
       const cx0 = clamp01(x);
       const saturation = cx0 * 100;
       const topLightness = cx0 < 0.01 ? 100 : 50 + 50 * (1 - cx0);
       const nextL = topLightness * (1 - clamp01(y));
       const next = hslToOklch(hsl.h, saturation, nextL);
-      setColor({ l: next.l, c: next.c, h: next.h });
+      setColor({ l: next.l, c: next.c, h: next.h }, reason, event);
     },
     [hsl.h, setColor]
   );
@@ -304,7 +323,7 @@ const HslArea = (props: ColorPickerAreaProps) => {
           return;
       }
       e.preventDefault();
-      applyPosition(x, y);
+      applyPosition(x, y, 'keyboard', e.nativeEvent);
     },
     [applyPosition, hsl.s, hsl.l]
   );
diff --git a/packages/react/components/color-picker/color-picker-hue.tsx b/packages/react/components/color-picker/color-picker-hue.tsx
index ace9ee632..f1a48b87f 100644
--- a/packages/react/components/color-picker/color-picker-hue.tsx
+++ b/packages/react/components/color-picker/color-picker-hue.tsx
@@ -24,21 +24,26 @@ export const ColorPickerHue = ({
   );
   const value = isOklch ? hue : (hsl?.h ?? 0);
 
-  const handleValueChange = (next: number) => {
+  const handleValueChange = (
+    next: number,
+    { reason, event }: Slider.Root.ChangeEventDetails
+  ) => {
     if (isOklch) {
-      setColor({ h: next });
+      setColor({ h: next }, reason, event);
       return;
     }
     if (!hsl) return;
     const oklch = hslToOklch(next, hsl.s, hsl.l);
-    setColor({ l: oklch.l, c: oklch.c, h: oklch.h });
+    setColor({ l: oklch.l, c: oklch.c, h: oklch.h }, reason, event);
   };
 
   return (
     <Slider.Root
       className={cx(styles.sliderRoot, className)}
       max={360}
-      onValueChange={value => handleValueChange(value as number)}
+      onValueChange={(value, eventDetails) =>
+        handleValueChange(value as number, eventDetails)
+      }
       // OKLCH hue is perceptually uniform, so sub-degree precision is meaningful
       // when fine-tuning a tone. HSL hue keeps the classic 1° granularity.
       step={isOklch ? 0.1 : 1}
diff --git a/packages/react/components/color-picker/color-picker-input.tsx b/packages/react/components/color-picker/color-picker-input.tsx
index 12684705d..33c11779a 100644
--- a/packages/react/components/color-picker/color-picker-input.tsx
+++ b/packages/react/components/color-picker/color-picker-input.tsx
@@ -43,10 +43,12 @@ export const ColorPickerInput = ({
     setDraft(null);
   }
 
-  const commit = () => {
+  const commit = (event: Event) => {
     if (draft === null) return;
     setDraft(null);
-    if (draft !== value && parse(draft)) setColor(parseColor(draft));
+    if (draft !== value && parse(draft)) {
+      setColor(parseColor(draft), 'input-change', event);
+    }
   };
 
   // A consumer-supplied trailingIcon always wins; copyable only fills the slot
@@ -64,7 +66,7 @@ export const ColorPickerInput = ({
         onChange?.(event);
       }}
       onBlur={event => {
-        commit();
+        commit(event.nativeEvent);
         onBlur?.(event);
       }}
       onKeyDown={event => {
@@ -74,7 +76,7 @@ export const ColorPickerInput = ({
           event.keyCode !== 229
         ) {
           event.preventDefault();
-          commit();
+          commit(event.nativeEvent);
         }
         onKeyDown?.(event);
       }}
diff --git a/packages/react/components/color-picker/color-picker-root.tsx b/packages/react/components/color-picker/color-picker-root.tsx
index e6b8e522c..d8f7f8f7f 100644
--- a/packages/react/components/color-picker/color-picker-root.tsx
+++ b/packages/react/components/color-picker/color-picker-root.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import type { Slider as SliderPrimitive } from '@base-ui/react/slider';
 import { useControlled } from '@base-ui/utils/useControlled';
 import {
   ComponentProps,
@@ -9,6 +10,10 @@ import {
   useMemo,
   useRef
 } from 'react';
+import {
+  type ChangeDetails,
+  createChangeDetails
+} from '~/shared/change-details';
 import { Flex } from '../flex';
 import {
   ColorObject,
@@ -18,13 +23,24 @@ import {
   parseColor
 } from './utils';
 
+export type ColorPickerChangeReason = SliderPrimitive.Root.ChangeEventReason;
+
+export type ColorPickerChangeDetails = ChangeDetails<
+  ColorPickerChangeReason,
+  { mode: ModeType }
+>;
+
 type ColorPickerContextValue = {
   lightness: number;
   chroma: number;
   hue: number;
   alpha: number;
   mode: ModeType;
-  setColor: (color: Partial<ColorObject>) => void;
+  setColor: (
+    color: Partial<ColorObject>,
+    reason: ColorPickerChangeReason,
+    event?: Event
+  ) => void;
   setMode: (mode: ModeType) => void;
 };
 
@@ -44,7 +60,7 @@ export interface ColorPickerProps
   extends Omit<ComponentProps<typeof Flex>, 'defaultValue'> {
   value?: string;
   defaultValue?: string;
-  onValueChange?: (value: string, mode: string) => void;
+  onValueChange?: (value: string, details: ColorPickerChangeDetails) => void;
   defaultMode?: ModeType;
   mode?: ModeType;
   onModeChange?: (mode: ModeType) => void;
@@ -104,11 +120,14 @@ export const ColorPickerRoot = ({
   rawColorRef.current = rawColor;
 
   const setColor = useCallback<ColorPickerContextValue['setColor']>(
-    value => {
+    (value, reason, event) => {
       const next = { ...rawColorRef.current, ...value };
       rawColorRef.current = next;
       setColorUnwrapped(next);
-      onValueChange?.(getColorString(next, mode), mode);
+      onValueChange?.(
+        getColorString(next, mode),
+        createChangeDetails(reason, event, { mode })
+      );
     },
     [mode, onValueChange, setColorUnwrapped]
   );
diff --git a/packages/react/components/combobox/__tests__/combobox.test.tsx b/packages/react/components/combobox/__tests__/combobox.test.tsx
index 8df68130d..00a8ebf3d 100644
--- a/packages/react/components/combobox/__tests__/combobox.test.tsx
+++ b/packages/react/components/combobox/__tests__/combobox.test.tsx
@@ -98,7 +98,10 @@ describe('Combobox', () => {
       const bananaOption = await screen.findByText('Banana');
       await clickOption(bananaOption);
 
-      expect(handleValueChange).toHaveBeenCalledWith('banana');
+      expect(handleValueChange).toHaveBeenCalledWith(
+        'banana',
+        expect.objectContaining({ reason: 'item-press' })
+      );
     });
 
     it('closes content after selection in single mode', async () => {
@@ -145,11 +148,17 @@ describe('Combobox', () => {
 
       const bananaOption = await screen.findByText('Banana');
       await clickOption(bananaOption);
-      expect(handleValueChange).toHaveBeenCalledWith(['banana']);
+      expect(handleValueChange).toHaveBeenCalledWith(
+        ['banana'],
+        expect.anything()
+      );
 
       const pineappleOption = await screen.findByText('Pineapple');
       await clickOption(pineappleOption);
-      expect(handleValueChange).toHaveBeenCalledWith(['banana', 'pineapple']);
+      expect(handleValueChange).toHaveBeenCalledWith(
+        ['banana', 'pineapple'],
+        expect.anything()
+      );
     });
 
     it('allows deselecting items in multiple mode', async () => {
@@ -162,10 +171,13 @@ describe('Combobox', () => {
 
       const bananaOption = await screen.findByText('Banana');
       await clickOption(bananaOption);
-      expect(handleValueChange).toHaveBeenCalledWith(['banana']);
+      expect(handleValueChange).toHaveBeenCalledWith(
+        ['banana'],
+        expect.anything()
+      );
 
       await clickOption(bananaOption);
-      expect(handleValueChange).toHaveBeenCalledWith([]);
+      expect(handleValueChange).toHaveBeenCalledWith([], expect.anything());
     });
 
     it('keeps dropdown open after selection in multiple mode', async () => {
@@ -338,7 +350,7 @@ describe('Combobox', () => {
       const input = screen.getByRole('combobox');
       await user.type(input, 'a');
 
-      expect(handleInputChange).toHaveBeenCalledWith('a');
+      expect(handleInputChange).toHaveBeenCalledWith('a', expect.anything());
     });
   });
 
@@ -463,7 +475,7 @@ describe('Combobox', () => {
 
       fireEvent.change(input, { target: { value: 'app' } });
 
-      expect(handleInputChange).toHaveBeenCalledWith('app');
+      expect(handleInputChange).toHaveBeenCalledWith('app', expect.anything());
       expect(input).toHaveValue('ban');
       expect(screen.getByText('Banana')).toBeInTheDocument();
       expect(screen.queryByText('Apple')).not.toBeInTheDocument();
@@ -539,7 +551,10 @@ describe('Combobox', () => {
       const appleOption = await screen.findByText('Apple');
       await clickOption(appleOption);
 
-      expect(handleValueChange).toHaveBeenCalledWith('Apple');
+      expect(handleValueChange).toHaveBeenCalledWith(
+        'Apple',
+        expect.anything()
+      );
     });
   });
 });
@@ -578,7 +593,7 @@ describe('Combobox.createItems', () => {
     await user.click(screen.getByRole('combobox'));
     await clickOption(await screen.findByText('John Smith'));
 
-    expect(onValueChange).toHaveBeenCalledWith('u2');
+    expect(onValueChange).toHaveBeenCalledWith('u2', expect.anything());
   });
 
   it('filters by the derived label', async () => {
diff --git a/packages/react/components/combobox/combobox-input.tsx b/packages/react/components/combobox/combobox-input.tsx
index a8399ef4c..cb448a05f 100644
--- a/packages/react/components/combobox/combobox-input.tsx
+++ b/packages/react/components/combobox/combobox-input.tsx
@@ -1,6 +1,8 @@
 'use client';
 
 import { Combobox as ComboboxPrimitive } from '@base-ui/react';
+import { createChangeEventDetails } from '@base-ui/react/internals/createBaseUIEventDetails';
+import { REASONS } from '@base-ui/react/internals/reasons';
 import { type ComponentProps } from 'react';
 import { ChevronDownIcon } from '~/icons';
 import { Input } from '../input';
@@ -26,7 +28,10 @@ export const ComboboxInput = ({ ref, ...props }: ComboboxInputProps) => {
               ? value.map(val => ({
                   label: getLabel(val),
                   onRemove: () =>
-                    onValueChange?.((value as string[])?.filter(v => v !== val))
+                    onValueChange?.(
+                      (value as string[])?.filter(v => v !== val),
+                      createChangeEventDetails(REASONS.chipRemovePress)
+                    )
                 }))
               : undefined
           }
diff --git a/packages/react/components/combobox/combobox-root.tsx b/packages/react/components/combobox/combobox-root.tsx
index 73ff964e2..24468b0a3 100644
--- a/packages/react/components/combobox/combobox-root.tsx
+++ b/packages/react/components/combobox/combobox-root.tsx
@@ -18,7 +18,10 @@ interface ComboboxContextValue<Value = string> {
   hasItems: boolean;
   inputContainerRef: RefObject<HTMLDivElement | null>;
   value: Value | Value[] | null | undefined;
-  onValueChange?: (value: Value | Value[] | null) => void;
+  onValueChange?: (
+    value: Value | Value[] | null,
+    eventDetails: ComboboxPrimitive.Root.ChangeEventDetails
+  ) => void;
   getLabel: (value: Value) => string;
 }
 
@@ -43,7 +46,10 @@ export interface BaseComboboxRootProps<Value, Item = Value>
     ComboboxPrimitive.Root.Props<Value, boolean, Item>,
     'onValueChange' | 'onInputValueChange' | 'multiple'
   > {
-  onInputValueChange?: (inputValue: string) => void;
+  onInputValueChange?: (
+    inputValue: string,
+    eventDetails: ComboboxPrimitive.Root.ChangeEventDetails
+  ) => void;
 }
 
 export interface SingleComboboxProps<Value = string, Item = Value>
@@ -51,7 +57,10 @@ export interface SingleComboboxProps<Value = string, Item = Value>
   multiple?: false;
   value?: Value | null;
   defaultValue?: Value | null;
-  onValueChange?: (value: Value | null) => void;
+  onValueChange?: (
+    value: Value | null,
+    eventDetails: ComboboxPrimitive.Root.ChangeEventDetails
+  ) => void;
 }
 
 export interface MultipleComboboxProps<Value = string, Item = Value>
@@ -59,7 +68,10 @@ export interface MultipleComboboxProps<Value = string, Item = Value>
   multiple: true;
   value?: Value[];
   defaultValue?: Value[];
-  onValueChange?: (value: Value[]) => void;
+  onValueChange?: (
+    value: Value[],
+    eventDetails: ComboboxPrimitive.Root.ChangeEventDetails
+  ) => void;
 }
 
 export type ComboboxRootProps<Value = string, Item = Value> =
@@ -106,7 +118,7 @@ export const ComboboxRoot = <Value extends unknown | unknown[], Item = Value>({
       eventDetails: ComboboxPrimitive.Root.ChangeEventDetails
     ) => {
       setInputValueUnwrapped(value);
-      onInputValueChange?.(value);
+      onInputValueChange?.(value, eventDetails);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
@@ -119,11 +131,13 @@ export const ComboboxRoot = <Value extends unknown | unknown[], Item = Value>({
       setValueUnwrapped(value);
       if (multiple) {
         (onValueChange as MultipleComboboxProps<Value>['onValueChange'])?.(
-          value as Value[]
+          value as Value[],
+          eventDetails
         );
       } else {
         (onValueChange as SingleComboboxProps<Value>['onValueChange'])?.(
-          value as Value | null
+          value as Value | null,
+          eventDetails
         );
       }
     },
diff --git a/packages/react/components/context-menu/context-menu-content.tsx b/packages/react/components/context-menu/context-menu-content.tsx
index d1fc9fc1b..6580d7858 100644
--- a/packages/react/components/context-menu/context-menu-content.tsx
+++ b/packages/react/components/context-menu/context-menu-content.tsx
@@ -144,7 +144,7 @@ export const ContextMenuContent = ({
               inline
               open
               value={inputValue}
-              onValueChange={(value: string) => onInputValueChange?.(value)}
+              onValueChange={onInputValueChange}
               autoHighlight={!!inputValue?.length}
               mode='none'
               loopFocus={false}
diff --git a/packages/react/components/context-menu/context-menu-root.tsx b/packages/react/components/context-menu/context-menu-root.tsx
index d3e38aac5..1efcba8d6 100644
--- a/packages/react/components/context-menu/context-menu-root.tsx
+++ b/packages/react/components/context-menu/context-menu-root.tsx
@@ -1,6 +1,11 @@
 'use client';
 
-import { ContextMenu as ContextMenuPrimitive } from '@base-ui/react';
+import {
+  Autocomplete as AutocompletePrimitive,
+  ContextMenu as ContextMenuPrimitive
+} from '@base-ui/react';
+import { createChangeEventDetails } from '@base-ui/react/internals/createBaseUIEventDetails';
+import { REASONS } from '@base-ui/react/internals/reasons';
 import { useControlled } from '@base-ui/utils/useControlled';
 import { useCallback, useRef } from 'react';
 import { MenuContext, useMenuContext } from '../menu/menu-root';
@@ -19,7 +24,10 @@ export interface AutocompleteContextMenuRootProps
   autocomplete: true;
   autocompleteMode?: 'auto' | 'manual';
   inputValue?: string;
-  onInputValueChange?: (value: string) => void;
+  onInputValueChange?: (
+    value: string,
+    eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
+  ) => void;
   defaultInputValue?: string;
 }
 
@@ -55,9 +63,12 @@ export const ContextMenuRoot = ({
   const isInitialRender = useRef(true);
 
   const setValue = useCallback(
-    (value: string) => {
+    (
+      value: string,
+      eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
+    ) => {
       setInputValueUnwrapped(value);
-      onInputValueChange?.(value);
+      onInputValueChange?.(value, eventDetails);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
@@ -69,7 +80,10 @@ export const ContextMenuRoot = ({
         eventDetails: ContextMenuPrimitive.Root.ChangeEventDetails
       ) => {
         if (!value && autocomplete) {
-          setValue('');
+          setValue(
+            '',
+            createChangeEventDetails(REASONS.inputClear, eventDetails.event)
+          );
           isInitialRender.current = true;
         }
         setOpenUnwrapped(value);
@@ -116,7 +130,10 @@ export interface AutocompleteContextMenuSubMenuProps
   autocomplete: true;
   autocompleteMode?: 'auto' | 'manual';
   inputValue?: string;
-  onInputValueChange?: (value: string) => void;
+  onInputValueChange?: (
+    value: string,
+    eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
+  ) => void;
   defaultInputValue?: string;
 }
 
@@ -153,9 +170,12 @@ export const ContextMenuSubMenu = ({
   const contentRef = useRef<HTMLDivElement>(null);
 
   const setValue = useCallback(
-    (value: string) => {
+    (
+      value: string,
+      eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
+    ) => {
       setInputValueUnwrapped(value);
-      onInputValueChange?.(value);
+      onInputValueChange?.(value, eventDetails);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
@@ -167,7 +187,10 @@ export const ContextMenuSubMenu = ({
         eventDetails: ContextMenuPrimitive.SubmenuRoot.ChangeEventDetails
       ) => {
         if (!value && autocomplete) {
-          setValue('');
+          setValue(
+            '',
+            createChangeEventDetails(REASONS.inputClear, eventDetails.event)
+          );
           isInitialRender.current = true;
         }
         setOpenUnwrapped(value);
diff --git a/packages/react/components/data-view/__tests__/data-view.test.tsx b/packages/react/components/data-view/__tests__/data-view.test.tsx
index 2b0b2abf3..11adc92ff 100644
--- a/packages/react/components/data-view/__tests__/data-view.test.tsx
+++ b/packages/react/components/data-view/__tests__/data-view.test.tsx
@@ -616,6 +616,31 @@ describe('DataView', () => {
       expect(screen.getByRole('list')).toBeInTheDocument();
     });
 
+    it('passes details to onViewChange', async () => {
+      const user = userEvent.setup();
+      const onViewChange = vi.fn();
+      render(
+        <DataView
+          data={mockData}
+          fields={mockFields}
+          defaultSort={defaultSort}
+          views={views}
+          defaultView='table'
+          onViewChange={onViewChange}
+        >
+          <DataView.DisplayControls />
+          <DataView.List name='table' variant='table' columns={mockColumns} />
+          <DataView.List name='list' variant='list' columns={mockColumns} />
+        </DataView>
+      );
+      await user.click(screen.getByRole('button', { name: 'Display' }));
+      await user.click(await screen.findByRole('tab', { name: 'List' }));
+      expect(onViewChange).toHaveBeenCalledWith(
+        'list',
+        expect.objectContaining({ reason: 'none', event: expect.any(Event) })
+      );
+    });
+
     it('renderer with name not matching any views[].value renders nothing', () => {
       render(
         <DataView
diff --git a/packages/react/components/data-view/components/view-switcher.tsx b/packages/react/components/data-view/components/view-switcher.tsx
index 3b2bf0c5b..8e7aaba90 100644
--- a/packages/react/components/data-view/components/view-switcher.tsx
+++ b/packages/react/components/data-view/components/view-switcher.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { createChangeDetails } from '~/shared/change-details';
 import { Tabs } from '../../tabs';
 import { useDataView } from '../hooks/useDataView';
 
@@ -19,7 +20,12 @@ export function ViewSwitcher({ size = 'small' }: ViewSwitcherProps) {
   return (
     <Tabs
       value={activeView}
-      onValueChange={v => setActiveView(v)}
+      onValueChange={(v, eventDetails) =>
+        setActiveView(
+          v,
+          createChangeDetails(eventDetails.reason, eventDetails.event)
+        )
+      }
       size={size}
       data-slot='data-view-view-switcher'
     >
diff --git a/packages/react/components/data-view/data-view.tsx b/packages/react/components/data-view/data-view.tsx
index 3d90946e6..d18f7820d 100644
--- a/packages/react/components/data-view/data-view.tsx
+++ b/packages/react/components/data-view/data-view.tsx
@@ -11,6 +11,7 @@ import {
   VisibilityState
 } from '@tanstack/react-table';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createChangeDetails } from '~/shared/change-details';
 
 import { DataViewClearFilters } from './components/clear-filters';
 import { DataViewCustom } from './components/custom';
@@ -28,6 +29,7 @@ import {
   DataViewContextType,
   DataViewField,
   DataViewProps,
+  DataViewViewChangeDetails,
   defaultGroupOption,
   GroupedData,
   InternalQuery,
@@ -84,9 +86,12 @@ function DataViewRoot<TData>({
     state: 'view'
   });
   const setActiveView = useCallback(
-    (next: string) => {
+    (
+      next: string,
+      details: DataViewViewChangeDetails = createChangeDetails('none')
+    ) => {
       setActiveViewUnwrapped(next);
-      onViewChange?.(next);
+      onViewChange?.(next, details);
     },
     [onViewChange, setActiveViewUnwrapped]
   );
diff --git a/packages/react/components/data-view/data-view.types.tsx b/packages/react/components/data-view/data-view.types.tsx
index 8ec4dff2b..8cc2faea6 100644
--- a/packages/react/components/data-view/data-view.types.tsx
+++ b/packages/react/components/data-view/data-view.types.tsx
@@ -1,3 +1,4 @@
+import type { Tabs as TabsPrimitive } from '@base-ui/react';
 import type {
   ColumnDef,
   Row,
@@ -6,6 +7,7 @@ import type {
   Updater,
   VisibilityState
 } from '@tanstack/table-core';
+import type { ChangeDetails } from '~/shared/change-details';
 import type {
   DataTableFilterOperatorTypes,
   FilterDataType,
@@ -18,6 +20,9 @@ import type { BaseSelectProps } from '../select/select-root';
 
 export type DataViewMode = 'client' | 'server';
 
+export type DataViewViewChangeDetails =
+  ChangeDetails<TabsPrimitive.Root.ChangeEventReason>;
+
 export const SortOrders = {
   ASC: 'asc',
   DESC: 'desc'
@@ -189,7 +194,7 @@ export interface DataViewProps<TData> {
   /** Active view (controlled). */
   view?: string;
   /** Called when the active view changes. */
-  onViewChange?: (view: string) => void;
+  onViewChange?: (view: string, details: DataViewViewChangeDetails) => void;
   /**
    * Optional local resolver map for non-accessor `group_by` keys. The wire
    * format (`group_by: string[]`) stays unchanged; resolvers run in client mode
@@ -516,7 +521,7 @@ export type DataViewContextType<TData> = {
   // multi-view
   views?: ViewSpec[];
   activeView?: string;
-  setActiveView: (view: string) => void;
+  setActiveView: (view: string, details?: DataViewViewChangeDetails) => void;
   /** Called by each renderer on mount to register its `fields` override for its `name`. Returns a cleanup function. */
   registerFieldsForView: (
     name: string,
diff --git a/packages/react/components/editor/core/mention-registry.ts b/packages/react/components/editor/core/mention-registry.ts
index 6ab1163aa..fac3312d6 100644
--- a/packages/react/components/editor/core/mention-registry.ts
+++ b/packages/react/components/editor/core/mention-registry.ts
@@ -2,6 +2,7 @@
 
 import type { ReactNode } from 'react';
 import { mentionKey } from './mention';
+import type { SuggestionOpenChangeDetails } from './use-suggestion-menu';
 
 export interface EditorMentionItem {
   id: string;
@@ -37,7 +38,7 @@ export interface MentionsData {
     context: { trigger: string; signal: AbortSignal }
   ) => Promise<EditorMentionItem[]>;
   resolveMentions?: (refs: EditorMentionRef[]) => Promise<EditorMentionItem[]>;
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (open: boolean, details: SuggestionOpenChangeDetails) => void;
   emptyMessage?: ReactNode;
   loadingRowCount?: number;
 }
diff --git a/packages/react/components/editor/core/use-suggestion-menu.ts b/packages/react/components/editor/core/use-suggestion-menu.ts
index c3d28db3a..48502e04d 100644
--- a/packages/react/components/editor/core/use-suggestion-menu.ts
+++ b/packages/react/components/editor/core/use-suggestion-menu.ts
@@ -14,6 +14,10 @@ import {
   useState,
   useSyncExternalStore
 } from 'react';
+import {
+  type ChangeDetails,
+  createChangeDetails
+} from '~/shared/change-details';
 import { type MentionAttrs, mentionKey } from './mention';
 import type {
   EditorMentionItem,
@@ -151,7 +155,7 @@ export interface UseSuggestionMenuOptions<Item extends SuggestionItem> {
   onSelect: (item: Item, state: SuggestionState) => void;
   /** Closes the menu and leaves the typed text literal. */
   dismiss: () => void;
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (open: boolean, details: SuggestionOpenChangeDetails) => void;
   listboxId: string;
   /** The part name in the dev warning for a rejected `onSearch`. */
   name: string;
@@ -173,6 +177,9 @@ export interface UseSuggestionMenuResult<Item extends SuggestionItem> {
   handleKeyDown: (event: KeyboardEvent, state: SuggestionState) => boolean;
 }
 
+/** `open` follows the editor state, so the reason is always `'none'`. */
+export type SuggestionOpenChangeDetails = ChangeDetails<'none'>;
+
 export function useSuggestionMenu<Item extends SuggestionItem>({
   getView,
   suggestion,
@@ -285,15 +292,15 @@ export function useSuggestionMenu<Item extends SuggestionItem>({
 
   // Held past the config that supplied it: closing clears the active trigger,
   // so reading the callback off the live config would swallow the `false`.
-  const onOpenChangeRef = useRef<((open: boolean) => void) | undefined>(
-    undefined
-  );
+  const onOpenChangeRef = useRef<
+    UseSuggestionMenuOptions<Item>['onOpenChange'] | undefined
+  >(undefined);
   if (onOpenChange) onOpenChangeRef.current = onOpenChange;
   const lastOpenRef = useRef(false);
   useEffect(() => {
     if (lastOpenRef.current === open) return;
     lastOpenRef.current = open;
-    onOpenChangeRef.current?.(open);
+    onOpenChangeRef.current?.(open, createChangeDetails('none'));
   }, [open]);
 
   const close = useCallback(() => {
diff --git a/packages/react/components/editor/editor-mentions.tsx b/packages/react/components/editor/editor-mentions.tsx
index c8d1953ea..e697d811a 100644
--- a/packages/react/components/editor/editor-mentions.tsx
+++ b/packages/react/components/editor/editor-mentions.tsx
@@ -8,7 +8,10 @@ import type {
 } from './core/mention-registry';
 import { docMentions } from './core/serializers';
 import { SuggestionMenu } from './core/suggestion-menu';
-import { useMentionResolution } from './core/use-suggestion-menu';
+import {
+  type SuggestionOpenChangeDetails,
+  useMentionResolution
+} from './core/use-suggestion-menu';
 import { useEditorStore, useStoreSelector } from './editor-context';
 import type { EditorStore } from './editor-store';
 import { useEditorSuggestion } from './use-editor-suggestion';
@@ -39,7 +42,7 @@ export interface EditorMentionsProps {
    */
   loadingRowCount?: number;
   /** Observes the menu's open state. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (open: boolean, details: SuggestionOpenChangeDetails) => void;
 }
 
 const NO_MENTIONS: MentionAttrs[] = [];
diff --git a/packages/react/components/editor/editor-slash-menu.tsx b/packages/react/components/editor/editor-slash-menu.tsx
index 64be8f9bd..d38250c17 100644
--- a/packages/react/components/editor/editor-slash-menu.tsx
+++ b/packages/react/components/editor/editor-slash-menu.tsx
@@ -6,7 +6,10 @@ import {
   SuggestionMenu,
   type SuggestionMenuItem
 } from './core/suggestion-menu';
-import { filterItems } from './core/use-suggestion-menu';
+import {
+  filterItems,
+  type SuggestionOpenChangeDetails
+} from './core/use-suggestion-menu';
 import styles from './editor.module.css';
 import { useEditorStore, useStoreSelector } from './editor-context';
 import { EditorShortcutKeys } from './editor-control';
@@ -32,7 +35,7 @@ export interface EditorSlashMenuProps {
    */
   emptyMessage?: ReactNode;
   /** Observes the menu's open state. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (open: boolean, details: SuggestionOpenChangeDetails) => void;
 }
 
 const NO_FLAGS: boolean[] = [];
diff --git a/packages/react/components/filter-chip/__tests__/filter-chip.test.tsx b/packages/react/components/filter-chip/__tests__/filter-chip.test.tsx
index ef8061735..d13c87c03 100644
--- a/packages/react/components/filter-chip/__tests__/filter-chip.test.tsx
+++ b/packages/react/components/filter-chip/__tests__/filter-chip.test.tsx
@@ -109,7 +109,7 @@ describe('FilterChip', () => {
 
       expect(onValueChange).toHaveBeenCalledWith(
         'test value',
-        expect.any(String)
+        expect.objectContaining({ operation: expect.any(String) })
       );
     });
 
@@ -157,7 +157,10 @@ describe('FilterChip', () => {
 
       await userEvent.click(screen.getByRole('option', { name: 'Two' }));
       await flush();
-      expect(onValueChange).toHaveBeenLastCalledWith([1, 2], 'in');
+      expect(onValueChange).toHaveBeenLastCalledWith(
+        [1, 2],
+        expect.objectContaining({ operation: 'in' })
+      );
     });
   });
 
@@ -179,7 +182,10 @@ describe('FilterChip', () => {
 
       fireEvent.change(getInput(container), { target: { value: '42' } });
 
-      expect(onValueChange).toHaveBeenCalledWith(42, expect.any(String));
+      expect(onValueChange).toHaveBeenCalledWith(
+        42,
+        expect.objectContaining({ operation: expect.any(String) })
+      );
     });
 
     it('rejects non-numeric input', () => {
@@ -234,8 +240,16 @@ describe('FilterChip', () => {
       fireEvent.change(input, { target: { value: '1.' } });
       expect(input).toHaveValue('1.');
 
-      expect(onValueChange).toHaveBeenNthCalledWith(1, '-', expect.any(String));
-      expect(onValueChange).toHaveBeenNthCalledWith(2, 1, expect.any(String));
+      expect(onValueChange).toHaveBeenNthCalledWith(
+        1,
+        '-',
+        expect.objectContaining({ operation: expect.any(String) })
+      );
+      expect(onValueChange).toHaveBeenNthCalledWith(
+        2,
+        1,
+        expect.objectContaining({ operation: expect.any(String) })
+      );
     });
 
     it('emits a trailing decimal as the number it parses to', () => {
@@ -251,10 +265,16 @@ describe('FilterChip', () => {
       const input = getInput(container);
 
       fireEvent.change(input, { target: { value: '1.' } });
-      expect(onValueChange).toHaveBeenLastCalledWith(1, expect.any(String));
+      expect(onValueChange).toHaveBeenLastCalledWith(
+        1,
+        expect.objectContaining({ operation: expect.any(String) })
+      );
 
       fireEvent.change(input, { target: { value: '1.5' } });
-      expect(onValueChange).toHaveBeenLastCalledWith(1.5, expect.any(String));
+      expect(onValueChange).toHaveBeenLastCalledWith(
+        1.5,
+        expect.objectContaining({ operation: expect.any(String) })
+      );
     });
 
     it('rejects a second decimal point', () => {
@@ -329,7 +349,10 @@ describe('FilterChip', () => {
 
       fireEvent.change(getInput(container), { target: { value: '' } });
 
-      expect(onValueChange).toHaveBeenCalledWith('', expect.any(String));
+      expect(onValueChange).toHaveBeenCalledWith(
+        '',
+        expect.objectContaining({ operation: expect.any(String) })
+      );
     });
   });
 
@@ -454,7 +477,7 @@ describe('FilterChip', () => {
       fireEvent.keyDown(input, { key: 'Enter' });
       expect(onValueChange).toHaveBeenCalledWith(
         new Date(2026, 4, 27),
-        expect.any(String)
+        expect.objectContaining({ operation: expect.any(String) })
       );
     });
 
@@ -471,7 +494,10 @@ describe('FilterChip', () => {
       const input = screen.getByPlaceholderText('Select date');
       fireEvent.change(input, { target: { value: '' } });
       fireEvent.blur(input);
-      expect(onValueChange).toHaveBeenCalledWith('', expect.any(String));
+      expect(onValueChange).toHaveBeenCalledWith(
+        '',
+        expect.objectContaining({ operation: expect.any(String) })
+      );
       expect(input).toHaveValue('');
     });
 
@@ -504,7 +530,7 @@ describe('FilterChip', () => {
       clickDay('12');
       expect(onValueChange).toHaveBeenCalledWith(
         new Date(2026, 4, 12),
-        expect.any(String)
+        expect.objectContaining({ operation: expect.any(String) })
       );
       await act(() => new Promise(resolve => setTimeout(resolve, 100)));
       expect(isOpen()).toBe(false);
diff --git a/packages/react/components/filter-chip/filter-chip.tsx b/packages/react/components/filter-chip/filter-chip.tsx
index ee5b34a71..5e6d96c3f 100644
--- a/packages/react/components/filter-chip/filter-chip.tsx
+++ b/packages/react/components/filter-chip/filter-chip.tsx
@@ -12,11 +12,16 @@ import {
 } from 'react';
 import {
   CalendarPreview,
+  type CalendarPreviewChangeReason,
   type CalendarPreviewContentProps,
   type CalendarPreviewInputProps,
   type CalendarPreviewProps
 } from '~/components/calendar-preview';
 import { XIcon } from '~/icons';
+import {
+  type ChangeDetails,
+  createChangeDetails
+} from '~/shared/change-details';
 import { toInstant } from '~/shared/date-filters';
 import {
   FilterOperation,
@@ -30,7 +35,10 @@ import {
 import { Flex } from '../flex';
 import { Input } from '../input';
 import { Select } from '../select';
-import { BaseSelectProps } from '../select/select-root';
+import {
+  BaseSelectProps,
+  type SelectChangeEventDetails
+} from '../select/select-root';
 import { Text } from '../text';
 import styles from './filter-chip.module.css';
 import { Operation } from './filter-chip-operation';
@@ -49,6 +57,16 @@ const chip = cva(styles.chip, {
 
 export type FilterChipValue = FilterValueType | FilterValueType[] | Date;
 
+export type FilterChipChangeReason =
+  | SelectChangeEventDetails['reason']
+  | CalendarPreviewChangeReason
+  | 'none';
+
+export type FilterChipChangeDetails = ChangeDetails<
+  FilterChipChangeReason,
+  { operation: string }
+>;
+
 /* The message `DatePicker` reports, so `onErrorChange` reads the same. */
 const INVALID_DATE = 'Invalid date';
 
@@ -101,7 +119,10 @@ export interface FilterChipProps
   onRemove?: () => void;
   columnType?: FilterTypes;
   options?: FilterSelectOption[];
-  onValueChange?: (value: FilterChipValue, operation: string) => void;
+  onValueChange?: (
+    value: FilterChipValue,
+    details: FilterChipChangeDetails
+  ) => void;
   onOperationChange?: (operation: string) => void;
   leadingIcon?: ReactElement;
   operations?: FilterOperator<string>[];
@@ -189,30 +210,44 @@ export const FilterChip = ({
     [onOperationChange]
   );
 
+  const emitValueChange = useCallback(
+    (value: FilterChipValue, reason: FilterChipChangeReason, event?: Event) => {
+      onValueChange?.(
+        value,
+        createChangeDetails(reason, event, {
+          operation: operation?.value ?? ''
+        })
+      );
+    },
+    [operation, onValueChange]
+  );
+
   const handleFilterValueChange = useCallback(
-    (value: FilterChipValue) => {
+    (value: FilterChipValue, reason: FilterChipChangeReason, event?: Event) => {
       setFilterValue(value);
-      onValueChange?.(value, operation?.value ?? '');
+      emitValueChange(value, reason, event);
     },
-    [operation, onValueChange]
+    [emitValueChange]
   );
 
   // Select works on strings, so map each pick back to its option's value.
   const handleSelectValueChange = useCallback(
-    (picked: string | string[]) => {
+    (picked: string | string[], eventDetails: SelectChangeEventDetails) => {
       const toOption = (v: string) =>
         options.find(o => String(o.value) === v)?.value ?? v;
       handleFilterValueChange(
-        Array.isArray(picked) ? picked.map(toOption) : toOption(picked)
+        Array.isArray(picked) ? picked.map(toOption) : toOption(picked),
+        eventDetails.reason,
+        eventDetails.event
       );
     },
     [options, handleFilterValueChange]
   );
 
   const handleTextInputChange = useCallback(
-    (raw: string) => {
+    (raw: string, event: Event) => {
       if (!isNumberColumn) {
-        handleFilterValueChange(raw);
+        handleFilterValueChange(raw, 'none', event);
         return;
       }
       // Skipping setFilterValue makes React restore the controlled value.
@@ -222,9 +257,9 @@ export const FilterChip = ({
 
       setFilterValue(raw);
       const isIntermediate = raw === '' || Number.isNaN(parsed);
-      onValueChange?.(isIntermediate ? raw : parsed, operation?.value ?? '');
+      emitValueChange(isIntermediate ? raw : parsed, 'none', event);
     },
-    [isNumberColumn, handleFilterValueChange, onValueChange, operation]
+    [isNumberColumn, handleFilterValueChange, emitValueChange]
   );
 
   const renderValueInput = () => {
@@ -286,8 +321,8 @@ export const FilterChip = ({
               disabled={inputProps.disabled}
               readOnly={inputProps.readOnly}
               value={dateValue}
-              onValueChange={date => {
-                handleFilterValueChange(date ?? '');
+              onValueChange={(date, details) => {
+                handleFilterValueChange(date ?? '', details.reason);
                 if (date) setDateOpen(false);
               }}
               open={dateOpen}
@@ -331,7 +366,9 @@ export const FilterChip = ({
               variant={variant === 'text' ? 'borderless' : 'default'}
               classNames={{ container: styles.inputField }}
               value={filterValue.toString()}
-              onChange={e => handleTextInputChange(e.target.value)}
+              onChange={e =>
+                handleTextInputChange(e.target.value, e.nativeEvent)
+              }
             />
           </div>
         );
diff --git a/packages/react/components/menu/__tests__/menu.test.tsx b/packages/react/components/menu/__tests__/menu.test.tsx
index 3455b9c39..1049eccc8 100644
--- a/packages/react/components/menu/__tests__/menu.test.tsx
+++ b/packages/react/components/menu/__tests__/menu.test.tsx
@@ -177,7 +177,10 @@ describe('Menu', () => {
 
       fireEvent.change(input, { target: { value: 'app' } });
 
-      expect(onInputValueChange).toHaveBeenCalledWith('app');
+      expect(onInputValueChange).toHaveBeenCalledWith(
+        'app',
+        expect.objectContaining({ reason: 'input-change' })
+      );
       expect(input).toHaveValue('ban');
       expect(screen.queryByText('Apple')).not.toBeInTheDocument();
       expect(screen.getByText('Banana')).toBeInTheDocument();
@@ -206,7 +209,10 @@ describe('Menu', () => {
       });
       fireEvent.click(screen.getByText(TRIGGER_TEXT));
 
-      expect(onInputValueChange).toHaveBeenCalledWith('');
+      expect(onInputValueChange).toHaveBeenCalledWith(
+        '',
+        expect.objectContaining({ reason: 'input-clear' })
+      );
       expect(await screen.findByText('Apple')).toBeInTheDocument();
       expect(screen.getByText('Banana')).toBeInTheDocument();
     });
diff --git a/packages/react/components/menu/menu-content.tsx b/packages/react/components/menu/menu-content.tsx
index 7729c69bf..4f3e4b056 100644
--- a/packages/react/components/menu/menu-content.tsx
+++ b/packages/react/components/menu/menu-content.tsx
@@ -144,7 +144,7 @@ export function MenuContent({
               inline
               open
               value={inputValue}
-              onValueChange={(value: string) => onInputValueChange?.(value)}
+              onValueChange={onInputValueChange}
               autoHighlight={!!inputValue?.length}
               mode='none'
               loopFocus={false}
diff --git a/packages/react/components/menu/menu-root.tsx b/packages/react/components/menu/menu-root.tsx
index 849abc7a9..b1a3c34cc 100644
--- a/packages/react/components/menu/menu-root.tsx
+++ b/packages/react/components/menu/menu-root.tsx
@@ -1,6 +1,11 @@
 'use client';
 
-import { Menu as MenuPrimitive } from '@base-ui/react';
+import {
+  Autocomplete as AutocompletePrimitive,
+  Menu as MenuPrimitive
+} from '@base-ui/react';
+import { createChangeEventDetails } from '@base-ui/react/internals/createBaseUIEventDetails';
+import { REASONS } from '@base-ui/react/internals/reasons';
 import { useControlled } from '@base-ui/utils/useControlled';
 import { createContext, useCallback, useContext, useRef } from 'react';
 
@@ -16,7 +21,10 @@ interface CommonProps {
 
 interface MenuContextValue extends CommonProps {
   parent?: CommonProps;
-  onInputValueChange?: (value: string) => void;
+  onInputValueChange?: (
+    value: string,
+    eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
+  ) => void;
 }
 
 interface UseMenuContextReturn extends MenuContextValue {
@@ -80,7 +88,10 @@ export interface AutocompleteMenuRootProps
   extends MenuPrimitive.Root.Props,
     CommonProps {
   autocomplete: true;
-  onInputValueChange?: (value: string) => void;
+  onInputValueChange?: (
+    value: string,
+    eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
+  ) => void;
   defaultInputValue?: string;
 }
 
@@ -114,9 +125,12 @@ export const MenuRoot = ({
   const isInitialRender = useRef(true);
 
   const setValue = useCallback(
-    (value: string) => {
+    (
+      value: string,
+      eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
+    ) => {
       setInputValueUnwrapped(value);
-      onInputValueChange?.(value);
+      onInputValueChange?.(value, eventDetails);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
@@ -125,7 +139,10 @@ export const MenuRoot = ({
     useCallback(
       (value: boolean, eventDetails: MenuPrimitive.Root.ChangeEventDetails) => {
         if (!value && autocomplete) {
-          setValue('');
+          setValue(
+            '',
+            createChangeEventDetails(REASONS.inputClear, eventDetails.event)
+          );
           isInitialRender.current = true;
         }
         setOpenUnwrapped(value);
@@ -173,7 +190,10 @@ export interface AutocompleteMenuSubMenuProps
   autocomplete: true;
   autocompleteMode?: 'auto' | 'manual';
   inputValue?: string;
-  onInputValueChange?: (value: string) => void;
+  onInputValueChange?: (
+    value: string,
+    eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
+  ) => void;
   defaultInputValue?: string;
 }
 
@@ -210,9 +230,12 @@ export const MenuSubMenu = ({
   const contentRef = useRef<HTMLDivElement>(null);
 
   const setValue = useCallback(
-    (value: string) => {
+    (
+      value: string,
+      eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
+    ) => {
       setInputValueUnwrapped(value);
-      onInputValueChange?.(value);
+      onInputValueChange?.(value, eventDetails);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
@@ -221,7 +244,10 @@ export const MenuSubMenu = ({
     useCallback(
       (value: boolean, eventDetails: MenuPrimitive.Root.ChangeEventDetails) => {
         if (!value && autocomplete) {
-          setValue('');
+          setValue(
+            '',
+            createChangeEventDetails(REASONS.inputClear, eventDetails.event)
+          );
           isInitialRender.current = true;
         }
         setOpenUnwrapped(value);
diff --git a/packages/react/components/prompt-input/__tests__/prompt-input-mentions.test.tsx b/packages/react/components/prompt-input/__tests__/prompt-input-mentions.test.tsx
index 9b48f29d1..320d71762 100644
--- a/packages/react/components/prompt-input/__tests__/prompt-input-mentions.test.tsx
+++ b/packages/react/components/prompt-input/__tests__/prompt-input-mentions.test.tsx
@@ -137,11 +137,14 @@ describe('PromptInput.Mentions', () => {
 
       type(editorOf(container), '@');
       await flush();
-      expect(onOpenChange).toHaveBeenLastCalledWith(true);
+      expect(onOpenChange).toHaveBeenLastCalledWith(
+        true,
+        expect.objectContaining({ reason: 'none' })
+      );
 
       fireEvent.keyDown(editorOf(container), { key: 'Escape' });
       await flush();
-      expect(onOpenChange).toHaveBeenLastCalledWith(false);
+      expect(onOpenChange).toHaveBeenLastCalledWith(false, expect.anything());
     });
   });
 
diff --git a/packages/react/components/prompt-input/prompt-input-mentions.tsx b/packages/react/components/prompt-input/prompt-input-mentions.tsx
index 9a0473ad3..50d9e5d84 100644
--- a/packages/react/components/prompt-input/prompt-input-mentions.tsx
+++ b/packages/react/components/prompt-input/prompt-input-mentions.tsx
@@ -2,6 +2,7 @@
 
 import { type ReactNode, useEffect, useRef } from 'react';
 import { isTriggerCharacter } from '../editor/core/mention';
+import type { SuggestionOpenChangeDetails } from '../editor/core/use-suggestion-menu';
 import { usePromptInputContext } from './prompt-input-context';
 import type {
   PromptInputMentionItem,
@@ -33,7 +34,7 @@ export interface PromptInputMentionsProps {
     refs: PromptInputMentionRef[]
   ) => Promise<PromptInputMentionItem[]>;
   /** Observes the menu's open state. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (open: boolean, details: SuggestionOpenChangeDetails) => void;
   /**
    * Empty-state content.
    * @defaultValue "No results"
diff --git a/packages/react/components/reasoning/__tests__/reasoning.test.tsx b/packages/react/components/reasoning/__tests__/reasoning.test.tsx
index f257faeba..263bb41fc 100644
--- a/packages/react/components/reasoning/__tests__/reasoning.test.tsx
+++ b/packages/react/components/reasoning/__tests__/reasoning.test.tsx
@@ -1,13 +1,9 @@
 import { fireEvent, render, screen } from '@testing-library/react';
-import { describe, expect, it } from 'vitest';
-import { Reasoning } from '../reasoning';
+import { describe, expect, it, vi } from 'vitest';
+import { Reasoning, type ReasoningProps } from '../reasoning';
 
 describe('Reasoning', () => {
-  const ReasoningExample = (props: {
-    streaming?: boolean;
-    duration?: number;
-    defaultOpen?: boolean;
-  }) => (
+  const ReasoningExample = (props: ReasoningProps) => (
     <Reasoning {...props}>
       <Reasoning.Trigger />
       <Reasoning.Content>
@@ -77,6 +73,24 @@ describe('Reasoning', () => {
     expect(screen.getByText('step detail')).toBeInTheDocument();
   });
 
+  it('passes eventDetails to onOpenChange', () => {
+    const onOpenChange = vi.fn();
+    const { rerender } = render(
+      <ReasoningExample streaming onOpenChange={onOpenChange} />
+    );
+    rerender(<ReasoningExample duration={2} onOpenChange={onOpenChange} />);
+    expect(onOpenChange).toHaveBeenLastCalledWith(
+      false,
+      expect.objectContaining({ reason: 'none' })
+    );
+
+    fireEvent.click(screen.getByRole('button'));
+    expect(onOpenChange).toHaveBeenLastCalledWith(
+      true,
+      expect.objectContaining({ reason: 'trigger-press' })
+    );
+  });
+
   it('renders step labels', () => {
     render(<ReasoningExample defaultOpen />);
     expect(screen.getByText('Gathering ticket updates')).toBeInTheDocument();
diff --git a/packages/react/components/reasoning/reasoning.tsx b/packages/react/components/reasoning/reasoning.tsx
index ff862ad72..89967af84 100644
--- a/packages/react/components/reasoning/reasoning.tsx
+++ b/packages/react/components/reasoning/reasoning.tsx
@@ -1,5 +1,8 @@
 'use client';
 
+import type { Collapsible as CollapsiblePrimitive } from '@base-ui/react';
+import { createChangeEventDetails } from '@base-ui/react/internals/createBaseUIEventDetails';
+import { REASONS } from '@base-ui/react/internals/reasons';
 import { useControlled } from '@base-ui/utils/useControlled';
 import { cx } from 'class-variance-authority';
 import {
@@ -47,7 +50,10 @@ export interface ReasoningProps
    */
   duration?: number;
   /** Called when the panel is opened or closed. */
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (
+    open: boolean,
+    eventDetails: CollapsiblePrimitive.Root.ChangeEventDetails
+  ) => void;
 }
 
 function ReasoningRoot({
@@ -71,9 +77,12 @@ function ReasoningRoot({
   const onOpenChangeRef = useRef(onOpenChange);
   onOpenChangeRef.current = onOpenChange;
 
-  const setOpen = (next: boolean) => {
+  const setOpen = (
+    next: boolean,
+    eventDetails: CollapsiblePrimitive.Root.ChangeEventDetails
+  ) => {
     setOpenUnwrapped(next);
-    onOpenChangeRef.current?.(next);
+    onOpenChangeRef.current?.(next, eventDetails);
   };
 
   // Auto-open while streaming and auto-collapse on completion, but hand the
@@ -85,7 +94,7 @@ function ReasoningRoot({
     if (prevStreamingRef.current === streaming) return;
     prevStreamingRef.current = streaming;
     if (userToggledRef.current) return;
-    setOpenRef.current(streaming);
+    setOpenRef.current(streaming, createChangeEventDetails(REASONS.none));
   }, [streaming]);
 
   const contextValue = useMemo<ReasoningContextValue>(
@@ -98,9 +107,9 @@ function ReasoningRoot({
       <Collapsible
         className={cx(styles.reasoning, className)}
         open={open}
-        onOpenChange={next => {
+        onOpenChange={(next, eventDetails) => {
           userToggledRef.current = true;
-          setOpen(next);
+          setOpen(next, eventDetails);
         }}
         data-slot='reasoning'
         {...props}
diff --git a/packages/react/components/select/__tests__/select.test.tsx b/packages/react/components/select/__tests__/select.test.tsx
index 8349a4200..f0909d632 100644
--- a/packages/react/components/select/__tests__/select.test.tsx
+++ b/packages/react/components/select/__tests__/select.test.tsx
@@ -110,7 +110,10 @@ describe('Select', () => {
       await user.click(options[1]);
       await flushMicrotasks();
 
-      expect(handleValueChange).toHaveBeenCalledWith('banana');
+      expect(handleValueChange).toHaveBeenCalledWith(
+        'banana',
+        expect.objectContaining({ reason: 'item-press' })
+      );
       expect(handleValueChange).toHaveBeenCalledTimes(1);
     });
 
@@ -141,11 +144,17 @@ describe('Select', () => {
 
       await user.click(options[1]);
       await flushMicrotasks();
-      expect(handleValueChange).toHaveBeenCalledWith(['banana']);
+      expect(handleValueChange).toHaveBeenCalledWith(
+        ['banana'],
+        expect.anything()
+      );
 
       await user.click(options[4]);
       await flushMicrotasks();
-      expect(handleValueChange).toHaveBeenCalledWith(['banana', 'pineapple']);
+      expect(handleValueChange).toHaveBeenCalledWith(
+        ['banana', 'pineapple'],
+        expect.anything()
+      );
 
       const optionsAfterSelection = screen.getAllByRole('option');
       expect(optionsAfterSelection[1]).toHaveAttribute('aria-selected', 'true');
@@ -162,11 +171,14 @@ describe('Select', () => {
 
       await user.click(options[1]);
       await flushMicrotasks();
-      expect(handleValueChange).toHaveBeenCalledWith(['banana']);
+      expect(handleValueChange).toHaveBeenCalledWith(
+        ['banana'],
+        expect.anything()
+      );
 
       await user.click(options[1]);
       await flushMicrotasks();
-      expect(handleValueChange).toHaveBeenCalledWith([]);
+      expect(handleValueChange).toHaveBeenCalledWith([], expect.anything());
     });
 
     it('renders a checkbox indicator that reflects selection state', async () => {
@@ -246,7 +258,10 @@ describe('Select', () => {
       await user.keyboard('{Enter}');
       await flushMicrotasks();
 
-      expect(handleValueChange).toHaveBeenCalledWith('banana');
+      expect(handleValueChange).toHaveBeenCalledWith(
+        'banana',
+        expect.anything()
+      );
       expect(handleValueChange).toHaveBeenCalledTimes(1);
     });
 
@@ -264,7 +279,10 @@ describe('Select', () => {
       await user.keyboard('{ArrowDown}{ArrowDown}{Enter}');
       await flushMicrotasks();
 
-      expect(handleValueChange).toHaveBeenCalledWith('blueberry');
+      expect(handleValueChange).toHaveBeenCalledWith(
+        'blueberry',
+        expect.anything()
+      );
     });
   });
 
diff --git a/packages/react/components/select/select-root.tsx b/packages/react/components/select/select-root.tsx
index 5a0321ecf..fe33879d7 100644
--- a/packages/react/components/select/select-root.tsx
+++ b/packages/react/components/select/select-root.tsx
@@ -59,11 +59,19 @@ export const useSelectContext = (): UseSelectContext => {
   };
 };
 
+/** Base UI's `eventDetails`, from Combobox when `autocomplete` is set. */
+export type SelectChangeEventDetails =
+  | SelectPrimitive.Root.ChangeEventDetails
+  | ComboboxPrimitive.Root.ChangeEventDetails;
+
 export interface BaseSelectProps extends CommonProps {
   children?: ReactNode;
   open?: boolean;
   defaultOpen?: boolean;
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (
+    open: boolean,
+    eventDetails: SelectChangeEventDetails
+  ) => void;
   disabled?: boolean;
   required?: boolean;
   name?: string;
@@ -73,14 +81,20 @@ export interface BaseSelectProps extends CommonProps {
 export interface SingleSelectProps extends BaseSelectProps {
   multiple?: false;
   value?: string;
-  onValueChange?: (value: string) => void;
+  onValueChange?: (
+    value: string,
+    eventDetails: SelectChangeEventDetails
+  ) => void;
   defaultValue?: string;
 }
 
 export interface MultipleSelectProps extends BaseSelectProps {
   multiple: true;
   value?: string[];
-  onValueChange?: (value: string[]) => void;
+  onValueChange?: (
+    value: string[],
+    eventDetails: SelectChangeEventDetails
+  ) => void;
   defaultValue?: string[];
 }
 
@@ -130,15 +144,20 @@ export const SelectRoot = (props: SelectRootProps) => {
   >({});
 
   const handleValueChange = useCallback(
-    (value: string | string[] | null) => {
+    (
+      value: string | string[] | null,
+      eventDetails: SelectChangeEventDetails
+    ) => {
       setValueUnwrapped(value ?? undefined);
       if (multiple) {
         (onValueChange as MultipleSelectProps['onValueChange'])?.(
-          value as string[]
+          value as string[],
+          eventDetails
         );
       } else {
         (onValueChange as SingleSelectProps['onValueChange'])?.(
-          value as string
+          value as string,
+          eventDetails
         );
       }
     },
@@ -154,8 +173,8 @@ export const SelectRoot = (props: SelectRootProps) => {
   );
 
   const handleOpenChange = useCallback(
-    (open: boolean) => {
-      onOpenChange?.(open);
+    (open: boolean, eventDetails: SelectChangeEventDetails) => {
+      onOpenChange?.(open, eventDetails);
     },
     [onOpenChange]
   );
diff --git a/packages/react/components/sidebar/__tests__/sidebar.test.tsx b/packages/react/components/sidebar/__tests__/sidebar.test.tsx
index 381e2772d..902b4638d 100644
--- a/packages/react/components/sidebar/__tests__/sidebar.test.tsx
+++ b/packages/react/components/sidebar/__tests__/sidebar.test.tsx
@@ -132,7 +132,10 @@ describe('Sidebar', () => {
       const handle = screen.getByRole('button', { name: COLLAPSE_TEXT });
       fireEvent.click(handle);
 
-      expect(onOpenChange).toHaveBeenCalledWith(false);
+      expect(onOpenChange).toHaveBeenCalledWith(
+        false,
+        expect.objectContaining({ reason: 'trigger-press' })
+      );
     });
 
     it('supports keyboard navigation on handle', async () => {
@@ -144,7 +147,7 @@ describe('Sidebar', () => {
       handle.focus();
       await user.keyboard('{Enter}');
 
-      expect(onOpenChange).toHaveBeenCalledWith(false);
+      expect(onOpenChange).toHaveBeenCalledWith(false, expect.anything());
     });
 
     it('supports space key on handle', async () => {
@@ -156,7 +159,7 @@ describe('Sidebar', () => {
       handle.focus();
       await user.keyboard(' ');
 
-      expect(onOpenChange).toHaveBeenCalledWith(false);
+      expect(onOpenChange).toHaveBeenCalledWith(false, expect.anything());
     });
 
     it('shows a custom handle tooltip via collapseTooltip', async () => {
@@ -358,7 +361,7 @@ describe('Sidebar', () => {
       const handle = screen.getByRole('button', { name: 'Expand sidebar' });
       fireEvent.click(handle);
 
-      expect(onOpenChange).toHaveBeenCalledWith(true);
+      expect(onOpenChange).toHaveBeenCalledWith(true, expect.anything());
     });
 
     it('flips the visual open state so collapse-hiding styles turn off', async () => {
@@ -887,7 +890,10 @@ describe('Sidebar', () => {
 
       const trigger = screen.getByRole('button', { name: /Main/ });
       fireEvent.click(trigger);
-      expect(onOpenChange).toHaveBeenCalledWith(true);
+      expect(onOpenChange).toHaveBeenCalledWith(
+        true,
+        expect.objectContaining({ reason: 'trigger-press' })
+      );
       expect(screen.queryByText(DASHBOARD_ITEM_TEXT)).not.toBeInTheDocument();
 
       rerender(
@@ -930,11 +936,11 @@ describe('Sidebar', () => {
 
       const trigger = screen.getByRole('button', { name: /Main/ });
       fireEvent.click(trigger);
-      expect(onOpenChange).toHaveBeenLastCalledWith(false);
+      expect(onOpenChange).toHaveBeenLastCalledWith(false, expect.anything());
       expect(screen.queryByText(DASHBOARD_ITEM_TEXT)).not.toBeInTheDocument();
 
       fireEvent.click(trigger);
-      expect(onOpenChange).toHaveBeenLastCalledWith(true);
+      expect(onOpenChange).toHaveBeenLastCalledWith(true, expect.anything());
       expect(screen.getByText(DASHBOARD_ITEM_TEXT)).toBeInTheDocument();
     });
 
@@ -1091,7 +1097,10 @@ describe('Sidebar', () => {
       );
 
       fireEvent.click(screen.getByTestId('sidebar-trigger'));
-      expect(onOpenChange).toHaveBeenCalledWith(false);
+      expect(onOpenChange).toHaveBeenCalledWith(
+        false,
+        expect.objectContaining({ reason: 'trigger-press' })
+      );
     });
 
     it('is disabled when the sidebar is not collapsible', () => {
diff --git a/packages/react/components/sidebar/sidebar-group.tsx b/packages/react/components/sidebar/sidebar-group.tsx
index 076e4acc3..212b7692e 100644
--- a/packages/react/components/sidebar/sidebar-group.tsx
+++ b/packages/react/components/sidebar/sidebar-group.tsx
@@ -21,7 +21,10 @@ export interface SidebarGroupProps extends ComponentProps<'section'> {
   collapsible?: boolean;
   open?: boolean;
   defaultOpen?: boolean;
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (
+    open: boolean,
+    eventDetails: AccordionPrimitive.Root.ChangeEventDetails
+  ) => void;
   leadingIcon?: ReactNode;
   trailingIcon?: ReactNode;
   /** @deprecated Every key here has an equivalent `[data-slot]`. See the Slots table in the Sidebar docs. */
@@ -66,11 +69,14 @@ export function SidebarNavigationGroup({
   const isOpen = isCollapsed || open;
 
   const handleOpenChange = useCallback(
-    (value: unknown[]) => {
+    (
+      value: unknown[],
+      eventDetails: AccordionPrimitive.Root.ChangeEventDetails
+    ) => {
       if (isCollapsed) return;
       const nextOpen = value.length > 0;
       setOpenUnwrapped(nextOpen);
-      onOpenChange?.(nextOpen);
+      onOpenChange?.(nextOpen, eventDetails);
     },
     [isCollapsed, onOpenChange, setOpenUnwrapped]
   );
diff --git a/packages/react/components/sidebar/sidebar-root.tsx b/packages/react/components/sidebar/sidebar-root.tsx
index a94f5a1e5..2e3a18a98 100644
--- a/packages/react/components/sidebar/sidebar-root.tsx
+++ b/packages/react/components/sidebar/sidebar-root.tsx
@@ -14,14 +14,20 @@ import {
   useRef,
   useState
 } from 'react';
+import {
+  type ChangeDetails,
+  createChangeDetails
+} from '~/shared/change-details';
 import { Tooltip } from '../tooltip';
 import styles from './sidebar.module.css';
 
+export type SidebarOpenChangeDetails = ChangeDetails<'trigger-press' | 'none'>;
+
 export interface SidebarContextValue {
   isCollapsed: boolean;
   isPeeking: boolean;
   open: boolean;
-  setOpen: (open: boolean) => void;
+  setOpen: (open: boolean, details?: SidebarOpenChangeDetails) => void;
   /** Mirrors the `collapsible` prop; `'none'` means it cannot be collapsed. */
   collapsible: 'icon' | 'hidden' | 'none';
   position: 'left' | 'right';
@@ -103,7 +109,7 @@ export interface SidebarRootProps extends ComponentProps<'aside'> {
   collapseTooltip?: ReactNode;
   open?: boolean;
   defaultOpen?: boolean;
-  onOpenChange?: (open: boolean) => void;
+  onOpenChange?: (open: boolean, details: SidebarOpenChangeDetails) => void;
 }
 
 const DEFAULT_PEEK_DELAY = 100;
@@ -141,9 +147,12 @@ export function SidebarRoot({
   const pointerInsideRef = useRef(false);
 
   const handleOpenChange = useCallback(
-    (value: boolean) => {
+    (
+      value: boolean,
+      details: SidebarOpenChangeDetails = createChangeDetails('none')
+    ) => {
       setOpenUnwrapped(value);
-      onOpenChange?.(value);
+      onOpenChange?.(value, details);
     },
     [onOpenChange, setOpenUnwrapped]
   );
@@ -245,7 +254,12 @@ export function SidebarRoot({
                     type='button'
                     className={styles['resize-handle']}
                     data-slot='sidebar-toggle'
-                    onClick={() => handleOpenChange(!open)}
+                    onClick={event =>
+                      handleOpenChange(
+                        !open,
+                        createChangeDetails('trigger-press', event.nativeEvent)
+                      )
+                    }
                     aria-label={open ? 'Collapse sidebar' : 'Expand sidebar'}
                     aria-expanded={open}
                     aria-controls={sidebarId}
diff --git a/packages/react/components/sidebar/sidebar-trigger.tsx b/packages/react/components/sidebar/sidebar-trigger.tsx
index 83fa1891d..d91627ead 100644
--- a/packages/react/components/sidebar/sidebar-trigger.tsx
+++ b/packages/react/components/sidebar/sidebar-trigger.tsx
@@ -3,6 +3,7 @@
 import type { BaseUIEvent } from '@base-ui/react/types';
 import { MouseEvent, ReactNode, useCallback } from 'react';
 import { PanelLeftIcon } from '~/icons';
+import { createChangeDetails } from '~/shared/change-details';
 import { IconButton, IconButtonProps } from '../icon-button/icon-button';
 import { useSidebar } from './sidebar-root';
 
@@ -26,7 +27,7 @@ export function SidebarTrigger({
     (event: BaseUIEvent<MouseEvent<HTMLButtonElement>>) => {
       onClick?.(event);
       if (!event.defaultPrevented) {
-        setOpen(!open);
+        setOpen(!open, createChangeDetails('trigger-press', event.nativeEvent));
       }
     },
     [onClick, open, setOpen]
diff --git a/packages/react/components/text-area/__tests__/text-area.test.tsx b/packages/react/components/text-area/__tests__/text-area.test.tsx
index a8d6e274e..e353a2856 100644
--- a/packages/react/components/text-area/__tests__/text-area.test.tsx
+++ b/packages/react/components/text-area/__tests__/text-area.test.tsx
@@ -66,8 +66,10 @@ describe('TextArea', () => {
 
       fireEvent.change(textarea, { target: { value: 'hello' } });
       expect(handleValueChange).toHaveBeenCalledTimes(1);
-      expect(handleValueChange.mock.calls[0][0]).toBe('hello');
-      expect(handleValueChange.mock.calls[0][1]).toBeDefined();
+      expect(handleValueChange).toHaveBeenCalledWith(
+        'hello',
+        expect.objectContaining({ reason: 'none', event: expect.any(Event) })
+      );
     });
 
     it('calls both onChange and onValueChange', () => {
diff --git a/packages/react/components/text-area/text-area.tsx b/packages/react/components/text-area/text-area.tsx
index 33c2ad180..49d740478 100644
--- a/packages/react/components/text-area/text-area.tsx
+++ b/packages/react/components/text-area/text-area.tsx
@@ -1,4 +1,7 @@
 import { Field as FieldPrimitive } from '@base-ui/react/field';
+import type { Input as InputPrimitive } from '@base-ui/react/input';
+import { createChangeEventDetails } from '@base-ui/react/internals/createBaseUIEventDetails';
+import { REASONS } from '@base-ui/react/internals/reasons';
 import { cva, cx, type VariantProps } from 'class-variance-authority';
 import { ChangeEvent, type ComponentProps } from 'react';
 import { radiusVariants } from '../../shared/radius';
@@ -33,7 +36,7 @@ export interface TextAreaProps
   onChange?: (event: ChangeEvent<HTMLTextAreaElement>) => void;
   onValueChange?: (
     value: string,
-    event: ChangeEvent<HTMLTextAreaElement>
+    eventDetails: InputPrimitive.ChangeEventDetails
   ) => void;
 }
 
@@ -55,7 +58,10 @@ export function TextArea({
 
   const handleChange = (event: ChangeEvent<HTMLTextAreaElement>) => {
     onChange?.(event);
-    onValueChange?.(event.target.value, event);
+    onValueChange?.(
+      event.target.value,
+      createChangeEventDetails(REASONS.none, event.nativeEvent)
+    );
   };
 
   const textarea = (
diff --git a/packages/react/shared/change-details.ts b/packages/react/shared/change-details.ts
new file mode 100644
index 000000000..ea381811b
--- /dev/null
+++ b/packages/react/shared/change-details.ts
@@ -0,0 +1,30 @@
+import type { BaseUIGenericEventDetails } from '@base-ui/react/types';
+
+/**
+ * The second argument of a change callback on a component that owns its state.
+ * It has the `reason` and `event` of Base UI's `eventDetails`, plus the
+ * component's own fields.
+ */
+export type ChangeDetails<
+  Reason extends string = string,
+  Custom extends object = {}
+> = BaseUIGenericEventDetails<Reason, Custom>;
+
+/**
+ * Creates a `ChangeDetails`. Without an event, `event` is a new `Event`, as in
+ * Base UI.
+ */
+export function createChangeDetails<
+  Reason extends string,
+  Custom extends object = {}
+>(
+  reason: Reason,
+  event?: Event,
+  custom?: Custom
+): ChangeDetails<Reason, Custom> {
+  return {
+    reason,
+    event: event ?? new Event('apsara'),
+    ...custom
+  } as ChangeDetails<Reason, Custom>;
+}

From 084e9aa7d44c0ade883595dea06629945a52b429 Mon Sep 17 00:00:00 2001
From: Rohan Chakraborty <irohan1999@gmail.com>
Date: Tue, 20 Oct 2026 14:26:18 +0530
Subject: [PATCH 2/3] fix: keep state when a change callback cancels the change

---
 .../react/components/combobox/combobox-root.tsx  |  6 ++++--
 .../context-menu/context-menu-root.tsx           |  6 ++++--
 packages/react/components/menu/menu-root.tsx     |  6 ++++--
 .../react/components/reasoning/reasoning.tsx     |  3 ++-
 .../components/select/__tests__/select.test.tsx  | 16 ++++++++++++++++
 packages/react/components/select/select-root.tsx | 12 +++---------
 .../react/components/sidebar/sidebar-group.tsx   |  3 ++-
 7 files changed, 35 insertions(+), 17 deletions(-)

diff --git a/packages/react/components/combobox/combobox-root.tsx b/packages/react/components/combobox/combobox-root.tsx
index 24468b0a3..3be458c91 100644
--- a/packages/react/components/combobox/combobox-root.tsx
+++ b/packages/react/components/combobox/combobox-root.tsx
@@ -117,8 +117,9 @@ export const ComboboxRoot = <Value extends unknown | unknown[], Item = Value>({
       value: string,
       eventDetails: ComboboxPrimitive.Root.ChangeEventDetails
     ) => {
-      setInputValueUnwrapped(value);
       onInputValueChange?.(value, eventDetails);
+      if (eventDetails.isCanceled) return;
+      setInputValueUnwrapped(value);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
@@ -128,7 +129,6 @@ export const ComboboxRoot = <Value extends unknown | unknown[], Item = Value>({
       value: Value | Value[] | null,
       eventDetails: ComboboxPrimitive.Root.ChangeEventDetails
     ) => {
-      setValueUnwrapped(value);
       if (multiple) {
         (onValueChange as MultipleComboboxProps<Value>['onValueChange'])?.(
           value as Value[],
@@ -140,6 +140,8 @@ export const ComboboxRoot = <Value extends unknown | unknown[], Item = Value>({
           eventDetails
         );
       }
+      if (eventDetails.isCanceled) return;
+      setValueUnwrapped(value);
     },
     [onValueChange, multiple, setValueUnwrapped]
   );
diff --git a/packages/react/components/context-menu/context-menu-root.tsx b/packages/react/components/context-menu/context-menu-root.tsx
index 1efcba8d6..c3486b43e 100644
--- a/packages/react/components/context-menu/context-menu-root.tsx
+++ b/packages/react/components/context-menu/context-menu-root.tsx
@@ -67,8 +67,9 @@ export const ContextMenuRoot = ({
       value: string,
       eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
     ) => {
-      setInputValueUnwrapped(value);
       onInputValueChange?.(value, eventDetails);
+      if (eventDetails.isCanceled) return;
+      setInputValueUnwrapped(value);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
@@ -174,8 +175,9 @@ export const ContextMenuSubMenu = ({
       value: string,
       eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
     ) => {
-      setInputValueUnwrapped(value);
       onInputValueChange?.(value, eventDetails);
+      if (eventDetails.isCanceled) return;
+      setInputValueUnwrapped(value);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
diff --git a/packages/react/components/menu/menu-root.tsx b/packages/react/components/menu/menu-root.tsx
index b1a3c34cc..0e173db1d 100644
--- a/packages/react/components/menu/menu-root.tsx
+++ b/packages/react/components/menu/menu-root.tsx
@@ -129,8 +129,9 @@ export const MenuRoot = ({
       value: string,
       eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
     ) => {
-      setInputValueUnwrapped(value);
       onInputValueChange?.(value, eventDetails);
+      if (eventDetails.isCanceled) return;
+      setInputValueUnwrapped(value);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
@@ -234,8 +235,9 @@ export const MenuSubMenu = ({
       value: string,
       eventDetails: AutocompletePrimitive.Root.ChangeEventDetails
     ) => {
-      setInputValueUnwrapped(value);
       onInputValueChange?.(value, eventDetails);
+      if (eventDetails.isCanceled) return;
+      setInputValueUnwrapped(value);
     },
     [onInputValueChange, setInputValueUnwrapped]
   );
diff --git a/packages/react/components/reasoning/reasoning.tsx b/packages/react/components/reasoning/reasoning.tsx
index 89967af84..58f6f50c8 100644
--- a/packages/react/components/reasoning/reasoning.tsx
+++ b/packages/react/components/reasoning/reasoning.tsx
@@ -81,8 +81,9 @@ function ReasoningRoot({
     next: boolean,
     eventDetails: CollapsiblePrimitive.Root.ChangeEventDetails
   ) => {
-    setOpenUnwrapped(next);
     onOpenChangeRef.current?.(next, eventDetails);
+    if (eventDetails.isCanceled) return;
+    setOpenUnwrapped(next);
   };
 
   // Auto-open while streaming and auto-collapse on completion, but hand the
diff --git a/packages/react/components/select/__tests__/select.test.tsx b/packages/react/components/select/__tests__/select.test.tsx
index f0909d632..9ad39f6fa 100644
--- a/packages/react/components/select/__tests__/select.test.tsx
+++ b/packages/react/components/select/__tests__/select.test.tsx
@@ -117,6 +117,22 @@ describe('Select', () => {
       expect(handleValueChange).toHaveBeenCalledTimes(1);
     });
 
+    it('keeps the value when onValueChange cancels the change', async () => {
+      render(
+        <BasicSelect
+          defaultValue='apple'
+          onValueChange={(_, eventDetails) => eventDetails.cancel()}
+        />
+      );
+      const user = userEvent.setup();
+      await openSelect(user);
+
+      await user.click(screen.getAllByRole('option')[1]);
+      await flushMicrotasks();
+
+      expect(screen.getByRole('combobox')).toHaveTextContent('Apple');
+    });
+
     it('closes content after selection', async () => {
       render(<BasicSelect />);
       const user = userEvent.setup();
diff --git a/packages/react/components/select/select-root.tsx b/packages/react/components/select/select-root.tsx
index fe33879d7..7068255b8 100644
--- a/packages/react/components/select/select-root.tsx
+++ b/packages/react/components/select/select-root.tsx
@@ -148,7 +148,6 @@ export const SelectRoot = (props: SelectRootProps) => {
       value: string | string[] | null,
       eventDetails: SelectChangeEventDetails
     ) => {
-      setValueUnwrapped(value ?? undefined);
       if (multiple) {
         (onValueChange as MultipleSelectProps['onValueChange'])?.(
           value as string[],
@@ -160,6 +159,8 @@ export const SelectRoot = (props: SelectRootProps) => {
           eventDetails
         );
       }
+      if (eventDetails.isCanceled) return;
+      setValueUnwrapped(value ?? undefined);
     },
     [multiple, onValueChange, setValueUnwrapped]
   );
@@ -172,13 +173,6 @@ export const SelectRoot = (props: SelectRootProps) => {
     [onSearch, setSearchValueUnwrapped]
   );
 
-  const handleOpenChange = useCallback(
-    (open: boolean, eventDetails: SelectChangeEventDetails) => {
-      onOpenChange?.(open, eventDetails);
-    },
-    [onOpenChange]
-  );
-
   const registerItem = useCallback<SelectContextValue['registerItem']>(item => {
     setRegisteredItems(prev => ({ ...prev, [item.value]: item }));
   }, []);
@@ -224,7 +218,7 @@ export const SelectRoot = (props: SelectRootProps) => {
     onValueChange: handleValueChange,
     open: providedOpen,
     defaultOpen,
-    onOpenChange: handleOpenChange,
+    onOpenChange,
     multiple,
     disabled,
     modal: true as const,
diff --git a/packages/react/components/sidebar/sidebar-group.tsx b/packages/react/components/sidebar/sidebar-group.tsx
index 212b7692e..6256c8478 100644
--- a/packages/react/components/sidebar/sidebar-group.tsx
+++ b/packages/react/components/sidebar/sidebar-group.tsx
@@ -75,8 +75,9 @@ export function SidebarNavigationGroup({
     ) => {
       if (isCollapsed) return;
       const nextOpen = value.length > 0;
-      setOpenUnwrapped(nextOpen);
       onOpenChange?.(nextOpen, eventDetails);
+      if (eventDetails.isCanceled) return;
+      setOpenUnwrapped(nextOpen);
     },
     [isCollapsed, onOpenChange, setOpenUnwrapped]
   );

From 5b27067fe355c17e4fa4e122a92fa55348372f22 Mon Sep 17 00:00:00 2001
From: Rohan Chakraborty <irohan1999@gmail.com>
Date: Tue, 20 Oct 2026 14:26:19 +0530
Subject: [PATCH 3/3] fix: [docs] scope the change callback notes to the
 changed callbacks

---
 .agents/skills/apsara/references/composition.md    | 2 +-
 apps/www/src/content/docs/(overview)/upgrading.mdx | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/apsara/references/composition.md b/.agents/skills/apsara/references/composition.md
index 82ed00651..635416cab 100644
--- a/.agents/skills/apsara/references/composition.md
+++ b/.agents/skills/apsara/references/composition.md
@@ -65,7 +65,7 @@ const [open, setOpen] = useState(false);
 </Dialog>
 ```
 
-Change callbacks (`onValueChange`, `onOpenChange`, `onInputValueChange`, and the like) take the new value first and a details object second: Base UI's `eventDetails` on components that wrap Base UI, or `details` with the same `reason` and `event` on components that own their state. Component data is a field of that object, for example `details.mode` on `ColorPicker` and `details.operation` on `FilterChip`.
+Most change callbacks (`onValueChange`, `onOpenChange`, `onInputValueChange`, and the like) take the new value first and a details object second. Components that wrap Base UI pass Base UI's `eventDetails`. Other components pass their own `details`, for example `details.mode` on `ColorPicker` and `details.operation` on `FilterChip`. A few callbacks take only the value, for example CodeBlock `onValueChange` and ColorPicker `onModeChange`. Check the props table for the exact signature.
 
 Several overlay roots (`Dialog`, `Menu`, `Popover`, `Tooltip`) also expose `createHandle` for advanced imperative open/close from outside the subtree — use only when a trigger can't live in the same tree.
 
diff --git a/apps/www/src/content/docs/(overview)/upgrading.mdx b/apps/www/src/content/docs/(overview)/upgrading.mdx
index efbd3ec3f..d7ca84e3b 100644
--- a/apps/www/src/content/docs/(overview)/upgrading.mdx
+++ b/apps/www/src/content/docs/(overview)/upgrading.mdx
@@ -9,7 +9,7 @@ on [GitHub releases](https://github.com/raystack/apsara/releases).
 
 ## Unreleased: change callbacks get a details object
 
-Every change callback now passes a second argument after the value. A
+The change callbacks below pass a second argument after the value. A
 component that wraps Base UI passes Base UI's `eventDetails`. A component that
 keeps its own state passes a `details` object with the same `reason` and
 `event` fields, plus any field of its own.