@dloizides/ui-forms 1.8.0 → 1.9.1

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 1.9.0
+
+**Campaign F3 — `Field`'s spacing model, and the layout primitives.** `Field` hard-coded a 16px
+bottom margin on its container. That is the pre-flexbox model — the CHILD owns the space after
+itself — and in a `gap`-laid-out parent, which is how every modern form row in this fleet is
+written, the margin STACKS on the parent's gap. So consumers cancelled it by hand: **16
+`containerStyle={{ marginBottom: 0 }}` sites across the fleet**, 13 of them in aml-v2, each with an
+apologetic comment. AML v1 got this right in CSS years ago (`.ui-field { display: flex;
+flex-direction: column; gap: 6px; }`) and wrote the contract down in `shared/FORMS.md`.
+
+**This release moves NO pixels for any existing consumer.** The fix is opt-in, not a 2.0.0 — see
+"Why not a major bump" below.
+
+- **Add `FormGrid` + `FormCell`** — the wrapping form row, extracted from the copy the fleet
+  re-declares verbatim (`{ flexDirection: 'row', flexWrap: 'wrap', gap: 12 }` +
+  `{ minWidth: 220, flexGrow: 1, flexBasis: 260 }`), with the min-width/basis parameterised. Cell
+  metrics live on the GRID, so the common call site is a bare `<FormCell>` and only the genuine
+  one-offs (`<FormCell basis={160} grow={false} minWidth={140}>`) carry props.
+- **Add `FormSection`** — the fieldset/legend grouping only v1 had. react-native-web has no
+  `fieldset` mapping, so this is the ARIA equivalent: `role="group"` + `aria-labelledby` pointing
+  at the legend. The legend reuses `resolveLabelVariantStyle` — the SAME function `Field` uses — so
+  a section heading cannot drift into a third label voice.
+- **Add `Field.spacing` (`'stack' | 'gap'`)** — the two spacing models. `stack` is the historical
+  16px margin + 4px child margins, byte-identical to 1.8.0, and remains the default. `gap` is the
+  FORMS.md contract: no bottom margin, one uniform 6px internal gap, parent owns the rhythm.
+- **`Field` inside a `FormGrid` or `FormSection` resolves to `gap` automatically.** Adopting the
+  shared grid IS the opt-in: a consumer deletes its hand-rolled `grid`/`field` styles AND its
+  `marginBottom: 0` cancel in the same edit. An explicit `spacing` prop beats the context in both
+  directions.
+- **`ChipSelector`**: the chip row now spaces with `gap: 8` instead of per-chip margins plus a
+  compensating `marginBottom: -8`. Rendered box is byte-identical. Also gains a `spacing`
+  passthrough, and `containerStyle` widens to `StyleProp<ViewStyle>` to match `Field`'s.
+
+### Why not a major bump
+
+The brief for this work allowed a breaking 2.0.0. It was rejected. Switching every `Field` to the
+gap model in one publish moves pixels on every form in seven portals simultaneously — which is
+precisely the change you cannot visually QA, because no app remains on the old behaviour to compare
+against, and a regression surfaces as "some form somewhere looks slightly wrong" with seven
+suspects. The context-aware opt-in gives the identical end state via a per-app rollout, each step
+behind visual QA, with `git revert` scoped to one app. The cost is that both models live in the
+code until the fleet has migrated; that is a smaller price than an un-QA-able fleet-wide pixel
+change.
+
+### Correction to the campaign premise
+
+`ChipSelector`'s `marginBottom: -CHIP_GUTTER` was documented — and briefed — as compensation for
+`Field`'s 16px margin, load-bearing enough that changing one without the other would break chip
+spacing in 7+ sites. **That was wrong.** The -8 cancelled the chips' OWN bottom gutter hanging off
+the last wrapped row; it behaved identically whatever `Field` contributed. It has been replaced with
+`gap` regardless, because a margin/negative-margin pair is fragile and leaks a negative margin onto
+the block's box. `fieldSpacing.test.tsx` now pins `Field` and `ChipSelector` to the same box in both
+models, so the relationship is checkable rather than folkloric.
+
+
 ## 1.8.0
 
 **Campaign F2 — the dense CONTROLS arrive.** `@dloizides/ui-tables` shipped a complete, themed,

