@expressivecss/expressive 0.15.0 → 0.17.0

package/src/sass/abstracts/_mixins.scss

@@ -1,11 +1,22 @@
 @use "sass:list";
 @use "sass:map";
+@use "sass:meta";
 @use "sass:math";
 @use "./elevation" as *;
 @use "./variables" as *;
 
 $_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 +34,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 +72,24 @@ $_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 button style and the FABs. Elevated and the FABs also move
+// z-depth on hover or 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();
@@ -80,14 +99,14 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   color: var(--md-comp-filled-button-label-text-color, var(--md-sys-color-on-primary));
   background-color: var(--md-comp-filled-button-container-color, var(--md-sys-color-primary));
 
-  @include _btn-states(var(--md-sys-color-on-primary), var(--md-sys-color-primary));
+  @include btn-states(var(--md-sys-color-on-primary), var(--md-sys-color-primary));
 }
 
 @mixin btn-tonal {
   color: var(--md-sys-color-on-secondary-container);
   background-color: var(--md-sys-color-secondary-container);
 
-  @include _btn-states(var(--md-sys-color-on-secondary-container), var(--md-sys-color-secondary-container));
+  @include btn-states(var(--md-sys-color-on-secondary-container), var(--md-sys-color-secondary-container));
 }
 
 @mixin btn-elevated {
@@ -95,18 +114,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 {
@@ -118,7 +126,7 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   // height right.
   border: var(--md-comp-filled-button-outline-width, 1px) solid var(--md-sys-color-outline);
 
-  @include _btn-states(var(--md-sys-color-primary), transparent);
+  @include btn-states(var(--md-sys-color-primary), transparent);
 }
 
 @mixin btn-flat {
@@ -127,7 +135,7 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   background-color: transparent;
   border-color: transparent;
 
-  @include _btn-states(var(--md-sys-color-primary), transparent);
+  @include btn-states(var(--md-sys-color-primary), transparent);
 }
 
 @mixin btn-disabled {
@@ -139,6 +147,36 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   cursor: default;
 }
 
+// A list with no markers or indentation. WebKit drops the list role from a
+// list with `list-style: none`, so markup that needs it adds role="list".
+@mixin list-reset {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+// One line, cut off with an ellipsis when the box is too narrow for it.
+@mixin ellipsis {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+// Covers the positioned parent. Width and height still matter for replaced
+// elements (a canvas, an svg, an iframe), which `inset` alone does not stretch.
+@mixin fill-parent {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+}
+
+// Hidden on paper. Important so a size or state rule that sets `display`
+// cannot bring it back; see base/_print.scss for the page itself.
+@mixin print-hidden {
+  @media print { display: none !important; }
+}
+
 // Off the screen but not out of the document: still focusable, still read, and
 // still a form control. `display: none` and `visibility: hidden` both take the
 // element out of the tab order, which is the wrong trade for a control whose
@@ -148,9 +186,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; }
@@ -169,40 +204,343 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
 // Focus with Keyboard
 // The ring itself, for the rare selector that cannot be written as
 // `&:focus-visible` on the focused element - a filter chip draws its ring on
-// the <label>, but the focus is on the checkbox before it.
-@mixin focus-ring {
+// the <label>, but the focus is on the checkbox before it. A row inside a
+// scrolling list passes a negative `$offset` so the list does not clip it.
+@mixin focus-ring($offset: 2px) {
   outline: 3px solid var(--md-sys-color-secondary);
-  outline-offset: 2px;
+  outline-offset: $offset;
 }
 
-@mixin focus-visible {
+@mixin focus-visible($offset: 2px) {
   &:focus-visible {
-    @include focus-ring();
+    @include focus-ring($offset);
+  }
+}
+
+// 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;
+}
+
+// The 64dp header bar of a full-screen dialog, a side sheet or a pane: a
+// flex row with no fill or shadow. `background: none` also keeps the top app
+// bar's `header:has(> nav)` fill off it. Callers add their own padding.
+@mixin header-bar($gap) {
+  display: flex;
+  align-items: center;
+  gap: $gap;
+  flex: 0 0 auto;
+  box-sizing: border-box;
+  min-height: 64px;
+  margin: 0;
+  background: none;
+  box-shadow: none;
+}
+
+// A header bar's heading: takes the free space and can shrink, title-large.
+@mixin header-bar-headline {
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+  color: var(--md-sys-color-on-surface);
+  @include typescale("title-large");
+}
+
+// The states of a text action with no button chrome of its own: a mega menu
+// or menubar item, a rail panel link, a tree or cascader row. An on-surface
+// hover layer and, given `$selected` (a compound such as `[aria-current]`), a
+// selected fill with a Highlight outline under forced colors. Hover comes
+// first: the two have equal specificity, so the selected fill wins on hover.
+@mixin text-action(
+  $selected: null,
+  $container: var(--md-sys-color-secondary-container),
+  $on-container: var(--md-sys-color-on-secondary-container),
+) {
+  &:hover {
+    background-color: state-layer(var(--md-sys-color-on-surface), "hover");
+  }
+
+  @if $selected {
+    &#{$selected} {
+      background-color: $container;
+      color: $on-container;
+      @include forced-colors-selected;
+    }
+  }
+}
+
+// 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} {
+    @include icon-size(rem(24px));
+  }
+
+  &:hover {
+    background-color: state-layer(var(--md-sys-color-on-surface), "hover");
+  }
+
+  @include focus-visible;
+}
+
+// An icon glyph's box: a ligature font size in a square of the same size. Pass
+// `$line-height: 1` where the glyph sits on a text baseline.
+@mixin icon-size($size, $line-height: $size) {
+  font-size: $size;
+  width: $size;
+  height: $size;
+  line-height: $line-height;
+}
+
+// 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.
+
+@mixin tree-chevron {
+  content: "";
+  flex: none;
+  width: 20px;
+  height: 20px;
+  background-color: currentColor;
+  mask: $expand-more 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");
+}
+
+// A radio, checkbox or switch drawn on the <input> itself: the native look
+// cleared to a $width x $height box with a 2px $border-color edge.
+@mixin selection-control($width, $height, $border-color) {
+  appearance: none;
+  flex: 0 0 $width;
+  box-sizing: border-box;
+  width: $width;
+  height: $height;
+  margin: 0;
+  padding: 0;
+  border: 2px solid $border-color;
+}
+
+// The hover, checked hover and focus rings of a selection control, from the
+// $inner edge out to $outer. $checked lists the states whose ring is primary.
+@mixin selection-control-states($outer, $inner, $checked: ":checked") {
+  $checked-hover: ();
+  @each $state in $checked {
+    $checked-hover: list.append($checked-hover, "&#{$state}:hover", comma);
+  }
+
+  &:hover {
+    @include state-layer-ring($outer, $inner, var(--md-sys-color-on-surface), "hover");
+  }
+
+  #{$checked-hover} {
+    @include state-layer-ring($outer, $inner, var(--md-sys-color-primary), "hover");
+  }
+
+  &:focus-visible {
+    @include state-layer-ring($outer, $inner, var(--md-sys-color-primary), "focus");
+    outline: none;
+  }
+}
+
 /// 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
