@momentum-design/components 0.122.5 → 0.122.7

package/dist/react/index.d.ts

@@ -9,10 +9,10 @@ export { default as Avatar } from './avatar';
 export { default as AvatarButton } from './avatarbutton';
 export { default as Badge } from './badge';
 export { default as Banner } from './banner';
-export { default as Brandvisual } from './brandvisual';
 export { default as Bullet } from './bullet';
 export { default as Button } from './button';
 export { default as ButtonGroup } from './buttongroup';
+export { default as Brandvisual } from './brandvisual';
 export { default as ButtonLink } from './buttonlink';
 export { default as Buttonsimple } from './buttonsimple';
 export { default as Card } from './card';
@@ -57,8 +57,8 @@ export { default as Popover } from './popover';
 export { default as Presence } from './presence';
 export { default as Progressbar } from './progressbar';
 export { default as Progressspinner } from './progressspinner';
-export { default as RadioGroup } from './radiogroup';
 export { default as Radio } from './radio';
+export { default as RadioGroup } from './radiogroup';
 export { default as ScreenreaderAnnouncer } from './screenreaderannouncer';
 export { default as Searchfield } from './searchfield';
 export { default as Searchpopover } from './searchpopover';
@@ -68,21 +68,21 @@ export { default as SideNavigation } from './sidenavigation';
 export { default as Skeleton } from './skeleton';
 export { default as Slider } from './slider';
 export { default as Spinner } from './spinner';
-export { default as StaticChip } from './staticchip';
 export { default as StaticCheckbox } from './staticcheckbox';
-export { default as StaticToggle } from './statictoggle';
+export { default as StaticChip } from './staticchip';
 export { default as StaticRadio } from './staticradio';
+export { default as StaticToggle } from './statictoggle';
 export { default as Stepper } from './stepper';
 export { default as StepperConnector } from './stepperconnector';
+export { default as StepperItem } from './stepperitem';
 export { default as Tab } from './tab';
 export { default as TabList } from './tablist';
-export { default as StepperItem } from './stepperitem';
-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 Text } from './text';
 export { default as Toggle } from './toggle';
 export { default as ToggleTip } from './toggletip';
-export { default as Toast } from './toast';
 export { default as Tooltip } from './tooltip';
 export { default as Typewriter } from './typewriter';
 export { default as VirtualizedList } from './virtualizedlist';

package/dist/react/index.js

@@ -9,10 +9,10 @@ export { default as Avatar } from './avatar';
 export { default as AvatarButton } from './avatarbutton';
 export { default as Badge } from './badge';
 export { default as Banner } from './banner';
-export { default as Brandvisual } from './brandvisual';
 export { default as Bullet } from './bullet';
 export { default as Button } from './button';
 export { default as ButtonGroup } from './buttongroup';
+export { default as Brandvisual } from './brandvisual';
 export { default as ButtonLink } from './buttonlink';
 export { default as Buttonsimple } from './buttonsimple';
 export { default as Card } from './card';
@@ -57,8 +57,8 @@ export { default as Popover } from './popover';
 export { default as Presence } from './presence';
 export { default as Progressbar } from './progressbar';
 export { default as Progressspinner } from './progressspinner';
-export { default as RadioGroup } from './radiogroup';
 export { default as Radio } from './radio';
+export { default as RadioGroup } from './radiogroup';
 export { default as ScreenreaderAnnouncer } from './screenreaderannouncer';
 export { default as Searchfield } from './searchfield';
 export { default as Searchpopover } from './searchpopover';
@@ -68,21 +68,21 @@ export { default as SideNavigation } from './sidenavigation';
 export { default as Skeleton } from './skeleton';
 export { default as Slider } from './slider';
 export { default as Spinner } from './spinner';
-export { default as StaticChip } from './staticchip';
 export { default as StaticCheckbox } from './staticcheckbox';
-export { default as StaticToggle } from './statictoggle';
+export { default as StaticChip } from './staticchip';
 export { default as StaticRadio } from './staticradio';
+export { default as StaticToggle } from './statictoggle';
 export { default as Stepper } from './stepper';
 export { default as StepperConnector } from './stepperconnector';
