material-inspired-component-library 1.2.1 → 1.3.0

package/components/menu/README.md

@@ -4,7 +4,7 @@ This component implements the [Material Design 3 Expressive Menu](https://m3.mat
 ## 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.
+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, where the value of the attribute matches the `id` of the menu's `<nav>` element.
 
 ```HTML
 <nav id="mymenu" class="micl-menu" popover>
@@ -17,7 +17,7 @@ The Menu component is an extension of the [List component](../list/README.md). I
   </ul>
 </nav>
 
-<button type="button" popovertarget="mymenu">Open Basic Menu</button>
+<button type="button" popovertarget="mymenu">Open Menu</button>
 ```
 
 ### CSS
@@ -68,17 +68,18 @@ Since the Menu component is based on the **List component**, all of its list ite
 ```
 
 **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">
+    <li class="micl-list-item-two" tabindex="0">
       <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 class="micl-list-item__supporting-text">Open the front page of The New York Times</span>
         </span>
       </a>
     </li>
@@ -86,9 +87,71 @@ To make a menu item function as a link, wrap its content in an `<a>` tag and set
 </nav>
 ```
 
+**Example: A menu with a submenu**
+
+A menu item may trigger opening a submenu when invoked by a button. Wrap the menu item content in a `<button>` tag, set its `tabindex` to `-1` and add the `popovertarget` attribute that points to the submenu. The button acts then as the control element for the submenu.
+
+```HTML
+<nav id="mymenu" class="micl-menu" popover>
+  <ul class="micl-list">
+    <li class="micl-list-item-one" tabindex="0">
+      <button popovertarget="mysubmenu" tabindex="-1">
+        <span class="micl-list-item__text">
+          <span class="micl-list-item__headline">Item 1</span>
+        </span>
+        <span class="micl-list-item__icon material-symbols-outlined">arrow_right</span>
+      </button>
+      <nav id="mysubmenu" 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">Item 1-1</span>
+            </span>
+          </li>
+          <li class="micl-list-item-one" tabindex="0">
+            <span class="micl-list-item__text">
+              <span class="micl-list-item__headline">Item 1-2</span>
+            </span>
+          </li>
+        </ul>
+      </nav>
+    </li>
+    <li class="micl-list-item-one" tabindex="0">
+      <span class="micl-list-item__text">
+        <span class="micl-list-item__headline">Item 2</span>
+      </span>
+    </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.
 
+## 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 |
+
+**Example: Changing the maximum width**
+
+```HTML
+<div style="--md-sys-menu-width-max:320px">
+  <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>
+</div>
+```
+
 ## 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.

package/components/menu/index.scss

@@ -21,19 +21,25 @@
 
 @use '../../styles/elevation';
 @use '../../styles/motion';
-@use '../../styles/ripple';
 @use '../../styles/shapes';
-@use '../../styles/statelayer';
+
+:root {
+    --md-sys-menu-motion-spatial: #{motion.$md-sys-motion-expressive-default-spatial};
+    --md-sys-menu-motion-duration: #{motion.$md-sys-motion-expressive-default-spatial-duration};
+    --md-sys-menu-motion-duration-reverse: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
+    --md-sys-menu-width-max: 280px;
+    --md-sys-menu-width-min: 112px;
+}
 
 .micl-menu[popover] {
     position: absolute;
     inset: unset;
     inset-block-start: anchor(end);
     inset-inline-start: anchor(start);
-    position-try-fallbacks: flip-block, flip-inline;
-    min-width: 112px;
-    max-width: 280px;
-    padding-inline: 0;
+    position-try: most-block-size flip-block, flip-inline;
+    min-width: var(--md-sys-menu-width-min);
+    max-width: var(--md-sys-menu-width-max);
+    padding: 0;
     border: none;
     border-radius: var(--md-sys-shape-corner-extra-small);
     background-color: var(--md-sys-color-surface-container);
@@ -41,33 +47,25 @@
     opacity: 0;
     overflow: hidden;
     transform: scaleY(0);
-    transform-origin: top left;
+    transform-origin: left top;
     transition:
-        opacity var(--md-sys-motion-duration-medium1),
-        transform var(--md-sys-motion-duration-medium1),
-        overlay var(--md-sys-motion-duration-medium1) allow-discrete,
-        display var(--md-sys-motion-duration-medium1) allow-discrete;
+        opacity var(--md-sys-menu-motion-duration-reverse) linear,
+        transform var(--md-sys-menu-motion-duration-reverse) var(--md-sys-menu-motion-spatial),
+        overlay var(--md-sys-menu-motion-duration-reverse) linear allow-discrete,
+        display var(--md-sys-menu-motion-duration-reverse) linear allow-discrete;
 
     &:popover-open {
         opacity: 1;
         transform: scaleY(1);
         transition:
-            opacity var(--md-sys-motion-duration-long2) motion.$md-sys-motion-easing-emphasized-decelerate,
-            transform var(--md-sys-motion-duration-long2) linear(motion.$md-sys-motion-spring-default-spatial),
-            overlay var(--md-sys-motion-duration-long2) linear allow-discrete,
-            display var(--md-sys-motion-duration-long2) linear allow-discrete;
-
-        @position-try-on {
-            transform-origin: bottom left;
-        }
+            opacity var(--md-sys-menu-motion-duration) motion.$md-sys-motion-easing-emphasized-decelerate,
+            transform var(--md-sys-menu-motion-duration) var(--md-sys-menu-motion-spatial),
+            overlay var(--md-sys-menu-motion-duration) linear allow-discrete,
+            display var(--md-sys-menu-motion-duration) linear allow-discrete;
 
         @starting-style {
             opacity: 0;
             transform: scaleY(0);
-
-            @position-try-on {
-                transform-origin: bottom left;
-            }
         }
         &::backdrop {
             background-color: rgba(0, 0, 0, 0.2);
@@ -80,12 +78,13 @@
     &::backdrop {
         background-color: rgba(0, 0, 0, 0);
         transition:
-            background-color var(--md-sys-motion-duration-long2),
-            overlay var(--md-sys-motion-duration-long2) linear allow-discrete,
-            display var(--md-sys-motion-duration-long2) linear allow-discrete;
+            background-color var(--md-sys-menu-motion-duration) linear,
+            overlay var(--md-sys-menu-motion-duration) linear allow-discrete,
+            display var(--md-sys-menu-motion-duration) linear allow-discrete;
     }
 
-    .micl-list {
+    &> .micl-list {
+        --md-sys-list-padding: 4px;
         --md-sys-list-item-one-height: 48px;
         --md-sys-list-item-one-padding: 0;
         --md-sys-list-item-two-padding: 0;
@@ -95,18 +94,6 @@
         .micl-list-item-one,
         .micl-list-item-two,
         .micl-list-item-three {
-            &:not(.micl-list-item--disabled) {
-                --miclripple: 1;
-
-                @include ripple.effect;
-
-                cursor: pointer;
-
-                &:focus-visible {
-                    outline-offset: calc(-1 * var(--md-sys-state-focus-indicator-thickness));
-                    z-index: 1;
-                }
-            }
             &.micl-list-item__divider {
                 position: relative;
                 margin-block-start: 16px;
@@ -122,6 +109,23 @@
                     border-top: var(--md-sys-divider-thickness) solid var(--md-sys-divider-color);
                 }
             }
+            &> .micl-menu[popover] {
+                transform: scaleX(0);
+
+                &:popover-open {
+                    transform: scaleX(1);
+
+                    @starting-style {
+                        transform: scaleX(0);
+                    }
+                }
+                &:popover-open {
+                    &::backdrop {
+                        background-color: rgba(0, 0, 0, 0);
+                    }
+                }
+            }
         }
     }
 }
+

package/components/menu/index.ts

@@ -21,27 +21,15 @@
 
 export const menuSelector = '.micl-menu[popover]';
 
-/**
- * Set the origin for menu transformations just before transitions start.
- * By default, the origin is "top left" (the menu opens just below the invoker, left aligned),
- * but could also be "top right", "bottom left" or "bottom right".
- * When the browser needs to apply a position-try-fallbacks, because there is not enough space
- * for the menu in the default location, then the reverse transformation will be applied from
- * the wrong origin.
- * Therefore, when the menu is open, calculate the transformation origin just before the
- * transitions start. When the menu is closed, do the same just after the 'display:none' has
- * been removed by the browser (the 'toggle' event has then been triggered).
- */
 export default (() =>
 {
     const getOrigin = (invoker: Element, popover: Element): string =>
     {
-        const invokerY  = invoker.getBoundingClientRect().y,
-              popoverY  = popover.getBoundingClientRect().y,
-              oldOrigin = window.getComputedStyle(popover).getPropertyValue('transform-origin');
+        const invokerRect = invoker.getBoundingClientRect(),
+              popoverRect = popover.getBoundingClientRect();
 
-        return ((invokerY > popoverY) ? 'bottom ' : 'top ') +
-               ((parseInt(oldOrigin) > 0) ? 'right' : 'left');
+        return ((invokerRect.x > popoverRect.x) ? 'right ' : 'left ') +
+               ((invokerRect.y > popoverRect.y) ? 'bottom' : 'top');
     };
 
     return {
@@ -72,6 +60,49 @@ export default (() =>
                 }
             });
 
+            element.querySelectorAll<HTMLButtonElement>(
+                ':scope > ul.micl-list > li > button[popovertarget]'
+            ).forEach(submenuinvoker =>
+            {
+                if (submenuinvoker.popoverTargetElement?.matches('.micl-menu[popover]')) {
+                    let hoverTimeout: any,
+                        id = `--${submenuinvoker.popoverTargetElement.id}`;
+
+                    if (submenuinvoker.popoverTargetElement instanceof HTMLElement) {
+                        submenuinvoker.style.setProperty('anchor-name', id);
+                        submenuinvoker.popoverTargetElement.style.insetBlockStart = `anchor(${id} start)`;
+                        submenuinvoker.popoverTargetElement.style.insetInlineStart = `anchor(${id} end)`;
+                    }
+
+                    submenuinvoker.addEventListener('mouseenter', () =>
+                    {
+                        if (submenuinvoker.popoverTargetElement instanceof HTMLElement) {
+                            submenuinvoker.popoverTargetElement.showPopover();
+                        }
+                    });
+                    submenuinvoker.addEventListener('mouseleave', () =>
+                    {
+                        hoverTimeout = setTimeout(() => {
+                            if (
+                                submenuinvoker.popoverTargetElement instanceof HTMLElement
+                                && !submenuinvoker.popoverTargetElement.matches(':hover')
+                            ) {
+                                submenuinvoker.popoverTargetElement.hidePopover();
+                            }
+                        }, 100);
+                    });
+                    submenuinvoker.popoverTargetElement.addEventListener('mouseenter', () =>
+                    {
+                        clearTimeout(hoverTimeout);
+                    });
+                    submenuinvoker.popoverTargetElement.addEventListener('mouseleave', () =>
+                    {
+                        if (submenuinvoker.popoverTargetElement instanceof HTMLElement) {
+                            submenuinvoker.popoverTargetElement.hidePopover();
+                        }
+                    });
+                }
+            });
         }
     };
 })();

package/components/navigationrail/README.md

@@ -0,0 +1,99 @@
+# Side sheet
+This component implements the the [Material Design 3 Expressive Side sheet](https://m3.material.io/components/side-sheets/overview) design.
+
+## Basic Usage
+
+### HTML
+To create a standard side sheet, use the `<dialog>` element with the `popover` attribute. The `closedby="any"` attribute allows the user to dismiss the side sheet by clicking anywhere outside of it.
+
+```HTML
+<dialog id="mysidesheet" class="micl-sidesheet" closedby="any" popover>
+  <div class="micl-sidesheet__headline">
+    <h2>Title</h2>
+    <button
+      type="button"
+      class="micl-iconbutton-s material-symbols-outlined"
+      popovertarget="mysidesheet"
+      aria-label="Close"
+    >close</button>
+  </div>
+  <div class="micl-sidesheet__content">
+    ...your content...
+  </div>
+</dialog>
+```
+
+### CSS
+Import the side sheet styles into your project:
+
+```CSS
+@use "material-inspired-component-library/dist/sidesheet";
+```
+
+### JavaScript
+No custom JavaScript is required for the core functionality of the side sheet component.
+
+### Demo
+A live example of the [Side sheet component](https://henkpb.github.io/micl/sidesheet.html) is available for you to interact with.
+
+## Variants
+A **modal** side sheet blocks access to the rest of the page and must be dismissed explicitly by the user. This is suitable for critical tasks or information that requires a user's full attention.
+
+To create a modal side sheet, use the `<dialog>` element without the `popover` attribute. Use `closedby="closerequest"` to prevent the side sheet from being dismissed by clicking outside of it. You'll also need a button or other control with popovertarget to close it.
+
+```HTML
+<dialog id="mysidesheet" class="micl-sidesheet" closedby="closerequest">
+  <div class="micl-sidesheet__headline">
+    <button
+      type="button"
+      class="micl-iconbutton-s material-symbols-outlined"
+      aria-label="Go back"
+    >arrow_back</button>
+    <h2>Title</h2>
+    <button
+      type="button"
+      class="micl-iconbutton-s material-symbols-outlined"
+      popovertarget="mysidesheet"
+      aria-label="Close"
+    >close</button>
+  </div>
+  <div class="micl-sidesheet__content">
+    ...your content...
+  </div>
+  <div class="micl-sidesheet__actions">
+    <button type="button" class="micl-button">Save</button>
+  </div>
+</dialog>
+```
+
+To open either a standard or modal side sheet, link a button to the side sheet's ID using the `popovertarget` attribute:
+```HTML
+<button type="button" popovertarget="mysidesheet">Open Side Sheet</button>
+```
+
+The back-button and the actions-container are optional. To remove the vertical divider of the "standard" side sheet, assign zero to the following CSS variable:
+```CSS
+#mysidesheet {
+  --md-sys-sidesheet-divider-width: 0;
+}
+```
+To remove the horizontal divider of the actions-container:
+```CSS
+#mysidesheet {
+  --md-sys-sidesheet-actions-divider-width: 0;
+}
+```
+
+### Warning
+The **standard** side sheet component adds CSS rules to the `<body>` element to properly resize the main content area when the side sheet is open. Overriding these rules may cause the component to behave unexpectedly. The rules that are applied are:
+
+```CSS
+box-sizing: border-box;
+margin-left: 0px;
+margin-right: 0px;
+max-width: ...varies depending on if the side sheet is opened...
+transition: ...transition on max-width...
+```
+
+## Compatibility
+This component uses the Popover API, which might not be supported in all browsers. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API#api.htmlelement.popover) for details.

package/components/navigationrail/index.scss

@@ -0,0 +1,157 @@
+//
+// 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/elevation';
+@use '../../styles/motion';
+@use '../../styles/shapes';
+@use '../../styles/typography';
+
+dialog.micl-navigationrail {
+    --md-sys-navigationrail-width: 256px;
+    --md-sys-navigationrail-maxwidth: 400px;
+    --md-sys-navigationrail-spring-buffer: 200px;
+    --md-sys-navigationrail-padding-standard: 24px;
+    --md-sys-navigationrail-padding-modal: 16px;
+    --md-sys-navigationrail-motion-spatial: #{motion.$md-sys-motion-expressive-slow-spatial};
+    --md-sys-navigationrail-motion-duration: #{motion.$md-sys-motion-expressive-slow-spatial-duration};
+    --md-sys-navigationrail-motion-duration-reverse: #{motion.$md-sys-motion-expressive-default-spatial-duration};
+
+    box-sizing: border-box;
+    display: none;
+    flex-direction: column;
+    justify-content: space-between;
+    min-width: calc(var(--md-sys-navigationrail-width) + var(--md-sys-navigationrail-spring-buffer));
+    max-width: calc(var(--md-sys-navigationrail-maxwidth) + var(--md-sys-navigationrail-spring-buffer));
+    height: 100%;
+    min-height: 100%;
+    margin-block: 0;
+    margin-inline-start: calc(-1 * (var(--md-sys-navigationrail-maxwidth) + var(--md-sys-navigationrail-spring-buffer)));
+    margin-inline-end: auto;
+    padding-block-start: 10px;
+    padding-block-end: var(--md-sys-navigationrail-padding-standard);
+    padding-inline-start: var(--md-sys-navigationrail-spring-buffer);
+    padding-inline-end: 0;
+    background-color: var(--md-sys-color-surface);
+    border: none;
+    box-shadow: var(--md-sys-elevation-level0);
+    opacity: 0;
+    overflow: hidden;
+    transition:
+        opacity var(--md-sys-navigationrail-motion-duration-reverse) linear,
+        margin-inline-start var(--md-sys-navigationrail-motion-duration-reverse) var(--md-sys-navigationrail-motion-spatial),
+        overlay var(--md-sys-navigationrail-motion-duration-reverse) linear allow-discrete,
+        display var(--md-sys-navigationrail-motion-duration-reverse) linear allow-discrete;
+
+    .micl-navigationrail__headline {
+        display: flex;
+        align-items: center;
+        padding-inline-start: 12px;
+        padding-inline-end: 24px;
+        column-gap: 8px;
+        color: var(--md-sys-color-on-surface-variant);
+
+        h1, h2, h3, h4, h5, h6, .micl-heading {
+            @include typography.title-large;
+
+            flex: 1 2 fit-content;
+            margin: 0;
+            overflow: hidden;
+            text-overflow: ellipsis;
+            white-space: nowrap;
+            user-select: none;
+        }
+    }
+    .micl-navigationrail__content {
+        box-sizing: border-box;
+        display: flex;
+        flex-direction: column;
+        flex: 1 1 auto;
+        align-items: flex-start;
+        row-gap: 8px;
+        width: 100%;
+        max-width: 100%;
+        padding-inline: var(--md-sys-navigationrail-padding-standard);
+        overflow: hidden auto;
+    }
+    .micl-navigationrail__actions {
+        box-sizing: border-box;
+        display: flex;
+        align-items: center;
+        justify-content: start;
+        width: 100%;
+        max-width: 100%;
+        height: calc(72px - var(--md-sys-navigationrail-padding-standard));
+        margin: auto 0 0 0;
+        padding-block-start: 16px;
+        overflow: hidden;
+        border-block-start: var(--md-sys-divider-thickness) solid var(--md-sys-divider-color);
+
+        button:active,
+        button:focus-visible,
+        button:hover {
+            color: var(--md-sys-color-primary);
+        }
+    }
+
+    &::backdrop {
+        background-color: rgba(0, 0, 0, 0);
+        transition:
+            background-color var(--md-sys-navigationrail-motion-duration) linear,
+            overlay var(--md-sys-navigationrail-motion-duration) linear allow-discrete,
+            display var(--md-sys-navigationrail-motion-duration) linear allow-discrete;
+    }
+    &[open] {
+        background-color: var(--md-sys-color-surface-container-low);
+        border-start-end-radius: var(--md-sys-shape-corner-large);
+        border-end-end-radius: var(--md-sys-shape-corner-large);
+        box-shadow: var(--md-sys-elevation-level1);
+
+        .micl-navigationrail__headline {
+            padding-inline-end: 4px;
+        }
+    }
+    &:popover-open {
+        border-inline-end: var(--md-sys-divider-thickness) solid var(--md-sys-divider-color);
+    }
+    &:popover-open,
+    &[open] {
+        display: flex;
+        margin-inline-start: calc(-1 * var(--md-sys-navigationrail-spring-buffer));
+        opacity: 1;
+        transition:
+            opacity var(--md-sys-navigationrail-motion-duration) linear,
+            margin-inline-start var(--md-sys-navigationrail-motion-duration) var(--md-sys-navigationrail-motion-spatial),
+            overlay var(--md-sys-navigationrail-motion-duration) linear allow-discrete,
+            display var(--md-sys-navigationrail-motion-duration) linear allow-discrete;
+
+        @starting-style {
+            margin-inline-start: calc(-1 * (var(--md-sys-navigationrail-maxwidth) + var(--md-sys-navigationrail-spring-buffer)));
+            opacity: 0;
+        }
+    }
+    &[open]::backdrop {
+        background-color: rgba(0, 0, 0, 0.2);
+
+        @starting-style {
+            background-color: rgba(0, 0, 0, 0);
+        }
+    }
+}