@momentum-design/components 0.104.17 → 0.105.1

package/dist/index.d.ts

@@ -76,6 +76,7 @@ import Tooltip from './components/tooltip';
 import VirtualizedList from './components/virtualizedlist';
 import Combobox from './components/combobox';
 import Slider from './components/slider';
+import ListBox from './components/listbox';
 import type { BadgeType } from './components/badge/badge.types';
 import type { ButtonColor, ButtonVariant, IconButtonSize, PillButtonSize } from './components/button/button.types';
 import type { PopoverPlacement } from './components/popover/popover.types';
@@ -86,9 +87,10 @@ import type { TextType as TypewriterType } from './components/typewriter/typewri
 import type { MenuPopoverActionEvent, MenuPopoverChangeEvent } from './components/menupopover/menupopover.types';
 import type { SelectChangeEvent, SelectInputEvent } from './components/select/select.types';
 import type { MenuSectionChangeEvent } from './components/menusection/menusection.types';
+import type { InputInputEvent, InputChangeEvent, InputFocusEvent, InputBlurEvent, InputClearEvent } from './components/input/input.types';
 import { BUTTON_COLORS, BUTTON_VARIANTS, ICON_BUTTON_SIZES, PILL_BUTTON_SIZES } from './components/button/button.constants';
 import { SKELETON_VARIANTS } from './components/skeleton/skeleton.constants';
 import { inMemoryCache, webAPIIconsCache } from './utils/icon-cache';
-export { Accordion, AccordionButton, AccordionGroup, AlertChip, Animation, Appheader, Avatar, AvatarButton, Badge, Brandvisual, Bullet, Button, ButtonGroup, ButtonLink, Card, CardButton, CardCheckbox, CardRadio, Checkbox, Chip, Coachmark, Dialog, Divider, FilterChip, FormfieldGroup, Icon, IconProvider, Input, InputChip, Link, LinkButton, Linksimple, List, Listheader, ListItem, Marker, MenuBar, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuSection, NavMenuItem, OptGroup, Option, Password, Popover, Presence, Progressbar, Progressspinner, Radio, RadioGroup, ScreenreaderAnnouncer, Searchfield, Select, SelectListbox, SideNavigation, Skeleton, Spinner, StaticCheckbox, StaticRadio, StaticToggle, Stepper, StepperConnector, StepperItem, Tab, TabList, Text, Textarea, ThemeProvider, Toast, Toggle, Typewriter, ToggleTip, Tooltip, VirtualizedList, Combobox, Slider, };
-export type { BadgeType, ButtonColor, ButtonVariant, IconButtonSize, MenuPopoverActionEvent, MenuPopoverChangeEvent, MenuSectionChangeEvent, PillButtonSize, PopoverPlacement, SkeletonVariant, SelectChangeEvent, SelectInputEvent, SpinnerSize, SpinnerVariant, TextType, TypewriterType, };
+export { Accordion, AccordionButton, AccordionGroup, AlertChip, Animation, Appheader, Avatar, AvatarButton, Badge, Brandvisual, Bullet, Button, ButtonGroup, ButtonLink, Card, CardButton, CardCheckbox, CardRadio, Checkbox, Chip, Coachmark, Dialog, Divider, FilterChip, FormfieldGroup, Icon, IconProvider, Input, InputChip, Link, LinkButton, Linksimple, List, Listheader, ListItem, Marker, MenuBar, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuSection, NavMenuItem, OptGroup, Option, Password, Popover, Presence, Progressbar, Progressspinner, Radio, RadioGroup, ScreenreaderAnnouncer, Searchfield, Select, SelectListbox, SideNavigation, Skeleton, Spinner, StaticCheckbox, StaticRadio, StaticToggle, Stepper, StepperConnector, StepperItem, Tab, TabList, Text, Textarea, ThemeProvider, Toast, Toggle, Typewriter, ToggleTip, Tooltip, VirtualizedList, Combobox, Slider, ListBox, };
+export type { BadgeType, ButtonColor, ButtonVariant, IconButtonSize, MenuPopoverActionEvent, MenuPopoverChangeEvent, MenuSectionChangeEvent, PillButtonSize, PopoverPlacement, SkeletonVariant, SelectChangeEvent, SelectInputEvent, SpinnerSize, SpinnerVariant, TextType, TypewriterType, InputInputEvent, InputChangeEvent, InputFocusEvent, InputBlurEvent, InputClearEvent, };
 export { BUTTON_COLORS, BUTTON_VARIANTS, ICON_BUTTON_SIZES, inMemoryCache, PILL_BUTTON_SIZES, SKELETON_VARIANTS, webAPIIconsCache, };

