@api-client/ui 0.5.5 → 0.5.7

package/.cursor/rules/html-and-css-best-practices.mdc

@@ -0,0 +1,63 @@
+---
+description: 
+globs: *.ts,*.css,*html
+alwaysApply: false
+---
+
+    You are an expert developer in HTML and CSS, focusing on best practices, accessibility, and responsive design.
+
+    Key Principles
+    - Write semantic HTML to improve accessibility and SEO.
+    - Use CSS for styling, avoiding inline styles.
+    - Ensure responsive design using media queries and flexible layouts.
+    - Prioritize accessibility by using ARIA roles and attributes.
+
+    HTML
+    - Use semantic elements (e.g., <header>, <main>, <footer>, <article>, <section>).
+    - Use <button> for clickable elements, not <div> or <span>.
+    - Use <a> for links, ensuring href attribute is present.
+    - Use <img> with alt attribute for images.
+    - Use <form> for forms, with appropriate input types and labels.
+    - Avoid using deprecated elements (e.g., <font>, <center>).
+
+    CSS
+    - Use external stylesheets for CSS.
+    - Use class selectors over ID selectors for styling.
+    - Use Flexbox and Grid for layout.
+    - Use rem and em units for scalable and accessible typography.
+    - Use CSS variables for consistent theming.
+    - Use BEM (Block Element Modifier) methodology for naming classes.
+    - Avoid !important; use specificity to manage styles.
+
+    Responsive Design
+    - Use media queries to create responsive layouts.
+    - Use mobile-first approach for media queries.
+    - Ensure touch targets are large enough for touch devices.
+    - Use responsive images with srcset and sizes attributes.
+    - Use viewport meta tag for responsive scaling.
+
+    Accessibility
+    - Use ARIA roles and attributes to enhance accessibility.
+    - Ensure sufficient color contrast for text.
+    - Provide keyboard navigation for interactive elements.
+    - Use focus styles to indicate focus state.
+    - Use landmarks (e.g., <nav>, <main>, <aside>) for screen readers.
+
+    Performance
+    - Minimize CSS and HTML file sizes.
+    - Use CSS minification and compression.
+    - Avoid excessive use of animations and transitions.
+    - Use lazy loading for images and other media.
+
+    Testing
+    - Test HTML and CSS in multiple browsers and devices.
+    - Use tools like Lighthouse for performance and accessibility audits.
+    - Validate HTML and CSS using W3C validators.
+
+    Documentation
+    - Comment complex CSS rules and HTML structures.
+    - Use consistent naming conventions for classes and IDs.
+    - Document responsive breakpoints and design decisions.
+
+    Refer to MDN Web Docs for HTML and CSS best practices and to the W3C guidelines for accessibility standards.
+    

package/.cursor/rules/lit-best-practices.mdc

