@cdx-ui/utils 0.0.1-beta.18 → 0.0.1-beta.180

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2026 Digital First Holdings LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,8 @@
 # @cdx-ui/utils
 
-Shared utilities used across CDS packages.
+![coverage](https://unpkg.com/@cdx-ui/utils/coverage.svg)
+
+Shared utilities used across FDS packages.
 
 Provides common helpers for styling, event handling, state management, and context propagation used by [`@cdx-ui/primitives`](../primitives/) and [`@cdx-ui/components`](../components/).
 
@@ -14,49 +16,75 @@ pnpm add @cdx-ui/utils
 
 ### Common helpers
 
-| Export | Description |
-| --- | --- |
-| `cn(...inputs)` | Merges class names with `clsx` + `tailwind-merge` — conditionals and conflict resolution in one call. |
-| `composeEventHandlers(...handlers)` | Chains multiple event callbacks into a single handler; skips `null`/`undefined` entries. |
-| `useControllableState(params)` | Hook that supports both controlled and uncontrolled modes for a single value. Warns in dev if the mode switches during a component's lifetime. |
-| `mergeRefs(...refs)` | Combines multiple refs (callback or object) into one ref callback. |
-| `flattenChildren(children)` | Recursively flattens React `children` into a flat array (used internally for spaced-child layouts). |
-| `ariaAttr(condition)` | Returns `'true'` or `undefined` — shorthand for boolean ARIA attribute values. |
+| Export                              | Description                                                                                                                                |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `cn(...inputs)`                     | Merges class names with `clsx` + `tailwind-merge` — conditionals and conflict resolution in one call.                                      |
+| `composeEventHandlers(...handlers)` | Chains multiple event callbacks into a single handler; skips `null`/`undefined` entries.                                                   |
+| `useControllableState(params)`      | Hook that supports both controlled and uncontrolled modes for a single value. Derives `isControlled` from whether the prop is `undefined`. |
+| `mergeRefs(...refs)`                | Combines multiple refs (callback or object) into one ref callback.                                                                         |
+| `flattenChildren(children)`         | Recursively flattens React `children` (including Fragments) into a flat array with re-keyed elements.                                      |
+| `ariaAttr(condition)`               | Returns `true` (boolean) or `undefined` — shorthand for boolean ARIA attribute values.                                                     |
+| `cva(base, config)`                 | Class Variance Authority helper for authoring variant-driven `className` builders. `VariantProps<typeof fn>` derives the prop type.         |
 
 ### Context
 
-| Export | Description |
-| --- | --- |
+| Export                       | Description                                                                                                                                                                                 |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `createContext(displayName)` | Wrapper around React's `createContext` that returns a `[Provider, useHook]` tuple. The hook throws a descriptive error if called outside the provider — eliminates silent `undefined` bugs. |
 
 ### Style context
 
 Used internally by `@cdx-ui/components` to propagate variant props (size, color, etc.) from a compound root to its sub-components.
 
-| Export | Description |
-| --- | --- |
-| `withStyleContext(Component, scope?)` | HOC that adds a `context` prop and provides it to descendants via `ParentContext`. |
-| `useStyleContext(scope?)` | Reads the style context set by the nearest `withStyleContext` wrapper. |
-| `useParentContext()` | Reads the full `StyleContextMap` from the nearest provider. |
-| `ParentContext` | The raw React context (rarely needed directly). |
+| Export                    | Description                                                                                                                                  |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ParentContext`           | React context for propagating variant props from a compound root to sub-components. Wrap children in `<ParentContext.Provider value={...}>`. |
+| `useStyleContext(scope?)` | Reads the style context set by the nearest `ParentContext.Provider`.                                                                         |
+| `useParentContext()`      | Reads the full `StyleContextMap` from the nearest provider.                                                                                  |
 
 ### Form control
 
 Low-level form-field state used by the `Field` and `Input` primitives.
 
-| Export | Description |
-| --- | --- |
-| `useFormControlRoot(props)` | Creates the root state object for a form field (id generation, `aria-describedby` wiring). |
-| `useFormControl(props)` | Merges component-level props with inherited form-control context. |
-| `useFormControlContext()` | Reads form-control state from the nearest provider. |
-| `FormControlContext` | The raw React context for form-control state. |
-| `FormControlContextValue` | Type: full context shape including field state, `id`, `labelId`, `feedbackId`, `helpTextId`, and setters. |
-| `FormControlState` | Type: `{ isRequired, isInvalid, isDisabled, isReadOnly }`. |
-| `FormControlRootProps` | Type: input props for `useFormControlRoot`. |
-| `FormControlRootReturn` | Type: return value of `useFormControlRoot` (`htmlProps` + context fields). |
-| `FormControlFieldProps` | Type: props accepted by `useFormControl` (field state flags + `id`). |
+| Export                                     | Description                                                                                                                                              |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useFormControlRoot(props)`                | Creates the root state object for a form field (id generation, tracks `hasFeedbackText`/`hasHelpText` for describedby assembly).                         |
+| `useFormControl(props)`                    | Merges component-level props with inherited form-control context. Assembles `aria-describedby` from feedback/help text ids.                              |
+| `useFormControlContext()`                  | Reads form-control state from the nearest provider.                                                                                                      |
+| `useReportFormControlLabelFocus(isActive)` | Reports focus/active state to the parent `FormControlContext` — used by `Input`/`Select.Trigger` to trigger `isFocused` styling on the associated label. |
+| `FormControlContext`                       | The React context object for form-control state propagation.                                                                                             |
+
+## Exported types
+
+| Type                         | Source       |
+| ---------------------------- | ------------ |
+| `UseControllableStateParams` | common       |
+| `VariantProps`               | common       |
+| `Focusable`                  | form-control |
+| `FormControlContextValue`    | form-control |
+| `FormControlFieldProps`      | form-control |
+| `FormControlRootProps`       | form-control |
+| `FormControlRootReturn`      | form-control |
+| `FormControlState`           | form-control |
+| `StyleContextMap`            | style        |
+
+## Testing
+
+Tests are colocated next to source files (`*.test.{ts,tsx}`). Run via the `utils` Jest project:
+
+```bash
+pnpm nx run @cdx-ui/utils:test
+```
+
+All runtime exports have test coverage using `@testing-library/react-native` (`renderHook`, `act`).
 
 ## Further reading
 
 - [State management practices](../../docs/internal/practices/state.md) — `useControllableState` and `composeEventHandlers` patterns
 - [Styling practices](../../docs/internal/practices/styling.md) — `cn()` and CVA variant authoring
+
+## License
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+MIT © 2026 Digital First Holdings LLC. See [LICENSE](./LICENSE) for details.

package/coverage.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 100.0%"><title>coverage: 100.0%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#4b0"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">100.0%</text><text x="865" y="150" fill-opacity=".3" textLength="430">100.0%</text></g><text x="865" y="140" textLength="430">100.0%</text></g></g></svg>

package/lib/commonjs/common/cva.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "cva", {
+  enumerable: true,
+  get: function () {
+    return _classVarianceAuthority.cva;
+  }
+});
+var _classVarianceAuthority = require("class-variance-authority");
+//# sourceMappingURL=cva.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["_classVarianceAuthority","require"],"sourceRoot":"../../../src","sources":["common/cva.ts"],"mappings":";;;;;;;;;;;AAAA,IAAAA,uBAAA,GAAAC,OAAA","ignoreList":[]}

