@expressivecss/expressive 0.15.0 → 0.16.0

package/src/sass/utilities/_helpers.scss

@@ -1,3 +1,6 @@
+@use "sass:map";
+@use "../abstracts" as *;
+
 // Small single-purpose classes a page author applies deliberately.
 //
 // Anything here must be one job, one class, and independent of any component.
@@ -6,40 +9,139 @@
 
 // Positioning
 .valign-wrapper { display: flex; align-items: center; }
+.relative { position: relative; }
+.sticky-top { position: sticky; top: 0; }
+// Not a bare `.fixed`: the navigation bar, toolbar and table of contents use
+// that as a modifier, and a utility would override them. No z-index either;
+// a fixed element takes a --expressive-z-* value from the page. Static comes
+// last so it beats .relative and .sticky-top on the same element.
+.position-absolute { position: absolute; }
+.position-fixed { position: fixed; }
+.position-static { position: static; }
+.inset-0 { inset: 0; }
+.top-0 { top: 0; }
+.bottom-0 { bottom: 0; }
+.start-0 { inset-inline-start: 0; }
+.end-0 { inset-inline-end: 0; }
+
+// Display and flex layout. One declaration each; combine on the container or child,
+// and pair with .gap-* from _spacing.scss for the space between items.
+//
+// Every class in this map also comes with a window-size prefix, emitted at
+// the end of this file: `.expanded:flex-row` applies from Expanded up, the
+// way the grid's `l6` does. `.inline` is the checkbox and radio row, so the
+// display utility for it is missing on purpose.
+//
+// The line clamps set display too, so put them on a child of a flex or grid
+// container, never on the container. Overflow clips at the padding box, so
+// block-end padding on a clamped element shows the top of the next line.
+$_clamp: (overflow: hidden, display: -webkit-box, -webkit-box-orient: vertical);
+
+$_layout: (
+  "block": (display: block),
+  "inline-block": (display: inline-block),
+  "flex": (display: flex),
+  "inline-flex": (display: inline-flex),
+  "grid": (display: grid),
+  "flex-row": (flex-direction: row),
+  "flex-column": (flex-direction: column),
+  "flex-wrap": (flex-wrap: wrap),
+  "flex-nowrap": (flex-wrap: nowrap),
+  "justify-start": (justify-content: flex-start),
+  "justify-center": (justify-content: center),
+  "justify-end": (justify-content: flex-end),
+  "justify-between": (justify-content: space-between),
+  "justify-around": (justify-content: space-around),
+  "justify-evenly": (justify-content: space-evenly),
+  "align-start": (align-items: flex-start),
+  "align-center": (align-items: center),
+  "align-end": (align-items: flex-end),
+  "align-stretch": (align-items: stretch),
+  "align-baseline": (align-items: baseline),
+  // Child sizing: shorthands precede shrink-only overrides.
+  "flex-1": (flex: 1 1 0),
+  "flex-none": (flex: none),
+  "flex-initial": (flex: 0 1 auto),
+  "shrink-0": (flex-shrink: 0),
+  "shrink-1": (flex-shrink: 1),
+  // Child self-alignment. .self-auto hands a child back to the parent's
+  // align-items, so a prefix can undo a smaller window's alignment.
+  "self-auto": (align-self: auto),
+  "self-start": (align-self: flex-start),
+  "self-center": (align-self: center),
+  "self-end": (align-self: flex-end),
+  "self-stretch": (align-self: stretch),
+  // Child order moves a child on screen only: Tab and reading order still
+  // follow the source. .order-none puts it back in its source position.
+  "order-first": (order: -1),
+  "order-last": (order: 1),
+  "order-none": (order: 0),
+  "start-align": (text-align: start),
+  "center-align": (text-align: center),
+  "end-align": (text-align: end),
+  "line-clamp-1": map.merge($_clamp, (-webkit-line-clamp: 1, line-clamp: 1)),
+  "line-clamp-2": map.merge($_clamp, (-webkit-line-clamp: 2, line-clamp: 2)),
+  "line-clamp-3": map.merge($_clamp, (-webkit-line-clamp: 3, line-clamp: 3)),
+  "line-clamp-none": (overflow: visible, display: block, -webkit-box-orient: horizontal, -webkit-line-clamp: unset, line-clamp: unset),
+);
+
+@mixin _declarations($map) {
+  @each $property, $value in $map {
+    #{$property}: $value;
+  }
+}
+
+@each $name, $declarations in $_layout {
+  .#{$name} { @include _declarations($declarations); }
+}
 
