@lion/ui/dist-types/components/input-amount-dropdown/src/LionInputAmountDropdown.d.ts

A package of extendable web components

/**
 * Note: one could consider to implement LionInputAmountDropdown as a
 * [combobox](https://www.w3.org/TR/wai-aria-practices-1.2/#combobox).
 * However, the currency dropdown does not directly set the textbox value, it only determines
 * its region code. Therefore it does not comply to this criterium:
 * "A combobox is an input widget with an associated popup that enables users to select a value for
 * the combobox from a collection of possible values. In some implementations,
 * the popup presents allowed values, while in other implementations, the popup presents suggested
 * values, and users may either select one of the suggestions or type a value".
 * We therefore decided to consider the dropdown a helper mechanism that does not set, but
 * contributes to and helps format and validate the actual value.
 */
/**
 * @typedef {import('lit/directives/ref.js').Ref} Ref
 * @typedef {import('lit').RenderOptions} RenderOptions
 * @typedef {import('../../form-core/types/FormatMixinTypes.js').FormatHost} FormatHost
 * @typedef {import('../../input-tel/types/index.js').RegionCode} RegionCode
 * @typedef {import('../types/index.js').TemplateDataForDropdownInputAmount} TemplateDataForDropdownInputAmount
 * @typedef {import('../types/index.js').OnDropdownChangeEvent} OnDropdownChangeEvent
 * @typedef {import('../types/index.js').DropdownRef} DropdownRef
 * @typedef {import('../types/index.js').RegionMeta} RegionMeta
 * @typedef {import('../types/index.js').CurrencyCode} CurrencyCode
 * @typedef {import('../../select-rich/src/LionSelectRich.js').LionSelectRich} LionSelectRich
 * @typedef {import('../../overlays/src/OverlayController.js').OverlayController} OverlayController
 * @typedef {import('../../form-core/types/FormatMixinTypes.js').FormatOptions} FormatOptions
 * @typedef {FormatOptions & {locale?:string;currency:string|undefined}} AmountFormatOptions
 * @typedef {TemplateDataForDropdownInputAmount & {data: {regionMetaList:RegionMeta[]}}} TemplateDataForIntlInputAmount
 */
/**
 * LionInputAmountDropdown renders a dropdown like element next to the text field, inside the
 * prefix, or suffix, slot. This could be a LionSelect, a LionSelectRich or a native select.
 * By default, the native `<select>` element is used for this, so that it's as lightweight as
 * possible. Also, it doesn't need to be a `FormControl`, because it's purely a helper element
 * to provide better UX: the modelValue (the text field) contains all needed info:
 * the currency code following ISO 4217 and its corresponding currency symbol using Intl.
 *
 * @customElement lion-input-amount-dropdown
 */
