@toptal/picasso-shared 16.0.0 → 16.0.1-alpha-pf-fix-alpha-release-4de9263c3.0

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

@@ -1,4 +1,6 @@
 export { default as isBrowser } from './is-browser';
 export { default as getElementById } from './get-element-by-id';
 export { default as isForwardRef } from './is-forward-ref';
+export { default as toReactEvent } from './to-react-event';
+export { default as toReactChangeEvent } from './to-react-change-event';
 //# sourceMappingURL=index.d.ts.map

package/dist-package/src/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist-package/src/utils/index.js

@@ -1,4 +1,6 @@
 export { default as isBrowser } from './is-browser';
 export { default as getElementById } from './get-element-by-id';
 export { default as isForwardRef } from './is-forward-ref';
+export { default as toReactEvent } from './to-react-event';
+export { default as toReactChangeEvent } from './to-react-change-event';
 //# sourceMappingURL=index.js.map

package/dist-package/src/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist-package/src/utils/to-react-change-event.d.ts

@@ -0,0 +1,19 @@
+import type React from 'react';
+type FormInputElement = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+/**
+ * Boundary cast for form-component `onChange` adapters. Specialization of
+ * `toReactEvent` with a tighter generic constraint (form-input elements only)
+ * and a dev-only sanity check on the event target.
+ *
+ * Use in `onCheckedChange` / `onValueChange` adapters when bridging
+ * `@base-ui/react`'s native DOM `Event` to Picasso's `React.ChangeEvent<T>`
+ * public type.
+ *
+ * @example
+ *   onCheckedChange={(checked, { event }) =>
+ *     onChange?.(toReactChangeEvent<HTMLInputElement>(event), checked)
+ *   }
+ */
+declare const toReactChangeEvent: <T extends FormInputElement = HTMLInputElement>(event: Event) => React.ChangeEvent<T>;
+export default toReactChangeEvent;
+//# sourceMappingURL=to-react-change-event.d.ts.map

package/dist-package/src/utils/to-react-change-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-react-change-event.d.ts","sourceRoot":"","sources":["../../../src/utils/to-react-change-event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B,KAAK,gBAAgB,GACjB,gBAAgB,GAChB,mBAAmB,GACnB,iBAAiB,CAAA;AAErB;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,kBAAkB,GAAI,CAAC,SAAS,gBAAgB,4BAC7C,KAAK,KACX,KAAK,CAAC,WAAW,CAAC,CAAC,CAcrB,CAAA;AAED,eAAe,kBAAkB,CAAA"}

package/dist-package/src/utils/to-react-change-event.js

@@ -0,0 +1,28 @@
+import toReactEvent from './to-react-event';
+/**
+ * Boundary cast for form-component `onChange` adapters. Specialization of
+ * `toReactEvent` with a tighter generic constraint (form-input elements only)
+ * and a dev-only sanity check on the event target.
+ *
+ * Use in `onCheckedChange` / `onValueChange` adapters when bridging
+ * `@base-ui/react`'s native DOM `Event` to Picasso's `React.ChangeEvent<T>`
+ * public type.
+ *
+ * @example
+ *   onCheckedChange={(checked, { event }) =>
+ *     onChange?.(toReactChangeEvent<HTMLInputElement>(event), checked)
+ *   }
+ */
+const toReactChangeEvent = (event) => {
+    if (process.env.NODE_ENV !== 'production') {
+        const target = event.target;
+        if (target === null || !('tagName' in target)) {
+            // eslint-disable-next-line no-console
+            console.warn('[picasso] toReactChangeEvent: event.target is not a DOM element. ' +
+                'Consumer onChange may receive an unexpected event shape.');
+        }
+    }
+    return toReactEvent(event);
+};
+export default toReactChangeEvent;
+//# sourceMappingURL=to-react-change-event.js.map