@@ -0,0 +1,78 @@
+You are an expert developer in web components using the Lit library and Material Design version 3, focusing on best practices, accessibility, and responsive design.
+
+Key Principles
+
+- Comply with web elements authoring standards when designing a web component.
+- Use accessibility best practices to produce semantically relevant web components.
+- Prioritize web standards over custom implementation.
+- Prioritize APIs that are passing the Web Platform Baseline
+- Minimize external dependencies, but also balance between custom code and widely known and trusted dependencies.
+- Everything must be ES compliant. Use the appropriate standards for module imports.
+
+Lit Web Components
+
+- Document public properties and public function for authors to understand what these properties and functions do.
+- Ensure the appropriate aria roles are applied to each element.
+- Document all events and their structure (for custom events).
+- Prioritize well-known events (like change, select) over custom events.
+- Provide examples of usage when producing component documentation.
+- Prioritize native elements over custom elements whenever possible.
+- Prioritize composition over attribute passed configuration (a dropdown should have a semantic HTML structure and not auto-generated structure from a complex configuration object).
+- Think of other use-cases and how the custom element can scale for future use cases.
+- Reuse existing components whenever possible.
+- Prefer to put lifecycle methods after the constructor and before the render and other methods.
+- Put render methods at the end of the class.
+- Use `@property` decorator for public properties and `@state` decorator for private properties.
+- Use `@query` decorator for querying elements in the shadow DOM.
+- Use `@queryAssignedElements` decorator for querying slotted elements.
+- Boolean properties should be initialized to `false` in the constructor.
+- Use `@eventOptions` decorator to specify event options like `capture`, `passive`, and `once`.
+- Use `@queryAsync` decorator for querying elements that may not be immediately available in the DOM.
+- Use `@state` decorator for properties that are internal to the component and should not be exposed to the outside world.
+- Avoid passing complex objects as properties. Instead, use simple types like `string`, `number`, or `boolean` and handle complex logic internally.
+- Use lifecycle methods like `connectedCallback`, `disconnectedCallback`, and `update` to manage component state and behavior.
+- Use `willUpdate` method to perform actions before the component updates, such as validating properties or preparing data.
+- Place the component definition under the `internals/` directory of a component folder. The components registration should be done in the component file in the main component directory.
+- Place the base material components under the `src/md/` directory.
+- Place composite components under the `src/elements/` directory.
+
+CSS and Styling
+
+- Prioritize native CSS over JavaScript implementation. Use Web Platform Baseline even if the editor says it's not supported.
+- Use anchoring and popover API whenever possible and applicable over JavaScript positioning.
+- Place lit component styles in a separate file with the `.styles.ts` extension.
+- Add styles to the component registration class, not the base class.
+- Declare the `part` attributes to expose custom styling.
+- When working on base components, use CSS variables to allow customization of the component styles.
+- Define component states via the `internals.states.add("--state-name")` method. These states can be used as `component-name:state(state-name) {}` in the CSS.
+
+Error handling
+
+- Components either communicate errors through rendering them internally or dispatch an error event with the error details to the parent component or application.
+- Prefer error states defined on the element internals over custom error styling.
+
+Naming Convention
+
+- Follow web authoring standards as closely as possible.
+- Minimize the the of "-" in attribute and event names
+
+Testing
+
+- Use @open-wc/testing library.
+- Always add accessibility tests.
+- Create fixtures for different states of a component.
+- To run tests for a specific file, use the `--files` option in the test command. For example:
+  ```bash
+  npm test -- --files=".tmp/test/**/[test file name].test.js"
+  ```
+
+Component Demoing
+
+- Always produce a demo page under the demo/ directory.
+- Use the `DemoPage` class to bootstrap the demo page.
+- Use material styles with the demo page. Minimize custom styling.
+- Try to render each state separately and minimize the use of complex configurations.
+- Start with simple states and progressively enhance the demo with more complex configurations.
+- If a component produces output, ensure that the demo page shows the output in a readable format. Use one output per component.
+- Document the states in a way that is obvious to the user. Use headings and paragraphs to explain the states.
+- Due to the nature how the demo pages are processed, ensure that typescript files that belong to the demo page are imported from the `/.tmp/demo/` directory. This is done automatically by the build process. Imports inside the typescript file should reference files from the `src/` folder directly.

package/.github/instructions/html-and-css-best-practices.instructions.md

