@dloizides/ui-forms 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,123 @@
 # Changelog
 
+## 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

package/README.md

@@ -98,6 +98,48 @@ with no label no label row is rendered, so it drops into a toolbar or filter bar
 | `containerStyle` | `ViewStyle` | merged over the container |
 | `testID` | `string` | on the container |
 
+## Dense controls — `SelectControl` / `TypeaheadControl` / `DateRangeControl`
+
+Promoted in 1.8.0 out of `@dloizides/ui-tables`' private filter bar, where they worked correctly
+for six portals and were exported to none — which is why the fleet grew 6 selects, 5 date fields
+and 2 typeaheads.
+
+They are **label-free by design**. Compose them inside `Field` so there is ONE label
+implementation for every control rather than one per control:
+
+```tsx
+<Field label="Status" labelVariant="control" containerStyle={{ marginBottom: 0 }}>
+  <SelectControl
+    accessibilityLabel={t('filters.statusName', 'Status', selectedLabel)}
+    options={options}
+    testID="filters-status"
+    value={value}
+    onChange={setValue}
+  />
+</Field>
+```
+
+`labelVariant="control"` is the 11/700/uppercase voice from
+[`FORMS.md`](../../../PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md) — the voice for
+labels that are SCANNED (filter bars, toolbars) rather than READ.
+
+### Every string is pre-localized
+
+This package never calls `t`. In particular `SelectControl`'s `accessibilityLabel` must be
+composed by YOU and must carry the **selection** — "Status: Active", not "Status". The accessible
+name REPLACES the trigger's visible text for a screen reader, so naming it with the field alone
+silently hides what is selected.
+
+| Control | Key props | testIDs |
+|---|---|---|
+| `SelectControl` | `options`, `value`, `onChange`, `placeholder`, `accessibilityLabel`, `optionHint` | `<testID>-trigger`, `-menu`, `-option-<value>` |
+| `TypeaheadControl` | `options`, `value`, `onChange`, `onSubmit`, `error`, `minChars`, `maxSuggestions` | `<testID>-input`, `-menu`, `-error` |
+| `DateRangeControl` | `value` (`{from,to}`), `onChange`, `onSubmit`, `fromLabel`, `toLabel` | `<testID>-range`, `-from`, `-to` |
+| `AnchoredMenu` | the floating list the first two compose | `<testID>-menu` |
+
+Also exported: `controlStyles` (the tuned metrics), `suggestOptions` / `isUnmatched` (the
+typeahead's ranker), and the `ControlOption` / `DateRangeValue` types.
+
 ## testIDs
 
 `form-field-input`, `chip-selector-chip-<value>`, `form-switch` (overridable on FormSwitch).

package/dist/index.d.mts

@@ -1,8 +1,31 @@
 import React from 'react';
-import { ViewStyle, TextInputProps, TextInput, TextStyle } from 'react-native';
+import { StyleProp, TextStyle, ViewStyle, TextInputProps, TextInput, View } from 'react-native';
 
 /**
- * Field — the generic "label over a control, error under it" wrapper.
+ * The TWO legitimate label voices, per the shared forms contract
+ * (`PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md` → "The TWO legitimate label voices").
+ *
+ *  - `field`   — 13 / 600 / sentence case. A label that is READ: prose addressed to the person
+ *                filling the form. This is `Field`'s historical, unchanged default, so every
+ *                existing consumer renders byte-identically.
+ *  - `control` — 11 / 700 / UPPERCASE + letter-spacing. A label that is SCANNED: a key over a value
+ *                in a dense row (filter bars, compact toolbars, pager controls). These are exactly
+ *                the metrics `@dloizides/ui-tables` forked into its private `FieldShell` because
+ *                `Field` hard-coded the `field` voice and offered no way out.
+ *
+ * A THIRD voice is drift, not a variant. Pick the voice from the SURFACE, not the component: every
+ * label on one surface uses one voice, and voices are never mixed within a single row.
+ *
+ * Why a plain string union and not a `const enum`: this type crosses the package boundary into
+ * consumers' `.d.ts`, and a cross-boundary `const enum` breaks `isolatedModules` / Babel-only
+ * builds. `@dloizides/ui-buttons` sets the same precedent for `ButtonVariant` for the same reason.
+ */
+
+/** Which of the two contract voices a field label speaks. */
+type FieldLabelVariant = 'field' | 'control';
+
+/**
+ * Field — the generic "label over a control, hint + 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
@@ -13,13 +36,20 @@ import { ViewStyle, TextInputProps, TextInput, TextStyle } from 'react-native';
  * 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.
+ * receiving `{ describedById, hasError }`, so a custom control can wire the hint AND error lines
+ * into its own `aria-describedby` / invalid state exactly the way `FormField` does.
+ *
+ * The anatomy (label → control → hint → error), the two label voices, the mutually-exclusive
+ * required/optional markers and the collapsing error slot all implement the shared cross-stack
+ * contract in `PROOViD/AMLService/AMLService/wwwroot/shared/FORMS.md`.
  */
 
 /** 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. */
+    /**
+     * Space-separated ids of the lines describing this control — the hint, the error, or both, in
+     * reading order. `undefined` when there is neither. Assign straight to `aria-describedby`.
+     */
     describedById?: string;
     hasError: boolean;
 }