package/dist/index.js

@@ -78,11 +78,12 @@ import Tooltip from './components/tooltip';
 import VirtualizedList from './components/virtualizedlist';
 import Combobox from './components/combobox';
 import Slider from './components/slider';
+import ListBox from './components/listbox';
 // Constants / Utils Imports
 import { BUTTON_COLORS, BUTTON_VARIANTS, ICON_BUTTON_SIZES, PILL_BUTTON_SIZES, } from './components/button/button.constants';
 import { SKELETON_VARIANTS } from './components/skeleton/skeleton.constants';
 import { inMemoryCache, webAPIIconsCache } from './utils/icon-cache';
 // Components Exports
-export { Accordion, AccordionButton, AccordionGroup, AlertChip, Animation, Appheader, Avatar, AvatarButton, Badge, Brandvisual, Bullet, Button, ButtonGroup, ButtonLink, Card, CardButton, CardCheckbox, CardRadio, Checkbox, Chip, Coachmark, Dialog, Divider, FilterChip, FormfieldGroup, Icon, IconProvider, Input, InputChip, Link, LinkButton, Linksimple, List, Listheader, ListItem, Marker, MenuBar, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuSection, NavMenuItem, OptGroup, Option, Password, Popover, Presence, Progressbar, Progressspinner, Radio, RadioGroup, ScreenreaderAnnouncer, Searchfield, Select, SelectListbox, SideNavigation, Skeleton, Spinner, StaticCheckbox, StaticRadio, StaticToggle, Stepper, StepperConnector, StepperItem, Tab, TabList, Text, Textarea, ThemeProvider, Toast, Toggle, Typewriter, ToggleTip, Tooltip, VirtualizedList, Combobox, Slider, };
+export { Accordion, AccordionButton, AccordionGroup, AlertChip, Animation, Appheader, Avatar, AvatarButton, Badge, Brandvisual, Bullet, Button, ButtonGroup, ButtonLink, Card, CardButton, CardCheckbox, CardRadio, Checkbox, Chip, Coachmark, Dialog, Divider, FilterChip, FormfieldGroup, Icon, IconProvider, Input, InputChip, Link, LinkButton, Linksimple, List, Listheader, ListItem, Marker, MenuBar, MenuItem, MenuItemCheckbox, MenuItemRadio, MenuPopover, MenuSection, NavMenuItem, OptGroup, Option, Password, Popover, Presence, Progressbar, Progressspinner, Radio, RadioGroup, ScreenreaderAnnouncer, Searchfield, Select, SelectListbox, SideNavigation, Skeleton, Spinner, StaticCheckbox, StaticRadio, StaticToggle, Stepper, StepperConnector, StepperItem, Tab, TabList, Text, Textarea, ThemeProvider, Toast, Toggle, Typewriter, ToggleTip, Tooltip, VirtualizedList, Combobox, Slider, ListBox, };
 // Constants / Utils Exports
 export { BUTTON_COLORS, BUTTON_VARIANTS, ICON_BUTTON_SIZES, inMemoryCache, PILL_BUTTON_SIZES, SKELETON_VARIANTS, webAPIIconsCache, };

