material-inspired-component-library 2.0.0 → 3.0.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+micl.hermana@proton.me.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/README.md

@@ -76,9 +76,15 @@ Copy the main `micl.js` file to your distribution folder and include it in your
 ```
 This will initialize all MICL components, including those that will be added to the DOM later on.
 
+## Foundations
+A separate CSS file, based on the [Material Design Layout Foundation](https://m3.material.io/foundations/layout/understanding-layout/overview), provides styles for an adaptive layout. It includes styles for the **window frame**, **body region** and **panes** that adjust to the available screen space, ensuring your layout follows Material Design's responsive guidelines.
+
+- [x] [Layout](layout/README.md)
+
 ## Available components ✅
 The library currently consists of the following components:
 - [x] [Accordion](components/accordion/README.md)
+- [x] [App Bar](components/appbar/README.md)
 - [x] [Badge](components/badge/README.md)
 - [x] [Bottom sheet](components/bottomsheet/README.md)
 - [x] [Button](components/button/README.md)
@@ -99,6 +105,14 @@ The library currently consists of the following components:
 
 ## Change Log
 
+### 3.0.0 (24.09.2025)
+**Features**
+
+- **App Bar**: New component.
+- **Layout**: Support for adaptive layout.
+- Improved handling of target area for small buttons.
+- **BREAKING:** Use `<nav>` instead of `<div>` for Navigation rail.
+
 ### 2.0.0 (04.09.2025)
 **Features**
 

package/components/README.md

@@ -10,3 +10,5 @@ Each component is self-contained in a separate folder, making it easy to find wh
 - A README.md file for detailed documentation.
 
 Most components are standalone, but some are built on top of others. For example, the [Menu component](./menu/README.md) extends the [List component](./list/README.md), so it requires the styles and functionality of both. Always check the documentation for each component to see which dependencies you need to import. This ensures everything works as expected.
+
+A [separate CSS file](../layout/README.md), based on the [Material Design Layout Foundation](https://m3.material.io/foundations/layout/understanding-layout/overview), provides styles for an adaptive layout. It includes styles for the **window frame**, **body region** and **panes** that adjust to the available screen space, ensuring your layout follows Material Design's responsive guidelines.

package/components/appbar/README.md

@@ -0,0 +1,94 @@
+# App Bar
+This component implements the the [Material Design 3 Expressive App Bar](https://m3.material.io/components/app-bars/overview) design. The app bar serves as the top container for a page, displaying the page title, primary actions, and navigation options.
+
+## Basic Usage
+
+### HTML
+To add a basic (small) app bar, use the `<header>` element with the `micl-appbar` class. The `<h1>` and `<p>` elements within the `.micl-appbar__headline` `<div>` define the main headline and an optional subtitle.
+
+```HTML
+<header class="micl-appbar">
+  <div class="micl-appbar__headline">
+    <h1>Headline</h1>
+    <p class="micl-appbar__subtitle">Subtitle</p>
+  </div>
+</header>
+```
+
+### CSS
+Import the app bar styles into your project:
+
+```CSS
+@use "material-inspired-component-library/dist/appbar";
+```
+
+### JavaScript
+No custom JavaScript is required for the core functionality of this component.
+
+### Demo
+A live example of the [App Bar component](https://henkpb.github.io/micl/index.html) is available for you to interact with.
+
+## Variants
+The app bar component supports three sizes: **small**, **medium** (flexible), and **large** (flexible). Use a modifier class to specify a size other than the default small size.
+
+- **Small** (default): `<header class="micl-appbar">`
+- **Medium**: `<header class="micl-appbar micl-appbar--medium">`
+- **Large**: `<header class="micl-appbar micl-appbar--large">`
+
+To center the headline and subtitle, add the `micl-appbar__headline--center` class to the headline container.
+
+**Example: A medium-sized app bar with centered text**
+
+```HTML
+<header class="micl-appbar micl-appbar--medium">
+  <div class="micl-appbar__headline micl-appbar__headline--center">
+    <h1>Headline</h1>
+    <p class="micl-appbar__subtitle">Subtitle</p>
+  </div>
+</header>
+```
+
+### Leading content
+Use the `micl-appbar__leading` (or: `micl-appbar__leading-icon`) class for an element (or: icon) placed before the headline.
+
+**Example: An app bar with a home link**
+
+```HTML
+<header class="micl-appbar">
+  <a href="index.html" class="micl-appbar__leading-icon micl-link micl-iconbutton-standard-m" aria-label="Home">
+    <span class="material-symbols-outlined" aria-hidden="true">home</span>
+  </a>
+  <div class="micl-appbar__headline">
+    <h1>Headline</h1>
+  </div>
+</header>
+```
+
+### Trailing content
+Use the `micl-appbar__trailing` (or: `micl-appbar__trailing-icon`) class for elements (or: icons) placed after the headline.
+
+**Example: An app bar with a settings-button**
+
+```HTML
+<header class="micl-appbar">
+  <div class="micl-appbar__headline">
+    <h1>Headline</h1>
+  </div>
+  <button type="button" class="micl-appbar__trailing micl-iconbutton-tonal-s micl-iconbutton--wide material-symbols-outlined">settings</button>
+</header>
+```
+
+### Sticky app bar
+The app bar is 'glued' to the top of the page when one of the following conditions is met:
+
+- The [body region](../../layout/README.md) contains only one pane.
+- The body region contains two or more panes and the page has a compact size.
+- The body region contains two or more panes, has the `micl-body--stacked-to-expanded` class and the page has a compact or medium size.
+- The body region contains two or more panes, has the `micl-body--stacked-to-large` class and the page has a compact, medium or expanded size.
+- The body region contains two or more panes, has the `micl-body--stacked-to-extralarge` class and the page has a compact, medium, expanded or large size.
+- The app bar has the `micl-appbar--sticky` class.
+
+Adding the `micl-appbar--not-sticky` class to the app bar will prohibit gluing the app bar to the top of the page.
+
+## Compatibility
+This component uses the `animation-timeline` CSS property for the scroll-effect, which may not be supported in your browser. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline#browser_compatibility) for details.

package/components/appbar/index.scss

@@ -0,0 +1,216 @@
+//
+// 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 '../../layout';
+@use '../../styles/elevation';
+@use '../../styles/shapes';
+@use '../../styles/statelayer';
+@use '../../styles/typography';
+
+@mixin appbar-sticky() {
+    position: sticky;
+    inset: unset;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    animation: 1ms linear alternate appbar-background;
+    animation-timeline: scroll(root);
+}
+
+.micl-appbar {
+    --md-sys-appbar-height: 64px;
+    --md-sys-appbar-padding-block-start: 0px;
+    --md-sys-appbar-padding-block-end: 0px;
+    --md-sys-appbar-padding-inline: 4px;
+
+    box-sizing: border-box;
+    display: grid;
+    grid-template-areas:
+        "appbar-leading appbar-middle appbar-trailing"
+        "appbar-bottom appbar-bottom appbar-bottom";
+    grid-template-columns: 0fr 1fr max-content;
+    column-gap: 4px;
+    align-items: center;
+    min-block-size: var(--md-sys-appbar-height);
+    padding-block: var(--md-sys-appbar-padding-block-start) var(--md-sys-appbar-padding-block-end);
+    padding-inline: var(--md-sys-appbar-padding-inline);
+    border-start-start-radius: inherit;
+    border-start-end-radius: inherit;
+    background-color: var(--md-sys-color-surface);
+    box-shadow: var(--md-sys-elevation-level0);
+    z-index: 8;
+
+    &.micl-appbar--sticky {
+        @include appbar-sticky;
+    }
+    .micl-appbar__leading {
+        grid-area: appbar-leading;
+        margin-inline-start: calc(var(--md-sys-layout-window-margin) - var(--md-sys-appbar-padding-inline));
+    }
+    .micl-appbar__leading-icon {
+        grid-area: appbar-leading;
+        margin-inline-start: calc(var(--md-sys-layout-window-margin) - (var(--micl-width, statelayer.$md-sys-target-size) / 2) + (24px / 2) - var(--md-sys-appbar-padding-inline));
+        color: var(--md-sys-color-on-surface);
+    }
+    .micl-appbar__headline {
+        display: flex;
+        grid-area: appbar-middle;
+        flex-direction: column;
+        align-items: flex-start;
+        margin: 8px 0;
+        border-radius: var(--md-sys-shape-corner-none);
+        color: var(--md-sys-color-on-surface);
+
+        &.micl-appbar__headline--center {
+            align-items: center;
+            text-align: center;
+        }
+        h1, h2, h3, h4, h5, h6, .micl-heading {
+            @include typography.title-large;
+
+            margin: 0;
+        }
+        .micl-appbar__subtitle {
+            margin: 0;
+            color: var(--md-sys-color-on-surface-variant);
+        }
+    }
+    &:has(.micl-appbar__subtitle) {
+        .micl-appbar__subtitle {
+            @include typography.label-medium;
+        }
+    }
+    .micl-appbar__trailing {
+        grid-area: appbar-trailing;
+        margin-inline-end: calc(var(--md-sys-layout-window-margin) - var(--md-sys-appbar-padding-inline));
+    }
+    .micl-appbar__trailing-icon {
+        grid-area: appbar-trailing;
+        margin-inline-end: calc(var(--md-sys-layout-window-margin) - (var(--micl-width, statelayer.$md-sys-target-size) / 2) + (24px / 2) - var(--md-sys-appbar-padding-inline));
+        color: var(--md-sys-color-on-surface-variant);
+    }
+    &.micl-appbar--medium {
+        --md-sys-appbar-height: 112px;
+        --md-sys-appbar-padding-block-start: 4px;
+        --md-sys-appbar-padding-block-end: 12px;
+
+        padding-inline-start: 0;
+
+        .micl-appbar__headline {
+            grid-area: appbar-bottom;
+            margin: 0;
+            padding-inline-start: var(--md-sys-layout-window-margin);
+
+            h1, h2, h3, h4, h5, h6, .micl-heading {
+                @include typography.headline-medium;
+            }
+        }
+        &:has(.micl-appbar__subtitle) {
+            --md-sys-appbar-height: 136px;
+
+            .micl-appbar__subtitle {
+                @include typography.title-small;
+            }
+        }
+    }
+    &.micl-appbar--large {
+        --md-sys-appbar-height: 120px;
+        --md-sys-appbar-padding-block-start: 4px;
+        --md-sys-appbar-padding-block-end: 12px;
+
+        padding-inline-start: 0;
+
+        .micl-appbar__headline {
+            grid-area: appbar-bottom;
+            margin: 0;
+            padding-inline-start: var(--md-sys-layout-window-margin);
+
+            h1, h2, h3, h4, h5, h6, .micl-heading {
+                @include typography.display-small;
+            }
+        }
+        &:has(.micl-appbar__subtitle) {
+            --md-sys-appbar-height: 152px;
+
+            .micl-appbar__subtitle {
+                @include typography.title-medium;
+            }
+        }
+    }
+}
+
+.micl-body:not(:has(> .micl-pane:nth-child(2))) {
+    .micl-appbar:not(.micl-appbar--not-sticky) {
+        @include appbar-sticky;
+    }
+}
+.micl-body:has(> .micl-pane:nth-child(2)) {
+    @media (max-width: layout.$md-sys-window-medium-min) {
+        .micl-appbar:not(.micl-appbar--not-sticky) {
+            @include appbar-sticky;
+        }
+    }
+    @media (min-width: layout.$md-sys-window-medium-min) and (max-width: layout.$md-sys-window-medium-max) {
+        &.micl-body--stacked-to-expanded,
+        &.micl-body--stacked-to-large,
+        &.micl-body--stacked-to-extralarge {
+            .micl-appbar:not(.micl-appbar--not-sticky) {
+                @include appbar-sticky;
+            }
+        }
+    }
+    @media (min-width: layout.$md-sys-window-expanded-min) and (max-width: layout.$md-sys-window-expanded-max) {
+        &.micl-body--stacked-to-large,
+        &.micl-body--stacked-to-extralarge {
+            .micl-appbar:not(.micl-appbar--not-sticky) {
+                @include appbar-sticky;
+            }
+        }
+    }
+    @media (min-width: layout.$md-sys-window-large-min) and (max-width: layout.$md-sys-window-large-max) {
+        &.micl-body--stacked-to-extralarge {
+            .micl-appbar:not(.micl-appbar--not-sticky) {
+                @include appbar-sticky;
+            }
+        }
+    }
+}
+
+@keyframes appbar-background {
+    0% {
+        background-color: inherit;
+        border-start-start-radius: inherit;
+        border-start-end-radius: inherit;
+    }
+    10% {
+        background-color: var(--md-sys-color-surface-container);
+        box-shadow: var(--md-sys-elevation-level2);
+    }
+    50% {
+        border-start-start-radius: 0;
+        border-start-end-radius: 0;
+    }
+    100% {
+        background-color: var(--md-sys-color-surface-container);
+        box-shadow: var(--md-sys-elevation-level2);
+        border-start-start-radius: 0;
+        border-start-end-radius: 0;
+    }
+}

package/components/badge/README.md

@@ -4,12 +4,12 @@ This component implements the the [Material Design 3 Expressive Badge](https://m
 ## Basic Usage
 
 ### HTML
-To add a large badge, use a `<span>` element with the `micl-badge-large` class and add a short text inside. For a small badge, which is a simple dot, use a `<span>` with the `micl-badge-small` class and leave the element empty.
+To add a large badge, use a `<span>` element with the `micl-badge` class and add a short text inside. For a small badge, which is a simple dot, add the `micl-badge--small` class and leave the element empty.
 
 ```HTML