package/dist-package/src/utils/to-react-change-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-react-change-event.js","sourceRoot":"","sources":["../../../src/utils/to-react-change-event.ts"],"names":[],"mappings":"AAEA,OAAO,YAAY,MAAM,kBAAkB,CAAA;AAO3C;;;;;;;;;;;;;GAaG;AACH,MAAM,kBAAkB,GAAG,CACzB,KAAY,EACU,EAAE;IACxB,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAwB,CAAA;QAE7C,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,SAAS,IAAI,MAAM,CAAC,EAAE,CAAC;YAC9C,sCAAsC;YACtC,OAAO,CAAC,IAAI,CACV,mEAAmE;gBACjE,0DAA0D,CAC7D,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAuB,KAAK,CAAC,CAAA;AAClD,CAAC,CAAA;AAED,eAAe,kBAAkB,CAAA"}

package/dist-package/src/utils/to-react-event.d.ts

@@ -0,0 +1,33 @@
+import type React from 'react';
+/**
+ * Boundary cast at the `@base-ui/react` ↔ Picasso form-component interface.
+ *
+ * `@base-ui/react` v1 callbacks surface the native DOM `Event` via
+ * `eventDetails.event`. Picasso's public `onChange` / `onClick` / etc. types
+ * pre-date the migration and expect React-flavored `React.SyntheticEvent`
+ * variants (`React.ChangeEvent<T>`, `React.MouseEvent<T>`, …).
+ *
+ * React doesn't expose a public API to construct a real SyntheticEvent. This
+ * helper bridges the type boundary by returning a Proxy that:
+ *   - Forwards all native-event property access unchanged (identity preserved
+ *     for `target`, `currentTarget`, `bubbles`, `cancelable`, `defaultPrevented`,
+ *     `type`, `timeStamp`, `isTrusted`, `preventDefault`, `stopPropagation`, etc.).
+ *   - Synthesizes the four React-SyntheticEvent shim methods that don't exist
+ *     on native events: `nativeEvent`, `persist`, `isDefaultPrevented`,
+ *     `isPropagationStopped`.
+ *   - Does NOT mutate the underlying native event (Proxy wraps; doesn't touch
+ *     the original).
+ *
+ * Runtime: O(1) Proxy allocation + per-access dispatch. No copying.
+ *
+ * Use the specialized `toReactChangeEvent<T>` helper for form-input `onChange`
+ * adapters (tighter generic constraint catches misuse). Use this primitive for
+ * non-change-event cases (Slider value events, MouseEvent adapters, etc.).
+ *
+ * @example
+ *   const reactEvent = toReactEvent<React.MouseEvent<HTMLButtonElement>>(nativeEvent)
+ *   onClick?.(reactEvent)
+ */
+declare const toReactEvent: <R extends React.SyntheticEvent>(event: Event) => R;
+export default toReactEvent;
+//# sourceMappingURL=to-react-event.d.ts.map

package/dist-package/src/utils/to-react-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-react-event.d.ts","sourceRoot":"","sources":["../../../src/utils/to-react-event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,QAAA,MAAM,YAAY,GAAI,CAAC,SAAS,KAAK,CAAC,cAAc,SAAS,KAAK,KAAG,CAyBjD,CAAA;AAEpB,eAAe,YAAY,CAAA"}

package/dist-package/src/utils/to-react-event.js