-// Flex layout. One declaration each; combine on the container, and pair with
-// .gap-* from _spacing.scss for the space between items. Row direction and
-// start alignment are the flex defaults, so only the overrides get a class.
-.flex { display: flex; }
-.inline-flex { display: inline-flex; }
-.flex-column { flex-direction: column; }
-.flex-wrap { flex-wrap: wrap; }
-.justify-start { justify-content: flex-start; }
-.justify-center { justify-content: center; }
-.justify-end { justify-content: flex-end; }
-.justify-between { justify-content: space-between; }
-.align-start { align-items: flex-start; }
-.align-center { align-items: center; }
-.align-end { align-items: flex-end; }
-.align-stretch { align-items: stretch; }
-.flex-1 { flex: 1 1 0; }
-.flex-none { flex: none; }
+.inline-grid { display: inline-grid; }
+
+// As many columns as fit, each at least --grid-column-min wide (set it here or
+// on an ancestor). Empty tracks stay, so a short last row keeps the column
+// width, and a container narrower than the minimum gets one column. The
+// column count follows the container, so there are no prefixed copies; pair
+// with .gap-*.
+.grid-auto-fill {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--grid-column-min, #{rem(240px)})), 1fr));
+}
+
+.contents { display: contents; }
 
 // Allow flex and grid children to shrink around their content.
 .min-w-0 { min-width: 0; }
 .min-h-0 { min-height: 0; }
 
+// Make the element a query container. Horizontal cards and description lists
+// inside it stack when it is narrower than 600px, whatever the window size.
+// Inline-size containment stops the element's width depending on its
+// content, so use it on a wrapper that fills its parent, not on a
+// shrink-to-fit box.
+.query-container { container-type: inline-size; }
+
+// Fill the containing block, or never overflow it.
+.w-full { width: 100%; }
+.h-full { height: 100%; }
+.max-w-full { max-width: 100%; }
+
+// Fixed proportions. With an explicit width the height follows; on an <img>
+// or <video>, pair with .object-cover or .object-contain.
+.aspect-1x1 { aspect-ratio: 1; }
+.aspect-4x3 { aspect-ratio: 4 / 3; }
+.aspect-16x9 { aspect-ratio: 16 / 9; }
+.object-cover { object-fit: cover; }
+.object-contain { object-fit: contain; }
+
 // Scrolling and clipping without changing the element's display or size.
 .overflow-x-auto { overflow-x: auto; }
 .overflow-y-auto { overflow-y: auto; }
 .overflow-hidden { overflow: hidden; }
 
-// Text alignment
+// Text alignment. start, center and end are in $_layout above; the physical
+// pair stays for text that must not mirror.
 .left-align { text-align: left; }
 .right-align { text-align: right }
-.center-align { text-align: center; }
-.start-align { text-align: start; }
-.end-align { text-align: end; }
 
 // Dividers
 .divider {
@@ -48,19 +150,63 @@
   background-color: var(--md-sys-color-outline-variant);
 }
 