-<span class="micl-badge-large">57</span>
+<span class="micl-badge">57</span>
 
-<span class="micl-badge-small"></span>
+<span class="micl-badge micl-badge--small"></span>
 ```
 
 ### CSS
@@ -33,7 +33,7 @@ Badges are typically placed on top of other elements, like icons. To anchor a ba
 
 ```HTML
 <span class="material-symbols-outlined" style="anchor-name:--inbox">inbox</span>
-<span class="micl-badge-large" style="position-anchor:--inbox">57</span>
+<span class="micl-badge" style="position-anchor:--inbox">57</span>
 ```
 
 You can fine-tune the badge's position relative to its anchor using the following CSS variables:
@@ -57,7 +57,7 @@ You can customize the appearance of the Badge component by overriding its global
 
 ```HTML
 <div style="--md-sys-badge-small-size:8px">
-  <span class="micl-badge-small"></span>
+  <span class="micl-badge micl-badge--small"></span>
 </div>
 ```
 

package/components/badge/index.scss

@@ -27,42 +27,35 @@
     --md-sys-badge-large-padding: 4px;
 }
 
-.micl-badge-small {
+.micl-badge {
     --md-sys-badge-inline-offset: 0px;
     --md-sys-badge-block-offset: 0px;
 
     box-sizing: border-box;
     position: fixed;
-    inline-size: var(--md-sys-badge-small-size);
-    block-size: var(--md-sys-badge-small-size);
     inset: unset;
-    inset-block-start: calc(anchor(start) + var(--md-sys-badge-block-offset));
-    inset-inline-start: calc(anchor(end) - var(--md-sys-badge-small-size) - var(--md-sys-badge-inline-offset));
-    border-radius: calc(var(--md-sys-badge-small-size) / 2);
     margin: 0;
-    padding: 0;
     background-color: var(--md-sys-color-error);
     color: var(--md-sys-color-on-error);
-}
 
-.micl-badge-large {
-    --md-sys-badge-inline-offset: 0px;
-    --md-sys-badge-block-offset: 0px;
+    &.micl-badge--small {
+        inline-size: var(--md-sys-badge-small-size);
+        block-size: var(--md-sys-badge-small-size);
+        inset-block-start: calc(anchor(start) + var(--md-sys-badge-block-offset));
+        inset-inline-start: calc(anchor(end) - var(--md-sys-badge-small-size) - var(--md-sys-badge-inline-offset));
+        padding: 0;
+        border-radius: calc(var(--md-sys-badge-small-size) / 2);
+    }
+    &:not(.micl-badge--small) {
+        @include typography.label-small;
 
-    @include typography.label-small;
-
-    box-sizing: border-box;
-    position: fixed;
-    inline-size: fit-content;
-    max-inline-size: 34px;
-    min-inline-size: var(--md-sys-badge-large-size);
-    block-size: var(--md-sys-badge-large-size);
-    inset: unset;
-    inset-block-start: calc(anchor(start) - 2px + var(--md-sys-badge-block-offset));
-    inset-inline-start: calc(anchor(end) - 12px - var(--md-sys-badge-inline-offset));
-    margin: 0;
-    padding-inline: var(--md-sys-badge-large-padding);
-    border-radius: calc(var(--md-sys-badge-large-size) / 2);
-    background-color: var(--md-sys-color-error);
-    color: var(--md-sys-color-on-error);
+        inline-size: fit-content;
+        max-inline-size: 34px;
+        min-inline-size: var(--md-sys-badge-large-size);
+        block-size: var(--md-sys-badge-large-size);
+        inset-block-start: calc(anchor(start) - 2px + var(--md-sys-badge-block-offset));
+        inset-inline-start: calc(anchor(end) - 12px - var(--md-sys-badge-inline-offset));
+        padding-inline: var(--md-sys-badge-large-padding);
+        border-radius: calc(var(--md-sys-badge-large-size) / 2);
+    }
 }

package/components/bottomsheet/README.md

@@ -1,13 +1,13 @@
 # Bottom sheet
-This component implements the the [Material Design 3 Expressive Bottom sheet](https://m3.material.io/components/bottom-sheets/overview) design.
+This component implements the the [Material Design 3 Expressive Bottom sheet](https://m3.material.io/components/bottom-sheets/overview) design. Bottom sheets show secondary content anchored to the bottom of the screen.
 
 ## Basic Usage
 
 ### HTML
-To create a standard bottom sheet, use the `<dialog>` element with the `popover` attribute. The `closedby="any"` attribute allows the user to dismiss the bottom sheet by clicking anywhere outside of it.
+To create a standard bottom sheet, use the `<dialog>` element with the `popover` attribute.
 
 ```HTML
