@cdx-ui/utils 0.0.1-beta.64 → 0.0.1-beta.66

package/lib/commonjs/common/mergeRefs.js

@@ -4,15 +4,53 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.mergeRefs = mergeRefs;
+/**
+ * Merges multiple refs (object or callback) into a single callback ref.
+ *
+ * Supports React 19 ref-cleanup semantics: if an inner callback ref returns a
+ * cleanup function, that cleanup is captured and invoked when the merged ref is
+ * detached — either via the returned cleanup (React 19) or via a subsequent
+ * call with `null` (React 18 backward-compat path).
+ */
 function mergeRefs(...refs) {
   return value => {
+    if (value === null) {
+      for (const ref of refs) {
+        if (typeof ref === 'function') {
+          ref(null);
+        } else if (ref != null) {
+          ref.current = null;
+        }
+      }
+      return undefined;
+    }
+    const cleanups = [];
     for (const ref of refs) {
       if (typeof ref === 'function') {
-        ref(value);
+        cleanups.push(ref(value));
       } else if (ref != null) {
         ref.current = value;
+        cleanups.push(undefined);
+      } else {
+        cleanups.push(undefined);
       }
     }
+    return () => {
+      for (let i = 0; i < refs.length; i++) {
+        const ref = refs[i];
+        if (ref == null) continue;
+        if (typeof ref === 'function') {
+          const refCleanup = cleanups[i];
+          if (typeof refCleanup === 'function') {
+            refCleanup();
+          } else {
+            ref(null);
+          }
+        } else {
+          ref.current = null;
+        }
+      }
+    };
   };
 }
 //# sourceMappingURL=mergeRefs.js.map

package/lib/commonjs/common/mergeRefs.js.map

@@ -1 +1 @@
-{"version":3,"names":["mergeRefs","refs","value","ref","current"],"sourceRoot":"../../../src","sources":["common/mergeRefs.ts"],"mappings":";;;;;;AAEO,SAASA,SAASA,CAAI,GAAGC,IAA4B,EAAkB;EAC5E,OAAQC,KAAe,IAAK;IAC1B,KAAK,MAAMC,GAAG,IAAIF,IAAI,EAAE;MACtB,IAAI,OAAOE,GAAG,KAAK,UAAU,EAAE;QAC7BA,GAAG,CAACD,KAAK,CAAC;MACZ,CAAC,MAAM,IAAIC,GAAG,IAAI,IAAI,EAAE;QACtBA,GAAG,CAACC,OAAO,GAAGF,KAAK;MACrB;IACF;EACF,CAAC;AACH","ignoreList":[]}
+{"version":3,"names":["mergeRefs","refs","value","ref","current","undefined","cleanups","push","i","length","refCleanup"],"sourceRoot":"../../../src","sources":["common/mergeRefs.ts"],"mappings":";;;;;;AAIA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASA,SAASA,CAAI,GAAGC,IAA4B,EAAkB;EAC5E,OAAQC,KAAe,IAA4B;IACjD,IAAIA,KAAK,KAAK,IAAI,EAAE;MAClB,KAAK,MAAMC,GAAG,IAAIF,IAAI,EAAE;QACtB,IAAI,OAAOE,GAAG,KAAK,UAAU,EAAE;UAC7BA,GAAG,CAAC,IAAI,CAAC;QACX,CAAC,MAAM,IAAIA,GAAG,IAAI,IAAI,EAAE;UACtBA,GAAG,CAACC,OAAO,GAAG,IAAI;QACpB;MACF;MACA,OAAOC,SAAS;IAClB;IAEA,MAAMC,QAAmC,GAAG,EAAE;IAC9C,KAAK,MAAMH,GAAG,IAAIF,IAAI,EAAE;MACtB,IAAI,OAAOE,GAAG,KAAK,UAAU,EAAE;QAC7BG,QAAQ,CAACC,IAAI,CAACJ,GAAG,CAACD,KAAK,CAA0B,CAAC;MACpD,CAAC,MAAM,IAAIC,GAAG,IAAI,IAAI,EAAE;QACtBA,GAAG,CAACC,OAAO,GAAGF,KAAK;QACnBI,QAAQ,CAACC,IAAI,CAACF,SAAS,CAAC;MAC1B,CAAC,MAAM;QACLC,QAAQ,CAACC,IAAI,CAACF,SAAS,CAAC;MAC1B;IACF;IAEA,OAAO,MAAM;MACX,KAAK,IAAIG,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGP,IAAI,CAACQ,MAAM,EAAED,CAAC,EAAE,EAAE;QACpC,MAAML,GAAG,GAAGF,IAAI,CAACO,CAAC,CAAC;QACnB,IAAIL,GAAG,IAAI,IAAI,EAAE;QAEjB,IAAI,OAAOA,GAAG,KAAK,UAAU,EAAE;UAC7B,MAAMO,UAAU,GAAGJ,QAAQ,CAACE,CAAC,CAAC;UAC9B,IAAI,OAAOE,UAAU,KAAK,UAAU,EAAE;YACpCA,UAAU,CAAC,CAAC;UACd,CAAC,MAAM;YACLP,GAAG,CAAC,IAAI,CAAC;UACX;QACF,CAAC,MAAM;UACLA,GAAG,CAACC,OAAO,GAAG,IAAI;QACpB;MACF;IACF,CAAC;EACH,CAAC;AACH","ignoreList":[]}