+// Borders and corners. `.border` and `.rounded` are card and button variants,
+// so the all-sides border is `.bordered` and the corner classes use the M3
+// corner names. Sides are logical, so start and end mirror in RTL.
+.bordered { border: 1px solid var(--md-sys-color-outline-variant); }
+.border-top { border-top: 1px solid var(--md-sys-color-outline-variant); }
+.border-bottom { border-bottom: 1px solid var(--md-sys-color-outline-variant); }
+.border-start { border-inline-start: 1px solid var(--md-sys-color-outline-variant); }
+.border-end { border-inline-end: 1px solid var(--md-sys-color-outline-variant); }
+
+@each $step in ("none", "extra-small", "small", "medium", "large", "extra-large", "full") {
+  .corner-#{$step} { border-radius: var(--md-sys-shape-corner-#{$step}); }
+}
+
+// Cut corners: the corner's radius becomes a straight bevel of the same
+// size. .corner-cut cuts one element; the container surfaces below follow
+// --md-sys-shape-corner-family, which corners="cut" switches for a subtree.
+// Round indicators (radios, switches, avatars, .circle) stay round, since
+// a cut 50% radius is a diamond. Browsers without `corner-shape` (Firefox
+// 157) keep rounded corners; a clip-path fallback would cut focus rings and
+// shadows too.
+.corner-cut { corner-shape: bevel; }
+
+:where(
+  article, dialog, menu[id], fieldset, .button:not(.circle), .chip, .alert,
+  .snackbar, .tooltip, .popover, .field.outlined > :is(input, textarea)
+) {
+  corner-shape: var(--md-sys-shape-corner-family);
+}
+
 // Shape and text behaviour
-.no-select { user-select: none; }
 // A FAB is `circle extra` / `circle large`, and its container shape is
 // 16dp rounded corners, not a full round - so the utility skips it. Layer
 // order puts utilities after components, which is why the exclusion has to
 // live here: no selector in `components` can outrank this one.
 .circle:not(.extra, .large) { border-radius: 50%; }
-.center-block { display: block; margin-left: auto; margin-right: auto; }
 .break-words { overflow-wrap: anywhere; }
 .text-nowrap { white-space: nowrap; }
 .text-wrap { white-space: normal; }