+export { default as StepperItem } from './stepperitem';
 export { default as Tab } from './tab';
 export { default as TabList } from './tablist';
-export { default as StepperItem } from './stepperitem';
-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 Text } from './text';
 export { default as Toggle } from './toggle';
 export { default as ToggleTip } from './toggletip';
-export { default as Toast } from './toast';
 export { default as Tooltip } from './tooltip';
 export { default as Typewriter } from './typewriter';
 export { default as VirtualizedList } from './virtualizedlist';

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

@@ -2,23 +2,61 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/virtualizedlist';
 import type { Events } from '../../components/virtualizedlist/virtualizedlist.types';
 /**
- * `mdc-virtualizedlist` component for creating custom virtualized lists.
- * IMPORTANT: This component does not create it's own list/list items.
- * Use the setlistdata callback prop to update client state in order to
- * Pass list/listitems as a child of this component, which this will virtuailze
- * This implementation handles dynamic lists as well as fixed sized lists.
+ * `mdc-virtualizedlist` is an extension of the `mdc-list` component that adds virtualization capabilities using
+ * the Tanstack Virtual library.
+ *
+ * This component is thin wrapper around the Tanstack libray to provide additional funtionalities such as
+ * keyboard navigation, focus management, scroll anchoring and accessibility features.
+ *
  * Please refer to [Tanstack Virtual Docs](https://tanstack.com/virtual/latest) for more in depth documentation.
  *
+ * ## Setup
+ *
+ * `virtualizerProps` is a required prop that requires at least two properties to be set: `count` and `estimateSize`.
+ * `count` is the total number of items in the list, and `estimateSize` is a function that returns the estimated
+ * size (in pixels) of each item in the list. `getItemKey` is also strongly recommended to be set to provide unique
+ * keys for each item in the list.
+ *
+ * ### Render list items
+ *
+ * To keep the component framework-agnostic, the rendering of the list items is left to the consumer.
+ *
+ * We need to render only the visible items. The list of visible items are provided by the `virtualitemschange` event.
+ * The event detail contains the `virtualItems` array, which contains the information for the rendering.
+ * List items must have an `data-index` attribute, the indexes are in the `virtualItems` list.
+ *
+ * ## Best practices
+ *
+ * ### List updates
+ *
+ * Tanstack needs only the count of the items in the list and the size of each item to perform virtualization.
+ * List updates happens when
+ * - when `virtualizerProps` property of the component instance changes
+ * - when `observe-size-changes` is set and the item's size changes (it uses ResizeObserver internally)
+ * - when `component.visualiser.measure` called manually.
+ *
+ * ### Header
+ *
+ * To add a header to the list, use the `mdc-listheader` component and place it in the `list-header` slot.
+ *
+ * ### Lists with dynamic content
+ *
+ * Unique keys for the list items are critical for dynamically changing list items or item's content.
+ * If the key change with the content it will cause scrollbar and content shuttering.
+ *
  * @tagname mdc-virtualizedlist
  *
  * @event scroll - (React: onScroll) Event that gets called when user scrolls inside of list.
+ * @event virtualitemschange - (React: onVirtualItemsChange) Event that gets called when the virtual items change.
  *
- * @slot - Client side List with nested list items.
+ * @slot default - This is a default/unnamed slot, where listitems can be placed.
+ * @slot list-header - This slot is used to pass a header for the list, which can be a `mdc-listheader` component.
  *
  * @csspart container - The container of the virtualized list.
  * @csspart scroll - The scrollable area of the virtualized list.
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {
+    onVirtualItemsChange: EventName<Events["onVirtualItemsChangeEvent"]>;
     onScroll: EventName<Events["onScrollEvent"]>;
 }>;
 export default reactWrapper;

package/dist/react/virtualizedlist/index.js

@@ -3,18 +3,55 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/virtualizedlist';
 import { TAG_NAME } from '../../components/virtualizedlist/virtualizedlist.constants';
 /**
- * `mdc-virtualizedlist` component for creating custom virtualized lists.
- * IMPORTANT: This component does not create it's own list/list items.
- * Use the setlistdata callback prop to update client state in order to
- * Pass list/listitems as a child of this component, which this will virtuailze
- * This implementation handles dynamic lists as well as fixed sized lists.
+ * `mdc-virtualizedlist` is an extension of the `mdc-list` component that adds virtualization capabilities using
+ * the Tanstack Virtual library.
+ *
+ * This component is thin wrapper around the Tanstack libray to provide additional funtionalities such as
+ * keyboard navigation, focus management, scroll anchoring and accessibility features.
+ *
  * Please refer to [Tanstack Virtual Docs](https://tanstack.com/virtual/latest) for more in depth documentation.
  *
+ * ## Setup
+ *
+ * `virtualizerProps` is a required prop that requires at least two properties to be set: `count` and `estimateSize`.
+ * `count` is the total number of items in the list, and `estimateSize` is a function that returns the estimated
+ * size (in pixels) of each item in the list. `getItemKey` is also strongly recommended to be set to provide unique
+ * keys for each item in the list.
+ *
+ * ### Render list items
+ *
+ * To keep the component framework-agnostic, the rendering of the list items is left to the consumer.
+ *
+ * We need to render only the visible items. The list of visible items are provided by the `virtualitemschange` event.
+ * The event detail contains the `virtualItems` array, which contains the information for the rendering.
+ * List items must have an `data-index` attribute, the indexes are in the `virtualItems` list.
+ *
+ * ## Best practices
+ *
+ * ### List updates
+ *
+ * Tanstack needs only the count of the items in the list and the size of each item to perform virtualization.
+ * List updates happens when
+ * - when `virtualizerProps` property of the component instance changes
+ * - when `observe-size-changes` is set and the item's size changes (it uses ResizeObserver internally)
+ * - when `component.visualiser.measure` called manually.
+ *
+ * ### Header
+ *
+ * To add a header to the list, use the `mdc-listheader` component and place it in the `list-header` slot.
+ *
+ * ### Lists with dynamic content
+ *
+ * Unique keys for the list items are critical for dynamically changing list items or item's content.
+ * If the key change with the content it will cause scrollbar and content shuttering.
+ *
  * @tagname mdc-virtualizedlist
  *
  * @event scroll - (React: onScroll) Event that gets called when user scrolls inside of list.
+ * @event virtualitemschange - (React: onVirtualItemsChange) Event that gets called when the virtual items change.
  *
- * @slot - Client side List with nested list items.
+ * @slot default - This is a default/unnamed slot, where listitems can be placed.
+ * @slot list-header - This slot is used to pass a header for the list, which can be a `mdc-listheader` component.
  *
  * @csspart container - The container of the virtualized list.
  * @csspart scroll - The scrollable area of the virtualized list.
@@ -24,6 +61,7 @@ const reactWrapper = createComponent({
     elementClass: Component,
     react: React,
     events: {
+        onVirtualItemsChange: 'virtualitemschange',
         onScroll: 'scroll',
     },
     displayName: 'VirtualizedList',

package/dist/utils/mixins/AutoFocusOnMountMixin.js

@@ -15,7 +15,7 @@ export const AutoFocusOnMountMixin = (superClass) => {
             /**
              * @internal
              */