package/lib/commonjs/form-control/useFormControl.js

@@ -12,6 +12,16 @@ var _react = _interopRequireDefault(require("react"));
 var _reactNative = require("react-native");
 var _accessibilityUtils = require("../common/accessibilityUtils");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Minimal contract for any control registered on `FormControlContextValue.inputRef`.
+ *
+ * `Field.Label` / `focusInput()` only need to call `.focus()` on the registered node;
+ * narrower control-specific shapes (`TextInput`, `HTMLInputElement`, custom focus
+ * bridges like `Select.Trigger`'s) all satisfy this contract. Consumers that need
+ * more (e.g. reading `.value`) should cast locally — keeping the context type
+ * minimal avoids a typed lie when a non-input bridge is registered.
+ */
+
 const FormControlContext = exports.FormControlContext = /*#__PURE__*/_react.default.createContext({});
 
 /** Props for the FormControl root; known fields plus passthrough to the styled root box. */

package/lib/commonjs/form-control/useFormControl.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","_interopRequireDefault","require","_reactNative","_accessibilityUtils","e","__esModule","default","FormControlContext","exports","React","createContext","useFormControlRoot","props","id","idProp","name","isRequired","isInvalid","isDisabled","isReadOnly","htmlProps","reactId","useId","labelId","feedbackId","helpTextId","hasFeedbackText","setHasFeedbackText","useState","hasHelpText","setHasHelpText","isLabelFocused","setIsLabelFocused","inputRef","useRef","focusInput","useCallback","node","current","focus","context","Boolean","Platform","OS","useReportFormControlLabelFocus","isActive","useFormControlContext","useLayoutEffect","undefined","useFormControl","field","describedBy","push","ariaDescribedBy","join","cleanProps","disabled","readOnly","required","ariaAttr","useContext"],"sourceRoot":"../../../src","sources":["form-control/useFormControl.tsx"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["_react","_interopRequireDefault","require","_reactNative","_accessibilityUtils","e","__esModule","default","FormControlContext","exports","React","createContext","useFormControlRoot","props","id","idProp","name","isRequired","isInvalid","isDisabled","isReadOnly","htmlProps","reactId","useId","labelId","feedbackId","helpTextId","hasFeedbackText","setHasFeedbackText","useState","hasHelpText","setHasHelpText","isLabelFocused","setIsLabelFocused","inputRef","useRef","focusInput","useCallback","node","current","focus","context","Boolean","Platform","OS","useReportFormControlLabelFocus","isActive","useFormControlContext","useLayoutEffect","undefined","useFormControl","field","describedBy","push","ariaDescribedBy","join","cleanProps","disabled","readOnly","required","ariaAttr","useContext"],"sourceRoot":"../../../src","sources":["form-control/useFormControl.tsx"],"mappings":"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","ignoreList":[]}

package/lib/module/common/mergeRefs.js

@@ -1,14 +1,52 @@
 "use strict";
 
+/**
+ * Merges multiple refs (object or callback) into a single callback ref.
+ *
+ * Supports React 19 ref-cleanup semantics: if an inner callback ref returns a
+ * cleanup function, that cleanup is captured and invoked when the merged ref is
+ * detached — either via the returned cleanup (React 19) or via a subsequent
+ * call with `null` (React 18 backward-compat path).
+ */
 export function mergeRefs(...refs) {
   return value => {
+    if (value === null) {
+      for (const ref of refs) {
+        if (typeof ref === 'function') {
+          ref(null);
+        } else if (ref != null) {
+          ref.current = null;
+        }
+      }
+      return undefined;
+    }
+    const cleanups = [];
     for (const ref of refs) {
       if (typeof ref === 'function') {
-        ref(value);
+        cleanups.push(ref(value));
       } else if (ref != null) {
         ref.current = value;
+        cleanups.push(undefined);
+      } else {
+        cleanups.push(undefined);
       }
     }
+    return () => {
+      for (let i = 0; i < refs.length; i++) {
+        const ref = refs[i];
+        if (ref == null) continue;
+        if (typeof ref === 'function') {
+          const refCleanup = cleanups[i];
+          if (typeof refCleanup === 'function') {
+            refCleanup();
+          } else {
+            ref(null);
+          }
+        } else {
+          ref.current = null;
+        }
+      }
+    };
   };
 }
 //# sourceMappingURL=mergeRefs.js.map

package/lib/module/common/mergeRefs.js.map

@@ -1 +1 @@
-{"version":3,"names":["mergeRefs","refs","value","ref","current"],"sourceRoot":"../../../src","sources":["common/mergeRefs.ts"],"mappings":";;AAEA,OAAO,SAASA,SAASA,CAAI,GAAGC,IAA4B,EAAkB;EAC5E,OAAQC,KAAe,IAAK;IAC1B,KAAK,MAAMC,GAAG,IAAIF,IAAI,EAAE;MACtB,IAAI,OAAOE,GAAG,KAAK,UAAU,EAAE;QAC7BA,GAAG,CAACD,KAAK,CAAC;MACZ,CAAC,MAAM,IAAIC,GAAG,IAAI,IAAI,EAAE;QACtBA,GAAG,CAACC,OAAO,GAAGF,KAAK;MACrB;IACF;EACF,CAAC;AACH","ignoreList":[]}
+{"version":3,"names":["mergeRefs","refs","value","ref","current","undefined","cleanups","push","i","length","refCleanup"],"sourceRoot":"../../../src","sources":["common/mergeRefs.ts"],"mappings":";;AAIA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASA,SAASA,CAAI,GAAGC,IAA4B,EAAkB;EAC5E,OAAQC,KAAe,IAA4B;IACjD,IAAIA,KAAK,KAAK,IAAI,EAAE;MAClB,KAAK,MAAMC,GAAG,IAAIF,IAAI,EAAE;QACtB,IAAI,OAAOE,GAAG,KAAK,UAAU,EAAE;UAC7BA,GAAG,CAAC,IAAI,CAAC;QACX,CAAC,MAAM,IAAIA,GAAG,IAAI,IAAI,EAAE;UACtBA,GAAG,CAACC,OAAO,GAAG,IAAI;QACpB;MACF;MACA,OAAOC,SAAS;IAClB;IAEA,MAAMC,QAAmC,GAAG,EAAE;IAC9C,KAAK,MAAMH,GAAG,IAAIF,IAAI,EAAE;MACtB,IAAI,OAAOE,GAAG,KAAK,UAAU,EAAE;QAC7BG,QAAQ,CAACC,IAAI,CAACJ,GAAG,CAACD,KAAK,CAA0B,CAAC;MACpD,CAAC,MAAM,IAAIC,GAAG,IAAI,IAAI,EAAE;QACtBA,GAAG,CAACC,OAAO,GAAGF,KAAK;QACnBI,QAAQ,CAACC,IAAI,CAACF,SAAS,CAAC;MAC1B,CAAC,MAAM;QACLC,QAAQ,CAACC,IAAI,CAACF,SAAS,CAAC;MAC1B;IACF;IAEA,OAAO,MAAM;MACX,KAAK,IAAIG,CAAC,GAAG,CAAC,EAAEA,CAAC,GAAGP,IAAI,CAACQ,MAAM,EAAED,CAAC,EAAE,EAAE;QACpC,MAAML,GAAG,GAAGF,IAAI,CAACO,CAAC,CAAC;QACnB,IAAIL,GAAG,IAAI,IAAI,EAAE;QAEjB,IAAI,OAAOA,GAAG,KAAK,UAAU,EAAE;UAC7B,MAAMO,UAAU,GAAGJ,QAAQ,CAACE,CAAC,CAAC;UAC9B,IAAI,OAAOE,UAAU,KAAK,UAAU,EAAE;YACpCA,UAAU,CAAC,CAAC;UACd,CAAC,MAAM;YACLP,GAAG,CAAC,IAAI,CAAC;UACX;QACF,CAAC,MAAM;UACLA,GAAG,CAACC,OAAO,GAAG,IAAI;QACpB;MACF;IACF,CAAC;EACH,CAAC;AACH","ignoreList":[]}

package/lib/module/form-control/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["FormControlContext","useFormControl","useFormControlContext","useFormControlRoot","useReportFormControlLabelFocus"],"sourceRoot":"../../../src","sources":["form-control/index.ts"],"mappings":";;AAAA,SAMEA,kBAAkB,EAClBC,cAAc,EACdC,qBAAqB,EACrBC,kBAAkB,EAClBC,8BAA8B,QACzB,kBAAkB","ignoreList":[]}
+{"version":3,"names":["FormControlContext","useFormControl","useFormControlContext","useFormControlRoot","useReportFormControlLabelFocus"],"sourceRoot":"../../../src","sources":["form-control/index.ts"],"mappings":";;AAAA,SAOEA,kBAAkB,EAClBC,cAAc,EACdC,qBAAqB,EACrBC,kBAAkB,EAClBC,8BAA8B,QACzB,kBAAkB","ignoreList":[]}

