@momentum-design/components 0.122.6 → 0.122.7

package/dist/components/list/list.component.d.ts

@@ -1,5 +1,8 @@
 import type { CSSResult } from 'lit';
 import { Component } from '../../models';
+import { ElementStoreChangeTypes } from '../../utils/controllers/ElementStore';
+import type ListItem from '../listitem';
+import type { BaseArray } from '../../utils/virtualIndexArray';
 declare const List_base: import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/ListNavigationMixin").ListNavigationMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/lifecycle/CaptureDestroyEventForChildElement").CaptureDestroyEventForChildElementInterface> & typeof Component;
 /**
  * mdc-list component is used to display a group of list items. It is used as a container to wrap other list items.
@@ -25,39 +28,31 @@ declare class List extends List_base {
      * and pressing the up arrow on the first item will focus the last item.
      * If 'false', navigation will stop at the first or last item.
      *
-     * @default ''
+     * @default 'true'
      */
     loop: 'true' | 'false';
     /**
      * The index of the item that should receive focus when the list is first rendered.
-     * If the index is out of bounds, the first item (index 0) will receive focus.
+     * If the index is out of bounds, the focused element will be clamped to the nearest valid index.
      *
      * @default 0
      */
     initialFocus: number;
+    /** @internal */
+    protected focusWithin: boolean;
     constructor();
     connectedCallback(): void;
     /**
      * @internal
      */
-    get navItems(): HTMLElement[];
-    /**
-     * Update the tabIndex of the list items when a new item is added.
-     *
-     * @internal
-     */
-    private handleCreatedEvent;
-    /**
-     * Update the focus when an item is removed.
-     * If there is a next item, focus it. If not, focus the previous item.
-     *
-     * @internal
-     */
-    private handleDestroyEvent;
+    protected get navItems(): BaseArray<HTMLElement>;
+    protected onElementStoreUpdate(item: ListItem, changeType: ElementStoreChangeTypes, index: number): void;
+    /** @internal */
+    private handleFocusEvent;
     /** @internal */
     private handleModifiedEvent;
     /** @internal */
-    private isValidItem;
+    protected isValidItem(item: Element): boolean;
     render(): import("lit-html").TemplateResult<1>;
     static styles: Array<CSSResult>;
 }

package/dist/components/list/list.component.js

