material-inspired-component-library 1.0.0

package/components/card/README.md

@@ -0,0 +1,125 @@
+# Card
+This component implements the the [Material Design 3 Expressive Card](https://m3.material.io/components/cards/overview) design.
+
+## Basic Usage
+
+### HTML
+To add a basic card, use a `<div>` element with one of the primary card style classes: `micl-card-elevated`, `micl-card-filled` or `micl-card-outlined`.
+
+```HTML
+<div class="micl-card-elevated">
+  <p>This is a basic elevated card.</p>
+</div>
+```
+
+### CSS
+Import the card styles into your project:
+
+```CSS
+@use "micl/components/card";
+```
+
+### TypeScript
+No custom TypeScript is required for the core functionality of this component.
+
+### Demo
+A live example of the [Card component](https://henkpb.github.io/micl/card.html) is available for you to interact with.
+
+## Variants
+Cards come in **three distinct styles**:
+
+- `micl-card-elevated`: A card with a subtle shadow, visually lifted from the background. This is the style shown in Basic Usage.
+
+- `micl-card-filled`: A card with a solid background color, blending more seamlessly with its surroundings.
+  ```HTML
+  <div class="micl-card-filled">
+    <p>This is a filled card.</p>
+  </div>
+  ```
+
+- `micl-card-outlined`: A card with a clear border, often used for less prominent content or to indicate interactivity.
+
+### Card Content Structure
+
+While the card container is the only required element, the Card component provides several optional utility classes to help structure your card's content:
+```HTML
+<div class="micl-card-outlined" tabindex="0">
+  <img alt="Descriptive image text" class="micl-card__image" src="/path/to/your/image.jpg">
+
+  <div class="micl-card__headline-m">
+    <h2>Card headline</h2>
+  </div>
+
+  <p class="micl-card__subhead">This is a sub-header</p>
+  <p class="micl-card__supporting-text">This is supporting text that provides more details about the card's content.</p>
+
+  <div class="micl-card__content">
+    <p>Additional content</p>
+  </div>
+</div>
+```
+
+- **Headline Classes**: Use these classes for prominent text within the card. They expect a child heading element (`<h1>`-`<h6>`).
+  - `micl-card__headline-s` (small)
+  - `micl-card__headline-m` (medium) - *Used in the example above*
+  - `micl-card__headline-l` (large)
+
+- `micl-card__image`: Applies styling to an `<img>` element used as the primary image for the card.
+
+- `micl-card__subhead`: For secondary headings, displayed with a smaller font than the main headline.
+
+- `micl-card__supporting-text`: Intended for short descriptions or supplementary information, displayed with a smaller font.
+
+- `micl-card__content`: A flexible container for the main body of your card's content.
+
+### Actionable Cards
+For cards that are themselves clickable or interactive (e.g., to navigate to another page), specify the `tabindex="0"` attribute on the card container. Non-actionable cards, which contain interactive elements like buttons or links within their content, should *not* have a tabindex on the card container itself.
+
+### Expandable Cards
+Cards can also serve as containers for expandable detail areas using the `<details>` and `<summary>` elements. In this scenario, the `<summary>` element becomes the actionable part of the card.
+
+```HTML
+<details class="micl-card-elevated">
+  <summary>
+    <img alt="Image of a landscape" class="micl-card__image" src="/path/to/another/image.jpg">
+    <span class="micl-card__headline-m">
+      <span class="micl-heading">Expandable Card Title</span>
+    </span>
+    <span class="micl-card__supporting-text">Click to reveal more details.</span>
+  </summary>
+  <div class="micl-card__content">
+    <p>This is the hidden content that appears when the summary is clicked.</p>
+  </div>
+</details>
+```
+
+### States
+- **Disabled Cards**: To visually indicate a disabled card (e.g., non-interactive), add the `micl-card--disabled` class to the card container.
+
+- **Dragging State**: When implementing drag-and-drop functionality for cards, apply the `micl-card--dragging` class to the card container to provide visual feedback during the drag operation.
+
+## Customizations
+You can customize the appearance of the Card 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 dividers.
+
+| Variable name | Default Value | Description |
+| ------------- | ----- | ----------- |
+| --md-sys-card-margin | 8px | Sets the spacing between adjacent cards both horizontally and vertically |
+| --md-sys-card-padding-inline | 16px | Defines the amount of space between the left and right edges of a card and its content |
+
+**Example: Changing the card margins**
+
+```HTML
+<div style="--md-sys-card-margin:4px">
+  <div class="micl-card-filled">
+    <p>This is a filled card.</p>
+  </div>
+  <div class="micl-card-filled">
+    <p>This is another filled card.</p>
+  </div>
+</div>
+```
+
+## Compatibility
+This component uses the `color-mix` CSS functional notation, which might not be supported in your browser. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix#browser_compatibility) for details.
+
+The Card component uses the `interpolate-size` CSS property to smoothly open and close the detail area of a Details disclosure element, which might not be supported in your browser. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/interpolate-size#browser_compatibility) for details.

package/components/card/card.scss

@@ -0,0 +1,261 @@
+//
+// 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/motion';
+@use '../../styles/ripple';
+@use '../../styles/typography';
+
+:root {
+    --md-sys-card-margin: 8px;
+    --md-sys-card-padding-inline: 16px;
+}
+
+.micl-card-elevated,
+.micl-card-filled,
+.micl-card-outlined {
+    height: fit-content;
+    margin: var(--md-sys-card-margin);
+    border-radius: var(--md-sys-shape-corner-medium);
+    overflow: hidden;
+    interpolate-size: allow-keywords;
+
+    &[tabindex='0']:not(.micl-card--disabled) {
+        --miclripple: 1;
+
+        @include ripple.effect;
+
+        &:hover {
+            box-shadow: var(--md-sys-elevation-level1);
+            cursor: pointer;
+        }
+        &:focus-visible {
+            outline: var(--md-sys-state-focus-indicator-thickness) solid var(--md-sys-color-secondary);
+            outline-offset: var(--md-sys-state-focus-indicator-outer-offset);
+            box-shadow: var(--md-sys-elevation-level1);
+        }
+    }
+    &:not([tabindex='0']):not(.micl-card--disabled):has(> summary:focus-visible) {
+        outline: var(--md-sys-state-focus-indicator-thickness) solid var(--md-sys-color-secondary);
+        outline-offset: var(--md-sys-state-focus-indicator-outer-offset);
+    }
+    &::details-content {
+        height: 0;
+        overflow: hidden;
+        transition:
+            content-visibility var(--md-sys-motion-duration-medium4) allow-discrete,
+            height var(--md-sys-motion-duration-medium4) linear(motion.$md-sys-motion-spring-default-spatial);
+    }
+    &[open]::details-content {
+        height: auto;
+    }
+    &> summary {
+        padding-block-end: 8px;
+        outline: none;
+        list-style: none;
+        cursor: pointer
+    }
+}
+
+.micl-card-elevated {
+    background-color: var(--md-sys-color-surface-container-low);
+    box-shadow: var(--md-sys-elevation-level1);
+
+    &[tabindex='0']:not(.micl-card--disabled) {
+        &:hover {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface-container-low), var(--md-sys-color-on-surface) var(--md-sys-state-hover-state-layer-opacity));
+            box-shadow: var(--md-sys-elevation-level2);
+        }
+        &:focus-visible {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface-container-low), var(--md-sys-color-on-surface) var(--md-sys-state-focus-state-layer-opacity));
+        }
+        &:active {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface-container-low), var(--md-sys-color-on-surface) var(--md-sys-state-pressed-state-layer-opacity));
+            box-shadow: var(--md-sys-elevation-level1);
+        }
+        &.micl-card--dragging {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface-container-low), var(--md-sys-color-on-surface) var(--md-sys-state-dragged-state-layer-opacity));
+            box-shadow: var(--md-sys-elevation-level4);
+            cursor: grabbing;
+        }
+    }
+}
+.micl-card-filled {
+    background-color: var(--md-sys-color-surface-container-highest);
+    box-shadow: var(--md-sys-elevation-level0);
+
+    &[tabindex='0']:not(.micl-card--disabled) {
+        &:hover {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface-container-highest), var(--md-sys-color-on-surface) var(--md-sys-state-hover-state-layer-opacity));
+        }
+        &:focus-visible {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface-container-highest), var(--md-sys-color-on-surface) var(--md-sys-state-focus-state-layer-opacity));
+            box-shadow: var(--md-sys-elevation-level0);
+        }
+        &:active {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface-container-highest), var(--md-sys-color-on-surface) var(--md-sys-state-pressed-state-layer-opacity));
+            box-shadow: var(--md-sys-elevation-level0);
+        }
+        &.micl-card--dragging {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface-container-highest), var(--md-sys-color-on-surface) var(--md-sys-state-dragged-state-layer-opacity));
+            box-shadow: var(--md-sys-elevation-level3);
+            cursor: grabbing;
+        }
+    }
+}
+.micl-card-outlined {
+    background-color: var(--md-sys-color-surface);
+    box-shadow: var(--md-sys-elevation-level0);
+    border: 1px solid var(--md-sys-color-outline-variant);
+
+    &[tabindex='0']:not(.micl-card--disabled) {
+        &:hover {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface), var(--md-sys-color-on-surface) var(--md-sys-state-hover-state-layer-opacity));
+        }
+        &:focus-visible {
+            border-color: var(--md-sys-color-on-surface);
+            background-color: color-mix(in srgb, var(--md-sys-color-surface), var(--md-sys-color-on-surface) var(--md-sys-state-focus-state-layer-opacity));
+            box-shadow: var(--md-sys-elevation-level0);
+        }
+        &:active {
+            border-color: var(--md-sys-color-outline-variant);
+            background-color: color-mix(in srgb, var(--md-sys-color-surface), var(--md-sys-color-on-surface) var(--md-sys-state-pressed-state-layer-opacity));
+            box-shadow: var(--md-sys-elevation-level0);
+        }
+        &.micl-card--dragging {
+            background-color: color-mix(in srgb, var(--md-sys-color-surface), var(--md-sys-color-on-surface) var(--md-sys-state-dragged-state-layer-opacity));
+            box-shadow: var(--md-sys-elevation-level3);
+            cursor: grabbing;
+        }
+    }
+}
+
+.micl-card--disabled {
+    opacity: 38%;
+    pointer-events: none;
+
+    &.micl-card-elevated {
+        background-color: var(--md-sys-color-surface);
+    }
+    &.micl-card-filled {
+        background-color: var(--md-sys-color-surface-variant);
+    }
+    &.micl-card-outlined {
+        box-shadow: var(--md-sys-elevation-level0);
+        border-color: rgb(from var(--md-sys-color-outline) r g b / 12%);
+    }
+}
+
+.micl-card__image {
+    width: 100%;
+    border-radius: var(--md-sys-shape-corner-medium);
+}
+
+.micl-card__headline-s,
+.micl-card__headline-m,
+.micl-card__headline-l {
+    display: flex;
+    align-items: center;
+    column-gap: 8px;
+    margin-block: 8px;
+    color: var(--md-sys-color-on-surface-variant);
+
+    h1, h2, h3, h4, h5, h6, .micl-heading {
+        flex: 1 2 fit-content;
+        margin: 0;
+        padding-inline: var(--md-sys-card-padding-inline);
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+
+        &:has(+ button) {
+            padding-inline-end: 0;
+        }
+    }
+    &:has(button) {
+        margin-block: 0;
+    }
+}
+.micl-card__headline-s {
+    h1, h2, h3, h4, h5, h6, .micl-heading {
+        @include typography.headline-small;
+    }
+}
+.micl-card__headline-m {
+    h1, h2, h3, h4, h5, h6, .micl-heading {
+        @include typography.headline-medium;
+    }
+}
+.micl-card__headline-l {
+    h1, h2, h3, h4, h5, h6, .micl-heading {
+        @include typography.headline-large;
+    }
+}
+
+.micl-card__subhead {
+    @include typography.title-medium;
+
+    display: block;
+    margin-block: 0 8px;
+    padding-inline: var(--md-sys-card-padding-inline);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--md-sys-color-on-surface-variant);
+}
+
+.micl-card__supporting-text {
+    @include typography.body-small;
+
+    display: block;
+    margin-block: 0 8px;
+    padding-inline: var(--md-sys-card-padding-inline);
+    color: var(--md-sys-color-on-surface-variant);
+}
+
+.micl-card-elevated[tabindex='0']:not(.micl-card--disabled),
+.micl-card-filled[tabindex='0']:not(.micl-card--disabled),
+.micl-card-outlined[tabindex='0']:not(.micl-card--disabled) {
+    &:hover,
+    &:focus-visible,
+    &:active,
+    &.micl-card--dragging {
+        .micl-card__headline-s,
+        .micl-card__headline-m,
+        .micl-card__headline-l {
+            color: var(--md-sys-color-on-surface);
+
+            button {
+                color: var(--md-sys-color-on-surface);
+            }
+        }
+        .micl-card__subhead,
+        .micl-card__supporting-text {
+            color: var(--md-sys-color-on-surface);
+        }
+    }
+}
+
+.micl-card__content {
+    box-sizing: border-box;
+    padding-inline: var(--md-sys-card-padding-inline);
+    background-color: inherit;
+    overflow: hidden;
+}