@@ -0,0 +1,70 @@
+---
+applyTo: "*.ts,*.css,*html"
+---
+
+# HTML and CSS Best Practices
+
+You are an expert developer in HTML and CSS, focusing on best practices, accessibility, and responsive design.
+
+## Key Principles
+
+- Write semantic HTML to improve accessibility and SEO.
+- Use CSS for styling, avoiding inline styles.
+- Ensure responsive design using media queries and flexible layouts.
+- Prioritize accessibility by using ARIA roles and attributes.
+
+## HTML
+
+- Use semantic elements (e.g., <header>, <main>, <footer>, <article>, <section>).
+- Use <button> for clickable elements, not <div> or <span>.
+- Use <a> for links, ensuring href attribute is present.
+- Use <img> with alt attribute for images.
+- Use <form> for forms, with appropriate input types and labels.
+- Avoid using deprecated elements (e.g., <font>, <center>).
+
+## CSS
+
+- Use external stylesheets for CSS.
+- Use class selectors over ID selectors for styling.
+- Use Flexbox and Grid for layout.
+- Use rem and em units for scalable and accessible typography.
+- Use CSS variables for consistent theming.
+- Use BEM (Block Element Modifier) methodology for naming classes.
+- Avoid !important; use specificity to manage styles.
+
+## Responsive Design
+
+- Use media queries to create responsive layouts.
+- Use mobile-first approach for media queries.
+- Ensure touch targets are large enough for touch devices.
+- Use responsive images with srcset and sizes attributes.
+- Use viewport meta tag for responsive scaling.
+
+## Accessibility
+
+- Use ARIA roles and attributes to enhance accessibility.
+- Ensure sufficient color contrast for text.
+- Provide keyboard navigation for interactive elements.
+- Use focus styles to indicate focus state.
+- Use landmarks (e.g., <nav>, <main>, <aside>) for screen readers.
+
+## Performance
+
+- Minimize CSS and HTML file sizes.
+- Use CSS minification and compression.
+- Avoid excessive use of animations and transitions.
+- Use lazy loading for images and other media.
+
+## Testing
+
+- Test HTML and CSS in multiple browsers and devices.
+- Use tools like Lighthouse for performance and accessibility audits.
+- Validate HTML and CSS using W3C validators.
+
+## Documentation
+
+- Comment complex CSS rules and HTML structures.
+- Use consistent naming conventions for classes and IDs.
+- Document responsive breakpoints and design decisions.
+
+Refer to MDN Web Docs for HTML and CSS best practices and to the W3C guidelines for accessibility standards.

package/.github/instructions/lit-best-practices.instructions.md

@@ -0,0 +1,86 @@
+---
+applyTo: "src/{elements,md,styles}/**,demo/**"
+---
+
+# Lit Element Best Practices
+
+You are an expert developer in web components using the Lit library and Material Design version 3, focusing on best practices, accessibility, and responsive design.
+
+## Key Principles
+
+- Comply with web elements authoring standards when designing a web component.
+- Use accessibility best practices to produce semantically relevant web components.
+- Prioritize web standards over custom implementation.
+- Prioritize APIs that are passing the Web Platform Baseline
+- Minimize external dependencies, but also balance between custom code and widely known and trusted dependencies.
+- Everything must be ES compliant. Use the appropriate standards for module imports.
+
+## Lit Web Components
+
+- Document public properties and public function for authors to understand what these properties and functions do.
+- Ensure the appropriate aria roles are applied to each element.
+- Document all events and their structure (for custom events).
+- Prioritize well-known events (like change, select) over custom events.
+- Provide examples of usage when producing component documentation.
+- Prioritize native elements over custom elements whenever possible.
+- Prioritize composition over attribute passed configuration (a dropdown should have a semantic HTML structure and not auto-generated structure from a complex configuration object).
+- Think of other use-cases and how the custom element can scale for future use cases.
+- Reuse existing components whenever possible.
+- Prefer to put lifecycle methods after the constructor and before the render and other methods.
+- Put render methods at the end of the class.
+- Use `@property` decorator for public properties and `@state` decorator for private properties.
+- Use `@query` decorator for querying elements in the shadow DOM.
+- Use `@queryAssignedElements` decorator for querying slotted elements.
+- Boolean properties should be initialized to `false` in the constructor.
+- Use `@eventOptions` decorator to specify event options like `capture`, `passive`, and `once`.
+- Use `@queryAsync` decorator for querying elements that may not be immediately available in the DOM.
+- Use `@state` decorator for properties that are internal to the component and should not be exposed to the outside world.
+- Avoid passing complex objects as properties. Instead, use simple types like `string`, `number`, or `boolean` and handle complex logic internally.
+- Use lifecycle methods like `connectedCallback`, `disconnectedCallback`, and `update` to manage component state and behavior.
+- Use `willUpdate` method to perform actions before the component updates, such as validating properties or preparing data.
+- Place the component definition under the `internals/` directory of a component folder. The components registration should be done in the component file in the main component directory.
+- Place the base material components under the `src/md/` directory.
+- Place composite components under the `src/elements/` directory.
+
+## CSS and Styling
+
+- Prioritize native CSS over JavaScript implementation. Use Web Platform Baseline even if the editor says it's not supported.
+- Use anchoring and popover API whenever possible and applicable over JavaScript positioning.
+- Place lit component styles in a separate file with the `.styles.ts` extension.
+- Add styles to the component registration class, not the base class.
+- Declare the `part` attributes to expose custom styling.
+- When working on base components, use CSS variables to allow customization of the component styles.
+- Define component states via the `internals.states.add("--state-name")` method. These states can be used as `component-name:state(state-name) {}` in the CSS.
+
+## Error handling
+
+- Components either communicate errors through rendering them internally or dispatch an error event with the error details to the parent component or application.
+- Prefer error states defined on the element internals over custom error styling.
+
+## Naming Convention
+
+- Follow web authoring standards as closely as possible.
+- Minimize the the of "-" in attribute and event names
+- Use camelCase for properties and methods.
+- Do not prefix private or protected properties and methods with an underscore. Use the typescript `private` and `protected` keywords to indicate visibility.
+
+## Testing
+
+- Use @open-wc/testing library.
+- Always add accessibility tests.
+- Create fixtures for different states of a component.
+- To run tests for a specific file, use the `--files` option in the test command. For example:
+  ```bash
+  npm test -- --files=".tmp/test/**/[test file name].test.js"
+  ```
+
+## Component Demoing
+
+- Always produce a demo page under the demo/ directory.
+- Use the `DemoPage` class to bootstrap the demo page.
+- Use material styles with the demo page. Minimize custom styling.
+- Try to render each state separately and minimize the use of complex configurations.
+- Start with simple states and progressively enhance the demo with more complex configurations.
+- If a component produces output, ensure that the demo page shows the output in a readable format. Use one output per component.
+- Document the states in a way that is obvious to the user. Use headings and paragraphs to explain the states.
+- Due to the nature how the demo pages are processed, ensure that typescript files that belong to the demo page are imported from the `/.tmp/demo/` directory. This is done automatically by the build process. Imports inside the typescript file should reference files from the `src/` folder directly.

