material-inspired-component-library 1.3.0 → 2.0.0

package/README.md

@@ -79,6 +79,7 @@ This will initialize all MICL components, including those that will be added to
 ## Available components ✅
 The library currently consists of the following components:
 - [x] [Accordion](components/accordion/README.md)
+- [x] [Badge](components/badge/README.md)
 - [x] [Bottom sheet](components/bottomsheet/README.md)
 - [x] [Button](components/button/README.md)
 - [x] [Card](components/card/README.md)
@@ -88,7 +89,7 @@ The library currently consists of the following components:
 - [x] [Icon button](components/iconbutton/README.md)
 - [x] [List](components/list/README.md)
 - [x] [Menu](components/menu/README.md)
-- [ ] [Navigation rail](components/navigationrail/README.md)
+- [x] [Navigation rail](components/navigationrail/README.md)
 - [x] [Radio button](components/radio/README.md)
 - [x] [Select](components/select/README.md)
 - [x] [Side sheet](components/sidesheet/README.md)
@@ -98,6 +99,13 @@ The library currently consists of the following components:
 
 ## Change Log
 
+### 2.0.0 (04.09.2025)
+**Features**
+
+- **Navigation rail**: New component.
+- **Badge**: New component.
+- **Ripple**: Now uses custom CSS properties.
+
 ### 1.3.0 (23.08.2025)
 **Features**
 

package/components/badge/README.md

