mtrl 0.8.0-next.21 → 0.8.0-next.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mtrl",
-  "version": "0.8.0-next.21",
+  "version": "0.8.0-next.24",
   "description": "A functional TypeScript/JavaScript component library with composable architecture based on Material Design 3",
   "author": "floor",
   "license": "MIT License",
@@ -52,7 +52,6 @@
     "test:ui": "bun test --watch --ui",
     "docs": "typedoc --skipErrorChecking",
     "docs:js": "typedoc --options typedoc.simple.json",
-    "docs:alt": "bun generate-docs.js",
     "docs:serve": "bun run --bun serve docs",
     "docs:fix-errors": "tsc --noEmit --allowJs --skipLibCheck",
     "ts:check": "tsc --noEmit --skipLibCheck",

package/src/styles/abstract/_variables.scss

@@ -249,7 +249,6 @@ $button: (
   'padding-horizontal': 16px,
   'padding-horizontal-small': 12px, // text button (ButtonDefaults.TextButtonContentPadding)
   'padding-icon': 12px, // small button leading space next to an icon (pointer devices)
-  'border-radius': map.get($shape, 'full'),
   'transition-duration': map.get($motion, 'duration-short2'),
   'transition-easing': map.get($motion, 'easing-standard'),
   // Container height per size
@@ -288,6 +287,19 @@ $button: (
   'shape-square-m': map.get($shape, 'large'),
   'shape-square-l': map.get($shape, 'extra-large'),
   'shape-square-xl': map.get($shape, 'extra-large'),
+  // Round container shape per size: exactly half the container height.
+  //
+  // A pill needs the real radius, not merely a large one. border-radius
+  // animates on the number in the stylesheet, not on the corner you see, so a
+  // 9999px pill morphing to a 12px pressed shape spends almost the whole
+  // transition above half the height, paints as a pill throughout, and then
+  // snaps square at the very end. Half the height interpolates linearly and
+  // the morph reads as a morph.
+  'shape-round-xs': 16px,
+  'shape-round-s': 20px,
+  'shape-round-m': 28px,
+  'shape-round-l': 48px,
+  'shape-round-xl': 68px,
   // Pressed container shape per size (round and square)
   'shape-pressed-xs': map.get($shape, 'small'),
   'shape-pressed-s': map.get($shape, 'small'),

package/src/styles/components/_bottom-sheet.scss

@@ -0,0 +1,167 @@
+// src/styles/components/_bottom-sheet.scss
+@use "../abstract/base" as base;
+@use "../abstract/variables" as v;
+@use "../abstract/mixins" as m;
+@use "../abstract/theme" as t;
+
+$component: "#{base.$prefix}-bottom-sheet";
+
+// -----------------------------------------------------------------------------
+// Bottom sheet (Compose SheetBottomTokens and BottomSheetDefaults)
+//
+// A surface anchored to the bottom edge: surface-container-low, extra-large
+// corners on the top two only, elevation level 1, and a 32x4dp handle that says
+// it can be dragged. It stops growing at 640dp and centres itself, so it does
+// not stretch across a desktop window.
+// -----------------------------------------------------------------------------
+.#{$component} {
+    position: fixed;
+    inset: 0;
+    z-index: v.z-index("modal");
+    display: flex;
+    align-items: flex-end;
+    justify-content: center;
+
+    // A standard sheet leaves the page usable, so the layer itself must not
+    // swallow clicks meant for what is behind it
+    pointer-events: none;
+
+    &--scrim-visible,
+    &--partial,
+    &--expanded {
+        pointer-events: auto;
+    }
+
+    // The scrim, on modal sheets only (ScrimTokens.ContainerOpacity)
+    &-scrim {
+        position: absolute;
+        inset: 0;
+        background-color: t.alpha("scrim", 0.32);
+        opacity: 0;
+        visibility: hidden;
+        transition:
+            opacity v.motion("duration-medium1") v.motion("easing-emphasized"),
+            visibility v.motion("duration-medium1") v.motion("easing-emphasized");
+    }
+
+    // The sheet itself
+    &-container {
+        position: relative;
+        width: 100%;
+        max-width: 640px; // BottomSheetDefaults.SheetMaxWidth
+        max-height: 100%;
+        display: flex;
+        flex-direction: column;
+        box-sizing: border-box;
+        pointer-events: auto;
+
+        background-color: t.color("surface-container-low"); // DockedContainerColor
+        color: t.color("on-surface");
+
+        // CornerExtraLargeTop: the bottom edge meets the screen, so it is square
+        border-start-start-radius: v.shape("extra-large");
+        border-start-end-radius: v.shape("extra-large");
+        @include m.elevation(1); // DockedStandardContainerElevation
+
+        // Hidden by default: translated fully out of view
+        transform: translateY(100%);
+        transition: transform v.motion("duration-medium2") v.motion("easing-emphasized");
+
+        &:focus {
+            outline: none;
+        }
+
+        // Focus ring uses the secondary role (FocusIndicatorColor)
+        &:focus-visible {
+            outline: 3px solid t.color("secondary");
+            outline-offset: -3px;
+        }
+    }
+
+    // The 32x4dp bar (DockedDragHandleWidth / DockedDragHandleHeight)
+    &-handle {
+        flex: 0 0 auto;
+        width: 32px;
+        height: 4px;
+        margin: 16px auto;
+        border-radius: v.shape("extra-large"); // BottomSheetDefaults.DragHandle shape
+        background-color: t.color("on-surface-variant"); // DockedDragHandleColor
+        cursor: grab;
+        touch-action: none; // the sheet handles the gesture, not the browser
+
+        &:active {
+            cursor: grabbing;
+        }
+    }
+
+    &-header {
+        flex: 0 0 auto;
+        padding: 0 24px 16px;
+    }
+
+    &-title {
+        margin: 0;
+        color: t.color("on-surface");
+        @include m.typography("headline-small");
+    }
+
+    &-content {
+        flex: 1 1 auto;
+        min-height: 0;
+        overflow-y: auto;
+        padding: 0 24px 24px;
+        @include m.typography("body-medium");
+        color: t.color("on-surface-variant");
+    }
+
+    // ---------------------------------------------------------------------
+    // States
+    // ---------------------------------------------------------------------
+    &--partial {
+        .#{$component}-container {
+            // the peek height, showing what the sheet holds without covering
+            // the page (BottomSheetDefaults.SheetPeekHeight and its content)
+            transform: translateY(0);
+            max-height: 50%;
+        }
+
+        .#{$component}-scrim {
+            opacity: 1;
+            visibility: visible;
+        }
+    }
+
+    &--expanded {
+        .#{$component}-container {
+            transform: translateY(0);
+            max-height: 100%;
+            // level with the top of the screen, the corners square off
+            // (DockedMinimizedContainerShape is CornerNone)
+            &:where(.#{$component}--full-height *) {
+                border-start-start-radius: 0;
+                border-start-end-radius: 0;
+            }
+        }
+
+        .#{$component}-scrim {
+            opacity: 1;
+            visibility: visible;
+        }
+    }
+
+    // A standard sheet has no scrim and does not block the page
+    &--standard {
+        pointer-events: none;
+
+        .#{$component}-container {
+            pointer-events: auto;
+        }
+    }
+
+    @include m.reduced-motion {
+        .#{$component}-container,
+        .#{$component}-scrim {
+            transition: none;
+        }
+    }
+}

