@dloizides/ui-forms 1.19.0 → 1.21.0

package/CHANGELOG.md

@@ -1,429 +1,437 @@
-# Changelog
-
-## 1.18.7
-
-- Focused inputs draw the fleet focus ring (`@dloizides/design-tokens` 1.14 `FOCUS_RING`: 2 px solid outline, 2 px offset, contrast-checked colour; error colour when errored) instead of the 3 px 16% box-shadow halo (FOCUS-RING-1 "One focus ring across the shared kit").
-
-## 1.18.6
-
-**ChipSelector: a short chip (e.g. "All") is at least 44 px wide, not only 44 px tall (KEFI-FIT-1 "kefi-web fit and hit-box fixes").**
-
-`chip` and `chipOutline` get `minWidth: 44` next to the existing `minHeight: 44`; measured 42x44 on kefi-web approvals at 360.
-
-## 1.18.3
-
-**FormCheckbox: the hint/description is now announced by screen readers.**
-
-The hint Text gets a stable per-instance id (`useFieldIds().hintId`, as `Field` does) and the role=checkbox
-Pressable sets `aria-describedby` to it when a hint is present; with no hint the attribute is omitted.
-
-## 1.18.2
-
-**FormSwitch: the switch now sits in a 44x44 (MIN_TOUCH_TARGET_PX) pressable slot on web.**
-
-Visual QA on kefi-web Site settings (360 and 1280) measured the switch at 40x20: react-native-web sizes the
-native input to the Switch root, and `hitSlop` is inert on web. The switch is now centred in a slot with
-`minWidth`/`minHeight` MIN_TOUCH_TARGET_PX inside the pressable row, so the row stays at least 44 tall even when a
-`containerStyle` overrides `minHeight`. The track and thumb are unchanged; the switch gains a few px of horizontal gutter.
-New testID: `<testID>-hitbox`.
-
-## 1.17.0
-
-**Chips now have a 44px minimum touch target on web. `hitSlop` never did that — it is native-only.**
-
-`CHIP_HIT_SLOP` was documented as expanding the chip's touch area toward the WCAG ≥44px floor
-"without changing the rendered pill size". Measured in headless Chromium at 360x640 on 2026-09-21:
-a chip's box is 33px tall (`paddingVertical: 6`), and `document.elementFromPoint(68, 35)` — 5px
-above a top edge at y=40, inside `CHIP_HIT_SLOP.top: 10` — returns the PARENT element, not the
-chip. react-native-web 0.21.2 references `hitSlop` only inside the legacy `Touchable` mixin's
-press-RETENTION path (after the responder is already granted) and not at all in `Pressable`, so on
-web the rendered box is the entire tappable area. The chips were a 33px target in all seven portals.
-
-- `chipStyles.chip` and `chipStyles.chipOutline` gain `minHeight: 44` + `justifyContent: 'center'`.
-  Chip width is unchanged (56.7px and 68px before and after for the same labels), so wrapping and
-  `CHIP_GUTTER` spacing are untouched; a chip row grows 33px → 44px tall.
-- `CHIP_HIT_SLOP` is kept and still helps iOS/Android. Its doc comment now states the web result
-  instead of claiming one.
-- Consumers with a dense chip strip should re-check row spacing: the pill itself is taller now.
-
-## 1.15.0
-
-**`FormSwitch` now emits `aria-checked` / `aria-disabled` on web; `ChipSelector` gained an option icon slot and opt-in radio semantics.**
-
-`FormSwitch` (A11Y-ARIA-CHECKED-1): react-native-web 0.21 emits nothing from `accessibilityState` on web, so the
-switch wrapper rendered `role="switch"` with no `aria-checked` - an invalid switch that announced no state. The
-state is now passed as literal `aria-checked` (always) and `aria-disabled` (only when disabled) web props;
-`accessibilityState` also carries `disabled` for native.
-
-`ChipSelector`:
-- `ChipOption.icon?: React.ReactNode` - rendered before the label inside the chip, wrapped `aria-hidden`. Options
-  without an icon render the exact same tree as before.
-- `singleSelectRole?: 'button' | 'radio'` (type `ChipSingleSelectRole`). Default `button` = unchanged. With
-  `radio` and `multiple` unset, the group is `role="radiogroup"` and each chip `role="radio"` + `aria-checked`.
-  Ignored for multi-select. Trade-off: RN-web renders a radio chip as a `<div>`, which activates on Enter but not
-  Space and has no arrow-key roving focus.
-
-**Additive and backward-compatible.** No prop set = identical DOM for every existing consumer.
-
-## 1.14.0
-
-**`FormField` gained an opt-in `recentKey` — remember the last N submitted values and offer them on focus.**
-
-A search / filter / lookup box that the user retypes the same handful of values into now gets a
-"recent values" dropdown for free. Set `recentKey="<namespace>"` on a `FormField` and the values it
-submits are remembered (per key) and surfaced in a menu on focus; picking one fills the input. A
-value is recorded on submit (Enter) **and** on blur-with-content, so both "hit enter" and "typed then
-moved on" are captured. The dropdown reuses the kit's `AnchoredMenu` (portalled to `document.body`, so
-it is never painted behind a table / card / the next field) with full a11y (menu name, per-row label +
-hint + role).
-
-Persistence is `localStorage` under `@dloizides/ui-forms:recent:<recentKey>`; the list de-dupes
-case-insensitively, promotes a repeat to the front, and caps at `recentMax` (default 10). On native /
-SSR / when storage is disabled it is a silent no-op (recents are always `[]`), and every storage
-access is wrapped so a quota or privacy-mode failure can never throw into render.
-
-**Additive and backward-compatible.** Leave `recentKey` unset — the default — and the field behaves
-exactly as before: nothing rendered, no state/refs/effects, no storage touched. NEVER set it on a
-password / secure field. The engine is also exported standalone as `useRecentValues(key, max?)` for
-bespoke recents surfaces, and `AnchoredMenu` gained an optional `accessibilityLabel` for naming the menu.
-
-## 1.13.3
-
-**Placeholder text was too dark — it read like an already-filled value.**
-
-`useThemedInput` painted the placeholder with the theme's `textSecondary` — a deliberately
-dark, accessible grey (design-tokens UX-11) that also renders readable secondary *copy*. At
-full strength a placeholder (e.g. `follower` in a "Dance role" box) was hard to tell apart
-from entered text. It is now `textSecondary` composited toward the field background at 0.6
-alpha, so a hint reads clearly lighter than the solid entered text (`colors.text`) while
-keeping the theme hue — and it works in dark mode too (it composites toward whatever the
-field background is). The field's visible label still carries the accessible name, so this
-is a usability win, not an a11y regression. Affects every `@dloizides/ui-forms`-driven input
-(`FormField`, `Field`, `ThemedTextInput`, the `ui-tables` `Filters` search box) across all
-seven portals.
-
-## 1.12.0
-
-**`FormField` gained `labelHidden` — hide the visible label, keep the accessible name.**
-
-A field whose placeholder already names it (a toolbar search box, an inline filter) does
-not want a stacked visible label: the label wastes a row and, worse, pushes the input a
-label-row lower than a bare button beside it, so the two misalign. Until now the only way
-to drop the visible label was to blank `label` — which ALSO blanked the input's
-`accessibilityLabel`, silently stripping the accessible name.
-
-`labelHidden` removes ONLY the visible `<label>` row: `label` stays required and the input
-keeps `accessibilityLabel={label}`, so a screen reader reads the same name and the field
-still resolves by role + name. Additive and backward-compatible — default `false`, every
-existing call renders unchanged.
-
-## 1.11.1
-
-**`ThemedTextInput` shipped no metrics, so every direct caller got a raw 19px input.**
-
-It documented itself as "the ONE source of truth for the input look" while shipping
-only **colours** — no border, radius, padding or height. `FormField` quietly passed its
-own private duplicate of those metrics, so anything reached *through* `FormField` looked
-correct and the gap was invisible. Every **direct** caller — the documented, blessed
-usage — got a raw browser input.
-
-Measured live in the Digital Kin CMS before: **10/10 inputs below the 48px floor**, text
-inputs 19px, textareas 38px. After: **0/10**, at 48/96px.
-
-**Label association was absent entirely** (0 `label[for]`, 0 ids). Two defects only a
-real browser could find, both fixed here:
-
-- **`htmlFor` is silently dropped by react-native-web** — it is not on the prop
-  allowlist, the same family as the dropped `accessibilityHint`. A prop-level assertion
-  passes against the broken build; only a DOM-level test catches it, so that is what the
-  new tests assert.
-- **Dangling `for`.** `Field` assumed render-function children place the id they are
-  handed, but `SelectControl` uses `aria-labelledby` instead — so the difficulty label
-  shipped `for="field-control-3"` pointing at **nothing**, passing every structural check
-  while focusing no field. `useHtmlFor` now sets `for` only when the target is genuinely
-  in the document.
-
-> ⚠️ **Cross-fleet visual change.** `controlStyles.input` gaining `minHeight: 48` lifts
-> dense filter inputs and select triggers in `aml-v2`/`agora-web` from ~38-41px to 48px.
-> This cannot be avoided: the input floor is what fixes the 19px defect, and nothing
-> fixes that without also lifting inputs that already had padding. Owner-approved.
-
-
-## 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,
-a11y-wired set of form controls inside its `Filters` bar and exported NONE of them: its
-`src/index.ts` exposed only `Filters`, `useFilterDraft`, `suggestOptions`, `isUnmatched` and
-types. Six portals could SEE those controls working and none could import them, so the fleet
-reimplemented them — **6 independent select implementations, 5 date fields, 2 typeaheads**. Same
-shape as `MultiTenancy.EntityFrameworkCore` shipping no EF Core. This release makes them public.
-
-Nothing here moves a pixel for an existing consumer: the metrics are the promoted originals,
-unchanged. `CONTAINER_MARGIN_BOTTOM` and `ChipSelector`'s compensating `marginBottom:
--CHIP_GUTTER` remain deliberately untouched.
-
-- **Add `SelectControl`** — single-select enum/status dropdown. Bordered trigger + chevron opening
-  the shared `AnchoredMenu`.
-- **Add `TypeaheadControl`** — search-as-you-type combobox (aml-v2's CountryPicker, generalized).
-  Free typing is preserved (the value is raw text the caller normalises at query time); picking a
-  suggestion fills the canonical LABEL, not the value.
-- **Add `DateRangeControl`** — inclusive from/to pair. Editing one side patches ONLY that side.
-- **Add `AnchoredMenu`** — the floating option list both of the above compose. Kept in-tree with
-  NO `ui-layout` dependency; that was a considered choice in `ui-tables` and it still holds, since
-  depending on the higher-level `ModalDropdown` would invert the graph for every consumer.
-- **Add `controlStyles`** — the tuned metrics, promoted verbatim. `ui-tables`' `Filters/styles.ts`
-  said the quiet part out loud in its own header: it "reconcile[d] the per-field styles that were
-  copy-pasted across aml-v2's filter files into one shared source" — and then locked the
-  reconciliation inside one bar where no other surface could reach it.
-- **Add `suggestOptions` / `isUnmatched`** — the ranked substring matcher behind the typeahead.
-- **Add `ControlOption` / `DateRangeValue`** types. `ui-tables` now ALIASES its long-standing
-  public `FilterOption` / `DateRangeValue` onto these, so there is one definition rather than two
-  structurally-compatible twins free to drift.
-
-### The controls are LABEL-FREE, on purpose
-
-They render the control only. Compose them inside `Field` — with `labelVariant="control"` on a
-dense surface — to get the label, hint and error slots. That is what retires `ui-tables`' private
-`FieldShell` fork (see `@dloizides/ui-tables` 1.14.0) and leaves ONE label implementation for
-every control instead of one per control.
-
-### i18n: this package still never calls `t`
-
-Every string — `accessibilityLabel`, `placeholder`, `optionHint`, `error`, `fromLabel`/`toLabel`
-— is a PRE-LOCALIZED prop. This is load-bearing, not stylistic: aml-v2 localizes through
-`@dloizides/i18n` with positional `{0}` while the other six portals use i18next `{{p1}}`, so a
-component that localized internally could not serve both. `SelectControl`'s `accessibilityLabel`
-is therefore composed BY THE CALLER — it must carry the selection ("Status: Active", not
-"Status"), and building that string needs a `t` call this package must not make.
-
-### Fixed — a WCAG defect carried in by the promoted code
-
-`AnchoredMenu` marked the current option with `accessibilityState={{ selected }}` alone.
-**react-native-web does not read `accessibilityState` at all** (verified against
-`react-native-web@0.21`'s `createDOMProps`, which enumerates `aria-selected` /
-`accessibilitySelected` and never `accessibilityState`), so on web the selected option was
-distinguished by colour and font-weight ONLY — no screen reader could tell which option was
-current (WCAG 1.4.1, use of colour). `aria-selected` is now passed alongside, so each platform
-gets the channel it honours. The trigger already paired `aria-expanded` with `accessibilityState`;
-the option row was simply missed when that was done. A test asserts it, and that test FAILED
-before the fix.
-
-## 1.7.0
-
-Additive wave implementing the shared cross-stack forms contract now written down at
-`PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md`. **Nothing in this release moves a pixel
-for an existing consumer**: every addition is opt-in and every default is the previous behaviour.
-`CONTAINER_MARGIN_BOTTOM` and `ChipSelector`'s compensating `marginBottom: -CHIP_GUTTER` are
-deliberately untouched — they are load-bearing and move together in a later, visual-QA-gated wave.
-
-- **Add `FormActions` — the submit/cancel row.** Promoted from the BYTE-IDENTICAL
-  `erevna-web/src/components/Forms/FormActions.tsx` and `katalogos-web/.../FormActions.tsx`
-  (68 lines each; `diff` returns nothing). All seven portals hand-roll this row; aml-v2, agora,
-  kefi, ichnos and zygos each inline their own variant. The primary action is LAST in DOM order so
-  tab reaches Cancel before Save, and `saving` drives the primary button's spinner rather than
-  disabling-and-relabelling it. `saveDisabled` blocks Save WITHOUT blocking Cancel — an invalid
-  form stays escapable. testIDs default to the twins' `save-button` / `cancel-button`, so existing
-  Playwright selectors keep matching.
-- **`Field` gains `hint`.** ~21 hand-rolled copies of `{fontSize:12, marginTop:4, color:
-  textSecondary}` exist across the fleet; aml-v2 alone declares a local `hint` style in 8 files.
-  Because `Field` had no hint slot, consumers rendered the hint as a SIBLING, where it lands past
-  the container's 16px bottom margin and detaches from the control it explains (see the apologetic
-  comment in `aml-v2/src/screens/screening/CoverageSelector.tsx`). The hint renders UNDER the
-  control and ABOVE the error, and hint and error COEXIST — both are reachable from the control via
-  a composed `aria-describedby` (hint id then error id, in reading order). Only the error is a
-  `role="alert"` live region; a hint that announced itself would interrupt on every focus.
-- **`Field` gains `optional` + `optionalLabel`.** Mutually exclusive with `required`; when a caller
-  sets both, `required` WINS — the safe direction, since an under-marked required field sends the
-  user into a failed submit. Enforced at runtime in `resolveFieldMarker` rather than in the type
-  system, so a caller spreading a computed props object still gets a defined single-marker result
-  instead of a compile error it cannot act on. Like the asterisk, the optional text is decorative
-  (`aria-hidden`) — "optional" is the ABSENCE of `aria-required`, which assistive tech already
-  conveys.
-- **`Field` gains `labelVariant` (+ `labelStyle` as the escape hatch).** `Field` hard-coded
-  13/600/sentence-case, which is exactly why kefi-web refused it and why `@dloizides/ui-tables`'
-  private `FieldShell` forked to 11/700/uppercase. `labelVariant` makes the contract's TWO
-  legitimate voices first-class and named: `field` (13/600 sentence case — a label that is READ)
-  and `control` (11/700 UPPERCASE + letter-spacing — a label that is SCANNED, for dense filter bars
-  and toolbars). An absent variant resolves to `field`, so every existing consumer renders
-  byte-identically. `labelStyle` applies AFTER the variant for the genuine one-off.
-- **`Field`'s `containerStyle` widens `ViewStyle` -> `StyleProp<ViewStyle>`.** The narrow type was a
-  documented pain: `aml-v2/src/screens/leaders/CountryPicker.tsx` has to build a COMPLETE style per
-  variant because it cannot compose an array.
-- **`useThemedInput`: a focused errored field now keeps a RED focus ring.** It previously computed
-  `isFocused && !hasError`, so an errored field got NO focus ring at all — removing the focus
-  indicator (WCAG 2.4.7) from precisely the field the user was sent back to fix, at the moment they
-  are most likely navigating by keyboard. It now always rings on focus and only changes the ring's
-  COLOUR, matching v1's `input.invalid:focus { box-shadow: 0 0 0 3px var(--danger-tint) }`.
-  One pre-existing test necessarily changed: it asserted `boxShadow === 'none'` for this state,
-  i.e. it encoded the defect as intended behaviour.
-- **New peer dependency `@dloizides/ui-buttons >= 1.4.0`**, required by `FormActions` so the estate
-  keeps exactly one button implementation rather than forking one here.
-- No i18n runtime is introduced: all user-visible copy (`saveLabel`, `cancelLabel`, `optionalLabel`,
-  `hint`, `error`) arrives pre-localized. aml-v2 localizes via `@dloizides/i18n` with positional
-  `{0}` params while the other six apps use i18next `{{p1}}`, and nothing bridges them, so a
-  component that localized internally could not serve both.
-- Also shipping in this tarball, from a CONCURRENT workstream (commit `13bd281`, not part of this
-  wave): `ChipSelector` gains `chipTestIDPrefix`, `optionAccessibilityHint` and `multiple`
-  toggle semantics, and reads its on-primary ink from the theme's `onBrand` scale instead of a
-  hardcoded `#fff`. All opt-in; the `chip-selector-chip-<value>` testID default is frozen.
-
-## 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.**
-  - `FormField`: the error message is now programmatically tied to the input — the input gets
-    `aria-invalid` when errored and `aria-describedby` pointing at the error line (which is a
-    `role="alert"` live region), and `aria-required` when `required`. The required `*` is marked
-    decorative (`aria-hidden` / `accessibilityElementsHidden`) so a screen reader hears "required"
-    (via `aria-required`) instead of "star".
-  - `ThemedTextInput`: new optional `describedById` + `requiredField` props forward
-    `aria-describedby` / `aria-required`, and it emits `aria-invalid` from `hasError` (web only;
-    no-ops on native). Existing callers are unaffected.
-  - `FormCheckbox`: now keyboard-operable — the `role="checkbox"` Pressable renders a `<div>`
-    (no free Enter/Space), so an explicit web-only Enter/Space handler toggles it (WCAG 2.1.1).
-  - `ChipSelector`: chips gain a `hitSlop` so the touch target reaches ~44px WITHOUT changing the
-    rendered pill size, and expose `accessibilityState.disabled` when the selector is disabled.
-  - `useThemedInput`: the focus/hover CSS transition now collapses to instant when the user
-    requests `prefers-reduced-motion: reduce` (WCAG 2.3.3, web only).
-
-## 1.3.0
-
-- `ChipSelector` gains a `variant` prop (`'solid' | 'outline'`, default `'solid'`). `solid` is the
-  original filled-pill look (selected = solid brand fill, white ink) — existing consumers
-  (erevna / katalogos / kefi) render **identically**, no change. `outline` is the AML v1 console
-  look: an outlined pill on a muted fill where the **selected** state is a subtle tinted-outline
-  (brand border + brand ink + a low-alpha brand wash), NOT a solid fill; on web, hover lifts the
-  border + ink to the brand colour. Fully theme-driven (brand colour + alpha, border/text from the
-  theme), so it re-themes per tenant. Additive + backward-compatible.
-
-## 1.2.0
-
-- Add `ThemedTextInput` + `useThemedInput` — the shared "readable + lively" text-input treatment,
-  driven entirely by the active theme (re-themes per tenant, no hard-coded hex). At rest: dark
-  readable text on a subtle off-white surface with a soft border. On hover (web): the border
-  strengthens a touch. On focus: the border becomes the brand primary, the background brightens to
-  the plain surface (white), and a soft 3px brand-tinted focus ring fades in. The animation is a
-  pure GPU-cheap CSS transition on `border-color`/`background-color`/`box-shadow` (the ring is a
-  `box-shadow`, so no layout/reflow) — NO `Animated`/`LayoutAnimation`/JS timers. Web-only style
-  keys and the mouse-hover handlers are guarded behind `Platform.OS === 'web'`, so it stays
-  native-safe (native applies the state-driven colours instantly).
-- `FormField` now renders `ThemedTextInput`, so every field gets the treatment for free; its label
-  uses `textSecondary` at 13px/600 for readability. Props/behaviour (label, hint, error, testID,
-  a11y, `onFocus`/`onBlur` pass-through) are backward-compatible.
-
-## 1.1.0
-
-- Add `FormCheckbox` — a native-safe (`Pressable`-based, RN-web + native) themed checkbox: a rounded
-  square that fills with the brand colour and shows a check glyph when on, with a label and optional
-  hint. Mirrors `FormSwitch`'s prop shape (`value`, `onValueChange`/`onChange`, `label`, `hint`,
-  `disabled`, `testID`, a11y) so it is a drop-in for boolean toggles that should read as checkboxes.
-  Exposes `role="checkbox"` + `aria-checked` / `accessibilityState={{ checked }}`.
-
-## 1.0.0
-
-Initial release. Extracted the proven duplicated form components from erevna-web ↔ katalogos-web
-(Capability Wave C1, batch 2).
-
-- `FormField`, `ChipSelector`, `FormSwitch` — share the `@dloizides/ui-feedback` UI context (`useUi`).
-- `FormActions` deferred (depends on a not-yet-shared `core/Button`).
+# Changelog
+
+## 1.20.0
+
+**Horizontal form fields line up (D-ALL-22 "Horizontal form fields are aligned").**
+
+- `FormGrid` rows set `alignItems: flex-start`: every cell starts on one top edge and a tall cell (hint, error) no longer stretches its neighbours.
+- New `AlignToControl`: an aria-hidden label line with the same font and spacing model as `Field`, so a button beside labelled fields sits on the input line, not the label line. `FormCell alignToControl` applies it to a cell.
+- New `InlineFieldRow` (extracted from kefi-web): a field and its action stacked below `inlineMinWidth` (default 1024) and on one row above it, the action placed by `AlignToControl` instead of a hand-measured offset.
+
+## 1.18.7
+
+- Focused inputs draw the fleet focus ring (`@dloizides/design-tokens` 1.14 `FOCUS_RING`: 2 px solid outline, 2 px offset, contrast-checked colour; error colour when errored) instead of the 3 px 16% box-shadow halo (FOCUS-RING-1 "One focus ring across the shared kit").
+
+## 1.18.6
+
+**ChipSelector: a short chip (e.g. "All") is at least 44 px wide, not only 44 px tall (KEFI-FIT-1 "kefi-web fit and hit-box fixes").**
+
+`chip` and `chipOutline` get `minWidth: 44` next to the existing `minHeight: 44`; measured 42x44 on kefi-web approvals at 360.
+
+## 1.18.3
+
+**FormCheckbox: the hint/description is now announced by screen readers.**
+
+The hint Text gets a stable per-instance id (`useFieldIds().hintId`, as `Field` does) and the role=checkbox
+Pressable sets `aria-describedby` to it when a hint is present; with no hint the attribute is omitted.
+
+## 1.18.2
+
+**FormSwitch: the switch now sits in a 44x44 (MIN_TOUCH_TARGET_PX) pressable slot on web.**
+
+Visual QA on kefi-web Site settings (360 and 1280) measured the switch at 40x20: react-native-web sizes the
+native input to the Switch root, and `hitSlop` is inert on web. The switch is now centred in a slot with
+`minWidth`/`minHeight` MIN_TOUCH_TARGET_PX inside the pressable row, so the row stays at least 44 tall even when a
+`containerStyle` overrides `minHeight`. The track and thumb are unchanged; the switch gains a few px of horizontal gutter.
+New testID: `<testID>-hitbox`.
+
+## 1.17.0
+
+**Chips now have a 44px minimum touch target on web. `hitSlop` never did that — it is native-only.**
+
+`CHIP_HIT_SLOP` was documented as expanding the chip's touch area toward the WCAG ≥44px floor
+"without changing the rendered pill size". Measured in headless Chromium at 360x640 on 2026-09-21:
+a chip's box is 33px tall (`paddingVertical: 6`), and `document.elementFromPoint(68, 35)` — 5px
+above a top edge at y=40, inside `CHIP_HIT_SLOP.top: 10` — returns the PARENT element, not the
+chip. react-native-web 0.21.2 references `hitSlop` only inside the legacy `Touchable` mixin's
+press-RETENTION path (after the responder is already granted) and not at all in `Pressable`, so on
+web the rendered box is the entire tappable area. The chips were a 33px target in all seven portals.
+
+- `chipStyles.chip` and `chipStyles.chipOutline` gain `minHeight: 44` + `justifyContent: 'center'`.
+  Chip width is unchanged (56.7px and 68px before and after for the same labels), so wrapping and
+  `CHIP_GUTTER` spacing are untouched; a chip row grows 33px → 44px tall.
+- `CHIP_HIT_SLOP` is kept and still helps iOS/Android. Its doc comment now states the web result
+  instead of claiming one.
+- Consumers with a dense chip strip should re-check row spacing: the pill itself is taller now.
+
+## 1.15.0
+
+**`FormSwitch` now emits `aria-checked` / `aria-disabled` on web; `ChipSelector` gained an option icon slot and opt-in radio semantics.**
+
+`FormSwitch` (A11Y-ARIA-CHECKED-1): react-native-web 0.21 emits nothing from `accessibilityState` on web, so the
+switch wrapper rendered `role="switch"` with no `aria-checked` - an invalid switch that announced no state. The
+state is now passed as literal `aria-checked` (always) and `aria-disabled` (only when disabled) web props;
+`accessibilityState` also carries `disabled` for native.
+
+`ChipSelector`:
+- `ChipOption.icon?: React.ReactNode` - rendered before the label inside the chip, wrapped `aria-hidden`. Options
+  without an icon render the exact same tree as before.
+- `singleSelectRole?: 'button' | 'radio'` (type `ChipSingleSelectRole`). Default `button` = unchanged. With
+  `radio` and `multiple` unset, the group is `role="radiogroup"` and each chip `role="radio"` + `aria-checked`.
+  Ignored for multi-select. Trade-off: RN-web renders a radio chip as a `<div>`, which activates on Enter but not
+  Space and has no arrow-key roving focus.
+
+**Additive and backward-compatible.** No prop set = identical DOM for every existing consumer.
+
+## 1.14.0
+
+**`FormField` gained an opt-in `recentKey` — remember the last N submitted values and offer them on focus.**
+
+A search / filter / lookup box that the user retypes the same handful of values into now gets a
+"recent values" dropdown for free. Set `recentKey="<namespace>"` on a `FormField` and the values it
+submits are remembered (per key) and surfaced in a menu on focus; picking one fills the input. A
+value is recorded on submit (Enter) **and** on blur-with-content, so both "hit enter" and "typed then
+moved on" are captured. The dropdown reuses the kit's `AnchoredMenu` (portalled to `document.body`, so
+it is never painted behind a table / card / the next field) with full a11y (menu name, per-row label +
+hint + role).
+
+Persistence is `localStorage` under `@dloizides/ui-forms:recent:<recentKey>`; the list de-dupes
+case-insensitively, promotes a repeat to the front, and caps at `recentMax` (default 10). On native /
+SSR / when storage is disabled it is a silent no-op (recents are always `[]`), and every storage
+access is wrapped so a quota or privacy-mode failure can never throw into render.
+
+**Additive and backward-compatible.** Leave `recentKey` unset — the default — and the field behaves
+exactly as before: nothing rendered, no state/refs/effects, no storage touched. NEVER set it on a
+password / secure field. The engine is also exported standalone as `useRecentValues(key, max?)` for
+bespoke recents surfaces, and `AnchoredMenu` gained an optional `accessibilityLabel` for naming the menu.
+
+## 1.13.3
+
+**Placeholder text was too dark — it read like an already-filled value.**
+
+`useThemedInput` painted the placeholder with the theme's `textSecondary` — a deliberately
+dark, accessible grey (design-tokens UX-11) that also renders readable secondary *copy*. At
+full strength a placeholder (e.g. `follower` in a "Dance role" box) was hard to tell apart
+from entered text. It is now `textSecondary` composited toward the field background at 0.6
+alpha, so a hint reads clearly lighter than the solid entered text (`colors.text`) while
+keeping the theme hue — and it works in dark mode too (it composites toward whatever the
+field background is). The field's visible label still carries the accessible name, so this
+is a usability win, not an a11y regression. Affects every `@dloizides/ui-forms`-driven input
+(`FormField`, `Field`, `ThemedTextInput`, the `ui-tables` `Filters` search box) across all
+seven portals.
+
+## 1.12.0
+
+**`FormField` gained `labelHidden` — hide the visible label, keep the accessible name.**
+
+A field whose placeholder already names it (a toolbar search box, an inline filter) does
+not want a stacked visible label: the label wastes a row and, worse, pushes the input a
+label-row lower than a bare button beside it, so the two misalign. Until now the only way
+to drop the visible label was to blank `label` — which ALSO blanked the input's
+`accessibilityLabel`, silently stripping the accessible name.
+
+`labelHidden` removes ONLY the visible `<label>` row: `label` stays required and the input
+keeps `accessibilityLabel={label}`, so a screen reader reads the same name and the field
+still resolves by role + name. Additive and backward-compatible — default `false`, every
+existing call renders unchanged.
+
+## 1.11.1
+
+**`ThemedTextInput` shipped no metrics, so every direct caller got a raw 19px input.**
+
+It documented itself as "the ONE source of truth for the input look" while shipping
+only **colours** — no border, radius, padding or height. `FormField` quietly passed its
+own private duplicate of those metrics, so anything reached *through* `FormField` looked
+correct and the gap was invisible. Every **direct** caller — the documented, blessed
+usage — got a raw browser input.
+
+Measured live in the Digital Kin CMS before: **10/10 inputs below the 48px floor**, text
+inputs 19px, textareas 38px. After: **0/10**, at 48/96px.
+
+**Label association was absent entirely** (0 `label[for]`, 0 ids). Two defects only a
+real browser could find, both fixed here:
+
+- **`htmlFor` is silently dropped by react-native-web** — it is not on the prop
+  allowlist, the same family as the dropped `accessibilityHint`. A prop-level assertion
+  passes against the broken build; only a DOM-level test catches it, so that is what the
+  new tests assert.
+- **Dangling `for`.** `Field` assumed render-function children place the id they are
+  handed, but `SelectControl` uses `aria-labelledby` instead — so the difficulty label
+  shipped `for="field-control-3"` pointing at **nothing**, passing every structural check
+  while focusing no field. `useHtmlFor` now sets `for` only when the target is genuinely
+  in the document.
+
+> ⚠️ **Cross-fleet visual change.** `controlStyles.input` gaining `minHeight: 48` lifts
+> dense filter inputs and select triggers in `aml-v2`/`agora-web` from ~38-41px to 48px.
+> This cannot be avoided: the input floor is what fixes the 19px defect, and nothing
+> fixes that without also lifting inputs that already had padding. Owner-approved.
+
+
+## 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,
+a11y-wired set of form controls inside its `Filters` bar and exported NONE of them: its
+`src/index.ts` exposed only `Filters`, `useFilterDraft`, `suggestOptions`, `isUnmatched` and
+types. Six portals could SEE those controls working and none could import them, so the fleet
+reimplemented them — **6 independent select implementations, 5 date fields, 2 typeaheads**. Same
+shape as `MultiTenancy.EntityFrameworkCore` shipping no EF Core. This release makes them public.
+
+Nothing here moves a pixel for an existing consumer: the metrics are the promoted originals,
+unchanged. `CONTAINER_MARGIN_BOTTOM` and `ChipSelector`'s compensating `marginBottom:
+-CHIP_GUTTER` remain deliberately untouched.
+
+- **Add `SelectControl`** — single-select enum/status dropdown. Bordered trigger + chevron opening
+  the shared `AnchoredMenu`.
+- **Add `TypeaheadControl`** — search-as-you-type combobox (aml-v2's CountryPicker, generalized).
+  Free typing is preserved (the value is raw text the caller normalises at query time); picking a
+  suggestion fills the canonical LABEL, not the value.
+- **Add `DateRangeControl`** — inclusive from/to pair. Editing one side patches ONLY that side.
+- **Add `AnchoredMenu`** — the floating option list both of the above compose. Kept in-tree with
+  NO `ui-layout` dependency; that was a considered choice in `ui-tables` and it still holds, since
+  depending on the higher-level `ModalDropdown` would invert the graph for every consumer.
+- **Add `controlStyles`** — the tuned metrics, promoted verbatim. `ui-tables`' `Filters/styles.ts`
+  said the quiet part out loud in its own header: it "reconcile[d] the per-field styles that were
+  copy-pasted across aml-v2's filter files into one shared source" — and then locked the
+  reconciliation inside one bar where no other surface could reach it.
+- **Add `suggestOptions` / `isUnmatched`** — the ranked substring matcher behind the typeahead.
+- **Add `ControlOption` / `DateRangeValue`** types. `ui-tables` now ALIASES its long-standing
+  public `FilterOption` / `DateRangeValue` onto these, so there is one definition rather than two
+  structurally-compatible twins free to drift.
+
+### The controls are LABEL-FREE, on purpose
+
+They render the control only. Compose them inside `Field` — with `labelVariant="control"` on a
+dense surface — to get the label, hint and error slots. That is what retires `ui-tables`' private
+`FieldShell` fork (see `@dloizides/ui-tables` 1.14.0) and leaves ONE label implementation for
+every control instead of one per control.
+
+### i18n: this package still never calls `t`
+
+Every string — `accessibilityLabel`, `placeholder`, `optionHint`, `error`, `fromLabel`/`toLabel`
+— is a PRE-LOCALIZED prop. This is load-bearing, not stylistic: aml-v2 localizes through
+`@dloizides/i18n` with positional `{0}` while the other six portals use i18next `{{p1}}`, so a
+component that localized internally could not serve both. `SelectControl`'s `accessibilityLabel`
+is therefore composed BY THE CALLER — it must carry the selection ("Status: Active", not
+"Status"), and building that string needs a `t` call this package must not make.
+
+### Fixed — a WCAG defect carried in by the promoted code
+
+`AnchoredMenu` marked the current option with `accessibilityState={{ selected }}` alone.
+**react-native-web does not read `accessibilityState` at all** (verified against
+`react-native-web@0.21`'s `createDOMProps`, which enumerates `aria-selected` /
+`accessibilitySelected` and never `accessibilityState`), so on web the selected option was
+distinguished by colour and font-weight ONLY — no screen reader could tell which option was
+current (WCAG 1.4.1, use of colour). `aria-selected` is now passed alongside, so each platform
+gets the channel it honours. The trigger already paired `aria-expanded` with `accessibilityState`;
+the option row was simply missed when that was done. A test asserts it, and that test FAILED
+before the fix.
+
+## 1.7.0
+
+Additive wave implementing the shared cross-stack forms contract now written down at
+`PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md`. **Nothing in this release moves a pixel
+for an existing consumer**: every addition is opt-in and every default is the previous behaviour.
+`CONTAINER_MARGIN_BOTTOM` and `ChipSelector`'s compensating `marginBottom: -CHIP_GUTTER` are
+deliberately untouched — they are load-bearing and move together in a later, visual-QA-gated wave.
+
+- **Add `FormActions` — the submit/cancel row.** Promoted from the BYTE-IDENTICAL
+  `erevna-web/src/components/Forms/FormActions.tsx` and `katalogos-web/.../FormActions.tsx`
+  (68 lines each; `diff` returns nothing). All seven portals hand-roll this row; aml-v2, agora,
+  kefi, ichnos and zygos each inline their own variant. The primary action is LAST in DOM order so
+  tab reaches Cancel before Save, and `saving` drives the primary button's spinner rather than
+  disabling-and-relabelling it. `saveDisabled` blocks Save WITHOUT blocking Cancel — an invalid
+  form stays escapable. testIDs default to the twins' `save-button` / `cancel-button`, so existing
+  Playwright selectors keep matching.
+- **`Field` gains `hint`.** ~21 hand-rolled copies of `{fontSize:12, marginTop:4, color:
+  textSecondary}` exist across the fleet; aml-v2 alone declares a local `hint` style in 8 files.
+  Because `Field` had no hint slot, consumers rendered the hint as a SIBLING, where it lands past
+  the container's 16px bottom margin and detaches from the control it explains (see the apologetic
+  comment in `aml-v2/src/screens/screening/CoverageSelector.tsx`). The hint renders UNDER the
+  control and ABOVE the error, and hint and error COEXIST — both are reachable from the control via
+  a composed `aria-describedby` (hint id then error id, in reading order). Only the error is a
+  `role="alert"` live region; a hint that announced itself would interrupt on every focus.
+- **`Field` gains `optional` + `optionalLabel`.** Mutually exclusive with `required`; when a caller
+  sets both, `required` WINS — the safe direction, since an under-marked required field sends the
+  user into a failed submit. Enforced at runtime in `resolveFieldMarker` rather than in the type
+  system, so a caller spreading a computed props object still gets a defined single-marker result
+  instead of a compile error it cannot act on. Like the asterisk, the optional text is decorative
+  (`aria-hidden`) — "optional" is the ABSENCE of `aria-required`, which assistive tech already
+  conveys.
+- **`Field` gains `labelVariant` (+ `labelStyle` as the escape hatch).** `Field` hard-coded
+  13/600/sentence-case, which is exactly why kefi-web refused it and why `@dloizides/ui-tables`'
+  private `FieldShell` forked to 11/700/uppercase. `labelVariant` makes the contract's TWO
+  legitimate voices first-class and named: `field` (13/600 sentence case — a label that is READ)
+  and `control` (11/700 UPPERCASE + letter-spacing — a label that is SCANNED, for dense filter bars
+  and toolbars). An absent variant resolves to `field`, so every existing consumer renders
+  byte-identically. `labelStyle` applies AFTER the variant for the genuine one-off.
+- **`Field`'s `containerStyle` widens `ViewStyle` -> `StyleProp<ViewStyle>`.** The narrow type was a
+  documented pain: `aml-v2/src/screens/leaders/CountryPicker.tsx` has to build a COMPLETE style per
+  variant because it cannot compose an array.
+- **`useThemedInput`: a focused errored field now keeps a RED focus ring.** It previously computed
+  `isFocused && !hasError`, so an errored field got NO focus ring at all — removing the focus
+  indicator (WCAG 2.4.7) from precisely the field the user was sent back to fix, at the moment they
+  are most likely navigating by keyboard. It now always rings on focus and only changes the ring's
+  COLOUR, matching v1's `input.invalid:focus { box-shadow: 0 0 0 3px var(--danger-tint) }`.
+  One pre-existing test necessarily changed: it asserted `boxShadow === 'none'` for this state,
+  i.e. it encoded the defect as intended behaviour.
+- **New peer dependency `@dloizides/ui-buttons >= 1.4.0`**, required by `FormActions` so the estate
+  keeps exactly one button implementation rather than forking one here.
+- No i18n runtime is introduced: all user-visible copy (`saveLabel`, `cancelLabel`, `optionalLabel`,
+  `hint`, `error`) arrives pre-localized. aml-v2 localizes via `@dloizides/i18n` with positional
+  `{0}` params while the other six apps use i18next `{{p1}}`, and nothing bridges them, so a
+  component that localized internally could not serve both.
+- Also shipping in this tarball, from a CONCURRENT workstream (commit `13bd281`, not part of this
+  wave): `ChipSelector` gains `chipTestIDPrefix`, `optionAccessibilityHint` and `multiple`
+  toggle semantics, and reads its on-primary ink from the theme's `onBrand` scale instead of a
+  hardcoded `#fff`. All opt-in; the `chip-selector-chip-<value>` testID default is frozen.
+
+## 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.**
+  - `FormField`: the error message is now programmatically tied to the input — the input gets
+    `aria-invalid` when errored and `aria-describedby` pointing at the error line (which is a
+    `role="alert"` live region), and `aria-required` when `required`. The required `*` is marked
+    decorative (`aria-hidden` / `accessibilityElementsHidden`) so a screen reader hears "required"
+    (via `aria-required`) instead of "star".
+  - `ThemedTextInput`: new optional `describedById` + `requiredField` props forward
+    `aria-describedby` / `aria-required`, and it emits `aria-invalid` from `hasError` (web only;
+    no-ops on native). Existing callers are unaffected.
+  - `FormCheckbox`: now keyboard-operable — the `role="checkbox"` Pressable renders a `<div>`
+    (no free Enter/Space), so an explicit web-only Enter/Space handler toggles it (WCAG 2.1.1).
+  - `ChipSelector`: chips gain a `hitSlop` so the touch target reaches ~44px WITHOUT changing the
+    rendered pill size, and expose `accessibilityState.disabled` when the selector is disabled.
+  - `useThemedInput`: the focus/hover CSS transition now collapses to instant when the user
+    requests `prefers-reduced-motion: reduce` (WCAG 2.3.3, web only).
+
+## 1.3.0
+
+- `ChipSelector` gains a `variant` prop (`'solid' | 'outline'`, default `'solid'`). `solid` is the
+  original filled-pill look (selected = solid brand fill, white ink) — existing consumers
+  (erevna / katalogos / kefi) render **identically**, no change. `outline` is the AML v1 console
+  look: an outlined pill on a muted fill where the **selected** state is a subtle tinted-outline
+  (brand border + brand ink + a low-alpha brand wash), NOT a solid fill; on web, hover lifts the
+  border + ink to the brand colour. Fully theme-driven (brand colour + alpha, border/text from the
+  theme), so it re-themes per tenant. Additive + backward-compatible.
+
+## 1.2.0
+
+- Add `ThemedTextInput` + `useThemedInput` — the shared "readable + lively" text-input treatment,
+  driven entirely by the active theme (re-themes per tenant, no hard-coded hex). At rest: dark
+  readable text on a subtle off-white surface with a soft border. On hover (web): the border
+  strengthens a touch. On focus: the border becomes the brand primary, the background brightens to
+  the plain surface (white), and a soft 3px brand-tinted focus ring fades in. The animation is a
+  pure GPU-cheap CSS transition on `border-color`/`background-color`/`box-shadow` (the ring is a
+  `box-shadow`, so no layout/reflow) — NO `Animated`/`LayoutAnimation`/JS timers. Web-only style
+  keys and the mouse-hover handlers are guarded behind `Platform.OS === 'web'`, so it stays
+  native-safe (native applies the state-driven colours instantly).
+- `FormField` now renders `ThemedTextInput`, so every field gets the treatment for free; its label
+  uses `textSecondary` at 13px/600 for readability. Props/behaviour (label, hint, error, testID,
+  a11y, `onFocus`/`onBlur` pass-through) are backward-compatible.
+
+## 1.1.0
+
+- Add `FormCheckbox` — a native-safe (`Pressable`-based, RN-web + native) themed checkbox: a rounded
+  square that fills with the brand colour and shows a check glyph when on, with a label and optional
+  hint. Mirrors `FormSwitch`'s prop shape (`value`, `onValueChange`/`onChange`, `label`, `hint`,
+  `disabled`, `testID`, a11y) so it is a drop-in for boolean toggles that should read as checkboxes.
+  Exposes `role="checkbox"` + `aria-checked` / `accessibilityState={{ checked }}`.
+
+## 1.0.0
+
+Initial release. Extracted the proven duplicated form components from erevna-web ↔ katalogos-web
+(Capability Wave C1, batch 2).
+
+- `FormField`, `ChipSelector`, `FormSwitch` — share the `@dloizides/ui-feedback` UI context (`useUi`).
+- `FormActions` deferred (depends on a not-yet-shared `core/Button`).