package/dist/react/index.d.ts

@@ -28,12 +28,13 @@ export { default as FormfieldGroup } from './formfieldgroup';
 export { default as FormfieldWrapper } from './formfieldwrapper';
 export { default as Icon } from './icon';
 export { default as IconProvider } from './iconprovider';
-export { default as Input } from './input';
 export { default as InputChip } from './inputchip';
+export { default as Input } from './input';
 export { default as Link } from './link';
 export { default as LinkButton } from './linkbutton';
 export { default as Linksimple } from './linksimple';
 export { default as List } from './list';
+export { default as ListBox } from './listbox';
 export { default as Listheader } from './listheader';
 export { default as ListItem } from './listitem';
 export { default as Marker } from './marker';
@@ -72,9 +73,9 @@ export { default as TabList } from './tablist';
 export { default as Text } from './text';
 export { default as Textarea } from './textarea';
 export { default as ThemeProvider } from './themeprovider';
-export { default as Toast } from './toast';
 export { default as Toggle } from './toggle';
-export { default as ToggleTip } from './toggletip';
 export { default as Tooltip } from './tooltip';
+export { default as Toast } from './toast';
+export { default as ToggleTip } from './toggletip';
 export { default as Typewriter } from './typewriter';
 export { default as VirtualizedList } from './virtualizedlist';

package/dist/react/index.js

@@ -28,12 +28,13 @@ export { default as FormfieldGroup } from './formfieldgroup';
 export { default as FormfieldWrapper } from './formfieldwrapper';
 export { default as Icon } from './icon';
 export { default as IconProvider } from './iconprovider';
-export { default as Input } from './input';
 export { default as InputChip } from './inputchip';
+export { default as Input } from './input';
 export { default as Link } from './link';
 export { default as LinkButton } from './linkbutton';
 export { default as Linksimple } from './linksimple';
 export { default as List } from './list';
+export { default as ListBox } from './listbox';
 export { default as Listheader } from './listheader';
 export { default as ListItem } from './listitem';
 export { default as Marker } from './marker';
@@ -72,9 +73,9 @@ export { default as TabList } from './tablist';
 export { default as Text } from './text';
 export { default as Textarea } from './textarea';
 export { default as ThemeProvider } from './themeprovider';
-export { default as Toast } from './toast';
 export { default as Toggle } from './toggle';
-export { default as ToggleTip } from './toggletip';
 export { default as Tooltip } from './tooltip';
+export { default as Toast } from './toast';
+export { default as ToggleTip } from './toggletip';
 export { default as Typewriter } from './typewriter';
 export { default as VirtualizedList } from './virtualizedlist';

package/dist/react/input/index.d.ts

@@ -45,9 +45,9 @@ import Component from '../../components/input';
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {
     onClear: EventName<import("../../components/input/input.types").InputClearEvent>;
-    onInput: EventName<import("../../utils/types").OverrideEventTarget<InputEvent, Component>>;
+    onInput: EventName<import("../../components/input/input.types").InputInputEvent>;
     onChange: EventName<import("../../components/input/input.types").InputChangeEvent>;
-    onFocus: EventName<import("../../utils/types").OverrideEventTarget<FocusEvent, Component>>;
-    onBlur: EventName<import("../../utils/types").OverrideEventTarget<FocusEvent, Component>>;
+    onFocus: EventName<import("../../components/input/input.types").InputFocusEvent>;
+    onBlur: EventName<import("../../components/input/input.types").InputBlurEvent>;
 }>;
 export default reactWrapper;

package/dist/react/listbox/index.d.ts