-            this.elementToAutoFocus = this;
+            this.elementToAutoFocus = null;
             /**
              * This property indicates whether the element should receive focus automatically when it is mounted.
              *
@@ -30,7 +30,7 @@ export const AutoFocusOnMountMixin = (superClass) => {
             if (this.autoFocusOnMount) {
                 // wait for the element to be fully updated before focusing
                 await this.updateComplete;
-                this.elementToAutoFocus.focus();
+                (this.elementToAutoFocus || this).focus();
             }
         }
     }

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

@@ -1,12 +1,15 @@
 import type { Component } from '../../models';
+import type { BaseArray } from '../virtualIndexArray';
 import type { Constructor } from './index.types';
 export declare abstract class ListNavigationMixinInterface {
     protected loop: 'true' | 'false';
     protected propagateAllKeyEvents: boolean;
     protected initialFocus: number;
-    protected abstract get navItems(): HTMLElement[];
-    protected resetTabIndexes(index: number): void;
+    protected abstract get navItems(): BaseArray<HTMLElement>;
+    protected resetTabIndexes(index: number, focusElement?: boolean): void;
     protected resetTabIndexAndSetFocus(newIndex: number, oldIndex?: number, focusNewItem?: boolean): void;
+    protected setInitialFocus(): void;
+    protected handleNavigationKeyDown(event: KeyboardEvent): void;
 }
 /**
  * This mixin extends the passed class with list like navigation capabilities.

package/dist/utils/mixins/ListNavigationMixin.js

@@ -47,64 +47,6 @@ export const ListNavigationMixin = (superClass) => {
              * @internal
              */
             this.initialFocus = 0;
