@cdx-ui/utils 0.0.1-alpha.8 → 0.0.1-beta.1

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.
Files changed (16) hide show
  1. package/README.md +47 -1
  2. package/lib/commonjs/form-control/index.js +6 -0
  3. package/lib/commonjs/form-control/index.js.map +1 -1
  4. package/lib/commonjs/form-control/useFormControl.js +79 -11
  5. package/lib/commonjs/form-control/useFormControl.js.map +1 -1
  6. package/lib/module/form-control/index.js +1 -1
  7. package/lib/module/form-control/index.js.map +1 -1
  8. package/lib/module/form-control/useFormControl.js +78 -11
  9. package/lib/module/form-control/useFormControl.js.map +1 -1
  10. package/lib/typescript/form-control/index.d.ts +1 -1
  11. package/lib/typescript/form-control/index.d.ts.map +1 -1
  12. package/lib/typescript/form-control/useFormControl.d.ts +41 -1
  13. package/lib/typescript/form-control/useFormControl.d.ts.map +1 -1
  14. package/package.json +1 -1
  15. package/src/form-control/index.ts +3 -0
  16. package/src/form-control/useFormControl.tsx +103 -10
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, platform detection, and other cross-cutting concerns used by [`@cdx-ui/primitives`](../primitives/) and [`@cdx-ui/components`](../components/).
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
package/lib/commonjs/form-control/index.js CHANGED
@@ -21,5 +21,11 @@ Object.defineProperty(exports, "useFormControlContext", {
21
21
  return _useFormControl.useFormControlContext;
22
22
  }
23
23
  });
24
+ Object.defineProperty(exports, "useFormControlRoot", {
25
+ enumerable: true,
26
+ get: function () {
27
+ return _useFormControl.useFormControlRoot;
28
+ }
29
+ });
24
30
  var _useFormControl = require("./useFormControl");
25
31
  //# sourceMappingURL=index.js.map