@@ -0,0 +1,56 @@
+const noop = () => { };
+/**
+ * Boundary cast at the `@base-ui/react` ↔ Picasso form-component interface.
+ *
+ * `@base-ui/react` v1 callbacks surface the native DOM `Event` via
+ * `eventDetails.event`. Picasso's public `onChange` / `onClick` / etc. types
+ * pre-date the migration and expect React-flavored `React.SyntheticEvent`
+ * variants (`React.ChangeEvent<T>`, `React.MouseEvent<T>`, …).
+ *
+ * React doesn't expose a public API to construct a real SyntheticEvent. This
+ * helper bridges the type boundary by returning a Proxy that:
+ *   - Forwards all native-event property access unchanged (identity preserved
+ *     for `target`, `currentTarget`, `bubbles`, `cancelable`, `defaultPrevented`,
+ *     `type`, `timeStamp`, `isTrusted`, `preventDefault`, `stopPropagation`, etc.).
+ *   - Synthesizes the four React-SyntheticEvent shim methods that don't exist
+ *     on native events: `nativeEvent`, `persist`, `isDefaultPrevented`,
+ *     `isPropagationStopped`.
+ *   - Does NOT mutate the underlying native event (Proxy wraps; doesn't touch
+ *     the original).
+ *
+ * Runtime: O(1) Proxy allocation + per-access dispatch. No copying.
+ *
+ * Use the specialized `toReactChangeEvent<T>` helper for form-input `onChange`
+ * adapters (tighter generic constraint catches misuse). Use this primitive for
+ * non-change-event cases (Slider value events, MouseEvent adapters, etc.).
+ *
+ * @example
+ *   const reactEvent = toReactEvent<React.MouseEvent<HTMLButtonElement>>(nativeEvent)
+ *   onClick?.(reactEvent)
+ */
+const toReactEvent = (event) => new Proxy(event, {
+    get(target, key) {
+        switch (key) {
+            case 'nativeEvent':
+                return target;
+            case 'persist':
+                // React 17+ removed event pooling; persist is a no-op in modern React.
+                return noop;
+            case 'isDefaultPrevented':
+                return () => target.defaultPrevented;
+            case 'isPropagationStopped':
+                // Native events don't track propagation-stop state after dispatch;
+                // returning false is safe for consumers checking "did I already stop?".
+                return () => false;
+            default: {
+                const value = Reflect.get(target, key, target);
+                // Native event methods (preventDefault, stopPropagation, …) must keep
+                // the native event as `this`; invoked through the Proxy they'd receive
+                // the Proxy as `this` and throw "Illegal invocation" in real browsers.
+                return typeof value === 'function' ? value.bind(target) : value;
+            }
+        }
+    },
+});
+export default toReactEvent;
+//# sourceMappingURL=to-react-event.js.map

package/dist-package/src/utils/to-react-event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-react-event.js","sourceRoot":"","sources":["../../../src/utils/to-react-event.ts"],"names":[],"mappings":"AAEA,MAAM,IAAI,GAAG,GAAS,EAAE,GAAE,CAAC,CAAA;AAE3B;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,YAAY,GAAG,CAAiC,KAAY,EAAK,EAAE,CACvE,IAAI,KAAK,CAAC,KAAK,EAAE;IACf,GAAG,CAAC,MAAM,EAAE,GAAG;QACb,QAAQ,GAAG,EAAE,CAAC;YACZ,KAAK,aAAa;gBAChB,OAAO,MAAM,CAAA;YACf,KAAK,SAAS;gBACZ,uEAAuE;gBACvE,OAAO,IAAI,CAAA;YACb,KAAK,oBAAoB;gBACvB,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAA;YACtC,KAAK,sBAAsB;gBACzB,mEAAmE;gBACnE,wEAAwE;gBACxE,OAAO,GAAG,EAAE,CAAC,KAAK,CAAA;YACpB,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;gBAE9C,sEAAsE;gBACtE,uEAAuE;gBACvE,uEAAuE;gBACvE,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;YACjE,CAAC;QACH,CAAC;IACH,CAAC;CACF,CAAiB,CAAA;AAEpB,eAAe,YAAY,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toptal/picasso-shared",
-  "version": "16.0.0",
+  "version": "16.0.1-alpha-pf-fix-alpha-release-4de9263c3.0",
   "description": "Shared types, utils for Picasso internal usage",
   "author": "Toptal",
   "homepage": "https://github.com/toptal/picasso/tree/master/packages/picasso-shared#readme",
@@ -23,7 +23,7 @@
   "peerDependencies": {
     "react": ">=16.12.0 < 19.0.0",
     "typescript": "^5.5.0",
-    "@toptal/picasso-provider": "*",
+    "@toptal/picasso-provider": "6.0.1-alpha-pf-fix-alpha-release-4de9263c3.0",
     "notistack": "3.0.1",
     "react-dom": ">=16.12.0 < 19.0.0"
   },