package/lib/module/form-control/useFormControl.js

@@ -3,6 +3,17 @@
 import React from 'react';
 import { Platform } from 'react-native';
 import { ariaAttr } from '../common/accessibilityUtils';
+
+/**
+ * Minimal contract for any control registered on `FormControlContextValue.inputRef`.
+ *
+ * `Field.Label` / `focusInput()` only need to call `.focus()` on the registered node;
+ * narrower control-specific shapes (`TextInput`, `HTMLInputElement`, custom focus
+ * bridges like `Select.Trigger`'s) all satisfy this contract. Consumers that need
+ * more (e.g. reading `.value`) should cast locally — keeping the context type
+ * minimal avoids a typed lie when a non-input bridge is registered.
+ */
+
 export const FormControlContext = /*#__PURE__*/React.createContext({});
 
 /** Props for the FormControl root; known fields plus passthrough to the styled root box. */

package/lib/module/form-control/useFormControl.js.map

@@ -1 +1 @@
-{"version":3,"names":["React","Platform","ariaAttr","FormControlContext","createContext","useFormControlRoot","props","id","idProp","name","isRequired","isInvalid","isDisabled","isReadOnly","htmlProps","reactId","useId","labelId","feedbackId","helpTextId","hasFeedbackText","setHasFeedbackText","useState","hasHelpText","setHasHelpText","isLabelFocused","setIsLabelFocused","inputRef","useRef","focusInput","useCallback","node","current","focus","context","Boolean","OS","useReportFormControlLabelFocus","isActive","useFormControlContext","useLayoutEffect","undefined","useFormControl","field","describedBy","push","ariaDescribedBy","join","cleanProps","disabled","readOnly","required","useContext"],"sourceRoot":"../../../src","sources":["form-control/useFormControl.tsx"],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["React","Platform","ariaAttr","FormControlContext","createContext","useFormControlRoot","props","id","idProp","name","isRequired","isInvalid","isDisabled","isReadOnly","htmlProps","reactId","useId","labelId","feedbackId","helpTextId","hasFeedbackText","setHasFeedbackText","useState","hasHelpText","setHasHelpText","isLabelFocused","setIsLabelFocused","inputRef","useRef","focusInput","useCallback","node","current","focus","context","Boolean","OS","useReportFormControlLabelFocus","isActive","useFormControlContext","useLayoutEffect","undefined","useFormControl","field","describedBy","push","ariaDescribedBy","join","cleanProps","disabled","readOnly","required","useContext"],"sourceRoot":"../../../src","sources":["form-control/useFormControl.tsx"],"mappings":"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","ignoreList":[]}