@@ -0,0 +1,65 @@
+# Badge
+This component implements the the [Material Design 3 Expressive Badge](https://m3.material.io/components/badges/overview) design. Badges are small status indicators that can show a count or simply signal new information.
+
+## Basic Usage
+
+### HTML
+To add a large badge, use a `<span>` element with the `micl-badge-large` class and add a short text inside. For a small badge, which is a simple dot, use a `<span>` with the `micl-badge-small` class and leave the element empty.
+
+```HTML
+<span class="micl-badge-large">57</span>
+
+<span class="micl-badge-small"></span>
+```
+
+### CSS
+Import the badge styles into your project:
+
+```CSS
+@use "material-inspired-component-library/dist/badge";
+```
+
+### JavaScript
+No custom JavaScript is required for the core functionality of this component.
+
+### Demo
+A live example of the [Badge component](https://henkpb.github.io/micl/index.html) is available for you to interact with.
+
+## Anchoring
+Badges are typically placed on top of other elements, like icons. To anchor a badge to a specific element, use CSS `anchor positioning`.
+
+1. Assign a unique `anchor-name` to the element you want to anchor the badge to. The value should start with `--`.
+2. Use the `position-anchor` CSS property on the badge and set its value to the `anchor-name` of the target element.
+
+```HTML
+<span class="material-symbols-outlined" style="anchor-name:--inbox">inbox</span>
+<span class="micl-badge-large" style="position-anchor:--inbox">57</span>
+```
+
+You can fine-tune the badge's position relative to its anchor using the following CSS variables:
+
+| Variable name | Default Value | Description |
+| ------------- | ------------- | ----------- |
+| --md-sys-badge-inline-offset | 0px | Adjusts the horizontal position of the badge |
+| --md-sys-badge-block-offset | 0px | Adjusts the vertical position of the badge |
+
+
+## Customizations
+You can customize the appearance of the Badge 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 badges.
+
+| Variable name | Default Value | Description |
+| ------------- | ------------- | ----------- |
+| --md-sys-badge-small-size | 6px | The height and width of the small badge |
+| --md-sys-badge-large-size | 16px | The height and minimum width of the large badge |
+| --md-sys-badge-large-padding | 4px | The horizontal padding used for the large badge |
+
+**Example: Changing the size of the small badge**
+
+```HTML
+<div style="--md-sys-badge-small-size:8px">
+  <span class="micl-badge-small"></span>
+</div>
+```
+
+## Compatibility
+This component uses **anchor positioning**, a modern CSS feature that may not be fully supported in all browsers. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/anchor#browser_compatibility) for details.

package/components/badge/index.scss

@@ -0,0 +1,68 @@
+//
+// 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/typography';
+
+:root {
+    --md-sys-badge-small-size: 6px;
+    --md-sys-badge-large-size: 16px;
+    --md-sys-badge-large-padding: 4px;
+}
+
+.micl-badge-small {
+    --md-sys-badge-inline-offset: 0px;
+    --md-sys-badge-block-offset: 0px;
+
+    box-sizing: border-box;
+    position: fixed;
+    inline-size: var(--md-sys-badge-small-size);
+    block-size: var(--md-sys-badge-small-size);
+    inset: unset;
+    inset-block-start: calc(anchor(start) + var(--md-sys-badge-block-offset));
+    inset-inline-start: calc(anchor(end) - var(--md-sys-badge-small-size) - var(--md-sys-badge-inline-offset));
+    border-radius: calc(var(--md-sys-badge-small-size) / 2);
+    margin: 0;
+    padding: 0;
+    background-color: var(--md-sys-color-error);
+    color: var(--md-sys-color-on-error);
+}
+
+.micl-badge-large {
+    --md-sys-badge-inline-offset: 0px;
+    --md-sys-badge-block-offset: 0px;
+
+    @include typography.label-small;
+
+    box-sizing: border-box;
+    position: fixed;
+    inline-size: fit-content;
+    max-inline-size: 34px;
+    min-inline-size: var(--md-sys-badge-large-size);
+    block-size: var(--md-sys-badge-large-size);
+    inset: unset;
+    inset-block-start: calc(anchor(start) - 2px + var(--md-sys-badge-block-offset));
+    inset-inline-start: calc(anchor(end) - 12px - var(--md-sys-badge-inline-offset));
+    margin: 0;
+    padding-inline: var(--md-sys-badge-large-padding);
+    border-radius: calc(var(--md-sys-badge-large-size) / 2);
+    background-color: var(--md-sys-color-error);
+    color: var(--md-sys-color-on-error);
+}

package/components/button/index.scss

@@ -53,12 +53,15 @@ button.micl-button-outlined-xl {
     --md-sys-button-motion-effects: #{motion.$md-sys-motion-expressive-fast-spatial};
     --md-sys-button-motion-duration: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
     --md-sys-button-motion-duration-reverse: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
-    --miclripple: 1;
+    --micl-ripple: 1;
 
+    position: relative;
+    display: inline-flex;
+    align-items: center;
     padding: 0;
     border: none;
     background-image:
-        radial-gradient(circle at var(--x, center) var(--y, center), transparent 0%, rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)) 10%, transparent 10%),
+        radial-gradient(circle at var(--micl-x, center) var(--micl-y, center), transparent 0%, rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)) 10%, transparent 10%),
         linear-gradient(rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)));
     background-repeat: no-repeat;
     background-size: 10000%, 100%;