@@ -35,7 +35,7 @@
   "devDependencies": {
     "@types/classnames": "^2.3.1",
     "notistack": "3.0.1",
-    "@toptal/picasso-provider": "6.0.0"
+    "@toptal/picasso-provider": "6.0.1-alpha-pf-fix-alpha-release-4de9263c3.0"
   },
   "sideEffects": [
     "**/styles.ts",

package/src/utils/index.ts

@@ -1,3 +1,5 @@
 export { default as isBrowser } from './is-browser'
 export { default as getElementById } from './get-element-by-id'
 export { default as isForwardRef } from './is-forward-ref'
+export { default as toReactEvent } from './to-react-event'
+export { default as toReactChangeEvent } from './to-react-change-event'

package/src/utils/test.ts

@@ -0,0 +1,186 @@
+import { toReactEvent, toReactChangeEvent } from './'
+
+describe('toReactEvent', () => {
+  const makeNativeChangeEvent = (target: HTMLInputElement): Event => {
+    const event = new Event('change', { bubbles: true, cancelable: true })
+
+    Object.defineProperty(event, 'target', { value: target, writable: false })
+
+    return event
+  }
+
+  let input: HTMLInputElement
+  let nativeEvent: Event
+
+  beforeEach(() => {
+    input = document.createElement('input')
+    input.type = 'checkbox'
+    input.checked = true
+    nativeEvent = makeNativeChangeEvent(input)
+  })
+
+  it('forwards native event properties unchanged', () => {
+    const result =
+      toReactEvent<React.ChangeEvent<HTMLInputElement>>(nativeEvent)
+
+    expect(result.type).toBe('change')
+    expect(result.target).toBe(input)
+    expect(result.bubbles).toBe(true)
+    expect(result.cancelable).toBe(true)
+    // Reading `target.checked` works because target IS the native input
+    expect(result.target.checked).toBe(true)
+  })
+
+  it('synthesizes `nativeEvent` to return the original event', () => {
+    const result =
+      toReactEvent<React.ChangeEvent<HTMLInputElement>>(nativeEvent)
+
+    expect(result.nativeEvent).toBe(nativeEvent)
+  })
+
+  it('synthesizes `persist` as a noop function', () => {
+    const result =
+      toReactEvent<React.ChangeEvent<HTMLInputElement>>(nativeEvent)
+
+    expect(typeof result.persist).toBe('function')
+    expect(() => result.persist()).not.toThrow()
+    expect(result.persist()).toBeUndefined()
+  })
+
+  it('synthesizes `isDefaultPrevented` to reflect native state', () => {
+    const result =
+      toReactEvent<React.ChangeEvent<HTMLInputElement>>(nativeEvent)
+
+    expect(result.isDefaultPrevented()).toBe(false)
+    nativeEvent.preventDefault()
+    expect(result.isDefaultPrevented()).toBe(true)
+  })
+
+  it('synthesizes `isPropagationStopped` to return false (native lacks the state)', () => {
+    const result =
+      toReactEvent<React.ChangeEvent<HTMLInputElement>>(nativeEvent)
+
+    expect(result.isPropagationStopped()).toBe(false)
+    nativeEvent.stopPropagation()
+    // Native events don't track propagation-stop state after dispatch.
+    // The shim returns `false` consistently; consumers checking
+    // "did I already stop?" get a safe default.
+    expect(result.isPropagationStopped()).toBe(false)
+  })
+
+  it('does not mutate the underlying native event', () => {
+    const nativeKeys = Object.keys(nativeEvent)
+
+    toReactEvent<React.ChangeEvent<HTMLInputElement>>(nativeEvent)
+
+    expect(Object.keys(nativeEvent)).toEqual(nativeKeys)
+  })
+
+  it('forwards method calls to the native event', () => {
+    const preventDefaultSpy = jest.spyOn(nativeEvent, 'preventDefault')
+    const stopPropagationSpy = jest.spyOn(nativeEvent, 'stopPropagation')
+
+    const result =
+      toReactEvent<React.ChangeEvent<HTMLInputElement>>(nativeEvent)
+
+    result.preventDefault()
+    result.stopPropagation()
+
+    expect(preventDefaultSpy).toHaveBeenCalled()
+    expect(stopPropagationSpy).toHaveBeenCalled()
+  })
+
+  it('binds native methods to the native event (avoids "Illegal invocation")', () => {
+    let probeBoundToNativeEvent = false
+
+    // A method that records whether its `this` is the native event. Native DOM
+    // methods (stopPropagation, …) throw "Illegal invocation" in real browsers
+    // when invoked with the Proxy as `this` instead of the native event.
+    ;(nativeEvent as unknown as { probe: () => void }).probe = function probe() {
+      probeBoundToNativeEvent = this === nativeEvent
+    }
+
+    const result =
+      toReactEvent<React.ChangeEvent<HTMLInputElement>>(nativeEvent)
+
+    ;(result as unknown as { probe: () => void }).probe()
+
+    expect(probeBoundToNativeEvent).toBe(true)
+  })
+})
+
+describe('toReactChangeEvent', () => {
+  const makeNativeChangeEvent = (target: EventTarget | null): Event => {
+    const event = new Event('change', { bubbles: true, cancelable: true })
+
+    Object.defineProperty(event, 'target', { value: target, writable: false })
+
+    return event
+  }
+
+  let consoleWarnSpy: jest.SpyInstance
+
+  beforeEach(() => {
+    consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation()
+  })
+
+  afterEach(() => {
+    consoleWarnSpy.mockRestore()
+  })
+
+  it('returns a React.ChangeEvent shape with the input target', () => {
+    const input = document.createElement('input')
+
+    input.type = 'text'
+    input.value = 'hello'
+    const nativeEvent = makeNativeChangeEvent(input)
+
+    const result = toReactChangeEvent<HTMLInputElement>(nativeEvent)
+
+    expect(result.target).toBe(input)
+    expect(result.target.value).toBe('hello')
+  })
+
+  it('defaults the generic to HTMLInputElement', () => {
+    const input = document.createElement('input')
+    const nativeEvent = makeNativeChangeEvent(input)
+
+    // No generic supplied — defaults to HTMLInputElement.
+    const result = toReactChangeEvent(nativeEvent)
+
+    // TypeScript should infer `result.target` as HTMLInputElement.
+    expect(result.target).toBe(input)
+  })
+
+  it('delegates to toReactEvent (inherits Proxy shim methods)', () => {
+    const input = document.createElement('input')
+    const nativeEvent = makeNativeChangeEvent(input)
+
+    const result = toReactChangeEvent<HTMLInputElement>(nativeEvent)
+
+    expect(result.nativeEvent).toBe(nativeEvent)
+    expect(typeof result.persist).toBe('function')
+    expect(result.isDefaultPrevented()).toBe(false)
+  })
+
+  it('emits a dev-warning when target is null', () => {
+    const nativeEvent = makeNativeChangeEvent(null)
+
+    toReactChangeEvent<HTMLInputElement>(nativeEvent)
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      expect.stringContaining(
+        'toReactChangeEvent: event.target is not a DOM element'
+      )
+    )
+  })
+
+  it('does not warn when target is a valid DOM element', () => {
+    const input = document.createElement('input')
+    const nativeEvent = makeNativeChangeEvent(input)
+
+    toReactChangeEvent<HTMLInputElement>(nativeEvent)
+
+    expect(consoleWarnSpy).not.toHaveBeenCalled()
+  })
+})