package/lib/typescript/common/mergeRefs.d.ts

@@ -1,3 +1,11 @@
 import type { Ref, RefCallback } from 'react';
+/**
+ * Merges multiple refs (object or callback) into a single callback ref.
+ *
+ * Supports React 19 ref-cleanup semantics: if an inner callback ref returns a
+ * cleanup function, that cleanup is captured and invoked when the merged ref is
+ * detached — either via the returned cleanup (React 19) or via a subsequent
+ * call with `null` (React 18 backward-compat path).
+ */
 export declare function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): RefCallback<T>;
 //# sourceMappingURL=mergeRefs.d.ts.map

package/lib/typescript/common/mergeRefs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mergeRefs.d.ts","sourceRoot":"","sources":["../../../src/common/mergeRefs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAE9C,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAU5E"}
+{"version":3,"file":"mergeRefs.d.ts","sourceRoot":"","sources":["../../../src/common/mergeRefs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAI9C;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CA2C5E"}

package/lib/typescript/form-control/index.d.ts

@@ -1,2 +1,2 @@
-export { type FormControlContextValue, type FormControlFieldProps, type FormControlRootProps, type FormControlRootReturn, type FormControlState, FormControlContext, useFormControl, useFormControlContext, useFormControlRoot, useReportFormControlLabelFocus, } from './useFormControl';
+export { type Focusable, type FormControlContextValue, type FormControlFieldProps, type FormControlRootProps, type FormControlRootReturn, type FormControlState, FormControlContext, useFormControl, useFormControlContext, useFormControlRoot, useReportFormControlLabelFocus, } from './useFormControl';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/form-control/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/form-control/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/form-control/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,SAAS,EACd,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,8BAA8B,GAC/B,MAAM,kBAAkB,CAAC"}

package/lib/typescript/form-control/useFormControl.d.ts

@@ -1,6 +1,17 @@
 import React from 'react';
-import { type TextInput } from 'react-native';
 type HTMLProps = Record<string, unknown>;
+/**
+ * Minimal contract for any control registered on `FormControlContextValue.inputRef`.
+ *
+ * `Field.Label` / `focusInput()` only need to call `.focus()` on the registered node;
+ * narrower control-specific shapes (`TextInput`, `HTMLInputElement`, custom focus
+ * bridges like `Select.Trigger`'s) all satisfy this contract. Consumers that need
+ * more (e.g. reading `.value`) should cast locally — keeping the context type
+ * minimal avoids a typed lie when a non-input bridge is registered.
+ */
+export interface Focusable {
+    focus(): void;
+}
 export interface FormControlState {
     isRequired: boolean;
     isInvalid: boolean;
@@ -21,8 +32,12 @@ export interface FormControlContextValue extends FormControlState {
     /**
      * @platform native — set by `Input.Field` / `Select.Trigger` for label press-to-focus.
      * On web, use `<label htmlFor>` with a labelable control (`input`, `button`, `select`, …).
+     *
+     * Typed as `Focusable` so any control (TextInput, HTMLInputElement, custom focus
+     * bridge) can register without a cast at the assignment site. Consumers that need
+     * the narrower shape cast locally.
      */
-    inputRef?: React.RefObject<TextInput | null>;
+    inputRef?: React.RefObject<Focusable | null>;
     focusInput?: () => void;
     /** True when the primary child control is focused or (for Select) open — drives `Field.Label` styling. */
     isLabelFocused?: boolean;
@@ -52,7 +67,7 @@ export interface FormControlRootReturn {
     feedbackId: string;
     helpTextId: string;
     htmlProps: HTMLProps;
-    inputRef?: React.RefObject<TextInput | null>;
+    inputRef?: React.RefObject<Focusable | null>;
     focusInput?: () => void;
     isLabelFocused: boolean;
     setIsLabelFocused: React.Dispatch<React.SetStateAction<boolean>>;

package/lib/typescript/form-control/useFormControl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useFormControl.d.ts","sourceRoot":"","sources":["../../../src/form-control/useFormControl.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"useFormControl.d.ts","sourceRoot":"","sources":["../../../src/form-control/useFormControl.tsx"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cdx-ui/utils",
-  "version": "0.0.1-beta.64",
+  "version": "0.0.1-beta.66",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "react-native": "src/index.ts",

package/src/common/mergeRefs.test.ts

@@ -37,4 +37,112 @@ describe('mergeRefs', () => {
     expect(callback).toHaveBeenCalledWith('shared');
     expect(objectRef.current).toBe('shared');
   });
+
+  describe('React 19 ref-cleanup semantics', () => {
+    it('returns a cleanup function when called with a non-null value', () => {
+      const ref = createRef<string>();
+      const merged = mergeRefs(ref);
+
+      const cleanup = merged('value');
+
+      expect(typeof cleanup).toBe('function');
+    });
+
+    it('does not return a cleanup when called with null', () => {
+      const ref = createRef<string>();
+      const merged = mergeRefs(ref);
+
+      const result = merged(null);
+
+      expect(result).toBeUndefined();
+    });
+
+    it('cleanup nulls object refs', () => {
+      const refA = createRef<string>();
+      const refB = createRef<string>();
+      const merged = mergeRefs(refA, refB);
+
+      const cleanup = merged('value') as () => void;
+      expect(refA.current).toBe('value');
+      expect(refB.current).toBe('value');
+
+      cleanup();
+      expect(refA.current).toBeNull();
+      expect(refB.current).toBeNull();
+    });
+
+    it('cleanup calls callback refs with null when they did not return a cleanup', () => {
+      const callback = jest.fn();
+      const merged = mergeRefs(callback);
+
+      const cleanup = merged('value') as () => void;
+      expect(callback).toHaveBeenCalledWith('value');
+
+      callback.mockClear();
+      cleanup();
+      expect(callback).toHaveBeenCalledWith(null);
+    });
+
+    it('cleanup invokes the inner cleanup instead of calling ref(null) for refs that returned one', () => {
+      const innerCleanup = jest.fn();
+      const callbackWithCleanup = jest.fn().mockReturnValue(innerCleanup);
+      const merged = mergeRefs(callbackWithCleanup);
+
+      const cleanup = merged('element') as () => void;
+      expect(callbackWithCleanup).toHaveBeenCalledWith('element');
+
+      callbackWithCleanup.mockClear();
+      cleanup();
+      expect(innerCleanup).toHaveBeenCalledTimes(1);
+      expect(callbackWithCleanup).not.toHaveBeenCalled();
+    });
+
+    it('handles mixed refs: object, callback with cleanup, callback without cleanup', () => {
+      const objectRef = createRef<string>();
+      const innerCleanup = jest.fn();
+      const callbackWithCleanup = jest.fn().mockReturnValue(innerCleanup);
+      const callbackNoCleanup = jest.fn();
+
+      const merged = mergeRefs(objectRef, callbackWithCleanup, callbackNoCleanup);
+      const cleanup = merged('node') as () => void;
+
+      expect(objectRef.current).toBe('node');
+      expect(callbackWithCleanup).toHaveBeenCalledWith('node');
+      expect(callbackNoCleanup).toHaveBeenCalledWith('node');
+
+      callbackWithCleanup.mockClear();
+      callbackNoCleanup.mockClear();
+      cleanup();
+
+      expect(objectRef.current).toBeNull();
+      expect(innerCleanup).toHaveBeenCalledTimes(1);
+      expect(callbackWithCleanup).not.toHaveBeenCalled();
+      expect(callbackNoCleanup).toHaveBeenCalledWith(null);
+    });
+
+    it('null-call path still works for React 18 compat (calls all refs with null)', () => {
+      const objectRef = createRef<string>();
+      const callback = jest.fn();
+      const merged = mergeRefs(objectRef, callback);
+
+      merged('value');
+      callback.mockClear();
+
+      merged(null);
+
+      expect(objectRef.current).toBeNull();
+      expect(callback).toHaveBeenCalledWith(null);
+    });
+
+    it('skips undefined entries in cleanup', () => {
+      const objectRef = createRef<string>();
+      const merged = mergeRefs(undefined, objectRef, undefined);
+
+      const cleanup = merged('value') as () => void;
+      expect(objectRef.current).toBe('value');
+
+      cleanup();
+      expect(objectRef.current).toBeNull();
+    });
+  });
 });

package/src/common/mergeRefs.ts

@@ -1,13 +1,56 @@
 import type { Ref, RefCallback } from 'react';
 
+type CleanupFn = () => void;
+
+/**
+ * Merges multiple refs (object or callback) into a single callback ref.
+ *
+ * Supports React 19 ref-cleanup semantics: if an inner callback ref returns a
+ * cleanup function, that cleanup is captured and invoked when the merged ref is
+ * detached — either via the returned cleanup (React 19) or via a subsequent
+ * call with `null` (React 18 backward-compat path).
+ */
 export function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): RefCallback<T> {
-  return (value: T | null) => {
+  return (value: T | null): CleanupFn | undefined => {
+    if (value === null) {
+      for (const ref of refs) {
+        if (typeof ref === 'function') {
+          ref(null);
+        } else if (ref != null) {
+          ref.current = null;
+        }
+      }
+      return undefined;
+    }
+
+    const cleanups: (CleanupFn | undefined)[] = [];
     for (const ref of refs) {
       if (typeof ref === 'function') {
-        ref(value);
+        cleanups.push(ref(value) as CleanupFn | undefined);
       } else if (ref != null) {
         ref.current = value;
+        cleanups.push(undefined);
+      } else {
+        cleanups.push(undefined);
       }
     }
+
+    return () => {
+      for (let i = 0; i < refs.length; i++) {
+        const ref = refs[i];
+        if (ref == null) continue;
+
+        if (typeof ref === 'function') {
+          const refCleanup = cleanups[i];
+          if (typeof refCleanup === 'function') {
+            refCleanup();
+          } else {
+            ref(null);
+          }
+        } else {
+          ref.current = null;
+        }
+      }
+    };
   };
 }

package/src/form-control/index.ts

@@ -1,4 +1,5 @@
 export {
+  type Focusable,
   type FormControlContextValue,
   type FormControlFieldProps,
   type FormControlRootProps,

package/src/form-control/useFormControl.tsx

@@ -1,9 +1,22 @@
 import React from 'react';
-import { Platform, type TextInput } from 'react-native';
+import { Platform } from 'react-native';
 import { ariaAttr } from '../common/accessibilityUtils';
 
 type HTMLProps = Record<string, unknown>;
 
+/**
+ * Minimal contract for any control registered on `FormControlContextValue.inputRef`.
+ *
+ * `Field.Label` / `focusInput()` only need to call `.focus()` on the registered node;
+ * narrower control-specific shapes (`TextInput`, `HTMLInputElement`, custom focus
+ * bridges like `Select.Trigger`'s) all satisfy this contract. Consumers that need
+ * more (e.g. reading `.value`) should cast locally — keeping the context type
+ * minimal avoids a typed lie when a non-input bridge is registered.
+ */
+export interface Focusable {
+  focus(): void;
+}
+
 export interface FormControlState {
   isRequired: boolean;
   isInvalid: boolean;
@@ -25,8 +38,12 @@ export interface FormControlContextValue extends FormControlState {
   /**
    * @platform native — set by `Input.Field` / `Select.Trigger` for label press-to-focus.
    * On web, use `<label htmlFor>` with a labelable control (`input`, `button`, `select`, …).
+   *
+   * Typed as `Focusable` so any control (TextInput, HTMLInputElement, custom focus
+   * bridge) can register without a cast at the assignment site. Consumers that need
+   * the narrower shape cast locally.
    */
-  inputRef?: React.RefObject<TextInput | null>;
+  inputRef?: React.RefObject<Focusable | null>;
   focusInput?: () => void;
   /** True when the primary child control is focused or (for Select) open — drives `Field.Label` styling. */
   isLabelFocused?: boolean;
@@ -60,7 +77,7 @@ export interface FormControlRootReturn {
   feedbackId: string;
   helpTextId: string;
   htmlProps: HTMLProps;
-  inputRef?: React.RefObject<TextInput | null>;
+  inputRef?: React.RefObject<Focusable | null>;
   focusInput?: () => void;
   isLabelFocused: boolean;
   setIsLabelFocused: React.Dispatch<React.SetStateAction<boolean>>;
@@ -94,7 +111,7 @@ export function useFormControlRoot(props: FormControlRootProps): FormControlRoot
 
   const [isLabelFocused, setIsLabelFocused] = React.useState(false);
 
-  const inputRef = React.useRef<TextInput | null>(null);
+  const inputRef = React.useRef<Focusable | null>(null);
 
   const focusInput = React.useCallback(() => {
     const node = inputRef.current;