material-inspired-component-library 8.1.0 → 9.0.0

package/components/button/README.md

@@ -23,7 +23,7 @@ Or import all MICL styles:
 ```
 
 ### JavaScript
-This component requires JavaScript for interactive features like the **toggle logic**:
+This component requires JavaScript to support the **toggle logic**:
 
 ```JavaScript
 import micl from "material-inspired-component-library/dist/micl";
@@ -40,7 +40,7 @@ Buttons come in **five sizes**: extra small (`xs`), small (`s`), medium (`m`), l
 **Example: An extra-large text button**
 
 ```HTML
-<button type="button" class="micl-button-text-xl>Save</button>
+<button type="button" class="micl-button-text-xl">Save</button>
 ```
 
 Material Design provides **five distinct styles**: `text`, `elevated`, `filled`, `tonal` and `outlined`. To use a style other than the `text` style used above, apply the corresponding class to the button:
@@ -56,9 +56,9 @@ By default, buttons have a **rounded shape**. For a more square-like appearance,
 Adding the `disabled` boolean attribute to the button causes the button to be displayed in a disabled state.
 
 ### Toggle Button
-A toggle button has two states: **on** (selected) and **off** (unselected). To create one, add the `micl-button--toggle` class.
-- **Off state**: The button has the `micl-button--toggle` class.
-- **On state**: The button has both the `micl-button--toggle` and `micl-button--selected` classes.
+A toggle button has two states: **on** (pressed) and **off** (unpressed). To create one, add the `micl-button--toggle` class and an `aria-pressed` attribute.
+- **Off state**: The button has the `micl-button--toggle` class and `aria-pressed="false"`.
+- **On state**: The button has the `micl-button--toggle` class and `aria-pressed="true"`.
 
 **Example: A selected toggle button**
 
@@ -66,13 +66,14 @@ A toggle button has two states: **on** (selected) and **off** (unselected). To c
 <button
   type="button"
   id="id0"
-  class="micl-button-tonal-s micl-button--toggle micl-button--selected"
+  class="micl-button-tonal-s micl-button--toggle"
+  aria-pressed="true"
   commandfor="id0"
   command="--micl-toggle"
 >Selected</button>
 ```
 
-The self-targeting `command` property (`--micl-toggle`) toggles the button state whenever the user interacts with the button.
+The self-targeting `command` property (`--micl-toggle`) flips `aria-pressed` whenever the user interacts with the button.
 
 ## Icons
 To add a leading icon to a button, include an element with the `micl-button__icon` class inside the `<button>`:
@@ -84,14 +85,14 @@ To add a leading icon to a button, include an element with the `micl-button__ico
 </button>
 ```
 
-To use different icons for the **on** state and the **off** state in a toggle button, remove the icon name from the `micl-button__icon` element and add the `data-miclicon` (the name of the **on** icon) and `data-micliconselected` (the name of the **off** icon) attributes:
+To use different icons for the **on** state and the **off** state in a toggle button, remove the icon name from the `micl-button__icon` element and add the `data-miclicon` (the name of the **off** icon) and `data-micliconselected` (the name of the **on** icon) attributes:
 
 ```HTML
   ...
   <span
     class="micl-button__icon material-symbols-outlined"
-    data-miclicon="icon_for_on"
-    data-micliconselected="icon_for_off"
+    data-miclicon="icon_for_off"
+    data-micliconselected="icon_for_on"
     aria-hidden="true"
   ><span>
   ...