package/components/checkbox/README.md

@@ -0,0 +1,62 @@
+# Checkbox
+This component implements the the [Material Design 3 Expressive Checkbox](https://m3.material.io/components/checkbox/overview) design.
+
+## Basic Usage
+
+### HTML
+To add a basic checkbox, use the `<input type="checkbox">` element with the `micl-checkbox` class, paired with a `<label>` element:
+
+```HTML
+<input type="checkbox" id="mycheckbox" class="micl-checkbox" value="foo">
+<label for="mycheckbox">Bar</label>
+```
+
+### CSS
+Import the checkbox styles into your project:
+
+```CSS
+@use "micl/components/checkbox";
+```
+
+### TypeScript
+This component requires a TypeScript module to support checking and unchecking using a keyboard. You can import the specific module or use the main MICL TypeScript library, which handles initialization automatically.
+
+To manually initialize the component:
+
+```TypeScript
+import miclCheckbox from 'micl/components/checkbox';
+
+miclCheckbox.initialize(document.querySelector('.micl-checkbox'));
+```
+
+### Demo
+A live example of the [Checkbox component](https://henkpb.github.io/micl/checkbox.html) is available for you to interact with.
+
+## Variants
+Adding the `micl-checkbox--error` CSS class to the `<input>` element will create an error-checkbox as specified by the Material Design 3 specification.
+
+A checkbox can be disabled by adding the `disabled` attribute to the `<input>` element.
+
+The Checkbox component respects the `dir` global attribute, automatically adjusting its layout for right-to-left (RTL) languages when `dir="rtl"` is applied to an ancestor element.
+
+## Customizations
+You can customize the appearance of the Checkbox 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 checkboxes.
+
+| Variable name | Default Value | Description |
+| ------------- | ------------- | ----------- |
+| --md-sys-checkbox-border-width | 2px | Controls the thickness of the checkbox's border |
+| --md-sys-checkbox-container-size | 18px | Defines the size of the checkbox itself |
+| --md-sys-checkbox-selected-icon | \2A3D | The character used as the checkmark for the checkbox |
+| --md-sys-checkbox-state-layer-radius | 20px | Sets the radius of the interactive area that indicates the component's current state (e.g., hover, focus, press) |
+
+**Example: Changing the size of the interactive area**
+
+```HTML
+<div style="--md-sys-checkbox-state-layer-radius:24px">
+  <input type="checkbox" id="mycheckbox" class="micl-checkbox">
+  <label for="mycheckbox">Checkbox</label>
+</div>
+```
+
+## 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.