material-inspired-component-library 8.1.0 → 9.0.0

package/components/navigationbar/index.scss

@@ -0,0 +1,185 @@
+//
+// 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 '../../foundations/layout';
+@use '../../styles/elevation';
+@use '../../styles/statelayer';
+@use '../navigationrail/navitem';
+
+@include elevation.level(0);
+@include elevation.level(2);
+
+@include statelayer.token('hover-state-layer-opacity');
+@include statelayer.token('focus-state-layer-opacity');
+@include statelayer.token('pressed-state-layer-opacity');
+@include statelayer.token('ripple-opacity-factor');
+@include statelayer.token('ripple-duration');
+@include statelayer.property;
+@include statelayer.keyframes;
+
+nav.micl-navigationbar {
+    box-sizing: border-box;
+    position: fixed;
+    inset-block: auto 0;
+    inset-inline: 0;
+    padding-block-end: env(safe-area-inset-bottom);
+    background-color: var(--md-comp-nav-bar-container-color, var(--md-sys-color-surface-container));
+    box-shadow: var(--md-comp-nav-bar-container-elevation, var(--md-sys-elevation-level2));
+    border-radius: var(--md-comp-nav-bar-container-shape, 0px);
+    z-index: 9;
+
+    &> .micl-navigationbar__content {
+        box-sizing: border-box;
+        display: flex;
+        align-items: flex-start;
+        justify-content: space-evenly;
+        block-size: var(--md-comp-nav-bar-container-height, 64px);
+        padding-block-start: 6px;
+
+        &> a.micl-navigationbar__item {
+            @extend %micl-navitem;
+
+            flex-direction: column;
+            inline-size: var(--md-comp-nav-bar-item-vertical-active-indicator-width, 56px);
+            block-size: var(--md-comp-nav-bar-item-vertical-active-indicator-height, 32px);
+            border-radius: var(--md-comp-nav-bar-item-active-indicator-shape, calc(var(--md-comp-nav-bar-item-vertical-active-indicator-height, 32px) / 2));
+
+            .micl-navigationbar__icon {
+                @extend %micl-navitem-icon;
+                font-size: var(--md-comp-nav-bar-item-icon-size, var(--md-sys-icon-size));
+                inline-size: var(--md-comp-nav-bar-item-icon-size, var(--md-sys-icon-size));
+                padding-inline: 16px;
+            }
+            .micl-navigationbar__text {
+                @extend %micl-navitem-text;
+                margin-block-start: var(--md-comp-nav-bar-item-active-indicator-icon-label-space, 4px);
+                white-space: nowrap;
+                text-overflow: ellipsis;
+            }
+        }
+
+        &> a.micl-navigationbar__item[aria-current="page"] {
+            @extend %micl-navitem-current;
+
+            .micl-navigationbar__icon {
+                @extend %micl-navitem-current-icon;
+            }
+            .micl-navigationbar__text {
+                @extend %micl-navitem-current-text;
+            }
+        }
+    }
+
+    // Tall bar (80px): the item stack is vertically centered
+    &.micl-navigationbar--tall > .micl-navigationbar__content {
+        block-size: var(--md-comp-nav-bar-tall-container-height, 80px);
+        padding-block-start: 14px;
+    }
+
+    // Horizontal items: icon and label side by side in a 40px pill
+    &.micl-navigationbar--horizontal > .micl-navigationbar__content {
+        align-items: center;
+        padding-block-start: 0;
+
+        &> a.micl-navigationbar__item {
+            flex-direction: row;
+            inline-size: fit-content;
+            max-inline-size: 100%;
+            block-size: var(--md-comp-nav-bar-item-horizontal-active-indicator-height, 40px);
+            border-radius: var(--md-comp-nav-bar-item-active-indicator-shape, calc(var(--md-comp-nav-bar-item-horizontal-active-indicator-height, 40px) / 2));
+
+            .micl-navigationbar__icon {
+                padding-inline:
+                    var(--md-comp-nav-bar-item-horizontal-active-indicator-leading-space, 16px)
+                    var(--md-comp-nav-bar-item-active-indicator-icon-label-space, 4px);
+            }
+            .micl-navigationbar__text {
+                margin-block-start: 0;
+                padding-inline-end: var(--md-comp-nav-bar-item-horizontal-active-indicator-trailing-space, 16px);
+            }
+        }
+    }
+}
+
+// Reserve space at the bottom of the page for the fixed navigation bar
+// (higher specificity than the padding shorthand of body.micl-window)
+body:has(nav.micl-navigationbar) {
+    padding-block-end: calc(var(--md-comp-nav-bar-container-height, 64px) + env(safe-area-inset-bottom));
+}
+body:has(nav.micl-navigationbar--tall) {
+    padding-block-end: calc(var(--md-comp-nav-bar-tall-container-height, 80px) + env(safe-area-inset-bottom));
+}
+
+// Adaptive navigation: a navigation bar below the named breakpoint and a
+// collapsed navigation rail (using the nav-rail tokens) at the breakpoint
+// and above. The item anatomy is shared, so only the container changes.
+$_breakpoints: (
+    medium:   layout.$md-sys-breakpoint-medium-min,
+    expanded: layout.$md-sys-breakpoint-expanded-min,
+);
+
+@each $name, $min in $_breakpoints {
+    @media (min-width: $min) {
+        nav.micl-navigationbar--bar-to-#{$name} {
+            display: flex;
+            flex-direction: column;
+            position: sticky;
+            float: inline-start;
+            inset: unset;
+            inset-block-start: 0;
+            inline-size: var(--md-comp-nav-rail-collapsed-container-width, 96px);
+            block-size: 100vh;
+            min-block-size: 100%;
+            margin-inline: calc(-1 * var(--md-sys-layout-window-margin, 0px)) auto;
+            padding-block: var(--md-comp-nav-rail-collapsed-top-space, 44px) 0;
+            background-color: var(--md-comp-nav-rail-collapsed-container-color, var(--md-sys-color-surface));
+            box-shadow: var(--md-comp-nav-rail-collapsed-container-elevation, var(--md-sys-elevation-level0));
+            border-radius: var(--md-comp-nav-rail-collapsed-container-shape, 0px);
+            border-inline-end: var(--md-comp-nav-rail-divider-thickness, 0px) solid var(--md-comp-nav-rail-divider-color, var(--md-comp-divider-color));
+            overflow: hidden;
+
+            &> .micl-navigationbar__content {
+                flex: 1 1 auto;
+                flex-direction: column;
+                justify-content: flex-start;
+                inline-size: 100%;
+                block-size: auto;
+                row-gap: var(--md-comp-nav-rail-item-container-vertical-space, 6px);
+                padding-block: var(--md-comp-nav-rail-item-header-space-minimum, 40px) 16px;
+                padding-inline: 20px;
+                overflow: hidden auto;
+
+                &> a.micl-navigationbar__item {
+                    margin-block-end: 40px;
+                    row-gap: var(--md-comp-nav-rail-collapsed-item-vertical-space, 4px);
+                }
+            }
+        }
+
+        // in rail mode the bottom of the page no longer needs to be reserved
+        body.micl-window:has(nav.micl-navigationbar--bar-to-#{$name}) {
+            padding-block-end: var(--md-sys-layout-window-margin, 0px);
+        }
+        body:not(.micl-window):has(nav.micl-navigationbar--bar-to-#{$name}) {
+            padding-block-end: 0;
+        }
+    }
+}