@@ -0,0 +1,30 @@
+import { type EventName } from '@lit/react';
+import Component from '../../components/listbox';
+/**
+ * listbox component presents a list of options and allows a user to select one of them.
+ *
+ * Notes:
+ * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.
+ * - this component has name and value attributes and also emits change event,
+ *   but it is not a form control (yet).
+ *
+ * @dependency mdc-list
+ * @dependency mdc-icon
+ * @dependency mdc-text
+ * @dependency mdc-option
+ * @dependency mdc-optgroup
+ *
+ * @tagname mdc-listbox
+ *
+ * @cssproperty --mdc-listbox-max-height - max height of the listbox
+ *
+ * @slot default - This is a default/unnamed slot, where options and optgroups are placed
+ *
+ * @csspart container - The container of the listbox
+ *
+ * @event change - (React: onChange) This event is emitted when the selected item changed
+ */
+declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {
+    onChange: EventName<import("../../components/listbox/listbox.types").ListBoxChangeEvent>;
+}>;
+export default reactWrapper;

package/dist/react/listbox/index.js

@@ -0,0 +1,38 @@
+import * as React from 'react';
+import { createComponent } from '@lit/react';
+import Component from '../../components/listbox';
+import { TAG_NAME } from '../../components/listbox/listbox.constants';
+/**
+ * listbox component presents a list of options and allows a user to select one of them.
+ *
+ * Notes:
+ * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.
+ * - this component has name and value attributes and also emits change event,
+ *   but it is not a form control (yet).
+ *
+ * @dependency mdc-list
+ * @dependency mdc-icon
+ * @dependency mdc-text
+ * @dependency mdc-option
+ * @dependency mdc-optgroup
+ *
+ * @tagname mdc-listbox
+ *
+ * @cssproperty --mdc-listbox-max-height - max height of the listbox
+ *
+ * @slot default - This is a default/unnamed slot, where options and optgroups are placed
+ *
+ * @csspart container - The container of the listbox
+ *
+ * @event change - (React: onChange) This event is emitted when the selected item changed
+ */
+const reactWrapper = createComponent({
+    tagName: TAG_NAME,
+    elementClass: Component,
+    react: React,
+    events: {
+        onChange: 'change',
+    },
+    displayName: 'ListBox',
+});
+export default reactWrapper;

package/dist/react/password/index.d.ts

@@ -42,10 +42,10 @@ import Component from '../../components/password';
  *
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {
-    onInput: EventName<import("../../utils/types").OverrideEventTarget<InputEvent, import("../../components/input/input.component").default>>;
+    onInput: EventName<import("../../components/input/input.types").InputInputEvent>;
     onChange: EventName<import("../../components/input/input.types").InputChangeEvent>;
-    onFocus: EventName<import("../../utils/types").OverrideEventTarget<FocusEvent, import("../../components/input/input.component").default>>;
-    onBlur: EventName<import("../../utils/types").OverrideEventTarget<FocusEvent, import("../../components/input/input.component").default>>;
+    onFocus: EventName<import("../../components/input/input.types").InputFocusEvent>;
+    onBlur: EventName<import("../../components/input/input.types").InputBlurEvent>;
     onClear: EventName<import("../../components/input/input.types").InputClearEvent>;
 }>;
 export default reactWrapper;

package/dist/react/searchfield/index.d.ts

@@ -18,10 +18,10 @@ import Component from '../../components/searchfield';
  * @slot filters - Slot for input chips
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {
-    onInput: EventName<import("../../utils/types").OverrideEventTarget<InputEvent, import("../../components/input/input.component").default>>;
+    onInput: EventName<import("../../components/input/input.types").InputInputEvent>;
     onChange: EventName<import("../../components/input/input.types").InputChangeEvent>;
-    onFocus: EventName<import("../../utils/types").OverrideEventTarget<FocusEvent, import("../../components/input/input.component").default>>;
-    onBlur: EventName<import("../../utils/types").OverrideEventTarget<FocusEvent, import("../../components/input/input.component").default>>;
+    onFocus: EventName<import("../../components/input/input.types").InputFocusEvent>;
+    onBlur: EventName<import("../../components/input/input.types").InputBlurEvent>;
     onClear: EventName<import("../../components/input/input.types").InputClearEvent>;
 }>;
 export default reactWrapper;

