@dloizides/ui-forms 1.13.4 → 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.
  *
@@ -770,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. */
@@ -788,7 +839,7 @@ interface AnchoredMenuProps {
      */
     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: {
     /**
@@ -893,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.
  *
@@ -770,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. */
@@ -788,7 +839,7 @@ interface AnchoredMenuProps {
      */
     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: {
     /**
@@ -893,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 };