package/src/styles/components/_button.scss

@@ -64,7 +64,7 @@ $content-color: (
   height: v.button('height-s');
   padding: 0 v.button('padding-s');
   border: none;
-  border-radius: var(--#{base.$prefix}-button-shape, v.button('border-radius'));
+  border-radius: var(--#{base.$prefix}-button-shape, v.button('shape-round-s'));
   background-color: transparent;
   color: inherit;
   font: inherit;
@@ -183,6 +183,10 @@ $content-color: (
         height: v.button('icon-size-#{$size}');
       }
 
+      // Round shape at rest: half the height, so the pressed shape is a
+      // morph rather than a snap. See shape-round-* in $button.
+      border-radius: var(--#{base.$prefix}-button-shape, v.button('shape-round-#{$size}'));
+
       // Square shape at rest
       &.#{$component}--square {
         border-radius: var(--#{base.$prefix}-button-shape, v.button('shape-square-#{$size}'));
@@ -434,8 +438,10 @@ $content-color: (
         }
       }
 
-      &.#{$component}--square {
-        border-radius: var(--#{base.$prefix}-button-shape-selected, v.button('border-radius'));
+      @each $size in $sizes {
+        &.#{$component}--square.#{$component}--#{$size} {
+          border-radius: var(--#{base.$prefix}-button-shape-selected, v.button('shape-round-#{$size}'));
+        }
       }
 
       @each $size in $sizes {

package/src/styles/components/_card.scss

@@ -17,7 +17,11 @@ $component: '#{base.$prefix}-card';
   background-color: t.color('surface');
   color: t.color('on-surface');
   overflow: hidden;
-  width: v.card('width'); // Use card width variable
+  // No width of its own. A card fills the column, grid cell or flex track it
+  // is placed in, as the M3 card specs describe. This used to be a hard 344px,
+  // which meant every card had to opt out of its own component to sit in a
+  // layout. The sizes are still available as modifiers below for the cases
+  // that genuinely want them.
   --card-elevation: 0;
   
   // Typography - use mixin
@@ -57,47 +61,89 @@ $component: '#{base.$prefix}-card';
   
   // === Variants - use proper theme colors ===
   
-  // Elevated variant
+  // Elevated: ElevatedCardTokens. Level 1 at rest, 2 hovered, back to 1 when
+  // pressed or focused, 4 while dragged.
   &--elevated {
     background-color: t.color('surface-container-low');
-    @include m.elevation(1); // Use elevation mixin
-    
+    @include m.elevation(1);
+
     &:hover.#{$component}--interactive {
-      @include m.elevation(2); // Use elevation mixin for hover state
+      @include m.elevation(2);
     }
 
     &:active.#{$component}--interactive {
-      @include m.state-layer(t.color('on-surface'), 'pressed'); // Use state-layer mixin
+      @include m.elevation(1);
+      @include m.state-layer(t.color('on-surface'), 'pressed');
+    }
+
+    &.#{$component}--dragging {
+      @include m.elevation(4); // DraggedContainerElevation
+    }
+
+    &.#{$component}--state-disabled {
+      background-color: t.color('surface'); // DisabledContainerColor
+      @include m.elevation(1); // it keeps its elevation while disabled
     }
   }
-  
-  // Filled variant
+
+  // Filled: FilledCardTokens. Flat at rest, and it rises to level 1 on hover,
+  // which is the only elevation it ever takes.
   &--filled {
     background-color: t.color('surface-container-highest');
-    @include m.elevation(0); // No elevation
-    
+    @include m.elevation(0);
+
     &:hover.#{$component}--interactive {
+      @include m.elevation(1); // HoverContainerElevation
       @include m.state-layer(t.color('on-surface'), 'hover');
     }
 
     &:active.#{$component}--interactive {
+      @include m.elevation(0);
       @include m.state-layer(t.color('on-surface'), 'pressed');
     }
+
+    &.#{$component}--dragging {
+      @include m.elevation(3); // DraggedContainerElevation
+    }
+
+    &.#{$component}--state-disabled {
+      background-color: t.color('surface-variant'); // DisabledContainerColor
+    }
   }
