@dloizides/ui-forms 1.13.3 → 1.14.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 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.**

package/dist/index.d.mts

@@ -394,8 +394,21 @@ interface FormFieldProps extends Omit<TextInputProps, 'style'> {
     required?: boolean;
     error?: string;
     containerStyle?: ViewStyle;
+    /**
+     * OPT-IN "recent values" behaviour. When set, the values submitted through this field are
+     * remembered (per this key) and offered in a dropdown on focus; picking one fills the input.
+     * Values are recorded on submit (Enter) and on blur-with-content. Persisted to `localStorage`
+     * under `@dloizides/ui-forms:recent:<recentKey>`; a silent no-op on native / when storage is
+     * unavailable.
+     *
+     * Leave it UNSET (the default) and the field behaves exactly as before — nothing rendered, no
+     * storage touched. NEVER set it on a password / secure field: recents must not persist secrets.
+     */
+    recentKey?: string;
+    /** Cap on remembered values when {@link recentKey} is set (most-recent-first). Default 10. */
+    recentMax?: number;
 }
-declare const FormField: ({ label, labelHidden, required, error, containerStyle, ...textInputProps }: FormFieldProps) => React.ReactElement;
+declare const FormField: ({ label, labelHidden, required, error, containerStyle, recentKey, recentMax, ...textInputProps }: FormFieldProps) => React.ReactElement;
 
 /**
  * `ThemedTextInput` — the shared, readable + lively text-input primitive. A thin `<TextInput>`
@@ -479,6 +492,38 @@ interface ThemedInput {
 }
 declare function useThemedInput(options?: UseThemedInputOptions): ThemedInput;
 
+interface RecentValues {
+    /** The remembered values, most-recent-first (never longer than `max`; `[]` when storage is unavailable). */
+    recents: string[];
+    /** Fold a value into the list (trim / de-dupe / promote / cap) and persist. Empty values are ignored. */
+    remember: (value: string) => void;
+    /** Forget every remembered value for this key and clear it from storage. */
+    clear: () => void;
+}
+/**
+ * @param key logical name for this input's history (namespaced under `@dloizides/ui-forms:recent:`).
+ * @param max most-recent-first cap on remembered values. Default {@link DEFAULT_MAX_RECENTS}.
+ */
+declare function useRecentValues(key: string, max?: number): RecentValues;
+
+/**
+ * `recentValuesCore` — the pure + storage-facing internals of {@link useRecentValues}, kept out of
+ * the hook file so the list algebra (trim / de-dupe / promote / cap) and the `localStorage` access
+ * are each unit-testable in isolation.
+ *
+ * ## RN-web storage reality
+ *
+ * `ui-forms` runs on react-native-web, so a component using this may mount on web (where
+ * `window.localStorage` exists), on native (where it does NOT), or under SSR / a hardened browser
+ * where touching `window.localStorage` THROWS (disabled cookies, privacy mode, quota). Every access
+ * therefore goes through {@link getStorage}, which returns `null` rather than throwing, and every
+ * read/write is wrapped so a storage failure degrades to an in-memory-only no-op instead of
+ * exploding inside render. On native / when storage is unavailable the feature is simply inert and
+ * the recents list is always `[]`.
+ */
+/** Default cap on remembered values (most-recent-first). */
+declare const DEFAULT_MAX_RECENTS = 10;
+
 /**
  * Chip/pill selector for selecting one or multiple options.
  *
@@ -737,12 +782,13 @@ declare function DateRangeControl({ value, onChange, onSubmit, fromLabel, toLabe
 /**
  * `AnchoredMenu` — the floating option list shared by `SelectControl` and `TypeaheadControl`.
  *
- * By default it renders an in-tree, absolutely-positioned popover under its anchor
- * (`position:absolute; top:100%; zIndex; elevation`). Set {@link AnchoredMenuProps.usePortal} to
- * render it — on web only — in a PORTAL to `document.body` with `position: fixed` at the trigger's
- * measured rect instead: that escapes react-native-web's trapped `z-index: 0` stacking contexts and
- * any ancestor `overflow: hidden`, so the menu is never painted under / clipped by later siblings
- * (the fix for the Country typeahead menu that hid behind the content below it). See {@link menuPortal}.
+ * By DEFAULT (web) it renders in a PORTAL to `document.body` with `position: fixed` at the trigger's
+ * measured rect: that escapes react-native-web's trapped `z-index: 0` stacking contexts and any
+ * ancestor `overflow: hidden`, so the menu is never painted under / clipped by later siblings (a
+ * table, a card, the next filter field). On native, and when {@link AnchoredMenuProps.usePortal} is
+ * explicitly `false`, it renders an in-tree, absolutely-positioned popover under its anchor
+ * (`position:absolute; top:100%; zIndex; elevation`) — which is exactly what left `SelectControl`'s
+ * menu hidden behind the attendee table until the default flipped. See {@link menuPortal}.
  * 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.
  *
@@ -769,6 +815,12 @@ interface AnchoredMenuProps {
     colors: AnchoredMenuColors;
     /** PRE-LOCALIZED accessibility hint applied to every option. */
     optionHint: string;
