@dloizides/ui-forms 1.22.0 → 1.23.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.23.0
+
+BEAD-3 "Report form: searchable pattern field and shared form feedback".
+
+- `TypeaheadControl` takes `search` instead of `options` for async results: `load(query, signal)`, `onPick(option | null)`, loading, empty and error text, 250 ms debounce, stale responses ignored, editing after a pick clears it.
+- `TypeaheadControl` is a WAI-ARIA combobox in both modes: Down, Up, Enter, Esc, `aria-activedescendant`, a ref to its input. Its rows change role from `menuitem` to `option`; testIDs are unchanged.
+- `ControlOption` gains an optional `detail`, shown under the title on a phone and beside it from 768 px.
+- `AnchoredMenu` fits its height above the on-screen keyboard through `visualViewport`; new `listbox` prop for listbox roles and a status line.
+- New `FormStatusLine` and `useFocusFirstInvalid`.
+
 ## 1.22.0
 
 KEFI-EDITOR-UI-2 "Extract stepper and upload-with-link field to @dloizides/ui-forms", extracted from kefi-web.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { RefObject } from 'react';
 import { StyleProp, TextStyle, ViewStyle, TextInputProps, TextInput, View } from 'react-native';
 
 /**
@@ -701,6 +701,7 @@ declare const FormCheckbox: ({ label, value, onValueChange, onChange, hint, desc
 interface ControlOption {
     readonly label: string;
     readonly value: string;
+    readonly detail?: string;
 }
 /** The inclusive from/to value of a date-range control (each an ISO `YYYY-MM-DD` string, or ''). */
 interface DateRangeValue {
@@ -761,6 +762,22 @@ interface SelectControlProps {
 }
 declare function SelectControl({ options, value, onChange, placeholder, accessibilityLabel, accessibilityHint, labelledById, optionHint, style, testID, }: SelectControlProps): React.ReactElement;
 
+interface FieldControlWiring {
+    id?: string;
+    describedById?: string;
+}
+interface TypeaheadSearch {
+    load: (query: string, signal: AbortSignal) => Promise<readonly ControlOption[]>;
+    onPick: (option: ControlOption | null) => void;
+    loadingText: string;
+    emptyText: string;
+    errorText: string;
+    debounceMs?: number;
+    maxResults?: number;
+    scrollMarginTop?: number;
+    inputTestID?: string;
+}
+
 /**
  * `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});
@@ -779,8 +796,7 @@ declare function SelectControl({ options, value, onChange, placeholder, accessib
 declare const DEFAULT_TYPEAHEAD_MIN_CHARS = 1;
 /** Default cap on rendered suggestions. */
 declare const DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS = 8;
-interface TypeaheadControlProps {
-    options: readonly ControlOption[];
+interface TypeaheadCommonProps {
     /** The raw text in the box — NOT necessarily an option value. */
     value: string;
     onChange: (value: string) => void;
@@ -796,14 +812,19 @@ interface TypeaheadControlProps {
     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;
+interface TypeaheadControlProps extends TypeaheadCommonProps {
+    options: readonly ControlOption[];
+    maxSuggestions?: number;
+}
+interface TypeaheadSearchProps extends TypeaheadCommonProps {
+    search: TypeaheadSearch;
+}
+declare const TypeaheadControl: React.ForwardRefExoticComponent<((TypeaheadControlProps | TypeaheadSearchProps) & FieldControlWiring) & React.RefAttributes<TextInput>>;
 
 /**
  * `DateRangeControl` — an inclusive from/to pair (aml cases `from`/`to`, kefi audit `from`/`to`).
@@ -861,10 +882,15 @@ declare function DateRangeControl({ value, onChange, onSubmit, fromLabel, toLabe
 /** The four theme colours the menu paints with — passed in, so the menu stays theme-flat. */
 interface AnchoredMenuColors {
     text: string;
+    textSecondary?: string;
     border: string;
     surface: string;
     brand: string;
 }
+interface AnchoredMenuListbox {
+    highlightedValue: string;
+    statusText?: string;
+}
 interface AnchoredMenuProps {
     options: readonly ControlOption[];
     /** The currently-selected value, highlighted in the list ('' = none). */
@@ -897,8 +923,9 @@ interface AnchoredMenuProps {
      * only for the rare case that genuinely wants the menu clipped to its container.
      */
     usePortal?: boolean;
+    listbox?: AnchoredMenuListbox;
 }
-declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, accessibilityLabel, testID, anchorRef, usePortal, }: AnchoredMenuProps): React.ReactElement;
+declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, accessibilityLabel, testID, anchorRef, usePortal, listbox, }: AnchoredMenuProps): React.ReactElement;
 
 declare const controlStyles: {
     /**
@@ -1104,6 +1131,21 @@ interface StepperNavProps<TKey extends string | number = string> {
 /** Back and next under a step: back is disabled on the first step, next is absent on the last. */
 declare const StepperNav: <TKey extends string | number = string>({ steps, current, onStep, labels, testID, }: StepperNavProps<TKey>) => React.ReactElement;
 
+interface FormStatusLineProps {
+    message: string | null | undefined;
+    testID: string;
+    style?: StyleProp<TextStyle>;
+}
+/** A form's result message, announced as an alert; renders nothing until there is one. */
+declare function FormStatusLine({ message, testID, style }: FormStatusLineProps): React.ReactElement | null;
+
+interface Focusable {
+    focus: () => void;
+}
+type FocusableRefs<Field extends string> = Readonly<Record<Field, RefObject<Focusable | null>>>;
+/** Returns a stable function that focuses the first listed field that is on screen. */
+declare function useFocusFirstInvalid<Field extends string>(refs: FocusableRefs<Field>): (invalid: readonly Field[]) => void;
+
 /** Every string the field shows; all pre-localized. */
 interface UploadWithLinkLabels {
     title: string;
@@ -1128,4 +1170,4 @@ interface UploadWithLinkFieldProps {
 /** An image field: preview, an upload control, and a link input revealed on request. */
 declare const UploadWithLinkField: ({ value, onChange, labels, uploadControl, testID, disabled, previewSize, }: UploadWithLinkFieldProps) => React.ReactElement;
 
-export { AlignToControl, type AlignToControlProps, AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipSingleSelectRole, type ChipVariant, type ControlOption, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, type GroupSelection, INLINE_FIELD_ROW_MIN_WIDTH, InlineFieldRow, type InlineFieldRowLayout, type InlineFieldRowProps, type RecentValues, SelectControl, type SelectControlProps, type StepNeighbours, StepperNav, type StepperNavLabels, type StepperNavProps, type StepperStep, StepperTabs, type StepperTabsProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, UploadWithLinkField, type UploadWithLinkFieldProps, type UploadWithLinkLabels, type UseThemedInputOptions, controlStyles, groupAriaChecked, inlineFieldRowLayout, isUnmatched, resolveGroupSelection, resolveStepNeighbours, suggestOptions, toggleGroupSelection, useRecentValues, useThemedInput };
+export { AlignToControl, type AlignToControlProps, AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuListbox, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipSingleSelectRole, type ChipVariant, type ControlOption, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, type Focusable, type FocusableRefs, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormStatusLine, type FormStatusLineProps, FormSwitch, type FormSwitchProps, type GroupSelection, INLINE_FIELD_ROW_MIN_WIDTH, InlineFieldRow, type InlineFieldRowLayout, type InlineFieldRowProps, type RecentValues, SelectControl, type SelectControlProps, type StepNeighbours, StepperNav, type StepperNavLabels, type StepperNavProps, type StepperStep, StepperTabs, type StepperTabsProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type TypeaheadSearch, type TypeaheadSearchProps, UploadWithLinkField, type UploadWithLinkFieldProps, type UploadWithLinkLabels, type UseThemedInputOptions, controlStyles, groupAriaChecked, inlineFieldRowLayout, isUnmatched, resolveGroupSelection, resolveStepNeighbours, suggestOptions, toggleGroupSelection, useFocusFirstInvalid, useRecentValues, useThemedInput };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { RefObject } from 'react';
 import { StyleProp, TextStyle, ViewStyle, TextInputProps, TextInput, View } from 'react-native';
 
 /**
@@ -701,6 +701,7 @@ declare const FormCheckbox: ({ label, value, onValueChange, onChange, hint, desc
 interface ControlOption {
     readonly label: string;
     readonly value: string;
+    readonly detail?: string;
 }
 /** The inclusive from/to value of a date-range control (each an ISO `YYYY-MM-DD` string, or ''). */
 interface DateRangeValue {
@@ -761,6 +762,22 @@ interface SelectControlProps {
 }
 declare function SelectControl({ options, value, onChange, placeholder, accessibilityLabel, accessibilityHint, labelledById, optionHint, style, testID, }: SelectControlProps): React.ReactElement;
 
+interface FieldControlWiring {
+    id?: string;
+    describedById?: string;
+}
+interface TypeaheadSearch {
+    load: (query: string, signal: AbortSignal) => Promise<readonly ControlOption[]>;
+    onPick: (option: ControlOption | null) => void;
+    loadingText: string;
+    emptyText: string;
+    errorText: string;
+    debounceMs?: number;
+    maxResults?: number;
+    scrollMarginTop?: number;
+    inputTestID?: string;
+}
+
 /**
  * `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});
@@ -779,8 +796,7 @@ declare function SelectControl({ options, value, onChange, placeholder, accessib
 declare const DEFAULT_TYPEAHEAD_MIN_CHARS = 1;
 /** Default cap on rendered suggestions. */
 declare const DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS = 8;
-interface TypeaheadControlProps {
-    options: readonly ControlOption[];
+interface TypeaheadCommonProps {
     /** The raw text in the box — NOT necessarily an option value. */
     value: string;
     onChange: (value: string) => void;
@@ -796,14 +812,19 @@ interface TypeaheadControlProps {
     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;
+interface TypeaheadControlProps extends TypeaheadCommonProps {
+    options: readonly ControlOption[];
+    maxSuggestions?: number;
+}
+interface TypeaheadSearchProps extends TypeaheadCommonProps {
+    search: TypeaheadSearch;
+}
+declare const TypeaheadControl: React.ForwardRefExoticComponent<((TypeaheadControlProps | TypeaheadSearchProps) & FieldControlWiring) & React.RefAttributes<TextInput>>;
 
 /**
  * `DateRangeControl` — an inclusive from/to pair (aml cases `from`/`to`, kefi audit `from`/`to`).
@@ -861,10 +882,15 @@ declare function DateRangeControl({ value, onChange, onSubmit, fromLabel, toLabe
 /** The four theme colours the menu paints with — passed in, so the menu stays theme-flat. */
 interface AnchoredMenuColors {
     text: string;
+    textSecondary?: string;
     border: string;
     surface: string;
     brand: string;
 }
+interface AnchoredMenuListbox {
+    highlightedValue: string;
+    statusText?: string;
+}
 interface AnchoredMenuProps {
     options: readonly ControlOption[];
     /** The currently-selected value, highlighted in the list ('' = none). */
@@ -897,8 +923,9 @@ interface AnchoredMenuProps {
      * only for the rare case that genuinely wants the menu clipped to its container.
      */
     usePortal?: boolean;
+    listbox?: AnchoredMenuListbox;
 }
-declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, accessibilityLabel, testID, anchorRef, usePortal, }: AnchoredMenuProps): React.ReactElement;
+declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, accessibilityLabel, testID, anchorRef, usePortal, listbox, }: AnchoredMenuProps): React.ReactElement;
 
 declare const controlStyles: {
     /**
@@ -1104,6 +1131,21 @@ interface StepperNavProps<TKey extends string | number = string> {
 /** Back and next under a step: back is disabled on the first step, next is absent on the last. */
 declare const StepperNav: <TKey extends string | number = string>({ steps, current, onStep, labels, testID, }: StepperNavProps<TKey>) => React.ReactElement;
 
+interface FormStatusLineProps {
+    message: string | null | undefined;
+    testID: string;
+    style?: StyleProp<TextStyle>;
+}
+/** A form's result message, announced as an alert; renders nothing until there is one. */
+declare function FormStatusLine({ message, testID, style }: FormStatusLineProps): React.ReactElement | null;
+
+interface Focusable {
+    focus: () => void;
+}
+type FocusableRefs<Field extends string> = Readonly<Record<Field, RefObject<Focusable | null>>>;
+/** Returns a stable function that focuses the first listed field that is on screen. */
+declare function useFocusFirstInvalid<Field extends string>(refs: FocusableRefs<Field>): (invalid: readonly Field[]) => void;
+
 /** Every string the field shows; all pre-localized. */
 interface UploadWithLinkLabels {
     title: string;
@@ -1128,4 +1170,4 @@ interface UploadWithLinkFieldProps {
 /** An image field: preview, an upload control, and a link input revealed on request. */
 declare const UploadWithLinkField: ({ value, onChange, labels, uploadControl, testID, disabled, previewSize, }: UploadWithLinkFieldProps) => React.ReactElement;
 
-export { AlignToControl, type AlignToControlProps, AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipSingleSelectRole, type ChipVariant, type ControlOption, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, type GroupSelection, INLINE_FIELD_ROW_MIN_WIDTH, InlineFieldRow, type InlineFieldRowLayout, type InlineFieldRowProps, type RecentValues, SelectControl, type SelectControlProps, type StepNeighbours, StepperNav, type StepperNavLabels, type StepperNavProps, type StepperStep, StepperTabs, type StepperTabsProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, UploadWithLinkField, type UploadWithLinkFieldProps, type UploadWithLinkLabels, type UseThemedInputOptions, controlStyles, groupAriaChecked, inlineFieldRowLayout, isUnmatched, resolveGroupSelection, resolveStepNeighbours, suggestOptions, toggleGroupSelection, useRecentValues, useThemedInput };
+export { AlignToControl, type AlignToControlProps, AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuListbox, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipSingleSelectRole, type ChipVariant, type ControlOption, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, type Focusable, type FocusableRefs, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormStatusLine, type FormStatusLineProps, FormSwitch, type FormSwitchProps, type GroupSelection, INLINE_FIELD_ROW_MIN_WIDTH, InlineFieldRow, type InlineFieldRowLayout, type InlineFieldRowProps, type RecentValues, SelectControl, type SelectControlProps, type StepNeighbours, StepperNav, type StepperNavLabels, type StepperNavProps, type StepperStep, StepperTabs, type StepperTabsProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type TypeaheadSearch, type TypeaheadSearchProps, UploadWithLinkField, type UploadWithLinkFieldProps, type UploadWithLinkLabels, type UseThemedInputOptions, controlStyles, groupAriaChecked, inlineFieldRowLayout, isUnmatched, resolveGroupSelection, resolveStepNeighbours, suggestOptions, toggleGroupSelection, useFocusFirstInvalid, useRecentValues, useThemedInput };