-    );
+  // Two lengths fold to one. Anything else is interpolated, so a quoted
+  // value, such as "var(--c)", is written unquoted.
+  $spread: calc((#{$outer} - #{$inner}) / 2);
+  @if meta.type-of($outer) == "number" and meta.type-of($inner) == "number" {
+    $spread: calc(($outer - $inner) / 2);
+  }
+  box-shadow: 0 0 0 $spread state-layer(#{$color}, $state);
 }
 
 /// The button size tokens for one rung of `$button-sizes`.
@@ -213,20 +551,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,21 +646,159 @@ $_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 series colors. Past the first four come the container roles, which
+// alone are 1.3:1 on the surface in light mode and 2:1 in dark. Mixed 45%
+// with on-surface, they keep their hue and reach 5:1 and 6.8:1, past the 3:1
+// a mark needs (WCAG 1.4.11), and surface text on them passes too.
+$_chart-colors: (
+  var(--md-sys-color-primary),
+  var(--md-sys-color-tertiary),
+  var(--md-sys-color-secondary),
+  var(--md-sys-color-on-surface-variant),
+  color-mix(in oklab, var(--md-sys-color-primary-container) 45%, var(--md-sys-color-on-surface)),
+  color-mix(in oklab, var(--md-sys-color-tertiary-container) 45%, var(--md-sys-color-on-surface))
+);
+$_chart-on-colors: ("on-primary", "on-tertiary", "on-secondary", "surface", "surface", "surface");
+
 // 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,
+// Defines the --md-comp-#{$name}-height, -grid-color and -color-1..N 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) {
+//
+// The options draw parts that some chart types share:
+//   $colors     4 to 6 series colors; 5 and 6 are primary- and
+//               tertiary-container deepened toward on-surface
+//   $on-colors  adds --md-comp-#{$name}-on-color-1..N, the text color on each
+//               series color, and --#{$name}-on-color on each [data-series]
+//   $grid       false leaves out the plot's grid lines and baseline
+//   $round      a round plot with no grid, as wide as the height token and
+//               centred; a sparkline's sits at the inline start
+//   $rows       a band per table row down the plot, which is as tall as its
+//               rows at --md-comp-#{$name}-row-height (40px each), with the
+//               labels beside it, grid lines down it and the tooltip below
+//               the highlighted row
+//   $tooltip    middle centres the tooltip on its point instead of hanging
+//               it from the point's top
+//   $cursor     line draws a 1px line with a dot on it for each series;
+//               band tints the highlighted row behind the marks, rounded by
+//               --md-comp-#{$name}-shape (4px)
+//   $lines      styles series drawn as SVG lines: .#{$name}-line, dashed in
+//               a .dashed .#{$name}-series, .#{$name}-points and the area
+//               gradient's stops, at --md-comp-#{$name}-line-width (3px,
+//               sparkline 2px)
+//   $legend-columns  a number, 3 or more, lays the legend out as a table of
+//               that many columns: swatch, name, then the values, the first
+//               of them bold
+@mixin chart(
+  $name,
+  $colors: 4,
+  $on-colors: false,
+  $grid: true,
+  $round: false,
+  $rows: false,
+  $tooltip: top,
+  $cursor: null,
+  $lines: false,
+  $legend-columns: null
+) {
+  @if $colors < 4 or $colors > list.length($_chart-colors) {
+    @error "chart() takes 4 to #{list.length($_chart-colors)} $colors, got #{$colors}.";
+  }
+  @if not list.index((top, middle), $tooltip) {
+    @error "chart() $tooltip must be top or middle, got #{$tooltip}.";
+  }
+  @if $legend-columns and $legend-columns < 3 {
+    @error "chart() $legend-columns must be 3 or more, got #{$legend-columns}.";
+  }
+  @if $cursor and not list.index((line, band), $cursor) {
+    @error "chart() $cursor must be line, band or null, got #{$cursor}.";
+  }
+
+  $grid: $grid and not $round;
+
+  @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);
-    --md-comp-#{$name}-color-3: var(--md-sys-color-secondary);
-    --md-comp-#{$name}-color-4: var(--md-sys-color-on-surface-variant);
+    @for $i from 1 through $colors {
+      --md-comp-#{$name}-color-#{$i}: #{list.nth($_chart-colors, $i)};
+    }
+    @if $on-colors {
+      @for $i from 1 through $colors {
+        --md-comp-#{$name}-on-color-#{$i}: var(--md-sys-color-#{list.nth($_chart-on-colors, $i)});
+      }
+    }
+    @if $rows {
+      --md-comp-#{$name}-row-height: #{rem(40px)};
+    }
+    @if $cursor == band {
+      --md-comp-#{$name}-shape: var(--md-sys-shape-corner-extra-small);
+    }
+    @if $lines {
+      --md-comp-#{$name}-line-width: 3px;
+    }
 
-    display: flex;
+    @if $rows {
+      display: grid;
+    } @else {
+      display: flex;
+    }
     flex-direction: column;
     gap: 8px;
     min-width: 0;
@@ -333,6 +811,28 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
     // it hangs up from the bottom edge, where the overflow cannot scroll.
     position: relative;
 
+    @if $rows {
+      // Labels beside the plot, up to 40% of the width; everything else
+      // spans both columns. Dense flow puts the labels in the plot's row. A
+      // stretched figure, as in a grid of cards, keeps its rows at their size.
+      grid-template-columns: fit-content(40%) minmax(0, 1fr);
+      grid-auto-flow: row dense;
+      align-content: start;
+      column-gap: 12px;
+
+      > * {
+        grid-column: 1 / -1;
+      }
+
+      > .#{$name}-plot {
+        grid-column: 2;
+      }
+
+      > .#{$name}-labels {
+        grid-column: 1;
+      }
+    }
+
     > figcaption {
       color: var(--md-sys-color-on-surface-variant);
       @include typescale("title-small");
@@ -345,27 +845,92 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
     }
   }
 
