quang 19.3.15-2 → 19.3.15-3

package/components/autocomplete/README.md

@@ -5,16 +5,19 @@ The `QuangAutocompleteComponent` is a comprehensive autocomplete input with real
 ## Inputs
 
 - `selectOptions`: `SelectOption[]` — Array of available options for selection. Each option should have `value` and `label` properties. **(Required)**
+- `allowFreeText`: `boolean` — When true, allows any text input as a valid form value, not just option values. The form value will sync with whatever text the user types. When false, the form value must match one of the option values. Default: `false`
+- `autoSelectOnExactMatch`: `boolean` — When true and `allowFreeText` is false, automatically selects an option if the user's input text matches an option's label exactly (case-insensitive, trimmed). This provides a better UX by auto-selecting when users type a complete option label. Default: `true`
+- `updateValueOnType`: `boolean` — When true, updates the form value as the user types (after debounce). When false, the form value is only updated when the user selects an option from the dropdown or when the input loses focus (blur). Default: `false`
 - `multiple`: `boolean` — Enable multiple selection mode with chip display. Default: `false`
 - `multiSelectDisplayMode`: `'vertical' | 'horizontal'` — Layout direction for chips in multiple mode. Horizontal mode includes scroll support. Default: `'vertical'`
 - `chipMaxLength`: `number` — Maximum character length for chip labels. Longer labels will be truncated with ellipsis. Default: `0` (no limit)
-- `syncFormWithText`: `boolean` — Synchronize form control value with input text as user types. Useful for free-text input with suggestions. Default: `false`
 - `optionListMaxHeight`: `string` — Maximum height for dropdown option list with CSS units. Default: `'200px'`
 - `translateValue`: `boolean` — Enable translation of option values through QuangTranslationService. Default: `true`
 - `scrollBehaviorOnOpen`: `ScrollBehavior` — Scroll behavior when opening dropdown ('smooth' or 'instant'). Default: `'smooth'`
 - `emitOnly`: `boolean` — Only emit selection events without updating form control. Useful for read-only suggestion display. Default: `false`
 - `searchTextDebounce`: `number` — Debounce delay in milliseconds for search input to optimize performance. Default: `300`
 - `internalFilterOptions`: `boolean` — Use built-in filtering logic. Disable for custom external filtering via searchTextChange event. Default: `true`
+- `syncFormWithText`: `boolean` — **@deprecated** Use `allowFreeText` instead. Synchronize form control value with input text as user types. Default: `false`
 - `isReadonly`: `boolean` — Set component to read-only mode. Inherited from `QuangBaseComponent`
 - `componentLabel`: `string` — Label text for the component. Inherited from `QuangBaseComponent`
 - `componentPlaceholder`: `string` — Placeholder text for the input. Inherited from `QuangBaseComponent`

package/components/autocomplete/autocomplete.component.d.ts

@@ -1,71 +1,263 @@
-import { Subscription } from 'rxjs';
 import { OptionListParentType, QuangBaseComponent, QuangOptionListComponent, SelectOption } from 'quang/components/shared';
 import * as i0 from "@angular/core";