-  
-  // Outlined variant
+
+  // Outlined: OutlinedCardTokens. The outline is outline-variant at rest and
+  // hovered, and on-surface once focused, which is the only state that changes
+  // it. It used to sit at the darker `outline` and lighten on hover, which is
+  // the wrong role and the wrong direction.
   &--outlined {
-    border: 1px solid t.color('outline');
+    border: 1px solid t.color('outline-variant'); // OutlineColor
     background-color: t.color('surface');
-    @include m.elevation(0); // No elevation
-    
+    @include m.elevation(0);
+
     &:hover.#{$component}--interactive {
+      @include m.elevation(1); // HoverContainerElevation
       @include m.state-layer(t.color('on-surface'), 'hover');
-      border-color: t.color('outline-variant');
+      border-color: t.color('outline-variant'); // HoverOutlineColor
+    }
+
+    &:focus-visible,
+    &.#{$component}--focused {
+      border-color: t.color('on-surface'); // FocusOutlineColor
     }
 
     &:active.#{$component}--interactive {
+      @include m.elevation(0);
       @include m.state-layer(t.color('on-surface'), 'pressed');
+      border-color: t.color('outline-variant'); // PressedOutlineColor
+    }
+
+    &.#{$component}--dragging {
+      @include m.elevation(3); // DraggedContainerElevation
+    }
+
+    &.#{$component}--state-disabled {
+      // DisabledOutlineColor at DisabledOutlineOpacity
+      border-color: t.alpha('outline', 0.12);
     }
   }
   