-            /**
-             * Handles keydown events for navigation within the list.
-             * It allows users to navigate through the list items using arrow keys, home, and end keys.
-             * The navigation is based on the current focused item and the direction of the layout (RTL or LTR).
-             *
-             * By default, it will stop propagation for key events which are handled by the component.
-             * Check the mixin options to change this behavior.
-             *
-             * @param event - The keyboard event triggered by user interaction.
-             * @internal
-             */
-            this.handleNavigationKeyDown = (event) => {
-                const keysToHandle = new Set([KEYS.ARROW_DOWN, KEYS.ARROW_UP, KEYS.HOME, KEYS.END]);
-                const isRtl = window.getComputedStyle(this).direction === 'rtl';
-                const targetKey = this.resolveDirectionKey(event.key, isRtl);
-                if (!keysToHandle.has(targetKey)) {
-                    return;
-                }
-                const target = event.target;
-                const currentIndex = this.getCurrentIndex(target);
-                if (currentIndex === -1)
-                    return;
-                this.resetTabIndexes(currentIndex);
-                switch (targetKey) {
-                    case KEYS.HOME: {
-                        // Move focus to the first item
-                        this.resetTabIndexAndSetFocus(0, currentIndex);
-                        break;
-                    }
-                    case KEYS.END: {
-                        // Move focus to the last item
-                        this.resetTabIndexAndSetFocus(this.navItems.length - 1, currentIndex);
-                        break;
-                    }
-                    case KEYS.ARROW_DOWN: {
-                        // Move focus to the next item
-                        const eolIndex = this.shouldLoop() ? 0 : currentIndex;
-                        const newIndex = currentIndex + 1 === this.navItems.length ? eolIndex : currentIndex + 1;
-                        this.resetTabIndexAndSetFocus(newIndex, currentIndex);
-                        break;
-                    }
-                    case KEYS.ARROW_UP: {
-                        // Move focus to the prev item
-                        const eolIndex = this.shouldLoop() ? this.navItems.length - 1 : currentIndex;
-                        const newIndex = currentIndex - 1 === -1 ? eolIndex : currentIndex - 1;
-                        this.resetTabIndexAndSetFocus(newIndex, currentIndex);
-                        break;
-                    }
-                    default:
-                        break;
-                }
-                // When the component consume any of the pressed key, we need to stop propagation
-                // to prevent the event from bubbling up and being handled by parent components which might use the same key.
-                if (!this.propagateAllKeyEvents) {
-                    event.stopPropagation();
-                    event.preventDefault();
-                }
-            };
             /**
              * Handles click events on the navigation items.
              * It retrieves the index of the clicked item and resets the tabindex accordingly.
@@ -118,11 +60,11 @@ export const ListNavigationMixin = (superClass) => {
                 if (newIndex !== -1) {
                     // When user clicked on a focusable element inside the item, we update the navigation index, but
                     // keep the focus on the clicked element.
-                    const focusNewItem = !(this.navItems[newIndex] !== target && document.activeElement === event.target);
+                    const focusNewItem = !(this.navItems.at(newIndex) !== target && document.activeElement === event.target);
                     this.resetTabIndexAndSetFocus(newIndex, undefined, focusNewItem);
                 }
             };
-            this.addEventListener('keydown', this.handleNavigationKeyDown);
+            this.addEventListener('keydown', this.handleNavigationKeyDown.bind(this));
             this.addEventListener('click', this.handleNavigationClick);
         }
         /**
@@ -132,9 +74,70 @@ export const ListNavigationMixin = (superClass) => {
          */
         async firstUpdated(changedProperties) {
             super.firstUpdated(changedProperties);
+            this.setInitialFocus();
+        }
+        setInitialFocus() {
             const indexToFocus = Math.max(Math.min(this.initialFocus, this.navItems.length - 1), 0);
             this.resetTabIndexAndSetFocus(indexToFocus, undefined, false);
         }