package/lib/commonjs/common/index.js

@@ -21,6 +21,12 @@ Object.defineProperty(exports, "composeEventHandlers", {
     return _composeEventHandlers.composeEventHandlers;
   }
 });
+Object.defineProperty(exports, "cva", {
+  enumerable: true,
+  get: function () {
+    return _cva.cva;
+  }
+});
 Object.defineProperty(exports, "flattenChildren", {
   enumerable: true,
   get: function () {
@@ -41,6 +47,7 @@ Object.defineProperty(exports, "useControllableState", {
 });
 var _accessibilityUtils = require("./accessibilityUtils");
 var _cn = require("./cn");
+var _cva = require("./cva");
 var _composeEventHandlers = require("./composeEventHandlers");
 var _getSpacedChild = require("./getSpacedChild");
 var _mergeRefs = require("./mergeRefs");

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

@@ -1 +1 @@
-{"version":3,"names":["_accessibilityUtils","require","_cn","_composeEventHandlers","_getSpacedChild","_mergeRefs","_useControllableState"],"sourceRoot":"../../../src","sources":["common/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,mBAAA,GAAAC,OAAA;AACA,IAAAC,GAAA,GAAAD,OAAA;AACA,IAAAE,qBAAA,GAAAF,OAAA;AACA,IAAAG,eAAA,GAAAH,OAAA;AACA,IAAAI,UAAA,GAAAJ,OAAA;AACA,IAAAK,qBAAA,GAAAL,OAAA","ignoreList":[]}
+{"version":3,"names":["_accessibilityUtils","require","_cn","_cva","_composeEventHandlers","_getSpacedChild","_mergeRefs","_useControllableState"],"sourceRoot":"../../../src","sources":["common/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,mBAAA,GAAAC,OAAA;AACA,IAAAC,GAAA,GAAAD,OAAA;AACA,IAAAE,IAAA,GAAAF,OAAA;AACA,IAAAG,qBAAA,GAAAH,OAAA;AACA,IAAAI,eAAA,GAAAJ,OAAA;AACA,IAAAK,UAAA,GAAAL,OAAA;AACA,IAAAM,qBAAA,GAAAN,OAAA","ignoreList":[]}

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/context/createContext.js

@@ -6,8 +6,12 @@ Object.defineProperty(exports, "__esModule", {
 exports.createContext = createContext;
 var _react = require("react");
 var _jsxRuntime = require("react/jsx-runtime");
-function createContext(displayName) {
-  const Context = /*#__PURE__*/(0, _react.createContext)(undefined);
+function createContext(displayName, options) {
+  const {
+    defaultValue,
+    strict = true
+  } = options ?? {};
+  const Context = /*#__PURE__*/(0, _react.createContext)(defaultValue);
   const Provider = props => {
     const {
       children,
@@ -21,7 +25,7 @@ function createContext(displayName) {
   Provider.displayName = `${displayName}Provider`;
   function useC() {
     const context = (0, _react.useContext)(Context);
-    if (context === undefined) {
+    if (context === undefined && strict) {
       throw new Error(`use${displayName} must be used within a ${displayName}Provider`);
     }
     return context;

package/lib/commonjs/context/createContext.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","require","_jsxRuntime","createContext","displayName","Context","createReactContext","undefined","Provider","props","children","value","jsx","useC","context","useContext","Error"],"sourceRoot":"../../../src","sources":["context/createContext.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAKe,IAAAC,WAAA,GAAAD,OAAA;AAER,SAASE,aAAaA,CAAIC,WAAmB,EAAE;EACpD,MAAMC,OAAO,gBAAG,IAAAC,oBAAkB,EAAgBC,SAAS,CAAC;EAE5D,MAAMC,QAA0D,GAAIC,KAAK,IAAK;IAC5E,MAAM;MAAEC,QAAQ;MAAEC;IAAM,CAAC,GAAGF,KAAK;IACjC,oBAAO,IAAAP,WAAA,CAAAU,GAAA,EAACP,OAAO,CAACG,QAAQ;MAACG,KAAK,EAAEA,KAAM;MAAAD,QAAA,EAAEA;IAAQ,CAAmB,CAAC;EACtE,CAAC;EAEDF,QAAQ,CAACJ,WAAW,GAAG,GAAGA,WAAW,UAAU;EAE/C,SAASS,IAAIA,CAAA,EAAM;IACjB,MAAMC,OAAO,GAAG,IAAAC,iBAAU,EAACV,OAAO,CAAC;IACnC,IAAIS,OAAO,KAAKP,SAAS,EAAE;MACzB,MAAM,IAAIS,KAAK,CAAC,MAAMZ,WAAW,0BAA0BA,WAAW,UAAU,CAAC;IACnF;IACA,OAAOU,OAAO;EAChB;EAEA,OAAO,CAACN,QAAQ,EAAEK,IAAI,CAAC;AACzB","ignoreList":[]}
+{"version":3,"names":["_react","require","_jsxRuntime","createContext","displayName","options","defaultValue","strict","Context","createReactContext","Provider","props","children","value","jsx","useC","context","useContext","undefined","Error"],"sourceRoot":"../../../src","sources":["context/createContext.tsx"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAKe,IAAAC,WAAA,GAAAD,OAAA;AAiBR,SAASE,aAAaA,CAAIC,WAAmB,EAAEC,OAAiC,EAAE;EACvF,MAAM;IAAEC,YAAY;IAAEC,MAAM,GAAG;EAAK,CAAC,GAAGF,OAAO,IAAI,CAAC,CAAC;EAErD,MAAMG,OAAO,gBAAG,IAAAC,oBAAkB,EAAgBH,YAAY,CAAC;EAE/D,MAAMI,QAA0D,GAAIC,KAAK,IAAK;IAC5E,MAAM;MAAEC,QAAQ;MAAEC;IAAM,CAAC,GAAGF,KAAK;IACjC,oBAAO,IAAAT,WAAA,CAAAY,GAAA,EAACN,OAAO,CAACE,QAAQ;MAACG,KAAK,EAAEA,KAAM;MAAAD,QAAA,EAAEA;IAAQ,CAAmB,CAAC;EACtE,CAAC;EAEDF,QAAQ,CAACN,WAAW,GAAG,GAAGA,WAAW,UAAU;EAE/C,SAASW,IAAIA,CAAA,EAAM;IACjB,MAAMC,OAAO,GAAG,IAAAC,iBAAU,EAACT,OAAO,CAAC;IACnC,IAAIQ,OAAO,KAAKE,SAAS,IAAIX,MAAM,EAAE;MACnC,MAAM,IAAIY,KAAK,CAAC,MAAMf,WAAW,0BAA0BA,WAAW,UAAU,CAAC;IACnF;IACA,OAAOY,OAAO;EAChB;EAEA,OAAO,CAACN,QAAQ,EAAEK,IAAI,CAAC;AACzB","ignoreList":[]}

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

@@ -27,5 +27,11 @@ Object.defineProperty(exports, "useFormControlRoot", {
     return _useFormControl.useFormControlRoot;
   }
 });
+Object.defineProperty(exports, "useReportFormControlLabelFocus", {
+  enumerable: true,
+  get: function () {
+    return _useFormControl.useReportFormControlLabelFocus;
+  }
+});
 var _useFormControl = require("./useFormControl");
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"names":["_useFormControl","require"],"sourceRoot":"../../../src","sources":["form-control/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,eAAA,GAAAC,OAAA","ignoreList":[]}
+{"version":3,"names":["_useFormControl","require"],"sourceRoot":"../../../src","sources":["form-control/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,eAAA,GAAAC,OAAA","ignoreList":[]}

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

@@ -7,10 +7,21 @@ exports.FormControlContext = void 0;
 exports.useFormControl = useFormControl;
 exports.useFormControlContext = void 0;
 exports.useFormControlRoot = useFormControlRoot;
+exports.useReportFormControlLabelFocus = useReportFormControlLabelFocus;
 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. */
@@ -46,6 +57,7 @@ function useFormControlRoot(props) {
    * We use this to append its id the the `aria-describedby` of the `input`.
    */
   const [hasHelpText, setHasHelpText] = _react.default.useState(false);
+  const [isLabelFocused, setIsLabelFocused] = _react.default.useState(false);
   const inputRef = _react.default.useRef(null);
   const focusInput = _react.default.useCallback(() => {
     const node = inputRef.current;
@@ -68,6 +80,8 @@ function useFormControlRoot(props) {
     feedbackId,
     helpTextId,
     htmlProps,
+    isLabelFocused,
+    setIsLabelFocused,
     ...(_reactNative.Platform.OS !== 'web' ? {
       inputRef,
       focusInput
@@ -76,6 +90,25 @@ function useFormControlRoot(props) {
   return context;
 }
 
+/**
+ * Reports focus/active state from `Input` / `Select.Trigger` to the parent `Field` for label styling.
+ * No-ops outside a `Field` (no `setIsLabelFocused` on context).
+ */
+function useReportFormControlLabelFocus(isActive) {
+  const {
+    setIsLabelFocused
+  } = useFormControlContext();
+  _react.default.useLayoutEffect(() => {
+    if (typeof setIsLabelFocused !== 'function') {
+      return undefined;
+    }
+    setIsLabelFocused(isActive);
+    return () => {
+      setIsLabelFocused(false);
+    };
+  }, [isActive, setIsLabelFocused]);
+}
+
 /**
  * Hook that merges local field props with the nearest form field context
  * and returns normalised HTML / ARIA attributes for input elements.

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","inputRef","useRef","focusInput","useCallback","node","current","focus","context","Boolean","Platform","OS","useFormControl","field","useFormControlContext","describedBy","push","ariaDescribedBy","join","cleanProps","undefined","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/commonjs/style/index.js

@@ -14,15 +14,4 @@ Object.keys(_context).forEach(function (key) {
     }
   });
 });
-var _withStyleContext = require("./withStyleContext");
-Object.keys(_withStyleContext).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _withStyleContext[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _withStyleContext[key];
-    }
-  });
-});
 //# sourceMappingURL=index.js.map

package/lib/commonjs/style/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["_context","require","Object","keys","forEach","key","exports","defineProperty","enumerable","get","_withStyleContext"],"sourceRoot":"../../../src","sources":["style/index.tsx"],"mappings":";;;;;AAAA,IAAAA,QAAA,GAAAC,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAH,QAAA,EAAAI,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAA,GAAA,IAAAC,OAAA,IAAAA,OAAA,CAAAD,GAAA,MAAAL,QAAA,CAAAK,GAAA;EAAAH,MAAA,CAAAK,cAAA,CAAAD,OAAA,EAAAD,GAAA;IAAAG,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAT,QAAA,CAAAK,GAAA;IAAA;EAAA;AAAA;AACA,IAAAK,iBAAA,GAAAT,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAO,iBAAA,EAAAN,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAA,GAAA,IAAAC,OAAA,IAAAA,OAAA,CAAAD,GAAA,MAAAK,iBAAA,CAAAL,GAAA;EAAAH,MAAA,CAAAK,cAAA,CAAAD,OAAA,EAAAD,GAAA;IAAAG,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAC,iBAAA,CAAAL,GAAA;IAAA;EAAA;AAAA","ignoreList":[]}
+{"version":3,"names":["_context","require","Object","keys","forEach","key","exports","defineProperty","enumerable","get"],"sourceRoot":"../../../src","sources":["style/index.tsx"],"mappings":";;;;;AAAA,IAAAA,QAAA,GAAAC,OAAA;AAAAC,MAAA,CAAAC,IAAA,CAAAH,QAAA,EAAAI,OAAA,WAAAC,GAAA;EAAA,IAAAA,GAAA,kBAAAA,GAAA;EAAA,IAAAA,GAAA,IAAAC,OAAA,IAAAA,OAAA,CAAAD,GAAA,MAAAL,QAAA,CAAAK,GAAA;EAAAH,MAAA,CAAAK,cAAA,CAAAD,OAAA,EAAAD,GAAA;IAAAG,UAAA;IAAAC,GAAA,WAAAA,CAAA;MAAA,OAAAT,QAAA,CAAAK,GAAA;IAAA;EAAA;AAAA","ignoreList":[]}

package/lib/module/common/cva.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { cva } from 'class-variance-authority';
+//# sourceMappingURL=cva.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["cva"],"sourceRoot":"../../../src","sources":["common/cva.ts"],"mappings":";;AAAA,SAASA,GAAG,QAA2B,0BAA0B","ignoreList":[]}

package/lib/module/common/index.js

@@ -2,6 +2,7 @@
 
 export { ariaAttr } from './accessibilityUtils';
 export { cn } from './cn';
+export { cva } from './cva';
 export { composeEventHandlers } from './composeEventHandlers';
 export { flattenChildren } from './getSpacedChild';
 export { mergeRefs } from './mergeRefs';

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

@@ -1 +1 @@
-{"version":3,"names":["ariaAttr","cn","composeEventHandlers","flattenChildren","mergeRefs","useControllableState"],"sourceRoot":"../../../src","sources":["common/index.ts"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,sBAAsB;AAC/C,SAASC,EAAE,QAAQ,MAAM;AACzB,SAASC,oBAAoB,QAAQ,wBAAwB;AAC7D,SAASC,eAAe,QAAQ,kBAAkB;AAClD,SAASC,SAAS,QAAQ,aAAa;AACvC,SAA0CC,oBAAoB,QAAQ,wBAAwB","ignoreList":[]}
+{"version":3,"names":["ariaAttr","cn","cva","composeEventHandlers","flattenChildren","mergeRefs","useControllableState"],"sourceRoot":"../../../src","sources":["common/index.ts"],"mappings":";;AAAA,SAASA,QAAQ,QAAQ,sBAAsB;AAC/C,SAASC,EAAE,QAAQ,MAAM;AACzB,SAASC,GAAG,QAA2B,OAAO;AAC9C,SAASC,oBAAoB,QAAQ,wBAAwB;AAC7D,SAASC,eAAe,QAAQ,kBAAkB;AAClD,SAASC,SAAS,QAAQ,aAAa;AACvC,SAA0CC,oBAAoB,QAAQ,wBAAwB","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/context/createContext.js

@@ -2,8 +2,12 @@
 
 import { createContext as createReactContext, useContext } from 'react';
 import { jsx as _jsx } from "react/jsx-runtime";
-export function createContext(displayName) {
-  const Context = /*#__PURE__*/createReactContext(undefined);
+export function createContext(displayName, options) {
+  const {
+    defaultValue,
+    strict = true
+  } = options ?? {};
+  const Context = /*#__PURE__*/createReactContext(defaultValue);
   const Provider = props => {
     const {
       children,
@@ -17,7 +21,7 @@ export function createContext(displayName) {
   Provider.displayName = `${displayName}Provider`;
   function useC() {
     const context = useContext(Context);
-    if (context === undefined) {
+    if (context === undefined && strict) {
       throw new Error(`use${displayName} must be used within a ${displayName}Provider`);
     }
     return context;

package/lib/module/context/createContext.js.map

@@ -1 +1 @@
-{"version":3,"names":["createContext","createReactContext","useContext","jsx","_jsx","displayName","Context","undefined","Provider","props","children","value","useC","context","Error"],"sourceRoot":"../../../src","sources":["context/createContext.tsx"],"mappings":";;AAAA,SAEEA,aAAa,IAAIC,kBAAkB,EAEnCC,UAAU,QACL,OAAO;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAEf,OAAO,SAASJ,aAAaA,CAAIK,WAAmB,EAAE;EACpD,MAAMC,OAAO,gBAAGL,kBAAkB,CAAgBM,SAAS,CAAC;EAE5D,MAAMC,QAA0D,GAAIC,KAAK,IAAK;IAC5E,MAAM;MAAEC,QAAQ;MAAEC;IAAM,CAAC,GAAGF,KAAK;IACjC,oBAAOL,IAAA,CAACE,OAAO,CAACE,QAAQ;MAACG,KAAK,EAAEA,KAAM;MAAAD,QAAA,EAAEA;IAAQ,CAAmB,CAAC;EACtE,CAAC;EAEDF,QAAQ,CAACH,WAAW,GAAG,GAAGA,WAAW,UAAU;EAE/C,SAASO,IAAIA,CAAA,EAAM;IACjB,MAAMC,OAAO,GAAGX,UAAU,CAACI,OAAO,CAAC;IACnC,IAAIO,OAAO,KAAKN,SAAS,EAAE;MACzB,MAAM,IAAIO,KAAK,CAAC,MAAMT,WAAW,0BAA0BA,WAAW,UAAU,CAAC;IACnF;IACA,OAAOQ,OAAO;EAChB;EAEA,OAAO,CAACL,QAAQ,EAAEI,IAAI,CAAC;AACzB","ignoreList":[]}
+{"version":3,"names":["createContext","createReactContext","useContext","jsx","_jsx","displayName","options","defaultValue","strict","Context","Provider","props","children","value","useC","context","undefined","Error"],"sourceRoot":"../../../src","sources":["context/createContext.tsx"],"mappings":";;AAAA,SAEEA,aAAa,IAAIC,kBAAkB,EAEnCC,UAAU,QACL,OAAO;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAiBf,OAAO,SAASJ,aAAaA,CAAIK,WAAmB,EAAEC,OAAiC,EAAE;EACvF,MAAM;IAAEC,YAAY;IAAEC,MAAM,GAAG;EAAK,CAAC,GAAGF,OAAO,IAAI,CAAC,CAAC;EAErD,MAAMG,OAAO,gBAAGR,kBAAkB,CAAgBM,YAAY,CAAC;EAE/D,MAAMG,QAA0D,GAAIC,KAAK,IAAK;IAC5E,MAAM;MAAEC,QAAQ;MAAEC;IAAM,CAAC,GAAGF,KAAK;IACjC,oBAAOP,IAAA,CAACK,OAAO,CAACC,QAAQ;MAACG,KAAK,EAAEA,KAAM;MAAAD,QAAA,EAAEA;IAAQ,CAAmB,CAAC;EACtE,CAAC;EAEDF,QAAQ,CAACL,WAAW,GAAG,GAAGA,WAAW,UAAU;EAE/C,SAASS,IAAIA,CAAA,EAAM;IACjB,MAAMC,OAAO,GAAGb,UAAU,CAACO,OAAO,CAAC;IACnC,IAAIM,OAAO,KAAKC,SAAS,IAAIR,MAAM,EAAE;MACnC,MAAM,IAAIS,KAAK,CAAC,MAAMZ,WAAW,0BAA0BA,WAAW,UAAU,CAAC;IACnF;IACA,OAAOU,OAAO;EAChB;EAEA,OAAO,CAACL,QAAQ,EAAEI,IAAI,CAAC;AACzB","ignoreList":[]}

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

@@ -1,4 +1,4 @@
 "use strict";
 
-export { FormControlContext, useFormControl, useFormControlContext, useFormControlRoot } from './useFormControl';
+export { FormControlContext, useFormControl, useFormControlContext, useFormControlRoot, useReportFormControlLabelFocus } from './useFormControl';
 //# sourceMappingURL=index.js.map

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

@@ -1 +1 @@
-{"version":3,"names":["FormControlContext","useFormControl","useFormControlContext","useFormControlRoot"],"sourceRoot":"../../../src","sources":["form-control/index.ts"],"mappings":";;AAAA,SAMEA,kBAAkB,EAClBC,cAAc,EACdC,qBAAqB,EACrBC,kBAAkB,QACb,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. */
@@ -38,6 +49,7 @@ export function useFormControlRoot(props) {
    * We use this to append its id the the `aria-describedby` of the `input`.
    */
   const [hasHelpText, setHasHelpText] = React.useState(false);
+  const [isLabelFocused, setIsLabelFocused] = React.useState(false);
   const inputRef = React.useRef(null);
   const focusInput = React.useCallback(() => {
     const node = inputRef.current;
@@ -60,6 +72,8 @@ export function useFormControlRoot(props) {
     feedbackId,
     helpTextId,
     htmlProps,
+    isLabelFocused,
+    setIsLabelFocused,
     ...(Platform.OS !== 'web' ? {
       inputRef,
       focusInput
@@ -68,6 +82,25 @@ export function useFormControlRoot(props) {
   return context;
 }
 
+/**
+ * Reports focus/active state from `Input` / `Select.Trigger` to the parent `Field` for label styling.
+ * No-ops outside a `Field` (no `setIsLabelFocused` on context).
+ */
+export function useReportFormControlLabelFocus(isActive) {
+  const {
+    setIsLabelFocused
+  } = useFormControlContext();
+  React.useLayoutEffect(() => {
+    if (typeof setIsLabelFocused !== 'function') {
+      return undefined;
+    }
+    setIsLabelFocused(isActive);
+    return () => {
+      setIsLabelFocused(false);
+    };
+  }, [isActive, setIsLabelFocused]);
+}
+
 /**
  * Hook that merges local field props with the nearest form field context
  * and returns normalised HTML / ARIA attributes for input elements.