@esri/calcite-components

/// <reference path="../../index.d.ts" /> import type { PublicLitElement as LitElement } from "@arcgis/lumina"; import type { FlipPlacement, LogicalPlacement, OverlayPositioning } from "../../utils/floating-ui.js"; import type { MutableValidityState } from "../../utils/form.js"; import type { Scale, SelectionMode, Status } from "../interfaces.js"; import type { IconName } from "../calcite-icon/interfaces.js"; import type { ComboboxItem as HTMLCalciteComboboxItemElement } from "../calcite-combobox-item/customElement.js"; import type { SelectionDisplay } from "./interfaces.js"; /** * @cssproperty [--calcite-combobox-divider-color] - Specifies the component's divider color. * @cssproperty [--calcite-combobox-icon-color] - Specifies the component's icon color. * @cssproperty [--calcite-combobox-icon-color-hover] - Specifies the component's icon color when hovered. * @cssproperty [--calcite-combobox-background-color] - Specifies the background color of the component's listbox. * @cssproperty [--calcite-combobox-input-border-color] - Specifies the border color of the component's input. * @cssproperty [--calcite-combobox-input-background-color] - Specifies the background color of the component's input. * @cssproperty [--calcite-combobox-input-height] - Specifies the height of the component's input. * @cssproperty [--calcite-combobox-input-text-color] - When `selectionDisplay` is `"single"`, specifies the text color of the component's input. * @slot - A slot for adding `calcite-combobox-item`s. * @slot [label-content] - A slot for rendering content next to the component's `labelText`. */ export abstract class Combobox extends LitElement { /** * When `true`, allows entry of custom values, which are not in the original set of items. * * @default false */ accessor allowCustomValues: boolean; /** * When `true`, disables value-clearing. * * @default false */ accessor clearDisabled: boolean; /** * When `true`, prevents interaction and decreases the component's opacity. * * @default false */ accessor disabled: boolean; /** The component's filtered items. */ get filteredItems(): HTMLCalciteComboboxItemElement[]; /** Specifies the properties to match against when filtering. If not set, all properties will be matched (`description`, `label`, `metadata`, `shortHeading`). */ accessor filterProps: string[]; /** The component's filter input field text. */ accessor filterText: string; /** Specifies the component's fallback `placement` for slotted content when it's initial or specified `placement` has insufficient space available. */ accessor flipPlacements: FlipPlacement[]; /** * Specifies the `id` of the component's associated form. * * When not set, the component is associated with its ancestor form element, if one exists. */ accessor form: string; /** * Specifies an accessible label for the component. * * @required */ accessor label: string; /** Specifies the component's label text. */ accessor labelText: string; /** * Specifies the maximum number of `calcite-combobox-item`s (including nested children) to display before displaying a scrollbar. * * @default 0 */ accessor maxItems: number; /** Overrides individual strings used by the component. */ accessor messageOverrides: { add?: string; all?: string; allSelected?: string; clear?: string; noMatches?: string; removeTag?: string; required?: string; selectAll?: string; selected?: string; nonEditable?: string; }; /** Specifies the name of the component. Required to pass the component's `value` on form submission. */ accessor name: string; /** * When `true`, displays and positions the component. * * @default false */ accessor open: boolean; /** * Specifies the type of positioning to use for overlaid content, where: * * `"absolute"` works for most cases - positioning the component inside of overflowing parent containers, which affects the container's layout, and * * `"fixed"` is used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. * * @default "absolute" */ accessor overlayPositioning: OverlayPositioning; /** Specifies the input's placeholder text. */ accessor placeholder: string; /** Specifies the input's placeholder icon. */ accessor placeholderIcon: IconName; /** * When `true` and the element direction is right-to-left (`"rtl"`), flips the input's `placeholderIcon`. * * @default false */ accessor placeholderIconFlipRtl: boolean; /** * Specifies the component's position relative to the `referenceElement`. * * @default "bottom-start" */ accessor placement: LogicalPlacement; /** * When `true`, the component's value can be read, but controls are not accessible and the value cannot be modified. * * @default false */ accessor readOnly: boolean; /** * When `true` and the component resides in a form, * the component must have a value in order for the form to submit. * * @default false */ accessor required: boolean; /** * Specifies the size of the component. * * @default "m" */ accessor scale: Scale; /** * When `true` and `selectionMode` is `"multiple"` or `"ancestors"`, displays a checkbox for selecting all `calcite-combobox-item`s. * * @default false */ accessor selectAllEnabled: boolean; /** The component's selected items. */ get selectedItems(): HTMLCalciteComboboxItemElement[]; /** * When `selectionMode` is `"ancestors"` or `"multiple"`, specifies the display of multiple `calcite-combobox-item` selections, where: * * `"all"` displays all selections with individual `calcite-chip`s, * * `"fit"` displays individual `calcite-chip`s that scale to the component's size, including a non-closable `calcite-chip`, which provides the number of additional `calcite-combobox-item` selections not visually displayed, and * * `"single"` displays one `calcite-chip` with the total number of selections. * * @default "all" */ accessor selectionDisplay: SelectionDisplay; /** * Specifies the selection mode of the component, where: * * `"multiple"` allows any number of selections, * * `"single"` allows only one selection, * * `"single-persist"` allows one selection and prevents de-selection, and * * `"ancestors"` allows multiple selections, but shows ancestors of selected items as selected, with only deepest children shown in chips. * * @default "multiple" */ accessor selectionMode: Extract<"single" | "single-persist" | "ancestors" | "multiple", SelectionMode>; /** * Specifies the input field's status, which determines message and icons. * * @default "idle" */ accessor status: Status; /** * When `true` and the component is `open`, disables top layer placement. * * Only set this if you need complex z-index control or if top layer placement causes conflicts with third-party components. * * @default false * @mdn [Top Layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer) */ accessor topLayerDisabled: boolean; /** Specifies the validation icon to display under the component. */ accessor validationIcon: IconName | boolean; /** Specifies the validation message to display under the component. */ accessor validationMessage: string; /** * The component's current validation state. * * @mdn [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) */ get validity(): MutableValidityState; /** The component's value(s) from the selected `calcite-combobox-item`(s). */ accessor value: string | string[]; /** * Updates the component's position. * * @param delayed - Reposition the component after a delay * @returns Promise */ reposition(delayed?: boolean): Promise<void>; /** * Sets focus on the component. * * @param options - When specified an optional object customizes the component's focusing process. When `preventScroll` is `true`, scrolling will not occur on the component. * @mdn [focus(options)](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus#options) */ setFocus(options?: FocusOptions): Promise<void>; /** Fires when the component is requested to be closed, and before the closing transition begins. */ readonly calciteComboboxBeforeClose: import("@arcgis/lumina").TargetedEvent<this, void>; /** Fires when the component is added to the DOM but not rendered, and before the opening transition begins. */ readonly calciteComboboxBeforeOpen: import("@arcgis/lumina").TargetedEvent<this, void>; /** Fires when the selected item(s) changes. */ readonly calciteComboboxChange: import("@arcgis/lumina").TargetedEvent<this, void>; /** Fires when a selected item in the component is closed via its `calcite-chip`. */ readonly calciteComboboxChipClose: import("@arcgis/lumina").TargetedEvent<this, void>; /** Fires when the component is closed and animation is complete. */ readonly calciteComboboxClose: import("@arcgis/lumina").TargetedEvent<this, void>; /** Fires when text is added to filter the options list. */ readonly calciteComboboxFilterChange: import("@arcgis/lumina").TargetedEvent<this, void>; /** Fires when the component is open and animation is complete. */ readonly calciteComboboxOpen: import("@arcgis/lumina").TargetedEvent<this, void>; readonly "@eventTypes": { calciteComboboxBeforeClose: Combobox["calciteComboboxBeforeClose"]["detail"]; calciteComboboxBeforeOpen: Combobox["calciteComboboxBeforeOpen"]["detail"]; calciteComboboxChange: Combobox["calciteComboboxChange"]["detail"]; calciteComboboxChipClose: Combobox["calciteComboboxChipClose"]["detail"]; calciteComboboxClose: Combobox["calciteComboboxClose"]["detail"]; calciteComboboxFilterChange: Combobox["calciteComboboxFilterChange"]["detail"]; calciteComboboxOpen: Combobox["calciteComboboxOpen"]["detail"]; }; }