+        /**
+         * Handles keydown events for navigation within the list.
+         * It allows users to navigate through the list items using arrow keys, home, and end keys.
+         * The navigation is based on the current focused item and the direction of the layout (RTL or LTR).
+         *
+         * By default, it will stop propagation for key events which are handled by the component.
+         * Check the mixin options to change this behavior.
+         *
+         * @param event - The keyboard event triggered by user interaction.
+         * @internal
+         */
+        handleNavigationKeyDown(event) {
+            const keysToHandle = new Set([KEYS.ARROW_DOWN, KEYS.ARROW_UP, KEYS.HOME, KEYS.END]);
+            const isRtl = window.getComputedStyle(this).direction === 'rtl';
+            const targetKey = this.resolveDirectionKey(event.key, isRtl);
+            if (!keysToHandle.has(targetKey)) {
+                return;
+            }
+            const target = event.target;
+            const currentIndex = this.getCurrentIndex(target);
+            if (currentIndex === -1)
+                return;
+            this.resetTabIndexes(currentIndex);
+            switch (targetKey) {
+                case KEYS.HOME: {
+                    // Move focus to the first item
+                    this.resetTabIndexAndSetFocus(0, currentIndex);
+                    break;
+                }
+                case KEYS.END: {
+                    // Move focus to the last item
+                    this.resetTabIndexAndSetFocus(this.navItems.length - 1, currentIndex);
+                    break;
+                }
+                case KEYS.ARROW_DOWN: {
+                    // Move focus to the next item
+                    const eolIndex = this.shouldLoop() ? 0 : currentIndex;
+                    const newIndex = currentIndex + 1 === this.navItems.length ? eolIndex : currentIndex + 1;
+                    this.resetTabIndexAndSetFocus(newIndex, currentIndex);
+                    break;
+                }
+                case KEYS.ARROW_UP: {
+                    // Move focus to the prev item
+                    const eolIndex = this.shouldLoop() ? this.navItems.length - 1 : currentIndex;
+                    const newIndex = currentIndex - 1 === -1 ? eolIndex : currentIndex - 1;
+                    this.resetTabIndexAndSetFocus(newIndex, currentIndex);
+                    break;
+                }
+                default:
+                    break;
+            }
+            // When the component consume any of the pressed key, we need to stop propagation
+            // to prevent the event from bubbling up and being handled by parent components which might use the same key.
+            if (!this.propagateAllKeyEvents) {
+                event.stopPropagation();
+                event.preventDefault();
+            }
+        }
         /**
          * Retrieves the current index of the item that triggered the event.
          *
@@ -152,14 +155,20 @@ export const ListNavigationMixin = (superClass) => {
          * Reset all tabindex to -1 and set the tabindex of the current item to 0
          *
          * @param index - The index of the currently focused item.
+         * @param focusElement - Call focus() on the current item or not.
          */