+/**
+ * Autocomplete component for providing suggestion options {@link SelectOption} as the user types.
+ *
+ * @usageNotes
+ * This component displays a list of filtered options based on user input.
+ * It allows users to select an option from the suggestions and emits the event `selectedOption` when an option is selected.
+ *
+ * `searchTextDebounce` is by default set to 300ms.
+ */
 export declare class QuangAutocompleteComponent extends QuangBaseComponent<string | number | string[] | number[]> {
+    /**
+     * The list of options to display in the autocomplete dropdown.
+     */
+    selectOptions: import("@angular/core").InputSignal<SelectOption[]>;
+    /**
+     * When true, allows any text input as a valid form value, not just option values.
+     * The form value will sync with whatever text the user types.
+     * When false (default), the form value must match one of the option values.
+     * @default false
+     */
+    allowFreeText: import("@angular/core").InputSignal<boolean>;
+    /**
+     * When true and allowFreeText is false, automatically selects an option if the user's
+     * input text matches an option's label exactly (case-insensitive, trimmed).
+     * This provides a better UX by auto-selecting when users type a complete option label.
+     * @default true
+     */
+    autoSelectOnExactMatch: import("@angular/core").InputSignal<boolean>;
+    /**
+     * When true, updates the form value as the user types (after debounce).
+     * When false (default), the form value is only updated when:
+     * - User selects an option from the dropdown
+     * - User stops typing and the input loses focus (blur)
+     * @default false
+     */
+    updateValueOnType: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Whether the form value can be any text or must match one of the options.
+     * When true, the form value syncs with the input text.
+     * When false (default), the form value must be one of the option values.
+     * @default false
+     * @deprecated Use `allowFreeText` instead. This input will be removed in a future version.
+     */
     syncFormWithText: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Maximum height of the option list before scrolling.
+     * @default '200px'
+     */
     optionListMaxHeight: import("@angular/core").InputSignal<string>;
-    selectOptions: import("@angular/core").InputSignal<SelectOption[]>;
+    /**
+     * Whether to translate option labels.
+     * @default true
+     */
     translateValue: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Scroll behavior when the option list opens.
+     * @default 'smooth'
+     */
     scrollBehaviorOnOpen: import("@angular/core").InputSignal<ScrollBehavior>;
     /**
-     * Only emits the value without saving it in ngControl
+     * When true, only emits the value without saving it to ngControl.
+     * @default false
      */
     emitOnly: import("@angular/core").InputSignal<boolean>;
+    /**
+     * Enable multiple selection mode with chips.
+     * @default false
+     */
     multiple: import("@angular/core").InputSignal<boolean>;
     /**
-     * Set the maximum length in characters of the single chip.
+     * Maximum length in characters for chip display text.
+     * When set, chips will be truncated and show a tooltip with full text.
+     * @default 0 (no limit)
      */
     chipMaxLength: import("@angular/core").InputSignal<number>;
+    /**
+     * Layout direction for chips in multiple selection mode.
+     * @default 'vertical'
+     */
     multiSelectDisplayMode: import("@angular/core").InputSignal<"vertical" | "horizontal">;
-    optionList: import("@angular/core").Signal<QuangOptionListComponent | undefined>;
-    _showOptions: import("@angular/core").WritableSignal<boolean | null>;
-    _inputValue: import("@angular/core").WritableSignal<string>;
-    _optionHideTimeout: import("@angular/core").WritableSignal<any>;
-    _chipList: import("@angular/core").WritableSignal<string[]>;
-    _selectedOptions: import("@angular/core").WritableSignal<SelectOption[]>;
-    selectOptionsChange: Subscription;
-    _filteredOptions: import("@angular/core").Signal<SelectOption[]>;
-    selectedOption: import("@angular/core").OutputEmitterRef<string | number | null>;
-    searchTextChange: import("@angular/core").OutputEmitterRef<string>;
+    /**
+     * Debounce time in milliseconds for search text changes.
+     * @default 300
+     */
     searchTextDebounce: import("@angular/core").InputSignal<number>;
+    /**
+     * Whether to filter options internally based on input text.
+     * When false, filtering should be handled externally via searchTextChange event.
+     * @default true
+     */
     internalFilterOptions: import("@angular/core").InputSignal<boolean>;
-    readonly ParentType = OptionListParentType.AUTOCOMPLETE;
-    formValueChange$: Subscription | undefined;
+    /**
+     * Emitted when an option is selected.
+     * Emits the selected option's value, or null when cleared.
+     */
+    selectedOption: import("@angular/core").OutputEmitterRef<string | number | null>;
+    /**
+     * Emitted when the search text changes (after debounce).
+     * Useful for external filtering or API calls.
+     */
+    searchTextChange: import("@angular/core").OutputEmitterRef<string>;
+    /** Reference to the option list component */
+    protected readonly optionList: import("@angular/core").Signal<QuangOptionListComponent | undefined>;
+    /** Reference to the input element */
     private readonly selectInput;
+    /** Reference to the chip container element */
     private readonly chipContainer;
+    /** Reference to the main autocomplete container */
     private readonly autocompleteContainer;
-    inputHeight: import("@angular/core").WritableSignal<number>;
+    /** Constant for option list parent type */
+    readonly ParentType = OptionListParentType.AUTOCOMPLETE;
+    /** Height of the input element (used for positioning) */
+    readonly inputHeight: import("@angular/core").WritableSignal<number>;
+    /**
+     * The display text for the input field.
+     * - When searching: shows what the user typed
+     * - When allowFreeText/syncFormWithText is true and no matching option: shows the raw value
+     * - When not searching: shows the selected option's label (derived from _value)
+     */
+    readonly _inputValue: import("@angular/core").Signal<string>;
+    /** Whether the option list is currently visible */
+    readonly _showOptions: import("@angular/core").WritableSignal<boolean | null>;
+    /** List of selected chip values (for multiple mode) */
+    readonly _chipList: import("@angular/core").WritableSignal<string[]>;
+    /** List of selected option objects (for multiple mode) */
+    readonly _selectedOptions: import("@angular/core").WritableSignal<SelectOption[]>;
+    /** Filtered options based on search text and chip selection */
+    readonly _filteredOptions: import("@angular/core").Signal<SelectOption[]>;
+    /**
+     * The value to use for highlighting in the option list.
+     * When searching: shows the matched option (if any) based on exact label match
+     * When not searching: shows the current form value
+     * This keeps highlighting in sync with what will be selected on blur.
+     */
+    readonly _highlightedValue: import("@angular/core").Signal<string | number | string[] | number[] | null>;
+    /** Whether the user is actively typing/searching */
+    protected readonly _isSearching: import("@angular/core").WritableSignal<boolean>;
+    /** The text the user is currently typing while searching */
+    protected readonly _userSearchText: import("@angular/core").WritableSignal<string>;
+    /**
+     * Internal computed that returns true if free text input is allowed.
+     * Combines both `allowFreeText` and deprecated `syncFormWithText` inputs.
+     */
+    protected readonly _allowFreeTextInternal: import("@angular/core").Signal<boolean>;
+    /**
+     * Finds an option whose label exactly matches the given text (case-insensitive, trimmed).
+     * @param text The text to match against option labels
+     * @returns The matching option, or undefined if no match
+     */
+    protected findMatchingOption(text: string | null | undefined): SelectOption | undefined;
+    /** Timer for search text debounce */
     private _searchDebounceTimer;
+    /** Last emitted search text (for distinctUntilChanged behavior) */
     private _lastEmittedSearchText;
+    /** Whether the component has been destroyed */
     private _isDestroyed;
-    private readonly onChangeSelectInput;
+    /** Subscription to form value changes */
+    private formValueChangeSubscription;
+    /** Effect to handle input element setup and keyboard events */
+    private readonly onChangeSelectInputEffect;
+    /** Subscription to options changes */
+    private readonly selectOptionsChangeSubscription;
+    /** Subscription to show options changes */
+    private readonly showOptionsChangeSubscription;
     constructor();
+    setupFormControl(): void;
+    writeValue(val: string | number | string[] | number[]): void;
+    onChangedHandler(value: string | number | string[] | number[]): void;
+    onBlurHandler(): void;
     /**
-     * Handle debounced search text change emission
-     * @param value The input value to emit after debounce
+     * Shows the option list dropdown.
      */
-    private emitDebouncedSearchText;
-    setupFormControl(): void;
     showOptionVisibility(): void;
-    hideOptionVisibility(skipTimeout?: boolean): void;
+    /**
+     * Hides the option list dropdown.
+     */
+    hideOptionVisibility(): void;
+    /**
+     * Handles input text changes (typing).
+     * @param event The input event
+     */
     onChangeInput(event: Event): void;
-    filterOptions(value: string): SelectOption[];
-    onChangedHandler(value: string | number | string[] | number[]): void;
+    /**
+     * Handles option selection from the dropdown.
+     * @param value The selected option's value
+     * @param hideOptions Whether to hide the dropdown after selection
+     */
     onValueChange(value: string | number, hideOptions?: boolean): void;
-    checkInputValue(): void;
-    writeValue(val: string | number | string[] | number[]): void;
+    /**
+     * Handles input blur event.
+     * @param event The focus event
+     */
     onBlurInput(event: FocusEvent): void;
-    onBlurHandler(): void;
-    onBlurOptionList(event: any): void;
-    setInputValue(resetOnMiss?: boolean): void;
-    getDescription(chip: any): string;
-    onSelectValue(value: any): void;
     /**
-     * remove chip from chips list
-     * @param chipValue chip to delete
+     * Handles blur event on the option list.
+     * @param event The blur event (truthy if should hide)
+     */
+    onBlurOptionList(event: FocusEvent | boolean): void;
+    /**
+     * Gets the display description for a chip value.
+     * @param chipValue The chip's value
+     * @returns The chip's display label
+     */
+    getDescription(chipValue: string | number): string;
+    /**
+     * Removes a chip from the selection (multiple mode).
+     * @param chipValue The chip value to remove
+     */
+    deleteChip(chipValue: string | number): void;
+    /**
+     * Filters options based on input text.
+     * @param value The search text
+     * @returns Filtered options
+     */
+    protected filterOptions(value: string): SelectOption[];
+    /**
+     * Core method that processes text input and updates form value accordingly.
+     *
+     * Matching logic:
+     * - If text matches an option label (case-insensitive, trimmed) and autoSelectOnExactMatch is true, select that option
+     * - If no match and allowFreeText is true, use the typed text as value
+     * - If no match and allowFreeText is false, clear the value
+     *
+     * @param text The text to process
+     * @param options Configuration options:
+     *   - exitSearchMode: If true, uses onChangedHandler which exits search mode. If false, stays in search mode.
+     *   - updateOnMatch: If true, updates form when match found. If false, only clears on no-match.
+     *   - clearSearchText: If true, clears _userSearchText after processing.
+     */
+    private processTextToFormValue;
+    /**
+     * Handles keyboard events on the input element.
+     */
+    private handleInputKeydown;
+    /**
+     * Handles changes to the select options input.
+     */
+    private handleOptionsChange;
+    /**
+     * Handles form value changes from external sources.
+     */
+    private handleFormValueChange;
+    /**
+     * Handles selecting a value (adding to chip list in multiple mode).
+     */
+    private handleSelectValue;
+    /**
+     * Emits search text change after debounce.
+     * When `updateValueOnType` is true, also updates the form value using the same
+     * matching logic as checkInputValue (auto-select matching options, or use free text).
+     */
+    private emitDebouncedSearchText;
+    /**
+     * Updates the form value and internal _value signal without exiting search mode.
+     * This is used when clearing the value during typing - we want to update the form
+     * but keep the user in search mode so they can continue typing.
      */
-    deleteChip(chipValue: any): void;
-    createChipList(chip: any): void;
+    private updateValueWithoutExitingSearchMode;
     static ɵfac: i0.ɵɵFactoryDeclaration<QuangAutocompleteComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<QuangAutocompleteComponent, "quang-autocomplete", never, { "syncFormWithText": { "alias": "syncFormWithText"; "required": false; "isSignal": true; }; "optionListMaxHeight": { "alias": "optionListMaxHeight"; "required": false; "isSignal": true; }; "selectOptions": { "alias": "selectOptions"; "required": true; "isSignal": true; }; "translateValue": { "alias": "translateValue"; "required": false; "isSignal": true; }; "scrollBehaviorOnOpen": { "alias": "scrollBehaviorOnOpen"; "required": false; "isSignal": true; }; "emitOnly": { "alias": "emitOnly"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "chipMaxLength": { "alias": "chipMaxLength"; "required": false; "isSignal": true; }; "multiSelectDisplayMode": { "alias": "multiSelectDisplayMode"; "required": false; "isSignal": true; }; "searchTextDebounce": { "alias": "searchTextDebounce"; "required": false; "isSignal": true; }; "internalFilterOptions": { "alias": "internalFilterOptions"; "required": false; "isSignal": true; }; }, { "selectedOption": "selectedOption"; "searchTextChange": "searchTextChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<QuangAutocompleteComponent, "quang-autocomplete", never, { "selectOptions": { "alias": "selectOptions"; "required": true; "isSignal": true; }; "allowFreeText": { "alias": "allowFreeText"; "required": false; "isSignal": true; }; "autoSelectOnExactMatch": { "alias": "autoSelectOnExactMatch"; "required": false; "isSignal": true; }; "updateValueOnType": { "alias": "updateValueOnType"; "required": false; "isSignal": true; }; "syncFormWithText": { "alias": "syncFormWithText"; "required": false; "isSignal": true; }; "optionListMaxHeight": { "alias": "optionListMaxHeight"; "required": false; "isSignal": true; }; "translateValue": { "alias": "translateValue"; "required": false; "isSignal": true; }; "scrollBehaviorOnOpen": { "alias": "scrollBehaviorOnOpen"; "required": false; "isSignal": true; }; "emitOnly": { "alias": "emitOnly"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "chipMaxLength": { "alias": "chipMaxLength"; "required": false; "isSignal": true; }; "multiSelectDisplayMode": { "alias": "multiSelectDisplayMode"; "required": false; "isSignal": true; }; "searchTextDebounce": { "alias": "searchTextDebounce"; "required": false; "isSignal": true; }; "internalFilterOptions": { "alias": "internalFilterOptions"; "required": false; "isSignal": true; }; }, { "selectedOption": "selectedOption"; "searchTextChange": "searchTextChange"; }, never, never, true, never>;
 }