@cute-widgets/base 20.0.1

package/select/index.d.ts

@@ -0,0 +1,426 @@
+import { FocusOrigin } from '@angular/cdk/a11y';
+import { ScrollStrategy, Overlay, ConnectedPosition, CdkOverlayOrigin, CdkConnectedOverlay } from '@angular/cdk/overlay';
+import { ViewportRuler } from '@angular/cdk/scrolling';
+import * as i0 from '@angular/core';
+import { InjectionToken, DoCheck, NgZone, QueryList, ElementRef, EventEmitter, SimpleChanges } from '@angular/core';
+import { NgControl } from '@angular/forms';
+import { Subject, Observable } from 'rxjs';
+import * as i3 from '@cute-widgets/base/core/option';
+import { CuteOption, CuteOptgroup, CuteOptionSelectionChange } from '@cute-widgets/base/core/option';
+import { RelativeSize } from '@cute-widgets/base/core/types';
+import { CuteFormFieldControl, CuteFormField } from '@cute-widgets/base/form-field';
+import { ErrorStateMatcher } from '@cute-widgets/base/core/error';
+import { CuteInputDropdownControl } from '@cute-widgets/base/abstract';
+import { AnimationTriggerMetadata } from '@angular/animations';
+import * as i1 from '@angular/common';
+
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2025 CuteWidgets Team. All Rights Reserved.
+ *
+ * You may not use this file except in compliance with the License
+ * that can be found at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * This code is a modification of the `@angular/material` original
+ * code licensed under MIT-style License (https://angular.dev/license).
+ */
+
+/** Injection token that determines the scroll handling while a select is open. */
+declare const CUTE_SELECT_SCROLL_STRATEGY: InjectionToken<() => ScrollStrategy>;
+/** @docs-private */
+declare function CUTE_SELECT_SCROLL_STRATEGY_PROVIDER_FACTORY(overlay: Overlay): () => ScrollStrategy;
+/** Object that can be used to configure the default options for the select module. */
+interface CuteSelectConfig {
+    /** Whether option centering should be disabled. */
+    disableOptionCentering?: boolean;
+    /** Time to wait in milliseconds after the last keystroke before moving focus to an item. */
+    typeaheadDebounceInterval?: number;
+    /** Class or list of classes to be applied to the menu's overlay panel. */
+    overlayPanelClass?: string | string[];
+    /** Whether icon indicators should be hidden for single-selection. */
+    hideSingleSelectionIndicator?: boolean;
+    /**
+     * Width of the panel. If set to `auto`, the panel will match the trigger width.
+     * If set to _null_ or an empty string, the panel will grow to match the longest option's text.
+     */
+    panelWidth?: string | number | null;
+    /**
+     * Height of the panel. If set to `auto`, _null_ or an empty string, the panel will display all options.
+     * If height is not empty, its value is set as a maximum height of the panel with vertical scrolling set to `auto`.
+     */
+    panelHeight?: string | number | null;
+    /**
+     * Whether nullable options can be selected by default.
+     * See `CuteSelect.canSelectNullableOptions` for more information.
+     */
+    canSelectNullableOptions?: boolean;
+}
+/** Injection token that can be used to provide the default options the select module. */
+declare const CUTE_SELECT_CONFIG: InjectionToken<CuteSelectConfig>;
+/** @docs-private */
+declare const CUTE_SELECT_SCROLL_STRATEGY_PROVIDER: {
+    provide: InjectionToken<() => ScrollStrategy>;
+    deps: (typeof Overlay)[];
+    useFactory: typeof CUTE_SELECT_SCROLL_STRATEGY_PROVIDER_FACTORY;
+};
+/**
+ * Injection token that can be used to reference instances of `CuteSelectTrigger`. It serves as
+ * an alternative token to the actual `CuteSelectTrigger` class which could cause unnecessary
+ * retention of the class and its directive metadata.
+ */
+declare const CUTE_SELECT_TRIGGER: InjectionToken<CuteSelectTrigger>;
+/** Change event object that is emitted when the select value has changed. */
+declare class CuteSelectChange {
+    /** Reference to the select that emitted the change event. */
+    source: CuteSelect;
+    /** Current value of the select that emitted the event. */
+    value: any;
+    constructor(
+    /** Reference to the select that emitted the change event. */
+    source: CuteSelect, 
+    /** Current value of the select that emitted the event. */
+    value: any);
+}
+declare class CuteSelect extends CuteInputDropdownControl implements DoCheck, CuteFormFieldControl<any> {
+    protected _viewportRuler: ViewportRuler;
+    protected _ngZone: NgZone;
+    private _dir;
+    protected _parentFormField: CuteFormField | null;
+    ngControl: NgControl;
+    private _liveAnnouncer;
+    protected _defaultOptions: CuteSelectConfig | null;
+    /** All the defined select options. */
+    options: QueryList<CuteOption> | undefined;
+    /** All of the defined groups of options. */
+    optionGroups: QueryList<CuteOptgroup> | undefined;
+    /** User-supplied override of the trigger element. */
+    customTrigger: CuteSelectTrigger | undefined;
+    /**
+     * This position config ensures that the top "start" corner of the overlay
+     * is aligned with the top "start" of the origin by default (overlapping
+     * the trigger completely). If the panel cannot fit below the trigger, it
+     * will fall back to a position above the trigger.
+     */
+    _positions: ConnectedPosition[];
+    /** Scrolls a particular option into the view. */
+    _scrollOptionIntoView(index: number): void;
+    /** Generates unique identifier */
+    protected generateId(): string;
+    /** Called when the panel has been opened and the overlay has settled on its final position. */
+    private _positioningSettled;
+    /** Creates a change event object that should be emitted by the select. */
+    private _getChangeEvent;
+    /** Factory function used to create a scroll strategy for this select. */
+    private _scrollStrategyFactory;
+    /** Whether the overlay panel is open. */
+    private _panelOpen;
+    /** Comparison function to specify which option is displayed. Defaults to object equality. */
+    private _compareWith;
+    /** Current `aria-labelledby` value for the select trigger. */
+    private _triggerAriaLabelledBy;
+    /**
+     * Keeps track of the previous form control assigned to the select.
+     * Used to detect if it has changed.
+     */
+    private _previousControl;
+    /** Emits whenever the component is destroyed. */
+    protected readonly _destroy: Subject<void>;
+    /** Emits when the panel element is finished transforming in. */
+    protected readonly _panelDoneAnimatingStream: Subject<string>;
+    /** Tracks the error state of the select. */
+    private _errorStateTracker;
+    /** Disable the automatic labeling to avoid issues like #27241. */
+    readonly disableAutomaticLabeling = true;
+    /** Deals with the selection logic. */
+    private _selectionModel;
+    /** Manages keyboard events for options in the panel. */
+    private _keyManager;
+    /** Ideal origin for the overlay panel. */
+    protected _preferredOverlayOrigin: CdkOverlayOrigin | ElementRef | undefined;
+    /** Width of the overlay panel. */
+    protected _overlayWidth: string | number | undefined;
+    /** Strategy that will be used to handle scrolling while the select panel is open. */
+    protected _scrollStrategy: ScrollStrategy;
+    protected _overlayPanelClass: string | string[];
+    get expanded(): boolean;
+    /** Whether the select is focused. */
+    get focused(): boolean;
+    private _focused;
+    /** A name for this control that can be used by `cute-form-field`. */
+    controlType: string;
+    /** Implemented as part of CuteFormFieldControl. */
+    get controlElementRef(): ElementRef;
+    /** Trigger that opens the select. */
+    trigger: ElementRef | undefined;
+    /** Panel containing the select options. */
+    panel: ElementRef | undefined;
+    /** Overlay pane containing the options. */
+    protected _overlayDir: CdkConnectedOverlay | undefined;
+    /** Implemented as part of CuteFormFieldControl. */
+    userAriaDescribedBy: string | undefined;
+    /** Classes to be passed to the select panel. Supports the same syntax as `ngClass`. */
+    panelClass: string | string[] | Set<string> | {
+        [key: string]: any;
+    };
+    /** Whether ripples in the select are disabled. */
+    disableRipple: boolean;
+    /** Whether the checkmark indicator for single-selection options is hidden. */
+    get hideSingleSelectionIndicator(): boolean;
+    set hideSingleSelectionIndicator(value: boolean);
+    private _hideSingleSelectionIndicator;
+    /** Placeholder to be shown if no value has been selected. */
+    get placeholder(): string;
+    set placeholder(value: string);
+    private _placeholder;
+    /** Whether the component is required. */
+    get required(): boolean;
+    set required(value: boolean);
+    /** Whether the user should be allowed to select multiple options. */
+    get multiple(): boolean;
+    set multiple(value: boolean);
+    private _multiple;
+    /** Whether to center the active option over the trigger. */
+    disableOptionCentering: boolean;
+    /**
+     * Function to compare the option values with the selected values. The first argument
+     * is a value from an option. The second is a value from the selection. A boolean
+     * should be returned.
+     */
+    get compareWith(): (o1: any, o2: any) => boolean;
+    set compareWith(fn: (o1: any, o2: any) => boolean);
+    /** Value of the select control. */
+    get value(): any;
+    set value(newValue: any);
+    private _value;
+    /** Object used to control when error messages are shown. */
+    get errorStateMatcher(): ErrorStateMatcher;
+    set errorStateMatcher(value: ErrorStateMatcher);
+    /** Relative size of the select control */
+    magnitude: RelativeSize | undefined;
+    /** Time to wait in milliseconds after the last keystroke before moving focus to an item. */
+    typeaheadDebounceInterval: number;
+    /**
+     * Function used to sort the values in a select in multiple mode.
+     * Follows the same logic as `Array.prototype.sort`.
+     */
+    sortComparator: ((a: CuteOption, b: CuteOption, options: CuteOption[]) => number) | undefined;
+    /** Whether the select is in an error state. */
+    get errorState(): boolean;
+    set errorState(value: boolean);
+    /**
+     * Width of the panel. If set to `auto`, the panel will match the trigger width.
+     * If set to null or an empty string, the panel will grow to match the longest option's text.
+     */
+    panelWidth: string | number | null;
+    /**
+     * Height of the panel. If set to `auto`, _null_ or an empty string, the panel will display all options.
+     * If height is not empty, its value is set as a maximum height of the panel with vertical scrolling set to `auto`.
+     */
+    panelHeight: string | number | null;
+    /**
+     * By default, selecting an option with a `null` or `undefined` value will reset the select's
+     * value. Enable this option if the reset behavior doesn't match your requirements and instead,
+     * the nullable options should become selected. The value of this input can be controlled app-wide
+     * using the `MAT_SELECT_CONFIG` injection token.
+     */
+    canSelectNullableOptions: boolean;
+    /** Combined stream of all of the child options' change events. */
+    readonly optionSelectionChanges: Observable<CuteOptionSelectionChange>;
+    /** Event emitted when the select panel has been toggled. */
+    readonly openedChange: EventEmitter<boolean>;
+    /** Event emitted when the select has been opened. */
+    readonly _openedStream: Observable<void>;
+    /** Event emitted when the select has been closed. */
+    readonly _closedStream: Observable<void>;
+    /** Event emitted when the selected value has been changed by the user. */
+    readonly selectionChange: EventEmitter<CuteSelectChange>;
+    /**
+     * Event that emits whenever the raw value of the select changes. This is here primarily
+     * to facilitate the two-way binding for the `value` input.
+     */
+    readonly valueChange: EventEmitter<any>;
+    constructor(...args: unknown[]);
+    ngOnInit(): void;
+    ngAfterContentInit(): void;
+    ngDoCheck(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngOnDestroy(): void;
+    /** Toggles the overlay panel open or closed. */
+    toggle(): void;
+    /** Opens the overlay panel. */
+    open(): void;
+    /**
+     * Track which modal we have modified the `aria-owns` attribute of. When the combobox trigger is
+     * inside an aria-modal, we apply aria-owns to the parent modal with the `id` of the options
+     * panel. Track the modal we have changed so we can undo the changes on destroy.
+     */
+    private _trackedModal;
+    /**
+     * If the autocomplete trigger is inside of an `aria-modal` element, connect
+     * that modal to the options panel with `aria-owns`.
+     *
+     * For some browser + screen reader combinations, when navigation is inside
+     * of an `aria-modal` element, the screen reader treats everything outside
+     * of that modal as hidden or invisible.
+     *
+     * This causes a problem when the combobox trigger is _inside_ of a modal, because the
+     * options panel is rendered _outside_ of that modal, preventing screen reader navigation
+     * from reaching the panel.
+     *
+     * We can work around this issue by applying `aria-owns` to the modal with the `id` of
+     * the options panel. This effectively communicates to assistive technology that the
+     * options panel is part of the same interaction as the modal.
+     *
+     * At the time of this writing, this issue is present in VoiceOver.
+     * See https://github.com/angular/components/issues/20694
+     */
+    private _applyModalPanelOwnership;
+    /** Clears the reference to the listbox overlay element from the modal it was added to. */
+    private _clearFromModal;
+    /** Closes the overlay panel and focuses the host element. */
+    close(): void;
+    /**
+     * Sets the select' value. Part of the ControlValueAccessor interface
+     * required to integrate with Angular core forms API.
+     *
+     * @param value New value to be written to the model.
+     */
+    writeValue(value: any): void;
+    /** Whether the overlay panel is open. */
+    get panelOpen(): boolean;
+    /** The currently selected option. */
+    get selected(): CuteOption | CuteOption[];
+    /** The value displayed in the trigger. */
+    get triggerValue(): string;
+    /** Refreshes the error state of the select. */
+    updateErrorState(): void;
+    /** Whether the element is in RTL mode. */
+    _isRtl(): boolean;
+    /** Handles all keydown events on the select. */
+    _handleKeydown(event: KeyboardEvent): void;
+    /** Handles keyboard events while the select is closed. */
+    private _handleClosedKeydown;
+    /** Handles keyboard events when the selected is open. */
+    private _handleOpenKeydown;
+    _onFocus(): void;
+    /**
+     * Calls the touched callback only if the panel is closed. Otherwise, the trigger will
+     * "blur" to the panel when it opens, causing a false positive.
+     */
+    _onBlur(): void;
+    /**
+     * Callback that is invoked when the overlay panel has been attached.
+     */
+    _onAttached(): void;
+    /** Returns the theme to be used on the panel. */
+    _getPanelTheme(): string;
+    /** Whether the select has a value. */
+    get empty(): boolean;
+    private _initializeSelection;
+    /**
+     * Sets the selected option based on a value. If no option can be
+     * found with the designated value, the select trigger is cleared.
+     */
+    private _setSelectionByValue;
+    /**
+     * Finds and selects and option based on its value.
+     * @returns Option that has the corresponding value.
+     */
+    private _selectOptionByValue;
+    /** Assigns a specific value to the select. Returns whether the value has changed. */
+    private _assignValue;
+    private _skipPredicate;
+    /** Gets how wide the overlay panel should be. */
+    private _getOverlayWidth;
+    /** Syncs the parent state with the individual options. */
+    _syncParentProperties(): void;
+    /** Sets up a key manager to listen to keyboard events on the overlay panel. */
+    private _initKeyManager;
+    /** Drops current option subscriptions and IDs and resets from scratch. */
+    private _resetOptions;
+    /** Invoked when an option is clicked. */
+    private _onSelect;
+    /** Sorts the selected values in the selected based on their order in the panel. */
+    private _sortValues;
+    /** Emits change event to set the model value. */
+    private _propagateChanges;
+    /**
+     * Highlights the selected item. If no option is selected, it will highlight
+     * the first *enabled* option.
+     */
+    private _highlightCorrectOption;
+    /** Whether the panel is allowed to open. */
+    protected _canOpen(): boolean;
+    /** Focuses the select element. */
+    focus(origin?: FocusOrigin, options?: FocusOptions): void;
+    /** Gets the aria-labelledby for the select panel. */
+    _getPanelAriaLabelledby(): string | null;
+    /** Determines the `aria-activedescendant` to be set on the host. */
+    protected _getAriaActiveDescendant(): string | null;
+    /** Gets the aria-labelledby of the select component trigger. */
+    private _getTriggerAriaLabelledby;
+    /** Called when the overlay panel is done animating. */
+    protected _panelDoneAnimating(isOpen: boolean): void;
+    /**
+     * Implemented as part of CuteFormFieldControl.
+     */
+    setDescribedByIds(ids: string[]): void;
+    /**
+     * Implemented as part of CuteFormFieldControl.
+     */
+    onContainerClick(): void;
+    /**
+     * Implemented as part of CuteFormFieldControl.
+     */
+    get shouldLabelFloat(): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteSelect, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CuteSelect, "cute-select", ["cuteSelect"], { "userAriaDescribedBy": { "alias": "aria-describedby"; "required": false; }; "panelClass": { "alias": "panelClass"; "required": false; }; "disableRipple": { "alias": "disableRipple"; "required": false; }; "hideSingleSelectionIndicator": { "alias": "hideSingleSelectionIndicator"; "required": false; }; "placeholder": { "alias": "placeholder"; "required": false; }; "multiple": { "alias": "multiple"; "required": false; }; "disableOptionCentering": { "alias": "disableOptionCentering"; "required": false; }; "compareWith": { "alias": "compareWith"; "required": false; }; "value": { "alias": "value"; "required": false; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; }; "magnitude": { "alias": "magnitude"; "required": false; }; "typeaheadDebounceInterval": { "alias": "typeaheadDebounceInterval"; "required": false; }; "sortComparator": { "alias": "sortComparator"; "required": false; }; "panelWidth": { "alias": "panelWidth"; "required": false; }; "panelHeight": { "alias": "panelHeight"; "required": false; }; "canSelectNullableOptions": { "alias": "canSelectNullableOptions"; "required": false; }; }, { "openedChange": "openedChange"; "_openedStream": "opened"; "_closedStream": "closed"; "selectionChange": "selectionChange"; "valueChange": "valueChange"; }, ["customTrigger", "options", "optionGroups"], ["cute-select-trigger", "*"], true, never>;
+    static ngAcceptInputType_disableRipple: unknown;
+    static ngAcceptInputType_hideSingleSelectionIndicator: unknown;
+    static ngAcceptInputType_multiple: unknown;
+    static ngAcceptInputType_disableOptionCentering: unknown;
+    static ngAcceptInputType_typeaheadDebounceInterval: unknown;
+    static ngAcceptInputType_canSelectNullableOptions: unknown;
+}
+/**
+ * Allows the user to customize the trigger that is displayed when the select has a value.
+ */
+declare class CuteSelectTrigger {
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteSelectTrigger, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CuteSelectTrigger, "cute-select-trigger", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2025 CuteWidgets Team. All Rights Reserved.
+ *
+ * You may not use this file except in compliance with the License
+ * that can be found at http://www.apache.org/licenses/LICENSE-2.0
+ */
+
+/**
+ * The following are all the animations for the mat-select component, with each
+ * const containing the metadata for one animation.
+ *
+ * The values below match the implementation of the AngularJS Material mat-select animation.
+ * @docs-private
+ */
+declare const cuteSelectAnimations: {
+    /**
+     * @deprecated No longer being used. To be removed.
+     * @breaking-change 12.0.0
+     */
+    readonly transformPanelWrap: AnimationTriggerMetadata;
+    readonly transformPanel: AnimationTriggerMetadata;
+};
+
+declare class CuteSelectModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteSelectModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<CuteSelectModule, never, [typeof i1.CommonModule, typeof CuteSelect, typeof CuteSelectTrigger, typeof i3.CuteOptgroup, typeof i3.CuteOption], [typeof CuteSelect, typeof CuteSelectTrigger, typeof i3.CuteOptgroup, typeof i3.CuteOption]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<CuteSelectModule>;
+}
+
+export { CUTE_SELECT_CONFIG, CUTE_SELECT_SCROLL_STRATEGY, CUTE_SELECT_SCROLL_STRATEGY_PROVIDER, CUTE_SELECT_SCROLL_STRATEGY_PROVIDER_FACTORY, CUTE_SELECT_TRIGGER, CuteSelect, CuteSelectChange, CuteSelectModule, CuteSelectTrigger, cuteSelectAnimations };
+export type { CuteSelectConfig };