+    /**
+     * PRE-LOCALIZED accessible NAME for the menu container itself (e.g. "Recent values"). Optional and
+     * additive — omitted, the menu keeps only its `role="menu"` as before, so existing callers are
+     * unaffected. Supplied, a screen reader announces the list's purpose, not just "menu".
+     */
+    accessibilityLabel?: 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. */
@@ -777,12 +829,17 @@ interface AnchoredMenuProps {
      * On web, render the popover in a portal to `document.body` with `position: fixed` at the anchor's
      * measured rect, so it escapes react-native-web's trapped stacking contexts and any ancestor
      * `overflow: hidden` (the fix for a menu that paints under / is clipped by the content below it).
-     * No effect on native. Default `false` — the existing in-tree behaviour, so `SelectControl`
-     * usages are unchanged; `TypeaheadControl` opts in.
+     * No effect on native (the `IS_WEB` guard keeps native in-tree regardless).
+     *
+     * Default `true` — portalling is the CORRECT default: an in-tree popover is always at risk of
+     * being painted under a later-painting sibling (a table, a card, the next filter field). The old
+     * default was `false`, which silently left `SelectControl`'s menu hidden behind the attendee table
+     * (a recurrence of the exact bug this mechanism fixed for `TypeaheadControl`). Pass `usePortal={false}`
+     * only for the rare case that genuinely wants the menu clipped to its container.
      */
     usePortal?: boolean;
 }
-declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, testID, anchorRef, usePortal, }: AnchoredMenuProps): React.ReactElement;
+declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, accessibilityLabel, testID, anchorRef, usePortal, }: AnchoredMenuProps): React.ReactElement;
 
 declare const controlStyles: {
     /**
@@ -887,4 +944,4 @@ declare function suggestOptions(options: readonly ControlOption[], query: string
 /** True when `text` is non-empty yet matches no option's value or label exactly (case-insensitive). */
 declare function isUnmatched(options: readonly ControlOption[], text: string): boolean;
 
-export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, type ControlOption, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useThemedInput };
+export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, 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 RecentValues, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useRecentValues, useThemedInput };

package/dist/index.d.ts

@@ -394,8 +394,21 @@ interface FormFieldProps extends Omit<TextInputProps, 'style'> {
     required?: boolean;
     error?: string;
     containerStyle?: ViewStyle;
+    /**
+     * OPT-IN "recent values" behaviour. When set, the values submitted through this field are
+     * remembered (per this key) and offered in a dropdown on focus; picking one fills the input.
+     * Values are recorded on submit (Enter) and on blur-with-content. Persisted to `localStorage`
+     * under `@dloizides/ui-forms:recent:<recentKey>`; a silent no-op on native / when storage is
+     * unavailable.
+     *
+     * Leave it UNSET (the default) and the field behaves exactly as before — nothing rendered, no
+     * storage touched. NEVER set it on a password / secure field: recents must not persist secrets.
+     */
+    recentKey?: string;
+    /** Cap on remembered values when {@link recentKey} is set (most-recent-first). Default 10. */
+    recentMax?: number;
 }