@@ -109,10 +155,22 @@ $component: '#{base.$prefix}-card';
     user-select: none;
   }
   
-  // Full-width cards
+  // Widths, for the cases that want a fixed one. A card has none by default.
   &--full-width {
     width: 100%;
   }
+
+  &--small {
+    width: v.card('width-small');
+  }
+
+  &--medium {
+    width: v.card('width-medium');
+  }
+
+  &--large {
+    width: v.card('width-large');
+  }
   
   // === Sub-components ===
   
@@ -310,9 +368,10 @@ $component: '#{base.$prefix}-card';
     pointer-events: none;
   }
   
+  // Elevation while dragged differs by variant, so it is set with each of them
+  // above. The 0.9 opacity that used to be here is in no token.
   &--dragging {
-    @include m.elevation(4); // Use elevation mixin
-    opacity: 0.9;
+    cursor: grabbing;
   }
   
   // Loading overlay

package/src/styles/components/_menu.scss

@@ -59,6 +59,24 @@ $component: "#{$prefix}-menu";
         z-index: f.get-z-index("menu") + 1;
     }
 
+    // A run of items between gaps. The element is presentational: it exists so
+    // a gap can split the menu into separate surfaces in the vertical variant.
+    // A standard menu is one surface, so here a group is only spacing.
+    &-group {
+        display: block;
+        list-style: none;
+
+        > ul {
+            margin: 0;
+            padding: 0;
+            list-style: none;
+        }
+
+        + .#{$component}-group {
+            margin-top: 8px;
+        }
+    }
+
     // List container
     &-list {
         margin: 0;
@@ -331,7 +349,11 @@ $component: "#{$prefix}-menu";
         border-radius: v.shape("large");
         background-color: var(--#{$prefix}-menu-container);
         color: var(--#{$prefix}-menu-label);
-        padding: 8px;
+        // GroupPadding. The vertical menu has no container spacing token of
+        // its own: it is made of groups, and a menu with no gaps is one group,
+        // so the container's inset is the group's. The 8dp that was here is
+        // the horizontal variant's ContainerTopSpace, which does not apply.
+        padding: 4px;
 
         // Vibrant: tertiary-based, more prominent, to be used sparingly
         &.#{$component}--vibrant {
@@ -443,14 +465,78 @@ $component: "#{$prefix}-menu";
             }
         }
 
-        // A grouped menu separates its runs of items with a divider; the gap
-        // treatment the spec shows is not offered on the web
+        // A grouped menu separates its runs of items two ways, as the spec
+        // shows: a divider line across one surface, or a gap
         // (m3.material.io menu guidelines, "Gaps & dividers")
         .#{$component}-divider {
             margin: 6px 0;
         }
     }
 