package/src/utils/to-react-change-event.ts

@@ -0,0 +1,42 @@
+import type React from 'react'
+
+import toReactEvent from './to-react-event'
+
+type FormInputElement =
+  | HTMLInputElement
+  | HTMLTextAreaElement
+  | HTMLSelectElement
+
+/**
+ * Boundary cast for form-component `onChange` adapters. Specialization of
+ * `toReactEvent` with a tighter generic constraint (form-input elements only)
+ * and a dev-only sanity check on the event target.
+ *
+ * Use in `onCheckedChange` / `onValueChange` adapters when bridging
+ * `@base-ui/react`'s native DOM `Event` to Picasso's `React.ChangeEvent<T>`
+ * public type.
+ *
+ * @example
+ *   onCheckedChange={(checked, { event }) =>
+ *     onChange?.(toReactChangeEvent<HTMLInputElement>(event), checked)
+ *   }
+ */
+const toReactChangeEvent = <T extends FormInputElement = HTMLInputElement>(
+  event: Event
+): React.ChangeEvent<T> => {
+  if (process.env.NODE_ENV !== 'production') {
+    const target = event.target as Element | null
+
+    if (target === null || !('tagName' in target)) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[picasso] toReactChangeEvent: event.target is not a DOM element. ' +
+          'Consumer onChange may receive an unexpected event shape.'
+      )
+    }
+  }
+
+  return toReactEvent<React.ChangeEvent<T>>(event)
+}
+
+export default toReactChangeEvent