package/dist/index.d.mts

@@ -1,6 +1,48 @@
 import React from 'react';
 import { StyleProp, TextStyle, ViewStyle, TextInputProps, TextInput, View } from 'react-native';
 
+/**
+ * `Field`'s TWO spacing models — the F3 fix, shipped as an OPT-IN rather than a breaking change.
+ *
+ * ## The defect
+ *
+ * `Field` hard-coded a 16px bottom margin on its container and 4px margins on its label / hint /
+ * error. That is the pre-flexbox model: the CHILD owns the space after itself. In a `gap`-laid-out
+ * parent — which is how every modern form row in this fleet is written — the child's margin STACKS
+ * on the parent's gap, so the consumer has to cancel it by hand. aml-v2 alone carries 13
+ * `marginBottom: 0` cancels, each with an apologetic comment; the fleet carries 16.
+ *
+ * AML v1 got this right in CSS: `.ui-field { display: flex; flex-direction: column; gap: 6px; }` —
+ * internal gap only, and the parent grid owns the space BETWEEN fields. That contract is written up
+ * in `PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md` ("The gap is owned by the container,
+ * never by margins on the children").
+ *
+ * ## Why opt-in and not a 2.0.0
+ *
+ * Switching every `Field` to the gap model at once moves pixels on every form in seven portals in a
+ * single publish — which is exactly the change you cannot visually QA, because there is no app you
+ * can look at that is still on the old behaviour to compare against. The two models are therefore
+ * both implemented, selected per field:
+ *
+ *  - `stack` (DEFAULT) — the historical margins, byte-identical to 1.8.0. Every existing consumer
+ *    is untouched, including the 16 that currently cancel the margin.
+ *  - `gap` — the FORMS.md contract: no bottom margin at all, uniform 6px internal gap. The parent
+ *    owns the rhythm.
+ *
+ * A `Field` inside a `FormGrid` resolves to `gap` automatically, so adopting the shared grid IS the
+ * opt-in — the consumer deletes its hand-rolled `grid`/`field` styles and its margin cancel in the
+ * same edit, and the fleet migrates one app at a time behind visual QA.
+ */
+
+/**
+ * Which spacing model a field speaks.
+ *
+ * A plain string union rather than a `const enum` for the same reason as `FieldLabelVariant`: this
+ * type crosses the package boundary into consumers' `.d.ts`, and a cross-boundary `const enum`
+ * breaks `isolatedModules` / Babel-only builds.
+ */
+type FieldSpacing = 'stack' | 'gap';
+
 /**
  * The TWO legitimate label voices, per the shared forms contract
  * (`PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md` → "The TWO legitimate label voices").
@@ -102,9 +144,18 @@ interface FieldProps {
      * plus a `grow` modifier — instead of having to restate a COMPLETE style per variant.
      */
     containerStyle?: StyleProp<ViewStyle>;
+    /**
+     * Which of the two spacing models this field speaks — see `fieldSpacing.ts`.
+     *
+     * Leave it unset. Inside a `FormGrid` or `FormSection` it resolves to `gap` (the FORMS.md
+     * contract: no bottom margin, the parent's `gap` owns the rhythm); anywhere else it resolves to
+     * `stack` (the historical 16px margin, byte-identical to 1.8.0). Set it explicitly only to
+     * override that — e.g. a cell inside a grid that genuinely stacks two fields wants `stack`.
+     */
+    spacing?: FieldSpacing;
     testID?: string;
 }
