@momentum-design/components 0.133.13 → 0.133.14

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

@@ -3,7 +3,10 @@ import type Option from '../option';
 import { Component } from '../../models';
 declare const ListBox_base: import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/ListNavigationMixin").ListNavigationMixinInterface & import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface & import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/lifecycle/CaptureDestroyEventForChildElement").CaptureDestroyEventForChildElementInterface> & typeof Component;
 /**
- * listbox component presents a list of options and allows a user to select one of them.
+ * listbox component presents a list of options and allows a user to select one or more of them.
+ *
+ * When `multiple` is enabled, clicking/pressing Enter/Space on an option toggles its selection
+ * instead of replacing the current selection.
  *
  * Notes:
  * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.
@@ -41,6 +44,11 @@ declare class ListBox extends ListBox_base {
      * The value attribute is used to represent the last selected option's value in the listbox.
      */
     value?: undefined | string;
+    /**
+     * When true, multiple options can be selected.
+     * @default false
+     */
+    multiple: boolean;
     /** @internal */
     selectedOption?: Option | null;
     /** @internal */
@@ -62,8 +70,26 @@ declare class ListBox extends ListBox_base {
     private isValidItem;
     /** @internal */
     private handleClick;
+    /**
+     * Toggles the selection state of an option (for multiselect mode).
+     * @internal
+     */
+    private toggleOptionSelection;
     /** @internal */
     private getFirstSelectedOption;
+    /**
+     * Syncs value and selectedOption to reflect the first selected option (when multiple)
+     * @internal
+     */
+    private syncValueToFirstSelected;
+    /** @internal */
+    private getSelectedValues;
+    /**
+     * Override to focus the first selected option per W3C APG.
+     * This applies to both single-select and multi-select listboxes.
+     * @internal
+     */
+    protected setInitialFocus(): void;
     /**
      * Handles the updated lifecycle event.
      *
@@ -85,7 +111,7 @@ declare class ListBox extends ListBox_base {
      */
     private updateSelectedInChildOptions;
     /**
-     * Dispatch change event when an option is selected.
+     * Dispatch change event when selection changes.
      */
     private fireEvents;
     render(): import("lit-html").TemplateResult<1>;

package/dist/components/listbox/listbox.component.js

@@ -18,7 +18,10 @@ import { Component } from '../../models';
 import { ElementStore } from '../../utils/controllers/ElementStore';
 import styles from './listbox.styles';
 /**
- * listbox component presents a list of options and allows a user to select one of them.
+ * listbox component presents a list of options and allows a user to select one or more of them.
+ *
+ * When `multiple` is enabled, clicking/pressing Enter/Space on an option toggles its selection
+ * instead of replacing the current selection.
  *
  * Notes:
  * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.
@@ -58,6 +61,11 @@ class ListBox extends ListNavigationMixin(CaptureDestroyEventForChildElement(Com
          * The value attribute is used to represent the last selected option's value in the listbox.
          */
         this.value = undefined;
+        /**
+         * When true, multiple options can be selected.
+         * @default false
+         */
+        this.multiple = false;
         /** @internal */
         this.itemsStore = new ElementStore(this, {
             isValidItem: this.isValidItem,
@@ -85,11 +93,20 @@ class ListBox extends ListNavigationMixin(CaptureDestroyEventForChildElement(Com
                 this.itemsStore.delete(item);
                 break;
             case 'selected':
-                // When selection changed on the option
-                this.setSelectedOption(item, false, false);
+                if (this.multiple) {
+                    this.syncValueToFirstSelected();
+                }
+                else {
+                    this.setSelectedOption(item, false, false);
+                }
                 break;
             case 'unselected':
-                this.handleNoSelection();
+                if (this.multiple) {
+                    this.syncValueToFirstSelected();
+                }
+                else {
+                    this.handleNoSelection();
+                }
                 break;
             default:
                 break;
@@ -117,21 +134,82 @@ class ListBox extends ListNavigationMixin(CaptureDestroyEventForChildElement(Com
     /** @internal */
     handleClick(event) {
         const target = event.target;
-        if (this.isValidItem(target)) {
-            this.setSelectedOption(target);
+        if (!this.isValidItem(target))
+            return;
+        const option = target;
+        if (this.multiple) {
+            this.toggleOptionSelection(option);
+        }
+        else {
+            this.setSelectedOption(option);
         }
     }
+    /**
+     * Toggles the selection state of an option (for multiselect mode).
+     * @internal
+     */
+    toggleOptionSelection(option) {
+        if (option.disabled || option.softDisabled)
+            return;
+        const isCurrentlySelected = option.hasAttribute('selected');
+        option.toggleAttribute('selected', !isCurrentlySelected);
+        this.syncValueToFirstSelected();
+        this.fireEvents();
+    }
     /** @internal */
     getFirstSelectedOption() {
         return this.itemsStore.items.find(el => el.matches('[selected]'));
     }
+    /**
+     * Syncs value and selectedOption to reflect the first selected option (when multiple)
+     * @internal
+     */
+    syncValueToFirstSelected() {
+        const firstSelected = this.getFirstSelectedOption();
+        this.value = firstSelected === null || firstSelected === void 0 ? void 0 : firstSelected.value;
+        this.selectedOption = firstSelected !== null && firstSelected !== void 0 ? firstSelected : null;
+    }
+    /** @internal */
+    getSelectedValues() {
+        return this.itemsStore.items.reduce((acc, option) => {
+            const { value } = option;
+            if (option.hasAttribute('selected') && value !== undefined) {
+                acc.push(value);
+            }
+            return acc;
+        }, []);
+    }
+    /**
+     * Override to focus the first selected option per W3C APG.
+     * This applies to both single-select and multi-select listboxes.
+     * @internal
+     */
+    setInitialFocus() {
+        const firstSelected = this.getFirstSelectedOption();
+        if (firstSelected) {
+            const index = this.itemsStore.items.indexOf(firstSelected);
+            if (index !== -1) {
+                this.resetTabIndexAndSetFocus(index, undefined, false);
+                return;
+            }
+        }
+        super.setInitialFocus();
+    }
     /**
      * Handles the updated lifecycle event.
      *
      * @param changedProperties - The properties that have changed since the last update.
      */
     updated(changedProperties) {
-        if (changedProperties.has('value')) {
+        if (changedProperties.has('multiple')) {
+            if (this.multiple) {
+                this.setAttribute('aria-multiselectable', 'true');
+            }
+            else {
+                this.removeAttribute('aria-multiselectable');
+            }
+        }
+        if (changedProperties.has('value') && !this.multiple) {
             const newSelectedOption = this.itemsStore.items.find(option => option.value === this.value);
             if (newSelectedOption) {
                 this.setSelectedOption(newSelectedOption, false);
@@ -171,12 +249,17 @@ class ListBox extends ListNavigationMixin(CaptureDestroyEventForChildElement(Com
         selectedOption === null || selectedOption === void 0 ? void 0 : selectedOption.toggleAttribute('selected', true);
     }
     /**
-     * Dispatch change event when an option is selected.
+     * Dispatch change event when selection changes.
      */
     fireEvents() {
-        if (this.selectedOption) {
-            this.dispatchEvent(new Event('change', { composed: true, bubbles: true }));
-        }
+        this.dispatchEvent(new CustomEvent('change', {
+            detail: {
+                value: this.value,
+                selectedValues: this.getSelectedValues(),
+            },
+            composed: true,
+            bubbles: true,
+        }));
     }
     render() {
         return html `<slot part="container"></slot>`;
@@ -191,6 +274,10 @@ __decorate([
     property({ type: String, reflect: true }),
     __metadata("design:type", Object)
 ], ListBox.prototype, "value", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true }),
+    __metadata("design:type", Object)
+], ListBox.prototype, "multiple", void 0);
 __decorate([
     state(),
     __metadata("design:type", Object)

package/dist/components/listbox/listbox.types.d.ts

@@ -1,6 +1,10 @@
-import { OverrideEventTarget } from '../../utils/types';
+import type { TypedCustomEvent } from '../../utils/types';
 import type ListBox from './listbox.component';
-export type ListBoxChangeEvent = OverrideEventTarget<Event, ListBox>;
+export interface ListBoxChangeEventDetail {
+    value: string | undefined;
+    selectedValues: string[];
+}
+export type ListBoxChangeEvent = TypedCustomEvent<ListBox, ListBoxChangeEventDetail>;
 interface Events {
     onChangeEvent: ListBoxChangeEvent;
 }

package/dist/custom-elements.json

@@ -23217,7 +23217,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "listbox component presents a list of options and allows a user to select one of them.\n\nNotes:\n- This is a standalone listbox component. Select has its own mdc-selectlistbox component.\n- this component has name and value attributes and also emits change event,\n  but it is not a form control (yet).",
+          "description": "listbox component presents a list of options and allows a user to select one or more of them.\n\nWhen `multiple` is enabled, clicking/pressing Enter/Space on an option toggles its selection\ninstead of replacing the current selection.\n\nNotes:\n- This is a standalone listbox component. Select has its own mdc-selectlistbox component.\n- this component has name and value attributes and also emits change event,\n  but it is not a form control (yet).",
           "name": "ListBox",
           "cssProperties": [
             {
@@ -23247,7 +23247,7 @@
                   "text": "void"
                 }
               },
-              "description": "Dispatch change event when an option is selected."
+              "description": "Dispatch change event when selection changes."
             },
             {
               "kind": "method",
@@ -23273,6 +23273,17 @@
                 "module": "utils/mixins/ListNavigationMixin.js"
               }
             },
+            {
+              "kind": "field",
+              "name": "multiple",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When true, multiple options can be selected.",
+              "attribute": "multiple",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "name",
@@ -23436,7 +23447,7 @@
             {
               "name": "change",
               "type": {
-                "text": "Event"
+                "text": "CustomEvent"
               },
               "description": "(React: onChange) This event is emitted when the selected item changed",
               "reactName": "onChange"
@@ -23460,6 +23471,15 @@
               "default": "undefined",
               "description": "The value attribute is used to represent the last selected option's value in the listbox.",
               "fieldName": "value"
+            },
+            {
+              "name": "multiple",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When true, multiple options can be selected.",
+              "fieldName": "multiple"
             }
           ],
           "mixins": [
@@ -23477,7 +23497,7 @@
             "module": "/src/models"
           },
           "tagName": "mdc-listbox",
-          "jsDoc": "/**\n * listbox component presents a list of options and allows a user to select one of them.\n *\n * Notes:\n * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.\n * - this component has name and value attributes and also emits change event,\n *   but it is not a form control (yet).\n *\n * @dependency mdc-list\n * @dependency mdc-icon\n * @dependency mdc-text\n * @dependency mdc-option\n * @dependency mdc-optgroup\n *\n * @tagname mdc-listbox\n *\n * @cssproperty --mdc-listbox-max-height - max height of the listbox\n *\n * @slot default - This is a default/unnamed slot, where options and optgroups are placed\n *\n * @csspart container - The container of the listbox\n *\n * @event change - (React: onChange) This event is emitted when the selected item changed\n */",
+          "jsDoc": "/**\n * listbox component presents a list of options and allows a user to select one or more of them.\n *\n * When `multiple` is enabled, clicking/pressing Enter/Space on an option toggles its selection\n * instead of replacing the current selection.\n *\n * Notes:\n * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.\n * - this component has name and value attributes and also emits change event,\n *   but it is not a form control (yet).\n *\n * @dependency mdc-list\n * @dependency mdc-icon\n * @dependency mdc-text\n * @dependency mdc-option\n * @dependency mdc-optgroup\n *\n * @tagname mdc-listbox\n *\n * @cssproperty --mdc-listbox-max-height - max height of the listbox\n *\n * @slot default - This is a default/unnamed slot, where options and optgroups are placed\n *\n * @csspart container - The container of the listbox\n *\n * @event change - (React: onChange) This event is emitted when the selected item changed\n */",
           "customElement": true
         }
       ],

package/dist/index.d.ts

@@ -118,6 +118,7 @@ import { inMemoryCache, webAPIAssetsCache } from './utils/assets-cache';
 import type { TimePickerChangeEvent, TimePickerInputEvent } from './components/timepicker/timepicker.types';
 import type { DatePickerChangeEvent, DatePickerInputEvent } from './components/datepicker/datepicker.types';
 import type { CalendarDateSelectedEvent, CalendarMonthChangedEvent } from './components/calendar/calendar.types';
+import type { ListBoxChangeEvent } from './components/listbox/listbox.types';
 export { Accordion, AccordionButton, AccordionGroup, AlertChip, Animation, AnnouncementDialog, Appheader, Avatar, AvatarButton, Badge, Brandvisual, Bullet, Button, ButtonGroup, ButtonLink, Calendar, Card, CardButton, CardCheckbox, CardRadio, Checkbox, Chip, Coachmark, ControlTypeProvider, DatePicker, Dialog, Divider, FilterChip, FormfieldGroup, Icon, IconProvider, Illustration, IllustrationProvider, 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, ResponsiveSettingsProvider, ScreenreaderAnnouncer, Searchfield, Searchpopover, Select, SelectListbox, SideNavigation, Skeleton, Spinner, StaticChip, StaticCheckbox, StaticRadio, StaticToggle, Stepper, StepperConnector, StepperItem, Tab, TabList, Text, Textarea, TimePicker, ThemeProvider, Toast, Toggle, Typewriter, ToggleTip, Tooltip, VirtualizedList, Combobox, Slider, ListBox, Banner, Buttonsimple, Verticaltablist, };
-export type { AvatarSize, BadgeType, ChipColorType, ButtonColor, ButtonVariant, IconButtonSize, MenuPopoverActionEvent, MenuPopoverChangeEvent, MenuSectionChangeEvent, PillButtonSize, PopoverPlacement, PresenceType, SkeletonVariant, SelectChangeEvent, SelectInputEvent, SpinnerSize, SpinnerVariant, SliderChangeEvent, TextType, TypewriterType, InputInputEvent, InputChangeEvent, InputFocusEvent, InputBlurEvent, InputClearEvent, VirtualizedListScrollEvent, TablistChangeEvent, TextareaInputEvent, TextareaChangeEvent, TextareaFocusEvent, TextareaBlurEvent, TextareaLimitExceededEvent, ToggleOnChangeEvent, CheckboxOnChangeEvent, LinkButtonSize, TimePickerChangeEvent, TimePickerInputEvent, DatePickerChangeEvent, DatePickerInputEvent, CalendarDateSelectedEvent, CalendarMonthChangedEvent, VerticaltablistChangeEvent, };
+export type { AvatarSize, BadgeType, ChipColorType, ButtonColor, ButtonVariant, IconButtonSize, MenuPopoverActionEvent, MenuPopoverChangeEvent, MenuSectionChangeEvent, PillButtonSize, PopoverPlacement, PresenceType, SkeletonVariant, SelectChangeEvent, SelectInputEvent, SpinnerSize, SpinnerVariant, SliderChangeEvent, TextType, TypewriterType, InputInputEvent, InputChangeEvent, InputFocusEvent, InputBlurEvent, InputClearEvent, VirtualizedListScrollEvent, TablistChangeEvent, TextareaInputEvent, TextareaChangeEvent, TextareaFocusEvent, TextareaBlurEvent, TextareaLimitExceededEvent, ToggleOnChangeEvent, CheckboxOnChangeEvent, LinkButtonSize, TimePickerChangeEvent, TimePickerInputEvent, DatePickerChangeEvent, DatePickerInputEvent, CalendarDateSelectedEvent, CalendarMonthChangedEvent, VerticaltablistChangeEvent, ListBoxChangeEvent, };
 export { BUTTON_COLORS, BUTTON_VARIANTS, ICON_BUTTON_SIZES, inMemoryCache, PILL_BUTTON_SIZES, SKELETON_VARIANTS, webAPIAssetsCache, };

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

@@ -2,7 +2,10 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/listbox';
 import type { Events } from '../../components/listbox/listbox.types';
 /**
- * listbox component presents a list of options and allows a user to select one of them.
+ * listbox component presents a list of options and allows a user to select one or more of them.
+ *
+ * When `multiple` is enabled, clicking/pressing Enter/Space on an option toggles its selection
+ * instead of replacing the current selection.
  *
  * Notes:
  * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.

package/dist/react/listbox/index.js

@@ -3,7 +3,10 @@ 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.
+ * listbox component presents a list of options and allows a user to select one or more of them.
+ *
+ * When `multiple` is enabled, clicking/pressing Enter/Space on an option toggles its selection
+ * instead of replacing the current selection.
  *
  * Notes:
  * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@momentum-design/components",
   "packageManager": "yarn@3.2.4",
-  "version": "0.133.13",
+  "version": "0.133.14",
   "engines": {
     "node": ">=20.0.0",
     "npm": ">=8.0.0"