export class LionInputAmountDropdown extends LionInputAmount {
    /**
     * @configure LitElement
     * @type {any}
     */
    static properties: any;
    static localizeNamespaces: import("../../localize/types/LocalizeMixinTypes.js").NamespaceObject[];
    static templates: {
        dropdown: (templateDataForDropdown: TemplateDataForDropdownInputAmount) => import("lit-html").TemplateResult<1>;
        /**
         * @param {TemplateDataForDropdownInputAmount} templateDataForDropdown
         * @param {RegionMeta} contextData
         */
        dropdownOption: (templateDataForDropdown: TemplateDataForDropdownInputAmount, { currencyCode, nameForLocale, currencySymbol }: RegionMeta) => import("lit-html").TemplateResult<1>;
    };
    /**
     * @configure LitElement
     * @enhance LionInputAmountDropdown
     */
    static styles: (import("lit").CSSResult | (import("lit").CSSResultOrNative | import("lit").CSSResultArray)[])[];
    refs: {
        /** @type {DropdownRef} */
        dropdown: DropdownRef;
    };
    /**
     * This method provides a TemplateData object to be fed to pure template functions, a.k.a.
     * Pure Templates™. The goal is to totally decouple presentation from logic here, so that
     * Subclassers can override all content without having to loose private info contained
     * within the template function that was overridden.
     *
     * Subclassers would need to make sure all the contents of the TemplateData object are implemented
     * by making sure they are coupled to the right 'ref' ([data-ref=dropdown] in this example),
     * with the help of lit's spread operator directive.
     * To enhance this process, the TemplateData object is completely typed. Ideally, this would be
     * enhanced by providing linters that make sure all of their required members are implemented by
     * a Subclasser.
     * When a Subclasser wants to add more data, this can be done via:
     * @example
     * ```js
     * get _templateDataDropdown() {
     *   return {
     *     ...super._templateDataDropdown,
     *     myExtraData: { x: 1, y: 2 },
     *   }
     * }
     * ```
     * @overridable
     * @type {TemplateDataForDropdownInputAmount}
     */
    get _templateDataDropdown(): import("../types/index.js").TemplateDataForDropdownInputAmount;
    set _dropdownSlot(arg: string);
    /**
     * @returns {string}
     */
    get _dropdownSlot(): string;
    __dropdownSlot: string;
    /**
     * @protected
     * @type {RegionCode}
     */
    protected _langIso: import("../../input-tel/types/index.js").RegionCode | undefined;
    __namesForLocale: Intl.DisplayNames | undefined;
    parser: (value: string, givenOptions?: import("../../localize/types/LocalizeMixinTypes.js").FormatNumberOptions | undefined) => import("../types/index.js").AmountDropdownModelValue;
    /**
     * @param {import("../types/index.js").AmountDropdownModelValue} modelValue
     * @param {import('../../localize/types/LocalizeMixinTypes.js').FormatNumberOptions} [givenOptions] Locale Options
     */
    formatter: (modelValue: import("../types/index.js").AmountDropdownModelValue, givenOptions?: import("../../localize/types/LocalizeMixinTypes.js").FormatNumberOptions | undefined) => string;
    serializer: (modelValue: import("../types/index.js").AmountDropdownModelValue) => string;
    deserializer: (serializedValue: string) => import("../types/index.js").AmountDropdownModelValue;
    defaultValidators: CurrencyAndAmount[];
    /**
     * Regions that will be shown on top of the dropdown
     * @type {CurrencyCode[]}
     */
    preferredCurrencies: CurrencyCode[];
    /**
     * Regions that are allowed to be selected in the dropdown.
     * @type {CurrencyCode[]}
     */
    allowedCurrencies: CurrencyCode[];
    /**
     * Group label for all countries, when preferredCountries are shown
     * @protected
     */
    protected _allCurrenciesLabel: string;
    /**
     * Group label for preferred countries, when preferredCountries are shown
     * @protected
     */
    protected _preferredCurrenciesLabel: string;
    /**
     * Contains everything needed for rendering region options:
     * region code, currency code, display name according to locale, display name
     * @private
     * @type {RegionMeta[]}
     */
    private __regionMetaList;
    /**
     * A filtered `this.__regionMetaList`, containing all regions provided in `preferredCurrencies`
     * @private
     * @type {RegionMeta[]}
     */
    private __regionMetaListPreferred;
    /**
     * @protected
     * @param {OnDropdownChangeEvent} event
     */
    protected _onDropdownValueChange(event: OnDropdownChangeEvent): void;
    /**
     * @private
     */
    private __syncCurrencyWithDropdown;
    _currencyUtil: {
        countryToCurrencyMap: import("../types/index.js").RegionToCurrencyMap;
        allCurrencies: import("../types/index.js").AllCurrenciesSet;
        getCurrencySymbol: (currency: import("../types/index.js").CurrencyCode, locale: string) => string;
    };
    /**
     * @protected
     */
    protected _initModelValueBasedOnDropdown(): void;
    __initializedCurrencyCode: string | undefined;
    /**
     * Used for Required validation and computation of interaction states.
     * We need to override this, because we prefill the input with the currency code, but for proper UX,
     * we don't consider this as having interaction state `prefilled`
     * @param {string} modelValue
     * @return {boolean}
     * @protected
     */
    protected _isEmpty(modelValue?: string): boolean;
    /**
     * Prepares data for options, like "Greece (Ελλάδα)", where "Greece" is `nameForLocale` and
     * "Ελλάδα" `nameForRegion`.
     * This should be run on change of:
     * - allowedCurrencies
     * - locale
     * @private
     */
    private __createCurrencyMeta;
    /**
     * Usually, we don't use composition in regular LionFields (non choice-groups). Here we use a LionSelect(Rich) inside.
     * We don't want to repropagate any children, since an Application Developer is not concerned with these internals (see repropate logic in FormControlMixin)
     * Also, we don't want to give (wrong) info to InteractionStateMixin, that will set the wrong interaction states based on child info.
     * TODO: Make "this._repropagationRole !== 'child'" the default for FormControlMixin
     * (so that FormControls used within are never repropagated for LionFields)
     * @protected
     * @configure FormControlMixin: don't repropagate any children
     */
    protected _repropagationCondition(): boolean;
    __calculateActiveCurrency(): void;
    /**
     * Used for rendering the region/currency list
     * @property _allowedOrAllRegions
     * @type {CurrencyCode[]}
     */
    get _allowedOrAllCurrencies(): import("../types/index.js").CurrencyCode[];
}
export type Ref = import('lit/directives/ref.js').Ref;
export type RenderOptions = import('lit').RenderOptions;
export type FormatHost = import('../../form-core/types/FormatMixinTypes.js').FormatHost;
export type RegionCode = import('../../input-tel/types/index.js').RegionCode;
export type TemplateDataForDropdownInputAmount = import('../types/index.js').TemplateDataForDropdownInputAmount;
export type OnDropdownChangeEvent = import('../types/index.js').OnDropdownChangeEvent;
export type DropdownRef = import('../types/index.js').DropdownRef;
export type RegionMeta = import('../types/index.js').RegionMeta;
export type CurrencyCode = import('../types/index.js').CurrencyCode;
export type LionSelectRich = import('../../select-rich/src/LionSelectRich.js').LionSelectRich;
export type OverlayController = import('../../overlays/src/OverlayController.js').OverlayController;
export type FormatOptions = import('../../form-core/types/FormatMixinTypes.js').FormatOptions;
export type AmountFormatOptions = FormatOptions & {
    locale?: string;
    currency: string | undefined;
};
export type TemplateDataForIntlInputAmount = TemplateDataForDropdownInputAmount & {
    data: {
        regionMetaList: RegionMeta[];
    };
};
import { LionInputAmount } from "../../../exports/input-amount.js";
import { CurrencyAndAmount } from "./validators.js";
//# sourceMappingURL=LionInputAmountDropdown.d.ts.map