@dloizides/ui-forms 1.7.0 → 1.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import { StyleProp, TextStyle, ViewStyle, TextInputProps, TextInput } from 'react-native';
+import { StyleProp, TextStyle, ViewStyle, TextInputProps, TextInput, View } from 'react-native';
 
 /**
  * The TWO legitimate label voices, per the shared forms contract
@@ -351,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, DEFAULT_OPTIONAL_LABEL, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, FormActions, type FormActionsProps, 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 };