@dloizides/ui-forms 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 1.6.0
+
+- **`ChipSelector` now composes `Field` internally — its label was drifting.** It rendered its OWN
+  `<Text>` label whose metrics differed from `Field`'s on three of four axes: `marginBottom: 8`
+  (vs 4), NO `fontSize` at all so it fell back to RN's ~14 (vs 13), and `colors.text`
+  (vs `textSecondary`). A `ChipSelector` next to a `FormField` in a row/grid therefore started a
+  different distance down the column and read as a different weight of text. Found at 4 sites in
+  aml-v2 (`TenantWatchlistsEditor`, `CoverageSelector`, `CustomCoverageFields`,
+  `AdvancedMatching`); fixing it in the package fixes every consumer with zero app churn.
+  The local label styles are deleted — there is now exactly one label implementation in the kit.
+- **`ChipSelectorProps` is unchanged and fully backward-compatible** — every existing prop keeps
+  its name, type and default, and `label` stays OPTIONAL. With no label (or an empty one) NO label
+  row is rendered, so composing `Field` cannot introduce a phantom gap above the chips.
+- **`ChipSelector` gains `required`, `error` and `testID`** (all optional, all additive) now that
+  `Field` provides them for free. `error` renders the same `role="alert"` line as `FormField` and
+  is tied to the chip group via `aria-describedby` + `aria-invalid` (web only; no-op on native).
+- **Spacing:** a `ChipSelector` now carries `Field`'s `marginBottom: 16` like every other field
+  (it previously had none). The chips' own 8px trailing gutter is cancelled on the group so the
+  block's total bottom spacing is exactly 16 — the same as a `FormField`, not 24. Pass
+  `containerStyle` to override, as before.
+- **`Field`'s `label` is now optional** (widened from `label: string`, so existing callers are
+  unaffected). An absent or empty label renders no label row, letting a control whose label lives
+  elsewhere still use the shared shell for its error line and spacing.
+- `FormSwitch` / `FormCheckbox` are deliberately NOT changed — see `src/labelRoles.test.tsx`.
+  Their labels are INLINE control labels (beside the control in a row, the row's primary text),
+  not field headers stacked above a control, so they have no alignment defect to fix and `Field`'s
+  smaller/dimmer header treatment would be a regression. They were already identical to each
+  other; a new test now enforces that they stay so.
+
+## 1.5.0
+
+- **Add `Field` — the generic label-over-control wrapper.** `FormField` is hard-wired to a text
+  input (`FormFieldProps extends Omit<TextInputProps,'style'>`), so any NON-text control (a
+  dropdown, a date picker, a chip selector) had no shared way to get a label — and ended up
+  visually misaligned next to its `FormField` siblings: the control's box started ~21px higher
+  (no label row) and it missed `FormField`'s `marginBottom: 16`, so wrapped rows lost their
+  vertical rhythm. This was hand-rolled in 5 places across zygos-web and aml-v2.
+  `Field` takes `{ label, required?, error?, children, containerStyle?, testID? }` and renders the
+  same label row / required mark / error line / spacing.
+- **`FormField` now composes `Field` internally**, so the two can never drift apart — the metrics
+  live in exactly one place. `FormFieldProps` and every rendered attribute (`form-field-input`
+  testID, `aria-invalid` / `aria-describedby` / `aria-required`, the `role="alert"` error line)
+  are unchanged: fully backward-compatible.
+- `Field`'s `children` may be a plain node (the common case) or a render function receiving
+  `{ describedById, hasError }`, so a custom control can wire the error line into its own
+  `aria-describedby` / invalid state exactly the way `FormField` does.
+
 ## 1.4.0
 
 - **Accessibility (WCAG 2.1 AA) hardening — additive + backward-compatible.**

package/README.md

@@ -1,37 +1,107 @@
-# @dloizides/ui-forms
-
-Themable, brand-agnostic React Native (RN-web) **form** components for the dloizides.com
-portfolio: `FormField`, `ChipSelector`, `FormSwitch`. They read theme colours from the shared
-`@dloizides/ui-feedback` UI context (`useUi`) — mount one `UiProvider` / `FeedbackUiProvider`
-at your app root and these components pick up your theme automatically.
-
-## Install
-
-```bash
-npm install @dloizides/ui-forms @dloizides/ui-feedback
-```
-
-Peer dependencies: `@dloizides/ui-feedback >= 1.1.0`, `react >= 18`, `react-native >= 0.74`
-(use `react-native-web` on web).
-
-## Usage
-
-```tsx
-import { FormField, ChipSelector, FormSwitch } from '@dloizides/ui-forms';
-
-<FormField label="Email" required error={errors.email} value={email} onChangeText={setEmail} />
-<ChipSelector label="Plan" options={plans} value={plan} onChange={setPlan} />
-<FormSwitch label="Email notifications" value={notify} onValueChange={setNotify} />
-```
-
-The injected theme needs `colors.{surface,text,textSecondary,border}`, `palette.primary['500']`
-and `semantic.error['500']` — supplied via `@dloizides/ui-feedback`'s provider. Without a provider
-the components fall back to a neutral default theme.
-
-## testIDs
-
-`form-field-input`, `chip-selector-chip-<value>`, `form-switch` (overridable on FormSwitch).
-
-## License
-
-MIT
+# @dloizides/ui-forms
+
+Themable, brand-agnostic React Native (RN-web) **form** components for the dloizides.com
+portfolio: `Field`, `FormField`, `ChipSelector`, `FormSwitch`. They read theme colours from the shared
+`@dloizides/ui-feedback` UI context (`useUi`) — mount one `UiProvider` / `FeedbackUiProvider`
+at your app root and these components pick up your theme automatically.
+
+## Install
+
+```bash
+npm install @dloizides/ui-forms @dloizides/ui-feedback
+```
+
+Peer dependencies: `@dloizides/ui-feedback >= 1.1.0`, `react >= 18`, `react-native >= 0.74`
+(use `react-native-web` on web).
+
+## Usage
+
+```tsx
+import { FormField, ChipSelector, FormSwitch } from '@dloizides/ui-forms';
+
+<FormField label="Email" required error={errors.email} value={email} onChangeText={setEmail} />
+<ChipSelector label="Plan" options={plans} value={plan} onChange={setPlan} />
+<FormSwitch label="Email notifications" value={notify} onValueChange={setNotify} />
+```
+
+## `Field` — label any control, not just a text input
+
+`FormField` is hard-wired to a text input. For **any other control** — a dropdown, a date picker,
+a chip selector — wrap it in `Field` to get the identical label row, required mark, error line and
+bottom spacing. This is what keeps a dropdown aligned with the `FormField` next to it: without it
+the dropdown's box starts a label-row higher and the row loses its vertical rhythm.
+
+```tsx
+import { Field } from '@dloizides/ui-forms';
+
+<Field label="Currency" required error={errors.currency}>
+  <ModalDropdown options={currencies} value={currency} onChange={setCurrency} />
+</Field>
+```
+
+`FormField` **and** `ChipSelector` compose `Field` internally, so the label row can never drift
+out of alignment between them — there is exactly one label implementation in the kit.
+
+To wire the error line into a custom control's own `aria-describedby` / invalid state, pass a
+**function** child — it receives `{ describedById, hasError }` (`describedById` is `undefined`
+when there is no error):
+
+```tsx
+<Field label="Country" error={errors.country}>
+  {({ describedById, hasError }) => (
+    <CountryPicker aria-describedby={describedById} hasError={hasError} value={country} onChange={setCountry} />
+  )}
+</Field>
+```
+
+| Prop | Type | Notes |
+|------|------|-------|
+| `label` | `string` | optional — an absent or empty label renders NO label row |
+| `children` | `ReactNode \| (ctx) => ReactNode` | the control |
+| `required` | `boolean` | renders a decorative `*` (hidden from assistive tech) |
+| `error` | `string` | renders a `role="alert"` line, linked via the child's `describedById` |
+| `containerStyle` | `ViewStyle` | merged over the container |
+| `testID` | `string` | on the container |
+
+The injected theme needs `colors.{surface,text,textSecondary,border}`, `palette.primary['500']`
+and `semantic.error['500']` — supplied via `@dloizides/ui-feedback`'s provider. Without a provider
+the components fall back to a neutral default theme.
+
+## `ChipSelector`
+
+```tsx
+<ChipSelector
+  label="Plan"
+  required
+  error={errors.plan}
+  options={plans}
+  value={plan}
+  onChange={setPlan}
+  variant="outline"
+/>
+```
+
+Its label, required mark, error line and bottom spacing come from `Field`. `label` is optional:
+with no label no label row is rendered, so it drops into a toolbar or filter bar cleanly.
+
+| Prop | Type | Notes |
+|------|------|-------|
+| `label` | `string` | optional — no label means no label row |
+| `options` | `Array<{ value, label }>` | `value` is a `string` or `number` |
+| `value` | `T \| T[]` | array when `multiple` |
+| `onChange` | `(value: T) => void` | fires the pressed value; the parent owns toggle logic |
+| `multiple` | `boolean` | selection is an array |
+| `disabled` | `boolean` | disables every chip |
+| `variant` | `'solid' \| 'outline'` | `solid` (default) = filled pill; `outline` = tinted outline |
+| `required` | `boolean` | renders `Field`'s decorative `*` |
+| `error` | `string` | `role="alert"` line, tied to the chip group via `aria-describedby` |
+| `containerStyle` | `ViewStyle` | merged over the container |
+| `testID` | `string` | on the container |
+
+## testIDs
+
+`form-field-input`, `chip-selector-chip-<value>`, `form-switch` (overridable on FormSwitch).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,12 +1,55 @@
 import React from 'react';
-import { TextInputProps, ViewStyle, TextInput, TextStyle } from 'react-native';
+import { ViewStyle, TextInputProps, TextInput, TextStyle } from 'react-native';
+
+/**
+ * Field — the generic "label over a control, error under it" wrapper.
+ *
+ * `FormField` is hard-wired to a text input, so any NON-text control (a dropdown, a date picker,
+ * a chip selector) had no shared way to get a label — and ended up visually misaligned next to
+ * its `FormField` siblings: its box started a label-row higher, and it missed the container's
+ * bottom margin so wrapped rows lost their vertical rhythm.
+ *
+ * `Field` is that label row + spacing, control-agnostic. Its metrics are the single source of
+ * truth: `FormField` composes `Field` internally, so the two can never drift apart.
+ *
+ * Children may be a plain node (the common case — just wrap your control) or a render function
+ * receiving `{ describedById, hasError }`, so a custom control can wire the error line into its
+ * own `aria-describedby` / invalid state exactly the way `FormField` does.
+ */
+
+/** What a render-function child receives, so it can mirror `FormField`'s error wiring. */
+interface FieldChildContext {
+    /** id of the rendered error line, or `undefined` when there is no error. */
+    describedById?: string;
+    hasError: boolean;
+}
+type FieldChildren = React.ReactNode | ((context: FieldChildContext) => React.ReactNode);
+interface FieldProps {
+    /**
+     * Label shown above the control. Optional so a control whose label is supplied elsewhere (or
+     * which genuinely has none) can still use the shared shell for its error line + spacing: an
+     * absent or empty label renders NO label row at all, rather than an empty one that would add a
+     * phantom gap and misalign the control against its labelled siblings.
+     */
+    label?: string;
+    children: FieldChildren;
+    required?: boolean;
+    error?: string;
+    containerStyle?: ViewStyle;
+    testID?: string;
+}
+declare const Field: ({ label, children, required, error, containerStyle, testID, }: FieldProps) => React.ReactElement;
 
 /**
  * Reusable form field — labelled text input with optional required mark + error.
  *
- * The input itself is the shared `ThemedTextInput` primitive, so every FormField gets the
- * readable + lively treatment (dark text, subtle off-white rest background, brand focus
- * animation with a soft ring) for free, driven by the active theme.
+ * The label row, the required mark, the error line and the container spacing all come from the
+ * generic `Field` wrapper, so a `FormField` and a `Field`-wrapped dropdown sitting next to each
+ * other line up exactly and can never drift apart. FormField only adds the control itself.
+ *
+ * The input is the shared `ThemedTextInput` primitive, so every FormField gets the readable +
+ * lively treatment (dark text, subtle off-white rest background, brand focus animation with a
+ * soft ring) for free, driven by the active theme.
  */
 
 interface FormFieldProps extends Omit<TextInputProps, 'style'> {
@@ -80,6 +123,12 @@ declare function useThemedInput(options?: UseThemedInputOptions): ThemedInput;
  *  - `outline` — the AML v1 console look: an outlined pill on a muted fill; selected = a subtle
  *    tinted-outline (primary border + primary ink + a low-alpha primary wash), NOT a solid fill.
  *    Hover (web) lifts the border/ink to the primary colour.
+ *
+ * The label row, the error line and the container spacing come from the shared `Field` wrapper —
+ * NOT from a local `<Text>`. Its own label used to drift from `Field` on three of four axes
+ * (`marginBottom: 8` vs 4, no `fontSize` at all so ~14 vs 13, `colors.text` vs `textSecondary`),
+ * so a `ChipSelector` next to a `FormField` in a row/grid started a different distance down the
+ * column and read as a different weight of text. Now there is exactly one label implementation.
  */
 
 /** Visual variant. `solid` = filled selected pill (default); `outline` = v1 tinted-outline. */
@@ -89,6 +138,7 @@ interface ChipOption<T> {
     label: string;
 }
 interface ChipSelectorProps<T> {
+    /** Optional — with no label, no label row is rendered (no phantom gap above the chips). */
     label?: string;
     options: Array<ChipOption<T>>;
     value: T | T[];
@@ -98,8 +148,13 @@ interface ChipSelectorProps<T> {
     /** Visual variant. `solid` (default) = filled selected pill; `outline` = v1 tinted-outline. */
     variant?: ChipVariant;
     containerStyle?: ViewStyle;
+    /** Marks the selection mandatory — renders `Field`'s decorative `*` next to the label. */
+    required?: boolean;
+    /** Validation message under the chips, wired to the chip group via `aria-describedby`. */
+    error?: string;
+    testID?: string;
 }
-declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, }: ChipSelectorProps<T>) => React.ReactElement;
+declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, required, error, testID, }: ChipSelectorProps<T>) => React.ReactElement;
 
 /**
  * Reusable form switch/toggle with an optional description.
@@ -142,4 +197,4 @@ interface FormCheckboxProps {
 }
 declare const FormCheckbox: ({ label, value, onValueChange, onChange, hint, description, disabled, containerStyle, testID, accessibilityLabel, accessibilityHint, }: FormCheckboxProps) => React.ReactElement;
 
-export { type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormSwitch, type FormSwitchProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, type UseThemedInputOptions, useThemedInput };
+export { type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, Field, type FieldChildContext, type FieldChildren, type FieldProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormSwitch, type FormSwitchProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, type UseThemedInputOptions, useThemedInput };

package/dist/index.d.ts

@@ -1,12 +1,55 @@
 import React from 'react';
-import { TextInputProps, ViewStyle, TextInput, TextStyle } from 'react-native';
+import { ViewStyle, TextInputProps, TextInput, TextStyle } from 'react-native';
+
+/**
+ * Field — the generic "label over a control, error under it" wrapper.
+ *
+ * `FormField` is hard-wired to a text input, so any NON-text control (a dropdown, a date picker,
+ * a chip selector) had no shared way to get a label — and ended up visually misaligned next to
+ * its `FormField` siblings: its box started a label-row higher, and it missed the container's
+ * bottom margin so wrapped rows lost their vertical rhythm.
+ *
+ * `Field` is that label row + spacing, control-agnostic. Its metrics are the single source of
+ * truth: `FormField` composes `Field` internally, so the two can never drift apart.
+ *
+ * Children may be a plain node (the common case — just wrap your control) or a render function
+ * receiving `{ describedById, hasError }`, so a custom control can wire the error line into its
+ * own `aria-describedby` / invalid state exactly the way `FormField` does.
+ */
+
+/** What a render-function child receives, so it can mirror `FormField`'s error wiring. */
+interface FieldChildContext {
+    /** id of the rendered error line, or `undefined` when there is no error. */
+    describedById?: string;
+    hasError: boolean;
+}
+type FieldChildren = React.ReactNode | ((context: FieldChildContext) => React.ReactNode);
+interface FieldProps {
+    /**
+     * Label shown above the control. Optional so a control whose label is supplied elsewhere (or
+     * which genuinely has none) can still use the shared shell for its error line + spacing: an
+     * absent or empty label renders NO label row at all, rather than an empty one that would add a
+     * phantom gap and misalign the control against its labelled siblings.
+     */
+    label?: string;
+    children: FieldChildren;
+    required?: boolean;
+    error?: string;
+    containerStyle?: ViewStyle;
+    testID?: string;
+}
+declare const Field: ({ label, children, required, error, containerStyle, testID, }: FieldProps) => React.ReactElement;
 
 /**
  * Reusable form field — labelled text input with optional required mark + error.
  *
- * The input itself is the shared `ThemedTextInput` primitive, so every FormField gets the
- * readable + lively treatment (dark text, subtle off-white rest background, brand focus
- * animation with a soft ring) for free, driven by the active theme.
+ * The label row, the required mark, the error line and the container spacing all come from the
+ * generic `Field` wrapper, so a `FormField` and a `Field`-wrapped dropdown sitting next to each
+ * other line up exactly and can never drift apart. FormField only adds the control itself.
+ *
+ * The input is the shared `ThemedTextInput` primitive, so every FormField gets the readable +
+ * lively treatment (dark text, subtle off-white rest background, brand focus animation with a
+ * soft ring) for free, driven by the active theme.
  */
 
 interface FormFieldProps extends Omit<TextInputProps, 'style'> {
@@ -80,6 +123,12 @@ declare function useThemedInput(options?: UseThemedInputOptions): ThemedInput;
  *  - `outline` — the AML v1 console look: an outlined pill on a muted fill; selected = a subtle
  *    tinted-outline (primary border + primary ink + a low-alpha primary wash), NOT a solid fill.
  *    Hover (web) lifts the border/ink to the primary colour.
+ *
+ * The label row, the error line and the container spacing come from the shared `Field` wrapper —
+ * NOT from a local `<Text>`. Its own label used to drift from `Field` on three of four axes
+ * (`marginBottom: 8` vs 4, no `fontSize` at all so ~14 vs 13, `colors.text` vs `textSecondary`),
+ * so a `ChipSelector` next to a `FormField` in a row/grid started a different distance down the
+ * column and read as a different weight of text. Now there is exactly one label implementation.
  */
 
 /** Visual variant. `solid` = filled selected pill (default); `outline` = v1 tinted-outline. */
@@ -89,6 +138,7 @@ interface ChipOption<T> {
     label: string;
 }
 interface ChipSelectorProps<T> {
+    /** Optional — with no label, no label row is rendered (no phantom gap above the chips). */
     label?: string;
     options: Array<ChipOption<T>>;
     value: T | T[];
@@ -98,8 +148,13 @@ interface ChipSelectorProps<T> {
     /** Visual variant. `solid` (default) = filled selected pill; `outline` = v1 tinted-outline. */
     variant?: ChipVariant;
     containerStyle?: ViewStyle;
+    /** Marks the selection mandatory — renders `Field`'s decorative `*` next to the label. */
+    required?: boolean;
+    /** Validation message under the chips, wired to the chip group via `aria-describedby`. */
+    error?: string;
+    testID?: string;
 }
-declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, }: ChipSelectorProps<T>) => React.ReactElement;
+declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, required, error, testID, }: ChipSelectorProps<T>) => React.ReactElement;
 
 /**
  * Reusable form switch/toggle with an optional description.
@@ -142,4 +197,4 @@ interface FormCheckboxProps {
 }
 declare const FormCheckbox: ({ label, value, onValueChange, onChange, hint, description, disabled, containerStyle, testID, accessibilityLabel, accessibilityHint, }: FormCheckboxProps) => React.ReactElement;
 
-export { type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormSwitch, type FormSwitchProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, type UseThemedInputOptions, useThemedInput };
+export { type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, Field, type FieldChildContext, type FieldChildren, type FieldProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormSwitch, type FormSwitchProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, type UseThemedInputOptions, useThemedInput };