@expressivecss/expressive 0.14.1 → 0.16.0

package/src/sass/components/forms/_switches.scss

@@ -4,12 +4,11 @@
 //
 // Anatomy is the HTML. A <label class="switch"> wrapping
 // <input type="checkbox"> is the control. The label text is a sibling of
-// the input — no .lever required. input + .lever and input + span still
-// work (legacy).
+// the input — no .lever required.
 //
 // Tokens follow https://m3.material.io/components/switch/specs
 //   track          52×32dp, 16dp corners
-//   unselected     surface-variant + 2dp outline, 16dp handle
+//   unselected     surface-container-highest + 2dp outline, 16dp handle
 //   selected       primary track, 24dp on-primary handle
 //   state layer    40dp, 8% hover / 10% focus
 //   touch target   48dp
@@ -18,46 +17,22 @@
 
 .switch {
   --md-comp-switch-track-width: 52px;
+  // The handle slides and grows on the fast spatial spring; colors keep
+  // their short ease.
+  --md-comp-switch-motion: var(--md-sys-motion-spring-fast-spatial);
+  --md-comp-switch-motion-duration: var(--md-sys-motion-spring-fast-spatial-duration);
   --md-comp-switch-track-height: 32px;
   --md-comp-switch-handle-unselected: 16px;
   --md-comp-switch-handle-selected: 24px;
 
-  display: inline-flex;
-  align-items: center;
-  gap: 12px;
-  min-height: 48px;
-  margin: 0;
-  cursor: pointer;
-  user-select: none;
   -webkit-tap-highlight-color: transparent;
-  color: var(--md-sys-color-on-surface);
-  @include typescale("body-large");
-}
-
-.switch label {
-  display: inline-flex;
-  align-items: center;
-  gap: 12px;
-  cursor: pointer;
-  user-select: none;
+  @include selection-control-label(inline-flex);
 }
 