package/dist/utils/controllers/ElementStore.d.ts

@@ -0,0 +1,153 @@
+import { ReactiveController } from 'lit';
+import type { Component } from '../../models';
+export type ElementStoreChangeTypes = 'added' | 'removed';
+interface ElementStoreOptions {
+    /**
+     * - A function to determine if an item is valid for caching.
+     */
+    isValidItem: (item: any) => boolean;
+}
+/**
+ * ElementStore is a controller that manages a collection of elements.
+ *
+ * @example
+ * ```ts
+ * // Add and remove item based on the disabled state
+ * class Container extends Component {
+ *    private this.store = new ElementStore<HTMLLIElement>(this, {
+ *       validItemPredicate: (item) => item.matches('li:not([disabled])')
+ *    });
+ *
+ *    constructor() {
+ *      super();
+ *      this.addEventListener('modified', this.handleModifiedEvent);
+ *    }
+ *
+ *    handleModifiedEvent(event: LifeCycleModifiedEvent) {
+ *      if (event.details.change === 'enabled') {
+ *         this.store.addItemToCacheAt(event.target);
+ *      } else if (event.details.change === 'disabled') {
+ *         this.store.removeItemFromCache(event.target)
+ *      }
+ *    }
+ * }
+ * ```
+ */
+export declare class ElementStore<TItem extends HTMLElement> implements ReactiveController {
+    private host;
+    /**
+     * Checks if the item is valid.
+     * Invalid items will not be collected or processed.
+     * This method can be overridden by subclasses to define custom validation logic.
+     *
+     * @param item - The item to validate.
+     * @returns - True if the item is valid, false otherwise.
+     */
+    private readonly isValidItem;
+    /** Stored items */
+    private cache;
+    /** Access to stored items */
+    get items(): TItem[];
+    /**
+     * Creates an instance of ElementStore.
+     * This controller manages a collection of elements, allowing for
+     * adding and removing items based on lifecycle events.
+     *
+     * A component can have multiple ElementStore controllers
+     *
+     * All ElementStore must be created before any `addEventListener` in the constructor, see the example.
+     *
+     * Note: This controller relies on `created` and `destroyed` events.
+     * For the best result, dispatch these events on the child components or use the `LifeCycleMixin` mixin.
+     * And make sure the `destroyed` event properly propagated to the host, `CaptureDestroyEventForChildElement` mixin
+     * can help with that.
+     *
+     * @example
+     * ```ts
+     * class Container extends CaptureDestroyEventForChildElement(Component) {
+     *  private itemsStore = new ElementStore<Item>(this, {
+     *     isValidItem: this.isValidItem,
+     *  });
+     *
+     *  constructor() {
+     *     super()
+     *     this.addEventListener('modified', this.handleModifiedEvent);
+     *  }
+     *
+     *  private handleModifiedEvent(event: LifeCycleModifiedEvent) {
+     *     const item = event.target as Item;
+     *
+     *     switch (event.detail.change) {
+     *       case 'enabled':  return this.itemsStore.add(item);
+     *       case 'disabled': return this.itemsStore.delete(item);
+     *     }
+     *  }
+     *
+     *  private isValidItem(item: Element): boolean {
+     *     return item.matches(`${ITEM_TAGNAME}:not([disabled])`);
+     *  }
+     * ```
+     *
+     * @param host - The host component that this controller is attached to.
+     * @param options - Element store options
+     */
+    constructor(host: Component, options?: ElementStoreOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /**
+     * Handles the item creation event.
+     *
+     * @param event - The event triggered when an item is created.
+     */
+    protected itemCreationHandler: (event: Event) => void;
+    /**
+     * Handles the item destroy event.
+     *
+     * @param event - The event triggered when an item is destroyed.
+     */
+    protected itemDestroyHandler: (event: Event) => void;
+    /**
+     * Adds an item to the cache.
+     * If the item is valid and not already in the cache, it will be added at the end of the cache.
+     *
+     * It uses the `compareDocumentPosition` method to determine the correct order of the items in the cache.
+     * @see [compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition)
+     *
+     * @param newItem - The item to add to the cache.
+     */
+    add(newItem: Element): void;
+    /**
+     * Adds an item to the cache.
+     * If the item is valid and not already in the cache, it will be added to the specified index.
+     *
+     * @param newItem - The item to add to the cache.
+     * @param index - The index at which to add the item.
+     */
+    addAt(newItem: Element, index: number): void;
+    /**
+     * Adds an item to the cache at the specified index.
+     * When the index
+     *  is `undefined`, the item is added automatically keeping the DOM order.
+     *  is `-1`, the item is added to the end of the cache.
+     *  is `>= 0`, the item is added at that index.
+     *  otherwise, do nothing.
+     *
+     * @param item - The item to add to the cache.
+     * @param index - The index at which to add the item. If `undefined`, the item is added automatically.
+     */
+    private addItem;
+    /**
+     * Removes an item from the cache.
+     *
+     * @param item - The item to remove from the cache.
+     */
+    delete(item: Element): void;
+    /**
+     * Sets the item cache to the provided items.
+     * If no items are provided, it clears the cache.
+     *
+     * @param items - The items to set in the cache.
+     */
+    protected reset(items: TItem[]): void;
+}
+export {};

package/dist/utils/controllers/ElementStore.js

@@ -0,0 +1,171 @@
+import { LIFE_CYCLE_EVENTS } from '../mixins/lifecycle/lifecycle.contants';
+import { isBefore } from '../dom';
+const defaultIsValidFn = (item) => !!item;
+/**
+ * ElementStore is a controller that manages a collection of elements.
+ *
+ * @example
+ * ```ts
+ * // Add and remove item based on the disabled state
+ * class Container extends Component {
+ *    private this.store = new ElementStore<HTMLLIElement>(this, {
+ *       validItemPredicate: (item) => item.matches('li:not([disabled])')
+ *    });
+ *
+ *    constructor() {
+ *      super();
+ *      this.addEventListener('modified', this.handleModifiedEvent);
+ *    }
+ *
+ *    handleModifiedEvent(event: LifeCycleModifiedEvent) {
+ *      if (event.details.change === 'enabled') {
+ *         this.store.addItemToCacheAt(event.target);
+ *      } else if (event.details.change === 'disabled') {
+ *         this.store.removeItemFromCache(event.target)
+ *      }
+ *    }
+ * }
+ * ```
+ */
+export class ElementStore {
+    /** Access to stored items */
+    get items() {
+        return this.cache;
+    }
+    /**
+     * Creates an instance of ElementStore.
+     * This controller manages a collection of elements, allowing for
+     * adding and removing items based on lifecycle events.
+     *
+     * A component can have multiple ElementStore controllers
+     *
+     * All ElementStore must be created before any `addEventListener` in the constructor, see the example.
+     *
+     * Note: This controller relies on `created` and `destroyed` events.
+     * For the best result, dispatch these events on the child components or use the `LifeCycleMixin` mixin.
+     * And make sure the `destroyed` event properly propagated to the host, `CaptureDestroyEventForChildElement` mixin
+     * can help with that.
+     *
+     * @example
+     * ```ts
+     * class Container extends CaptureDestroyEventForChildElement(Component) {
+     *  private itemsStore = new ElementStore<Item>(this, {
+     *     isValidItem: this.isValidItem,
+     *  });
+     *
+     *  constructor() {
+     *     super()
+     *     this.addEventListener('modified', this.handleModifiedEvent);
+     *  }
+     *
+     *  private handleModifiedEvent(event: LifeCycleModifiedEvent) {
+     *     const item = event.target as Item;
+     *
+     *     switch (event.detail.change) {
+     *       case 'enabled':  return this.itemsStore.add(item);
+     *       case 'disabled': return this.itemsStore.delete(item);
+     *     }
+     *  }
+     *
+     *  private isValidItem(item: Element): boolean {
+     *     return item.matches(`${ITEM_TAGNAME}:not([disabled])`);
+     *  }
+     * ```
+     *
+     * @param host - The host component that this controller is attached to.
+     * @param options - Element store options
+     */
+    constructor(host, options) {
+        /** Stored items */
+        this.cache = [];
+        /**
+         * Handles the item creation event.
+         *
+         * @param event - The event triggered when an item is created.
+         */
+        this.itemCreationHandler = (event) => {
+            this.addItem(event.target, undefined);
+        };
+        /**
+         * Handles the item destroy event.
+         *
+         * @param event - The event triggered when an item is destroyed.
+         */
+        this.itemDestroyHandler = (event) => {
+            this.delete(event.target);
+        };
+        this.host = host;
+        host.addController(this);
+        this.isValidItem = (options === null || options === void 0 ? void 0 : options.isValidItem) || defaultIsValidFn;
+        this.host.addEventListener(LIFE_CYCLE_EVENTS.CREATED, this.itemCreationHandler);
+        this.host.addEventListener(LIFE_CYCLE_EVENTS.DESTROYED, this.itemDestroyHandler);
+    }
+    hostConnected() { }
+    hostDisconnected() { }
+    /**
+     * Adds an item to the cache.
+     * If the item is valid and not already in the cache, it will be added at the end of the cache.
+     *
+     * It uses the `compareDocumentPosition` method to determine the correct order of the items in the cache.
+     * @see [compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition)
+     *
+     * @param newItem - The item to add to the cache.
+     */
+    add(newItem) {
+        this.addItem(newItem, undefined);
+    }
+    /**
+     * Adds an item to the cache.
+     * If the item is valid and not already in the cache, it will be added to the specified index.
+     *
+     * @param newItem - The item to add to the cache.
+     * @param index - The index at which to add the item.
+     */
+    addAt(newItem, index) {
+        this.addItem(newItem, index);
+    }
+    /**
+     * Adds an item to the cache at the specified index.
+     * When the index
+     *  is `undefined`, the item is added automatically keeping the DOM order.
+     *  is `-1`, the item is added to the end of the cache.
+     *  is `>= 0`, the item is added at that index.
+     *  otherwise, do nothing.
+     *
+     * @param item - The item to add to the cache.
+     * @param index - The index at which to add the item. If `undefined`, the item is added automatically.
+     */
+    addItem(item, index = undefined) {
+        const newItem = item;
+        if (this.isValidItem(newItem) && !this.cache.includes(newItem)) {
+            const idx = index === undefined ? this.cache.findIndex(e => isBefore(newItem, e)) : index;
+            if (idx === -1) {
+                this.cache.push(newItem);
+            }
+            else if (idx >= 0) {
+                this.cache.splice(idx, 0, newItem);
+            }
+        }
+    }
+    /**
+     * Removes an item from the cache.
+     *
+     * @param item - The item to remove from the cache.
+     */
+    delete(item) {
+        const idx = this.cache.indexOf(item);
+        if (idx !== -1) {
+            this.cache.splice(idx, 1);
+        }
+    }
+    /**
+     * Sets the item cache to the provided items.
+     * If no items are provided, it clears the cache.
+     *
+     * @param items - The items to set in the cache.
+     */
+    reset(items) {
+        this.cache.length = 0;
+        this.cache.push(...(items || []));
+    }
+}

package/dist/utils/dom.d.ts

@@ -0,0 +1,13 @@
+/**
+ * nodeB follows nodeA in either a pre-order depth-first traversal of a tree containing both
+ * (e.g., as a descendant or following sibling or a descendant of a following sibling or
+ * following sibling of an ancestor) or (if they are disconnected) in an arbitrary but
+ * consistent ordering.
+ *
+ * @param nodeA - The first node to compare.
+ * @param nodeB - The second node to compare.
+ * @returns - True if nodeA is before nodeB, false otherwise.
+ *
+ * @see [compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition)
+ */
+export declare const isBefore: (nodeA: Element, nodeB: Element) => boolean;

package/dist/utils/dom.js

@@ -0,0 +1,14 @@
+/* eslint-disable max-classes-per-file,no-bitwise */
+/**
+ * nodeB follows nodeA in either a pre-order depth-first traversal of a tree containing both
+ * (e.g., as a descendant or following sibling or a descendant of a following sibling or
+ * following sibling of an ancestor) or (if they are disconnected) in an arbitrary but
+ * consistent ordering.
+ *
+ * @param nodeA - The first node to compare.
+ * @param nodeB - The second node to compare.
+ * @returns - True if nodeA is before nodeB, false otherwise.
+ *
+ * @see [compareDocumentPosition](https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition)
+ */
+export const isBefore = (nodeA, nodeB) => !!(nodeA.compareDocumentPosition(nodeB) & Node.DOCUMENT_POSITION_FOLLOWING);

package/dist/utils/mixins/ItemCollectionMixin.d.ts

@@ -0,0 +1,68 @@
+import type { LitElement } from 'lit';
+import type { Constructor } from './index.types';
+export declare class ItemCollectionMixinInterface<TItem> {
+    /**
+     * List of items (cached)
+     */
+    get items(): TItem[];
+    /**
+     * Checks if the item is valid.
+     * Invalid items will not be collected or processed.
+     * This method can be overridden by subclasses to define custom validation logic.
+     *
+     * @param item - The item to validate.
+     * @returns - True if the item is valid, false otherwise.
+     */
+    protected isValidItem(item: Element): boolean;
+    /**
+     * Adds an item to the cache at the specified index.
+     * When the index
+     *  is `undefined`, the item is added automatically keeping the DOM order.
+     *  is `-1`, the item is added to the end of the cache.
+     *  is `>= 0`, the item is added at that index.
+     *  otherwise, do nothing.
+     *
+     * @param item - The item to add to the cache.
+     * @param index - The index at which to add the item. If -1, adds to the end.
+     */
+    protected addItemToCacheAt(item: Element, index?: number): void;
+    /**
+     * Removes an item from the cache.
+     *
+     * @param item - The item to remove from the cache.
+     */
+    protected removeItemFromCache(item: Element): void;
+    /**
+     * Sets the item cache to the provided items.
+     * If no items are provided, it clears the cache.
+     *
+     * @param items - The items to set in the cache.
+     */
+    protected setItemCache(items?: TItem[]): void;
+}
+/**
+ * This mixin collects and cache items based on the `created` and `destroyed` lifecycle events.
+ * Also provides methods to manage the item cache.
+ *
+ * @example
+ * ```ts
+ * // Add and remove item based on the disabled state
+ * class ListBox extends ItemCollectionMixin<Option, typeof Component>(Component) {
+ *    constructor() {
+ *      super();
+ *      this.addEventListener('modified', this.handleModifiedEvent);
+ *    }
+ *
+ *    handleModifiedEvent(event: LifeCycleModifiedEvent) {
+ *      if (event.details.change === 'enabled') {
+ *         this.addItemToCacheAt(event.target);
+ *      } else if (event.details.change === 'disabled') {
+ *         this.removeItemFromCache(event.target)
+ *      }
+ *    }
+ * }
+ * ```
+ *
+ * @param superClass - The class to extend with the mixin.
+ */
+export declare const ItemCollectionMixin: <TItem extends HTMLElement, T extends Constructor<LitElement>>(superClass: T) => Constructor<ItemCollectionMixinInterface<TItem>> & T;