@@ -40,49 +40,18 @@ class List extends ListNavigationMixin(CaptureDestroyEventForChildElement(Compon
          * and pressing the up arrow on the first item will focus the last item.
          * If 'false', navigation will stop at the first or last item.
          *
-         * @default ''
+         * @default 'true'
          */
         this.loop = DEFAULTS.LOOP;
         /**
          * The index of the item that should receive focus when the list is first rendered.
-         * If the index is out of bounds, the first item (index 0) will receive focus.
+         * If the index is out of bounds, the focused element will be clamped to the nearest valid index.
          *
          * @default 0
          */
         this.initialFocus = DEFAULTS.INITIAL_FOCUS;
-        /**
-         * Update the tabIndex of the list items when a new item is added.
-         *
-         * @internal
-         */
-        this.handleCreatedEvent = (event) => {
-            const createdElement = event.target;
-            if (!this.isValidItem(createdElement)) {
-                return;
-            }
-            createdElement.tabIndex = -1;
-        };
-        /**
-         * Update the focus when an item is removed.
-         * If there is a next item, focus it. If not, focus the previous item.
-         *
-         * @internal
-         */
-        this.handleDestroyEvent = (event) => {
-            const destroyedElement = event.detail.originalTarget;
-            if (!this.isValidItem(destroyedElement) || destroyedElement.tabIndex !== 0) {
-                return;
-            }
-            const destroyedItemIndex = this.navItems.findIndex(node => node === destroyedElement);
-            if (destroyedItemIndex === -1) {
-                return;
-            }
-            let newIndex = destroyedItemIndex + 1;
-            if (newIndex >= this.navItems.length) {
-                newIndex = destroyedItemIndex - 1;
-            }
-            this.resetTabIndexes(newIndex);
-        };
+        /** @internal */
+        this.focusWithin = false;
         /** @internal */
         this.handleModifiedEvent = (event) => {
             const item = event.target;
@@ -97,19 +66,19 @@ class List extends ListNavigationMixin(CaptureDestroyEventForChildElement(Compon
                     break;
             }
         };
-        this.addEventListener(LIFE_CYCLE_EVENTS.CREATED, this.handleCreatedEvent);
         this.addEventListener(LIFE_CYCLE_EVENTS.MODIFIED, this.handleModifiedEvent);
-        this.addEventListener(LIFE_CYCLE_EVENTS.DESTROYED, this.handleDestroyEvent);
+        this.addEventListener('focusin', this.handleFocusEvent);
+        this.addEventListener('focusout', this.handleFocusEvent);
         // This must be initialized after the destroyed event listener
         // to keep the element in the itemStore in order to move the focus correctly
         this.itemsStore = new ElementStore(this, {
             isValidItem: this.isValidItem,
+            onStoreUpdate: this.onElementStoreUpdate.bind(this),
         });
     }
     connectedCallback() {
         super.connectedCallback();
-        // Set the role attribute for accessibility.
-        this.setAttribute('role', ROLE.LIST);
+        this.role = ROLE.LIST;
     }
     /**
      * @internal
@@ -117,6 +86,27 @@ class List extends ListNavigationMixin(CaptureDestroyEventForChildElement(Compon
     get navItems() {
         return this.itemsStore.items;
     }
+    onElementStoreUpdate(item, changeType, index) {
+        if (changeType === 'added') {
+            // Update the tabIndex of the list items when a new item is added.
+            // eslint-disable-next-line no-param-reassign
+            item.tabIndex = -1;
+        }
+        else if (changeType === 'removed' && item.tabIndex === 0) {
+            let newIndex = index + 1;
+            if (newIndex >= this.navItems.length) {
+                newIndex = index - 1;
+            }
+            this.resetTabIndexes(newIndex, this.focusWithin);
+        }
+    }
+    /** @internal */
+    handleFocusEvent(event) {
+        // If previously focused element is being removed from the DOM, ignore the focusout event
+        if (!(event.type === 'focusout' && event.relatedTarget === null)) {
+            this.focusWithin = event.type === 'focusin';
+        }
+    }
     /** @internal */
     isValidItem(item) {
         return item.matches(`${LISTITEM_TAGNAME}:not([disabled])`);

package/dist/components/listitem/listitem.component.d.ts

@@ -106,6 +106,16 @@ declare class ListItem extends ListItem_base {
      * @default undefined
      */
     softDisabled?: boolean;
+    /**
+     * Data attribute to define the index of the list item in a list.
+     * This also set the `aria-posinset` attribute for accessibility purposes.
+     *
+     * It is required when the list item is used inside a virtualized list where the items are not sequentially rendered.
+     * It should be a zero-based index.
+     *
+     * @default undefined
+     */
+    dataIndex?: number;
     constructor();
     connectedCallback(): void;
     /**

package/dist/components/listitem/listitem.component.js

@@ -183,6 +183,9 @@ class ListItem extends DisabledMixin(TabIndexMixin(LifeCycleMixin(Component))) {
         if (changedProperties.has('softDisabled')) {
             this.disableSlottedChildren(this.softDisabled);
         }
+        if (changedProperties.has('dataIndex')) {
+            this.ariaPosInSet = `${this.dataIndex !== undefined ? this.dataIndex + 1 : ''}`;
+        }
     }
     /**
      * Renders the trailing controls slot.
@@ -280,4 +283,8 @@ __decorate([
     property({ type: Boolean, reflect: true, attribute: 'soft-disabled' }),
     __metadata("design:type", Boolean)
 ], ListItem.prototype, "softDisabled", void 0);
+__decorate([
+    property({ type: Number, reflect: true, attribute: 'data-index' }),
+    __metadata("design:type", Number)
+], ListItem.prototype, "dataIndex", void 0);
 export default ListItem;

package/dist/components/virtualizedlist/virtualizedlist.component.d.ts

@@ -1,91 +1,294 @@
-import { CSSResult, PropertyValues, TemplateResult } from 'lit';
-import { Virtualizer, VirtualItem } from '@tanstack/virtual-core';
-import { Ref } from 'lit/directives/ref.js';
-import { Component } from '../../models';
-import { SetListDataProps, VirtualizerProps } from './virtualizedlist.types';
+import { type CSSResult, type PropertyValues } from 'lit';
+import { type Range, ScrollToOptions, type VirtualItem } from '@tanstack/virtual-core';
+import List from '../list/list.component';
+import type { ElementStoreChangeTypes } from '../../utils/controllers/ElementStore';
+import { type BaseArray } from '../../utils/virtualIndexArray';
+import { VirtualizerProps, Virtualizer } from './virtualizedlist.types';
+declare const VirtualizedList_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DataAriaLabelMixin").DataAriaLabelMixinInterface> & typeof List;
 /**
- * `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 class VirtualizedList extends Component {
+declare class VirtualizedList extends VirtualizedList_base {
     /**
      * Object that sets and updates the virtualizer with any relevant props.
-     * There are two required object props in order to get virtualization to work properly.
-     * count - The length of your list that you are virtualizing.
+     * There are three required object props in order to get virtualization to work properly.
+     *
+     * **count** - The length of your list that you are virtualizing.
      * As your list grows/shrinks, this component must be updated with the appropriate value
      * (Same with any other updated prop).
-     * estimateSize - A function that returns the estimated size of your items.
+     *
+     * **estimateSize** - A function that returns the estimated size of your items.
      * If your list is fixed, this will just be the size of your items.
      * If your list is dynamic, try to return approximate the size of each item.
      *
+     * **getItemKey** - A function that returns a unique key for each item in your list based on its index.
+     *
      * A full list of possible props can be in
      * [Tanstack Virtualizer API Docs](https://tanstack.com/virtual/latest/docs/api/virtualizer)
      *
      */
     virtualizerProps: VirtualizerProps;
     /**
-     * Callback that gets envoked when updates to the virtualizer interally occur.
-     * This must be implemented in such a way that this function will trigger update to parent.
+     * Whether to loop navigation when reaching the end of the list.
+     * If 'true', pressing the down arrow on the last item will focus the first item,
+     * and pressing the up arrow on the first item will focus the last item.
+     * If 'false', navigation will stop at the first or last item.
+     *
+     * @default 'false'
+     */
+    loop: 'true' | 'false';
+    /**
+     * Enable automatic scroll anchoring when the list size changes.
+     * By default, list does not scroll to the very end it keeps the scroll position otherwise
+     * it try hold the scroll position on the last selected when list updates.
+     *
+     * It is handy when list size or list item sizes change dynamically (e.g., incoming messages in a chat app).
      *
-     * virtualItems - Array that will be what the client displays on screen. Use this to render
-     * a List of your choosing with these items nested inside as your ListItems.
-     * measureElement - Ref to pass to each ListItem rendered client side.
-     * Each ListItem should also be be passed key and a data-index (which can be found on the virtualItem).
-     * listStyle - This should be passed as the style attribute to your List.
+     * @default false
+     */
+    scrollAnchoring: boolean;
+    /**
+     * When true, the list will observe size changes of its items and re-measure them as needed.
+     * This is useful if your list items can change size dynamically (e.g., due to content changes or window resizing).
      */
-    setlistdata: (({ virtualItems, measureElement, listStyle }: SetListDataProps) => void) | null;
+    observeSizeChanges: boolean;
+    /**
+     * When true, the list items will be aligned to the bottom of the list, and it anchors scroll to the bottom
+     * until the first user scroll interaction.
+     *
+     * Note: It does not affect on the rendering order, the first item is still at the top of the list.
+     */
+    revertList: boolean;
+    /**
+     * The maximum gap (in pixels) between the very bottom of the list end the current scroll positioning
+     * It is used to calculate scroll anchoring.
+     */
+    atBottomThreshold: number;
+    /**
+     * The virtualizer instance created by the VirtualizerController.
+     */
+    virtualizer: Virtualizer | null;
+    /**
+     * The current virtual items being rendered.
+     */
+    get virtualItems(): VirtualItem[];
+    /**
+     * @internal
+     */
+    private virtualizedNavItems;
+    /**
+     * @internal
+     */
+    protected get navItems(): BaseArray<HTMLElement>;
+    /**
+     * A ref to the scrollable element within the list.
+     * @internal
+     */
+    private scrollRef;
+    /**
+     * Container wrapper ref
+     * @internal
+     */
+    private wrapperRef;
+    /**
+     * The container element that holds the virtualized list items.
+     * @internal
+     */
+    private containerRef;
     /**
      * @internal
      */
     private virtualizerController;
-    scrollElementRef: Ref<HTMLDivElement>;
-    virtualizer: Virtualizer<Element, Element> | null;
-    virtualItems: Array<VirtualItem>;
+    /**
+     * The currently selected index in the list.
+     * If keyboard navigation is being used, this will be the focused item.
+     * If the list is clicked, this will be the last clicked item.
+     * @internal
+     */
+    private selectedIndex;
+    /**
+     * The key of the currently selected item.
+     * This is used to keep track where the selected item goes when the list changes size.
+     * @internal
+     */
+    private selectedKey;
+    /**
+     * The index of the first item in the current virtual items.
+     * @internal
+     */
+    private firstIndex;
+    /**
+     * The key of the first item in the current virtual items.
+     * @internal
+     */
+    private firstKey;
+    /**
+     * The indexes of items that are not in the current virtual items, but need to be rendered for focus purposes.
+     * @internal
+     */
+    private hiddenIndexes;
+    /**
+     * Is the scroll position at the bottom of the list?
+     *
+     * - 'no' - The scroll position is not at the bottom of the list.
+     * - 'yes' - The scroll position is at the bottom of the list.
+     * - 're-evaluate' - The scroll position needs to be re-evaluated on the next scroll event.
+     * @internal
+     */
+    private atBottomValue;
+    /**
+     * Getter for atBottom
+     * @internal
+     */
+    private get atBottom();
+    /**
+     * Setter for atBottom to handle side effects when the value changes.
+     * @param value - new value for atBottom
+     *
+     * @internal
+     */
+    private set atBottom(value);
+    /**
+     * rAF ID for the scroll to bottom action when atBottom is 'yes'.
+     * @internal
+     */
+    private atBottomTimer;
+    /**
+     * The total height of the list based on the virtualizer's calculations.
+     * @internal
+     */
+    private get totalListHeight();
+    /**
+     * Last recorded scroll position to help determine scroll direction.
+     * @internal
+     */
+    private lastScrollPosition;
+    /**
+     * List of functions executed aster the virtualizer finishes scrolling.
+     * @internal
+     */
+    private endOfScrollQueue;
     constructor();
+    /**
+     * Create the virtualizer controller and the virtualizer instance when the component is first connected to the DOM.
+     */
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     /**
      * This override is necessary to update the virtualizer with relevant props
      * if the client updates any props (most commonly, count). Updating the options
      * this way ensures we don't initialize a new virtualizer upon very prop change.
      */
-    update(changedProperties: PropertyValues): void;
+    update(changedProperties: PropertyValues<this>): Promise<void>;
+    /**
+     * Handles updates to the virtualizerProps property.
+     * @param prevProps - The previous virtualizerProps before the update.
+     * @internal
+     */
+    handleVirtualizerPropsUpdate(prevProps: VirtualizerProps): Promise<void>;
     /**
-     * This is needed in order to ensure the initial render happens
+     * Sets the initial focus of the list based on the `initial-focus` prop and scrolls the item into view.
      */
-    firstUpdated(changedProperties: PropertyValues): void;
+    protected setInitialFocus(): void;
+    private emitChangeEvent;
     /**
+     * Calculates the array of indexes to render. We add the selected index (and +1/-1) if it's
+     * outside the current range so the focus can be kept correctly.
+     *
+     * @param range - The current range of items being rendered
+     * @returns An array of indexes to render, including the selected index if it's outside the current range.
      * @internal
-     * Update virtuailzer with the union of the two virtualizer options (current, passed in).
      */
-    private setVirtualizerOptions;
-    connectedCallback(): void;
+    protected virtualizerRangeExtractor(range: Range): number[];
+    /** @internal */
+    private updateHiddenItemsPosition;
+    /** @internal */
+    private isElementSelected;
+    /** @internal */
+    private setSelectedIndex;
+    protected onElementStoreUpdate(item: HTMLElement, changeType: ElementStoreChangeTypes): void;
+    protected handleElementFirstUpdateCompleted: (event: Event) => void;
     /**
+     * Handle the virtualizer's onChange event to emit the virtualitemschange event
+     * This is called when the internal state of the virtualizer changes.
+     *
      * @internal
-     * Renders the list wrapper and invokes the callback which eventually will render in the slot.
-     * Uses getTotalSize to update the height of the wrapper. This value is equal to the total size
-     * OR the total estimated size (if you haven't physically scrolled the entire list)
-     * Passes the virtualItems, measureElement, and listStyle to callback for client to pass in as child
+     */
+    protected onVListStateChangeHandler(_: Virtualizer, isScrolling: boolean): Promise<void>;
+    /**
+     * Refires the scroll event from the internal scroll container to the host element.
+     * Also updates whether the scroll is at the bottom of the list for scroll anchoring purposes.
      *
-     * @returns The template result containing the list wrapper.
+     * @internal
      */
-    private getVirtualizedListWrapper;
+    private onScrollHandler;
+    private checkAtBottom;
+    protected handleNavigationKeyDown(event: KeyboardEvent): void;
+    protected resetTabIndexes(index: number, focusElement?: boolean): void;
+    protected resetTabIndexAndSetFocus(newIndex: number, oldIndex?: number, focusNewItem?: boolean): void;
+    /** @internal */
+    private setAriaSetSize;
     /**
-     * Refires the scroll event from the internal scroll container to the host element
+     * Scrolls to the bottom of the list if `atBottom` is 'yes'.
+     * @internal
      */
-    private handleScroll;
-    render(): TemplateResult<1>;
+    private scrollToBottom;
+    private clearScrollToBottomTimer;
+    scrollToIndex(index: number, options?: ScrollToOptions): void;
+    private syncUI;
+    private handleWheelEvent;
+    render(): import("lit-html").TemplateResult<1>;
     static styles: Array<CSSResult>;
 }
 export default VirtualizedList;