@cdx-ui/utils

Shared utilities used across FDS packages.

Provides common helpers for styling, event handling, state management, and context propagation used by @cdx-ui/primitives and @cdx-ui/components.

Installation

pnpm add @cdx-ui/utils

Exports

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. 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 | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | 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, 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 | | Focusable | form-control | | 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:

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 — useControllableState and composeEventHandlers patterns
• Styling practices — cn() and CVA variant authoring