-        resetTabIndexes(index) {
+        resetTabIndexes(index, focusElement = true) {
             var _a;
             if (this.navItems.length > 0) {
                 this.navItems.forEach(item => item.setAttribute('tabindex', '-1'));
-                const currentIndex = this.navItems[index] ? index : 0;
-                this.navItems[currentIndex].setAttribute('tabindex', '0');
-                (_a = this.navItems[currentIndex]) === null || _a === void 0 ? void 0 : _a.focus();
+                const currentIndex = this.navItems.at(index) ? index : 0;
+                const currentItem = (_a = this.navItems.at(currentIndex)) !== null && _a !== void 0 ? _a : this.navItems.find(Boolean);
+                if (currentItem) {
+                    currentItem.setAttribute('tabindex', '0');
+                    if (focusElement) {
+                        currentItem.focus();
+                    }
+                }
             }
         }
         /**
@@ -171,21 +180,21 @@ export const ListNavigationMixin = (superClass) => {
          * @returns - This method does not return anything.
          */
         resetTabIndexAndSetFocus(newIndex, oldIndex, focusNewItem = true) {
+            var _a;
             const { navItems } = this;
             if (navItems.length === 0)
                 return;
             // Ensure newIndex is valid
-            const newIdx = navItems[newIndex] ? newIndex : 0;
-            const newItem = navItems[newIdx];
+            const newItem = (_a = navItems.at(newIndex)) !== null && _a !== void 0 ? _a : navItems.find(Boolean);
             if (newIndex === oldIndex && newItem && newItem.getAttribute('tabindex') === '0') {
                 return;
             }
             if (oldIndex === undefined) {
                 navItems.forEach(item => item.setAttribute('tabindex', '-1'));
             }
-            else if (navItems[oldIndex]) {
+            else if (navItems.at(oldIndex)) {
                 // Reset tabindex of the old item
-                navItems[oldIndex].setAttribute('tabindex', '-1');
+                navItems.at(oldIndex).setAttribute('tabindex', '-1');
             }
             newItem.setAttribute('tabindex', '0');
             if (focusNewItem) {

package/dist/utils/mixins/lifecycle/LifeCycleMixin.js

@@ -26,6 +26,10 @@ export const LifeCycleMixin = (superClass) => {
         connectedCallback() {
             super.connectedCallback();
             this.dispatchEvent(new Event(LIFE_CYCLE_EVENTS.CREATED, { bubbles: true, composed: true }));
+            // eslint-disable-next-line @typescript-eslint/no-floating-promises
+            this.updateComplete.then(() => {
+                this.dispatchEvent(new Event(LIFE_CYCLE_EVENTS.FIRST_UPDATE_COMPLETED, { bubbles: true, composed: true }));
+            });
         }
         disconnectedCallback() {
             super.disconnectedCallback();

package/dist/utils/mixins/lifecycle/lifecycle.contants.d.ts

@@ -1,5 +1,6 @@
 export declare const LIFE_CYCLE_EVENTS: {
     readonly CREATED: "created";
+    readonly FIRST_UPDATE_COMPLETED: "first-update-completed";
     readonly DESTROYED: "destroyed";
     readonly MODIFIED: "modified";
 };

package/dist/utils/mixins/lifecycle/lifecycle.contants.js

@@ -1,5 +1,6 @@
 export const LIFE_CYCLE_EVENTS = {
     CREATED: 'created',
+    FIRST_UPDATE_COMPLETED: 'first-update-completed',
     DESTROYED: 'destroyed',
     MODIFIED: 'modified',
 };

package/dist/utils/range.d.ts

@@ -0,0 +1,40 @@
+interface RangeOptions {
+    includeEnd?: boolean;
+}
+/**
+ * Represents a numeric interval between two numbers.
+ *
+ * Start is inclusive, end is exclusive by default.
+ */
+export declare class Interval implements Iterable<number> {
+    /** The start of the Interval (inclusive). */
+    readonly start: number;
+    /** The end of the Interval (exclusive) by default. */
+    readonly end: number;
+    /** Whether the end is inclusive. Default is false (exclusive). */
+    readonly includeEnd: boolean;
+    constructor(start: number, end: number, options?: RangeOptions);
+    /**
+     * Checks if a number is within the Interval.
+     * @param value - The number to check.
+     */
+    includes(value: number): boolean;
+    /**
+     * Returns an iterator for the Interval.
+     *
+     * If the start is greater than the end, it decrements by step.
+     * The iteration stops when the current number reaches or exceeds the end (or equals if includeEnd is true).
+     *
+     * @param step - The step between each number in the Interval. Default is the step defined in the constructor.
+     *        It must be a positive non-zero number.
+     * @returns An iterator that yields numbers from start to end, incremented by step.
+     */
+    iter(step?: number): Iterator<number>;
+    /**
+     * Returns the default iterator for the Interval.
+     *
+     * it steps by 1.
+     */
+    [Symbol.iterator](): Iterator<number, any, any>;
+}
+export {};

package/dist/utils/range.js

@@ -0,0 +1,66 @@
+const DEFAULT_OPTIONS = {
+    includeEnd: false,
+};
+/**
+ * Represents a numeric interval between two numbers.
+ *
+ * Start is inclusive, end is exclusive by default.
+ */
+export class Interval {
+    constructor(start, end, options = {}) {
+        const opt = { ...DEFAULT_OPTIONS, ...options };
+        this.start = start;
+        this.end = end;
+        this.includeEnd = opt.includeEnd;
+    }
+    /**
+     * Checks if a number is within the Interval.
+     * @param value - The number to check.
+     */
+    includes(value) {
+        const { start, end, includeEnd } = this;
+        const min = Math.min(start, end);
+        const max = Math.max(start, end);
+        return includeEnd ? value >= min && value <= max : value >= min && value < max;
+    }
+    /**
+     * Returns an iterator for the Interval.
+     *
+     * If the start is greater than the end, it decrements by step.
+     * The iteration stops when the current number reaches or exceeds the end (or equals if includeEnd is true).
+     *
+     * @param step - The step between each number in the Interval. Default is the step defined in the constructor.
+     *        It must be a positive non-zero number.
+     * @returns An iterator that yields numbers from start to end, incremented by step.
+     */
+    iter(step = 1) {
+        if (step <= 0) {
+            throw new Error('Step must be a positive non-zero number');
+        }
+        const stepper = step * (this.start <= this.end ? 1 : -1);
+        const { includeEnd, end } = this;
+        let current = this.start;
+        let done = false;
+        return {
+            next: () => {
+                if (done)
+                    return { value: undefined, done: true };
+                const value = current;
+                current += stepper;
+                if (includeEnd ? value > end : value >= end) {
+                    done = true;
+                    return { value: undefined, done: true };
+                }
+                return { value, done: false };
+            },
+        };
+    }
+    /**
+     * Returns the default iterator for the Interval.
+     *
+     * it steps by 1.
+     */
+    [Symbol.iterator]() {
+        return this.iter();
+    }
+}

package/dist/utils/virtualIndexArray.d.ts

@@ -0,0 +1,27 @@
+export interface BaseArray<TItem> extends Pick<Array<TItem>, 'length' | 'forEach' | 'findIndex' | 'map' | 'at' | 'find'> {
+}
+/**
+ * A wrapper around an array that applies a "virtual" index to the index when accessing items.
+ * This is useful when the array is just a view of the real data and the real data has gaps in the indexes.
+ *
+ * @example
+ * ```ts
+ * const originalArray = [{realIndex: 2, value: 10}, {realIndex: 3, value: 20}];
+ * const offsetArray = new OffsetArray(originalArray, (item) => item.realIndex);
+ *
+ * console.log(offsetArray.at(0)); // Output: undefined
+ * console.log(offsetArray.at(2).value); // Output: 10
+ * ```
+ */
+export declare class VirtualIndexArray<TItem> implements BaseArray<TItem> {
+    readonly items: BaseArray<TItem>;
+    private readonly getIndex;
+    private lengthFn;
+    constructor(items: BaseArray<TItem>, getIndex: (item: TItem) => number, length: () => number);
+    get length(): number;
+    at(index: number): TItem | undefined;
+    map<U>(cb: (value: TItem, index: number, array: TItem[]) => U, thisArg?: any): U[];
+    forEach(cb: (value: TItem, index: number, array: TItem[]) => void, thisArg?: any): void;
+    findIndex(predicate: (value: TItem, index: number, obj: TItem[]) => boolean, thisArg?: any): number;
+    find(predicate: (value: TItem, index: number, obj: TItem[]) => boolean, thisArg?: any): TItem | undefined;
+}