material-inspired-component-library 7.0.2 → 8.0.0

package/components/list/index.ts

@@ -21,118 +21,118 @@
 
 export const listSelector = '.micl-list';
 
-export default (() =>
-{
-    const isDisabled = (item: HTMLElement | null): boolean => !!item && item.classList.contains('micl-list-item--disabled');
-    const isSelected = (item: HTMLElement | null): boolean => !!item && item.matches(':has(input[type=checkbox]:checked)');
-
-    return {
-        keydown: (event: Event): void =>
-        {
-            if (
-                !(event instanceof KeyboardEvent)
-                || !(event.target instanceof Element)
-                || !event.target.matches('.micl-list-item-one,.micl-list-item-two,.micl-list-item-three')
-            ) {
-                return;
-            }
-            const parent = (event.target as Element).parentElement;
-            if (!parent) return;
+const isDisabled   = (item?: HTMLElement | null) => item?.classList.contains('micl-list-item--disabled');
+const isSelectable = (item?: HTMLElement | null) => item?.matches(':has(input[type=checkbox])');
+const isSelected   = (item?: HTMLElement | null) => item?.matches(':has(input[type=checkbox]:checked)');
 
-            let items: HTMLElement[] = [];
-
-            if (parent instanceof HTMLDetailsElement) {
-                items = Array.from(parent.parentElement?.children || []).map(details => {
-                    let summary = details.querySelector(':scope > summary') as HTMLElement;
-                    return isDisabled(summary) ? null : summary;
-                }).filter(item => !!item);
-            }
-            else if (parent instanceof HTMLUListElement || parent instanceof HTMLOListElement) {
-                items = Array.from(parent.children).map(child => {
-                    return (
-                        (child instanceof HTMLLIElement)
-                        && !isDisabled(child)
-                        && (child.role !== 'separator')
-                    ) ? child : null;
-                }).filter(item => !!item);
-            }
-            if (items.length === 0) {
-                return;
-            }
+export default
+{
+    keydown(event: KeyboardEvent | Event): void
+    {
+        const target = event.target as HTMLElement;
+
+        if (
+            !(event instanceof KeyboardEvent)
+            || !target?.matches('.micl-list-item-one,.micl-list-item-two,.micl-list-item-three')
+        ) {
+            return;
+        }
 
-            const selectedIndex = items.findIndex(item => isSelected(item));
-            const currentItem   = document.activeElement as HTMLElement;
-            const currentIndex  = items.indexOf(currentItem);
+        const parent = target.parentElement;
+        if (!parent) return;
 
-            if (currentIndex === -1) return;
+        const isAccordion = parent instanceof HTMLDetailsElement;
+        let items: HTMLElement[] = [];
 
-            let nextIndex = currentIndex;
+        if (isAccordion) {
+            items = Array.from(parent.parentElement?.children || [])
+                .map(details => details.querySelector(':scope > summary') as HTMLElement)
+                .filter(Boolean);
+        }
+        else if (['UL', 'OL'].includes(parent.tagName)) {
+            items = Array.from(parent.children).filter(child =>
+                child instanceof HTMLLIElement && child.getAttribute('role') !== 'separator'
+                ) as HTMLElement[];
+        }
 
-            switch (event.key) {
-                case 'ArrowDown':
-                    event.preventDefault(); // prevent page scrolling
-                    nextIndex = (currentIndex + 1) % items.length;
-                    break;
-                case 'ArrowUp':
-                    event.preventDefault();
-                    nextIndex = (currentIndex - 1 + items.length) % items.length;
-                    break;
-                case 'Tab':
-                    nextIndex = (selectedIndex === -1) ? 0 : selectedIndex;
-                    break;
-                case ' ':
+        items = items.filter(item => !isDisabled(item));
+        if (!items.length) return;
+
+        const currentIndex = items.indexOf(target);
+        if (currentIndex === -1) return;
+
+        let nextIndex = currentIndex;
+
+        switch (event.key) {
+            case 'ArrowDown':
+                event.preventDefault(); // prevent page scrolling
+                nextIndex = (currentIndex + 1) % items.length;
+                break;
+            case 'ArrowUp':
+                event.preventDefault();
+                nextIndex = (currentIndex - 1 + items.length) % items.length;
+                break;
+            case 'Tab':
+                if (!isAccordion) {
+                    const selectedIndex = items.findIndex(isSelected);
+                    nextIndex = selectedIndex === -1 ? 0 : selectedIndex;
+                }
+                break;
+            case ' ':
+            case 'Enter':
+                if (isAccordion) break;
+                if (event.key === ' ') {
                     event.preventDefault();
-                case 'Enter':
-                    const el = (event.target as Element).querySelector(
-                        'input[type=checkbox], a[href], button'
-                    );
-                    if (el instanceof HTMLInputElement) {
-                        el.checked = !el.checked;
-                    }
-                    else if (el instanceof HTMLAnchorElement) {
-                        el.click();
-                    }
-                    else if (el instanceof HTMLButtonElement) {
-                        el.dispatchEvent(new MouseEvent('mouseenter', {
-                            bubbles   : true,
-                            cancelable: true,
-                            view      : window
-                        }));
-                    }
-                    break;
-                default:
-            }
+                }
+                const el = target.querySelector<HTMLElement>(
+                    'input[type=checkbox], a[href], button'
+                );
+                if (el instanceof HTMLInputElement) {
+                    el.checked = !el.checked;
+                    el.dispatchEvent(new Event('change', {
+                        bubbles   : true,
+                        cancelable: true
+                    }));
+                }
+                else {
+                    el?.click();
+                }
+                break;
+            default:
+        }
 
-            if (nextIndex !== currentIndex) {
-                currentItem?.setAttribute('tabindex', '-1');
+        if (nextIndex !== currentIndex) {
+            if (!isAccordion) {
+                target.setAttribute('tabindex', '-1');
                 items[nextIndex].setAttribute('tabindex', '0');
-                items[nextIndex].focus();
             }
-        },
+            items[nextIndex].focus();
+        }
+    },
 
-        initialize: (element: HTMLElement): void =>
-        {
-            if (element.dataset.miclinitialized) return;
+    initialize(element: HTMLElement): void
+    {
+        if (element.dataset.miclinitialized) return;
+        element.dataset.miclinitialized = '1';
 
-            element.dataset.miclinitialized = '1';
+        element.querySelectorAll<HTMLElement>(
+            ':scope > details > summary.micl-list-item--disabled'
+        ).forEach(summary => summary.setAttribute('tabindex', '-1'));
 
-            if (element.querySelectorAll<HTMLLIElement>('li[tabindex="0"]').length === 0) {
-                return;
-            }
+        if (!element.querySelector('li[tabindex="0"]')) return;
 
-            const items: HTMLLIElement[] = Array.from(element.querySelectorAll(
-                'li:not([role="separator"])'
-            ));
+        element.querySelectorAll<HTMLLIElement>('li:not([role="separator"])').forEach(item =>
+        {
+            if (item.getAttribute('tabindex') !== '0') {
+                item.setAttribute('tabindex', '-1');
+            }
 
-            items.forEach(item =>
-            {
-                if (item.getAttribute('tabindex') !== '0') {
-                    item.setAttribute('tabindex', '-1');
-                }
+            item.querySelectorAll('a, button, input').forEach(link => link.setAttribute('tabindex', '-1'));
 
-                const links = item.querySelectorAll('a, button, input');
-                links.forEach(link => link.setAttribute('tabindex', '-1'));
-            });
-        }
-    };
-})();
+            if (isSelectable(item)) {
+                item.setAttribute('role', 'option');
+                item.parentElement?.setAttribute('role', 'listbox');
+            }
+        });
+    }
+};

package/components/menu/README.md

@@ -20,6 +20,8 @@ The Menu component is an extension of the [List component](../list/README.md). I
 <button type="button" popovertarget="mymenu">Open Menu</button>
 ```
 
+Adding the `micl-list-item--disabled` class to a menu item causes the item to be displayed in a disabled state.
+
 ### CSS
 Import the styles for both the menu and list components into your project:
 
@@ -62,11 +64,11 @@ Since the Menu component is based on the **List component**, all of its list ite
     </li>
     <li class="micl-list-item-two">
       <span class="micl-list-item__image" style="background-image:url(https://...jpg)"></span>
-      <label for="cb" class="micl-list-item__text">
+      <label class="micl-list-item__text">
         <span class="micl-list-item__headline">Person</span>
         <span class="micl-list-item__supporting-text">This person is an administrator</span>
+        <input type="checkbox" id="cb" class="micl-checkbox">
       </label>
-      <input type="checkbox" id="cb" class="micl-checkbox">
     </li>
   </ul>
 </nav>
@@ -113,7 +115,7 @@ A menu item may trigger opening a submenu when invoked by a button. Wrap the men
               <span class="micl-list-item__headline">Item 1-1</span>
             </span>
           </li>
-          <li role="separator" class="micl-divider"></li>
+          <li role="separator" class="micl-divider-inset"></li>
           <li class="micl-list-item-one">
             <span class="micl-list-item__text">
               <span class="micl-list-item__headline">Item 1-2</span>
@@ -131,22 +133,209 @@ A menu item may trigger opening a submenu when invoked by a button. Wrap the men
 </nav>
 ```
 
-Adding the `micl-list-item--disabled` class to a menu item causes the item to be displayed in a disabled state.
+**Example: A vibrant menu**
+
+Add the `micl-menu--vibrant` class to render the menu in a high-emphasis variant.
+
+```HTML
+<nav id="mymenu" class="micl-menu micl-menu--vibrant" popover>
+  <ul class="micl-list">
+    <li class="micl-list-item-one" tabindex="0">
+      <span class="micl-list-item__text">
+        <span class="micl-list-item__headline">Menu item</span>
+      </span>
+    </li>
+  </ul>
+</nav>
+```
+
+**Example: Grouping menu items**
+
+Menu items can be grouped by including a [Divider component](../divider/README.md) or a small gap. To create a gap between groups of menu items, bundle similar menu items in different lists.
+
+```HTML
+<nav id="mymenu" class="micl-menu" popover>
+  <ul class="micl-list">
+    <li role="separator" class="micl-menu__section">File</li>
+    <li class="micl-list-item-one" tabindex="0">
+      <span class="micl-list-item__text">
+        <span class="micl-list-item__headline">New</span>
+      </span>
+    </li>
+  </ul>
+  <ul class="micl-list">
+    <li role="separator" class="micl-menu__section">Edit</li>
+    <li class="micl-list-item-one">
+      <span class="micl-list-item__text">
+        <span class="micl-list-item__headline">Cut</span>
+      </span>
+    </li>
+  </ul>
+</nav>
+```
 
-Use a [Divider component](../divider/README.md) to separate neighbouring menu items by a divider.
+You may include an `<li>` with the `micl-menu__section` class to give the menu item group a descriptive title.
 
 ## Customizations
 You can customize the appearance of the Menu component by overriding its global CSS variables. These variables are declared on the `:root` pseudo-class and can be changed on any appropriate parent element to affect its child menus.
 
-| Variable name | Default Value | Description |
-| ------------- | ----- | ----------- |
-| --md-sys-menu-width-max | 280px | The maximum width allowed for a menu |
-| --md-sys-menu-width-min | 112px | The minimum allowed width for a menu |
+| Variable name            | Default Value | Description                          |
+| ------------------------ | ------------- | ------------------------------------ |
+| --md-comp-menu-width-max | 320px         | The maximum width allowed for a menu |
+| --md-comp-menu-width-min | 112px         | The minimum allowed width for a menu |
+
+The Menu component supports the following CSS variables, as defined in the [Material Design 3 Expressive Menu Specification](https://m3.material.io/components/menus/specs):
+
+| Variable name |
+| ------------- |
+| --md-comp-menu-container-elevation |
+| --md-comp-menu-container-shape |
+| --md-comp-menu-active-container-shape |
+| --md-comp-menu-inactive-container-shape |
+| --md-comp-menu-gap |
+| --md-comp-menu-group-padding |
+| --md-comp-menu-group-shape |
+| --md-comp-menu-item-height |
+| --md-comp-menu-item-bottom-space |
+| --md-comp-menu-item-leading-space |
+| --md-comp-menu-item-top-space |
+| --md-comp-menu-item-trailing-space |
+| --md-comp-menu-item-focus-indicator-color |
+| --md-comp-menu-item-focus-indicator-offset |
+| --md-comp-menu-item-focus-indicator-thickness |
+| --md-comp-menu-item-leading-icon-size |
+| --md-comp-menu-item-trailing-icon-size |
+| --md-comp-menu-item-shape |
+| --md-comp-menu-item-shape-single |
+| --md-comp-menu-item-selected-shape |
+|  |
+| --md-comp-menu-section-label-bottom-space |
+| --md-comp-menu-section-label-top-space |
+|  |
+| --md-comp-menu-standard-container-color |
+| --md-comp-menu-standard-menu-item-container-color |
+| --md-comp-menu-standard-menu-item-focused-label-text-color |
+| --md-comp-menu-standard-menu-item-focused-leading-icon-color |
+| --md-comp-menu-standard-menu-item-focused-state-layer-color |
+| --md-comp-menu-standard-menu-item-focused-state-layer-opacity |
+| --md-comp-menu-standard-menu-item-focused-supporting-text-color |
+| --md-comp-menu-standard-menu-item-focused-trailing-icon-color |
+| --md-comp-menu-standard-menu-item-focused-trailing-supporting-text-color |
+| --md-comp-menu-standard-menu-item-hovered-label-text-color |
+| --md-comp-menu-standard-menu-item-hovered-leading-icon-color |
+| --md-comp-menu-standard-menu-item-hovered-state-layer-color |
+| --md-comp-menu-standard-menu-item-hovered-state-layer-opacity |
+| --md-comp-menu-standard-menu-item-hovered-supporting-text-color |
+| --md-comp-menu-standard-menu-item-hovered-trailing-icon-color |
+| --md-comp-menu-standard-menu-item-hovered-trailing-supporting-text-color |
+| --md-comp-menu-standard-menu-item-pressed-label-text-color |
+| --md-comp-menu-standard-menu-item-pressed-leading-icon-color |
+| --md-comp-menu-standard-menu-item-pressed-state-layer-color |
+| --md-comp-menu-standard-menu-item-pressed-state-layer-opacity |
+| --md-comp-menu-standard-menu-item-pressed-supporting-text-color |
+| --md-comp-menu-standard-menu-item-pressed-trailing-icon-color |
+| --md-comp-menu-standard-menu-item-pressed-trailing-supporting-text-color |
+| --md-comp-menu-standard-menu-item-label-text-color |
+| --md-comp-menu-standard-menu-item-leading-icon-color |
+| --md-comp-menu-standard-menu-item-supporting-text-color |
+| --md-comp-menu-standard-menu-item-trailing-icon-color |
+| --md-comp-menu-standard-menu-item-trailing-supporting-text-color |
+| --md-comp-menu-standard-section-label-text-color |
+|  |
+| --md-comp-menu-vibrant-container-color |
+| --md-comp-menu-vibrant-menu-item-container-color |
+| --md-comp-menu-vibrant-menu-item-focused-label-text-color |
+| --md-comp-menu-vibrant-menu-item-focused-leading-icon-color |
+| --md-comp-menu-vibrant-menu-item-focused-state-layer-color |
+| --md-comp-menu-vibrant-menu-item-focused-state-layer-opacity |
+| --md-comp-menu-vibrant-menu-item-focused-supporting-text-color |
+| --md-comp-menu-vibrant-menu-item-focused-trailing-icon-color |
+| --md-comp-menu-vibrant-menu-item-focused-trailing-supporting-text-color |
+| --md-comp-menu-vibrant-menu-item-hovered-label-text-color |
+| --md-comp-menu-vibrant-menu-item-hovered-leading-icon-color |
+| --md-comp-menu-vibrant-menu-item-hovered-state-layer-color |
+| --md-comp-menu-vibrant-menu-item-hovered-state-layer-opacity |
+| --md-comp-menu-vibrant-menu-item-hovered-supporting-text-color |
+| --md-comp-menu-vibrant-menu-item-hovered-trailing-icon-color |
+| --md-comp-menu-vibrant-menu-item-hovered-trailing-supporting-text-color |
+| --md-comp-menu-vibrant-menu-item-pressed-label-text-color |
+| --md-comp-menu-vibrant-menu-item-pressed-leading-icon-color |
+| --md-comp-menu-vibrant-menu-item-pressed-state-layer-color |
+| --md-comp-menu-vibrant-menu-item-pressed-state-layer-opacity |
+| --md-comp-menu-vibrant-menu-item-pressed-supporting-text-color |
+| --md-comp-menu-vibrant-menu-item-pressed-trailing-icon-color |
+| --md-comp-menu-vibrant-menu-item-pressed-trailing-supporting-text-color |
+| --md-comp-menu-vibrant-menu-item-label-text-color |
+| --md-comp-menu-vibrant-menu-item-leading-icon-color |
+| --md-comp-menu-vibrant-menu-item-supporting-text-color |
+| --md-comp-menu-vibrant-menu-item-trailing-icon-color |
+| --md-comp-menu-vibrant-menu-item-trailing-supporting-text-color |
+| --md-comp-menu-vibrant-section-label-text-color |
+|  |
+| --md-comp-menu-standard-menu-item-selected-container-color |
+| --md-comp-menu-standard-menu-item-selected-label-text-color |
+| --md-comp-menu-standard-menu-item-selected-leading-icon-color |
+| --md-comp-menu-standard-menu-item-selected-supporting-text-color |
+| --md-comp-menu-standard-menu-item-selected-trailing-icon-color |
+| --md-comp-menu-standard-menu-item-selected-trailing-supporting-text-color |
+|  |
+| --md-comp-menu-standard-menu-item-selected-disabled-container-color |
+| --md-comp-menu-standard-menu-item-selected-disabled-container-opacity |
+| --md-comp-menu-standard-menu-item-selected-disabled-label-text-color |
+| --md-comp-menu-standard-menu-item-selected-disabled-label-text-opacity |
+| --md-comp-menu-standard-menu-item-selected-disabled-leading-icon-color |
+| --md-comp-menu-standard-menu-item-selected-disabled-leading-icon-opacity |
+| --md-comp-menu-standard-menu-item-selected-disabled-trailing-icon-color |
+| --md-comp-menu-standard-menu-item-selected-disabled-trailing-icon-opacity |
+| --md-comp-menu-standard-menu-item-selected-disabled-trailing-supporting-text-color |
+| --md-comp-menu-standard-menu-item-selected-focused-label-text-color |
+| --md-comp-menu-standard-menu-item-selected-focused-leading-icon-color |
+| --md-comp-menu-standard-menu-item-selected-focused-state-layer-color |
+| --md-comp-menu-standard-menu-item-selected-focused-state-layer-opacity |
+| --md-comp-menu-standard-menu-item-selected-focused-supporting-text-color |
+| --md-comp-menu-standard-menu-item-selected-focused-trailing-icon-color |
+| --md-comp-menu-standard-menu-item-selected-focused-trailing-supporting-text-color |
+| --md-comp-menu-standard-menu-item-selected-hovered-label-text-color |
+| --md-comp-menu-standard-menu-item-selected-hovered-leading-icon-color |
+| --md-comp-menu-standard-menu-item-selected-hovered-state-layer-color |
+| --md-comp-menu-standard-menu-item-selected-hovered-state-layer-opacity |
+| --md-comp-menu-standard-menu-item-selected-hovered-supporting-text-color |
+| --md-comp-menu-standard-menu-item-selected-hovered-trailing-icon-color |
+| --md-comp-menu-standard-menu-item-selected-hovered-trailing-supporting-text-color |
+| --md-comp-menu-standard-menu-item-selected-pressed-label-text-color |
+| --md-comp-menu-standard-menu-item-selected-pressed-leading-icon-color |
+| --md-comp-menu-standard-menu-item-selected-pressed-state-layer-color |
+| --md-comp-menu-standard-menu-item-selected-pressed-state-layer-opacity |
+| --md-comp-menu-standard-menu-item-selected-pressed-supporting-text-color |
+| --md-comp-menu-standard-menu-item-selected-pressed-trailing-icon-color |
+| --md-comp-menu-standard-menu-item-selected-pressed-trailing-supporting-text-color |
+|  |
+| --md-comp-menu-vibrant-menu-item-selected-container-color |
+| --md-comp-menu-vibrant-menu-item-selected-label-text-color |
+| --md-comp-menu-vibrant-menu-item-selected-leading-icon-color |
+| --md-comp-menu-vibrant-menu-item-selected-supporting-text-color |
+| --md-comp-menu-vibrant-menu-item-selected-trailing-icon-color |
+| --md-comp-menu-vibrant-menu-item-selected-trailing-supporting-text-color |
+|  |
+| --md-comp-menu-vibrant-menu-item-selected-disabled-label-text-opacity |
+| --md-comp-menu-vibrant-menu-item-selected-disabled-leading-icon-opacity |
+| --md-comp-menu-vibrant-menu-item-selected-disabled-supporting-text-opacity |
+| --md-comp-menu-vibrant-menu-item-selected-disabled-trailing-icon-opacity |
+| --md-comp-menu-vibrant-menu-item-selected-disabled-trailing-supporting-text-opacity |
+| --md-comp-menu-vibrant-menu-item-selected-focused-state-layer-color |
+| --md-comp-menu-vibrant-menu-item-selected-focused-state-layer-opacity |
+| --md-comp-menu-vibrant-menu-item-selected-focused-label-text-color |
+| --md-comp-menu-vibrant-menu-item-selected-hovered-state-layer-color |
+| --md-comp-menu-vibrant-menu-item-selected-hovered-state-layer-opacity |
+| --md-comp-menu-vibrant-menu-item-selected-hovered-label-text-color |
+| --md-comp-menu-vibrant-menu-item-selected-pressed-state-layer-color |
+| --md-comp-menu-vibrant-menu-item-selected-pressed-state-layer-opacity |
+| --md-comp-menu-vibrant-menu-item-selected-pressed-label-text-color |
 
 **Example: Changing the maximum width**
 
 ```HTML
-<div style="--md-sys-menu-width-max:320px">
+<div style="--md-comp-menu-width-max:360px">
   <nav id="mymenu" class="micl-menu" popover>
     <ul class="micl-list">
       <li class="micl-list-item-one" tabindex="0">