package/components/navigationrail/README.md

@@ -25,6 +25,7 @@ To create a simple navigation rail, use a `<nav>` element with the `micl-navigat
 Import the navigation rail styles into your project:
 
 ```CSS
+@use "material-inspired-component-library/dist/iconbutton";
 @use "material-inspired-component-library/dist/navigationrail";
 ```
 
@@ -53,6 +54,7 @@ The basic example creates a **collapsed** navigation rail. Add a menu button to
       type="button"
       id="mybutton"
       class="micl-iconbutton-standard-s micl-button--toggle material-symbols-outlined"
+      aria-pressed="false"
       command="--micl-toggle"
       commandfor="mybutton"
       data-miclicon="menu"
@@ -66,7 +68,7 @@ The basic example creates a **collapsed** navigation rail. Add a menu button to
 </nav>
 ```
 
-When the user clicks the menu button, the navigation rail is expanded and the toggle button is given the `micl-button--selected` class and the `micl-button--toggled` class that indicates that the toggle button has been clicked at least once.
+When the user clicks the menu button, the navigation rail is expanded and the toggle button is given `aria-pressed="true"` and the `micl-button--toggled` class that indicates that the toggle button has been clicked at least once.
 
 ### Modal navigation rail
 
@@ -100,47 +102,70 @@ A **modal** navigation rail is hidden until the user clicks a menu button. When
 
 The button inside the navigation rail is used to hide the navigation rail, while the button outside is responsible for opening it.
 
