index.d.ts 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353
  1. import * as i0 from '@angular/core';
  2. import { OnDestroy, AfterContentInit, QueryList, NgZone, ChangeDetectorRef } from '@angular/core';
  3. import { H as Highlightable, A as ActiveDescendantKeyManager } from '../activedescendant-key-manager.d-Bjic5obv.js';
  4. import { L as ListKeyManagerOption } from '../list-key-manager.d-BlK3jyRn.js';
  5. import { Subject } from 'rxjs';
  6. import { S as SelectionModel } from '../selection-model.d-C_vvNGP-.js';
  7. import { ControlValueAccessor } from '@angular/forms';
  8. /**
  9. * An implementation of SelectionModel that internally always represents the selection as a
  10. * multi-selection. This is necessary so that we can recover the full selection if the user
  11. * switches the listbox from single-selection to multi-selection after initialization.
  12. *
  13. * This selection model may report multiple selected values, even if it is in single-selection
  14. * mode. It is up to the user (CdkListbox) to check for invalid selections.
  15. */
  16. declare class ListboxSelectionModel<T> extends SelectionModel<T> {
  17. multiple: boolean;
  18. constructor(multiple?: boolean, initiallySelectedValues?: T[], emitChanges?: boolean, compareWith?: (o1: T, o2: T) => boolean);
  19. isMultipleSelection(): boolean;
  20. select(...values: T[]): boolean | void;
  21. }
  22. /** A selectable option in a listbox. */
  23. declare class CdkOption<T = unknown> implements ListKeyManagerOption, Highlightable, OnDestroy {
  24. /** The id of the option's host element. */
  25. get id(): string;
  26. set id(value: string);
  27. private _id;
  28. private _generatedId;
  29. /** The value of this option. */
  30. value: T;
  31. /**
  32. * The text used to locate this item during listbox typeahead. If not specified,
  33. * the `textContent` of the item will be used.
  34. */
  35. typeaheadLabel: string | null;
  36. /** Whether this option is disabled. */
  37. get disabled(): boolean;
  38. set disabled(value: boolean);
  39. private _disabled;
  40. /** The tabindex of the option when it is enabled. */
  41. get enabledTabIndex(): number | null | undefined;
  42. set enabledTabIndex(value: number | null | undefined);
  43. private _enabledTabIndex;
  44. /** The option's host element */
  45. readonly element: HTMLElement;
  46. /** The parent listbox this option belongs to. */
  47. protected readonly listbox: CdkListbox<T>;
  48. /** Emits when the option is destroyed. */
  49. protected destroyed: Subject<void>;
  50. /** Emits when the option is clicked. */
  51. readonly _clicked: Subject<MouseEvent>;
  52. ngOnDestroy(): void;
  53. /** Whether this option is selected. */
  54. isSelected(): boolean;
  55. /** Whether this option is active. */
  56. isActive(): boolean;
  57. /** Toggle the selected state of this option. */
  58. toggle(): void;
  59. /** Select this option if it is not selected. */
  60. select(): void;
  61. /** Deselect this option if it is selected. */
  62. deselect(): void;
  63. /** Focus this option. */
  64. focus(): void;
  65. /** Get the label for this element which is required by the FocusableOption interface. */
  66. getLabel(): string;
  67. /**
  68. * No-op implemented as a part of `Highlightable`.
  69. * @docs-private
  70. */
  71. setActiveStyles(): void;
  72. /**
  73. * No-op implemented as a part of `Highlightable`.
  74. * @docs-private
  75. */
  76. setInactiveStyles(): void;
  77. /** Handle focus events on the option. */
  78. protected _handleFocus(): void;
  79. /** Get the tabindex for this option. */
  80. protected _getTabIndex(): number | null | undefined;
  81. static ɵfac: i0.ɵɵFactoryDeclaration<CdkOption<any>, never>;
  82. static ɵdir: i0.ɵɵDirectiveDeclaration<CdkOption<any>, "[cdkOption]", ["cdkOption"], { "id": { "alias": "id"; "required": false; }; "value": { "alias": "cdkOption"; "required": false; }; "typeaheadLabel": { "alias": "cdkOptionTypeaheadLabel"; "required": false; }; "disabled": { "alias": "cdkOptionDisabled"; "required": false; }; "enabledTabIndex": { "alias": "tabindex"; "required": false; }; }, {}, never, never, true, never>;
  83. static ngAcceptInputType_disabled: unknown;
  84. }
  85. declare class CdkListbox<T = unknown> implements AfterContentInit, OnDestroy, ControlValueAccessor {
  86. private _cleanupWindowBlur;
  87. /** The id of the option's host element. */
  88. get id(): string;
  89. set id(value: string);
  90. private _id;
  91. private _generatedId;
  92. /** The tabindex to use when the listbox is enabled. */
  93. get enabledTabIndex(): number | null | undefined;
  94. set enabledTabIndex(value: number | null | undefined);
  95. private _enabledTabIndex;
  96. /** The value selected in the listbox, represented as an array of option values. */
  97. get value(): readonly T[];
  98. set value(value: readonly T[]);
  99. /**
  100. * Whether the listbox allows multiple options to be selected. If the value switches from `true`
  101. * to `false`, and more than one option is selected, all options are deselected.
  102. */
  103. get multiple(): boolean;
  104. set multiple(value: boolean);
  105. /** Whether the listbox is disabled. */
  106. get disabled(): boolean;
  107. set disabled(value: boolean);
  108. private _disabled;
  109. /** Whether the listbox will use active descendant or will move focus onto the options. */
  110. get useActiveDescendant(): boolean;
  111. set useActiveDescendant(value: boolean);
  112. private _useActiveDescendant;
  113. /** The orientation of the listbox. Only affects keyboard interaction, not visual layout. */
  114. get orientation(): "horizontal" | "vertical";
  115. set orientation(value: 'horizontal' | 'vertical');
  116. private _orientation;
  117. /** The function used to compare option values. */
  118. get compareWith(): undefined | ((o1: T, o2: T) => boolean);
  119. set compareWith(fn: undefined | ((o1: T, o2: T) => boolean));
  120. /**
  121. * Whether the keyboard navigation should wrap when the user presses arrow down on the last item
  122. * or arrow up on the first item.
  123. */
  124. get navigationWrapDisabled(): boolean;
  125. set navigationWrapDisabled(wrap: boolean);
  126. private _navigationWrapDisabled;
  127. /** Whether keyboard navigation should skip over disabled items. */
  128. get navigateDisabledOptions(): boolean;
  129. set navigateDisabledOptions(skip: boolean);
  130. private _navigateDisabledOptions;
  131. /** Emits when the selected value(s) in the listbox change. */
  132. readonly valueChange: Subject<ListboxValueChangeEvent<T>>;
  133. /** The child options in this listbox. */
  134. protected options: QueryList<CdkOption<T>>;
  135. /** The selection model used by the listbox. */
  136. protected selectionModel: ListboxSelectionModel<T>;
  137. /** The key manager that manages keyboard navigation for this listbox. */
  138. protected listKeyManager: ActiveDescendantKeyManager<CdkOption<T>>;
  139. /** Emits when the listbox is destroyed. */
  140. protected readonly destroyed: Subject<void>;
  141. /** The host element of the listbox. */
  142. protected readonly element: HTMLElement;
  143. /** The Angular zone. */
  144. protected readonly ngZone: NgZone;
  145. /** The change detector for this listbox. */
  146. protected readonly changeDetectorRef: ChangeDetectorRef;
  147. /** Whether the currently selected value in the selection model is invalid. */
  148. private _invalid;
  149. /** The last user-triggered option. */
  150. private _lastTriggered;
  151. /** Callback called when the listbox has been touched */
  152. private _onTouched;
  153. /** Callback called when the listbox value changes */
  154. private _onChange;
  155. /** Emits when an option has been clicked. */
  156. private _optionClicked;
  157. /** The directionality of the page. */
  158. private readonly _dir;
  159. /** Whether the component is being rendered in the browser. */
  160. private readonly _isBrowser;
  161. /** A predicate that skips disabled options. */
  162. private readonly _skipDisabledPredicate;
  163. /** A predicate that does not skip any options. */
  164. private readonly _skipNonePredicate;
  165. /** Whether the listbox currently has focus. */
  166. private _hasFocus;
  167. /** A reference to the option that was active before the listbox lost focus. */
  168. private _previousActiveOption;
  169. constructor();
  170. ngAfterContentInit(): void;
  171. ngOnDestroy(): void;
  172. /**
  173. * Toggle the selected state of the given option.
  174. * @param option The option to toggle
  175. */
  176. toggle(option: CdkOption<T>): void;
  177. /**
  178. * Toggle the selected state of the given value.
  179. * @param value The value to toggle
  180. */
  181. toggleValue(value: T): void;
  182. /**
  183. * Select the given option.
  184. * @param option The option to select
  185. */
  186. select(option: CdkOption<T>): void;
  187. /**
  188. * Select the given value.
  189. * @param value The value to select
  190. */
  191. selectValue(value: T): void;
  192. /**
  193. * Deselect the given option.
  194. * @param option The option to deselect
  195. */
  196. deselect(option: CdkOption<T>): void;
  197. /**
  198. * Deselect the given value.
  199. * @param value The value to deselect
  200. */
  201. deselectValue(value: T): void;
  202. /**
  203. * Set the selected state of all options.
  204. * @param isSelected The new selected state to set
  205. */
  206. setAllSelected(isSelected: boolean): void;
  207. /**
  208. * Get whether the given option is selected.
  209. * @param option The option to get the selected state of
  210. */
  211. isSelected(option: CdkOption<T>): boolean;
  212. /**
  213. * Get whether the given option is active.
  214. * @param option The option to get the active state of
  215. */
  216. isActive(option: CdkOption<T>): boolean;
  217. /**
  218. * Get whether the given value is selected.
  219. * @param value The value to get the selected state of
  220. */
  221. isValueSelected(value: T): boolean;
  222. /**
  223. * Registers a callback to be invoked when the listbox's value changes from user input.
  224. * @param fn The callback to register
  225. * @docs-private
  226. */
  227. registerOnChange(fn: (value: readonly T[]) => void): void;
  228. /**
  229. * Registers a callback to be invoked when the listbox is blurred by the user.
  230. * @param fn The callback to register
  231. * @docs-private
  232. */
  233. registerOnTouched(fn: () => {}): void;
  234. /**
  235. * Sets the listbox's value.
  236. * @param value The new value of the listbox
  237. * @docs-private
  238. */
  239. writeValue(value: readonly T[]): void;
  240. /**
  241. * Sets the disabled state of the listbox.
  242. * @param isDisabled The new disabled state
  243. * @docs-private
  244. */
  245. setDisabledState(isDisabled: boolean): void;
  246. /** Focus the listbox's host element. */
  247. focus(): void;
  248. /**
  249. * Triggers the given option in response to user interaction.
  250. * - In single selection mode: selects the option and deselects any other selected option.
  251. * - In multi selection mode: toggles the selected state of the option.
  252. * @param option The option to trigger
  253. */
  254. protected triggerOption(option: CdkOption<T> | null): void;
  255. /**
  256. * Trigger the given range of options in response to user interaction.
  257. * Should only be called in multi-selection mode.
  258. * @param trigger The option that was triggered
  259. * @param from The start index of the options to toggle
  260. * @param to The end index of the options to toggle
  261. * @param on Whether to toggle the option range on
  262. */
  263. protected triggerRange(trigger: CdkOption<T> | null, from: number, to: number, on: boolean): void;
  264. /**
  265. * Sets the given option as active.
  266. * @param option The option to make active
  267. */
  268. _setActiveOption(option: CdkOption<T>): void;
  269. /** Called when the listbox receives focus. */
  270. protected _handleFocus(): void;
  271. /** Called when the user presses keydown on the listbox. */
  272. protected _handleKeydown(event: KeyboardEvent): void;
  273. /** Called when a focus moves into the listbox. */
  274. protected _handleFocusIn(): void;
  275. /**
  276. * Called when the focus leaves an element in the listbox.
  277. * @param event The focusout event
  278. */
  279. protected _handleFocusOut(event: FocusEvent): void;
  280. /** Get the id of the active option if active descendant is being used. */
  281. protected _getAriaActiveDescendant(): string | null | undefined;
  282. /** Get the tabindex for the listbox. */
  283. protected _getTabIndex(): number | null | undefined;
  284. /** Initialize the key manager. */
  285. private _initKeyManager;
  286. /** Focus the active option. */
  287. private _focusActiveOption;
  288. /**
  289. * Set the selected values.
  290. * @param value The list of new selected values.
  291. */
  292. private _setSelection;
  293. /** Sets the first selected option as first in the keyboard focus order. */
  294. private _setNextFocusToSelectedOption;
  295. /** Update the internal value of the listbox based on the selection model. */
  296. private _updateInternalValue;
  297. /**
  298. * Gets the index of the given value in the given list of options.
  299. * @param cache The cache of indices found so far
  300. * @param value The value to find
  301. * @return The index of the value in the options list
  302. */
  303. private _getIndexForValue;
  304. /**
  305. * Handle the user clicking an option.
  306. * @param option The option that was clicked.
  307. */
  308. private _handleOptionClicked;
  309. /** Verifies that no two options represent the same value under the compareWith function. */
  310. private _verifyNoOptionValueCollisions;
  311. /** Verifies that the option values are valid. */
  312. private _verifyOptionValues;
  313. /**
  314. * Coerces a value into an array representing a listbox selection.
  315. * @param value The value to coerce
  316. * @return An array
  317. */
  318. private _coerceValue;
  319. /**
  320. * Get the sublist of values that do not represent valid option values in this listbox.
  321. * @param values The list of values
  322. * @return The sublist of values that are not valid option values
  323. */
  324. private _getInvalidOptionValues;
  325. /** Get the index of the last triggered option. */
  326. private _getLastTriggeredIndex;
  327. static ɵfac: i0.ɵɵFactoryDeclaration<CdkListbox<any>, never>;
  328. static ɵdir: i0.ɵɵDirectiveDeclaration<CdkListbox<any>, "[cdkListbox]", ["cdkListbox"], { "id": { "alias": "id"; "required": false; }; "enabledTabIndex": { "alias": "tabindex"; "required": false; }; "value": { "alias": "cdkListboxValue"; "required": false; }; "multiple": { "alias": "cdkListboxMultiple"; "required": false; }; "disabled": { "alias": "cdkListboxDisabled"; "required": false; }; "useActiveDescendant": { "alias": "cdkListboxUseActiveDescendant"; "required": false; }; "orientation": { "alias": "cdkListboxOrientation"; "required": false; }; "compareWith": { "alias": "cdkListboxCompareWith"; "required": false; }; "navigationWrapDisabled": { "alias": "cdkListboxNavigationWrapDisabled"; "required": false; }; "navigateDisabledOptions": { "alias": "cdkListboxNavigatesDisabledOptions"; "required": false; }; }, { "valueChange": "cdkListboxValueChange"; }, ["options"], never, true, never>;
  329. static ngAcceptInputType_multiple: unknown;
  330. static ngAcceptInputType_disabled: unknown;
  331. static ngAcceptInputType_useActiveDescendant: unknown;
  332. static ngAcceptInputType_navigationWrapDisabled: unknown;
  333. static ngAcceptInputType_navigateDisabledOptions: unknown;
  334. }
  335. /** Change event that is fired whenever the value of the listbox changes. */
  336. interface ListboxValueChangeEvent<T> {
  337. /** The new value of the listbox. */
  338. readonly value: readonly T[];
  339. /** Reference to the listbox that emitted the event. */
  340. readonly listbox: CdkListbox<T>;
  341. /** Reference to the option that was triggered. */
  342. readonly option: CdkOption<T> | null;
  343. }
  344. declare class CdkListboxModule {
  345. static ɵfac: i0.ɵɵFactoryDeclaration<CdkListboxModule, never>;
  346. static ɵmod: i0.ɵɵNgModuleDeclaration<CdkListboxModule, never, [typeof CdkListbox, typeof CdkOption], [typeof CdkListbox, typeof CdkOption]>;
  347. static ɵinj: i0.ɵɵInjectorDeclaration<CdkListboxModule>;
  348. }
  349. export { CdkListbox, CdkListboxModule, CdkOption };
  350. export type { ListboxValueChangeEvent };