@cdx-ui/utils 0.0.1-beta.6 → 0.0.1-beta.61

package/README.md

@@ -1,6 +1,6 @@
 # @cdx-ui/utils
 
-Shared utilities used across CDS packages.
+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,42 +14,65 @@ 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.                                                     |
 
 ### 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 |
-| --- | --- |
+| 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). |
+| `useStyleContext(scope?)`             | Reads the style context set by the nearest `withStyleContext` wrapper.             |
+| `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. |
+| 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       |
+| `FormControlContextValue`    | form-control |
+| `FormControlFieldProps`      | form-control |
+| `FormControlRootProps`       | form-control |
+| `FormControlRootReturn`      | form-control |
+| `FormControlState`           | form-control |
+| `StyleContextMap`            | style        |
+| `WithStyleContextProps`      | 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
 

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,6 +7,7 @@ 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");
@@ -46,6 +47,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 +70,8 @@ function useFormControlRoot(props) {
     feedbackId,
     helpTextId,
     htmlProps,
+    isLabelFocused,
+    setIsLabelFocused,
     ...(_reactNative.Platform.OS !== 'web' ? {
       inputRef,
       focusInput
@@ -76,6 +80,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/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,SAMEA,kBAAkB,EAClBC,cAAc,EACdC,qBAAqB,EACrBC,kBAAkB,EAClBC,8BAA8B,QACzB,kBAAkB","ignoreList":[]}

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

@@ -38,6 +38,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 +61,8 @@ export function useFormControlRoot(props) {
     feedbackId,
     helpTextId,
     htmlProps,
+    isLabelFocused,
+    setIsLabelFocused,
     ...(Platform.OS !== 'web' ? {
       inputRef,
       focusInput
@@ -68,6 +71,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.

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

@@ -1,2 +1,2 @@
-export { type FormControlContextValue, type FormControlFieldProps, type FormControlRootProps, type FormControlRootReturn, type FormControlState, FormControlContext, useFormControl, useFormControlContext, useFormControlRoot, } from './useFormControl';
+export { 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,GACnB,MAAM,kBAAkB,CAAC"}
+{"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"}

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

@@ -24,6 +24,9 @@ export interface FormControlContextValue extends FormControlState {
      */
     inputRef?: React.RefObject<TextInput | null>;
     focusInput?: () => void;
+    /** True when the primary child control is focused or (for Select) open — drives `Field.Label` styling. */
+    isLabelFocused?: boolean;
+    setIsLabelFocused?: React.Dispatch<React.SetStateAction<boolean>>;
 }
 export declare const FormControlContext: React.Context<Partial<FormControlContextValue>>;
 export interface FormControlFieldProps extends Partial<FormControlState> {
@@ -51,12 +54,19 @@ export interface FormControlRootReturn {
     htmlProps: HTMLProps;
     inputRef?: React.RefObject<TextInput | null>;
     focusInput?: () => void;
+    isLabelFocused: boolean;
+    setIsLabelFocused: React.Dispatch<React.SetStateAction<boolean>>;
 }
 /**
  * Builds state and ids for a `Form` primitive root (`createFormRoot`). Pass the returned object
  * (minus `htmlProps`) to `FormControlContext.Provider` — this is not a React context consumer hook.
  */
 export declare function useFormControlRoot(props: FormControlRootProps): FormControlRootReturn;
+/**
+ * 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 declare function useReportFormControlLabelFocus(isActive: boolean): void;
 /**
  * Hook that merges local field props with the nearest form field context
  * and returns normalised HTML / ARIA attributes for input elements.

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":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAGxD,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzC,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,uBAAwB,SAAQ,gBAAgB;IAC/D,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,kBAAkB,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,cAAc,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED,eAAO,MAAM,kBAAkB,iDAA4D,CAAC;AAE5F,MAAM,WAAW,qBAAsB,SAAQ,OAAO,CAAC,gBAAgB,CAAC;IACtE,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,4FAA4F;AAC5F,MAAM,MAAM,oBAAoB,GAAG,OAAO,CAAC,gBAAgB,CAAC,GAAG;IAC7D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,SAAS,CAAC;AAEd,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAClE,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAC7C,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CAkDrF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,qBAAqB;;;;;;;;;;;EA4B1D;AAED,eAAO,MAAM,qBAAqB,wCAEjC,CAAC"}
+{"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.6",
+  "version": "0.0.1-beta.61",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
   "react-native": "src/index.ts",
@@ -22,6 +22,7 @@
   "react-native-builder-bob": {
     "source": "src",
     "output": "lib",
+    "exclude": "**/{__tests__/**,__fixtures__/**,__mocks__/**,*.test.ts,*.test.tsx,*.spec.ts,*.spec.tsx}",
     "targets": [
       "commonjs",
       "module",
@@ -67,6 +68,7 @@
   },
   "scripts": {
     "build": "bob build",
-    "lint": "eslint src/"
+    "lint": "eslint src/",
+    "test": "jest --config ../../jest.config.js --selectProjects utils"
   }
 }

package/src/common/accessibilityUtils.test.ts

@@ -0,0 +1,12 @@
+import { ariaAttr } from './accessibilityUtils';
+
+describe('ariaAttr', () => {
+  it('returns true when condition is true', () => {
+    expect(ariaAttr(true)).toBe(true);
+  });
+
+  it('returns undefined when condition is false or undefined', () => {
+    expect(ariaAttr(false)).toBeUndefined();
+    expect(ariaAttr(undefined)).toBeUndefined();
+  });
+});

package/src/common/cn.test.ts

@@ -0,0 +1,19 @@
+import { cn } from './cn';
+
+describe('cn', () => {
+  it('merges conflicting Tailwind classes', () => {
+    expect(cn('px-2', 'px-4')).toBe('px-4');
+  });
+
+  it('joins non-conflicting classes', () => {
+    expect(cn('px-2', 'py-1')).toBe('px-2 py-1');
+  });
+
+  it('ignores falsy inputs', () => {
+    expect(cn('foo', undefined, null, false, '')).toBe('foo');
+  });
+
+  it('returns empty string when called with no inputs', () => {
+    expect(cn()).toBe('');
+  });
+});

package/src/common/composeEventHandlers.test.ts

@@ -0,0 +1,35 @@
+import { composeEventHandlers } from './composeEventHandlers';
+
+describe('composeEventHandlers', () => {
+  it('calls handlers in order', () => {
+    const order: number[] = [];
+    const first = jest.fn(() => {
+      order.push(1);
+    });
+    const second = jest.fn(() => {
+      order.push(2);
+    });
+
+    composeEventHandlers(first, second)({ type: 'press' });
+
+    expect(order).toEqual([1, 2]);
+    expect(first).toHaveBeenCalledWith({ type: 'press' });
+    expect(second).toHaveBeenCalledWith({ type: 'press' });
+  });
+
+  it('skips null and undefined handlers', () => {
+    const handler = jest.fn();
+
+    composeEventHandlers(null, undefined, handler)({});
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns a no-op when no handlers are provided', () => {
+    const handleEvent = composeEventHandlers();
+
+    expect(() => {
+      handleEvent({});
+    }).not.toThrow();
+  });
+});

package/src/common/getSpacedChild.test.tsx

@@ -0,0 +1,64 @@
+import React, { isValidElement } from 'react';
+import { Text } from 'react-native';
+import { flattenChildren } from './getSpacedChild';
+
+describe('flattenChildren', () => {
+  it('flattens fragment children', () => {
+    const result = flattenChildren(
+      <>
+        <Text key="a">A</Text>
+        <Text key="b">B</Text>
+      </>,
+    );
+
+    expect(result).toHaveLength(2);
+    expect(isValidElement(result[0]) && result[0].type).toBe(Text);
+    expect(isValidElement(result[1]) && result[1].type).toBe(Text);
+  });
+
+  it('assigns composite keys to nested fragment children', () => {
+    const result = flattenChildren(
+      <React.Fragment key="group">
+        <Text key="child">Child</Text>
+      </React.Fragment>,
+    );
+
+    expect(result).toHaveLength(1);
+    const key = isValidElement(result[0]) ? String(result[0].key) : '';
+    expect(key).toContain('group');
+    expect(key).toContain('child');
+  });
+
+  it('passes through non-element children', () => {
+    const result = flattenChildren(['plain', <Text key="t">T</Text>]);
+
+    expect(result).toHaveLength(2);
+    expect(result[0]).toBe('plain');
+  });
+
+  it('preserves explicit element keys', () => {
+    const result = flattenChildren(<Text key="explicit">Label</Text>);
+
+    expect(result).toHaveLength(1);
+    const key = isValidElement(result[0]) ? String(result[0].key) : '';
+    expect(key).toContain('explicit');
+  });
+
+  it('uses index keys when fragment and child keys are missing', () => {
+    const result = flattenChildren(
+      <>
+        <Text>First</Text>
+        <React.Fragment>
+          <Text>Nested</Text>
+        </React.Fragment>
+      </>,
+    );
+
+    expect(result).toHaveLength(2);
+    const firstKey = isValidElement(result[0]) ? String(result[0].key) : '';
+    const secondKey = isValidElement(result[1]) ? String(result[1].key) : '';
+    expect(firstKey).toContain('0');
+    expect(secondKey).toContain('1');
+    expect(secondKey).toContain('0');
+  });
+});

package/src/common/mergeRefs.test.ts

@@ -0,0 +1,40 @@
+import { createRef } from 'react';
+import { mergeRefs } from './mergeRefs';
+
+describe('mergeRefs', () => {
+  it('assigns value to object refs', () => {
+    const refA = createRef<string>();
+    const refB = createRef<string>();
+
+    mergeRefs(refA, refB)('value');
+
+    expect(refA.current).toBe('value');
+    expect(refB.current).toBe('value');
+  });
+
+  it('invokes callback refs', () => {
+    const callback = jest.fn();
+
+    mergeRefs(callback)('value');
+
+    expect(callback).toHaveBeenCalledWith('value');
+  });
+
+  it('skips undefined refs and assigns null', () => {
+    const ref = createRef<string | null>();
+
+    mergeRefs(undefined, ref)(null);
+
+    expect(ref.current).toBeNull();
+  });
+
+  it('updates callback and object refs together', () => {
+    const callback = jest.fn();
+    const objectRef = createRef<string | null>();
+
+    mergeRefs(callback, objectRef)('shared');
+
+    expect(callback).toHaveBeenCalledWith('shared');
+    expect(objectRef.current).toBe('shared');
+  });
+});

package/src/common/useControllableState.test.tsx

@@ -0,0 +1,90 @@
+import { act, renderHook } from '@testing-library/react-native';
+import { useControllableState } from './useControllableState';
+
+describe('useControllableState', () => {
+  it('manages uncontrolled state from defaultProp', () => {
+    const onChange = jest.fn();
+    const { result } = renderHook(() => useControllableState({ defaultProp: 'initial', onChange }));
+
+    expect(result.current[0]).toBe('initial');
+
+    act(() => {
+      result.current[1]('next');
+    });
+
+    expect(result.current[0]).toBe('next');
+    expect(onChange).toHaveBeenCalledWith('next');
+  });
+
+  it('uses prop value in controlled mode and notifies onChange', () => {
+    const onChange = jest.fn();
+    const { result } = renderHook(() => useControllableState({ prop: 'controlled', onChange }));
+
+    expect(result.current[0]).toBe('controlled');
+
+    act(() => {
+      result.current[1]('updated');
+    });
+
+    expect(onChange).toHaveBeenCalledWith('updated');
+    expect(result.current[0]).toBe('controlled');
+  });
+
+  it('supports function updaters in uncontrolled mode', () => {
+    const { result } = renderHook(() => useControllableState({ defaultProp: 1 }));
+
+    act(() => {
+      result.current[1]((prev: number | undefined) => (prev ?? 0) + 1);
+    });
+
+    expect(result.current[0]).toBe(2);
+  });
+
+  it('follows prop updates in controlled mode', () => {
+    const { result, rerender } = renderHook(({ value }) => useControllableState({ prop: value }), {
+      initialProps: { value: 'a' },
+    });
+
+    rerender({ value: 'b' });
+
+    expect(result.current[0]).toBe('b');
+  });
+
+  it('supports function updaters in controlled mode', () => {
+    const onChange = jest.fn();
+    const { result } = renderHook(() => useControllableState({ prop: 2, onChange }));
+
+    act(() => {
+      result.current[1]((prev: number | undefined) => (prev ?? 0) + 3);
+    });
+
+    expect(onChange).toHaveBeenCalledWith(5);
+    expect(result.current[0]).toBe(2);
+  });
+
+  it('does not notify onChange when controlled value is unchanged', () => {
+    const onChange = jest.fn();
+    const { result } = renderHook(() => useControllableState({ prop: 'same', onChange }));
+
+    act(() => {
+      result.current[1]('same');
+    });
+
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it('switches from uncontrolled to controlled when prop is provided', () => {
+    const { result, rerender } = renderHook(
+      (props: { prop?: string; defaultProp?: string }) => useControllableState(props),
+      { initialProps: { defaultProp: 'internal' } },
+    );
+
+    act(() => {
+      result.current[1]('internal');
+    });
+
+    rerender({ prop: 'external' });
+
+    expect(result.current[0]).toBe('external');
+  });
+});

package/src/context/createContext.test.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+import { renderHook } from '@testing-library/react-native';
+import { createContext } from './createContext';
+
+describe('createContext', () => {
+  it('provides value through Provider and consumer hook', () => {
+    const [Provider, useTestContext] = createContext<{ label: string }>('Test');
+
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <Provider value={{ label: 'hello' }}>{children}</Provider>
+    );
+
+    const { result } = renderHook(() => useTestContext(), { wrapper });
+
+    expect(result.current).toEqual({ label: 'hello' });
+  });
+
+  it('throws when consumer is used outside Provider', () => {
+    const [, useTestContext] = createContext<{ label: string }>('Test');
+
+    expect(() => {
+      renderHook(() => useTestContext());
+    }).toThrow('useTest must be used within a TestProvider');
+  });
+
+  it('names the Provider from the display name argument', () => {
+    const [Provider] = createContext<{ label: string }>('Field');
+
+    expect(Provider.displayName).toBe('FieldProvider');
+  });
+});

package/src/form-control/index.ts

@@ -8,4 +8,5 @@ export {
   useFormControl,
   useFormControlContext,
   useFormControlRoot,
+  useReportFormControlLabelFocus,
 } from './useFormControl';

package/src/form-control/useFormControl.test.tsx

@@ -0,0 +1,214 @@
+import type { ReactNode } from 'react';
+import { Platform, type TextInput } from 'react-native';
+import { act, renderHook } from '@testing-library/react-native';
+import {
+  FormControlContext,
+  useFormControl,
+  useFormControlContext,
+  useFormControlRoot,
+  useReportFormControlLabelFocus,
+} from './useFormControl';
+
+function FormControlTestProvider({
+  children,
+  rootProps,
+  hasFeedbackText = false,
+  hasHelpText = false,
+}: {
+  children: ReactNode;
+  rootProps?: Parameters<typeof useFormControlRoot>[0];
+  hasFeedbackText?: boolean;
+  hasHelpText?: boolean;
+}) {
+  const root = useFormControlRoot(rootProps ?? { id: 'email' });
+
+  return (
+    <FormControlContext.Provider value={{ ...root, hasFeedbackText, hasHelpText }}>
+      {children}
+    </FormControlContext.Provider>
+  );
+}
+
+describe('useFormControlRoot', () => {
+  it('uses provided id and coerces boolean state flags', () => {
+    const { result } = renderHook(() =>
+      useFormControlRoot({
+        id: 'custom-id',
+        isRequired: true,
+        isInvalid: true,
+        isDisabled: false,
+        isReadOnly: false,
+        name: 'email',
+        'data-test': 'root',
+      }),
+    );
+
+    expect(result.current.id).toBe('custom-id');
+    expect(result.current.labelId).toBe('custom-id-label');
+    expect(result.current.isRequired).toBe(true);
+    expect(result.current.isInvalid).toBe(true);
+    expect(result.current.isDisabled).toBe(false);
+    expect(result.current.isReadOnly).toBe(false);
+    expect(result.current.name).toBe('email');
+    expect(result.current.htmlProps).toEqual({ 'data-test': 'root' });
+  });
+
+  it('generates an id when none is provided', () => {
+    const { result } = renderHook(() => useFormControlRoot({}));
+
+    expect(result.current.id).toMatch(/^field-/);
+    expect(result.current.feedbackId).toBe(`${result.current.id}-feedback`);
+  });
+
+  it('ignores empty string id and generates a fallback', () => {
+    const { result } = renderHook(() => useFormControlRoot({ id: '' }));
+
+    expect(result.current.id).toMatch(/^field-/);
+    expect(result.current.id).not.toBe('');
+  });
+
+  it('exposes native focus helpers by default', () => {
+    const { result } = renderHook(() => useFormControlRoot({}));
+
+    expect(result.current.inputRef).toBeDefined();
+    expect(result.current.focusInput).toBeDefined();
+
+    const { inputRef, focusInput } = result.current;
+    if (!inputRef || !focusInput) {
+      throw new Error('expected native focus helpers');
+    }
+
+    const focus = jest.fn();
+    act(() => {
+      inputRef.current = { focus } as TextInput;
+      focusInput();
+    });
+
+    expect(focus).toHaveBeenCalled();
+  });
+
+  it('no-ops focusInput when ref is empty or focus is unavailable', () => {
+    const { result } = renderHook(() => useFormControlRoot({}));
+    const { focusInput, inputRef } = result.current;
+
+    if (!focusInput || !inputRef) {
+      throw new Error('expected native focus helpers');
+    }
+
+    expect(() => {
+      focusInput();
+    }).not.toThrow();
+
+    act(() => {
+      inputRef.current = {} as TextInput;
+      focusInput();
+    });
+
+    expect(inputRef.current).toEqual({});
+  });
+
+  it('omits native focus helpers on web', () => {
+    const originalDescriptor = Object.getOwnPropertyDescriptor(Platform, 'OS');
+    Object.defineProperty(Platform, 'OS', { configurable: true, get: () => 'web' });
+
+    const { result } = renderHook(() => useFormControlRoot({}));
+
+    expect(result.current.inputRef).toBeUndefined();
+    expect(result.current.focusInput).toBeUndefined();
+
+    if (originalDescriptor) {
+      Object.defineProperty(Platform, 'OS', originalDescriptor);
+    }
+  });
+});
+
+describe('useFormControl', () => {
+  it('merges local props with context and composes aria-describedby', () => {
+    const { result } = renderHook(() => useFormControl({ id: 'override', isDisabled: true }), {
+      wrapper: ({ children }) => (
+        <FormControlTestProvider
+          rootProps={{
+            id: 'email',
+            name: 'email',
+            isRequired: true,
+            isInvalid: true,
+            isDisabled: false,
+            isReadOnly: false,
+          }}
+          hasFeedbackText
+          hasHelpText
+        >
+          {children}
+        </FormControlTestProvider>
+      ),
+    });
+
+    expect(result.current.id).toBe('override');
+    expect(result.current.name).toBe('email');
+    expect(result.current.disabled).toBe(true);
+    expect(result.current.required).toBe(true);
+    expect(result.current['aria-invalid']).toBe(true);
+    expect(result.current['aria-labelledby']).toBe('email-label');
+    expect(result.current['aria-describedby']).toBe('email-feedback email-helptext');
+  });
+
+  it('returns undefined aria-describedby when no help or feedback is present', () => {
+    const { result } = renderHook(() => useFormControl({}), {
+      wrapper: ({ children }) => <FormControlTestProvider>{children}</FormControlTestProvider>,
+    });
+
+    expect(result.current['aria-describedby']).toBeUndefined();
+    expect(result.current.id).toBe('email-input');
+  });
+
+  it('composes aria-describedby from feedback or help text alone', () => {
+    const feedbackOnly = renderHook(() => useFormControl({}), {
+      wrapper: ({ children }) => (
+        <FormControlTestProvider hasFeedbackText>{children}</FormControlTestProvider>
+      ),
+    }).result.current['aria-describedby'];
+
+    const helpOnly = renderHook(() => useFormControl({}), {
+      wrapper: ({ children }) => (
+        <FormControlTestProvider hasHelpText>{children}</FormControlTestProvider>
+      ),
+    }).result.current['aria-describedby'];
+
+    expect(feedbackOnly).toBe('email-feedback');
+    expect(helpOnly).toBe('email-helptext');
+  });
+
+  it('merges readOnly from local props and omits id without field context', () => {
+    const { result } = renderHook(() => useFormControl({ isReadOnly: true }));
+
+    expect(result.current.readOnly).toBe(true);
+    expect(result.current.id).toBeUndefined();
+  });
+});
+
+describe('useReportFormControlLabelFocus', () => {
+  it('reports active state to the form control context', () => {
+    const { result, rerender } = renderHook(
+      ({ active }: { active: boolean }) => {
+        useReportFormControlLabelFocus(active);
+        return useFormControlContext().isLabelFocused;
+      },
+      {
+        wrapper: ({ children }) => <FormControlTestProvider>{children}</FormControlTestProvider>,
+        initialProps: { active: true },
+      },
+    );
+
+    expect(result.current).toBe(true);
+
+    rerender({ active: false });
+
+    expect(result.current).toBe(false);
+  });
+
+  it('no-ops when setIsLabelFocused is unavailable', () => {
+    expect(() => {
+      renderHook(() => useReportFormControlLabelFocus(true));
+    }).not.toThrow();
+  });
+});

package/src/form-control/useFormControl.tsx

@@ -28,6 +28,9 @@ export interface FormControlContextValue extends FormControlState {
    */
   inputRef?: React.RefObject<TextInput | null>;
   focusInput?: () => void;
+  /** True when the primary child control is focused or (for Select) open — drives `Field.Label` styling. */
+  isLabelFocused?: boolean;
+  setIsLabelFocused?: React.Dispatch<React.SetStateAction<boolean>>;
 }
 
 export const FormControlContext = React.createContext<Partial<FormControlContextValue>>({});
@@ -59,6 +62,8 @@ export interface FormControlRootReturn {
   htmlProps: HTMLProps;
   inputRef?: React.RefObject<TextInput | null>;
   focusInput?: () => void;
+  isLabelFocused: boolean;
+  setIsLabelFocused: React.Dispatch<React.SetStateAction<boolean>>;
 }
 
 /**
@@ -87,6 +92,8 @@ export function useFormControlRoot(props: FormControlRootProps): FormControlRoot
    */
   const [hasHelpText, setHasHelpText] = React.useState(false);
 
+  const [isLabelFocused, setIsLabelFocused] = React.useState(false);
+
   const inputRef = React.useRef<TextInput | null>(null);
 
   const focusInput = React.useCallback(() => {
@@ -111,12 +118,32 @@ export function useFormControlRoot(props: FormControlRootProps): FormControlRoot
     feedbackId,
     helpTextId,
     htmlProps,
+    isLabelFocused,
+    setIsLabelFocused,
     ...(Platform.OS !== 'web' ? { inputRef, focusInput } : {}),
   };
 
   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: boolean) {
+  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.

package/src/style/context/index.test.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+import { renderHook } from '@testing-library/react-native';
+import { ParentContext, useParentContext, useStyleContext } from './index';
+
+describe('style context hooks', () => {
+  it('reads parent context values', () => {
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <ParentContext.Provider value={{ Button: { size: 'lg' }, Card: { padded: true } }}>
+        {children}
+      </ParentContext.Provider>
+    );
+
+    const { result: parentResult } = renderHook(() => useParentContext(), { wrapper });
+    const { result: styleResult } = renderHook(() => useStyleContext('Button'), { wrapper });
+
+    expect(parentResult.current).toEqual({ Button: { size: 'lg' }, Card: { padded: true } });
+    expect(styleResult.current).toEqual({ size: 'lg' });
+  });
+
+  it('defaults to Global scope', () => {
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <ParentContext.Provider value={{ Global: { theme: 'dark' } }}>
+        {children}
+      </ParentContext.Provider>
+    );
+
+    const { result } = renderHook(() => useStyleContext(), { wrapper });
+
+    expect(result.current).toEqual({ theme: 'dark' });
+  });
+});

package/src/style/withStyleContext/index.test.tsx

@@ -0,0 +1,55 @@
+import { Text, View } from 'react-native';
+import { render, screen } from '@testing-library/react-native';
+import { useStyleContext } from '../context';
+import { withStyleContext } from './index';
+
+const StyledView = withStyleContext(View, 'Button');
+
+function StyleConsumer() {
+  const context = useStyleContext('Button');
+  return <Text testID="style-context">{JSON.stringify(context)}</Text>;
+}
+
+describe('withStyleContext', () => {
+  it('provides scoped context to descendants', () => {
+    render(
+      <StyledView context={{ size: 'lg' }} testID="wrapped">
+        <StyleConsumer />
+      </StyledView>,
+    );
+
+    expect(screen.getByTestId('style-context')).toHaveTextContent('{"size":"lg"}');
+    expect(screen.getByTestId('wrapped')).toBeTruthy();
+  });
+
+  it('inherits parent context for other scopes', () => {
+    const Outer = withStyleContext(View, 'Card');
+
+    render(
+      <Outer context={{ padded: true }} testID="outer">
+        <StyledView context={{ size: 'sm' }} testID="inner">
+          <StyleConsumer />
+        </StyledView>
+      </Outer>,
+    );
+
+    expect(screen.getByTestId('style-context')).toHaveTextContent('{"size":"sm"}');
+  });
+
+  it('defaults to the Global scope when none is provided', () => {
+    const GlobalView = withStyleContext(View);
+
+    function GlobalConsumer() {
+      const context = useStyleContext('Global');
+      return <Text testID="global-context">{JSON.stringify(context)}</Text>;
+    }
+
+    render(
+      <GlobalView context={{ theme: 'dark' }} testID="global-wrapped">
+        <GlobalConsumer />
+      </GlobalView>,
+    );
+
+    expect(screen.getByTestId('global-context')).toHaveTextContent('{"theme":"dark"}');
+  });
+});