package/build/src/elements/currency/currency-picker.d.ts

@@ -0,0 +1,10 @@
+import Element from './internals/Picker.js';
+export declare class CurrencyPickerElement extends Element {
+    static styles: import("lit").CSSResult[];
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'currency-picker': CurrencyPickerElement;
+    }
+}
+//# sourceMappingURL=currency-picker.d.ts.map

package/build/src/elements/currency/currency-picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency-picker.d.ts","sourceRoot":"","sources":["../../../../src/elements/currency/currency-picker.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,MAAM,uBAAuB,CAAA;AAG3C,qBACa,qBAAsB,SAAQ,OAAO;IAChD,OAAgB,MAAM,4BAAkB;CACzC;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,iBAAiB,EAAE,qBAAqB,CAAA;KACzC;CACF"}

package/build/src/elements/currency/currency-picker.js

@@ -0,0 +1,27 @@
+import { __esDecorate, __runInitializers } from "tslib";
+import { customElement } from 'lit/decorators.js';
+import Element from './internals/Picker.js';
+import elementStyles from './internals/Picker.styles.js';
+let CurrencyPickerElement = (() => {
+    let _classDecorators = [customElement('currency-picker')];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    let _classSuper = Element;
+    var CurrencyPickerElement = class extends _classSuper {
+        static { _classThis = this; }
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+            CurrencyPickerElement = _classThis = _classDescriptor.value;
+            if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static styles = [elementStyles];
+        static {
+            __runInitializers(_classThis, _classExtraInitializers);
+        }
+    };
+    return CurrencyPickerElement = _classThis;
+})();
+export { CurrencyPickerElement };
+//# sourceMappingURL=currency-picker.js.map