@@ -34,11 +64,123 @@ interface FieldProps {
     label?: string;
     children: FieldChildren;
     required?: boolean;
+    /**
+     * Marks the field explicitly optional. MUTUALLY EXCLUSIVE with `required` — if both are set,
+     * `required` wins (the safe direction: an under-marked required field causes a failed submit).
+     * Use it to mark the MINORITY: on a mostly-required form, marking the two optional fields is far
+     * less noise than asterisking the other eleven.
+     */
+    optional?: boolean;
+    /**
+     * Pre-localized text for the optional marker. Defaults to the English `DEFAULT_OPTIONAL_LABEL`
+     * so a single-locale app can adopt `optional` in one line; a localized app MUST pass this.
+     */
+    optionalLabel?: string;
+    /**
+     * Help line rendered UNDER the control and ABOVE the error — the sentence that stops the user
+     * guessing. It coexists with `error` (the hint states the rule, the error says which rule was
+     * broken) and both are reachable from the control via `aria-describedby`.
+     *
+     * Rendering a hint INSIDE the field is the point: as an outside sibling it lands past the
+     * container's 16px bottom margin and detaches from the control it explains.
+     */
+    hint?: string;
     error?: string;
-    containerStyle?: ViewStyle;
+    /**
+     * Which of the two contract label voices to speak: `field` (13/600 sentence case — the default,
+     * unchanged) or `control` (11/700 uppercase — dense filter bars and toolbars).
+     */
+    labelVariant?: FieldLabelVariant;
+    /**
+     * Escape hatch applied AFTER `labelVariant`, for the genuine one-off a variant does not cover.
+     * Prefer `labelVariant`: it is the reviewable, named choice, and a bare `labelStyle` is the thing
+     * to grep for when auditing label drift.
+     */
+    labelStyle?: StyleProp<TextStyle>;
+    /**
+     * `StyleProp` (not a bare `ViewStyle`) so a caller can compose an array — e.g. a base field style
+     * plus a `grow` modifier — instead of having to restate a COMPLETE style per variant.
+     */
+    containerStyle?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+declare const Field: ({ label, children, required, optional, optionalLabel, hint, error, labelVariant, labelStyle, containerStyle, testID, }: FieldProps) => React.ReactElement;
+
+/**
+ * Required / optional markers, per the shared forms contract
+ * (`…/wwwroot/shared/FORMS.md` → "Required and optional markers").
+ *
+ * The contract says the two markers are MUTUALLY EXCLUSIVE — a field is required or optional, never
+ * annotated as both — and that you mark the MINORITY: on a mostly-required form mark the optional
+ * fields, on a mostly-optional form mark the required ones. Asterisking twelve of thirteen fields
+ * is noise that trains the eye to ignore the marker.
+ *
+ * Exclusivity is enforced here rather than in the type system so that a caller spreading a props
+ * object (`<Field {...fieldProps} />`, where both flags may be computed) still gets a defined,
+ * single-marker result instead of a compile error it cannot act on.
+ *
+ * Precedence when a caller asks for BOTH: `required` wins. That is the safe failure direction —
+ * showing "optional" on a field the server will reject sends the user into a failed submit, while
+ * showing "required" on a genuinely optional field costs, at worst, an unnecessary keystroke.
+ */
+/** Which marker a field label carries. Exactly one, never both. */
+type FieldMarker = 'none' | 'required' | 'optional';
+/**
+ * The English fallback for the optional marker's text.
+ *
+ * `@dloizides/ui-forms` contains NO i18n runtime by design — aml-v2 uses `@dloizides/i18n` with
+ * positional `{0}` params while the other six apps use i18next `{{p1}}`, and nothing bridges them,
+ * so all user-visible copy arrives as pre-localized props. This constant exists ONLY so a
+ * single-locale app can adopt `optional` in one line. It is exported precisely so it is greppable:
+ * **a localized app MUST pass `optionalLabel`.** The required marker needs no such escape — `*` is
+ * a glyph, not copy.
+ */
+declare const DEFAULT_OPTIONAL_LABEL = "(optional)";
+
+/**
+ * `FormActions` — the submit/cancel button row every form ends with.
+ *
+ * Promoted from the BYTE-IDENTICAL `erevna-web/src/components/Forms/FormActions.tsx` and
+ * `katalogos-web/src/components/Forms/FormActions.tsx` (68 lines each, `diff` returns nothing);
+ * all seven apps hand-roll the same row. Buttons come from the shared `@dloizides/ui-buttons` kit
+ * rather than being forked here, so there is exactly one button implementation in the estate.
+ *
+ * The layout implements the contract's actions row
+ * (`…/wwwroot/shared/FORMS.md` → "Actions row"): the primary action is LAST in DOM order, so tab
+ * order reaches Cancel before Save, and `saving` drives the primary button's spinner rather than
+ * disabling-and-relabelling it.
+ *
+ * Two minimal generalizations over the app-local twins:
+ *  1. Labels and hints arrive as PRE-LOCALIZED props. The twins called `FM()` internally, which
+ *     cannot work here: aml-v2 localizes via `@dloizides/i18n` with positional `{0}` params while
+ *     the other six use i18next `{{p1}}`, and nothing bridges them.
+ *  2. `testID`s are overridable but default to the twins' `save-button` / `cancel-button`, so the
+ *     existing Playwright selectors in every app keep matching.
+ */
+
+interface FormActionsProps {
+    /** Submit handler. May be async — the shared Button drives its own spinner for the promise. */
+    onSave: () => void | Promise<unknown>;
+    /** Cancel handler. Omit it entirely to render a save-only row (no empty Cancel slot). */
+    onCancel?: () => void | Promise<unknown>;
+    /** Pre-localized label for the primary action. */
+    saveLabel: string;
+    /** Pre-localized label for the cancel action. Required whenever `onCancel` is supplied. */
+    cancelLabel?: string;
+    /** Pre-localized accessibility hint for the primary action. Falls back to its label. */
+    saveHint?: string;
+    /** Pre-localized accessibility hint for the cancel action. Falls back to its label. */
+    cancelHint?: string;
+    /** In-flight submit: spins the primary action and disables cancel so the form can't be abandoned mid-write. */
+    saving?: boolean;
+    /** Disables the primary action independently of `saving` (e.g. an invalid form). */
+    saveDisabled?: boolean;
+    containerStyle?: StyleProp<ViewStyle>;
+    saveTestID?: string;
+    cancelTestID?: string;
     testID?: string;
 }
-declare const Field: ({ label, children, required, error, containerStyle, testID, }: FieldProps) => React.ReactElement;
+declare const FormActions: ({ onSave, onCancel, saveLabel, cancelLabel, saveHint, cancelHint, saving, saveDisabled, containerStyle, saveTestID, cancelTestID, testID, }: FormActionsProps) => React.ReactElement;
 
 /**
  * Reusable form field — labelled text input with optional required mark + error.
@@ -153,8 +295,20 @@ interface ChipSelectorProps<T> {
     /** Validation message under the chips, wired to the chip group via `aria-describedby`. */
     error?: string;
     testID?: string;
+    /**
+     * Stem for each chip's testID — a chip becomes `${chipTestIDPrefix}-${value}`. Defaults to
+     * `chip-selector-chip`, which existing specs select on; supply your own when a screen has
+     * several chip groups that must be addressed independently.
+     */
+    chipTestIDPrefix?: string;
+    /**
+     * Accessibility hint applied to every chip in the group. Supply a LOCALIZED string — the
+     * built-in default (`Selects <label>`) is English-only and exists solely so pre-existing
+     * consumers keep their current announcement.
+     */
+    optionAccessibilityHint?: string;
 }
-declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, required, error, testID, }: ChipSelectorProps<T>) => React.ReactElement;
+declare const ChipSelector: <T extends string | number>({ label, options, value, onChange, multiple, disabled, variant, containerStyle, required, error, testID, chipTestIDPrefix, optionAccessibilityHint, }: ChipSelectorProps<T>) => React.ReactElement;
 
 /**
  * Reusable form switch/toggle with an optional description.
@@ -197,4 +351,277 @@ 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, Field, type FieldChildContext, type FieldChildren, type FieldProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormSwitch, type FormSwitchProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, type UseThemedInputOptions, useThemedInput };
+/**
+ * Shared value types for the dense CONTROLS (select / typeahead / date-range) promoted out of
+ * `@dloizides/ui-tables`' private filter bar.
+ *
+ * They live here, not in `ui-tables`, because a control's option list and a date range are form
+ * concepts — a filter bar is only one surface that happens to compose them. `ui-tables` aliases
+ * its long-standing public names (`FilterOption`, `DateRangeValue`) onto these, so there is ONE
+ * definition and the two can never drift into structurally-compatible-but-separate twins.
+ */
+/** A single choice in a select / typeahead. `label` is PRE-LOCALIZED by the caller. */
+interface ControlOption {
+    readonly label: string;
+    readonly value: string;
+}
+/** The inclusive from/to value of a date-range control (each an ISO `YYYY-MM-DD` string, or ''). */
+interface DateRangeValue {
+    readonly from: string;
+    readonly to: string;
+}
+
+/**
+ * `SelectControl` — a single-select enum/status dropdown. A bordered trigger shows the selected
+ * option's label (or the placeholder when unset) plus a chevron; pressing it opens the shared
+ * {@link AnchoredMenu}. Selecting fires `onChange` and closes.
+ *
+ * Promoted out of `@dloizides/ui-tables`' private `Filters/fields/SelectField`, where six portals
+ * could see it working and none could import it — which is why the fleet grew SIX independent
+ * select implementations.
+ *
+ * The control is LABEL-FREE by design: wrap it in a `Field` (with `labelVariant="control"` on a
+ * dense surface) to get the label, hint and error slots. That keeps one label implementation for
+ * every control instead of one per control.
+ *
+ * i18n: this package never calls `t`. `accessibilityLabel`, `placeholder`, `accessibilityHint`
+ * and `optionHint` are PRE-LOCALIZED strings supplied by the caller — the only shape that can
+ * serve both aml-v2's positional `{0}` `@dloizides/i18n` and the other six portals' i18next
+ * `{{p1}}` from one component.
+ */
+
+interface SelectControlProps {
+    options: readonly ControlOption[];
+    /** The selected option's `value`. `''` (or any unmatched value) renders the placeholder. */
+    value: string;
+    onChange: (value: string) => void;
+    /** PRE-LOCALIZED text shown when the value matches no option. */
+    placeholder?: string;
+    /**
+     * PRE-LOCALIZED accessible NAME of the trigger. It REPLACES the trigger's visible text for a
+     * screen reader, so it must carry the SELECTION too — "Status: Active", not just "Status",
+     * which announces the control but silently hides its value.
+     */
+    accessibilityLabel: string;
+    accessibilityHint?: string;
+    /** PRE-LOCALIZED accessibility hint applied to every option in the menu. */
+    optionHint?: string;
+    /** Merged LAST onto the anchor wrapper — the consumer always wins over the shared style. */
+    style?: StyleProp<ViewStyle>;
+    /** Trigger is `${testID}-trigger`, menu `${testID}-menu`, options `${testID}-option-${value}`. */
+    testID: string;
+}
+declare function SelectControl({ options, value, onChange, placeholder, accessibilityLabel, accessibilityHint, optionHint, style, testID, }: SelectControlProps): React.ReactElement;
+
+/**
+ * `TypeaheadControl` — a search-as-you-type combobox (aml-v2's CountryPicker, generalized). A
+ * text input plus a floating {@link AnchoredMenu} of ranked suggestions ({@link suggestOptions});
+ * picking one fills the canonical label.
+ *
+ * Free typing is PRESERVED: the value is the raw text, so a caller can accept "CY", "cyprus" or
+ * "Cyprus (CY)" and normalise it themselves at query time, exactly as aml does. An optional
+ * PRE-LOCALIZED `error` shows a persistent banner and tints the border.
+ *
+ * Promoted out of `@dloizides/ui-tables`' private `Filters/fields/TypeaheadField`.
+ *
+ * Label-free by design — wrap in a `Field` for the label/hint slots.
+ */
+
+/** Default min characters before suggestions surface. */
+declare const DEFAULT_TYPEAHEAD_MIN_CHARS = 1;
+/** Default cap on rendered suggestions. */
+declare const DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS = 8;
+interface TypeaheadControlProps {
+    options: readonly ControlOption[];
+    /** The raw text in the box — NOT necessarily an option value. */
+    value: string;
+    onChange: (value: string) => void;
+    /** Called on Enter/submit (after the menu closes). Omit if the surface has nothing to commit. */
+    onSubmit?: () => void;
+    placeholder?: string;
+    /** PRE-LOCALIZED accessible name of the input. */
+    accessibilityLabel: string;
+    accessibilityHint?: string;
+    /** PRE-LOCALIZED accessibility hint applied to every suggestion. */
+    optionHint?: string;
+    /** PRE-LOCALIZED inline error (e.g. "Unrecognised country"). Shows a persistent banner. */
+    error?: string;
+    /** Minimum characters before suggestions surface. Default 1. */
+    minChars?: number;
+    /** Cap on rendered suggestions. Default 8. */
+    maxSuggestions?: number;
+    /** Merged LAST onto the anchor wrapper. */
+    style?: StyleProp<ViewStyle>;
+    /** Input is `${testID}-input`, menu `${testID}-menu`, error `${testID}-error`. */
+    testID: string;
+}
+declare function TypeaheadControl({ options, value, onChange, onSubmit, placeholder, accessibilityLabel, accessibilityHint, optionHint, error, minChars, maxSuggestions, style, testID, }: TypeaheadControlProps): React.ReactElement;
+
+/**
+ * `DateRangeControl` — an inclusive from/to pair (aml cases `from`/`to`, kefi audit `from`/`to`).
+ * Each side is a `YYYY-MM-DD` text input; on web the browser's native date UI is offered via
+ * `type="date"` (a react-native-web `TextInput` passes unknown props to the DOM input). Editing
+ * either side patches ONLY that side, so the other survives the edit.
+ *
+ * Promoted out of `@dloizides/ui-tables`' private `Filters/fields/DateRangeField`, which is why
+ * the fleet grew FIVE independent date fields.
+ *
+ * Label-free by design — the From/To sub-labels name the two HALVES; wrap in a `Field` for the
+ * range's own label.
+ */
+
+interface DateRangeControlProps {
+    value: DateRangeValue;
+    onChange: (value: DateRangeValue) => void;
+    /** Called on Enter/submit in either side. */
+    onSubmit?: () => void;
+    /** PRE-LOCALIZED sub-label for the FROM input (e.g. "From"). Also its accessible name. */
+    fromLabel: string;
+    /** PRE-LOCALIZED sub-label for the TO input (e.g. "To"). Also its accessible name. */
+    toLabel: string;
+    fromPlaceholder?: string;
+    toPlaceholder?: string;
+    /** PRE-LOCALIZED hint applied to BOTH inputs. */
+    accessibilityHint?: string;
+    /** Merged LAST onto the row wrapper. */
+    style?: StyleProp<ViewStyle>;
+    /** Row is `${testID}-range`, inputs `${testID}-from` / `${testID}-to`. */
+    testID: string;
+}
+declare function DateRangeControl({ value, onChange, onSubmit, fromLabel, toLabel, fromPlaceholder, toPlaceholder, accessibilityHint, style, testID, }: DateRangeControlProps): React.ReactElement;
+
+/**
+ * `AnchoredMenu` — the floating option list shared by `SelectControl` and `TypeaheadControl`.
+ *
+ * Renders an in-tree, absolutely-positioned popover under its anchor (the pattern aml-v2's
+ * CountryPicker proved: `position:absolute; top:100%; zIndex; elevation`), so it floats over
+ * sibling fields without a portal. On web it dismisses on outside-click / Escape; on native the
+ * caller closes it on blur/select. Purely presentational + theme-flat, so it stays reusable.
+ *
+ * Promoted verbatim out of `@dloizides/ui-tables`' private `Filters/components/AnchoredMenu`.
+ *
+ * Deliberately in-tree (no `ui-layout` dependency). That was a considered choice in `ui-tables`
+ * and it still holds here: `ui-forms` is a low-level primitive and must not take a runtime
+ * dependency on the higher-level `ui-layout` `ModalDropdown` — that would invert the graph for
+ * every consumer. Apps needing the responsive modal/bottom-sheet variant inject it instead.
+ */
+
+/** The four theme colours the menu paints with — passed in, so the menu stays theme-flat. */
+interface AnchoredMenuColors {
+    text: string;
+    border: string;
+    surface: string;
+    brand: string;
+}
+interface AnchoredMenuProps {
+    options: readonly ControlOption[];
+    /** The currently-selected value, highlighted in the list ('' = none). */
+    selectedValue: string;
+    onSelect: (value: string) => void;
+    onDismiss: () => void;
+    colors: AnchoredMenuColors;
+    /** PRE-LOCALIZED accessibility hint applied to every option. */
+    optionHint: string;
+    /** Base testID: the menu is `${testID}-menu`, each option `${testID}-option-${value}`. */
+    testID: string;
+    /** Node whose clicks count as "inside" (the anchor) so its own press doesn't self-dismiss. */
+    anchorRef: React.RefObject<View | null>;
+}
+declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, testID, anchorRef, }: AnchoredMenuProps): React.ReactElement;
+
+declare const controlStyles: {
+    /** The shared bordered box every dense text control renders in. */
+    input: {
+        borderWidth: number;
+        borderRadius: number;
+        paddingHorizontal: number;
+        paddingVertical: number;
+        fontSize: number;
+    };
+    /** The select trigger: a bordered field box matching the text inputs + a chevron. */
+    selectTrigger: {
+        flexDirection: "row";
+        alignItems: "center";
+        justifyContent: "space-between";
+        gap: number;
+        borderWidth: number;
+        borderRadius: number;
+        paddingHorizontal: number;
+        paddingVertical: number;
+    };
+    selectTriggerText: {
+        fontSize: number;
+        flexShrink: number;
+    };
+    chevron: {
+        fontSize: number;
+    };
+    dateRow: {
+        flexDirection: "row";
+        gap: number;
+    };
+    dateCol: {
+        gap: number;
+        flex: number;
+    };
+    /**
+     * The micro-caption above a sub-control (a date range's From/To) and beside a switch. Note it
+     * is deliberately NOT the `control` label voice: it carries no `700`/uppercase, because it
+     * names a HALF of a control that already has a `control`-voice label above it. Uppercasing it
+     * too would make one field shout twice.
+     */
+    subLabel: {
+        fontSize: number;
+        letterSpacing: number;
+    };
+    /** Positioning context for a floating `AnchoredMenu` (`position:absolute; top:100%`). */
+    anchor: {
+        position: "relative";
+    };
+    menu: {
+        position: "absolute";
+        top: "100%";
+        left: number;
+        marginTop: number;
+        minWidth: number;
+        maxHeight: number;
+        borderWidth: number;
+        borderRadius: number;
+        paddingVertical: number;
+        zIndex: number;
+        boxShadow: string;
+        elevation: number;
+        overflow: "hidden";
+    };
+    option: {
+        paddingHorizontal: number;
+        paddingVertical: number;
+    };
+    optionText: {
+        fontSize: number;
+    };
+    error: {
+        fontSize: number;
+        marginTop: number;
+    };
+};
+
+/**
+ * `suggestOptions` — the ranked substring matcher behind `TypeaheadControl`, generalized from
+ * aml-v2's `suggestCountries` and promoted verbatim out of `@dloizides/ui-tables`' private
+ * `Filters/utils/suggest.ts`.
+ *
+ * Ranks: value exact (0) > value prefix (1) > label prefix (2) > label contains (3); ties broken
+ * by `label.localeCompare`. Empty/short queries return `[]` — nothing surfaces until `minChars`
+ * is typed, mirroring a native `<datalist>`.
+ */
+
+/**
+ * Rank + cap the options matching `query`. Returns `[]` until `query` (trimmed) is at least
+ * `minChars` long, then the best `limit` matches, ranked as documented above.
+ */
+declare function suggestOptions(options: readonly ControlOption[], query: string, minChars: number, limit: number): readonly ControlOption[];
+/** 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 };