+.text-balance { text-wrap-style: balance; }
+.text-pretty { text-wrap-style: pretty; }
 .truncate { display: block; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-.no-padding { padding: 0 !important; }
+
+// Pointer input. Clicks pass through a .pointer-events-none overlay to what
+// lies beneath, and a .pointer-events-auto child takes them back. Neither
+// changes focus or keys: use inert or disabled to block all input.
+.pointer-events-none { pointer-events: none; }
+.pointer-events-auto { pointer-events: auto; }
+.cursor-pointer { cursor: pointer; }
+// Opacity. 38 is M3's disabled-content opacity. Dimming hides nothing from
+// pointers, keyboards or screen readers; use .hide or `hidden` for that.
+@each $step, $value in ("0": 0, "25": 0.25, "38": 0.38, "50": 0.5, "75": 0.75, "100": 1) {
+  .opacity-#{$step} { opacity: $value; }
+}
+
+// Lists without markers or indentation. WebKit drops the list role from a
+// list with `list-style: none`, so the markup adds role="list" back.
+.list-unstyled { list-style: none; padding-inline-start: 0; }
 
 // Responsive media
 img.responsive-img,
@@ -74,14 +220,14 @@ video.responsive-video {
 // element+class pair would beat `.circle` and square the disc off.
 img.responsive-img:not(.circle),
 video.responsive-video {
-  border-radius: 12px;
+  border-radius: var(--md-sys-shape-corner-medium);
 }
 
 .video-container {
   position: relative;
   aspect-ratio: 16 / 9;   // was padding-bottom: 56.25% + height: 0
   overflow: hidden;
-  border-radius: 12px;
+  border-radius: var(--md-sys-shape-corner-medium);
 
   iframe, object, embed {
     position: absolute;
@@ -91,3 +237,14 @@ video.responsive-video {
     border: 0;
   }
 }
+
+// Window-size prefixes for $_layout, mobile first: each applies from that
+// size class up and wins over the unprefixed class, because it comes later
+// in the same layer.
+@each $size in ("medium", "expanded", "large", "extra-large") {
+  @include bp-up($size) {
+    @each $name, $declarations in $_layout {
+      .#{$size}\:#{$name} { @include _declarations($declarations); }
+    }
+  }
+}

package/src/sass/utilities/_index.scss

@@ -8,3 +8,4 @@
 @forward "helpers";          // alignment, flex, truncate, responsive media
 @forward "scroll-area";      // native scrolling with themed scrollbars
 @forward "shapes";           // .shape-pebble, .shape-scallop-6, ... (masks)
+@forward "defer-render";     // skip layout and paint for off-screen rows

package/src/sass/utilities/_scroll-area.scss

@@ -1,5 +1,3 @@
-@use "../abstracts" as *;
-
 // Keep scrolling native; use the current theme for scrollbar colors.
 .scroll-area {
   overflow: auto;

package/src/sass/utilities/_spacing.scss

@@ -1,52 +1,70 @@
+@use "../abstracts" as *;
+
 // Margin, padding and gap scale: .m-3, .pt-2, .px-4, .ms-auto, .gap-2, ...
 //
 // Shortcut x value x direction, all !important so a helper wins over the
 // component it is applied to. Edit the maps here to change the scale.
 
-$spacing-shortcuts: ("margin": "m", "padding": "p") !default;
+$spacing-shortcuts: ("margin": "m", "padding": "p");
 $spacing-directions: (
   "top": "t", "right": "r", "bottom": "b", "left": "l",
   "inline-start": "s", "inline-end": "e"
-) !default;
-$spacing-horizontal: "x" !default;
-$spacing-vertical: "y" !default;
-$spacing-values: ("0": 0, "1": 0.25rem, "2": 0.5rem, "3": 0.75rem, "4": 1rem, "5": 1.5rem, "6": 3rem, "auto": auto) !default;
+);
+$spacing-values: ("0": 0, "1": 0.25rem, "2": 0.5rem, "3": 0.75rem, "4": 1rem, "5": 1.5rem, "6": 3rem, "auto": auto);
 
-@each $property, $shortcut in $spacing-shortcuts{
-  @each $name, $value in $spacing-values{
-    // CSS accepts auto margins, but not auto padding.
-    @if $property != "padding" or $value != auto {
-      // All direction spacing
-      .#{$shortcut}-#{$name}{
-        #{$property}: $value !important;
-      }
-      // Physical and logical side spacing
-      @each $direction, $suffix in $spacing-directions{
-        .#{$shortcut}#{$suffix}-#{$name}{
-          #{$property}-#{$direction}: $value !important
+// $prefix is "" for the base classes, or an escaped window size such as
+// medium\: for the prefixed ones at the end of this file.
+@mixin _margin-and-padding($prefix: "") {
+  @each $property, $shortcut in $spacing-shortcuts{
+    @each $name, $value in $spacing-values{
+      // CSS accepts auto margins, but not auto padding.
+      @if $property != "padding" or $value != auto {
+        // All direction spacing
+        .#{$prefix}#{$shortcut}-#{$name}{
+          #{$property}: $value !important;
         }
-      }
-      // x spacing
-      @if $spacing-horizontal != null{
-         .#{$shortcut}#{$spacing-horizontal}-#{$name}{
-           #{$property}-left: $value !important;
-           #{$property}-right: $value !important;
-         }
-      }
-      // y spacing
-      @if $spacing-vertical != null{
-        .#{$shortcut}#{$spacing-vertical}-#{$name}{
-          #{$property}-top: $value !important;
-          #{$property}-bottom: $value !important;
+        // Physical and logical side spacing
+        @each $direction, $suffix in $spacing-directions{
+          // The prefixed sets skip physical left and right; start and end
+          // cover them and mirror in RTL.
+          @if $prefix == "" or ($direction != "left" and $direction != "right") {
+            .#{$prefix}#{$shortcut}#{$suffix}-#{$name}{
+              #{$property}-#{$direction}: $value !important
+            }
+          }
+        }
+        .#{$prefix}#{$shortcut}x-#{$name}{
+          #{$property}-inline: $value !important;
+        }
+        .#{$prefix}#{$shortcut}y-#{$name}{
+          #{$property}-block: $value !important;
         }
       }
     }
   }
 }
 
-// Gap on the same scale for flex and grid containers: .gap-0 ... .gap-6.
-@each $name, $value in $spacing-values {
-  @if $name != "auto" {
-    .gap-#{$name} { gap: $value !important; }
+@mixin _gaps($prefix: "") {
+  // Axis rules follow every shorthand value so they win at the same breakpoint.
+  @each $class, $property in ("gap": "gap", "gap-x": "column-gap", "gap-y": "row-gap") {
+    @each $name, $value in $spacing-values {
+      @if $name != "auto" {
+        .#{$prefix}#{$class}-#{$name} { #{$property}: $value !important; }
+      }
+    }
+  }
+}
+
+@include _margin-and-padding;
+@include _gaps;
+
+// The margin, padding and gap scales with window-size prefixes, like the
+// layout classes in _helpers.scss: .expanded:p-5 and .expanded:gap-5 apply
+// from Expanded up. Later in the sheet than the base classes, and every one
+// is !important, so the prefixed class wins from its size class up.
+@each $size in ("medium", "expanded", "large", "extra-large") {
+  @include bp-up($size) {
+    @include _margin-and-padding("#{$size}\\:");
+    @include _gaps("#{$size}\\:");
   }
 }

package/src/sass/utilities/_typescale.scss

@@ -20,7 +20,7 @@ $typescale-roles: (
   "body-large", "body-medium", "body-small",
   "label-large", "label-medium", "label-small",
   "title-large", "title-medium", "title-small"
-) !default;
+);
 
 @each $role in $typescale-roles {
   .#{$role} {
@@ -28,6 +28,13 @@ $typescale-roles: (
   }
 }
 
+// The emphasized counterpart of each role: the same type, heavier.
+@each $role in $typescale-roles {
+  .#{$role}-emphasized {
+    @include typescale($role, $emphasized: true);
+  }
+}
+
 // Emphasis and case. One job each, independent of the type role.
 .italic { font-style: italic; }
 .bold { font-weight: 500; }

package/src/sass/utilities/_visibility.scss

@@ -1,98 +1,69 @@
 @use "../abstracts" as *;
 
-// Showing and hiding by the exact M3 window size classes.
-// The older small/med/xxl names remain aliases for compatibility.
+// Showing and hiding by the exact M3 window size classes. The two
+// `med-and-*` hide classes have no M3-named twin and stay as they are.
 
 .hide { display: none !important; }
 
-// Hidden from sight, still announced: a visible label's longer twin, an
-// icon-only control's name, a live region's text. Important for the same
-// reason `.hide` is.
-.visually-hidden,
-.visually-hidden-focusable:not(:focus-within) { @include visually-hidden(true); }
-
-.hide-on-compact-only,
-.hide-on-small-only,
-.hide-on-small-and-down {
-  @include bp-down("medium") { display: none !important; }
-}
-
-.hide-on-med-and-down {
-  @include bp-down("expanded") { display: none !important; }
-}
-
-.hide-on-med-and-up {
-  @include bp-up("medium") { display: none !important; }
-}
-
-.hide-on-medium-only,
-.hide-on-med-only {
-  @include bp-between("medium", "expanded") {
-    display: none !important;
+// .hide from a window size up, like the other prefixed helpers. Mobile first,
+// so there is no prefixed show: pair it with a hide-on-* class instead.
+@each $size in ("medium", "expanded", "large", "extra-large") {
+  .#{$size}\:hide {
+    @include bp-up($size) { display: none !important; }
   }
 }
 
-.hide-on-expanded-only {
-  @include bp-between("expanded", "large") {
-    display: none !important;
-  }
-}
-
-.hide-on-expanded-and-up {
-  @include bp-up("expanded") { display: none !important; }
-}
-
-.hide-on-large-only {
-  @include bp-between("large", "extra-large") {
-    display: none !important;
-  }
+// Print. .hide-on-print drops a screen-only control from paper; .print-only
+// is the reverse, for a printed footer or a QR code beside a link.
+.hide-on-print {
+  @media print { display: none !important; }
 }
 
-.hide-on-extra-large-only,
-.hide-on-xxl-only {
-  @include bp-up("extra-large") { display: none !important; }
+.print-only {
+  @media screen { display: none !important; }
 }
 
-.show-on-compact,
-.show-on-small {
-  @include bp-down("medium") { display: block !important; }
-}
+// Hidden from sight, still announced: a visible label's longer twin, an
+// icon-only control's name, a live region's text. Important for the same
+// reason `.hide` is.
+.visually-hidden,
+.visually-hidden-focusable:not(:focus-within) { @include visually-hidden(true); }
 
-.show-on-medium {
-  @include bp-between("medium", "expanded") {
-    display: block !important;
+// From the $from window size up to, not including, $to. A null end is open.
+@mixin _window($from, $to) {
+  @if not $from {
+    @include bp-down($to) { @content; }
+  } @else if not $to {
+    @include bp-up($from) { @content; }
+  } @else {
+    @include bp-between($from, $to) { @content; }
   }
 }
 
-.show-on-expanded {
-  @include bp-between("expanded", "large") {
-    display: block !important;
+// Class, first window size, first size past the range, display.
+@each $class, $from, $to, $display in (
+  ("hide-on-compact-only",     null,          "medium",      none),
+  ("hide-on-med-and-down",     null,          "expanded",    none),
+  ("hide-on-med-and-up",       "medium",      null,          none),
+  ("hide-on-medium-only",      "medium",      "expanded",    none),
+  ("hide-on-expanded-only",    "expanded",    "large",       none),
+  ("hide-on-expanded-and-up",  "expanded",    null,          none),
+  ("hide-on-large-only",       "large",       "extra-large", none),
+  ("hide-on-extra-large-only", "extra-large", null,          none),
+  ("show-on-compact",          null,          "medium",      block),
+  ("show-on-medium",           "medium",      "expanded",    block),
+  ("show-on-expanded",         "expanded",    "large",       block),
+  ("show-on-expanded-and-up",  "expanded",    null,          block),
+  ("show-on-large",            "large",       "extra-large", block),
+  ("show-on-extra-large",      "extra-large", null,          block),
+  ("show-on-medium-and-up",    "medium",      null,          block),
+  ("show-on-medium-and-down",  null,          "expanded",    block),
+) {
+  .#{$class} {
+    @include _window($from, $to) { display: $display !important; }
   }
 }
 
-.show-on-expanded-and-up {
-  @include bp-up("expanded") { display: block !important; }
-}
-
-.show-on-large {
-  @include bp-between("large", "extra-large") {
-    display: block !important;
-  }
-}
-
-.show-on-extra-large,
-.show-on-xxl {
-  @include bp-up("extra-large") { display: block !important; }
-}
-
-.show-on-medium-and-up {
-  @include bp-up("medium") { display: block !important; }
-}
-
-.show-on-medium-and-down {
-  @include bp-down("expanded") { display: block !important; }
-}
-
 // Center text on Compact windows.
 .center-on-small-only {
   @include bp-down("medium") { text-align: center; }

package/src/sass/utilities/_z-depth.scss

@@ -6,13 +6,16 @@
 
 @each $level in map.keys($elevations) {
   .z-depth-#{$level} {
-    @include z-depth($level);
+    // Level 0 exists to cancel a shadow, so it alone stays unconditional.
+    @include z-depth($level, $important: $level == "0");
   }
 }
 
+// A disabled element does not lift. Utilities outrank components, so the
+// disabled card and button rules cannot cancel this shadow themselves.
 .hoverable {
-  transition: box-shadow 0.25s;
-  &:hover {
-    box-shadow: 0 8px 17px 0 rgba(0, 0, 0, 0.2), 0 6px 20px 0 rgba(0, 0, 0, 0.19);
+  transition: box-shadow var(--md-sys-motion-duration-medium1);
+  &:hover:not(:where(#{$expressive-disabled}, :has(> .primary-action[aria-disabled="true"]))) {
+    @include z-depth("3");
   }
 }