-  @for $i from 1 through 4 {
+  @for $i from 1 through $colors {
     .#{$name} [data-series="#{$i}"] {
       --#{$name}-color: var(--md-comp-#{$name}-color-#{$i});
+      @if $on-colors {
+        --#{$name}-on-color: var(--md-comp-#{$name}-on-color-#{$i});
+      }
     }
   }
 
   .#{$name}-plot {
     position: relative;
-    height: var(--md-comp-#{$name}-height);
-    border-block-end: 1px solid var(--md-comp-#{$name}-grid-color);
-    border-radius: 2px;
-    // Four grid lines; the border is the fifth.
-    background: linear-gradient(var(--md-comp-#{$name}-grid-color) 1px, transparent 0) 0 0 / 100% 25%;
+    @if $cursor == band {
+      isolation: isolate;
+    }
+    @if $round {
+      width: min(100%, var(--md-comp-#{$name}-height));
+      height: auto;
+      aspect-ratio: 1;
+      margin-inline: auto;
+      border-radius: 50%;
+    } @else {
+      @if $rows {
+        height: calc(var(--rows, 1) * var(--md-comp-#{$name}-row-height));
+      } @else {
+        height: var(--md-comp-#{$name}-height);
+      }
+      @if $grid and $rows {
+        border-right: 1px solid var(--md-comp-#{$name}-grid-color);
+      } @else if $grid {
+        border-block-end: 1px solid var(--md-comp-#{$name}-grid-color);
+      }
+      border-radius: 2px;
+    }
+    @if $grid and $rows {
+      // A line down the plot at each quarter of the value axis.
+      background: linear-gradient(to right, var(--md-comp-#{$name}-grid-color) 1px, transparent 0) 0 0 / 25% 100%;
+    } @else if $grid {
+      // Four grid lines; the border is the fifth.
+      background: linear-gradient(var(--md-comp-#{$name}-grid-color) 1px, transparent 0) 0 0 / 100% 25%;
+    }
     touch-action: pan-y;
     @include focus-visible;
   }
 
   .#{$name}-cursor {
     position: absolute;
-    inset-block: 0;
+    @if $cursor == band and $rows {
+      inset-block: auto;
+      inset-inline: 0;
+      height: calc(100% / var(--rows, 1));
+    } @else {
+      inset-block: 0;
+    }
     pointer-events: none;
+
+    @if $cursor == line {
+      width: 1px;
+      background-color: var(--md-sys-color-outline);
+
+      > span {
+        position: absolute;
+        left: 0;
+        width: 10px;
+        height: 10px;
+        border: 2px solid var(--md-sys-color-surface);
+        border-radius: 50%;
+        background-color: var(--#{$name}-color);
+        translate: -50% -50%;
+      }
+    }
+
+    // A band behind the highlighted row's marks, which the plot's isolation
+    // keeps in front of the plot's own background.
+    @if $cursor == band {
+      z-index: -1;
+      @if not $rows {
+        width: calc(100% / var(--rows, 1));
+      }
+      border-radius: var(--md-comp-#{$name}-shape);
+      background-color: state-layer(var(--md-sys-color-on-surface), "hover");
+      @if $rows {
+        translate: 0 -50%;
+      } @else {
+        translate: -50% 0;
+      }
+    }
   }
 
   // Rich tooltip surface, as in _tooltip.scss.
@@ -374,21 +939,31 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
 
     position: absolute;
     top: 0;
+    @if $rows {
+      left: 50%;
+    }
     z-index: 1;
     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");
     white-space: nowrap;
     font-variant-numeric: tabular-nums;
     pointer-events: none;
-    translate: 12px 0;
+    @if $rows {
+      // Below the highlighted row, or above it in the lower half.
+      translate: -50% calc(var(--md-comp-#{$name}-row-height) / 2);
+    } @else if $tooltip == middle {
+      translate: 12px -50%;
+    } @else {
+      translate: 12px 0;
+    }
     @include z-depth("2");
     @include glass(var(--md-comp-#{$name}-tooltip-color));
 
@@ -397,7 +972,13 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
     }
 
     &.end {
-      translate: calc(-100% - 12px) 0;
+      @if $rows {
+        translate: -50% calc(-100% - var(--md-comp-#{$name}-row-height) / 2);
+      } @else if $tooltip == middle {
+        translate: calc(-100% - 12px) -50%;
+      } @else {
+        translate: calc(-100% - 12px) 0;
+      }
     }
 
     > strong {
@@ -421,9 +1002,7 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
 
   .#{$name}-labels,
   .#{$name}-legend {
-    margin: 0;
-    padding: 0;
-    list-style: none;
+    @include list-reset;
     color: var(--md-sys-color-on-surface-variant);
     @include typescale("body-small");
   }
@@ -431,26 +1010,87 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   .#{$name}-labels {
     display: grid;
     grid-auto-columns: minmax(0, 1fr);
-    grid-auto-flow: column;
-    text-align: center;
+    @if $rows {
+      grid-auto-rows: minmax(0, 1fr);
+      grid-auto-flow: row;
+      align-items: center;
+      text-align: end;
+    } @else {
+      grid-auto-flow: column;
+      text-align: center;
+    }
 
     > li {
-      overflow: hidden;
-      text-overflow: ellipsis;
-      white-space: nowrap;
+      @include ellipsis;
+    }
+
+    // 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 {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 4px 16px;
+    @if $legend-columns {
+      $columns: auto minmax(0, 1fr);
+      @for $i from 3 through $legend-columns {
+        $columns: list.append($columns, auto);
+      }
+
+      display: grid;
+      grid-template-columns: $columns;
+      align-items: center;
+      flex-wrap: wrap;
+      gap: 8px;
+    } @else {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 4px 16px;
+    }
 
     > li {
-      display: flex;
+      position: relative;
+      @if $legend-columns {
+        display: contents;
+      } @else {
+        display: flex;
+      }
       align-items: center;
       gap: 8px;
     }
+
+    @if $legend-columns {
+      > li > span:first-child {
+        @include ellipsis;
+      }
+
+      > li > span:not(:first-child) {
+        text-align: end;
+        font-variant-numeric: tabular-nums;
+      }
+
+      > li > span:nth-child(2) {
+        color: var(--md-sys-color-on-surface);
+        font-weight: 500;
+      }
+    }
   }
 
   // Series swatches.
@@ -464,15 +1104,57 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
     background-color: var(--#{$name}-color);
   }
 
+  @if $lines {
+    .#{$name}-line {
+      fill: none;
+      stroke: var(--#{$name}-color);
+      stroke-width: var(--md-comp-#{$name}-line-width);
+      stroke-linecap: round;
+      stroke-linejoin: round;
+      vector-effect: non-scaling-stroke;
+    }
+
+    .#{$name}-series.dashed .#{$name}-line {
+      stroke-dasharray: 2 8;
+    }
+
+    // Round caps on zero-length lines: dots that keep their size at any scale.
+    .#{$name}-points {
+      fill: none;
+      stroke: var(--#{$name}-color);
+      stroke-width: calc(var(--md-comp-#{$name}-line-width) * 3);
+      stroke-linecap: round;
+      vector-effect: non-scaling-stroke;
+    }
+
+    .#{$name}-series stop {
+      stop-color: var(--#{$name}-color);
+      stop-opacity: 0;
+
+      &:first-child {
+        stop-opacity: 0.24;
+      }
+    }
+  }
+
   .#{$name}.sparkline {
     --md-comp-#{$name}-height: 48px;
+    @if $lines {
+      --md-comp-#{$name}-line-width: 2px;
+    }
     // Keep the taller hidden table from adding scrollable overflow. A
     // sparkline has no tooltip or focus ring to clip.
     overflow: clip;
 
-    .#{$name}-plot {
-      border: 0;
-      background: none;
+    @if $grid {
+      .#{$name}-plot {
+        border: 0;
+        background: none;
+      }
+    } @else if $round {
+      .#{$name}-plot {
+        margin-inline: 0;
+      }
     }
 
     .#{$name}-labels,
@@ -482,14 +1164,30 @@ $_state-layers: ("hover", "focus", "pressed", "dragged");
   }
 
   @media (forced-colors: active) {
-    .#{$name}-plot {
-      background: none;
+    @if $grid {
+      .#{$name}-plot {
+        background: none;
+      }
     }
 
     .#{$name}-tooltip {
       outline: 1px solid CanvasText;
     }
 
+    @if $cursor == line {
+      .#{$name}-cursor {
+        background-color: CanvasText;
+      }
+
+      .#{$name}-cursor > span {
+        forced-color-adjust: none;
+      }
+    } @else if $cursor == band {
+      .#{$name}-cursor {
+        outline: 1px solid CanvasText;
+      }
+    }
+
     // The marks keep their colors, so the swatches that key them must too.
     .#{$name}-legend > li::before,
     .#{$name}-tooltip > span:nth-of-type(odd)::before {
@@ -497,3 +1195,91 @@ $_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;
+    @include list-reset;
+    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;
+      @include ellipsis;
+      text-align: end;
+      translate: 0 -50%;
+    }
+
+    &.end > li {
+      border: 0;
+    }
+
+    &.end > li > span {
+      inset-inline: 100% auto;
+      padding-inline: 8px 0;
+      text-align: start;
+    }
+  }
+}