@@ -97,6 +100,7 @@ button.micl-button-tonal-xs,
 button.micl-button-outlined-xs {
     @include typography.label-large;
 
+    column-gap: 8px;
     min-width: var(--md-sys-target-size);
     height: var(--md-sys-target-size);
     padding-inline: 12px;
@@ -134,8 +138,6 @@ button.micl-button-outlined-xs {
     .micl-button__icon {
         font-size: 20px;
         width: 20px;
-        margin-right: 8px;
-        vertical-align: text-bottom;
     }
 }
 
@@ -146,6 +148,7 @@ button.micl-button-tonal-s,
 button.micl-button-outlined-s {
     @include typography.label-large;
 
+    column-gap: 8px;
     min-width: var(--md-sys-target-size);
     height: var(--md-sys-target-size);
     padding-inline: 16px;
@@ -183,8 +186,6 @@ button.micl-button-outlined-s {
     .micl-button__icon {
         font-size: 20px;
         width: 20px;
-        margin-right: 8px;
-        vertical-align: text-bottom;
     }
 }
 
@@ -195,6 +196,7 @@ button.micl-button-tonal-m,
 button.micl-button-outlined-m {
     @include typography.title-medium;
 
+    column-gap: 8px;
     min-width: 56px;
     height: 56px;
     padding-inline: 24px;
@@ -218,8 +220,6 @@ button.micl-button-outlined-m {
     .micl-button__icon {
         font-size: 24px;
         width: 24px;
-        margin-right: 8px;
-        vertical-align: text-bottom;
     }
 }
 
@@ -230,6 +230,7 @@ button.micl-button-tonal-l,
 button.micl-button-outlined-l {
     @include typography.headline-small;
 
+    column-gap: 12px;
     min-width: 96px;
     height: 96px;
     padding-inline: 48px;
@@ -253,8 +254,6 @@ button.micl-button-outlined-l {
     .micl-button__icon {
         font-size: 32px;
         width: 32px;
-        margin-right: 12px;
-        vertical-align: text-bottom;
     }
 }
 
@@ -265,6 +264,7 @@ button.micl-button-tonal-xl,
 button.micl-button-outlined-xl {
     @include typography.headline-large;
 
+    column-gap: 16px;
     min-width: 136px;
     height: 136px;
     padding-inline: 64px;
@@ -288,8 +288,6 @@ button.micl-button-outlined-xl {
     .micl-button__icon {
         font-size: 40px;
         width: 40px;
-        margin-right: 16px;
-        vertical-align: text-bottom;
     }
 }
 

package/components/button/index.ts

@@ -37,7 +37,12 @@ export default (() =>
             }
         }
         if (event.target.classList.contains('micl-button--toggle')) {
+            event.target.classList.add('micl-button--toggled');
             event.target.classList.toggle('micl-button--selected');
+            if (!!event.target.dataset.miclalt) {
+                [event.target.textContent, event.target.dataset.miclalt] = 
+                [event.target.dataset.miclalt, event.target.textContent];
+            }
         }
     };
 

package/components/card/index.scss

@@ -43,11 +43,11 @@
     interpolate-size: allow-keywords;
 
     &[tabindex='0']:not(.micl-card--disabled) {
-        --miclripple: 1;
+        --micl-ripple: 1;
         --statelayer-color: var(--md-sys-color-on-surface);
 
         background-image:
-            radial-gradient(circle at var(--x, center) var(--y, center), transparent 0%, rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)) 10%, transparent 10%),
+            radial-gradient(circle at var(--micl-x, center) var(--micl-y, center), transparent 0%, rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)) 10%, transparent 10%),
             linear-gradient(rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)));
         background-repeat: no-repeat;
         background-size: 10000%, 100%;

package/components/checkbox/index.scss

@@ -173,7 +173,7 @@ input[type=checkbox].micl-checkbox {
         }
     }
     &:not(:disabled) {
-        --miclripple: 1;
+        --micl-ripple: 1;
 
         cursor: pointer;
 

package/components/iconbutton/index.scss

@@ -47,14 +47,14 @@ button.micl-iconbutton-outlined-xl {
     --md-sys-iconbutton-motion-effects: #{motion.$md-sys-motion-expressive-fast-spatial};
     --md-sys-iconbutton-motion-duration: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
     --md-sys-iconbutton-motion-duration-reverse: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
-    --miclripple: 1;
+    --micl-ripple: 1;
 
     padding: 0;
     border: none;
     border-radius: var(--md-sys-shape-corner-full);
     background-color: transparent;
     background-image:
-        radial-gradient(circle at var(--x, center) var(--y, center), transparent 0%, rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)) 10%, transparent 10%),
+        radial-gradient(circle at var(--micl-x, center) var(--micl-y, center), transparent 0%, rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)) 10%, transparent 10%),
         linear-gradient(rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)));
     background-repeat: no-repeat;
     background-size: 10000%, 100%;

package/components/iconbutton/index.ts

@@ -37,7 +37,12 @@ export default (() =>
             }
         }
         if (event.target.classList.contains('micl-button--toggle')) {
+            event.target.classList.add('micl-button--toggled');
             event.target.classList.toggle('micl-button--selected');
+            if (!!event.target.dataset.miclalt) {
+                [event.target.textContent, event.target.dataset.miclalt] = 
+                [event.target.dataset.miclalt, event.target.textContent];
+            }
         }
     };
 