+    // -------------------------------------------------------------------------
+    // The gap separator: the menu stops being one surface and each group
+    // becomes its own, keeping the container's shape and elevation.
+    //
+    // The measurements come from the vertical menu specimen on
+    // m3.material.io/components/menus, which the guidelines show but do not
+    // give numbers for. Read off that image at its 2px-per-dp scale: a 44dp
+    // item, a 16dp group corner, 4dp of padding inside each group and 2dp
+    // between them, so two items either side of a boundary sit 10dp apart.
+    // The group hugs its items more tightly than the whole-menu container
+    // does, which is what keeps a gap from reading as a chasm.
+    // -------------------------------------------------------------------------
+    &--vertical:has(.#{$component}-group) {
+        background-color: transparent;
+        box-shadow: none;
+        padding: 0;
+
+        // Each group casts its own shadow. The container clips so that item
+        // backgrounds stay inside its rounded corners, but there is no
+        // container here to stay inside, and clipping would cut the shadows
+        // off square.
+        overflow: visible;
+
+        .#{$component}-list {
+            overflow: visible;
+            // the separator is the 2dp the variant already puts between items
+            gap: 2px;
+        }
+
+        .#{$component}-group {
+            background-color: var(--#{$prefix}-menu-container);
+            padding: 4px; // GroupPadding
+            @include m.elevation(2);
+
+            // A corner facing a gap is the group's own shape, 8dp
+            // (SegmentedMenuTokens.GroupShape). Only the outside of the menu
+            // keeps the 16dp container shape, so the run of groups reads as
+            // one menu that has been cut, rather than as loose cards.
+            border-radius: v.shape("small");
+
+            &:first-child {
+                border-start-start-radius: v.shape("large"); // ContainerShape
+                border-start-end-radius: v.shape("large");
+            }
+
+            &:last-child {
+                border-end-start-radius: v.shape("large");
+                border-end-end-radius: v.shape("large");
+            }
+
+            // its own margin would add to the list gap
+            + .#{$component}-group {
+                margin-top: 0;
+            }
+
+            // and the items inside keep the 2dp separation of the variant
+            > ul {
+                display: flex;
+                flex-direction: column;
+                gap: 2px;
+            }
+        }
+    }
+
     // -------------------------------------------------------------------------
     // Shape morph on the container: while a submenu is open, the menu that
     // opened it steps back to an 8dp corner and the active one takes 24dp

package/src/styles/components/_segmented-button.scss

@@ -27,7 +27,6 @@ $component: "#{base.$prefix}-segmented-button";
     position: relative;
     display: inline-flex;
     align-items: stretch;
-    border-radius: 20px;
     border: 1px solid t.color("outline");
     background-color: transparent;
     overflow: hidden;
@@ -95,7 +94,6 @@ $component: "#{base.$prefix}-segmented-button";
         background-color: transparent;
         border: none;
         position: relative;
-        border-radius: 0 !important; // Override button's border-radius completely
         min-width: 48px;
         height: 100%;
         color: t.color("on-surface");
@@ -105,12 +103,16 @@ $component: "#{base.$prefix}-segmented-button";
         // Use CSS variables for dynamic sizing
         padding: 0 var(--segment-padding-x);
 
-        // CRITICAL: Override button's active state border-radius changes
-        // Segmented button segments must maintain their shape
-        &:active,
-        &.#{base.$prefix}-button--active {
-            border-radius: 0 !important;
-        }
+        // Corner shapes are handed to the button through its own shape hooks
+        // rather than declared over the top of it. The button reads every one
+        // of its radii through these, resting, pressed and selected alike, so
+        // one declaration per position holds the segment's shape in every
+        // state. Overriding border-radius directly meant re-stating each
+        // corner for each state and each variant, and losing to the button
+        // stylesheet without !important on all of it.
+        --#{base.$prefix}-button-shape: 0;
+        --#{base.$prefix}-button-shape-pressed: 0;
+        --#{base.$prefix}-button-shape-selected: 0;
 
         // Icon-only segments
         &.#{base.$prefix}-button--circular {
