material-inspired-component-library 3.1.0 → 4.0.0

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;
 
@@ -129,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/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>
+```

package/components/stepper/index.scss

@@ -19,11 +19,15 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-@use '../../layout';
+@use '../../foundations/layout';
 @use '../../styles/motion';
 
 :root {
-    --md-sys-stepper-thickness: 1px;
+    --md-sys-stepper-counter-style: decimal;
+    --md-sys-stepper-dot-size: 12px;
+}
+body {
+    --md-sys-stepper-dot-done-color: var(--md-sys-color-tertiary-container, blue);
 }
 
 .micl-stepper {
@@ -35,8 +39,38 @@
     display: flex;
     flex-direction: column;
     row-gap: var(--md-sys-layout-padding-xl, 24px);
+    margin: 0;
     background-color: inherit;
 
+    .micl-stepper__header {
+        --md-sys-stepper-dot-size: 24px;
+
+        display: flex;
+        justify-content: space-between;
+        align-items: flex-start;
+        margin-inline: -10px;
+        background-color: inherit;
+        background-image: linear-gradient(90deg, var(--md-sys-divider-color), var(--md-sys-divider-color));
+        background-position: center;
+        background-repeat: no-repeat;
+        background-size: 100% 1px;
+        counter-reset: dotnumber;
+
+        button {
+            background-color: inherit;
+            pointer-events: none;
+
+            &.micl-stepper__progress--done {
+                pointer-events: inherit;
+            }
+        }
+        .micl-stepper__progress-dot::before {
+            content: counter(dotnumber, var(--md-sys-stepper-counter-style));
+        }
+    }
+    &.micl-stepper--nonlinear .micl-stepper__header button {
+        pointer-events: inherit;
+    }
     .micl-stepper__steps {
         display: grid;
         grid-template-areas: "stepper-steps";
@@ -48,7 +82,9 @@
             display: flex;
             visibility: hidden;
             flex-direction: column;
-            justify-content: space-between;
+            margin: 0;
+            padding: 0;
+            border: none;
             opacity: 0%;
             background-color: inherit;
             transform: translateX(100%);
@@ -56,30 +92,73 @@
                 opacity var(--md-sys-stepper-motion-duration) linear,
                 transform var(--md-sys-stepper-motion-duration) var(--md-sys-stepper-motion-spatial);
 
-            &:has(~ .micl-stepper__step--current) {
+            &:has(~ .micl-stepper__step[aria-current=step]) {
                 transform: translateX(-100%);
             }
-            &.micl-stepper__step--tocurrent {
+            &.micl-stepper__step--toselected {
                 visibility: visible;
             }
-            &.micl-stepper__step--current {
+            &[aria-current=step] {
                 visibility: visible;
                 opacity: 100%;
                 transform: translateX(0%);
             }
-            &.micl-stepper__step--fromcurrent {
+            &.micl-stepper__step--fromselected {
                 visibility: visible;
             }
-
-            .micl-stepper__content {
-                box-sizing: border-box;
-                padding-inline: var(--md-sys-stepper-padding-inline);
-                background-color: inherit;
-            }
         }
     }
     .micl-stepper__actions {
         display: flex;
-        justify-content: space-between;
+        flex-direction: row;
+        justify-content: center;
+        inline-size: 100%;
+        align-items: center;
+
+        &>:first-child,
+        &>:last-child {
+            display: flex;
+            flex: 1 1 0;
+            column-gap: var(--md-sys-layout-padding-xs, 8px)
+        }
+        &>:last-child {
+            justify-content: flex-end;
+        }
+    }
+    .micl-stepper__progress-dots {
+        display: flex;
+        align-items: center;
+        column-gap: 4px;
+    }
+    .micl-stepper__progress-dot {
+        block-size: var(--md-sys-stepper-dot-size);
+        inline-size: var(--md-sys-stepper-dot-size);
+        min-inline-size: var(--md-sys-stepper-dot-size);
+        line-height: var(--md-sys-stepper-dot-size);
+        border-radius: calc(var(--md-sys-stepper-dot-size) / 2);
+        text-align: center;
+        background-color: var(--md-sys-color-on-surface);
+        color: var(--md-sys-color-surface);
+        opacity: 38%;
+        counter-increment: dotnumber 1;
+    }
+    .micl-stepper__progress--done.micl-stepper__progress-dot,
+    .micl-stepper__progress--done .micl-stepper__progress-dot {
+        background-color: var(--md-sys-stepper-dot-done-color);
+        color: var(--md-sys-color-on-tertiary-container);
+        opacity: 100%;
+    }
+}
+
+[dir=rtl] {
+    .micl-stepper .micl-stepper__steps .micl-stepper__step {
+        transform: translateX(-100%);
+
+        &:has(~ .micl-stepper__step[aria-current=step]) {
+            transform: translateX(100%);
+        }
+        &[aria-current=step] {
+            transform: translateX(0%);
+        }
     }
 }