@expressivecss/expressive 0.15.0 → 0.16.0

package/src/sass/abstracts/_mixins.scss

@@ -6,6 +6,16 @@
 
 $_state-layers: ("hover", "focus", "pressed", "dragged");
 
+/// A dp size as rem, for a box that holds text or an icon.
+///
+/// Type is set in rem, so raising the browser's default font size or zooming
+/// text only grows the text. A px box around it stays put, and the text spills
+/// out of it or is cut. A rem box grows with its text, and it renders exactly
+/// as before at the default 16px. Borders, gaps and insets stay px.
+@function rem($px) {
+  @return math.div($px, 16px) * 1rem;
+}
+
 /// A state layer opacity, as the percentage `color-mix()` wants.
 ///
 /// The tokens hold numbers (0.08), because an overlay uses one as `opacity`
@@ -23,12 +33,17 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   @return calc(var(--md-sys-state-#{$state}-state-layer-opacity) * 100%);
 }
 
+/// `$color` at the `$state` layer's opacity, mixed over `$base`.
+@function state-layer($color, $state, $base: transparent) {
+  @return color-mix(in oklab, $color state-opacity($state), $base);
+}
+
 
 // Common-button geometry. M3 Expressive's default size is small: 40dp,
 // label-large, corner.full, 16dp inset, 8dp icon gap. The size axis moves
 // those tokens; the style mixins only change color and elevation.
 @mixin btn(
-  $height: var(--md-comp-filled-button-container-height, 40px),
+  $height: var(--md-comp-filled-button-container-height, #{rem(40px)}),
   $border-radius: var(--md-comp-filled-button-container-shape, 9999px),
   $padding-left: var(--md-comp-filled-button-leading-space, 16px),
   $padding-right: var(--md-comp-filled-button-trailing-space, 16px),
@@ -56,21 +71,23 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   user-select: none;
   appearance: none;
   -webkit-tap-highlight-color: transparent;
-  transition: background-color .2s ease-out, box-shadow .2s ease-out;
+  transition: background-color var(--md-sys-motion-duration-short4) ease-out, box-shadow var(--md-sys-motion-duration-short4) ease-out;
 }
 
 // State layers mix the on-color into the container in oklab; the opacities come
 // from md.sys.state via `state-opacity()`. Filled and tonal have no elevation.
 
-// Shared by filled, tonal, outlined and flat. Elevated also moves z-depth.
-@mixin _btn-states($on, $base) {
+// Shared by every style. Elevated also moves z-depth on hover and press.
+@mixin _btn-states($on, $base, $hover-depth: null, $press-depth: null) {
   &:hover {
-    background-color: color-mix(in oklab, #{$on} state-opacity("hover"), #{$base});
+    @if $hover-depth { @include z-depth($hover-depth); }
+    background-color: state-layer($on, "hover", $base);
   }
 
   &:active,
   &:focus {
-    background-color: color-mix(in oklab, #{$on} state-opacity("focus"), #{$base});
+    @if $press-depth { @include z-depth($press-depth); }
+    background-color: state-layer($on, "focus", $base);
   }
 
   @include focus-visible();
@@ -95,18 +112,7 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   background-color: var(--md-sys-color-surface-container-low);
   @include z-depth("1");
 
-  &:hover {
-    @include z-depth("2");
-    background-color: color-mix(in oklab, var(--md-sys-color-primary) state-opacity("hover"), var(--md-sys-color-surface-container-low));
-  }
-
-  &:active,
-  &:focus {
-    @include z-depth("1");
-    background-color: color-mix(in oklab, var(--md-sys-color-primary) state-opacity("focus"), var(--md-sys-color-surface-container-low));
-  }
-
-  @include focus-visible();
+  @include _btn-states(var(--md-sys-color-primary), var(--md-sys-color-surface-container-low), "2", "1");
 }
 
 @mixin btn-outlined {
@@ -148,9 +154,6 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
 // `$important` is for the `.visually-hidden` utility, which has to beat a
 // consumer's own `position` or `padding` the way `.hide` beats their
 // `display`. Component rules leave it off.
-//
-// _navigation-rail.scss carries its own copy, which predates the mixin and
-// omits the margin and white-space; fold it in when it is next touched.
 @mixin visually-hidden($important: false) {
   $flag: null;
   @if $important { $flag: !important; }
@@ -181,28 +184,238 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   }
 }
 
+// The 18dp up arrow on a pseudo-element: Stat and KPI change lines, data
+// table sort buttons. Rotate it 180deg for down.
+@mixin trend-arrow {
+  content: "";
+  flex: none;
+  width: 18px;
+  height: 18px;
+  background-color: currentColor;
+  mask: $trend-arrow center / 18px no-repeat;
+}
+
+// A 48dp icon action in a dialog, pane or side sheet header bar.
+@mixin header-icon-action {
+  flex: 0 0 48px;
+  box-sizing: border-box;
+  width: 48px;
+  height: 48px;
+  min-width: 48px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background-color: transparent;
+  color: var(--md-sys-color-on-surface-variant);
+  box-shadow: none;
+
+  > #{$icon} {
+    font-size: rem(24px);
+    width: rem(24px);
+    height: rem(24px);
+    line-height: rem(24px);
+  }
+
+  &:hover {
+    background-color: state-layer(var(--md-sys-color-on-surface), "hover");
+  }
+
+  @include focus-visible;
+}
+
+// Forced colors repaint every background as Canvas and drop box-shadow, so a
+// state shown only by a fill or a ring disappears. forced-colors-selected marks
+// a selected item with a Highlight outline. forced-colors-fill keeps a drawn
+// shape (an indicator bar, a dot, a glyph drawn as a mask) by opting it out
+// and painting it with a system color.
+@mixin forced-colors-selected {
+  @media (forced-colors: active) {
+    outline: 2px solid Highlight;
+    outline-offset: -2px;
+  }
+}
+
+// A tree branch's chevron, drawn as the row's ::before: it points to the end
+// edge while closed. The row turns it with `transform: none` once the branch
+// opens, and with rotate(90deg) under :dir(rtl). .tree and the tree select
+// share it.
+$_tree-chevron: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M12 15.4 6 9.4 7.4 8l4.6 4.6L16.6 8 18 9.4z'/%3E%3C/svg%3E");
+
+@mixin tree-chevron {
+  content: "";
+  flex: none;
+  width: 20px;
+  height: 20px;
+  background-color: currentColor;
+  mask: $_tree-chevron center / 20px no-repeat;
+  transform: rotate(-90deg);
+  transition: transform var(--md-sys-motion-duration-short3) ease-out;
+}
+
+@mixin forced-colors-fill($color: CanvasText) {
+  @media (forced-colors: active) {
+    forced-color-adjust: none;
+    background-color: $color;
+  }
+}
+
+// A fieldset of round, labeled choices (color swatches, rating): no fieldset
+// chrome, a body-medium legend, and labels whose 4px of padding makes the
+// 48px target. $control is the input the label's focus and disabled states
+// follow.
+@mixin choice-fieldset($radius, $control) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  margin: 0;
+  padding: 0;
+  border: 0;
+
+  > legend {
+    margin-block-end: 4px;
+    padding: 0;
+    color: var(--md-sys-color-on-surface-variant);
+    @include typescale("body-medium");
+  }
+
+  > label {
+    display: inline-flex;
+    gap: 0;
+    min-height: 0;
+    padding: 4px;
+    border-radius: $radius;
+    cursor: pointer;
+
+    &:has(> #{$control}:focus-visible) {
+      @include focus-ring;
+    }
+
+    &:has(> #{$control}:disabled) {
+      opacity: 0.38;
+      cursor: default;
+    }
+  }
+}
+
+// A navigation bar or rail destination stacked over its label: the indicator
+// behind the icon, its hover layer, the active state, and a sibling badge on
+// the upper trailing corner of the 24dp glyph. $prefix names the component
+// tokens (nav-bar, nav-rail); $inset is the destination's top padding. Rules
+// passed as content land between the active state and the badge.
+@mixin nav-destination($prefix, $inset, $transition) {
+  > #{$icon} {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    justify-content: center;
+    box-sizing: border-box;
+    width: var(--md-comp-#{$prefix}-indicator-width);
+    height: var(--md-comp-#{$prefix}-indicator-height);
+    border-radius: var(--md-comp-#{$prefix}-indicator-shape);
+    font-size: var(--md-comp-#{$prefix}-icon-size);
+    color: inherit;
+    transition: $transition;
+  }
+
+  &:hover:not(.active, [aria-current]) > #{$icon} {
+    background-color: state-layer(var(--md-sys-color-on-surface), "hover");
+  }
+
+  &.active,
+  &[aria-current] {
+    color: var(--md-sys-color-on-surface);
+
+    > #{$icon} {
+      background-color: var(--md-comp-#{$prefix}-active-indicator-color);
+      color: var(--md-comp-#{$prefix}-active-color);
+      --md-icon-fill: 1;
+      @include forced-colors-selected;
+    }
+  }
+
+  @content;
+
+  > .badge {
+    position: absolute;
+    z-index: 1;
+    top: calc(#{$inset} + (var(--md-comp-#{$prefix}-indicator-height) - 24px) / 2);
+    inset-inline-start: calc(50% + 12px);
+    transform: translate(-50%, -50%);
+
+    &:dir(rtl) {
+      transform: translate(50%, -50%);
+    }
+  }
+}
+
+// The same destination laid out as a row (bar .horizontal, rail .expanded):
+// the indicator moves from the icon to the whole destination.
+@mixin nav-destination-row($prefix) {
+  > #{$icon} {
+    width: var(--md-comp-#{$prefix}-icon-size);
+    height: var(--md-comp-#{$prefix}-icon-size);
+    border-radius: 0;
+  }
+
+  &:hover:not(.active, [aria-current]) {
+    background-color: state-layer(var(--md-sys-color-on-surface), "hover");
+
+    > #{$icon} {
+      background-color: transparent;
+    }
+  }
+
+  &.active,
+  &[aria-current] {
+    background-color: var(--md-comp-#{$prefix}-active-indicator-color);
+    color: var(--md-comp-#{$prefix}-active-color);
+    @include forced-colors-selected;
+
+    > #{$icon} {
+      background-color: transparent;
+      color: inherit;
+      outline: none;
+    }
+  }
+}
+
 // M3 type role. Every property must name a token tokens/_reference.scss
 // actually defines — a missing var() drops the whole declaration.
-@mixin typescale($role) {
+// $emphasized takes the role's M3 Expressive emphasized weight.
+@mixin typescale($role, $emphasized: false) {
   font-family: var(--md-sys-typescale-#{$role}-font-family-name);
   font-size: var(--md-sys-typescale-#{$role}-font-size);
-  font-weight: var(--md-sys-typescale-#{$role}-font-weight);
+  @if $emphasized {
+    font-weight: var(--md-sys-typescale-emphasized-#{$role}-font-weight);
+  } @else {
+    font-weight: var(--md-sys-typescale-#{$role}-font-weight);
+  }
   line-height: var(--md-sys-typescale-#{$role}-line-height);
   letter-spacing: var(--md-sys-typescale-#{$role}-letter-spacing);
 }
 
+// The <label> row of a radio, checkbox or switch: 48dp touch target, 12dp
+// between control and text, body-large on-surface.
+@mixin selection-control-label($display: flex) {
+  display: $display;
+  align-items: center;
+  gap: 12px;
+  min-height: 48px;
+  margin: 0;
+  cursor: pointer;
+  user-select: none;
+  color: var(--md-sys-color-on-surface);
+  @include typescale("body-large");
+}
+
 /// The state layer some controls draw as a ring rather than an overlay.
 ///
 /// Checkboxes and radio buttons have no room for an overlay pseudo-element, so
 /// they grow a `box-shadow` from the control's edge out to the state layer
 /// size.
 @mixin state-layer-ring($outer, $inner, $color, $state) {
-  box-shadow: 0 0 0 calc((#{$outer} - #{$inner}) / 2)
-    color-mix(
-      in oklab,
-      #{$color} state-opacity($state),
-      transparent
-    );
+  // Interpolated so a quoted color, such as "var(--c)", is written unquoted.
+  box-shadow: 0 0 0 calc((#{$outer} - #{$inner}) / 2) state-layer(#{$color}, $state);
 }
 
 /// The button size tokens for one rung of `$button-sizes`.
@@ -213,20 +426,22 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
 @mixin button-size($name) {
   $s: map.get($button-sizes, $name);
 
-  --md-comp-filled-button-container-height: #{map.get($s, height)};
-  --md-comp-filled-button-icon-size: #{map.get($s, icon)};
+  --md-comp-filled-button-container-height: #{rem(map.get($s, height))};
+  --md-comp-filled-button-icon-size: #{rem(map.get($s, icon))};
   --md-comp-filled-button-leading-space: #{map.get($s, space)};
   --md-comp-filled-button-trailing-space: #{map.get($s, space)};
   --md-comp-filled-button-icon-label-space: #{map.get($s, gap)};
   --md-comp-filled-button-outline-width: #{map.get($s, outline)};
+  --md-comp-filled-button-container-shape-square: #{map.get($s, square)};
+  --md-comp-filled-button-pressed-container-shape: #{map.get($s, pressed)};
 }
 
 /// The icon-button tokens for one rung of `$icon-button-sizes`.
 @mixin icon-button-size($name) {
   $s: map.get($icon-button-sizes, $name);
 
-  --md-comp-icon-button-container-height: #{map.get($s, height)};
-  --md-comp-icon-button-icon-size: #{map.get($s, icon)};
+  --md-comp-icon-button-container-height: #{rem(map.get($s, height))};
+  --md-comp-icon-button-icon-size: #{rem(map.get($s, icon))};
   --md-comp-icon-button-leading-space: #{map.get($s, space)};
   --md-comp-icon-button-trailing-space: #{map.get($s, space)};
   --md-comp-icon-button-narrow-space: #{map.get($s, narrow)};
@@ -306,14 +521,70 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   }
 }
 
+// The .toggle legend button is the same in every chart, so chart() writes
+// it once, with the first chart in the build.
+$_chart-toggle-written: false;
+
+// With .toggle, a button shows or hides each series. It covers its legend
+// item, swatch included, and a hidden series is struck through with a
+// hollow swatch, so the state does not rest on color. The class keeps it
+// out of the button styles, in _buttons.scss.
+@mixin _chart-toggle {
+  .chart-toggle {
+    min-height: rem(48px);
+    padding: 0;
+    border: 0;
+    background: none;
+    color: inherit;
+    font: inherit;
+    cursor: pointer;
+
+    &::after {
+      content: "";
+      position: absolute;
+      inset: 0;
+      border-radius: 4px;
+    }
+
+    &:focus-visible {
+      outline: none;
+
+      &::after {
+        @include focus-ring();
+      }
+    }
+
+    &:hover {
+      color: var(--md-sys-color-on-surface);
+    }
+
+    &[aria-pressed="false"] {
+      text-decoration: line-through;
+    }
+
+    &[aria-disabled="true"] {
+      cursor: default;
+    }
+  }
+
+  li:has(> .chart-toggle[aria-pressed="false"])::before {
+    mask: radial-gradient(closest-side, transparent 50%, #000 calc(50% + 0.5px));
+  }
+}
+
 // The parts LineChart draws for every chart type, prefixed with the
 // component's name: .#{$name}-plot, -cursor, -tooltip, -labels and -legend.
 // Defines the --md-comp-#{$name}-height, -grid-color and -color-1..4 tokens,
 // and --#{$name}-color on each [data-series]. Include it at the root of the
 // component's partial; the component adds its own marks and cursor look.
 @mixin chart($name) {
+  @if not $_chart-toggle-written {
+    $_chart-toggle-written: true !global;
+    @include _chart-toggle;
+  }
+
   .#{$name} {
-    --md-comp-#{$name}-height: 240px;
+    --md-comp-#{$name}-height: #{rem(240px)};
     --md-comp-#{$name}-grid-color: var(--md-sys-color-outline-variant);
     --md-comp-#{$name}-color-1: var(--md-sys-color-primary);
     --md-comp-#{$name}-color-2: var(--md-sys-color-tertiary);
@@ -378,10 +649,10 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
     display: grid;
     grid-template-columns: auto auto;
     gap: 4px 16px;
-    min-width: 120px;
+    min-width: rem(120px);
     margin: 0;
     padding: 12px 16px;
-    border-radius: 12px;
+    border-radius: var(--md-sys-shape-corner-medium);
     background-color: var(--md-comp-#{$name}-tooltip-color);
     color: var(--md-sys-color-on-surface-variant);
     @include typescale("body-small");
@@ -439,6 +710,28 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
       text-overflow: ellipsis;
       white-space: nowrap;
     }
+
+    // When each label is wider than its column, LineChart keeps every nth
+    // one. A kept label spreads over the hidden ones beside it, still
+    // centred on its own column; the flex box centres what overflows. The
+    // end labels line up with the chart's edges, so none overflows them.
+    &[data-thinned] > li:not([data-skip]) {
+      display: flex;
+      justify-content: center;
+      overflow: visible;
+
+      &:first-child {
+        justify-content: start;
+      }
+
+      &:last-child {
+        justify-content: end;
+      }
+    }
+
+    > li[data-skip] {
+      visibility: hidden;
+    }
   }
 
   .#{$name}-legend {
@@ -447,6 +740,7 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
     gap: 4px 16px;
 
     > li {
+      position: relative;
       display: flex;
       align-items: center;
       gap: 8px;
@@ -497,3 +791,95 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
     }
   }
 }
+
+// The columns' or bars' growth, inside their container: from the zero
+// line, or after update() from where each span was, which ColumnChart
+// writes as --from-top and --from-bottom. !important lets these starting
+// values beat the inline --top and --bottom.
+@mixin chart-column-motion {
+  @media (prefers-reduced-motion: no-preference) {
+    > div > span {
+      transition: clip-path var(--md-sys-motion-duration-medium4) var(--md-sys-motion-easing-standard);
+
+      @starting-style {
+        --top: var(--from-top, var(--zero, 100%)) !important;
+        --bottom: var(--from-bottom, calc(100% - var(--zero, 100%))) !important;
+      }
+    }
+  }
+}
+
+// The value labels LineChart draws for .axis: an .#{$name}-axis list in the
+// plot, behind the marks, with each label's distance down the plot in --at.
+// A label sits beside the plot with a grid line across it at its value; a
+// mixed chart's end scale gets a second list, .end, on the far side, whose
+// labels share those lines. With $beside the plot and row labels make room
+// at the inline start (and end, for .end) for
+// --md-comp-#{$name}-axis-width, 48px. Without it the component places the
+// labels itself.
+@mixin chart-axis($name, $beside: true) {
+  .#{$name}.axis {
+    --md-comp-#{$name}-axis-width: #{rem(48px)};
+
+    > .#{$name}-plot {
+      background: none;
+    }
+  }
+
+  @if $beside {
+    // Room for the top label's upper half.
+    .#{$name}.axis > .#{$name}-plot {
+      margin-block-start: 8px;
+    }
+
+    .#{$name}.axis > :is(.#{$name}-plot, .#{$name}-labels) {
+      margin-inline-start: var(--md-comp-#{$name}-axis-width);
+    }
+
+    .#{$name}.axis:has(.#{$name}-axis.end) > :is(.#{$name}-plot, .#{$name}-labels) {
+      margin-inline-end: var(--md-comp-#{$name}-axis-width);
+    }
+  }
+
+  .#{$name}-axis {
+    position: absolute;
+    inset: 0;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    color: var(--md-sys-color-on-surface-variant);
+    @include typescale("body-small");
+    font-variant-numeric: tabular-nums;
+    pointer-events: none;
+
+    > li {
+      position: absolute;
+      inset-inline: 0;
+      top: var(--at, 0%);
+      border-block-start: 1px solid var(--md-comp-#{$name}-grid-color);
+    }
+
+    > li > span {
+      position: absolute;
+      inset-inline-end: 100%;
+      box-sizing: border-box;
+      width: var(--md-comp-#{$name}-axis-width);
+      padding-inline-end: 8px;
+      overflow: hidden;
+      text-align: end;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+      translate: 0 -50%;
+    }
+
+    &.end > li {
+      border: 0;
+    }
+
+    &.end > li > span {
+      inset-inline: 100% auto;
+      padding-inline: 8px 0;
+      text-align: start;
+    }
+  }
+}

package/src/sass/abstracts/_spring.scss

@@ -0,0 +1,63 @@
+@use "sass:list";
+@use "sass:math";
+@use "sass:string";
+
+// Springs, solved at compile time. M3 Expressive describes motion as springs
+// (a damping ratio and a stiffness, mass 1) rather than as curves and
+// durations. CSS has no spring timing function, so spring() samples the
+// spring's position from rest to the target into a `linear()` easing, and
+// spring-duration() returns how long it takes to settle. Use them together:
+//
+//   transition: translate spring-duration(0.8, 380) spring(0.8, 380);
+//
+// tokens/_motion.scss emits M3's six standard and expressive springs as
+// --md-sys-motion-spring-* tokens from these.
+
+// Settled once within this fraction of the distance, about a pixel on a
+// 200px move.
+$_settle: 0.005;
+$_samples: 24;
+
+// Position at $t seconds, from 0 to 1, for a spring released at rest.
+@function _position($t, $damping, $stiffness) {
+  $w: math.sqrt($stiffness);
+  @if $damping < 1 {
+    $wd: $w * math.sqrt(1 - $damping * $damping);
+    $decay: math.pow(math.$e, -$damping * $w * $t);
+    @return 1 - $decay * (math.cos($wd * $t) + math.div($damping * $w, $wd) * math.sin($wd * $t));
+  }
+  // Critically damped (M3's effects springs). Overdamped springs are not used.
+  @return 1 - math.pow(math.$e, -$w * $t) * (1 + $w * $t);
+}
+
+// Seconds until the spring stays within $_settle of the target. An
+// underdamped spring settles when its envelope does; a critically damped one
+// is stepped forward a millisecond at a time.
+@function _settle-time($damping, $stiffness) {
+  $w: math.sqrt($stiffness);
+  @if $damping < 1 {
+    @return math.div(math.log(math.div(1, $_settle * math.sqrt(1 - $damping * $damping))), $damping * $w);
+  }
+  $t: 0;
+  @while 1 - _position($t, $damping, $stiffness) > $_settle {
+    $t: $t + 0.001;
+  }
+  @return $t;
+}
+
+/// How long the spring takes to settle, in milliseconds.
+@function spring-duration($damping, $stiffness) {
+  @return math.round(_settle-time($damping, $stiffness) * 1000) * 1ms;
+}
+
+/// The spring as a `linear()` easing over spring-duration().
+@function spring($damping, $stiffness) {
+  $end: _settle-time($damping, $stiffness);
+  $points: (0,);
+  @for $i from 1 to $_samples {
+    $x: _position($end * math.div($i, $_samples), $damping, $stiffness);
+    $points: list.append($points, string.unquote("#{math.div(math.round($x * 10000), 10000)} #{math.div(math.round(math.div($i, $_samples) * 1000), 10)}%"), comma);
+  }
+  $points: list.append($points, 1, comma);
+  @return string.unquote("linear(#{$points})");
+}