@@ -124,50 +126,34 @@ $component: "#{base.$prefix}-segmented-button";
                 var(--segment-padding-icon-text-left);
         }
 
-        // First segment - rounded left corners only
+        // The container is one rounded shape, so only its ends round off
+        $round: var(--segment-border-radius);
+
+        // First segment: left corners only
         &:first-child {
-            border-top-left-radius: var(--segment-border-radius) !important;
-            border-bottom-left-radius: var(--segment-border-radius) !important;
-
-            &:active,
-            &.#{base.$prefix}-button--active {
-                border-top-left-radius: var(--segment-border-radius) !important;
-                border-bottom-left-radius: var(
-                    --segment-border-radius
-                ) !important;
-            }
+            --#{base.$prefix}-button-shape: #{$round} 0 0 #{$round};
+            --#{base.$prefix}-button-shape-pressed: #{$round} 0 0 #{$round};
+            --#{base.$prefix}-button-shape-selected: #{$round} 0 0 #{$round};
         }
 
-        // Last segment - rounded right corners only
+        // Last segment: right corners only
         &:last-child {
-            border-top-right-radius: var(--segment-border-radius) !important;
-            border-bottom-right-radius: var(--segment-border-radius) !important;
-
-            &:active,
-            &.#{base.$prefix}-button--active {
-                border-top-right-radius: var(
-                    --segment-border-radius
-                ) !important;
-                border-bottom-right-radius: var(
-                    --segment-border-radius
-                ) !important;
-            }
+            --#{base.$prefix}-button-shape: 0 #{$round} #{$round} 0;
+            --#{base.$prefix}-button-shape-pressed: 0 #{$round} #{$round} 0;
+            --#{base.$prefix}-button-shape-selected: 0 #{$round} #{$round} 0;
         }
 
-        // Single segment - all corners rounded
+        // A lone segment is the whole container
         &:only-child {
-            border-radius: var(--segment-border-radius) !important;
-
-            &:active,
-            &.#{base.$prefix}-button--active {
-                border-radius: var(--segment-border-radius) !important;
-            }
+            --#{base.$prefix}-button-shape: #{$round};
+            --#{base.$prefix}-button-shape-pressed: #{$round};
+            --#{base.$prefix}-button-shape-selected: #{$round};
         }
 
         // Reset button ::before pseudo-element (used for state layers)
         // This prevents button hover effects from interfering
         &::before {
-            content: none !important;
+            content: none;
         }
 
         // Hover state (MD3: 8% state layer with on-surface color over surface)
@@ -254,7 +240,7 @@ $component: "#{base.$prefix}-segmented-button";
 
             // Reset variant ::before pseudo-element (state layers)
             &::before {
-                content: none !important;
+                content: none;
             }
 
             // Override variant hover states
@@ -277,34 +263,6 @@ $component: "#{base.$prefix}-segmented-button";
                 box-shadow: none;
             }
 
-            &:active,
-            &.#{base.$prefix}-button--active {
-                border-radius: 0 !important;
-            }
-
-            &:first-child {
-                &:active,
-                &.#{base.$prefix}-button--active {
-                    border-top-left-radius: var(
-                        --segment-border-radius
-                    ) !important;
-                    border-bottom-left-radius: var(
-                        --segment-border-radius
-                    ) !important;
-                }
-            }
-
-            &:last-child {
-                &:active,
-                &.#{base.$prefix}-button--active {
-                    border-top-right-radius: var(
-                        --segment-border-radius
-                    ) !important;
-                    border-bottom-right-radius: var(
-                        --segment-border-radius
-                    ) !important;
-                }
-            }
         }
     }
 
@@ -345,7 +303,7 @@ $component: "#{base.$prefix}-segmented-button";
 
             // Reset variant ::before pseudo-element
             &::before {
-                content: none !important;
+                content: none;
             }
 
             // Override variant hover states for selected