-declare const Field: ({ label, children, required, optional, optionalLabel, hint, error, labelVariant, labelStyle, containerStyle, testID, }: FieldProps) => React.ReactElement;
+declare const Field: ({ label, children, required, optional, optionalLabel, hint, error, labelVariant, labelStyle, containerStyle, spacing, testID, }: FieldProps) => React.ReactElement;
 
 /**
  * Required / optional markers, per the shared forms contract
@@ -137,6 +188,117 @@ type FieldMarker = 'none' | 'required' | 'optional';
  */
 declare const DEFAULT_OPTIONAL_LABEL = "(optional)";
 
+/**
+ * `FormGrid` — the wrapping form row, extracted from ~177 hand-rolled copies.
+ *
+ * Verbatim in every portal, differing only in one constant:
+ *
+ * ```ts
+ * grid:  { flexDirection: 'row', flexWrap: 'wrap', gap: 12 },
+ * field: { minWidth: 220, flexGrow: 1, flexBasis: 260 },   // or 200/240/260
+ * ```
+ *
+ * Extracting it is worth more than the deleted lines: because the grid declares itself through
+ * `FormGridContext`, a `Field` inside it knows its vertical rhythm is owned by the grid's `gap` and
+ * drops its own bottom margin. That kills the fleet's 16 `marginBottom: 0` cancel hacks at the same
+ * time — the grid and the cancel were always two halves of one bug.
+ *
+ * The cell metrics live on the GRID, not on each cell, because that is how the real call sites are
+ * written: one `styles.field` reused by every cell in the row, with the occasional narrow one-off.
+ * `<FormCell>` with no props is therefore the common case, and `<FormCell basis={160} grow={false}>`
+ * the exception — which is exactly the ratio in aml-v2's `ScreeningForm`.
+ */
+
+interface FormGridProps {
+    children: React.ReactNode;
+    /**
+     * Space between cells, horizontally AND between wrapped rows. This is the value that makes the
+     * grid own the vertical rhythm, so it is also what a descendant `Field` is dropping its own
+     * margin in favour of.
+     */
+    gap?: number;
+    /** Default `minWidth` for every `FormCell` in this grid. */
+    minWidth?: number;
+    /** Default `flexBasis` for every `FormCell` in this grid. */
+    basis?: number;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+declare const FormGrid: ({ children, gap, minWidth, basis, style, testID, }: FormGridProps) => React.ReactElement;
+
+/**
+ * `FormCell` — one cell of a `FormGrid`.
+ *
+ * Replaces the `<View style={styles.field}>` wrapper every real call site already puts around each
+ * control. It inherits `minWidth` / `flexBasis` from the enclosing grid so the common case is a bare
+ * `<FormCell>`, and takes per-cell overrides for the genuine one-offs (aml-v2's `fieldNarrow`:
+ * `minWidth: 140, flexBasis: 160, flexGrow: 0`).
+ *
+ * Used OUTSIDE a `FormGrid` it still renders a sensible cell from the package defaults rather than
+ * throwing — a cell is a layout hint, and a form that renders slightly wide is a better failure than
+ * a form that does not render. The grid-owned SPACING behaviour, by contrast, is deliberately NOT
+ * available this way: that one has to come from a real grid, because a `Field` dropping its margin
+ * with nothing to replace it would collapse the form.
+ */
+
+interface FormCellProps {
+    children: React.ReactNode;
+    /** Overrides the grid's `minWidth` for this cell only. */
+    minWidth?: number;
+    /** Overrides the grid's `basis` for this cell only. */
+    basis?: number;
+    /** `false` pins the cell to its basis instead of letting it absorb the row's slack. */
+    grow?: boolean;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+declare const FormCell: ({ children, minWidth, basis, grow, style, testID, }: FormCellProps) => React.ReactElement;
+
+/**
+ * `FormSection` — a titled group of fields. The React answer to v1's `<fieldset>` / `<legend>`.
+ *
+ * v1 has a real `<fieldset>` whose `<legend>` takes the identical label metric as a field label, so
+ * a group heading reads as part of the form rather than as page furniture. Nothing in the React
+ * fleet has this: zygos fakes it with a generic `Heading`, and everybody else emits an untitled
+ * `<View>` — which means the grouping exists visually but not semantically, so a screen-reader user
+ * tabbing into "Threshold" is never told it belongs to "Advanced matching".
+ *
+ * ## Why not a literal `<fieldset>`
+ *
+ * react-native-web has no `fieldset` mapping — a `View` is a `div`, and there is no escape hatch
+ * that turns one into a `<fieldset>` with a real `<legend>`. What IS available is the pattern the
+ * ARIA spec defines as the equivalent: `role="group"` + `aria-labelledby` pointing at the heading.
+ * Assistive tech announces "Advanced matching, group" exactly as it would for a fieldset. This is
+ * the honest ceiling of the platform, not a shortcut — and it is why the legend is a `Text` whose
+ * `nativeID` is generated the same way `Field`'s hint/error ids are.
+ *
+ * The legend deliberately reuses `resolveLabelVariantStyle` — the SAME function `Field` uses for its
+ * label — so the two cannot drift. A section titled in one metric above fields labelled in another
+ * is precisely the "third voice is drift" failure FORMS.md warns about.
+ */
+
+interface FormSectionProps {
+    /**
+     * The legend — pre-localized, like every string in this package. Optional: a section with no
+     * title still groups its children for layout, but renders NO legend row and NO `aria-labelledby`,
+     * because a group labelled by an empty element is worse for assistive tech than an unlabelled one.
+     */
+    title?: string;
+    /** Help line for the whole group, under the legend. The group-level sibling of `Field`'s hint. */
+    description?: string;
+    children: React.ReactNode;
+    /**
+     * Which label voice the legend speaks. Defaults to `field` — a section heading on a form the user
+     * fills in. Pass `control` on a dense surface so the legend matches the controls beneath it.
+     */
+    labelVariant?: FieldLabelVariant;
+    /** Escape hatch applied AFTER `labelVariant`, for the genuine one-off a variant does not cover. */
+    titleStyle?: StyleProp<TextStyle>;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+declare const FormSection: ({ title, description, children, labelVariant, titleStyle, style, testID, }: FormSectionProps) => React.ReactElement;
+
 /**
  * `FormActions` — the submit/cancel button row every form ends with.
  *
@@ -289,7 +451,17 @@ interface ChipSelectorProps<T> {
     disabled?: boolean;
     /** Visual variant. `solid` (default) = filled selected pill; `outline` = v1 tinted-outline. */
     variant?: ChipVariant;
-    containerStyle?: ViewStyle;
+    /**
+     * `StyleProp` (not a bare `ViewStyle`) so it composes the same way `Field`'s does — a caller can
+     * pass an array instead of restating a complete style per variant.
+     */
+    containerStyle?: StyleProp<ViewStyle>;
+    /**
+     * Forwarded verbatim to the underlying `Field`. `ChipSelector` deliberately holds NO spacing
+     * opinion of its own: it delegates, so the two cannot drift into disagreeing about how much room
+     * a chip block occupies. The guard for that is `chipSelectorFieldLockstep` in the tests.
+     */
+    spacing?: FieldSpacing;
     /** 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`. */
@@ -308,7 +480,7 @@ interface ChipSelectorProps<T> {
      */
     optionAccessibilityHint?: string;
 }
-declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, }: ChipSelectorProps<T>) => React.ReactElement;
+declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, spacing, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, }: ChipSelectorProps<T>) => React.ReactElement;
 
 /**
  * Reusable form switch/toggle with an optional description.
@@ -624,4 +796,4 @@ declare function suggestOptions(options: readonly ControlOption[], query: string
 /** True when `text` is non-empty yet matches no option's value or label exactly (case-insensitive). */
 declare function isUnmatched(options: readonly ControlOption[], text: string): boolean;
 