-// Hide the native control only when a following span/lever draws the track.
-.switch [type="checkbox"]:has(+ .lever),
-.switch [type="checkbox"]:has(+ span) {
-  position: absolute;
-  opacity: 0;
-  width: 0;
-  height: 0;
-  pointer-events: none;
-}
-
-// Paint the switch on the checkbox when there is no lever/span.
-.switch [type="checkbox"]:not(:has(+ .lever)):not(:has(+ span)) {
+// Paint the switch on the checkbox. The class goes on the <label> that wraps
+// it; a checkbox nested deeper is an ordinary checkbox.
+.switch > [type="checkbox"] {
   appearance: none;
-  position: static;
-  opacity: 1;
-  pointer-events: auto;
   flex: 0 0 var(--md-comp-switch-track-width);
   box-sizing: border-box;
   width: var(--md-comp-switch-track-width);
@@ -65,8 +40,8 @@
   margin: 0;
   padding: 0;
   border: 2px solid var(--md-sys-color-outline);
-  border-radius: 16px;
-  background-color: var(--md-sys-color-surface-variant);
+  border-radius: var(--md-sys-shape-corner-large);
+  background-color: var(--md-sys-color-surface-container-highest);
   // Size the image to the handle. A 100% gradient keeps the circle in
   // the middle of the track, so background-position cannot put off on
   // the start and on on the end.
@@ -83,8 +58,13 @@
   // thumb on the start and it only grows.
   background-position: 6px 50%;
   cursor: pointer;
-  transition: background-color .2s ease, background-position .2s ease,
-    background-size .2s ease, border-color .2s ease, box-shadow .2s ease;
+  transition: background-color var(--md-sys-motion-duration-short4) ease,
+    background-position var(--md-comp-switch-motion-duration) var(--md-comp-switch-motion),
+    background-size var(--md-comp-switch-motion-duration) var(--md-comp-switch-motion), border-color var(--md-sys-motion-duration-short4) ease, box-shadow var(--md-sys-motion-duration-short4) ease;
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
 
   &:checked {
     border-color: var(--md-sys-color-primary);
@@ -103,16 +83,15 @@
   }
 
   &:hover {
-    box-shadow: 0 0 0 8px color-mix(in oklab, var(--md-sys-color-on-surface) state-opacity("hover"), transparent);
+    box-shadow: 0 0 0 8px state-layer(var(--md-sys-color-on-surface), "hover");
   }
 
   &:checked:hover {
-    box-shadow: 0 0 0 8px color-mix(in oklab, var(--md-sys-color-primary) state-opacity("hover"), transparent);
+    box-shadow: 0 0 0 8px state-layer(var(--md-sys-color-primary), "hover");
   }
 
-  &:focus-visible,
-  &.tabbed:focus {
-    box-shadow: 0 0 0 8px color-mix(in oklab, var(--md-sys-color-primary) state-opacity("focus"), transparent);
+  &:focus-visible {
+    box-shadow: 0 0 0 8px state-layer(var(--md-sys-color-primary), "focus");
     outline: none;
   }
 
@@ -123,129 +102,39 @@
   }
 }
 
-.switch:has(> [type="checkbox"]:disabled),
-.switch:has([type="checkbox"]:disabled) label {
+.switch:has(> [type="checkbox"]:disabled) {
   color: color-mix(in oklab, var(--md-sys-color-on-surface) 38%, transparent);
   cursor: default;
 }
 
-// Legacy: input + .lever or input + span draws the same anatomy.
-.switch [type="checkbox"] + .lever,
-.switch [type="checkbox"] + span {
-  position: relative;
-  display: inline-flex;
-  align-items: center;
-  flex: 0 0 auto;
-  box-sizing: border-box;
-  width: var(--md-comp-switch-track-width);
-  height: var(--md-comp-switch-track-height);
-  margin: 0;
-  padding: 0;
-  border: 2px solid var(--md-sys-color-outline);
-  border-radius: 16px;
-  background-color: var(--md-sys-color-surface-variant);
-  vertical-align: middle;
-  transition: background-color .2s ease, border-color .2s ease, box-shadow .2s ease;
-
-  &::before,
-  &::after {
-    content: "";
-    position: absolute;
-    top: 6px;
-    left: 6px;
-    width: 16px;
-    height: 16px;
-    border-radius: 50%;
-    transition: left .2s ease, top .2s ease, width .2s ease, height .2s ease,
-      background-color .2s ease, transform .2s ease;
-  }
-
-  &::after {
-    background-color: var(--md-sys-color-outline);
-  }
-}
-
-.switch [type="checkbox"]:checked + .lever,
-.switch [type="checkbox"]:checked + span {
-  border-color: var(--md-sys-color-primary);
-  background-color: var(--md-sys-color-primary);
-
-  &::before,
-  &::after {
-    top: 2px;
-    left: 22px;
-    width: 24px;
-    height: 24px;
-  }
-
-  &::after {
-    background-color: var(--md-sys-color-on-primary);
-  }
-}
-
-.switch [type="checkbox"]:hover + .lever,
-.switch [type="checkbox"]:hover + span {
-  box-shadow: 0 0 0 8px color-mix(in oklab, var(--md-sys-color-on-surface) state-opacity("hover"), transparent);
-}
-
-.switch [type="checkbox"]:checked:hover + .lever,
-.switch [type="checkbox"]:checked:hover + span {
-  box-shadow: 0 0 0 8px color-mix(in oklab, var(--md-sys-color-primary) state-opacity("hover"), transparent);
-}
-
-.switch [type="checkbox"]:focus-visible + .lever,
-.switch [type="checkbox"].tabbed:focus + .lever,
-.switch [type="checkbox"]:focus-visible + span,
-.switch [type="checkbox"].tabbed:focus + span {
-  box-shadow: 0 0 0 8px color-mix(in oklab, var(--md-sys-color-primary) state-opacity("focus"), transparent);
-}
-
-.switch [type="checkbox"]:disabled + .lever,
-.switch [type="checkbox"]:disabled + span {
-  opacity: 0.38;
-  box-shadow: none;
-  cursor: default;
-}
-
-// The span holds the label text as well as the track.
-.switch [type="checkbox"] + span:not(.lever):not(:empty) {
-  width: auto;
-  min-width: var(--md-comp-switch-track-width);
-  height: auto;
-  min-height: var(--md-comp-switch-track-height);
-  padding-left: calc(var(--md-comp-switch-track-width) + 12px);
-  border: 0;
-  background-color: transparent;
-  border-radius: 0;
-
-  &::before {
-    border: 2px solid var(--md-sys-color-outline);
-    background-color: var(--md-sys-color-surface-variant);
-    box-sizing: border-box;
-    width: var(--md-comp-switch-track-width);
-    height: var(--md-comp-switch-track-height);
-    border-radius: 16px;
-    top: 0;
-    left: 0;
-  }
-
-  &::after {
-    top: 8px;
-    left: 8px;
-  }
-}
-
-.switch [type="checkbox"]:checked + span:not(.lever):not(:empty) {
-  background-color: transparent;
-  border-color: transparent;
-
-  &::before {
-    border-color: var(--md-sys-color-primary);
-    background-color: var(--md-sys-color-primary);
-  }
-
-  &::after {
-    top: 4px;
-    left: 24px;
+// Forced colors drop the gradient handle, so a switch shows only an empty
+// track whatever its state. Repaint the whole control in system colors.
+@media (forced-colors: active) {
+  .switch > [type="checkbox"] {
+    forced-color-adjust: none;
+    border-color: CanvasText;
+    background-color: Canvas;
+    background-image: radial-gradient(circle closest-side, CanvasText 100%, transparent 101%);
+
+    &:checked {
+      border-color: Highlight;
+      background-color: Highlight;
+      background-image: radial-gradient(circle closest-side, HighlightText 100%, transparent 101%);
+    }
+
+    &:disabled {
+      border-color: GrayText;
+      background-image: radial-gradient(circle closest-side, GrayText 100%, transparent 101%);
+    }
+
+    &:disabled:checked {
+      background-color: GrayText;
+      background-image: radial-gradient(circle closest-side, Canvas 100%, transparent 101%);
+    }
+
+    &:focus-visible {
+      outline: 2px solid CanvasText;
+      outline-offset: 2px;
+    }
   }
 }

package/src/sass/custom.scss

@@ -1,10 +1,19 @@
 @charset "UTF-8";
+
+// The only place cascade order is decided; expressive.scss forwards this file
+// with its defaults. See README.md for why each layer sits where it does.
+// abstracts emits no CSS and is forwarded for the Sass API. @forward cannot
+// appear inside @layer, so each layer is loaded with meta.load-css().
 @use "sass:meta";
-@forward "abstracts";
+// The destination and fieldset mixins only serve the partials that share them.
+@forward "abstracts" hide nav-destination, nav-destination-row, choice-fieldset;
 
 $components: null !default;
 $utilities: null !default;
 
+// @font-face must stay unlayered. A face declared inside @layer base can
+// lose to any unlayered consumer face, or be ignored by engines that still
+// treat layered faces as experimental.
 @include meta.load-css("base/fonts");
 
 @layer tokens, base, components, utilities;

package/src/sass/expressive.scss

@@ -1,65 +1,5 @@
 @charset "UTF-8";
 
-// ExpressiveCSS entry point.
-//
-// This is the only place cascade order is decided, so a rule's position is
-// always answerable from this file. Layers:
-//
-//   abstracts  - variables, functions, mixins. Emits nothing, so it is not a
-//                cascade layer at all; partials pull it in with
-//                `@use "../abstracts" as *;`. Forwarded below so that
-//                downstream projects consuming this file keep access to the
-//                breakpoint mixins, z-depth() and btn-*.
-//   tokens     - :root custom properties (M3 reference palette + theme).
-//   base       - normalize, element defaults, typography, grid.
-//   components - widgets.
-//   utilities  - helper classes.
-//
-// Order used to be expressed purely as @forward order, with utilities emitted
-// before components so a component rule would win at equal specificity. It is
-// now a real @layer list, which changes three things:
-//
-//   1. Utilities moved after components. Layer order beats specificity
-//      outright, so a helper class now wins over a component rule without
-//      needing to out-specify it.
-//   2. Unlayered CSS beats every layer. A consumer can override any component
-//      with a plain `.btn { ... }` - no specificity war, no load-order
-//      dependence on where the framework sits in their bundle.
-//   3. !important is NOT dropped from utilities. Layer order reverses for
-//      important declarations, so an important rule inside `utilities` would
-//      also beat a consumer's own !important - but a *normal* rule in a layer
-//      loses to any unlayered consumer rule. Since `.hide`, `.m-3` and the
-//      palette classes exist precisely to be unconditional, they keep their
-//      flags and keep winning. Dropping them would silently make `.hide` lose
-//      to any unlayered `display` the consumer had already written.
-//
-// @forward cannot appear inside @layer, so each layer is pulled in with
-// meta.load-css() instead. abstracts emits no CSS, so loading it separately
-// below duplicates nothing.
-
-@use "sass:meta";
-
-@forward "abstracts";
-
-// @font-face must stay unlayered. A face declared inside @layer base can
-// lose to any unlayered consumer face, or be ignored by engines that still
-// treat layered faces as experimental.
-@include meta.load-css("base/fonts");
-
-@layer tokens, base, components, utilities;
-
-@layer tokens {
-  @include meta.load-css("tokens");
-}
-
-@layer base {
-  @include meta.load-css("base");
-}
-
-@layer components {
-  @include meta.load-css("components");
-}
-
-@layer utilities {
-  @include meta.load-css("utilities");
-}
+// ExpressiveCSS entry point: custom.scss with every component and utility.
+// Cascade order is decided there; see README.md for the layer rules.
+@forward "custom" hide $components, $utilities;

package/src/sass/tokens/_contrast.scss

@@ -0,0 +1,94 @@
+@use "sass:list";
+@use "sass:map";
+@use "sass:string";
+@use "../abstracts" as *;
+
+// Contrast levels. M3 offers standard, medium and high contrast schemes; the
+// standard one is tokens/_theme.scss. `contrast="medium"` or
+// `contrast="high"` on the root or on any subtree moves the accent roles,
+// on-surface-variant and the outlines to darker tones in the light scheme
+// and lighter tones in the dark one, from the same ramps, so a runtime
+// --md-source change still reaches them. Surfaces stay where they are.
+//
+// The tones are picked to meet M3's contrast targets against the surfaces
+// (about 4.5:1 for accents in medium and 7:1 in high, 3:1 and more for
+// outlines). They approximate material-color-utilities' contrast curves,
+// which solve a tone per color; they are not that solver's output.
+//
+// `prefers-contrast: more` applies the high scheme unless a `contrast`
+// attribute says otherwise; `contrast="standard"` opts out.
+//
+// The live roles are redeclared here, not the -light/-dark pairs, because a
+// role resolves its pair where it is declared. A page that overrides a pair
+// to re-theme should override it inside its own [contrast] rule too.
+
+// Role name pattern ("#" is the ramp) and [light tone, dark tone].
+$_accent-tones: (
+  "medium": ("#": (30, 87), "on-#": (100, 10), "#-container": (50, 60), "on-#-container": (100, 0)),
+  "high": ("#": (20, 95), "on-#": (100, 0), "#-container": (30, 80), "on-#-container": (100, 0)),
+);
+
+// Role and [ramp, light tone, dark tone].
+$_neutral-tones: (
+  "medium": (
+    "on-surface-variant": ("neutral-variant", 25, 87),
+    "outline": ("neutral-variant", 40, 70),
+    "outline-variant": ("neutral-variant", 60, 50),
+  ),
+  "high": (
+    "on-surface": ("neutral", 0, 100),
+    "on-surface-variant": ("neutral-variant", 20, 90),
+    "outline": ("neutral-variant", 25, 80),
+    "outline-variant": ("neutral-variant", 40, 70),
+  ),
+);
+
+// The error ramp is literal hex and has no tone 87.
+@function _palette($ramp, $tone) {
+  @if $ramp == "error" and $tone == 87 { $tone: 90; }
+  @return var(--md-ref-palette-#{$ramp}#{$tone});
+}
+
+@mixin _role($role, $ramp, $light, $dark) {
+  --md-sys-color-#{$role}: light-dark(#{_palette($ramp, $light)}, #{_palette($ramp, $dark)});
+}
+
+@mixin _scheme($level) {
+  @each $ramp in ("primary", "secondary", "tertiary", "error") {
+    @each $pattern, $tones in map.get($_accent-tones, $level) {
+      $at: string.index($pattern, "#");
+      $role: string.slice($pattern, 1, $at - 1) + $ramp + string.slice($pattern, $at + 1);
+      @include _role($role, $ramp, list.nth($tones, 1), list.nth($tones, 2));
+    }
+  }
+  @each $role, $spec in map.get($_neutral-tones, $level) {
+    @include _role($role, list.nth($spec, 1), list.nth($spec, 2), list.nth($spec, 3));
+  }
+}
+
+// Back to the standard pairs, for a subtree inside a page that asked for
+// more contrast.
+[contrast='standard'],
+:host([contrast='standard']) {
+  @each $role in map.keys(map.get($_neutral-tones, "high")) {
+    --md-sys-color-#{$role}: light-dark(var(--md-sys-color-#{$role}-light), var(--md-sys-color-#{$role}-dark));
+  }
+  @each $ramp in ("primary", "secondary", "tertiary", "error") {
+    @each $pattern in map.keys(map.get($_accent-tones, "high")) {
+      $at: string.index($pattern, "#");
+      $role: string.slice($pattern, 1, $at - 1) + $ramp + string.slice($pattern, $at + 1);
+      --md-sys-color-#{$role}: light-dark(var(--md-sys-color-#{$role}-light), var(--md-sys-color-#{$role}-dark));
+    }
+  }
+}
+
+[contrast='medium'],
+:host([contrast='medium']) { @include _scheme("medium"); }
+
+[contrast='high'],
+:host([contrast='high']) { @include _scheme("high"); }
+
+@media (prefers-contrast: more) {
+  :root:not([contrast]),
+  :host(:not([contrast])) { @include _scheme("high"); }
+}

package/src/sass/tokens/_elevation.scss

@@ -0,0 +1,16 @@
+@use "../abstracts" as *;
+
+// Elevation tokens: one --md-sys-elevation-level<N> shadow per key of
+// $elevations in abstracts/_elevation.scss. The z-depth() mixin and the
+// .z-depth-* classes read these, so a theme can change a level at runtime:
+//
+//   :root { --md-sys-elevation-level1: 0 1px 3px rgb(0 0 0 / 0.3); }
+//
+// Level 0 is `none`, which cancels a shadow.
+
+:root,
+:host {
+  @each $level, $shadow in $elevations {
+    --md-sys-elevation-level#{$level}: #{$shadow};
+  }
+}

package/src/sass/tokens/_index.scss

@@ -4,4 +4,9 @@
 @forward "reference";  // raw ramps + resolved light/dark pairs
 @forward "theme";      // maps the pairs onto the live --md-sys-color-* names
 @forward "vibrant";    // [vibrant] remaps the surface family onto an accent
+@forward "contrast";   // [contrast] medium and high schemes, and prefers-contrast: more
 @forward "state";      // md.sys.state.* state layer opacities
+@forward "motion";     // md.sys.motion.* easing curves and durations
+@forward "shape";      // md.sys.shape.corner.* corner scale
+@forward "elevation";  // md.sys.elevation.level* shadows
+@forward "stacking";   // z-index order for fixed and floating surfaces

package/src/sass/tokens/_motion.scss

@@ -0,0 +1,109 @@
+// Material Design 3 motion tokens: md.sys.motion.easing.* and
+// md.sys.motion.duration.*.
+//
+// Values match material-web/tokens/versions/latest/sass/_md-sys-motion.scss.
+// CSS cannot draw the emphasized curve, which M3 defines as a path, so
+// `emphasized` uses the same cubic-bezier as `standard`, as material-web does.
+//
+// Components read these instead of writing their own curves and times, so
+// one override changes the pace of everything on that step:
+//
+//   :root { --md-sys-motion-duration-short4: 150ms; }
+//
+// Off-scale times (a 2.1s indeterminate loop, a 180ms tooltip) stay literal.
+
+@use "sass:list";
+@use "sass:map";
+@use "../abstracts" as *;
+
+:root,
+:host {
+  --md-sys-motion-easing-standard: cubic-bezier(0.2, 0, 0, 1);
+  --md-sys-motion-easing-standard-accelerate: cubic-bezier(0.3, 0, 1, 1);
+  --md-sys-motion-easing-standard-decelerate: cubic-bezier(0, 0, 0, 1);
+  --md-sys-motion-easing-emphasized: cubic-bezier(0.2, 0, 0, 1);
+  --md-sys-motion-easing-emphasized-accelerate: cubic-bezier(0.3, 0, 0.8, 0.15);
+  --md-sys-motion-easing-emphasized-decelerate: cubic-bezier(0.05, 0.7, 0.1, 1);
+  --md-sys-motion-easing-linear: cubic-bezier(0, 0, 1, 1);
+
+  --md-sys-motion-duration-short1: 50ms;
+  --md-sys-motion-duration-short2: 100ms;
+  --md-sys-motion-duration-short3: 150ms;
+  --md-sys-motion-duration-short4: 200ms;
+  --md-sys-motion-duration-medium1: 250ms;
+  --md-sys-motion-duration-medium2: 300ms;
+  --md-sys-motion-duration-medium3: 350ms;
+  --md-sys-motion-duration-medium4: 400ms;
+  --md-sys-motion-duration-long1: 450ms;
+  --md-sys-motion-duration-long2: 500ms;
+  --md-sys-motion-duration-long3: 550ms;
+  --md-sys-motion-duration-long4: 600ms;
+  --md-sys-motion-duration-extra-long1: 700ms;
+  --md-sys-motion-duration-extra-long2: 800ms;
+  --md-sys-motion-duration-extra-long3: 900ms;
+  --md-sys-motion-duration-extra-long4: 1000ms;
+}
+
+// M3 Expressive springs: [damping ratio, stiffness] per speed and kind.
+// Spatial springs move and resize things; effects springs change color and
+// opacity and never overshoot. The expressive scheme only changes the
+// spatial ones. Values from Material's MotionScheme (standard and
+// expressive). Each becomes an easing token and a -duration token.
+$_springs: (
+  "standard": (
+    "fast-spatial": (0.9, 1400), "default-spatial": (0.9, 700), "slow-spatial": (0.9, 300),
+    "fast-effects": (1, 3800), "default-effects": (1, 1600), "slow-effects": (1, 800),
+  ),
+  "expressive": (
+    "fast-spatial": (0.6, 800), "default-spatial": (0.8, 380), "slow-spatial": (0.8, 200),
+  ),
+);
+
+@mixin _springs($scheme) {
+  @each $name, $spring in map.get($_springs, $scheme) {
+    $damping: list.nth($spring, 1);
+    $stiffness: list.nth($spring, 2);
+    --md-sys-motion-spring-#{$name}: #{spring($damping, $stiffness)};
+    --md-sys-motion-spring-#{$name}-duration: #{spring-duration($damping, $stiffness)};
+    // The spring itself, for motion solved at run time from where it is.
+    --md-sys-motion-spring-#{$name}-damping: #{$damping};
+    --md-sys-motion-spring-#{$name}-stiffness: #{$stiffness};
+  }
+}
+
+// Standard is the default; motion="expressive" on the root or a subtree
+// switches the spatial springs, and motion="standard" switches them back.
+:root,
+:host,
+[motion='standard'],
+:host([motion='standard']) {
+  @include _springs("standard");
+}
+
+[motion='expressive'],
+:host([motion='expressive']) {
+  @include _springs("expressive");
+}
+
+// Reduced motion, once for every component that reads these tokens: every
+// duration, scale step and spring alike, becomes 0s, so the change lands
+// without moving. No !important, so a page can still opt an element back in
+// for motion it needs. Off-scale literal times, such as the 2.1s progress
+// loop, are not tokens; their components cancel them in their own
+// reduced-motion rules.
+@media (prefers-reduced-motion: reduce) {
+  :root,
+  :host,
+  [motion],
+  :host([motion]) {
+    @each $step in ("short", "medium", "long", "extra-long") {
+      @for $i from 1 through 4 {
+        --md-sys-motion-duration-#{$step}#{$i}: 0s;
+      }
+    }
+    @each $name in map.keys(map.get($_springs, "standard")) {
+      --md-sys-motion-spring-#{$name}-duration: 0s;
+    }
+  }
+}
+