material-inspired-component-library 1.0.0

package/components/list/README.md

@@ -0,0 +1,176 @@
+# List
+This component implements the the [Material Design 3 Expressive List](https://m3.material.io/components/lists/overview) design. Lists are continuous, vertical groups of text or images, representing a set of data.
+
+## Basic Usage
+
+### HTML
+To create a basic list, use the `<ul>` element with the `micl-list` class and individual `<li>` elements for each list item. For a basic single-line item, use the `micl-list-item-one` class:
+
+```HTML
+<ul class="micl-list" role="listbox">
+  <li class="micl-list-item-one" tabindex="0">
+    <span class="micl-list-item__text">
+      <span class="micl-list-item__headline">A single-line item</span>
+    </span>
+  </li>
+</ul>
+```
+
+- The `role="listbox"` is used for accessibility, indicating a selectable list.
+
+- `tabindex="0"` on the `<li>` makes the list item focusable and allows keyboard navigation.
+
+### CSS
+Import the list styles into your project:
+
+```CSS
+@use "micl/components/list";
+```
+
+### TypeScript
+This component requires a TypeScript module to support keyboard navigation. You can import the specific module or use the main MICL TypeScript library, which handles initialization automatically.
+
+To manually initialize the component:
+
+```TypeScript
+import miclList from 'micl/components/list';
+
+miclList.initialize(document.querySelector('.micl-list'));
+```
+
+### Demo
+A live example of the [List component](https://henkpb.github.io/micl/list.html) is available for you to interact with.
+
+## Variants
+The List component offers three CSS classes to control the height and content capacity of individual list items:
+
+| CSS class | Description |
+| --------- | ----------- |
+| micl-list-item-one | For single-line items, accommodating one line of text. |
+| micl-list-item-two | For two-line items, accommodating up to two lines of text. |
+| micl-list-item-three | For three-line items, accommodating up to three lines of text. |
+
+```HTML
+<ul class="micl-list" role="listbox">
+  <li class="micl-list-item-three" tabindex="0">
+    <span class="micl-list-item__text">
+      <span class="micl-list-item__headline">A three-line item</span>
+      <span class="micl-list-item__supporting-text">Supporting text that is long enough to fill up multiple lines of text with words and sentences.</span>
+    </span>
+  </li>
+</ul>
+```
+
+Adding the `micl-list-item--disabled` class to the `<li>` element causes the list item to be displayed in a disabled state.
+
+Add the `micl-list__divider` class to the `<ul>` element to automatically place a divider between each list item.
+
+### Leading Content
+The text content of a list item can be preceded by various media elements:
+
+- **Icon**: Use `micl-list-item__icon` with a (Material Symbols) icon.
+  ```HTML
+  <li class="micl-list-item-two" tabindex="0">
+    <span class="material-symbols-outlined micl-list-item__icon" aria-hidden="true">person</span>
+    <span class="micl-list-item__text">
+      <span class="micl-list-item__headline">Bill Jones</span>
+      <span class="micl-list-item__supporting-text">bill.jones@email.com</span>
+    </span>
+  </li>
+  ```
+
+- **Avatar**: Use `micl-list-item__avatar` with an avatar image (or icon).
+  ```HTML
+  <li class="micl-list-item-two" tabindex="0">
+    <span class="material-symbols-outlined micl-list-item__avatar">account_circle</span>
+    <span class="micl-list-item__text">
+      <span class="micl-list-item__headline">Bill Jones</span>
+      <span class="micl-list-item__supporting-text">bill.jones@email.com</span>
+    </span>
+  </li>
+  ```
+
+- **Image**: Use `micl-list-item__image` with a background image.
+  ```HTML
+  <li class="micl-list-item-two" tabindex="0">
+    <span class="micl-list-item__image" style="background-image:url(https://...jpg)"></span>
+    <span class="micl-list-item__text">
+      <span class="micl-list-item__headline">Bill Jones</span>
+      <span class="micl-list-item__supporting-text">bill.jones@email.com</span>
+    </span>
+  </li>
+  ```
+
+- **Thumbnail (Video)**: Use `micl-list-item__thumbnail` for video previews with a background-image.
+  ```HTML
+  <li class="micl-list-item-two" tabindex="0">
+    <span class="micl-list-item__thumbnail" style="background-image:url(https://...mp4)"></span>
+    <span class="micl-list-item__text">
+      <span class="micl-list-item__headline">Bill Jones</span>
+      <span class="micl-list-item__supporting-text">Short clip of Bill</span>
+    </span>
+  </li>
+  ```
+
+### Trailing Content
+The text of a list item may be followed by a trailing text or other elements (like a checkbox).
+
+```HTML
+<li class="micl-list-item-one" tabindex="0">
+  <span class="micl-list-item__text">
+    <span class="micl-list-item__headline">To-do items</span>
+  </span>
+  <span class="micl-list-item__trailing-text">100+</span>
+</li>
+````
+
+### Selecting List Items
+To enable selection of list items, integrate a checkbox component within the `<li>` element. The `micl-list-item__text` should typically wrap the headline and supporting text, acting as the label for the checkbox.
+
+```HTML
+<ul class="micl-list micl-list__divider" role="listbox">
+  <li class="micl-list-item-two" tabindex="0">
+    <label for="checkbox1" class="micl-list-item__text">
+      <span class="micl-list-item__headline">Blue car</span>
+      <span class="micl-list-item__supporting-text">A blue car with four wheels.</span>
+    </label>
+    <input type="checkbox" id="checkbox1" class="micl-checkbox" value="cb1" tabindex="-1">
+  </li>
+  <li class="micl-list-item-two" tabindex="0">
+    <label for="checkbox2" class="micl-list-item__text">
+      <span class="micl-list-item__headline">Red car</span>
+      <span class="micl-list-item__supporting-text">A red car with tinted windows.</span>
+    </label>
+    <input type="checkbox" id="checkbox2" class="micl-checkbox" value="cb2" tabindex="-1">
+  </li>
+</ul>
+```
+
+- `tabindex="-1"` on the `input` is important here, as the `<li>` should handle the focus for accessibility.
+
+## Customizations
+You can customize the appearance of the List 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 lists.
+
+| Variable name | Default Value | Description |
+| ------------- | ------------- | ----------- |
+| --md-sys-list-item-one-height | 56px | The height for a single-line list item. |
+| --md-sys-list-item-two-height | 72px | The height for a two-line list item. |
+| --md-sys-list-item-three-height | 88px | The height for a three-line list item. |
+| --md-sys-list-item-one-padding | 8px | The vertical padding of a single-line list item. |
+| --md-sys-list-item-two-padding | 8px | The vertical padding of a two-line list item. |
+| --md-sys-list-item-three-padding | 12px | The vertical padding of a three-line list item. |
+| --md-sys-list-item-space | 16px | The horizontal spacing between the elements within a list item. |
+
+**Example: Changing the height of single-line list items**
+
+```HTML
+<div style="--md-sys-list-item-one-height:60px">
+  <ul class="micl-list">
+    <li class="micl-list-item-one" tabindex="0">
+      <span class="micl-list-item__text">
+        <span class="micl-list-item__headline">A single-line item</span>
+      </span>
+    </li>
+  </ul>
+</div>
+```

package/components/list/index.ts

@@ -0,0 +1,108 @@
+//
+// Copyright © 2025 Hermana AS
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+export const listSelector = '.micl-list-item-one,.micl-list-item-two,.micl-list-item-three';
+
+export default (() =>
+{
+    const
+        isDisabled = (item: HTMLElement | null): boolean => !!item && item.classList.contains('micl-list-item--disabled'),
+        isSelected = (item: HTMLElement | null): boolean => !!item && item.matches(':has(input[type=checkbox]:checked)');
+
+    return {
+        keydown: (event: Event) =>
+        {
+            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;
+            }
+
+            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) {
+                items = Array.from(parent.children).map(li => {
+                    return ((li instanceof HTMLLIElement) && !isDisabled(li)) ? li : null;
+                }).filter(item => !!item);
+            }
+            if (items.length === 0) {
+                return;
+            }
+
+            let currentIndex = items.findIndex(item => isSelected(item));
+            if (currentIndex === -1) {
+                currentIndex = items.findIndex(item => item.tabIndex === 0);
+            }
+            if (currentIndex === -1) {
+                currentIndex = 0;
+            }
+            let nextIndex = currentIndex;
+
+            switch (event.key) {
+                case 'ArrowDown':
+                    nextIndex = (currentIndex + 1) % items.length;
+                    event.preventDefault(); // prevent page scrolling
+                    break;
+                case 'ArrowUp':
+                    nextIndex = (currentIndex - 1 + items.length) % items.length;
+                    event.preventDefault();
+                    break;
+                case 'Tab':
+                    let selectedIndex = items.findIndex(item => isSelected(item));
+                    if (selectedIndex === -1) {
+                        if (currentIndex !== 0) {
+                            items[currentIndex].tabIndex = -1;
+                            items[0].tabIndex = 0;
+                        }
+                    }
+                    else if (selectedIndex !== currentIndex) {
+                        items[currentIndex].tabIndex = -1;
+                        items[selectedIndex].tabIndex = 0;
+                    }
+                    break;
+                case 'Enter':
+                case ' ':
+                    const cb = (event.target as Element).querySelector('input[type=checkbox].micl-checkbox');
+                    if (cb instanceof HTMLInputElement) {
+                        cb.checked = !cb.checked;
+                    }
+                    break;
+                default:
+            }
+            if (nextIndex !== currentIndex) {
+                items[currentIndex].tabIndex = -1;
+                items[nextIndex].tabIndex = 0;
+                items[nextIndex].focus();
+            }
+        }
+    };
+})();

package/components/list/list.scss

@@ -0,0 +1,295 @@
+//
+// Copyright © 2025 Hermana AS
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+
+@use '../../styles/motion';
+@use '../../styles/ripple';
+@use '../../styles/typography';
+
+:root {
+    --md-sys-list-item-one-height: 56px;
+    --md-sys-list-item-two-height: 72px;
+    --md-sys-list-item-three-height: 88px;
+    --md-sys-list-item-one-padding: 8px;
+    --md-sys-list-item-two-padding: 8px;
+    --md-sys-list-item-three-padding: 12px;
+    --md-sys-list-item-space: 16px;
+    --md-sys-list-item-padding-inline: 16px;
+}
+
+.micl-list {
+    --md-sys-list-item-background-color: var(--md-sys-color-surface);
+
+    margin: 0;
+    padding: 0;
+    interpolate-size: allow-keywords;
+    list-style-type: none;
+
+    &> details {
+        &::details-content {
+            height: 0;
+            overflow: hidden;
+            transition:
+                content-visibility var(--md-sys-motion-duration-medium4) allow-discrete,
+                height var(--md-sys-motion-duration-medium4) linear(motion.$md-sys-motion-spring-default-spatial);
+        }
+        &[open]::details-content {
+            height: auto;
+        }
+
+        &> summary.micl-list-item-one,
+        &> summary.micl-list-item-two,
+        &> summary.micl-list-item-three {
+            position: relative;
+
+            &::-webkit-details-marker {
+                display: none;
+            }
+            &.micl-list-item--disabled {
+                pointer-events: none;
+            }
+            &:not(.micl-list-item--disabled) {
+                --miclripple: 1;
+                @include ripple.effect;
+
+                cursor: pointer;
+            }
+        }
+        .micl-list-item__content {
+            box-sizing: border-box;
+            padding-inline: var(--md-sys-list-item-padding-inline);
+            background-color: var(--md-sys-list-item-background-color);
+            overflow: hidden;
+        }
+    }
+
+    &.micl-list__divider {
+        .micl-list-item-one + .micl-list-item-one,
+        .micl-list-item-two + .micl-list-item-two,
+        .micl-list-item-three + .micl-list-item-three,
+        details + details {
+            border-top: var(--md-sys-divider-thickness) solid var(--md-sys-divider-color);
+        }
+    }
+}
+
+.micl-list-item-one,
+.micl-list-item-two,
+.micl-list-item-three {
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    column-gap: var(--md-sys-list-item-space);
+    padding-inline: var(--md-sys-list-item-space);
+    border-radius: var(--md-sys-shape-corner-none);
+    background-color: var(--md-sys-list-item-background-color);
+    list-style: none;
+    transition: background-color var(--md-sys-motion-duration-long2) linear;
+
+    &:disabled,
+    &.micl-list-item--disabled {
+        .micl-list-item__icon,
+        .micl-list-item__text,
+        .micl-list-item__text .micl-list-item__headline,
+        .micl-list-item__text .micl-list-item__supporting-text,
+        .micl-list-item__text::after,
+        .micl-list-item__trailing-text {
+            color: rgb(from var(--md-sys-color-on-surface) r g b / 38%);
+        }
+        .micl-list-item__image,
+        .micl-list-item__thumbnail {
+            opacity: 38%;
+        }
+    }
+    &:not(:disabled):not(.micl-list-item--disabled) {
+        &:hover {
+            background-color: color-mix(in srgb, var(--md-sys-list-item-background-color), var(--md-sys-color-on-surface) var(--md-sys-state-hover-state-layer-opacity));
+
+            &:has(input[type=checkbox].micl-checkbox) {
+                cursor: pointer;
+            }
+            .micl-list-item__icon {
+                font-variation-settings: 'FILL' 1;
+            }
+        }
+        &:focus-visible {
+            outline: var(--md-sys-state-focus-indicator-thickness) solid var(--md-sys-color-secondary);
+            background-color: color-mix(in srgb, var(--md-sys-list-item-background-color), var(--md-sys-color-on-surface) var(--md-sys-state-focus-state-layer-opacity));
+            z-index: 1;
+
+            .micl-list-item__icon {
+                font-variation-settings: 'FILL' 1;
+            }
+        }
+        &:active {
+            background-color: color-mix(in srgb, var(--md-sys-list-item-background-color), var(--md-sys-color-on-surface) var(--md-sys-state-pressed-state-layer-opacity));
+
+            .micl-list-item__icon {
+                font-variation-settings: 'FILL' 1;
+            }
+        }
+        &:has(input[type=checkbox].micl-checkbox) {
+            --miclripple: 1;
+            --md-sys-ripple-background-color: var(--md-sys-color-primary);
+            @include ripple.effect;
+        }
+        &:has(input[type=checkbox].micl-checkbox:checked) {
+            background-color: var(--md-sys-color-secondary-container);
+
+            .micl-list-item__headline {
+                color: var(--md-sys-color-on-secondary-container);
+            }
+            .micl-list-item__icon,
+            .micl-list-item__supporting-text,
+            .micl-list-item__trailing-text {
+                color: var(--md-sys-color-on-surface);
+            }
+        }
+        input[type=checkbox].micl-checkbox:not(:disabled):hover,
+        input[type=checkbox].micl-checkbox:not(:disabled):active {
+            --checkbox-state-layer-color: initial;
+            --checkbox-outline-color: initial;
+            --md-sys-ripple-background-color: transparent;
+        }
+    }
+    &> a {
+        box-sizing: border-box;
+        display: flex;
+        align-items: center;
+        align-self: normal;
+        width: 100%;
+        column-gap: var(--md-sys-list-item-space);
+        text-decoration: none;
+    }
+}
+
+.micl-list-item-one {
+    min-height: var(--md-sys-list-item-one-height);
+    padding-block-start: var(--md-sys-list-item-one-padding);
+    padding-block-end: var(--md-sys-list-item-one-padding);
+
+    &:has(.micl-list-item__thumbnail) {
+        padding-block-start: var(--md-sys-list-item-three-padding);
+        padding-block-end: var(--md-sys-list-item-three-padding);
+        padding-inline-start: 0px;
+    }
+}
+.micl-list-item-two {
+    min-height: var(--md-sys-list-item-two-height);
+    padding-block-start: var(--md-sys-list-item-two-padding);
+    padding-block-end: var(--md-sys-list-item-two-padding);
+
+    &:has(.micl-list-item__thumbnail) {
+        padding-inline-start: 0px;
+        padding-block-start: 12px;
+        padding-block-end: 12px;
+    }
+    .micl-list-item__supporting-text {
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+    }
+}
+.micl-list-item-three {
+    min-height: var(--md-sys-list-item-three-height);
+    padding-block-start: var(--md-sys-list-item-three-padding);
+    padding-block-end: var(--md-sys-list-item-three-padding);
+
+    &:has(.micl-list-item__thumbnail) {
+        padding-block-start: var(--md-sys-list-item-three-padding);
+        padding-block-end: var(--md-sys-list-item-three-padding);
+        padding-inline-start: 0px;
+    }
+    .micl-list-item__icon,
+    .micl-list-item__avatar,
+    .micl-list-item__image {
+        align-self: flex-start;
+    }
+    .micl-list-item__supporting-text {
+        display: -webkit-box;
+        overflow: hidden;
+        -webkit-box-orient: vertical;
+        -webkit-line-clamp: 2;
+    }
+    input[type=checkbox].micl-checkbox {
+        align-self: flex-start;
+        margin-block-start: -12px;
+    }
+}
+
+.micl-list-item__icon {
+    color: var(--md-sys-color-on-surface-variant);
+    font-variation-settings: 'FILL' 0;
+    transition: font-variation-settings var(--md-sys-motion-duration-long2) linear;
+}
+.micl-list-item__avatar {
+    font-size: 40px;
+    border-radius: var(--md-sys-shape-corner-full);
+    color: var(--md-sys-color-primary-container);
+}
+.micl-list-item__avatar-text {
+    @include typography.title-medium;
+
+    color: var(--md-sys-on-primary-container);
+}
+.micl-list-item__image {
+    display: inline-block;
+    width: 56px;
+    height: 56px;
+    min-width: 56px;
+    min-height: 56px;
+    border-radius: var(--md-sys-shape-corner-none);
+    background-size: cover;
+}
+.micl-list-item__thumbnail {
+    display: inline-block;
+    width: auto;
+    height: 64px;
+    min-height: 64px;
+    aspect-ratio: 1.5;
+    border-radius: var(--md-sys-shape-corner-none);
+    background-size: contain;
+    background-repeat: no-repeat;
+}
+
+.micl-list-item__text {
+    display: flex;
+    flex-direction: column;
+    flex-basis: 100%;
+    min-width: 0;
+    text-align: start;
+
+    .micl-list-item__headline {
+        @include typography.body-large;
+
+        color: var(--md-sys-color-on-surface);
+    }
+    .micl-list-item__supporting-text {
+        @include typography.body-medium;
+
+        color: var(--md-sys-color-on-surface-variant);
+    }
+}
+
+.micl-list-item__trailing-text {
+    @include typography.label-small;
+
+    color: var(--md-sys-color-on-surface-variant);
+}

package/components/menu/README.md

@@ -0,0 +1,96 @@
+# Menu
+This component implements the [Material Design 3 Expressive Menu](https://m3.material.io/components/menus/overview) design. Menus provide a list of choices on a temporary surface that appears when a user interacts with a control element.
+
+## Basic Usage
+
+### HTML
+The Menu component is an extension of the [List component](../list/README.md). It consists of a `<nav>` element with the `micl-menu` class, which acts as the container for a `<ul>` with the `micl-list` class. The menu can be opened and closed using a control element with the `popovertarget` attribute.
+
+```HTML
+<nav id="mymenu" class="micl-menu" 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>
+
+<button type="button" popovertarget="mymenu">Open Basic Menu</button>
+```
+
+### CSS
+Import the styles for both the menu and list components into your project:
+
+```CSS
+@use "micl/components/list";
+@use "micl/components/menu";
+```
+
+### TypeScript
+This component requires the **Menu** TypeScript module for functionality. You can import the specific module and handle initialization manually, or use the main MICL library for automatic initialization.
+
+To manually initialize the component:
+
+```TypeScript
+import miclMenu from 'micl/components/menu';
+
+miclMenu.initialize(document.querySelector('.micl-menu'));
+```
+
+### Demo
+A live example of the [Menu component](https://henkpb.github.io/micl/menu.html) is available for you to interact with.
+
+## Variants
+Since the Menu component is based on the **List component**, all of its list item variants and content features can be used. You can incorporate icons, avatars, images, multiple lines of text, and more.
+
+**Example: A menu with graphics and supporting text**
+
+```HTML
+<nav id="mymenu" class="micl-menu" popover>
+  <ul class="micl-list">
+    <li class="micl-list-item-two" tabindex="0">
+      <span class="micl-list-item__icon material-symbols-outlined" aria-hidden="true">home</span>
+      <span class="micl-list-item__text">
+        <span class="micl-list-item__headline">Home</span>
+        <span class="micl-list-item__supporting-text">Click here to go home</span>
+      </span>
+    </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">
+        <span class="micl-list-item__headline">Person</span>
+        <span class="micl-list-item__supporting-text">This person is an administrator</span>
+      </label>
+      <input type="checkbox" id="cb" class="micl-checkbox" tabindex="-1">
+    </li>
+  </ul>
+</nav>
+```
+
+**Example: A menu with a link**
+To make a menu item function as a link, wrap its content in an `<a>` tag and set the `tabindex` to `-1`. This ensures the link is clickable but does not interfere with menu navigation.
+
+```HTML
+<nav id="mymenu" class="micl-menu" popover>
+  <ul class="micl-list">
+    <li class="micl-list-item-two micl-list-item__divider">
+      <a href="https://www.nytimes.com" tabindex="-1">
+        <span class="micl-list-item__icon material-symbols-outlined" aria-hidden="true">newspaper</span>
+        <span class="micl-list-item__text">
+          <span class="micl-list-item__headline">The New York Times</span>
+          <span class="micl-list-item__supporting-text">Clicking this item opens the front page of The New York Times</span>
+        </span>
+      </a>
+    </li>
+  </ul>
+</nav>
+```
+
+Adding the `micl-list-item--disabled` class to a menu item causes the item to be displayed in a disabled state.
+
+Add the `micl-list-item__divider` class to a menu item to create a divider between the item and the previous menu item.
+
+## Compatibility
+This component uses **popover anchor positioning** to place the menu next to its invoker. This is a modern CSS feature that may not be fully supported in all browsers. To ensure the menu works in browsers that do not support anchor positioning, wrap the menu and its invoker in a `<div>` element with `position:relative`. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/anchor#browser_compatibility) for details.