package/components/list/index.scss

@@ -107,7 +107,7 @@
     border-radius: var(--md-sys-shape-corner-none);
     background-color: var(--md-sys-list-item-container-color);
     background-image:
-        radial-gradient(circle at var(--x, center) var(--y, center), transparent 0%, rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)) 10%, transparent 10%),
+        radial-gradient(circle at var(--micl-x, center) var(--micl-y, center), transparent 0%, rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)) 10%, transparent 10%),
         linear-gradient(rgb(from var(--statelayer-color) r g b / var(--statelayer-opacity)));
     background-repeat: no-repeat;
     background-size: 10000%, 100%;
@@ -117,7 +117,7 @@
         --statelayer-opacity var(--md-sys-list-motion-duration) linear;
 
     &:not(:has(> button)) {
-        --miclripple: 1;
+        --micl-ripple: 1;
     }
     &> a,
     &> button,

package/components/navigationrail/README.md

@@ -1,98 +1,149 @@
-# Side sheet
-This component implements the the [Material Design 3 Expressive Side sheet](https://m3.material.io/components/side-sheets/overview) design.
+# Navigation rail
+This component implements the the [Material Design 3 Expressive Navigation rail](https://m3.material.io/components/navigation-rail/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.
+To create a simple navigation rail, use a `<div>` element with the `micl-navigationrail` class. Inside, use an `input type="radio"` group to create the selectable navigation items. The `input` elements must share the same `name` attribute to ensure that only one item can be selected at a time. The `label` elements are associated with their respective inputs using the `for` attribute.
 
 ```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 id="mynavigationrail" class="micl-navigationrail">
+  <div class="micl-navigationrail__content">
+    <input type="radio" id="item1" name="navitem" value="email_inbox" checked>
+    <label for="item1" class="micl-navigationrail__item" tabindex="0">
+      <span class="micl-navigationrail__icon material-symbols-outlined" aria-hidden="true">inbox</span>
+      <span class="micl-navigationrail__text">Inbox</span>
+    </label>
+    <input type="radio" id="item2" name="navitem" value="email_outbox">
+    <label for="item2" class="micl-navigationrail__item" tabindex="0">
+      <span class="micl-navigationrail__icon material-symbols-outlined" aria-hidden="true">outbox</span>
+      <span class="micl-navigationrail__text">Outbox</span>
+    </label>
   </div>
-</dialog>
+</div>
 ```
 
 ### CSS
-Import the side sheet styles into your project:
+Import the navigation rail styles into your project:
 
 ```CSS
-@use "material-inspired-component-library/dist/sidesheet";
+@use "material-inspired-component-library/dist/navigationrail";
 ```
 
 ### JavaScript
-No custom JavaScript is required for the core functionality of the side sheet component.
+This component requires JavaScript to support keyboard navigation. The library will automatically initialize new components as they're added to the DOM.
+
+```JavaScript
+import micl from "material-inspired-component-library/dist/micl";
+```
 
 ### Demo
-A live example of the [Side sheet component](https://henkpb.github.io/micl/sidesheet.html) is available for you to interact with.
+A live example of the [Navigation rail component](https://henkpb.github.io/micl/navigationrail.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.
+The basic example creates a **collapsed** navigation rail. Add a menu button to allow the user to toggle between a **collapsed** and an **expanded** view.
 
 ```HTML
-<dialog id="mysidesheet" class="micl-sidesheet" closedby="closerequest">
-  <div class="micl-sidesheet__headline">
+<div id="mynavigationrail" class="micl-navigationrail">
+  <div class="micl-navigationrail__headline">
     <button
       type="button"
-      class="micl-iconbutton-s material-symbols-outlined"
-      aria-label="Go back"
-    >arrow_back</button>
-    <h2>Title</h2>
+      class="micl-iconbutton-standard-s micl-button--toggle material-symbols-outlined"
+      data-miclalt="menu_open"
+      aria-label="Toggle navigation rail"
+    >menu</button>
+  </div>
+  <div class="micl-navigationrail__content">
+    ...
+  </div>
+</div>
+```
+
+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.
+
+### Popover expanded navigation rail
+
+Add the `popover` attribute to the navigation rail, and the `popovertarget` attribute to the menu button. The value of the `popovertarget` attribute must be the `id` of the navigation rail.
+
+```HTML
+<div id="mynavigationrail" class="micl-navigationrail" popover="manual">
+  <div class="micl-navigationrail__headline">
     <button
       type="button"
-      class="micl-iconbutton-s material-symbols-outlined"
-      popovertarget="mysidesheet"
-      aria-label="Close"
-    >close</button>
+      class="micl-iconbutton-standard-s micl-button--toggle material-symbols-outlined"
+      popovertarget="mynavigationrail"
+      data-miclalt="menu_open"
+      aria-label="Toggle navigation rail"
+    >menu</button>
   </div>
-  <div class="micl-sidesheet__content">
-    ...your content...
+  <div class="micl-navigationrail__content">
+    ...
   </div>
-  <div class="micl-sidesheet__actions">
-    <button type="button" class="micl-button">Save</button>
-  </div>
-</dialog>
+</div>
 ```
 
-To open either a standard or modal side sheet, link a button to the side sheet's ID using the `popovertarget` attribute:
+[!WARNING]
+The **popover** navigation rail component adds CSS rules to the `<body>` element to properly resize the main content area when the navigation rail is collapsed. Overriding these rules may cause the component to behave unexpectedly. The rules that are applied are:
+
+  ```CSS
+  margin-inline-start: var(--md-sys-navigationrail-collapsed-width);
+  ```
+
+### Modal navigation rail
+
+A **modal** navigation rail is hidden until the user clicks a menu button. When shown, the **expanded** navigation rail is displayed on top of other page content. Use a `<dialog>` element instead of a `<div>`.
+
 ```HTML
-<button type="button" popovertarget="mysidesheet">Open Side Sheet</button>
-```
+<dialog id="mynavigationrail" class="micl-navigationrail" closedby="closerequest">
+  <div class="micl-navigationrail__headline">
+    <button
+      type="button"
+      class="micl-iconbutton-standard-s micl-button--toggle material-symbols-outlined"
+      popovertarget="mynavigationrail"
+      data-miclalt="menu_open"
+      aria-label="Toggle navigation rail"
+    >menu</button>
+  </div>
+  <div class="micl-navigationrail__content">
+    ...
+  </div>
+</dialog>
 
-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;
-}
+<button
+  type="button"
+  class="micl-iconbutton-standard-s micl-button--toggle material-symbols-outlined"
+  popovertarget="mynavigationrail"
+  aria-label="Toggle navigation rail"
+>menu</button>
 ```
-To remove the horizontal divider of the actions-container:
-```CSS
-#mysidesheet {
-  --md-sys-sidesheet-actions-divider-width: 0;
-}
+
+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.
+
+| Variable name | Default Value | Description |
+| ------------- | ------------- | ----------- |
+| --md-sys-navigationrail-collapsed-width | 96px | The width of the collapsed navigation rail |
+| --md-sys-navigationrail-expanded-maxwidth | 360px | The largest allowed width of the expanded navigation rail |
+| --md-sys-navigationrail-expanded-minwidth | 220px | The smallest allowed width of the expanded navigation rail |
+
+**Example: Changing the width of the collapsed navigation rail**
+
+```HTML
+<div style="--md-sys-navigationrail-collapsed-width:80px">
+  <div id="mynavigationrail" class="micl-navigationrail">
+    ...
+  </div>
+</div>
 ```
 
-### 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:
+To add a vertical divider of the to the navigation rail, assign one to the following CSS variable:
 
 ```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...
+#mynavigationrail {
+  --md-sys-divider-thickness: 1;
+}
 ```
 
 ## Compatibility