@cdx-ui/utils 0.0.1-alpha.39 → 0.0.1-alpha.40
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +47 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,10 +2,56 @@
|
|
|
2
2
|
|
|
3
3
|
Shared utilities used across CDS packages.
|
|
4
4
|
|
|
5
|
-
Provides common helpers for styling,
|
|
5
|
+
Provides common helpers for styling, event handling, state management, and context propagation used by [`@cdx-ui/primitives`](../primitives/) and [`@cdx-ui/components`](../components/).
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
10
|
pnpm add @cdx-ui/utils
|
|
11
11
|
```
|
|
12
|
+
|
|
13
|
+
## Exports
|
|
14
|
+
|
|
15
|
+
### Common helpers
|
|
16
|
+
|
|
17
|
+
| Export | Description |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| `cn(...inputs)` | Merges class names with `clsx` + `tailwind-merge` — conditionals and conflict resolution in one call. |
|
|
20
|
+
| `composeEventHandlers(...handlers)` | Chains multiple event callbacks into a single handler; skips `null`/`undefined` entries. |
|
|
21
|
+
| `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. |
|
|
22
|
+
| `mergeRefs(...refs)` | Combines multiple refs (callback or object) into one ref callback. |
|
|
23
|
+
| `flattenChildren(children)` | Recursively flattens React `children` into a flat array (used internally for spaced-child layouts). |
|
|
24
|
+
| `ariaAttr(condition)` | Returns `'true'` or `undefined` — shorthand for boolean ARIA attribute values. |
|
|
25
|
+
|
|
26
|
+
### Context
|
|
27
|
+
|
|
28
|
+
| Export | Description |
|
|
29
|
+
| --- | --- |
|
|
30
|
+
| `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. |
|
|
31
|
+
|
|
32
|
+
### Style context
|
|
33
|
+
|
|
34
|
+
Used internally by `@cdx-ui/components` to propagate variant props (size, color, etc.) from a compound root to its sub-components.
|
|
35
|
+
|
|
36
|
+
| Export | Description |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| `withStyleContext(Component, scope?)` | HOC that adds a `context` prop and provides it to descendants via `ParentContext`. |
|
|
39
|
+
| `useStyleContext(scope?)` | Reads the style context set by the nearest `withStyleContext` wrapper. |
|
|
40
|
+
| `useParentContext()` | Reads the full `StyleContextMap` from the nearest provider. |
|
|
41
|
+
| `ParentContext` | The raw React context (rarely needed directly). |
|
|
42
|
+
|
|
43
|
+
### Form control
|
|
44
|
+
|
|
45
|
+
Low-level form-field state used by the `Field` and `Input` primitives.
|
|
46
|
+
|
|
47
|
+
| Export | Description |
|
|
48
|
+
| --- | --- |
|
|
49
|
+
| `useFormControlRoot(props)` | Creates the root state object for a form field (id generation, `aria-describedby` wiring). |
|
|
50
|
+
| `useFormControl(props)` | Merges component-level props with inherited form-control context. |
|
|
51
|
+
| `useFormControlContext()` | Reads form-control state from the nearest provider. |
|
|
52
|
+
| `FormControlContext` | The raw React context for form-control state. |
|
|
53
|
+
|
|
54
|
+
## Further reading
|
|
55
|
+
|
|
56
|
+
- [State management practices](../../docs/internal/practices/state.md) — `useControllableState` and `composeEventHandlers` patterns
|
|
57
|
+
- [Styling practices](../../docs/internal/practices/styling.md) — `cn()` and CVA variant authoring
|