-export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, type ControlOption, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, FormActions, type FormActionsProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormSwitch, type FormSwitchProps, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useThemedInput };
+export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, type ControlOption, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useThemedInput };

package/dist/index.d.ts

@@ -1,6 +1,48 @@
 import React from 'react';
 import { StyleProp, TextStyle, ViewStyle, TextInputProps, TextInput, View } from 'react-native';
 
+/**
+ * `Field`'s TWO spacing models — the F3 fix, shipped as an OPT-IN rather than a breaking change.
+ *
+ * ## The defect
+ *
+ * `Field` hard-coded a 16px bottom margin on its container and 4px margins on its label / hint /
+ * error. That is the pre-flexbox model: the CHILD owns the space after itself. In a `gap`-laid-out
+ * parent — which is how every modern form row in this fleet is written — the child's margin STACKS
+ * on the parent's gap, so the consumer has to cancel it by hand. aml-v2 alone carries 13
+ * `marginBottom: 0` cancels, each with an apologetic comment; the fleet carries 16.
+ *
+ * AML v1 got this right in CSS: `.ui-field { display: flex; flex-direction: column; gap: 6px; }` —
+ * internal gap only, and the parent grid owns the space BETWEEN fields. That contract is written up
+ * in `PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md` ("The gap is owned by the container,
+ * never by margins on the children").
+ *
+ * ## Why opt-in and not a 2.0.0
+ *
+ * Switching every `Field` to the gap model at once moves pixels on every form in seven portals in a
+ * single publish — which is exactly the change you cannot visually QA, because there is no app you
+ * can look at that is still on the old behaviour to compare against. The two models are therefore
+ * both implemented, selected per field:
+ *
+ *  - `stack` (DEFAULT) — the historical margins, byte-identical to 1.8.0. Every existing consumer
+ *    is untouched, including the 16 that currently cancel the margin.
+ *  - `gap` — the FORMS.md contract: no bottom margin at all, uniform 6px internal gap. The parent
+ *    owns the rhythm.
+ *
+ * A `Field` inside a `FormGrid` resolves to `gap` automatically, so adopting the shared grid IS the
+ * opt-in — the consumer deletes its hand-rolled `grid`/`field` styles and its margin cancel in the
+ * same edit, and the fleet migrates one app at a time behind visual QA.
+ */
+
+/**
+ * Which spacing model a field speaks.
+ *
+ * A plain string union rather than a `const enum` for the same reason as `FieldLabelVariant`: this
+ * type crosses the package boundary into consumers' `.d.ts`, and a cross-boundary `const enum`
+ * breaks `isolatedModules` / Babel-only builds.
+ */
+type FieldSpacing = 'stack' | 'gap';
+
 /**
  * The TWO legitimate label voices, per the shared forms contract
  * (`PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md` → "The TWO legitimate label voices").
@@ -102,9 +144,18 @@ interface FieldProps {
      * plus a `grow` modifier — instead of having to restate a COMPLETE style per variant.
      */
     containerStyle?: StyleProp<ViewStyle>;