@@ -114,5 +115,64 @@ You can also use other icon libraries. For example, with the [Bootstrap Icons li
 </button>
 ```
 
+## Theming
+Each button style can be themed with CSS custom properties that follow the Material Design 3 component-token naming convention. Note that the `selected-*` and `unselected-*` properties only apply to [toggle buttons](#toggle-button).
+
+### Text
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-text-button-label-text-color` | Label & icon colour | `--md-sys-color-primary` |
+| `--md-comp-text-button-disabled-label-text-color` | Label & icon colour when disabled | `--md-sys-color-on-surface-variant` |
+| `--md-comp-text-button-disabled-label-text-opacity` | Label & icon opacity when disabled | `38%` |
+
+### Elevated
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-elevated-button-container-color` | Container background | `--md-sys-color-surface-container-low` |
+| `--md-comp-elevated-button-container-elevation` | Container elevation (shadow) | `--md-sys-elevation-level1` |
+| `--md-comp-elevated-button-label-text-color` | Label & icon colour | `--md-sys-color-primary` |
+| `--md-comp-elevated-button-selected-container-color` | Container background when selected | `--md-sys-color-primary` |
+| `--md-comp-elevated-button-selected-label-text-color` | Label & icon colour when selected | `--md-sys-color-on-primary` |
+| `--md-comp-elevated-button-disabled-container-color` | Container background when disabled | `--md-sys-color-on-surface` |
+| `--md-comp-elevated-button-disabled-container-opacity` | Container opacity when disabled | `10%` |
+| `--md-comp-elevated-button-disabled-label-text-color` | Label & icon colour when disabled | `--md-sys-color-on-surface-variant` |
+| `--md-comp-elevated-button-disabled-label-text-opacity` | Label & icon opacity when disabled | `38%` |
+
+### Filled
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-filled-button-container-color` | Container background (also the selected state) | `--md-sys-color-primary` |
+| `--md-comp-filled-button-label-text-color` | Label & icon colour (also the selected state) | `--md-sys-color-on-primary` |
+| `--md-comp-filled-button-unselected-container-color` | Container background when an unselected toggle | `--md-sys-color-surface-container` |
+| `--md-comp-filled-button-unselected-label-text-color` | Label & icon colour when an unselected toggle | `--md-sys-color-on-surface-variant` |
+| `--md-comp-filled-button-disabled-container-color` | Container background when disabled | `--md-sys-color-on-surface` |
+| `--md-comp-filled-button-disabled-container-opacity` | Container opacity when disabled | `10%` |
+| `--md-comp-filled-button-disabled-label-text-color` | Label & icon colour when disabled | `--md-sys-color-on-surface-variant` |
+| `--md-comp-filled-button-disabled-label-text-opacity` | Label & icon opacity when disabled | `38%` |
+
+### Tonal
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-filled-tonal-button-container-color` | Container background | `--md-sys-color-secondary-container` |
+| `--md-comp-filled-tonal-button-label-text-color` | Label & icon colour | `--md-sys-color-on-secondary-container` |
+| `--md-comp-filled-tonal-button-selected-container-color` | Container background when selected | `--md-sys-color-secondary` |
+| `--md-comp-filled-tonal-button-selected-label-text-color` | Label & icon colour when selected | `--md-sys-color-on-secondary` |
+| `--md-comp-filled-tonal-button-disabled-container-color` | Container background when disabled | `--md-sys-color-on-surface` |
+| `--md-comp-filled-tonal-button-disabled-container-opacity` | Container opacity when disabled | `10%` |
+| `--md-comp-filled-tonal-button-disabled-label-text-color` | Label & icon colour when disabled | `--md-sys-color-on-surface-variant` |
+| `--md-comp-filled-tonal-button-disabled-label-text-opacity` | Label & icon opacity when disabled | `38%` |
+
+### Outlined
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-outlined-button-outline-color` | Outline (border) colour | `--md-sys-color-outline-variant` |
+| `--md-comp-outlined-button-label-text-color` | Label & icon colour | `--md-sys-color-on-surface-variant` |
+| `--md-comp-outlined-button-selected-container-color` | Container background when selected | `--md-sys-color-inverse-surface` |
+| `--md-comp-outlined-button-selected-label-text-color` | Label & icon colour when selected | `--md-sys-color-inverse-on-surface` |
+| `--md-comp-outlined-button-selected-disabled-container-color` | Container background when selected and disabled | `--md-sys-color-on-surface` |
+| `--md-comp-outlined-button-selected-disabled-container-opacity` | Container opacity when selected and disabled | `10%` |
+| `--md-comp-outlined-button-disabled-label-text-color` | Label & icon colour when disabled | `--md-sys-color-on-surface-variant` |
+| `--md-comp-outlined-button-disabled-label-text-opacity` | Label & icon opacity when disabled | `38%` |
+
 ## Compatibility
 This component utilizes relative RGB color values, which may not be fully supported in your browser. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#browser_compatibility) for details.

package/components/button/_shared.scss

@@ -0,0 +1,210 @@
+//
+// 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.
+
+// The shared foundation of the Button component: the state selectors and the
+// %micl-button-* placeholders, which the Chip component extends as well.
+
+@use '../../styles/elevation';
+@use '../../styles/motion';
+@use '../../styles/statelayer';
+@use '../../styles/typography';
+
+$disabled: ':is(:disabled, :has(input:disabled, > button:disabled))';
+$enabled: ':not(:disabled, :has(input:disabled, > button:disabled))';
+$focused: ':is(:focus-visible, :has(input:focus-visible))';
+
+@include elevation.level(0);
+@include elevation.level(1);
+@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('disabled-state-layer-opacity');
+@include statelayer.token('focus-indicator-thickness');
+@include statelayer.token('ripple-opacity-factor');
+@include statelayer.token('ripple-duration');
+@include statelayer.property;
+@include statelayer.keyframes;
+
+@include typography.scale('label-large');
+
+%micl-button-base {
+    --md-comp-button-motion-effects: #{motion.$md-sys-motion-expressive-fast-spatial};
+    --md-comp-button-motion-duration: #{motion.$md-sys-motion-expressive-fast-spatial-duration};
+    --micl-ripple: 1;
+
+    box-sizing: border-box;
+    position: relative;
+    display: inline-flex;
+    flex-shrink: 0;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    border: none;
+    border-radius: calc(var(--micl-height) / 2);
+    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%;
+    -webkit-tap-highlight-color: transparent;
+    cursor: pointer;
+    transition:
+        border-radius var(--md-comp-button-motion-duration) var(--md-comp-button-motion-effects),
+        box-shadow var(--md-comp-button-motion-duration) var(--md-comp-button-motion-effects),
+        background-size 0ms,
+        --statelayer-opacity var(--md-comp-button-motion-duration) linear;
+
+    &#{$disabled} {
+        cursor: default;
+    }
+    &#{$enabled} {
+        &:hover {
+            --statelayer-opacity: var(--md-sys-state-hover-state-layer-opacity, 8%);
+
+            .micl-button__icon {
+                font-variation-settings: 'FILL' 1;
+            }
+        }
+        &#{$focused} {
+            --statelayer-opacity: var(--md-sys-state-focus-state-layer-opacity, 10%);
+
+            outline: var(--md-sys-state-focus-indicator-thickness, 3px) solid var(--md-sys-color-secondary);
+            outline-offset: 2px;
+        }
+        &: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-button__icon {
+        font-variation-settings: 'FILL' 0;
+        transition: font-variation-settings var(--md-comp-button-motion-duration) linear;
+    }
+    &.micl-button--toggle:not([aria-pressed="true"]) .micl-button__icon::before {
+        content: attr(data-miclicon);
+    }
+    &.micl-button--toggle[aria-pressed="true"] .micl-button__icon::before {
+        content: attr(data-micliconselected);
+    }
+}
+
+// Buttons smaller than the minimum touch target extend their interactive area with a
+// transparent ::before overlay.
+%micl-button-target {
+    &::before {
+        content: "";
+        position: absolute;
+        block-size: var(--md-sys-target-size, 48px);
+        inline-size: 100%;
+        min-inline-size: var(--md-sys-target-size, 48px);
+        inset: calc((var(--micl-height) - var(--md-sys-target-size, 48px)) / 2) 0 0 calc((min(100%, var(--md-sys-target-size, 48px)) - var(--md-sys-target-size, 48px)) / 2);
+        background-color: transparent;
+    }
+}
+
+%micl-button-xs {
+    @include typography.label-large;
+    @extend %micl-button-target;
+
+    --micl-width: 32px;
+    --micl-height: 32px;
+
+    min-inline-size: var(--micl-width);
+    block-size: var(--micl-height);
+    min-block-size: var(--micl-height);
+    column-gap: 4px;
+    padding-inline: 12px;
+
+    .micl-button__icon {
+        font-size: 20px;
+        inline-size: 20px;
+    }
+}
+
+%micl-button-elevated {
+    --statelayer-color: var(--md-sys-color-primary);
+
+    background-color: var(--md-comp-elevated-button-container-color, var(--md-sys-color-surface-container-low));
+    color: var(--md-comp-elevated-button-label-text-color, var(--md-sys-color-primary));
+    box-shadow: var(--md-comp-elevated-button-container-elevation, var(--md-sys-elevation-level1));
+
+    &#{$disabled} {
+        background-color: var(--md-comp-elevated-button-disabled-container-color, rgb(from var(--md-sys-color-on-surface) r g b / var(--md-comp-elevated-button-disabled-container-opacity, 10%)));
+        color: var(--md-comp-elevated-button-disabled-label-text-color, rgb(from var(--md-sys-color-on-surface-variant) r g b / var(--md-comp-elevated-button-disabled-label-text-opacity, 38%)));
+        box-shadow: var(--md-sys-elevation-level0);
+    }
+    &#{$enabled} {
+        &:hover:not(:active) {
+            box-shadow: var(--md-sys-elevation-level2);
+        }
+        &.micl-button--toggle[aria-pressed="true"] {
+            --statelayer-color: var(--md-sys-color-on-primary);
+
+            background-color: var(--md-comp-elevated-button-selected-container-color, var(--md-sys-color-primary));
+            color: var(--md-comp-elevated-button-selected-label-text-color, var(--md-sys-color-on-primary));
+
+            .micl-button__icon {
+                font-variation-settings: 'FILL' 1;
+            }
+        }
+    }
+}
+
+%micl-button-outlined {
+    --statelayer-color: var(--md-sys-color-on-surface-variant);
+
+    background-color: transparent;
+    color: var(--md-comp-outlined-button-label-text-color, var(--md-sys-color-on-surface-variant));
+    border: 1px solid var(--md-comp-outlined-button-outline-color, var(--md-sys-color-outline-variant));
+
+    &#{$disabled} {
+        background-color: transparent;
+        color: var(--md-comp-outlined-button-disabled-label-text-color, rgb(from var(--md-sys-color-on-surface-variant) r g b / var(--md-comp-outlined-button-disabled-label-text-opacity, 38%)));
+
+        &.micl-button--toggle[aria-pressed="true"] {
+            border: none;
+            background-color: var(--md-comp-outlined-button-selected-disabled-container-color, rgb(from var(--md-sys-color-on-surface) r g b / var(--md-comp-outlined-button-selected-disabled-container-opacity, 10%)));
+        }
+    }
+    &#{$enabled} {
+        &.micl-button--toggle[aria-pressed="true"] {
+            --statelayer-color: var(--md-sys-color-inverse-on-surface);
+
+            border: none;
+            background-color: var(--md-comp-outlined-button-selected-container-color, var(--md-sys-color-inverse-surface));
+            color: var(--md-comp-outlined-button-selected-label-text-color, var(--md-sys-color-inverse-on-surface));
+
+            .micl-button__icon {
+                font-variation-settings: 'FILL' 1;
+            }
+        }
+    }
+}