-## Customizations
-You can customize the appearance of the Navigation rail 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 navigation rails.
+### Adaptive navigation rail
 
-| Variable name | Default Value | Description |
-| ------------- | ------------- | ----------- |
-| --md-comp-nav-rail-divider-thickness | 0px | The width of the vertical divider at the end of the rail |
-| --md-comp-nav-rail-divider-color |  | The color of the vertical divider |
+An **adaptive** navigation rail is permanently visible as a standard (expanded) navigation rail on wide screens, and acts as a modal navigation rail on narrow screens. Add one of the following modifier classes to a modal navigation rail:
 
-The Navigation rail component supports the following CSS variables, as defined in the [Material Design 3 Expressive Navigation rail Specification](https://m3.material.io/components/navigation-rail/specs):
+| Class | Modal below | Standard from |
+| ----- | ----------- | ------------- |
+| `micl-navigationrail--modal-to-medium` | `600px` | `600px` |
+| `micl-navigationrail--modal-to-expanded` | `840px` | `840px` |
+| `micl-navigationrail--modal-to-large` | `1200px` | `1200px` |
+| `micl-navigationrail--modal-to-extralarge` | `1600px` | `1600px` |
+
+```HTML
+<dialog id="mynavigationrail" class="micl-navigationrail micl-navigationrail--modal-to-expanded" closedby="closerequest">
+  ...
+</dialog>
+```
+
+Place the `<dialog>` element where a standard `<nav>` navigation rail would go, so that it occupies its usual position when the wide-screen layout applies. The open and close buttons only serve the modal behaviour, so hide them on wide screens, for example:
 
 ```CSS
---md-comp-nav-rail-item-icon-size
---md-comp-nav-rail-item-active-indicator-leading-space
---md-comp-nav-rail-item-active-indicator-icon-label-space
---md-comp-nav-rail-item-active-indicator-trailing-space
---md-comp-nav-rail-item-container-height
---md-comp-nav-rail-item-short-container-height
---md-comp-nav-rail-item-container-shape
---md-comp-nav-rail-item-container-vertical-space
---md-comp-nav-rail-item-header-space-minimum
---md-comp-nav-rail-collapsed-container-width
---md-comp-nav-rail-collapsed-narrow-container-width
---md-comp-nav-rail-collapsed-container-elevation
---md-comp-nav-rail-collapsed-container-shape
---md-comp-nav-rail-collapsed-container-color
---md-comp-nav-rail-collapsed-item-vertical-space
---md-comp-nav-rail-collapsed-top-space
---md-comp-nav-rail-expanded-container-width-minimum
---md-comp-nav-rail-expanded-container-width-maximum
---md-comp-nav-rail-expanded-top-space
---md-comp-nav-rail-expanded-container-elevation
---md-comp-nav-rail-expanded-modal-container-elevation
---md-comp-nav-rail-expanded-container-color
---md-comp-nav-rail-expanded-modal-container-color
---md-comp-nav-rail-expanded-container-shape
---md-comp-nav-rail-expanded-modal-container-shape
---md-comp-nav-rail-item-vertical-active-indicator-height
---md-comp-nav-rail-item-vertical-active-indicator-width
---md-comp-nav-rail-item-horizontal-full-width-leading-space
+@media (min-width: 840px) {
+  [commandfor="mynavigationrail"] {
+    display: none;
+  }
+}
 ```
 
+> [!NOTE]
+> If the modal navigation rail is open while the window is resized across the breakpoint, it remains modal until dismissed, after which it becomes the permanently visible standard rail.
+
+## Theming
+Each navigation rail can be themed with CSS custom properties that follow the Material Design 3 component-token naming convention.
+
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-nav-rail-divider-thickness` | The width of the vertical divider at the end of the rail | `0px` |
+| `--md-comp-nav-rail-divider-color` | The color of the vertical divider | `--md-comp-divider-color` |
+| `--md-comp-nav-rail-collapsed-container-width` | The width of the collapsed navigation rail | `96px` |
+| `--md-comp-nav-rail-collapsed-container-color` | The background color of the collapsed navigation rail | `--md-sys-color-surface` |
+| `--md-comp-nav-rail-collapsed-container-elevation` | The shadow (elevation) of the collapsed navigation rail | `--md-sys-elevation-level0` |
+| `--md-comp-nav-rail-collapsed-container-shape` | The corner rounding of the collapsed navigation rail | `0px` |
+| `--md-comp-nav-rail-collapsed-top-space` | The space between the top edge and the header of the collapsed navigation rail | `44px` |
+| `--md-comp-nav-rail-collapsed-item-vertical-space` | The space between the icon and the label of a collapsed item | `4px` |
+| `--md-comp-nav-rail-expanded-container-width-minimum` | The smallest allowed width of the expanded navigation rail | `220px` |
+| `--md-comp-nav-rail-expanded-container-width-maximum` | The largest allowed width of the expanded navigation rail | `360px` |
+| `--md-comp-nav-rail-expanded-container-color` | The background color of the expanded navigation rail | `--md-sys-color-surface` |
+| `--md-comp-nav-rail-expanded-container-elevation` | The shadow (elevation) of the expanded navigation rail | `--md-sys-elevation-level0` |
+| `--md-comp-nav-rail-expanded-container-shape` | The corner rounding of the expanded navigation rail | `0px` |
+| `--md-comp-nav-rail-expanded-top-space` | The space between the top edge and the header of the expanded navigation rail | `44px` |
+| `--md-comp-nav-rail-expanded-modal-container-color` | The background color of the modal navigation rail | `--md-sys-color-surface-container` |
+| `--md-comp-nav-rail-expanded-modal-container-elevation` | The shadow (elevation) of the modal navigation rail | `--md-sys-elevation-level2` |
+| `--md-comp-nav-rail-expanded-modal-container-shape` | The corner rounding of the modal navigation rail, applied to the two corners facing the content | `--md-sys-shape-corner-large` |
+| `--md-comp-nav-rail-item-icon-size` | The size of the item icons | `--md-sys-icon-size` |
+| `--md-comp-nav-rail-item-container-shape` | The corner rounding of an item's active indicator | half the item height |
+| `--md-comp-nav-rail-item-container-vertical-space` | The vertical space between items | `6px` |
+| `--md-comp-nav-rail-item-header-space-minimum` | The minimum space between the header and the first item | `40px` |
+| `--md-comp-nav-rail-item-short-container-height` | The height of items in an expanded navigation rail, and of items without a label | `56px` |
+| `--md-comp-nav-rail-item-vertical-active-indicator-width` | The width of an item's active indicator in a collapsed navigation rail | `56px` |
+| `--md-comp-nav-rail-item-vertical-active-indicator-height` | The height of an item's active indicator in a collapsed navigation rail | `32px` |
+| `--md-comp-nav-rail-item-active-indicator-leading-space` | The space between the start edge of the active indicator and the icon | `16px` |
+| `--md-comp-nav-rail-item-active-indicator-trailing-space` | The space between the icon and the end edge of the active indicator | `16px` |
+| `--md-comp-nav-rail-item-active-indicator-icon-label-space` | The space between the icon and the label of an expanded item | `8px` |
+| `--md-comp-nav-rail-item-horizontal-full-width-trailing-space` | The space between the end of an expanded item's click target and the container edge | `16px` |
+
 **Example: Changing the width of the collapsed navigation rail**
 
 ```HTML
@@ -151,7 +176,7 @@ The Navigation rail component supports the following CSS variables, as defined i
 </div>
 ```
 
-To add a vertical divider of the to the navigation rail, set the following CSS variable:
+To add a vertical divider to the navigation rail, set the following CSS variable:
 
 ```CSS
 #mynavigationrail {

package/components/navigationrail/_navitem.scss

@@ -0,0 +1,96 @@
+//
+// 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.
+
+// Shared navigation item anatomy, used by the Navigation rail and the
+// Navigation bar components (placeholders only — emits no CSS on its own).
+// The two components share the MD3 item colors, state layers and ripple;
+// geometry and component tokens stay with each component.
+
+@use '../../styles/motion';
+@use '../../styles/typography';
+
+@include typography.scale('label-medium');
+
+%micl-navitem {
+    --micl-ripple: 1;
+    --statelayer-color: var(--md-sys-color-on-secondary-container);
+
+    box-sizing: border-box;
+    display: flex;
+    position: relative;
+    align-items: center;
+    outline: none;
+    text-decoration: none;
+    cursor: pointer;
+
+    overflow: visible;
+    background-color: transparent;
+    background-image:
+        radial-gradient(
+            circle at var(--micl-x, center) var(--micl-y, center),
+            transparent 0%,
+            rgb(from var(--statelayer-color) r g b / calc(var(--statelayer-opacity) * var(--md-sys-state-ripple-opacity-factor))) 10%,
+            transparent 10%
+        ),
+        linear-gradient(rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)));
+    background-repeat: no-repeat;
+    background-position: var(--micl-x, center) var(--micl-y, center), 0 0;
+    background-size: 0%, 100%;
+
+    &:focus-visible {
+        --statelayer-opacity: var(--md-sys-state-focus-state-layer-opacity, 10%);
+    }
+    &:hover {
+        --statelayer-opacity: var(--md-sys-state-hover-state-layer-opacity, 8%);
+    }
+    &:active {
+        --statelayer-opacity: var(--md-sys-state-pressed-state-layer-opacity, 10%);
+    }
+    &.micl-rippling {
+        animation: micl-ripple calc(var(--md-sys-state-ripple-duration) * 1.333);
+    }
+}
+
+%micl-navitem-icon {
+    margin: 0;
+    padding-block: 4px;
+    color: var(--md-sys-color-on-surface-variant);
+    font-variation-settings: 'FILL' 0;
+}
+
+%micl-navitem-text {
+    @include typography.label-medium;
+    min-block-size: var(--md-sys-typescale-label-medium-line-height);
+    margin: 4px 0px 0px 0px;
+    color: var(--md-sys-color-on-surface-variant);
+    overflow: hidden;
+}
+
+%micl-navitem-current {
+    background-color: var(--md-sys-color-secondary-container);
+}
+%micl-navitem-current-icon {
+    color: var(--md-sys-color-on-secondary-container);
+    font-variation-settings: 'FILL' 1;
+}
+%micl-navitem-current-text {
+    color: var(--md-sys-color-secondary);
+}