material-inspired-component-library 3.0.2 → 4.0.0

package/components/list/README.md

@@ -1,5 +1,5 @@
 # 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.
+This component implements 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
 
@@ -27,6 +27,11 @@ Import the list styles into your project:
 @use "material-inspired-component-library/dist/list";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### JavaScript
 This component requires JavaScript to support keyboard navigation:
 
@@ -36,8 +41,8 @@ import micl from "material-inspired-component-library/dist/micl";
 
 This will initialize any List component, including those that will be added to the DOM later on.
 
-### Demo
-A live example of the [List component](https://henkpb.github.io/micl/list.html) is available for you to interact with.
+### Live Demo
+A live example of the [List component](https://henkpb.github.io/micl/list.html) is available to interact with.
 
 ## Variants
 The List component offers three CSS classes to control the height and content capacity of individual list items:

package/components/list/index.scss

@@ -19,6 +19,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+@use '../../foundations/layout';
 @use '../../styles/motion';
 @use '../../styles/shapes';
 @use '../../styles/statelayer';
@@ -63,6 +64,7 @@
         &> summary.micl-list-item-two,
         &> summary.micl-list-item-three {
             position: relative;
+            -webkit-tap-highlight-color: transparent;
 
             &::-webkit-details-marker {
                 display: none;

package/components/list/index.ts

@@ -23,9 +23,8 @@ export const listSelector = '.micl-list-item-one,.micl-list-item-two,.micl-list-
 
 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)');
+    const isDisabled = (item: HTMLElement | null): boolean => !!item && item.classList.contains('micl-list-item--disabled');
+    const isSelected = (item: HTMLElement | null): boolean => !!item && item.matches(':has(input[type=checkbox]:checked)');
 
     return {
         keydown: (event: Event) =>

package/components/menu/README.md

@@ -28,6 +28,11 @@ Import the styles for both the menu and list components into your project:
 @use "material-inspired-component-library/dist/menu";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### JavaScript
 This component requires JavaScript for functionality:
 
@@ -37,8 +42,8 @@ import micl from "material-inspired-component-library/dist/micl";
 
 This will initialize any Menu component, including those that will be added to the DOM later on.
 
-### Demo
-A live example of the [Menu component](https://henkpb.github.io/micl/menu.html) is available for you to interact with.
+### Live Demo
+A live example of the [Menu component](https://henkpb.github.io/micl/menu.html) is available 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.

package/components/menu/index.ts

@@ -25,8 +25,8 @@ export default (() =>
 {
     const getOrigin = (invoker: Element, popover: Element): string =>
     {
-        const invokerRect = invoker.getBoundingClientRect(),
-              popoverRect = popover.getBoundingClientRect();
+        const invokerRect = invoker.getBoundingClientRect();
+        const popoverRect = popover.getBoundingClientRect();
 
         return ((invokerRect.x > popoverRect.x) ? 'right ' : 'left ') +
                ((invokerRect.y > popoverRect.y) ? 'bottom' : 'top');

package/components/navigationrail/README.md

@@ -1,5 +1,5 @@
 # Navigation rail
-This component implements the the [Material Design 3 Expressive Navigation rail](https://m3.material.io/components/navigation-rail/overview) design.
+This component implements the [Material Design 3 Expressive Navigation rail](https://m3.material.io/components/navigation-rail/overview) design.
 
 ## Basic Usage
 
@@ -30,6 +30,11 @@ Import the navigation rail styles into your project:
 @use "material-inspired-component-library/dist/navigationrail";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### JavaScript
 This component requires JavaScript to support keyboard navigation. The library will automatically initialize new components as they're added to the DOM.
 
@@ -37,8 +42,8 @@ This component requires JavaScript to support keyboard navigation. The library w
 import micl from "material-inspired-component-library/dist/micl";
 ```
 
-### Demo
-A live example of the [Navigation rail component](https://henkpb.github.io/micl/navigationrail.html) is available for you to interact with.
+### Live Demo
+A live example of the [Navigation rail component](https://henkpb.github.io/micl/navigationrail.html) is available to interact with.
 
 ## Variants
 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.

package/components/navigationrail/index.scss

@@ -19,6 +19,7 @@
 // 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/motion';
 @use '../../styles/shapes';

package/components/radio/README.md

@@ -1,5 +1,5 @@
 # Radio button
-This component implements the the [Material Design 3 Expressive Radio button](https://m3.material.io/components/radio-button/overview) design. A radio button allows a user to select only one option from a group of mutually exclusive choices.
+This component implements the [Material Design 3 Expressive Radio button](https://m3.material.io/components/radio-button/overview) design. A radio button allows a user to select only one option from a group of mutually exclusive choices.
 
 ## Basic Usage
 
@@ -18,11 +18,16 @@ Import the radio button styles into your project:
 @use "material-inspired-component-library/dist/radio";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### JavaScript
 No custom JavaScript is required for the core functionality of this component.
 
-### Demo
-A live example of the [Radio button component](https://henkpb.github.io/micl/radio.html) is available for you to interact with.
+### Live Demo
+A live example of the [Radio button component](https://henkpb.github.io/micl/radio.html) is available to interact with.
 
 ## Variants
 A radio button can be disabled by adding the `disabled` attribute to the `<input>` element.

package/components/radio/index.scss

@@ -45,6 +45,7 @@ input[type=radio].micl-radio {
     border: calc((var(--md-sys-target-size) - var(--md-sys-radio-state-layer-size)) / 2) solid transparent;
     background-clip: content-box;
     background-color: transparent;
+    -webkit-tap-highlight-color: transparent;
     border-radius: var(--md-sys-shape-corner-full);
     outline-offset: -7px;
 
@@ -85,9 +86,10 @@ input[type=radio].micl-radio {
             background-size 3000ms,
             --statelayer-opacity var(--md-sys-radio-motion-duration) linear;
 
-        &:hover {
+        &:hover,
+        &:focus-visible,
+        &:active {
             --statelayer-color: var(--md-sys-color-on-surface);
-            --statelayer-opacity: var(--md-sys-state-hover-state-layer-opacity);
 
             &:checked {
                 --statelayer-color: var(--md-sys-color-primary);
@@ -99,38 +101,19 @@ input[type=radio].micl-radio {
                 border-color: var(--md-sys-color-primary);
             }
         }
+        &:hover {
+            --statelayer-opacity: var(--md-sys-state-hover-state-layer-opacity);
+        }
         &:focus-visible {
-            --statelayer-color: var(--md-sys-color-on-surface);
             --statelayer-opacity: var(--md-sys-state-focus-state-layer-opacity);
 
             outline: var(--md-sys-state-focus-indicator-thickness) solid var(--md-sys-color-secondary);
-
-            &:checked {
-                --statelayer-color: var(--md-sys-color-primary);
-            }
-            &::after {
-                border-color: var(--md-sys-color-on-surface);
-            }
-            &:checked::after {
-                border-color: var(--md-sys-color-primary);
-            }
         }
         &:active {
-            --statelayer-color: var(--md-sys-color-on-surface);
             --statelayer-opacity: var(--md-sys-state-pressed-state-layer-opacity);
 
             background-size: 0%, 100%;
             transition: background-size 0ms;
-
-            &:checked {
-                --statelayer-color: var(--md-sys-color-primary);
-            }
-            &::after {
-                border-color: var(--md-sys-color-on-surface);
-            }
-            &:checked::after {
-                border-color: var(--md-sys-color-primary);
-            }
         }
     }
     &:disabled {
@@ -147,6 +130,7 @@ input[type=radio].micl-radio {
 
 input[type=radio].micl-radio:not(:disabled) + label,
 label:has(+ input[type=radio].micl-radio:not(:disabled)) {
+    -webkit-tap-highlight-color: transparent;
     cursor: pointer;
 }
 input[type=radio].micl-radio + label,

package/components/select/README.md

@@ -1,5 +1,5 @@
 # Select
-This component implements the the [Material Design 3 Expressive Select](https://m3.material.io/components/menus/guidelines#ee2f3664-c926-47ab-acbf-2ab675506932) design. A select component is used to offer the user with a set of options from which the user can select a single one. 
+This component implements the [Material Design 3 Expressive Select](https://m3.material.io/components/menus/guidelines#ee2f3664-c926-47ab-acbf-2ab675506932) design. A select component is used to offer the user with a set of options from which the user can select a single one.
 
 ## Basic Usage
 
@@ -38,8 +38,8 @@ import micl from "material-inspired-component-library/dist/micl";
 
 This will initialize any Select component, including those that will be added to the DOM later on.
 
-### Demo
-A live example of the [Select component](https://henkpb.github.io/micl/select.html) is available for you to interact with.
+### Live Demo
+A live example of the [Select component](https://henkpb.github.io/micl/select.html) is available to interact with.
 
 ## Variants
 A Select Component can be disabled by adding the `disabled` attribute to the `<select>` element. An option within the component can be disabled by adding the `disabled` attribute to the `<option>` element.

package/components/sidesheet/README.md

@@ -1,5 +1,5 @@
 # Side sheet
-This component implements the the [Material Design 3 Expressive Side sheet](https://m3.material.io/components/side-sheets/overview) design. Side sheets provide optional content and actions without interrupting the main content.
+This component implements the [Material Design 3 Expressive Side sheet](https://m3.material.io/components/side-sheets/overview) design. Side sheets provide optional content and actions without interrupting the main content.
 
 ## Basic Usage
 
@@ -29,11 +29,16 @@ Import the side sheet styles into your project:
 @use "material-inspired-component-library/dist/sidesheet";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### 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.
+### Live Demo
+A live example of the [Side sheet component](https://henkpb.github.io/micl/sidesheet.html) is available 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.

package/components/slider/README.md

@@ -1,5 +1,5 @@
 # Slider
-This component implements the the [Material Design 3 Expressive Slider](https://m3.material.io/components/sliders/overview) design.
+This component implements the [Material Design 3 Expressive Slider](https://m3.material.io/components/sliders/overview) design.
 
 ## Basic Usage
 
@@ -17,6 +17,11 @@ Import the slider styles into your project:
 @use "material-inspired-component-library/dist/slider";
 ```
 
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
 ### JavaScript
 This component requires JavaScript for functionality:
 
@@ -26,8 +31,8 @@ import micl from "material-inspired-component-library/dist/micl";
 
 This will initialize any Slider component, including those that will be added to the DOM later on.
 
-### Demo
-A live example of the [Slider component](https://henkpb.github.io/micl/slider.html) is available for you to interact with.
+### Live Demo
+A live example of the [Slider component](https://henkpb.github.io/micl/slider.html) is available to interact with.
 
 ## Variants
 Sliders come in **five different sizes**: extra small (`xs`), small (`s`), medium (`m`), large (`l`), and extra large (`xl`). To set a specific size, append the appropriate postfix to the `micl-slider` CSS class name:

package/components/slider/index.scss

@@ -19,6 +19,7 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
+@use '../../foundations/layout';
 @use '../../styles/motion';
 @use '../../styles/shapes';
 @use '../../styles/statelayer';

package/components/slider/index.ts

@@ -97,18 +97,17 @@ export default (() =>
             setValue(element);
             setVars(element);
 
-            const
-                max  = parseFloat(element.max),
-                min  = parseFloat(element.min),
-                rect = element.getBoundingClientRect(),
-                percentages = getTickValues(element, max, min).sort((a, b) => a - b).map(value => {
-                    return Math.round(100 * (value - min) / (max - min));
-                });
+            const max  = parseFloat(element.max);
+            const min  = parseFloat(element.min);
+            const rect = element.getBoundingClientRect();
+            const percentages = getTickValues(element, max, min).sort((a, b) => a - b).map(value => {
+                return Math.round(100 * (value - min) / (max - min));
+            });
 
             if (percentages.length > 0) {
-                const
-                    canvas = document.createElement('canvas'),
-                    ctx    = canvas.getContext('2d');
+                const canvas = document.createElement('canvas');
+                const ctx    = canvas.getContext('2d');
+
                 if (ctx) {
                     ctx.font = window.getComputedStyle(element).getPropertyValue('font');
                     let blankWidth   = ctx.measureText(blank).width,

package/components/stepper/README.md

@@ -0,0 +1,190 @@
+# Stepper
+This component creates a **Stepper** to manage a linear, step-by-step process for gathering or displaying information, inspired by the design principles of [Material Design 3 Expressive](https://m3.material.io/components).
+
+## Basic Usage
+
+### HTML
+To create a basic stepper, use a `<div>` container with the `micl-stepper` class and the `role="tablist"` attribute. The individual steps are placed within `<div class="micl-stepper__steps">`. Each step content is a `<div>` with the `micl-stepper__step` class and the `role="tabpanel"` attribute. The currently active step must be marked with `aria-current="step"`.
+
+```HTML
+<div class="micl-stepper" role="tablist" aria-label="My Step-by-Step Process">
+  <div class="micl-stepper__steps">
+    <div class="micl-stepper__step" role="tabpanel" aria-current="step">
+      Step 1 Content
+    </div>
+    <div class="micl-stepper__step" role="tabpanel">
+      Step 2 Content
+    </div>
+  </div>
+
+  <div class="micl-stepper__actions">
+    <div>
+      <button type="button" class="micl-button-text-m micl-stepper__action-back">Back</button>
+    </div>
+    <div>
+      <button type="button" class="micl-button-tonal-m micl-stepper__action-next">Next</button>
+    </div>
+  </div>
+</div>
+```
+
+### CSS
+Import the stepper styles into your project:
+
+```CSS
+@use "material-inspired-component-library/dist/stepper";
+```
+
+Or import all MICL styles:
+```CSS
+@use "material-inspired-component-library/styles";
+```
+
+### JavaScript
+This component requires JavaScript to enable navigation, state management, and form validation. The library will automatically initialize new components as they're added to the DOM.
+
+```JavaScript
+import micl from "material-inspired-component-library/dist/micl";
+```
+
+### Live Demo
+A live example of the [Stepper component](https://henkpb.github.io/micl/stepper.html) is available to interact with.
+
+## Action and State Management
+The Stepper component automatically manages navigation between steps and controls the visibility of the **Back** and **Next** buttons based on the current step.
+
+- **Next Action**: Clicking a button with the `micl-stepper__action-next` class advances the stepper by one step. This button is automatically hidden when the last step is active.
+
+- **Back Action**: Clicking a button with the `micl-stepper__action-back` class moves the stepper back one step. This button is automatically hidden when the first step is active.
+
+### Stepper Header
+The optional Stepper Header displays the step titles horizontally, allowing users to navigate directly to steps. The `aria-controls` and `aria-labelledby` attributes are essential for accessibility, linking the header buttons to their corresponding step panels.
+
+```HTML
+<div class="micl-stepper">
+  <div class="micl-stepper__header">
+    <button type="button" role="tab" id="step1Label class="micl-button-text-xs" aria-controls="step1" aria-selected="true">
+      <span class="micl-stepper__progress-dot" aria-hidden="true"></span>
+      Step 1
+    </button>
+    <button type="button" role="tab" id="step2Label class="micl-button-text-xs" aria-controls="step2">
+      <span class="micl-stepper__progress-dot" aria-hidden="true"></span>
+      Step 2
+    </button>
+  </div>
+  <div class="micl-stepper__steps">
+    <div id="step1" role="tabpanel" class="micl-stepper__step" aria-labelledby="step1Label" aria-current="step">
+      Step 1 Content
+    </div>
+    <div id="step2" role="tabpanel" class="micl-stepper__step" aria-labelledby="step2Label">
+      Step 2 Content
+    </div>
+  </div>
+</div>
+```
+
+### Linear vs. Non-linear Steppers
+- **Linear (Default)**: The user can only click the header buttons of previous steps to revisit them. Navigation to future steps is disabled until they are reached.
+
+- **Non-linear**: Apply the `micl-stepper--nonlinear` modifier class to the main stepper container. This allows the user to click any of the header buttons to freely jump between steps.
+
+## Variants
+
+### Progress indicator
+You can include optional elements to display the user's progress.
+
+#### Counter
+Use the `micl-stepper__progress-current` and `micl-stepper__progress-total` classes to automatically display the current step number and the total number of steps (e.g., "1 of 3").
+
+```HTML
+<div class="micl-stepper__actions">
+  <div>
+    <button type="button" class="micl-button-text-m micl-stepper__action-back">Back</button>
+  </div>
+  <div>
+    <span class="micl-stepper__progress-current"></span>
+    <span> of </span>
+    <span class="micl-stepper__progress-total"></span>
+  </div>
+  <div>
+    <button type="button" class="micl-button-tonal-m micl-stepper__action-next">Next</button>
+  </div>
+</div>
+```
+
+#### Dots
+Use the `micl-stepper__progress-dots` class to generate a visual progress bar using colored dots. The dots dynamically change color to indicate the current step.
+
+```HTML
+<div class="micl-stepper__actions">
+  <div>
+    <button type="button" class="micl-button-text-m micl-stepper__action-back">Back</button>
+  </div>
+  <div class="micl-stepper__progress-dots"></div>
+  <div>
+    <button type="button" class="micl-button-tonal-m micl-stepper__action-next">Next</button>
+  </div>
+</div>
+```
+
+### Step validation
+To enable built-in **form validation** for each step, use a `<form>` element as the main stepper container and replace the step `<div>`s with `<fieldset>` elements.
+
+#### Validation Flow
+- **Step-by-Step Validation**: When a user clicks **Next**, the browser's built-in validation is triggered only for the input fields within the current step. If any constraints are violated, the stepper will not advance.
+
+- **Error Display**: The Stepper component applies the error state to any child MICL component that supports it, displaying the custom error text. Otherwise, the default browser validation message appears.
+
+- **Final Submission Validation**: If the final step contains a `type="submit"` button, the component validates the entire form upon submission. The form will only be submitted if all data input fields across all steps are valid.
+
+```HTML
+<form class="micl-stepper" action="/submit-data" method="post" role="tablist" aria-label="My Form">
+  <div class="micl-stepper__steps">
+    <fieldset class="micl-stepper__step" role="tabpanel" aria-current="step">
+      <div class="micl-textfield-filled">
+        <label for="mytextfield">Label text</label>
+        <input type="text" id="mytextfield" name="mytext" required>
+      </div>
+    </fieldset>
+    <fieldset class="micl-stepper__step" role="tabpanel">
+      Step 2 Content
+    </fieldset>
+  </div>
+  <div class="micl-stepper__actions">
+    ...
+  </div>
+</form>
+```
+
+#### Step-Specific Action Buttons
+Action buttons can be made visible only on a specific step by using the `data-step` attribute, which specifies the step number (starting from 1). This is useful for replacing the default **Next** button with a content-specific action, like a **Submit** button on the final step.
+
+In this example for a three-step stepper, the **Next** button is hidden on step 3, and the **Submit** button is shown instead:
+
+```HTML
+<div class="micl-stepper__actions">
+  <div>
+    <button type="button" class="micl-button-text-m micl-stepper__action-back">Back</button>
+  </div>
+  <div>
+    <button type="submit" class="micl-button-tonal-m" data-step="3">Submit</button>
+    <button type="button" class="micl-button-tonal-m micl-stepper__action-next">Next</button>
+  </div>
+</div>
+```
+
+## Customizations
+You can customize the appearance of the Stepper 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 steppers.
+
+| Variable name | Default Value | Description |
+| ------------- | ----- | ----------- |
+| --md-sys-stepper-counter-style | decimal | The list-style used for the counter number inside the dots in the stepper header |
+| --md-sys-stepper-dot-size | 12px | Controls the size of each progress dot |
+
+**Example: Changing the style of the counter inside header dots**
+
+```HTML
+<div class="micl-stepper" style="--md-sys-stepper-counter-style:upper-alpha">
+  ...
+</div>
+```