material-inspired-component-library 8.1.0 → 9.0.0

package/components/checkbox/index.scss

@@ -19,11 +19,11 @@
 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 // SOFTWARE.
 
-@use '../../foundations';
 @use '../../styles/motion';
 @use '../../styles/shape';
 @use '../../styles/statelayer';
 @use '../../styles/typography';
+@use './label';
 
 @include shape.corner('full');
 
@@ -41,17 +41,16 @@
 @include motion.duration('short3');
 @include motion.duration('long4');
 
-:root {
-    --md-sys-checkbox-border-width: 2px;
-    --md-sys-checkbox-check-thickness: 2px;
-    --md-sys-checkbox-container-size: 18px;
-}
+$checkbox: 'input[type=checkbox].micl-checkbox';
 
-input[type=checkbox].micl-checkbox {
-    --md-sys-checkbox-motion-duration: #{motion.$md-sys-motion-expressive-slow-effects-duration};
-    --md-sys-checkbox-motion-duration-reverse: #{motion.$md-sys-motion-expressive-default-effects-duration};
-    --md-sys-checkbox-motion-spatial: #{motion.$md-sys-motion-expressive-fast-spatial};
+#{$checkbox} {
+    --md-comp-checkbox-motion-duration: #{motion.$md-sys-motion-expressive-slow-effects-duration};
+    --md-comp-checkbox-motion-duration-reverse: #{motion.$md-sys-motion-expressive-default-effects-duration};
+    --md-comp-checkbox-motion-spatial: #{motion.$md-sys-motion-expressive-fast-spatial};
 
+    --_size: var(--md-comp-checkbox-container-size, 18px);
+    --_outline-width: var(--md-comp-checkbox-outline-width, 2px);
+    --_check-thickness: var(--md-comp-checkbox-check-thickness, 2px);
     --statelayer-color: var(--md-sys-color-on-surface);
 
     appearance: none;
@@ -69,21 +68,25 @@ input[type=checkbox].micl-checkbox {
     border-radius: var(--md-sys-shape-corner-full);
     outline-offset: -4px;
 
+    // The check mark: two currentColor borders rotated into a check, revealed by a
+    // combination of block-size and clip-path transitions. currentColor, so that the
+    // error and disabled states recolour it with a single color declaration.
     &::before {
-        --md-sys-checkbox-check-width: calc(var(--md-sys-checkbox-container-size) - 3px);
-        --md-sys-checkbox-check-height: calc(0.4667 * var(--md-sys-checkbox-check-width));
+        --_check-width: calc(var(--_size) - 3px);
+        --_check-height: calc(0.4667 * var(--_check-width));
 
         content: "";
         box-sizing: border-box;
         position: absolute;
-        inline-size: var(--md-sys-checkbox-check-width);
+        inline-size: var(--_check-width);
         block-size: 0;
         inset: 0;
-        inset-block-start: calc(-0.25 * var(--md-sys-checkbox-container-size));
+        inset-block-start: calc(-0.25 * var(--_size));
         inset-inline-start: 1px;
         margin: auto;
-        border-block-end: var(--md-sys-checkbox-check-thickness) var(--md-sys-color-on-primary) solid;
-        border-inline-start: var(--md-sys-checkbox-check-thickness) var(--md-sys-color-on-primary) solid;
+        color: var(--md-comp-checkbox-selected-icon-color, var(--md-sys-color-on-primary));
+        border-block-end: var(--_check-thickness) currentColor solid;
+        border-inline-start: var(--_check-thickness) currentColor solid;
         transform: rotate(-45deg);
         transform-origin: center;
         clip-path: rect(0 2px 0 0);
@@ -97,41 +100,40 @@ input[type=checkbox].micl-checkbox {
           transform 0ms linear var(--md-sys-motion-duration-short3);
     }
     &::after {
-        --md-sys-checkbox-background-color: transparent;
-        --md-sys-checkbox-border-color: var(--md-sys-color-on-surface-variant);
+        --_container-color: transparent;
+        --_outline-color: var(--md-comp-checkbox-unselected-outline-color, var(--md-sys-color-on-surface-variant));
 
         content: "";
         box-sizing: border-box;
         position: absolute;
-        inline-size: var(--md-sys-checkbox-container-size);
-        block-size: var(--md-sys-checkbox-container-size);
+        inline-size: var(--_size);
+        block-size: var(--_size);
         inset: 0;
         margin: auto;
-        border: var(--md-sys-checkbox-border-width) solid var(--md-sys-checkbox-border-color);
+        border: var(--_outline-width) solid var(--_outline-color);
         border-radius: 2px;
-        background-color: var(--md-sys-checkbox-background-color);
+        background-color: var(--_container-color);
         transition:
-            background-color var(--md-sys-checkbox-motion-duration-reverse) motion.$md-sys-motion-easing-emphasized var(--md-sys-checkbox-motion-duration-reverse),
-            border-color var(--md-sys-checkbox-motion-duration-reverse) motion.$md-sys-motion-easing-emphasized var(--md-sys-checkbox-motion-duration-reverse);
+            background-color var(--md-comp-checkbox-motion-duration-reverse) motion.$md-sys-motion-easing-emphasized var(--md-comp-checkbox-motion-duration-reverse),
+            border-color var(--md-comp-checkbox-motion-duration-reverse) motion.$md-sys-motion-easing-emphasized var(--md-comp-checkbox-motion-duration-reverse);
     }
-    &:checked,
-    &:indeterminate {
+    &:is(:checked, :indeterminate) {
         --statelayer-color: var(--md-sys-color-primary);
 
         &::before {
-            block-size: var(--md-sys-checkbox-check-height);
-            clip-path: rect(0 calc(var(--md-sys-checkbox-container-size) - 5px) 18px 0);
+            block-size: var(--_check-height);
+            clip-path: rect(0 calc(var(--_size) - 5px) var(--_size) 0);
             transition:
-                block-size var(--md-sys-motion-duration-short3) var(--md-sys-checkbox-motion-spatial),
-                clip-path var(--md-sys-motion-duration-long4) var(--md-sys-motion-duration-short3) var(--md-sys-checkbox-motion-spatial);
+                block-size var(--md-sys-motion-duration-short3) var(--md-comp-checkbox-motion-spatial),
+                clip-path var(--md-sys-motion-duration-long4) var(--md-sys-motion-duration-short3) var(--md-comp-checkbox-motion-spatial);
         }
         &::after {
-            --md-sys-checkbox-background-color: var(--md-sys-color-primary);
-            --md-sys-checkbox-border-color: var(--md-sys-color-primary);
+            --_container-color: var(--md-comp-checkbox-selected-container-color, var(--md-sys-color-primary));
+            --_outline-color: var(--md-comp-checkbox-selected-container-color, var(--md-sys-color-primary));
 
             transition:
-                background-color var(--md-sys-checkbox-motion-duration) linear,
-                border-color var(--md-sys-checkbox-motion-duration) motion.$md-sys-motion-easing-emphasized;
+                background-color var(--md-comp-checkbox-motion-duration) linear,
+                border-color var(--md-comp-checkbox-motion-duration) motion.$md-sys-motion-easing-emphasized;
         }
     }
     &:indeterminate::before {
@@ -143,10 +145,9 @@ input[type=checkbox].micl-checkbox {
         --statelayer-color: var(--md-sys-color-error);
 
         &::after {
-            --md-sys-checkbox-border-color: var(--md-sys-color-error);
+            --_outline-color: var(--md-sys-color-error);
         }
-        &:checked,
-        &:indeterminate {
+        &:is(:checked, :indeterminate) {
             &:hover,
             &:focus-visible,
             &:active {
@@ -156,17 +157,17 @@ input[type=checkbox].micl-checkbox {
                 color: var(--md-sys-color-on-error);
             }
             &::after {
-                --md-sys-checkbox-background-color: var(--md-sys-color-error);
+                --_container-color: var(--md-sys-color-error);
             }
         }
-        &:not(:checked):not(:indeterminate) {
+        &:not(:checked, :indeterminate) {
             &:hover,
             &:focus-visible,
             &:active {
                 --statelayer-color: var(--md-sys-color-error);
 
                 &::after {
-                    --md-sys-checkbox-border-color: var(--md-sys-color-error);
+                    --_outline-color: var(--md-sys-color-error);
                 }
             }
         }
@@ -183,17 +184,18 @@ input[type=checkbox].micl-checkbox {
             ),
             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%;
         cursor: pointer;
         transition:
             background-size 0ms,
-            --statelayer-opacity var(--md-sys-checkbox-motion-duration) linear;
+            --statelayer-opacity var(--md-comp-checkbox-motion-duration) linear;
 
         &:hover {
             --statelayer-opacity: var(--md-sys-state-hover-state-layer-opacity, 8%);
 
-            &:not(:checked):not(:indeterminate)::after {
-                --md-sys-checkbox-border-color: var(--md-sys-color-on-surface);
+            &:not(:checked, :indeterminate)::after {
+                --_outline-color: var(--md-sys-color-on-surface);
             }
         }
         &:focus-visible {
@@ -201,68 +203,66 @@ input[type=checkbox].micl-checkbox {
 
             outline: var(--md-sys-state-focus-indicator-thickness, 3px) solid var(--md-sys-color-secondary);
 
-            &:not(:checked):not(:indeterminate)::after {
-                --md-sys-checkbox-border-color: var(--md-sys-color-on-surface);
+            &:not(:checked, :indeterminate)::after {
+                --_outline-color: var(--md-sys-color-on-surface);
             }
         }
         &:active {
             --statelayer-color: var(--md-sys-color-on-surface);
             --statelayer-opacity: var(--md-sys-state-pressed-state-layer-opacity, 10%);
 
-            &:not(:checked):not(:indeterminate) {
+            &:not(:checked, :indeterminate) {
                 --statelayer-color: var(--md-sys-color-primary);
 
                 &::after {
-                    --md-sys-checkbox-border-color: var(--md-sys-color-on-surface);
+                    --_outline-color: var(--md-sys-color-on-surface);
                 }
             }
         }
         &.micl-rippling {
-            animation: micl-ripple var(--md-sys-state-ripple-duration) motion.$md-sys-motion-easing-standard;
+            animation: micl-ripple var(--md-sys-state-ripple-duration);
         }
     }
     &:disabled {
         opacity: var(--md-sys-state-disabled-state-layer-opacity, 38%);
 
-        &:checked,
-        &:indeterminate {
+        &:is(:checked, :indeterminate) {
             &::before {
                 color: var(--md-sys-color-surface);
             }
             &::after {
-                --md-sys-checkbox-background-color: var(--md-sys-color-on-surface);
+                --_container-color: var(--md-sys-color-on-surface);
             }
         }
         &::after {
-            --md-sys-checkbox-border-color: var(--md-sys-color-on-surface);
+            --_outline-color: var(--md-sys-color-on-surface);
         }
     }
 }
 
-input[type=checkbox].micl-checkbox:not(:disabled) + label,
-label:has(+ input[type=checkbox].micl-checkbox:not(:disabled)) {
-    -webkit-tap-highlight-color: transparent;
-    cursor: pointer;
+#{$checkbox}:not(:disabled) + label,
+label:has(+ #{$checkbox}:not(:disabled)) {
+    @extend %micl-toggle-label-pointer;
 }
-input[type=checkbox].micl-checkbox + label,
-label:has(+ input[type=checkbox].micl-checkbox) {
-    color: var(--md-sys-color-on-surface);
+#{$checkbox} + label,
+label:has(+ #{$checkbox}) {
+    @extend %micl-toggle-label;
 }
-input[type=checkbox].micl-checkbox:disabled + label,
-label:has(+ input[type=radio].micl-checkbox:disabled) {
-    opacity: var(--md-sys-state-disabled-state-layer-opacity, 38%)
+#{$checkbox}:disabled + label,
+label:has(+ #{$checkbox}:disabled) {
+    @extend %micl-toggle-label-disabled;
 }
 
-[dir=rtl] input[type=checkbox].micl-checkbox {
+#{$checkbox}:dir(rtl) {
     &::before {
-        clip-path: rect(0 18px 8px 16px);
+        clip-path: rect(0 var(--_size) var(--_size) calc(var(--_size) - 2px));
     }
     &:checked::before {
-        clip-path: rect(0 18px 8px 2px);
+        clip-path: rect(0 var(--_size) var(--_size) 2px);
         transform: rotate(45deg);
     }
     &:indeterminate::before {
-        clip-path: rect(0 18px 8px 2px);
+        clip-path: rect(0 var(--_size) var(--_size) 2px);
         transform: rotate(0deg);
     }
 }

package/components/chip/README.md

@@ -0,0 +1,186 @@
+# Chip
+This component implements the [Material Design 3 Chips](https://m3.material.io/components/chips/overview) design. Chips help people enter information, make selections, filter content, or trigger actions.
+
+## Basic Usage
+
+### HTML
+The Chip component is an extension of the [**Button** component](../button/README.md). Chips are placed in a `micl-chips` container. To create a basic chip, use the `<button>` element with a class that specifies its type. This example uses two assist chips:
+
+```HTML
+<fieldset class="micl-chips">
+  <button type="button" class="micl-chip-assist">Turn on lights</button>
+  <button type="button" class="micl-chip-assist">Set alarm</button>
+</fieldset>
+```
+
+### CSS
+Import the chip styles into your project:
+
+```CSS
+@use "material-inspired-component-library/dist/chip";
+```
+
+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.
+
+### Live Demo
+A live example of the [Chip component](https://henkpb.github.io/micl/chip.html) is available to interact with.
+
+## Variants
+Material Design provides **four types** of chips, each with its own class:
+
+| Type | Class | Purpose |
+|---|---|---|
+| Assist | `micl-chip-assist` | Trigger a smart or automated action |
+| Filter | `micl-chip-filter` | Select from a set of options |
+| Input | `micl-chip-input` | Represent discrete pieces of information entered by the user |
+| Suggestion | `micl-chip-suggestion` | Present dynamically generated suggestions |
+
+By default, chips have an **outlined** appearance. For an elevated appearance without an outline, add the `micl-chip--elevated` class:
+
+```HTML
+<button type="button" class="micl-chip-assist micl-chip--elevated">Turn on lights</button>
+```
+
+Adding the `disabled` boolean attribute causes the chip to be displayed in a disabled state. **Exceptions**: for filter chips, the attribute is placed on the nested `<input>` element instead, and for input chips on both nested `<button>` elements (see below).
+
+### Filter Chip
+A filter chip is a `<label>` wrapping an `<input type="checkbox">` (multiple selection) or `<input type="radio">` (single selection), followed by the label text. The leading element with the checkmark icon is required; it is revealed with an animation when the chip is selected:
+
+```HTML
+<fieldset class="micl-chips">
+  <label class="micl-chip-filter">
+    <span class="micl-button__icon material-symbols-outlined" aria-hidden="true">check</span>
+    <input type="checkbox" name="amenities" value="parking">
+    <span>Parking</span>
+  </label>
+  <label class="micl-chip-filter">
+    <span class="micl-button__icon material-symbols-outlined" aria-hidden="true">check</span>
+    <input type="checkbox" name="amenities" value="garden" disabled>
+    <span>Garden</span>
+  </label>
+</fieldset>
+```
+
+The selected state follows the `:checked` state of the input, and the disabled state its `disabled` attribute.
+
+A filter chip may additionally carry a **leading icon**, placed before the checkmark icon. It is visible while the chip is unselected and hidden while it is selected.
+
+```HTML
+<label class="micl-chip-filter">
+  <span class="micl-button__icon material-symbols-outlined" aria-hidden="true">elevator</span>
+  <span class="micl-button__icon material-symbols-outlined" aria-hidden="true">check</span>
+  <input type="checkbox" name="amenities" value="elevator">
+  <span>Elevator</span>
+</label>
+```
+
+### Input Chip
+An input chip carries **two actions** — activating the chip and removing it. The chip itself is a non-interactive `<span>` container holding two sibling `<button>` elements: the primary action with the label, and the trailing remove action.
+
+```HTML
+<span class="micl-chip-input">
+  <button type="button" class="micl-chip__primary">Avocado</button>
+  <button type="button" class="micl-chip__remove material-symbols-outlined"
+          aria-label="Remove Avocado">close</button>
+</span>
+```
+
+To disable an input chip, place the `disabled` attribute on **both** buttons.
+
+An input chip may represent a person with a leading avatar — an `<img>`, or an element with a monogram — placed inside the primary action before the label.
+
+```HTML
+<span class="micl-chip-input">
+  <button type="button" class="micl-chip__primary">
+    <img src="jonas.webp" alt="" class="micl-chip__avatar">
+    <span>Jonas</span>
+  </button>
+  <button type="button" class="micl-chip__remove material-symbols-outlined"
+          aria-label="Remove Jonas">close</button>
+</span>
+```
+
+For a collection of input chips presented like a form field, add the `micl-chips--input` class to the container:
+
+```HTML
+<fieldset class="micl-chips micl-chips--input">
+  <legend class="md-sys-typescale-label-large">Recipients</legend>
+  ...
+</fieldset>
+```
+
+## Icons
+To add a leading icon to a chip, include an element with the `micl-button__icon` class before the label text:
+
+```HTML
+<button type="button" class="micl-chip-suggestion">
+  <span class="micl-button__icon material-symbols-outlined" aria-hidden="true">music_note</span>
+  <span>What song is this?</span>
+</button>
+```
+
+These examples use [Google Material Symbols](https://fonts.google.com/icons), but other icon libraries can be used just as well.
+
+## Theming
+Each chip type can be themed with CSS custom properties that follow the Material Design 3 component-token naming convention.
+
+### Assist
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-assist-chip-label-text-color` | Label colour | `--md-sys-color-on-surface` |
+| `--md-comp-assist-chip-leading-icon-color` | Icon colour | `--md-sys-color-primary` |
+| `--md-comp-assist-chip-outline-color` | Outline (border) colour | `--md-sys-color-outline-variant` |
+| `--md-comp-assist-chip-elevated-container-color` | Container background when elevated | `--md-sys-color-surface-container-low` |
+| `--md-comp-assist-chip-disabled-label-text-color` | Label & icon colour when disabled | `--md-sys-color-on-surface` at `38%` |
+| `--md-comp-assist-chip-disabled-outline-color` | Outline colour when disabled | `--md-sys-color-on-surface` at `12%` |
+
+### Filter
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-filter-chip-label-text-color` | Label colour | `--md-sys-color-on-surface-variant` |
+| `--md-comp-filter-chip-leading-icon-color` | Icon colour | `--md-sys-color-primary` |
+| `--md-comp-filter-chip-outline-color` | Outline (border) colour | `--md-sys-color-outline-variant` |
+| `--md-comp-filter-chip-elevated-container-color` | Container background when elevated | `--md-sys-color-surface-container-low` |
+| `--md-comp-filter-chip-selected-container-color` | Container background when selected | `--md-sys-color-secondary-container` |
+| `--md-comp-filter-chip-selected-label-text-color` | Label colour when selected | `--md-sys-color-on-secondary-container` |
+| `--md-comp-filter-chip-selected-leading-icon-color` | Checkmark colour when selected | `--md-sys-color-on-secondary-container` |
+| `--md-comp-filter-chip-disabled-label-text-color` | Label & icon colour when disabled | `--md-sys-color-on-surface` at `38%` |
+| `--md-comp-filter-chip-disabled-outline-color` | Outline colour when disabled | `--md-sys-color-on-surface` at `12%` |
+| `--md-comp-filter-chip-disabled-selected-container-color` | Container background when selected and disabled | `--md-sys-color-on-surface` |
+| `--md-comp-filter-chip-disabled-selected-container-opacity` | Container opacity when selected and disabled | `12%` |
+
+### Input
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-input-chip-label-text-color` | Label colour | `--md-sys-color-on-surface-variant` |
+| `--md-comp-input-chip-leading-icon-color` | Icon colour | the label colour |
+| `--md-comp-input-chip-trailing-icon-color` | Trailing (remove) icon colour | the leading icon colour |
+| `--md-comp-input-chip-outline-color` | Outline (border) colour | `--md-sys-color-outline-variant` |
+| `--md-comp-input-chip-disabled-label-text-color` | Label & icon colour when disabled | `--md-sys-color-on-surface` at `38%` |
+| `--md-comp-input-chip-disabled-outline-color` | Outline colour when disabled | `--md-sys-color-on-surface` at `12%` |
+| `--md-comp-input-chip-avatar-size` | Avatar diameter | `24px` |
+| `--md-comp-input-chip-avatar-shape` | Avatar corner shape | `--md-sys-shape-corner-full` |
+| `--md-comp-input-chip-disabled-avatar-opacity` | Avatar opacity when disabled | `38%` |
+| `--md-comp-input-chip-avatar-color` | Monogram avatar background colour ¹ | `--md-sys-color-primary-container` |
+| `--md-comp-input-chip-avatar-label-color` | Monogram avatar text colour ¹ | `--md-sys-color-on-primary-container` |
+
+¹ MICL extension: monogram avatars are not part of the Material Design token set, which only covers image avatars.
+
+### Suggestion
+| Custom property | Meaning | Default |
+|---|---|---|
+| `--md-comp-suggestion-chip-label-text-color` | Label colour | `--md-sys-color-on-surface-variant` |
+| `--md-comp-suggestion-chip-leading-icon-color` | Icon colour | `--md-sys-color-primary` |
+| `--md-comp-suggestion-chip-outline-color` | Outline (border) colour | `--md-sys-color-outline-variant` |
+| `--md-comp-suggestion-chip-elevated-container-color` | Container background when elevated | `--md-sys-color-surface-container-low` |
+| `--md-comp-suggestion-chip-disabled-label-text-color` | Label & icon colour when disabled | `--md-sys-color-on-surface` at `38%` |
+| `--md-comp-suggestion-chip-disabled-outline-color` | Outline colour when disabled | `--md-sys-color-on-surface` at `12%` |
+
+## Compatibility
+This component utilizes relative RGB color values and the `:has()` pseudo-class, 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.