package/lib/commonjs/form-control/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"names":["_useFormControl","require"],"sourceRoot":"../../../src","sources":["form-control/index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAAA,IAAAA,eAAA,GAAAC,OAAA","ignoreList":[]}
1
+ {"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 CHANGED
@@ -6,21 +6,87 @@ Object.defineProperty(exports, "__esModule", {
6
6
  exports.FormControlContext = void 0;
7
7
  exports.useFormControl = useFormControl;
8
8
  exports.useFormControlContext = void 0;
9
+ exports.useFormControlRoot = useFormControlRoot;
9
10
  var _react = _interopRequireDefault(require("react"));
11
+ var _reactNative = require("react-native");
10
12
  var _accessibilityUtils = require("../common/accessibilityUtils");
11
13
  function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
12
14
  const FormControlContext = exports.FormControlContext = /*#__PURE__*/_react.default.createContext({});
15
+
16
+ /** Props for the FormControl root; known fields plus passthrough to the styled root box. */
17
+
18
+ /**
19
+ * Builds state and ids for a `Form` primitive root (`createFormRoot`). Pass the returned object
20
+ * (minus `htmlProps`) to `FormControlContext.Provider` — this is not a React context consumer hook.
21
+ */
22
+ function useFormControlRoot(props) {
23
+ const {
24
+ id: idProp,
25
+ name,
26
+ isRequired,
27
+ isInvalid,
28
+ isDisabled,
29
+ isReadOnly,
30
+ ...htmlProps
31
+ } = props;
32
+ const reactId = _react.default.useId();
33
+ const id = (typeof idProp === 'string' && idProp !== '' ? idProp : null) ?? `field-${reactId}`;
34
+ const labelId = `${id}-label`;
35
+ const feedbackId = `${id}-feedback`;
36
+ const helpTextId = `${id}-helptext`;
37
+
38
+ /**
39
+ * Track whether the `FormErrorMessage` has been rendered.
40
+ * We use this to append its id the the `aria-describedby` of the `input`.
41
+ */
42
+ const [hasFeedbackText, setHasFeedbackText] = _react.default.useState(false);
43
+
44
+ /**
45
+ * Track whether the `FormHelperText` has been rendered.
46
+ * We use this to append its id the the `aria-describedby` of the `input`.
47
+ */
48
+ const [hasHelpText, setHasHelpText] = _react.default.useState(false);
49
+ const inputRef = _react.default.useRef(null);
50
+ const focusInput = _react.default.useCallback(() => {
51
+ const node = inputRef.current;
52
+ if (node != null && typeof node.focus === 'function') {
53
+ node.focus();
54
+ }
55
+ }, []);
56
+ const context = {
57
+ isRequired: Boolean(isRequired),
58
+ isInvalid: Boolean(isInvalid),
59
+ isReadOnly: Boolean(isReadOnly),
60
+ isDisabled: Boolean(isDisabled),
61
+ hasFeedbackText,
62
+ setHasFeedbackText,
63
+ hasHelpText,
64
+ setHasHelpText,
65
+ name,
66
+ id,
67
+ labelId,
68
+ feedbackId,
69
+ helpTextId,
70
+ htmlProps,
71
+ ...(_reactNative.Platform.OS !== 'web' ? {
72
+ inputRef,
73
+ focusInput
74
+ } : {})
75
+ };
76
+ return context;
77
+ }
78
+
13
79
  /**
14
- * Hook that merges local field props with the nearest FormControl context
80
+ * Hook that merges local field props with the nearest form field context
15
81
  * and returns normalised HTML / ARIA attributes for input elements.
16
82
  */
17
83
  function useFormControl(props) {
18
84
  const field = useFormControlContext();
19
85
  const describedBy = [];
20
- if (field?.hasFeedbackText && field.feedbackId) {
86
+ if (field.hasFeedbackText && field.feedbackId) {
21
87
  describedBy.push(field.feedbackId);
22
88
  }
23
- if (field?.hasHelpText && field.helpTextId) {
89
+ if (field.hasHelpText && field.helpTextId) {
24
90
  describedBy.push(field.helpTextId);
25
91
  }
26
92
  const ariaDescribedBy = describedBy.join(' ');
@@ -31,17 +97,19 @@ function useFormControl(props) {
31
97
  isRequired,
32
98
  ...cleanProps
33
99
  } = props;
34
- const id = props.id ?? (field?.id ? `${field.id}-input` : undefined);
100
+ const id = props.id ?? (field.id ? `${field.id}-input` : undefined);
35
101
  return {
36
102
  ...cleanProps,
37
103
  id,
38
- disabled: isDisabled || field?.isDisabled,
39
- readOnly: isReadOnly || field?.isReadOnly,
40
- required: isRequired || field?.isRequired,
41
- 'aria-invalid': (0, _accessibilityUtils.ariaAttr)(isInvalid || field?.isInvalid),
42
- 'aria-required': (0, _accessibilityUtils.ariaAttr)(isRequired || field?.isRequired),
43
- 'aria-readonly': (0, _accessibilityUtils.ariaAttr)(isReadOnly || field?.isReadOnly),
44
- 'aria-describedby': ariaDescribedBy || undefined
104
+ name: field.name,
105
+ disabled: isDisabled || field.isDisabled,
106
+ readOnly: isReadOnly || field.isReadOnly,
107
+ required: isRequired || field.isRequired,
108
+ 'aria-invalid': (0, _accessibilityUtils.ariaAttr)(isInvalid || field.isInvalid),
109
+ 'aria-required': (0, _accessibilityUtils.ariaAttr)(isRequired || field.isRequired),
110
+ 'aria-readonly': (0, _accessibilityUtils.ariaAttr)(isReadOnly || field.isReadOnly),
111
+ 'aria-describedby': ariaDescribedBy || undefined,
112
+ 'aria-labelledby': field.labelId
45
113
  };
46
114
  }
47
115
  const useFormControlContext = () => {
package/lib/commonjs/form-control/useFormControl.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"names":["_react","_interopRequireDefault","require","_accessibilityUtils","e","__esModule","default","FormControlContext","exports","React","createContext","useFormControl","props","field","useFormControlContext","describedBy","hasFeedbackText","feedbackId","push","hasHelpText","helpTextId","ariaDescribedBy","join","isInvalid","isDisabled","isReadOnly","isRequired","cleanProps","id","undefined","disabled","readOnly","required","ariaAttr","useContext"],"sourceRoot":"../../../src","sources":["form-control/useFormControl.tsx"],"mappings":";;;;;;;;AAAA,IAAAA,MAAA,GAAAC,sBAAA,CAAAC,OAAA;AACA,IAAAC,mBAAA,GAAAD,OAAA;AAAwD,SAAAD,uBAAAG,CAAA,WAAAA,CAAA,IAAAA,CAAA,CAAAC,UAAA,GAAAD,CAAA,KAAAE,OAAA,EAAAF,CAAA;AAqBjD,MAAMG,kBAAkB,GAAAC,OAAA,CAAAD,kBAAA,gBAAGE,cAAK,CAACC,aAAa,CAAmC,CAAC,CAAC,CAAC;AAM3F;AACA;AACA;AACA;AACO,SAASC,cAAcA,CAACC,KAA4B,EAAE;EAC3D,MAAMC,KAAK,GAAGC,qBAAqB,CAAC,CAAC;EACrC,MAAMC,WAAqB,GAAG,EAAE;EAEhC,IAAIF,KAAK,EAAEG,eAAe,IAAIH,KAAK,CAACI,UAAU,EAAE;IAC9CF,WAAW,CAACG,IAAI,CAACL,KAAK,CAACI,UAAU,CAAC;EACpC;EACA,IAAIJ,KAAK,EAAEM,WAAW,IAAIN,KAAK,CAACO,UAAU,EAAE;IAC1CL,WAAW,CAACG,IAAI,CAACL,KAAK,CAACO,UAAU,CAAC;EACpC;EACA,MAAMC,eAAe,GAAGN,WAAW,CAACO,IAAI,CAAC,GAAG,CAAC;EAE7C,MAAM;IAAEC,SAAS;IAAEC,UAAU;IAAEC,UAAU;IAAEC,UAAU;IAAE,GAAGC;EAAW,CAAC,GAAGf,KAAK;EAC9E,MAAMgB,EAAE,GAAGhB,KAAK,CAACgB,EAAE,KAAKf,KAAK,EAAEe,EAAE,GAAG,GAAGf,KAAK,CAACe,EAAE,QAAQ,GAAGC,SAAS,CAAC;EAEpE,OAAO;IACL,GAAGF,UAAU;IACbC,EAAE;IACFE,QAAQ,EAAEN,UAAU,IAAIX,KAAK,EAAEW,UAAU;IACzCO,QAAQ,EAAEN,UAAU,IAAIZ,KAAK,EAAEY,UAAU;IACzCO,QAAQ,EAAEN,UAAU,IAAIb,KAAK,EAAEa,UAAU;IACzC,cAAc,EAAE,IAAAO,4BAAQ,EAACV,SAAS,IAAIV,KAAK,EAAEU,SAAS,CAAC;IACvD,eAAe,EAAE,IAAAU,4BAAQ,EAACP,UAAU,IAAIb,KAAK,EAAEa,UAAU,CAAC;IAC1D,eAAe,EAAE,IAAAO,4BAAQ,EAACR,UAAU,IAAIZ,KAAK,EAAEY,UAAU,CAAC;IAC1D,kBAAkB,EAAEJ,eAAe,IAAIQ;EACzC,CAAC;AACH;AAEO,MAAMf,qBAAqB,GAAGA,CAAA,KAAM;EACzC,OAAOL,cAAK,CAACyB,UAAU,CAAC3B,kBAAkB,CAAC;AAC7C,CAAC;AAACC,OAAA,CAAAM,qBAAA,GAAAA,qBAAA","ignoreList":[]}
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":[]}
package/lib/module/form-control/index.js CHANGED
@@ -1,4 +1,4 @@
1
1
  "use strict";
2
2
 
3
- export { FormControlContext, useFormControl, useFormControlContext } from './useFormControl';
3
+ export { FormControlContext, useFormControl, useFormControlContext, useFormControlRoot } from './useFormControl';
4
4
  //# sourceMappingURL=index.js.map
package/lib/module/form-control/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"names":["FormControlContext","useFormControl","useFormControlContext"],"sourceRoot":"../../../src","sources":["form-control/index.ts"],"mappings":";;AAAA,SAIEA,kBAAkB,EAClBC,cAAc,EACdC,qBAAqB,QAChB,kBAAkB","ignoreList":[]}
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":[]}
package/lib/module/form-control/useFormControl.js CHANGED
@@ -1,19 +1,84 @@
1
1
  "use strict";
2
2
 
3
3
  import React from 'react';
4
+ import { Platform } from 'react-native';
4
5
  import { ariaAttr } from '../common/accessibilityUtils';
5
6
  export const FormControlContext = /*#__PURE__*/React.createContext({});
7
+
8
+ /** Props for the FormControl root; known fields plus passthrough to the styled root box. */
9
+
10
+ /**
11
+ * Builds state and ids for a `Form` primitive root (`createFormRoot`). Pass the returned object
12
+ * (minus `htmlProps`) to `FormControlContext.Provider` — this is not a React context consumer hook.
13
+ */
14
+ export function useFormControlRoot(props) {
15
+ const {
16
+ id: idProp,
17
+ name,
18
+ isRequired,
19
+ isInvalid,
20
+ isDisabled,
21
+ isReadOnly,
22
+ ...htmlProps
23
+ } = props;
24
+ const reactId = React.useId();
25
+ const id = (typeof idProp === 'string' && idProp !== '' ? idProp : null) ?? `field-${reactId}`;
26
+ const labelId = `${id}-label`;
27
+ const feedbackId = `${id}-feedback`;
28
+ const helpTextId = `${id}-helptext`;
29
+
30
+ /**
31
+ * Track whether the `FormErrorMessage` has been rendered.
32
+ * We use this to append its id the the `aria-describedby` of the `input`.
33
+ */
34
+ const [hasFeedbackText, setHasFeedbackText] = React.useState(false);
35
+
36
+ /**
37
+ * Track whether the `FormHelperText` has been rendered.
38
+ * We use this to append its id the the `aria-describedby` of the `input`.
39
+ */
40
+ const [hasHelpText, setHasHelpText] = React.useState(false);
41
+ const inputRef = React.useRef(null);
42
+ const focusInput = React.useCallback(() => {
43
+ const node = inputRef.current;
44
+ if (node != null && typeof node.focus === 'function') {
45
+ node.focus();
46
+ }
47
+ }, []);
48
+ const context = {
49
+ isRequired: Boolean(isRequired),
50
+ isInvalid: Boolean(isInvalid),
51
+ isReadOnly: Boolean(isReadOnly),
52
+ isDisabled: Boolean(isDisabled),
53
+ hasFeedbackText,
54
+ setHasFeedbackText,
55
+ hasHelpText,
56
+ setHasHelpText,
57
+ name,
58
+ id,
59
+ labelId,
60
+ feedbackId,
61
+ helpTextId,
62
+ htmlProps,
63
+ ...(Platform.OS !== 'web' ? {
64
+ inputRef,
65
+ focusInput
66
+ } : {})
67
+ };
68
+ return context;
69
+ }
70
+
6
71
  /**
7
- * Hook that merges local field props with the nearest FormControl context
72
+ * Hook that merges local field props with the nearest form field context
8
73
  * and returns normalised HTML / ARIA attributes for input elements.
9
74
  */
10
75
  export function useFormControl(props) {
11
76
  const field = useFormControlContext();
12
77
  const describedBy = [];
13
- if (field?.hasFeedbackText && field.feedbackId) {
78
+ if (field.hasFeedbackText && field.feedbackId) {
14
79
  describedBy.push(field.feedbackId);
15
80
  }
16
- if (field?.hasHelpText && field.helpTextId) {
81
+ if (field.hasHelpText && field.helpTextId) {
17
82
  describedBy.push(field.helpTextId);
18
83
  }
19
84
  const ariaDescribedBy = describedBy.join(' ');
@@ -24,17 +89,19 @@ export function useFormControl(props) {
24
89
  isRequired,
25
90
  ...cleanProps
26
91
  } = props;
27
- const id = props.id ?? (field?.id ? `${field.id}-input` : undefined);
92
+ const id = props.id ?? (field.id ? `${field.id}-input` : undefined);
28
93
  return {
29
94
  ...cleanProps,
30
95
  id,
31
- disabled: isDisabled || field?.isDisabled,
32
- readOnly: isReadOnly || field?.isReadOnly,
33
- required: isRequired || field?.isRequired,
34
- 'aria-invalid': ariaAttr(isInvalid || field?.isInvalid),
35
- 'aria-required': ariaAttr(isRequired || field?.isRequired),
36
- 'aria-readonly': ariaAttr(isReadOnly || field?.isReadOnly),
37
- 'aria-describedby': ariaDescribedBy || undefined
96
+ name: field.name,
97
+ disabled: isDisabled || field.isDisabled,
98
+ readOnly: isReadOnly || field.isReadOnly,
99
+ required: isRequired || field.isRequired,
100
+ 'aria-invalid': ariaAttr(isInvalid || field.isInvalid),
101
+ 'aria-required': ariaAttr(isRequired || field.isRequired),
102
+ 'aria-readonly': ariaAttr(isReadOnly || field.isReadOnly),
103
+ 'aria-describedby': ariaDescribedBy || undefined,
104
+ 'aria-labelledby': field.labelId
38
105
  };
39
106
  }
40
107
  export const useFormControlContext = () => {
package/lib/module/form-control/useFormControl.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"names":["React","ariaAttr","FormControlContext","createContext","useFormControl","props","field","useFormControlContext","describedBy","hasFeedbackText","feedbackId","push","hasHelpText","helpTextId","ariaDescribedBy","join","isInvalid","isDisabled","isReadOnly","isRequired","cleanProps","id","undefined","disabled","readOnly","required","useContext"],"sourceRoot":"../../../src","sources":["form-control/useFormControl.tsx"],"mappings":";;AAAA,OAAOA,KAAK,MAAM,OAAO;AACzB,SAASC,QAAQ,QAAQ,8BAA8B;AAqBvD,OAAO,MAAMC,kBAAkB,gBAAGF,KAAK,CAACG,aAAa,CAAmC,CAAC,CAAC,CAAC;AAM3F;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAACC,KAA4B,EAAE;EAC3D,MAAMC,KAAK,GAAGC,qBAAqB,CAAC,CAAC;EACrC,MAAMC,WAAqB,GAAG,EAAE;EAEhC,IAAIF,KAAK,EAAEG,eAAe,IAAIH,KAAK,CAACI,UAAU,EAAE;IAC9CF,WAAW,CAACG,IAAI,CAACL,KAAK,CAACI,UAAU,CAAC;EACpC;EACA,IAAIJ,KAAK,EAAEM,WAAW,IAAIN,KAAK,CAACO,UAAU,EAAE;IAC1CL,WAAW,CAACG,IAAI,CAACL,KAAK,CAACO,UAAU,CAAC;EACpC;EACA,MAAMC,eAAe,GAAGN,WAAW,CAACO,IAAI,CAAC,GAAG,CAAC;EAE7C,MAAM;IAAEC,SAAS;IAAEC,UAAU;IAAEC,UAAU;IAAEC,UAAU;IAAE,GAAGC;EAAW,CAAC,GAAGf,KAAK;EAC9E,MAAMgB,EAAE,GAAGhB,KAAK,CAACgB,EAAE,KAAKf,KAAK,EAAEe,EAAE,GAAG,GAAGf,KAAK,CAACe,EAAE,QAAQ,GAAGC,SAAS,CAAC;EAEpE,OAAO;IACL,GAAGF,UAAU;IACbC,EAAE;IACFE,QAAQ,EAAEN,UAAU,IAAIX,KAAK,EAAEW,UAAU;IACzCO,QAAQ,EAAEN,UAAU,IAAIZ,KAAK,EAAEY,UAAU;IACzCO,QAAQ,EAAEN,UAAU,IAAIb,KAAK,EAAEa,UAAU;IACzC,cAAc,EAAElB,QAAQ,CAACe,SAAS,IAAIV,KAAK,EAAEU,SAAS,CAAC;IACvD,eAAe,EAAEf,QAAQ,CAACkB,UAAU,IAAIb,KAAK,EAAEa,UAAU,CAAC;IAC1D,eAAe,EAAElB,QAAQ,CAACiB,UAAU,IAAIZ,KAAK,EAAEY,UAAU,CAAC;IAC1D,kBAAkB,EAAEJ,eAAe,IAAIQ;EACzC,CAAC;AACH;AAEA,OAAO,MAAMf,qBAAqB,GAAGA,CAAA,KAAM;EACzC,OAAOP,KAAK,CAAC0B,UAAU,CAACxB,kBAAkB,CAAC;AAC7C,CAAC","ignoreList":[]}
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":[]}
package/lib/typescript/form-control/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- export { type FormControlContextValue, type FormControlFieldProps, type FormControlState, FormControlContext, useFormControl, useFormControlContext, } from './useFormControl';
1
+ export { type FormControlContextValue, type FormControlFieldProps, type FormControlRootProps, type FormControlRootReturn, type FormControlState, FormControlContext, useFormControl, useFormControlContext, useFormControlRoot, } from './useFormControl';
2
2
  //# sourceMappingURL=index.d.ts.map
package/lib/typescript/form-control/index.d.ts.map CHANGED
@@ -1 +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,gBAAgB,EACrB,kBAAkB,EAClB,cAAc,EACd,qBAAqB,GACtB,MAAM,kBAAkB,CAAC"}
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"}
package/lib/typescript/form-control/useFormControl.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import React from 'react';
2
+ import { type TextInput } from 'react-native';
2
3
  type HTMLProps = Record<string, unknown>;
3
4
  export interface FormControlState {
4
5
  isRequired: boolean;
@@ -9,22 +10,60 @@ export interface FormControlState {
9
10
  export interface FormControlContextValue extends FormControlState {
10
11
  hasFeedbackText: boolean;
11
12
  hasHelpText: boolean;
13
+ setHasFeedbackText: React.Dispatch<React.SetStateAction<boolean>>;
14
+ setHasHelpText: React.Dispatch<React.SetStateAction<boolean>>;
15
+ name?: string;
12
16
  id: string;
13
17
  labelId: string;
14
18
  feedbackId: string;
15
19
  helpTextId: string;
16
20
  htmlProps: HTMLProps;
21
+ /**
22
+ * @platform native — set by `Input.Field` / `Select.Trigger` for label press-to-focus.
23
+ * On web, use `<label htmlFor>` with a labelable control (`input`, `button`, `select`, …).
24
+ */
25
+ inputRef?: React.RefObject<TextInput | null>;
26
+ focusInput?: () => void;
17
27
  }
18
28
  export declare const FormControlContext: React.Context<Partial<FormControlContextValue>>;
19
29
  export interface FormControlFieldProps extends Partial<FormControlState> {
20
30
  id?: string;
21
31
  }
32
+ /** Props for the FormControl root; known fields plus passthrough to the styled root box. */
33
+ export type FormControlRootProps = Partial<FormControlState> & {
34
+ id?: string;
35
+ name?: string;
36
+ } & HTMLProps;
37
+ export interface FormControlRootReturn {
38
+ isRequired: boolean;
39
+ isInvalid: boolean;
40
+ isReadOnly: boolean;
41
+ isDisabled: boolean;
42
+ hasFeedbackText: boolean;
43
+ setHasFeedbackText: React.Dispatch<React.SetStateAction<boolean>>;
44
+ hasHelpText: boolean;
45
+ setHasHelpText: React.Dispatch<React.SetStateAction<boolean>>;
46
+ name?: string;
47
+ id: string;
48
+ labelId: string;
49
+ feedbackId: string;
50
+ helpTextId: string;
51
+ htmlProps: HTMLProps;
52
+ inputRef?: React.RefObject<TextInput | null>;
53
+ focusInput?: () => void;
54
+ }
55
+ /**
56
+ * Builds state and ids for a `Form` primitive root (`createFormRoot`). Pass the returned object
57
+ * (minus `htmlProps`) to `FormControlContext.Provider` — this is not a React context consumer hook.
58
+ */
59
+ export declare function useFormControlRoot(props: FormControlRootProps): FormControlRootReturn;
22
60
  /**
23
- * Hook that merges local field props with the nearest FormControl context
61
+ * Hook that merges local field props with the nearest form field context
24
62
  * and returns normalised HTML / ARIA attributes for input elements.
25
63
  */
26
64
  export declare function useFormControl(props: FormControlFieldProps): {
27
65
  id: string | undefined;
66
+ name: string | undefined;
28
67
  disabled: boolean | undefined;
29
68
  readOnly: boolean | undefined;
30
69
  required: boolean | undefined;
@@ -32,6 +71,7 @@ export declare function useFormControl(props: FormControlFieldProps): {
32
71
  'aria-required': boolean | undefined;
33
72
  'aria-readonly': boolean | undefined;
34
73
  'aria-describedby': string | undefined;
74
+ 'aria-labelledby': string | undefined;
35
75
  };
36
76
  export declare const useFormControlContext: () => Partial<FormControlContextValue>;
37
77
  export {};
package/lib/typescript/form-control/useFormControl.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"useFormControl.d.ts","sourceRoot":"","sources":["../../../src/form-control/useFormControl.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,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,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,eAAO,MAAM,kBAAkB,iDAA4D,CAAC;AAE5F,MAAM,WAAW,qBAAsB,SAAQ,OAAO,CAAC,gBAAgB,CAAC;IACtE,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,qBAAqB;;;;;;;;;EA0B1D;AAED,eAAO,MAAM,qBAAqB,wCAEjC,CAAC"}
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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cdx-ui/utils",
3
- "version": "0.0.1-alpha.8",
3
+ "version": "0.0.1-beta.1",
4
4
  "main": "lib/commonjs/index.js",
5
5
  "module": "lib/module/index.js",
6
6
  "react-native": "src/index.ts",
package/src/form-control/index.ts CHANGED
@@ -1,8 +1,11 @@
1
1
  export {
2
2
  type FormControlContextValue,
3
3
  type FormControlFieldProps,
4
+ type FormControlRootProps,
5
+ type FormControlRootReturn,
4
6
  type FormControlState,
5
7
  FormControlContext,
6
8
  useFormControl,
7
9
  useFormControlContext,
10
+ useFormControlRoot,
8
11
  } from './useFormControl';
package/src/form-control/useFormControl.tsx CHANGED
@@ -1,4 +1,5 @@
1
1
  import React from 'react';
2
+ import { Platform, type TextInput } from 'react-native';
2
3
  import { ariaAttr } from '../common/accessibilityUtils';
3
4
 
4
5
  type HTMLProps = Record<string, unknown>;
@@ -13,11 +14,20 @@ export interface FormControlState {
13
14
  export interface FormControlContextValue extends FormControlState {
14
15
  hasFeedbackText: boolean;
15
16
  hasHelpText: boolean;
17
+ setHasFeedbackText: React.Dispatch<React.SetStateAction<boolean>>;
18
+ setHasHelpText: React.Dispatch<React.SetStateAction<boolean>>;
19
+ name?: string;
16
20
  id: string;
17
21
  labelId: string;
18
22
  feedbackId: string;
19
23
  helpTextId: string;
20
24
  htmlProps: HTMLProps;
25
+ /**
26
+ * @platform native — set by `Input.Field` / `Select.Trigger` for label press-to-focus.
27
+ * On web, use `<label htmlFor>` with a labelable control (`input`, `button`, `select`, …).
28
+ */
29
+ inputRef?: React.RefObject<TextInput | null>;
30
+ focusInput?: () => void;
21
31
  }
22
32
 
23
33
  export const FormControlContext = React.createContext<Partial<FormControlContextValue>>({});
@@ -26,35 +36,118 @@ export interface FormControlFieldProps extends Partial<FormControlState> {
26
36
  id?: string;
27
37
  }
28
38
 
39
+ /** Props for the FormControl root; known fields plus passthrough to the styled root box. */
40
+ export type FormControlRootProps = Partial<FormControlState> & {
41
+ id?: string;
42
+ name?: string;
43
+ } & HTMLProps;
44
+
45
+ export interface FormControlRootReturn {
46
+ isRequired: boolean;
47
+ isInvalid: boolean;
48
+ isReadOnly: boolean;
49
+ isDisabled: boolean;
50
+ hasFeedbackText: boolean;
51
+ setHasFeedbackText: React.Dispatch<React.SetStateAction<boolean>>;
52
+ hasHelpText: boolean;
53
+ setHasHelpText: React.Dispatch<React.SetStateAction<boolean>>;
54
+ name?: string;
55
+ id: string;
56
+ labelId: string;
57
+ feedbackId: string;
58
+ helpTextId: string;
59
+ htmlProps: HTMLProps;
60
+ inputRef?: React.RefObject<TextInput | null>;
61
+ focusInput?: () => void;
62
+ }
63
+
64
+ /**
65
+ * Builds state and ids for a `Form` primitive root (`createFormRoot`). Pass the returned object
66
+ * (minus `htmlProps`) to `FormControlContext.Provider` — this is not a React context consumer hook.
67
+ */
68
+ export function useFormControlRoot(props: FormControlRootProps): FormControlRootReturn {
69
+ const { id: idProp, name, isRequired, isInvalid, isDisabled, isReadOnly, ...htmlProps } = props;
70
+
71
+ const reactId = React.useId();
72
+ const id = (typeof idProp === 'string' && idProp !== '' ? idProp : null) ?? `field-${reactId}`;
73
+
74
+ const labelId = `${id}-label`;
75
+ const feedbackId = `${id}-feedback`;
76
+ const helpTextId = `${id}-helptext`;
77
+
78
+ /**
79
+ * Track whether the `FormErrorMessage` has been rendered.
80
+ * We use this to append its id the the `aria-describedby` of the `input`.
81
+ */
82
+ const [hasFeedbackText, setHasFeedbackText] = React.useState(false);
83
+
84
+ /**
85
+ * Track whether the `FormHelperText` has been rendered.
86
+ * We use this to append its id the the `aria-describedby` of the `input`.
87
+ */
88
+ const [hasHelpText, setHasHelpText] = React.useState(false);
89
+
90
+ const inputRef = React.useRef<TextInput | null>(null);
91
+
92
+ const focusInput = React.useCallback(() => {
93
+ const node = inputRef.current;
94
+ if (node != null && typeof node.focus === 'function') {
95
+ node.focus();
96
+ }
97
+ }, []);
98
+
99
+ const context: FormControlRootReturn = {
100
+ isRequired: Boolean(isRequired),
101
+ isInvalid: Boolean(isInvalid),
102
+ isReadOnly: Boolean(isReadOnly),
103
+ isDisabled: Boolean(isDisabled),
104
+ hasFeedbackText,
105
+ setHasFeedbackText,
106
+ hasHelpText,
107
+ setHasHelpText,
108
+ name,
109
+ id,
110
+ labelId,
111
+ feedbackId,
112
+ helpTextId,
113
+ htmlProps,
114
+ ...(Platform.OS !== 'web' ? { inputRef, focusInput } : {}),
115
+ };
116
+
117
+ return context;
118
+ }
119
+
29
120
  /**
30
- * Hook that merges local field props with the nearest FormControl context
121
+ * Hook that merges local field props with the nearest form field context
31
122
  * and returns normalised HTML / ARIA attributes for input elements.
32
123
  */
33
124
  export function useFormControl(props: FormControlFieldProps) {
34
125
  const field = useFormControlContext();
35
126
  const describedBy: string[] = [];
36
127
 
37
- if (field?.hasFeedbackText && field.feedbackId) {
128
+ if (field.hasFeedbackText && field.feedbackId) {
38
129
  describedBy.push(field.feedbackId);
39
130
  }
40
- if (field?.hasHelpText && field.helpTextId) {
131
+ if (field.hasHelpText && field.helpTextId) {
41
132
  describedBy.push(field.helpTextId);
42
133
  }
43
134
  const ariaDescribedBy = describedBy.join(' ');
44
135
 
45
136
  const { isInvalid, isDisabled, isReadOnly, isRequired, ...cleanProps } = props;
46
- const id = props.id ?? (field?.id ? `${field.id}-input` : undefined);
137
+ const id = props.id ?? (field.id ? `${field.id}-input` : undefined);
47
138
 
48
139
  return {
49
140
  ...cleanProps,
50
141
  id,
51
- disabled: isDisabled || field?.isDisabled,
52
- readOnly: isReadOnly || field?.isReadOnly,
53
- required: isRequired || field?.isRequired,
54
- 'aria-invalid': ariaAttr(isInvalid || field?.isInvalid),
55
- 'aria-required': ariaAttr(isRequired || field?.isRequired),
56
- 'aria-readonly': ariaAttr(isReadOnly || field?.isReadOnly),
142
+ name: field.name,
143
+ disabled: isDisabled || field.isDisabled,
144
+ readOnly: isReadOnly || field.isReadOnly,
145
+ required: isRequired || field.isRequired,
146
+ 'aria-invalid': ariaAttr(isInvalid || field.isInvalid),
147
+ 'aria-required': ariaAttr(isRequired || field.isRequired),
148
+ 'aria-readonly': ariaAttr(isReadOnly || field.isReadOnly),
57
149
  'aria-describedby': ariaDescribedBy || undefined,
150
+ 'aria-labelledby': field.labelId,
58
151
  };
59
152
  }
60
153