package/build/src/elements/currency/currency-picker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"currency-picker.js","sourceRoot":"","sources":["../../../../src/elements/currency/currency-picker.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,OAAO,MAAM,uBAAuB,CAAA;AAC3C,OAAO,aAAa,MAAM,8BAA8B,CAAA;IAG3C,qBAAqB;4BADjC,aAAa,CAAC,iBAAiB,CAAC;;;;sBACU,OAAO;qCAAf,SAAQ,WAAO;;;;YAAlD,6KAEC;;;;QADC,MAAM,CAAU,MAAM,GAAG,CAAC,aAAa,CAAC,CAAA;;YAD7B,uDAAqB;;;;;SAArB,qBAAqB","sourcesContent":["import { customElement } from 'lit/decorators.js'\nimport Element from './internals/Picker.js'\nimport elementStyles from './internals/Picker.styles.js'\n\n@customElement('currency-picker')\nexport class CurrencyPickerElement extends Element {\n  static override styles = [elementStyles]\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n    'currency-picker': CurrencyPickerElement\n  }\n}\n"]}

package/build/src/elements/currency/internals/Picker.d.ts

@@ -0,0 +1,311 @@
+import { LitElement, type TemplateResult, type PropertyValues, nothing } from 'lit';
+import '@material/web/select/outlined-select.js';
+import '@material/web/select/select-option.js';
+import '../../../md/chip/ui-chip-set.js';
+import '../../../md/chip/ui-chip.js';
+/**
+ * Represents a currency with all its display information.
+ */
+export interface Currency {
+    /** ISO 4217 currency code (e.g., 'USD', 'EUR') */
+    code: string;
+    /** Full name of the currency (e.g., 'US Dollar', 'Euro') */
+    name: string;
+    /** Currency symbol (e.g., '$', '€') */
+    symbol: string;
+    /** Country or region name (e.g., 'United States', 'European Union') */
+    country: string;
+    /** Flag emoji representing the currency's origin */
+    flag: string;
+}
+/**
+ * Represents an error that can occur in the CurrencyPicker component.
+ */
+export interface CurrencyPickerError {
+    /** Type of error: validation, selection constraint, or internal error */
+    type: 'validation' | 'selection' | 'internal';
+    /** Human-readable error message */
+    message: string;
+    /** Optional additional details about the error for debugging */
+    details?: Record<string, unknown>;
+}
+/**
+ * Event detail interface for currency picker error events.
+ */
+export interface CurrencyPickerErrorEvent {
+    /** The error information */
+    error: CurrencyPickerError;
+}
+/**
+ * A web component for selecting currencies with chips display.
+ * Provides a searchable interface with country flags and currency information.
+ *
+ * This component uses ElementInternals for native form integration and
+ * follows web standards for error handling and validation.
+ *
+ * ## Features
+ * - Single or multi-select currency selection
+ * - Visual chips display for selected currencies
+ * - Native form integration with ElementInternals
+ * - Comprehensive validation and error handling
+ * - Accessibility support with ARIA attributes
+ * - Keyboard navigation support
+ * - Currency filtering based on allowed currencies
+ *
+ * ## Usage
+ * ```html
+ * <!-- Basic usage -->
+ * <currency-picker></currency-picker>
+ *
+ * <!-- Multi-select with allowed currencies -->
+ * <currency-picker multi .allowedCurrencies="${['USD', 'EUR', 'GBP']}"></currency-picker>
+ *
+ * <!-- Form integration -->
+ * <form>
+ *   <currency-picker name="currencies" required></currency-picker>
+ * </form>
+ * ```
+ *
+ * @fires change - Dispatched when selected currencies change due to user interaction.
+ *                 Contains {currencies: Currency[], codes: string[]} in event.detail
+ * @fires error - Dispatched when validation or other errors occur.
+ *                Contains {error: CurrencyPickerError} in event.detail
+ *
+ * @example
+ * ```typescript
+ * const picker = document.querySelector('currency-picker');
+ * picker.addEventListener('change', (e) => {
+ *   console.log('Selected currencies:', e.detail.currencies);
+ * });
+ * picker.addEventListener('error', (e) => {
+ *   console.error('Picker error:', e.detail.error.message);
+ * });
+ * ```
+ */
+export default class CurrencyPicker extends LitElement {
+    /**
+     * Indicates that this custom element is form-associated and can participate in form submission.
+     * This enables the component to work with native HTML forms and use ElementInternals.
+     */
+    static formAssociated: boolean;
+    /**
+     * Private ElementInternals instance for form integration and validation.
+     * Provides access to form APIs like setFormValue, setValidity, etc.
+     */
+    private internals;
+    /**
+     * Shadow root configuration for the component.
+     * Uses 'open' mode for accessibility and delegates focus to enable proper focus management.
+     */
+    static shadowRootOptions: ShadowRootInit;
+    /**
+     * The currently selected currency codes.
+     * This is an array of ISO 4217 currency codes (e.g., 'USD', 'EUR').
+     */
+    accessor selected: string[];
+    /**
+     * The currencies that should be available for selection.
+     * If not specified, all supported currencies will be available.
+     * This is an array of ISO 4217 currency codes (e.g., 'USD', 'EUR').
+     */
+    accessor allowedCurrencies: string[];
+    /**
+     * The label for the currency selection dropdown.
+     * This is displayed as the label for the select input.
+     * @attribute
+     */
+    accessor label: string;
+    /**
+     * The name attribute for the currency selection dropdown.
+     * This is used when submitting forms that include this component.
+     * @attribute
+     */
+    accessor name: string | undefined;
+    /**
+     * Supporting text for the currency selection dropdown.
+     * This is displayed below the select input.
+     * @attribute
+     */
+    accessor supportingText: string | undefined;
+    /**
+     * Whether the currency selection is required.
+     * If true, the component will enforce at least one currency to be selected.
+     * @attribute
+     */
+    accessor required: boolean;
+    /**
+     * Whether the currency selection is disabled.
+     * If true, the component will not allow any changes to the selected currencies.
+     * @attribute
+     */
+    accessor disabled: boolean;
+    /**
+     * Whether multiple currencies can be selected.
+     * If true, the component allows selecting multiple currencies.
+     * If false, only one currency can be selected at a time.
+     * @attribute
+     */
+    accessor multi: boolean;
+    /**
+     * Whether to show errors inline within the component.
+     * If true, errors will be displayed below the component.
+     * If false, errors will only be dispatched as events.
+     * @attribute
+     */
+    accessor showErrors: boolean;
+    /**
+     * The currently selectable currencies (filtered based on selection and allowed currencies).
+     * This is automatically updated based on the selected currencies and allowedCurrencies property.
+     */
+    private accessor selectableCurrencies;
+    /**
+     * Reference to the Material Design outlined select element.
+     * Used to manage the select's internal state and keep it synchronized with the component's selected property.
+     */
+    private accessor selectElement;
+    /**
+     * Returns the form element that contains this component, if any.
+     * Part of the ElementInternals API for form-associated custom elements.
+     */
+    get form(): HTMLFormElement | null;
+    /**
+     * Returns the validity state of the component.
+     * Part of the ElementInternals API for form-associated custom elements.
+     */
+    get validity(): ValidityState;
+    /**
+     * Returns the validation message for the component.
+     * Part of the ElementInternals API for form-associated custom elements.
+     */
+    get validationMessage(): string;
+    /**
+     * Returns whether the component will be validated when the form is submitted.
+     * Part of the ElementInternals API for form-associated custom elements.
+     */
+    get willValidate(): boolean;
+    /**
+     * Checks the validity of the component without displaying validation UI.
+     * Part of the ElementInternals API for form-associated custom elements.
+     * @returns True if the component is valid, false otherwise
+     */
+    checkValidity(): boolean;
+    /**
+     * Checks the validity of the component and displays validation UI if invalid.
+     * Part of the ElementInternals API for form-associated custom elements.
+     * @returns True if the component is valid, false otherwise
+     */
+    reportValidity(): boolean;
+    /**
+     * Master list of supported currencies with their display information.
+     * This includes popular currencies with their ISO codes, names, symbols, countries, and flag emojis.
+     * Private and readonly to ensure data integrity.
+     */
+    private readonly currencies;
+    constructor();
+    connectedCallback(): void;
+    /**
+     * Updates the form value using ElementInternals.
+     */
+    private updateFormValue;
+    protected willUpdate(changed: PropertyValues<this>): void;
+    /**
+     * Called after the component has been updated and rendered.
+     * Ensures the select element's value stays synchronized with the component's selected state.
+     */
+    protected updated(changed: PropertyValues<this>): void;
+    /**
+     * Sets an error state using ElementInternals and optionally dispatches an error event.
+     * @param error The error to set
+     * @param dispatch Whether to dispatch an error event (default: true)
+     */
+    private setError;
+    /**
+     * Dispatches an error event.
+     * @param error The error to dispatch
+     */
+    private dispatchErrorEvent;
+    /**
+     * Clears the current error state using ElementInternals.
+     */
+    private clearError;
+    /**
+     * Validates currency codes against the supported currencies.
+     * @param codes Array of currency codes to validate
+     * @returns Array of invalid currency codes
+     */
+    private validateCurrencyCodes;
+    /**
+     * Safely validates and filters currency codes, setting errors for invalid codes.
+     * @param codes Array of currency codes to validate
+     * @param property Name of the property being validated
+     * @returns Array of valid currency codes
+     */
+    private safeCurrencyValidation;
+    /**
+     * Validates selection constraints using ElementInternals.
+     * @param newSelection The new selection to validate
+     * @returns Whether the selection is valid
+     */
+    private validateSelectionConstraints;
+    private updateSelectableCurrencies;
+    private handleCurrencySelect;
+    private handleRemoveCurrency;
+    private dispatchChangeEvent;
+    /**
+     * Get the currently selected currency codes as a copy of the array.
+     * This is a read-only getter that returns a shallow copy to prevent external modification.
+     * @returns Array of selected ISO 4217 currency codes
+     */
+    get selectedCurrencyCodes(): string[];
+    /**
+     * Get the full currency objects for currently selected currencies.
+     * This method looks up each selected currency code in the master currencies list
+     * and returns the complete currency information including name, symbol, country, and flag.
+     * @returns Array of complete Currency objects for selected currencies
+     */
+    getSelectedCurrencies(): Currency[];
+    /**
+     * Clear all selected currencies.
+     * This method removes all selections, validates constraints (such as required),
+     * updates the UI, and dispatches a change event. If validation fails (e.g.,
+     * component is required), the operation will be cancelled and an error will be set.
+     * @throws Will dispatch an error event if validation fails or an internal error occurs
+     */
+    clearSelection(): void;
+    /**
+     * Form state restore callback for ElementInternals.
+     * This method is called by the browser when form state is being restored
+     * (e.g., browser back/forward navigation, form autofill).
+     * It parses a comma-separated string of currency codes and restores the selection.
+     * @param state The state to restore - typically a comma-separated string of currency codes
+     * @param _mode The restore mode (unused in this implementation)
+     */
+    formStateRestoreCallback(state: string | FormData | null): void;
+    /**
+     * Form reset callback for ElementInternals.
+     * This method is called by the browser when the containing form is reset.
+     * It clears all selections, updates the UI, clears any errors, and updates the form value.
+     */
+    formResetCallback(): void;
+    /**
+     * Main render method for the component.
+     * Renders the currency selector with dropdown, selected chips (if multi-select), and error display.
+     * Updates ARIA attributes and error states based on current component state.
+     * @returns TemplateResult containing the complete component HTML
+     */
+    render(): TemplateResult;
+    /**
+     * Renders error messages when showErrors is true and the component is invalid.
+     * The error display uses ARIA live regions for accessibility.
+     * @returns TemplateResult with error display or nothing if no errors should be shown
+     */
+    protected renderError(): TemplateResult | typeof nothing;
+    /**
+     * Renders the selected currencies as removable chips in multi-select mode.
+     * Only renders when multi=true and there are selected currencies.
+     * Each chip displays the currency flag and code, and can be removed by the user.
+     * @returns TemplateResult with chip display or nothing if not applicable
+     */
+    protected renderSelected(): TemplateResult | typeof nothing;
+}
+//# sourceMappingURL=Picker.d.ts.map

package/build/src/elements/currency/internals/Picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Picker.d.ts","sourceRoot":"","sources":["../../../../../src/elements/currency/internals/Picker.ts"],"names":[],"mappings":"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"}