package/src/utils/to-react-event.ts

@@ -0,0 +1,61 @@
+import type React from 'react'
+
+const noop = (): void => {}
+
+/**
+ * Boundary cast at the `@base-ui/react` ↔ Picasso form-component interface.
+ *
+ * `@base-ui/react` v1 callbacks surface the native DOM `Event` via
+ * `eventDetails.event`. Picasso's public `onChange` / `onClick` / etc. types
+ * pre-date the migration and expect React-flavored `React.SyntheticEvent`
+ * variants (`React.ChangeEvent<T>`, `React.MouseEvent<T>`, …).
+ *
+ * React doesn't expose a public API to construct a real SyntheticEvent. This
+ * helper bridges the type boundary by returning a Proxy that:
+ *   - Forwards all native-event property access unchanged (identity preserved
+ *     for `target`, `currentTarget`, `bubbles`, `cancelable`, `defaultPrevented`,
+ *     `type`, `timeStamp`, `isTrusted`, `preventDefault`, `stopPropagation`, etc.).
+ *   - Synthesizes the four React-SyntheticEvent shim methods that don't exist
+ *     on native events: `nativeEvent`, `persist`, `isDefaultPrevented`,
+ *     `isPropagationStopped`.
+ *   - Does NOT mutate the underlying native event (Proxy wraps; doesn't touch
+ *     the original).
+ *
+ * Runtime: O(1) Proxy allocation + per-access dispatch. No copying.
+ *
+ * Use the specialized `toReactChangeEvent<T>` helper for form-input `onChange`
+ * adapters (tighter generic constraint catches misuse). Use this primitive for
+ * non-change-event cases (Slider value events, MouseEvent adapters, etc.).
+ *
+ * @example
+ *   const reactEvent = toReactEvent<React.MouseEvent<HTMLButtonElement>>(nativeEvent)
+ *   onClick?.(reactEvent)
+ */
+const toReactEvent = <R extends React.SyntheticEvent>(event: Event): R =>
+  new Proxy(event, {
+    get(target, key) {
+      switch (key) {
+        case 'nativeEvent':
+          return target
+        case 'persist':
+          // React 17+ removed event pooling; persist is a no-op in modern React.
+          return noop
+        case 'isDefaultPrevented':
+          return () => target.defaultPrevented
+        case 'isPropagationStopped':
+          // Native events don't track propagation-stop state after dispatch;
+          // returning false is safe for consumers checking "did I already stop?".
+          return () => false
+        default: {
+          const value = Reflect.get(target, key, target)
+
+          // Native event methods (preventDefault, stopPropagation, …) must keep
+          // the native event as `this`; invoked through the Proxy they'd receive
+          // the Proxy as `this` and throw "Illegal invocation" in real browsers.
+          return typeof value === 'function' ? value.bind(target) : value
+        }
+      }
+    },
+  }) as unknown as R
+
+export default toReactEvent