-<dialog id="mybottomsheet" class="micl-bottomsheet" closedby="any" popover>
+<dialog id="mybottomsheet" class="micl-bottomsheet" popover>
   <div class="micl-bottomsheet__content">
     ...your content...
   </div>
@@ -22,34 +22,50 @@ Import the bottom sheet styles into your project:
 ```
 
 ### JavaScript
-This component requires JavaScript to support **modal** and **resizable** bottom sheets:
+This component requires JavaScript to support **resizable** bottom sheets. The library will automatically initialize new components as they're added to the DOM.
 
 ```JavaScript
 import micl from "material-inspired-component-library/dist/micl";
 ```
 
-This will initialize any Bottom sheet component, including those that will be added to the DOM later on.
-
 ### Demo
 A live example of the [Bottom sheet component](https://henkpb.github.io/micl/bottomsheet.html) is available for you to interact with.
 
 ## Variants
+Setting the `popover` attribute to `manual` lets a bottom sheet co-exist and be interactive with the rest of the page.
+
+```HTML
+<dialog id="mybottomsheet" class="micl-bottomsheet" popover="manual">
+  <div class="micl-bottomsheet__content">
+    ...your content...
+  </div>
+</dialog>
+```
+
+### Modal Bottom Sheet
 A **modal** bottom 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.
 
-To create a modal bottom sheet, use the `<dialog>` element without the `popover` attribute. Use `closedby="closerequest"` to prevent the bottom sheet from being dismissed by clicking outside of it. You'll also need a button or other control with popovertarget to close it.
+To create a modal bottom sheet, use the `<dialog>` element without the `popover` attribute. Add the `closedby="any"` to allow the bottom sheet to be dismissed by a user clicking outside of it.
 
 ```HTML