+    /**
+     * Which of the two spacing models this field speaks — see `fieldSpacing.ts`.
+     *
+     * Leave it unset. Inside a `FormGrid` or `FormSection` it resolves to `gap` (the FORMS.md
+     * contract: no bottom margin, the parent's `gap` owns the rhythm); anywhere else it resolves to
+     * `stack` (the historical 16px margin, byte-identical to 1.8.0). Set it explicitly only to
+     * override that — e.g. a cell inside a grid that genuinely stacks two fields wants `stack`.
+     */
+    spacing?: FieldSpacing;
     testID?: string;
 }
-declare const Field: ({ label, children, required, optional, optionalLabel, hint, error, labelVariant, labelStyle, containerStyle, testID, }: FieldProps) => React.ReactElement;
+declare const Field: ({ label, children, required, optional, optionalLabel, hint, error, labelVariant, labelStyle, containerStyle, spacing, testID, }: FieldProps) => React.ReactElement;
 
 /**
  * Required / optional markers, per the shared forms contract
@@ -137,6 +188,117 @@ type FieldMarker = 'none' | 'required' | 'optional';
  */
 declare const DEFAULT_OPTIONAL_LABEL = "(optional)";
 
+/**
+ * `FormGrid` — the wrapping form row, extracted from ~177 hand-rolled copies.
+ *
+ * Verbatim in every portal, differing only in one constant:
+ *
+ * ```ts
+ * grid:  { flexDirection: 'row', flexWrap: 'wrap', gap: 12 },
+ * field: { minWidth: 220, flexGrow: 1, flexBasis: 260 },   // or 200/240/260
+ * ```
+ *
+ * Extracting it is worth more than the deleted lines: because the grid declares itself through
+ * `FormGridContext`, a `Field` inside it knows its vertical rhythm is owned by the grid's `gap` and
+ * drops its own bottom margin. That kills the fleet's 16 `marginBottom: 0` cancel hacks at the same
+ * time — the grid and the cancel were always two halves of one bug.
+ *
+ * The cell metrics live on the GRID, not on each cell, because that is how the real call sites are
+ * written: one `styles.field` reused by every cell in the row, with the occasional narrow one-off.
+ * `<FormCell>` with no props is therefore the common case, and `<FormCell basis={160} grow={false}>`
+ * the exception — which is exactly the ratio in aml-v2's `ScreeningForm`.
+ */
+
+interface FormGridProps {
+    children: React.ReactNode;
+    /**
+     * Space between cells, horizontally AND between wrapped rows. This is the value that makes the
+     * grid own the vertical rhythm, so it is also what a descendant `Field` is dropping its own
+     * margin in favour of.
+     */
+    gap?: number;
+    /** Default `minWidth` for every `FormCell` in this grid. */
+    minWidth?: number;
+    /** Default `flexBasis` for every `FormCell` in this grid. */
+    basis?: number;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+declare const FormGrid: ({ children, gap, minWidth, basis, style, testID, }: FormGridProps) => React.ReactElement;
+
+/**
+ * `FormCell` — one cell of a `FormGrid`.
+ *
+ * Replaces the `<View style={styles.field}>` wrapper every real call site already puts around each
+ * control. It inherits `minWidth` / `flexBasis` from the enclosing grid so the common case is a bare
+ * `<FormCell>`, and takes per-cell overrides for the genuine one-offs (aml-v2's `fieldNarrow`:
+ * `minWidth: 140, flexBasis: 160, flexGrow: 0`).
+ *
+ * Used OUTSIDE a `FormGrid` it still renders a sensible cell from the package defaults rather than
+ * throwing — a cell is a layout hint, and a form that renders slightly wide is a better failure than
+ * a form that does not render. The grid-owned SPACING behaviour, by contrast, is deliberately NOT
+ * available this way: that one has to come from a real grid, because a `Field` dropping its margin
+ * with nothing to replace it would collapse the form.
+ */
+
+interface FormCellProps {
+    children: React.ReactNode;
+    /** Overrides the grid's `minWidth` for this cell only. */
+    minWidth?: number;
+    /** Overrides the grid's `basis` for this cell only. */
+    basis?: number;
+    /** `false` pins the cell to its basis instead of letting it absorb the row's slack. */
+    grow?: boolean;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+declare const FormCell: ({ children, minWidth, basis, grow, style, testID, }: FormCellProps) => React.ReactElement;
+
+/**
+ * `FormSection` — a titled group of fields. The React answer to v1's `<fieldset>` / `<legend>`.
+ *
+ * v1 has a real `<fieldset>` whose `<legend>` takes the identical label metric as a field label, so
+ * a group heading reads as part of the form rather than as page furniture. Nothing in the React
+ * fleet has this: zygos fakes it with a generic `Heading`, and everybody else emits an untitled
+ * `<View>` — which means the grouping exists visually but not semantically, so a screen-reader user
+ * tabbing into "Threshold" is never told it belongs to "Advanced matching".
+ *
+ * ## Why not a literal `<fieldset>`
+ *
+ * react-native-web has no `fieldset` mapping — a `View` is a `div`, and there is no escape hatch
+ * that turns one into a `<fieldset>` with a real `<legend>`. What IS available is the pattern the
+ * ARIA spec defines as the equivalent: `role="group"` + `aria-labelledby` pointing at the heading.
+ * Assistive tech announces "Advanced matching, group" exactly as it would for a fieldset. This is
+ * the honest ceiling of the platform, not a shortcut — and it is why the legend is a `Text` whose
+ * `nativeID` is generated the same way `Field`'s hint/error ids are.
+ *
+ * The legend deliberately reuses `resolveLabelVariantStyle` — the SAME function `Field` uses for its
+ * label — so the two cannot drift. A section titled in one metric above fields labelled in another
+ * is precisely the "third voice is drift" failure FORMS.md warns about.
+ */
+
+interface FormSectionProps {
+    /**
+     * The legend — pre-localized, like every string in this package. Optional: a section with no
+     * title still groups its children for layout, but renders NO legend row and NO `aria-labelledby`,
+     * because a group labelled by an empty element is worse for assistive tech than an unlabelled one.
+     */
+    title?: string;
+    /** Help line for the whole group, under the legend. The group-level sibling of `Field`'s hint. */
+    description?: string;
+    children: React.ReactNode;
+    /**
+     * Which label voice the legend speaks. Defaults to `field` — a section heading on a form the user
+     * fills in. Pass `control` on a dense surface so the legend matches the controls beneath it.
+     */
+    labelVariant?: FieldLabelVariant;
+    /** Escape hatch applied AFTER `labelVariant`, for the genuine one-off a variant does not cover. */
+    titleStyle?: StyleProp<TextStyle>;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+declare const FormSection: ({ title, description, children, labelVariant, titleStyle, style, testID, }: FormSectionProps) => React.ReactElement;
+
 /**
  * `FormActions` — the submit/cancel button row every form ends with.
  *
@@ -289,7 +451,17 @@ interface ChipSelectorProps<T> {
     disabled?: boolean;
     /** Visual variant. `solid` (default) = filled selected pill; `outline` = v1 tinted-outline. */
     variant?: ChipVariant;
-    containerStyle?: ViewStyle;
+    /**
+     * `StyleProp` (not a bare `ViewStyle`) so it composes the same way `Field`'s does — a caller can
+     * pass an array instead of restating a complete style per variant.
+     */
+    containerStyle?: StyleProp<ViewStyle>;
+    /**
+     * Forwarded verbatim to the underlying `Field`. `ChipSelector` deliberately holds NO spacing
+     * opinion of its own: it delegates, so the two cannot drift into disagreeing about how much room
+     * a chip block occupies. The guard for that is `chipSelectorFieldLockstep` in the tests.
+     */
+    spacing?: FieldSpacing;
     /** 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`. */
@@ -308,7 +480,7 @@ interface ChipSelectorProps<T> {
      */
     optionAccessibilityHint?: string;
 }
-declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, }: ChipSelectorProps<T>) => React.ReactElement;
+declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, spacing, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, }: ChipSelectorProps<T>) => React.ReactElement;
 
 /**
  * Reusable form switch/toggle with an optional description.
@@ -624,4 +796,4 @@ declare function suggestOptions(options: readonly ControlOption[], query: string
 /** True when `text` is non-empty yet matches no option's value or label exactly (case-insensitive). */
 declare function isUnmatched(options: readonly ControlOption[], text: string): boolean;
 
-export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, type ControlOption, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, FormActions, type FormActionsProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormSwitch, type FormSwitchProps, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useThemedInput };
+export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, type ControlOption, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useThemedInput };