-declare const FormField: ({ label, labelHidden, required, error, containerStyle, ...textInputProps }: FormFieldProps) => React.ReactElement;
+declare const FormField: ({ label, labelHidden, required, error, containerStyle, recentKey, recentMax, ...textInputProps }: FormFieldProps) => React.ReactElement;
 
 /**
  * `ThemedTextInput` — the shared, readable + lively text-input primitive. A thin `<TextInput>`
@@ -479,6 +492,38 @@ interface ThemedInput {
 }
 declare function useThemedInput(options?: UseThemedInputOptions): ThemedInput;
 
+interface RecentValues {
+    /** The remembered values, most-recent-first (never longer than `max`; `[]` when storage is unavailable). */
+    recents: string[];
+    /** Fold a value into the list (trim / de-dupe / promote / cap) and persist. Empty values are ignored. */
+    remember: (value: string) => void;
+    /** Forget every remembered value for this key and clear it from storage. */
+    clear: () => void;
+}
+/**
+ * @param key logical name for this input's history (namespaced under `@dloizides/ui-forms:recent:`).
+ * @param max most-recent-first cap on remembered values. Default {@link DEFAULT_MAX_RECENTS}.
+ */
+declare function useRecentValues(key: string, max?: number): RecentValues;
+
+/**
+ * `recentValuesCore` — the pure + storage-facing internals of {@link useRecentValues}, kept out of
+ * the hook file so the list algebra (trim / de-dupe / promote / cap) and the `localStorage` access
+ * are each unit-testable in isolation.
+ *
+ * ## RN-web storage reality
+ *
+ * `ui-forms` runs on react-native-web, so a component using this may mount on web (where
+ * `window.localStorage` exists), on native (where it does NOT), or under SSR / a hardened browser
+ * where touching `window.localStorage` THROWS (disabled cookies, privacy mode, quota). Every access
+ * therefore goes through {@link getStorage}, which returns `null` rather than throwing, and every
+ * read/write is wrapped so a storage failure degrades to an in-memory-only no-op instead of
+ * exploding inside render. On native / when storage is unavailable the feature is simply inert and
+ * the recents list is always `[]`.
+ */
+/** Default cap on remembered values (most-recent-first). */
+declare const DEFAULT_MAX_RECENTS = 10;
+
 /**
  * Chip/pill selector for selecting one or multiple options.
  *
@@ -737,12 +782,13 @@ declare function DateRangeControl({ value, onChange, onSubmit, fromLabel, toLabe
 /**
  * `AnchoredMenu` — the floating option list shared by `SelectControl` and `TypeaheadControl`.
  *
- * By default it renders an in-tree, absolutely-positioned popover under its anchor
- * (`position:absolute; top:100%; zIndex; elevation`). Set {@link AnchoredMenuProps.usePortal} to
- * render it — on web only — in a PORTAL to `document.body` with `position: fixed` at the trigger's
- * measured rect instead: that escapes react-native-web's trapped `z-index: 0` stacking contexts and
- * any ancestor `overflow: hidden`, so the menu is never painted under / clipped by later siblings
- * (the fix for the Country typeahead menu that hid behind the content below it). See {@link menuPortal}.
+ * By DEFAULT (web) it renders in a PORTAL to `document.body` with `position: fixed` at the trigger's
+ * measured rect: that escapes react-native-web's trapped `z-index: 0` stacking contexts and any
+ * ancestor `overflow: hidden`, so the menu is never painted under / clipped by later siblings (a
+ * table, a card, the next filter field). On native, and when {@link AnchoredMenuProps.usePortal} is
+ * explicitly `false`, it renders an in-tree, absolutely-positioned popover under its anchor
+ * (`position:absolute; top:100%; zIndex; elevation`) — which is exactly what left `SelectControl`'s
+ * menu hidden behind the attendee table until the default flipped. See {@link menuPortal}.
  * 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.
  *
@@ -769,6 +815,12 @@ interface AnchoredMenuProps {
     colors: AnchoredMenuColors;
     /** PRE-LOCALIZED accessibility hint applied to every option. */
     optionHint: string;
+    /**
+     * PRE-LOCALIZED accessible NAME for the menu container itself (e.g. "Recent values"). Optional and
+     * additive — omitted, the menu keeps only its `role="menu"` as before, so existing callers are
+     * unaffected. Supplied, a screen reader announces the list's purpose, not just "menu".
+     */
+    accessibilityLabel?: 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. */
@@ -777,12 +829,17 @@ interface AnchoredMenuProps {
      * On web, render the popover in a portal to `document.body` with `position: fixed` at the anchor's
      * measured rect, so it escapes react-native-web's trapped stacking contexts and any ancestor
      * `overflow: hidden` (the fix for a menu that paints under / is clipped by the content below it).
-     * No effect on native. Default `false` — the existing in-tree behaviour, so `SelectControl`
-     * usages are unchanged; `TypeaheadControl` opts in.
+     * No effect on native (the `IS_WEB` guard keeps native in-tree regardless).
+     *
+     * Default `true` — portalling is the CORRECT default: an in-tree popover is always at risk of
+     * being painted under a later-painting sibling (a table, a card, the next filter field). The old
+     * default was `false`, which silently left `SelectControl`'s menu hidden behind the attendee table
+     * (a recurrence of the exact bug this mechanism fixed for `TypeaheadControl`). Pass `usePortal={false}`
+     * only for the rare case that genuinely wants the menu clipped to its container.
      */
     usePortal?: boolean;
 }
-declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, testID, anchorRef, usePortal, }: AnchoredMenuProps): React.ReactElement;
+declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, accessibilityLabel, testID, anchorRef, usePortal, }: AnchoredMenuProps): React.ReactElement;
 
 declare const controlStyles: {
     /**
@@ -887,4 +944,4 @@ declare function suggestOptions(options: readonly ControlOption[], query: string
 /** True when `text` is non-empty yet matches no option's value or label exactly (case-insensitive). */
 declare function isUnmatched(options: readonly ControlOption[], text: string): boolean;
 
-export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, type ChipVariant, type ControlOption, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, type DateRangeControlProps, type DateRangeValue, Field, type FieldChildContext, type FieldChildren, type FieldLabelVariant, type FieldMarker, type FieldProps, type FieldSpacing, FormActions, type FormActionsProps, FormCell, type FormCellProps, FormCheckbox, type FormCheckboxProps, FormField, type FormFieldProps, FormGrid, type FormGridProps, FormSection, type FormSectionProps, FormSwitch, type FormSwitchProps, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useThemedInput };
+export { AnchoredMenu, type AnchoredMenuColors, type AnchoredMenuProps, type ChipOption, ChipSelector, type ChipSelectorProps, 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 RecentValues, SelectControl, type SelectControlProps, type ThemedInput, ThemedTextInput, type ThemedTextInputProps, TypeaheadControl, type TypeaheadControlProps, type UseThemedInputOptions, controlStyles, isUnmatched, suggestOptions, useRecentValues, useThemedInput };