-<dialog id="mybottomsheet" class="micl-bottomsheet" closedby="closerequest">
+<dialog id="mybottomsheet" class="micl-bottomsheet" closedby="any">
   <div class="micl-bottomsheet__content">
     ...your content...
   </div>
 </dialog>
 ```
 
-Include the bottom sheet heading (and optionally a drag-handle) to create a **resizable** bottom sheet.
+To open or close a bottom sheet, add the markup of a button that is linked to the bottom sheet using the `popovertarget` attribute:
+
+```HTML
+<button type="button" popovertarget="mybottomsheet">Open Bottom Sheet</button>
+```
+
+### Resizable Bottom Sheet
+To create a **resizable** bottom sheet, include a heading and an optional drag-handle.
 
 ```HTML
-<dialog id="mybottomsheet" class="micl-bottomsheet" closedby="any" popover>
+<dialog id="mybottomsheet" class="micl-bottomsheet" popover>
   <div class="micl-bottomsheet__headline">
     <button type="button" class="micl-bottomsheet__draghandle" aria-label="Drag handle"></button>
   </div>
@@ -59,17 +75,13 @@ Include the bottom sheet heading (and optionally a drag-handle) to create a **re
 </dialog>
 ```
 
-The height of a bottom sheet is determined by its contents, initially capped at 50% of the screen height. You can set multiple preset heights for the bottom sheet by adding the `data-snapheights` attribute:
+The initial height is determined by its content and capped at 50% of the screen's height. You can define specific preset heights by using the `data-miclsnapheights` attribute.
 
 ```HTML
-<dialog data-snapheights="200,420" ...>
+<dialog data-miclsnapheights="0,200,420" ...>
 ```
 
-To open or close a bottom sheet, add the markup of a button that is linked to the bottom sheet using the `popovertarget` attribute:
-
-```HTML
-<button type="button" popovertarget="mybottomsheet">Open Bottom Sheet</button>
-```
+The value `0` is equivalent to closing the bottom sheet. When a user clicks the drag-handle, the bottom sheet toggles between these preset heights and its initial height. The bottom sheet will also snap to these preset heights as a user drags the heading.
 
 ## Compatibility
 This component uses the Popover API, which might not be supported in your browser. Please check [Browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API#api.htmlelement.popover) for details.