@expressivecss/expressive 0.14.1 → 0.16.0

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})");
+}

package/src/sass/abstracts/_variables.scss

@@ -7,16 +7,34 @@
 // inset, icon-only toolbar actions stopped being 48dp circles and picked up the
 // text-action pill instead.
 //
-// So the answer lives in one place. `i` stays in the list for markup written
-// before 0.8.0. Interpolate it inside :is() - never as a bare comma list, which
-// breaks out of its context (see $_bar in components/_navbar).
-$icon: ":is(i, .material-symbols, .material-symbols-outlined, .material-symbols-rounded, .material-symbols-sharp, .material-icons)" !default;
+// So the answer lives in one place. Interpolate it inside :is() - never as a
+// bare comma list, which breaks out of its context (see $_bar in
+// components/_navbar). A bare <i> is idiomatic text, not an icon, so it is
+// not in the list.
+$icon: ":is(.material-symbols, .material-symbols-outlined, .material-symbols-rounded, .material-symbols-sharp)" !default;
 
 // The label beside an icon: any span that is not itself an icon.
-$icon-label: "span:not(.material-symbols):not(.material-symbols-outlined):not(.material-symbols-rounded):not(.material-symbols-sharp):not(.material-icons)" !default;
+$icon-label: "span:not(.material-symbols):not(.material-symbols-outlined):not(.material-symbols-rounded):not(.material-symbols-sharp)" !default;
 
 // The up arrow on a change line (Stat, KPI). Rotate it 180deg for down.
 $trend-arrow: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M11 20V7.8l-5.6 5.6L4 12l8-8 8 8-1.4 1.4L13 7.8V20z'/%3E%3C/svg%3E") !default;
+// The drop-down chevron: a select's caret and a mega menu button's trailing icon.
+$caret-down: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='black' d='M7 10l5 5 5-5z'/%3E%3C/svg%3E") !default;
+
+// Mist Iris is the default seed for the generated ramps. Primary, secondary,
+// tertiary and neutral colors derive from it; the error ramp stays fixed. It
+// lives here rather than in tokens/_reference so `@use "expressive" with
+// ($md-source: ...)` reaches it: only abstracts is forwarded, and the layers
+// are loaded with meta.load-css(), which takes no configuration.
+$md-source: #c6a0f6 !default;
+
+// A control the user cannot operate, natively or by ARIA. The FAB menu and
+// toolbar-group hosts and .hoverable skip it through
+// :not(:where(#{$expressive-disabled})), which adds no specificity, so a
+// disabled control never lifts or takes an enabled tint. Prefixed because
+// abstracts is forwarded to consumers, and a bare $disabled would collide
+// with theirs; not !default, since it is not a setting.
+$expressive-disabled: ':is(:disabled, [disabled], .disabled, [aria-disabled="true"])';
 
 // Colors
 //
@@ -29,8 +47,8 @@ $link-color: var(--md-sys-color-primary) !default;
 // M3 Expressive color roles. The live tokens are --md-sys-color-#{role}.
 // 26 standard roles in six groups (primary, secondary, tertiary, error,
 // surface, outline), plus optional add-ons (fixed accents, the surface
-// container scale) and four legacy aliases (background, on-background,
-// surface-variant, surface-tint). Consumed by tokens/_theme.scss and
+// container scale). The pre-1.0 aliases background, on-background,
+// surface-variant and surface-tint were removed in 0.16.0. Consumed by tokens/_theme.scss and
 // utilities/_colors.scss so the token layer and the utility classes
 // cannot drift.
 $sys-color-roles: (
@@ -47,8 +65,7 @@ $sys-color-roles: (
   "surface-container-high", "surface-container-highest",
   "outline", "outline-variant",
   "inverse-surface", "inverse-on-surface", "inverse-primary",
-  "scrim", "shadow",
-  "background", "on-background", "surface-variant", "surface-tint"
+  "scrim", "shadow"
 ) !default;
 
 // Menu
@@ -86,7 +103,7 @@ $expressive-include-fonts: true !default;
 $expressive-glass: false !default;
 $expressive-glass-blur: 16px !default;
 $expressive-glass-opacity: 72% !default;
-$text-color: var(--md-sys-color-on-background) !default;
+$text-color: var(--md-sys-color-on-surface) !default;
 
 // Modern browsers default to 16px. M3's web conversion is SP_SIZE / 16 = rem;
 // flow text uses the same basis without overriding the user's browser setting.
@@ -120,11 +137,11 @@ $flow-text-to: 960px !default;      // the old loop's last step: 360px + 20 * 30
 // the group itself. A partial may not @use another partial, so a table two of
 // them share has to be here.
 $button-sizes: (
-  "xsmall": (height: 32px, icon: 20px, space: 12px, gap: 8px, outline: 1px, label: "label-large"),
-  "small": (height: 40px, icon: 20px, space: 16px, gap: 8px, outline: 1px, label: "label-large"),
-  "medium": (height: 56px, icon: 24px, space: 24px, gap: 8px, outline: 1px, label: "title-medium"),
-  "large": (height: 96px, icon: 32px, space: 48px, gap: 12px, outline: 2px, label: "headline-small"),
-  "xlarge": (height: 136px, icon: 40px, space: 64px, gap: 16px, outline: 3px, label: "headline-large"),
+  "xsmall": (height: 32px, icon: 20px, space: 12px, gap: 8px, outline: 1px, square: 12px, pressed: 8px, label: "label-large"),
+  "small": (height: 40px, icon: 20px, space: 16px, gap: 8px, outline: 1px, square: 12px, pressed: 8px, label: "label-large"),
+  "medium": (height: 56px, icon: 24px, space: 24px, gap: 8px, outline: 1px, square: 16px, pressed: 12px, label: "title-medium"),
+  "large": (height: 96px, icon: 32px, space: 48px, gap: 12px, outline: 2px, square: 28px, pressed: 16px, label: "headline-small"),
+  "xlarge": (height: 136px, icon: 40px, space: 64px, gap: 16px, outline: 3px, square: 28px, pressed: 16px, label: "headline-large"),
 );
 
 // Icon-button geometry is shared with button groups. A group-size class must
@@ -137,3 +154,14 @@ $icon-button-sizes: (
   "large": (height: 96px, icon: 32px, space: 32px, narrow: 16px, wide: 48px, square: 28px, pressed: 16px, outline: 2px),
   "xlarge": (height: 136px, icon: 40px, space: 48px, narrow: 32px, wide: 72px, square: 28px, pressed: 16px, outline: 3px),
 );
+
+// Material's fast-spatial spring (damping .9, stiffness 1400), sampled into a
+// CSS linear easing over a fixed window. Superseded by spring(0.9, 1400) and
+// the --md-sys-motion-spring-fast-spatial token, which button groups and the
+// keypad now read; kept so Sass that still names it compiles.
+$motion-fast-spatial: linear(
+  0, 0.056 5%, 0.1796 10%, 0.3252 15%, 0.4675 20%, 0.5936 25%,
+  0.6988 30%, 0.7828 35%, 0.8475 40%, 0.8959 45%, 0.931 50%,
+  0.9559 55%, 0.973 60%, 0.9845 65%, 0.9919 70%, 0.9965 75%,
+  0.9992 80%, 1.0006 85%, 1.0013 90%, 1.0015 95%, 1.0015
+);

package/src/sass/base/_fonts.scss

@@ -1,63 +1,76 @@
+@use "sass:map";
+@use "sass:string";
 @use "../abstracts" as *;
 
 // Self-hosted faces for the families the tokens and icon classes name.
 // Unlayered on purpose: @font-face inside a cascade layer is unreliable.
 // $expressive-font-path is relative to the compiled CSS (dist/css -> dist/fonts).
 
-@if $expressive-include-fonts {
-  @font-face {
-    font-family: "Material Symbols Outlined";
-    font-style: normal;
-    font-weight: 100 700;
-    font-display: block;
-    src: url("#{$expressive-font-path}/material-symbols-outlined.woff2") format("woff2");
-  }
+// Text subsets and their unicode-range, as Fontsource publishes them
+// (node_modules/@fontsource/*/400.css). scripts/copy-fonts.mjs copies the
+// same subsets. Arabic, Hebrew and Thai, which Noto Sans leaves out, come as
+// their own Noto families with only their script's range, so a page fetches
+// them only when it shows that script. CJK families are megabytes each, so
+// CJK text falls through to the system font the browser picks for the
+// element's lang.
+$_roboto-subsets: (
+  "latin": "U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD",
+  "latin-ext": "U+0100-02BA,U+02BD-02C5,U+02C7-02CC,U+02CE-02D7,U+02DD-02FF,U+0304,U+0308,U+0329,U+1D00-1DBF,U+1E00-1E9F,U+1EF2-1EFF,U+2020,U+20A0-20AB,U+20AD-20C0,U+2113,U+2C60-2C7F,U+A720-A7FF",
+  "cyrillic": "U+0301,U+0400-045F,U+0490-0491,U+04B0-04B1,U+2116",
+  "cyrillic-ext": "U+0460-052F,U+1C80-1C8A,U+20B4,U+2DE0-2DFF,U+A640-A69F,U+FE2E-FE2F",
+  "greek": "U+0370-0377,U+037A-037F,U+0384-038A,U+038C,U+038E-03A1,U+03A3-03FF",
+  "greek-ext": "U+1F00-1FFF",
+  "vietnamese": "U+0102-0103,U+0110-0111,U+0128-0129,U+0168-0169,U+01A0-01A1,U+01AF-01B0,U+0300-0301,U+0303-0304,U+0308-0309,U+0323,U+0329,U+1EA0-1EF9,U+20AB",
+);
 
-  @font-face {
-    font-family: "Material Symbols Rounded";
-    font-style: normal;
-    font-weight: 100 700;
-    font-display: block;
-    src: url("#{$expressive-font-path}/material-symbols-rounded.woff2") format("woff2");
-  }
+// Noto Sans covers Roboto's subsets and adds Devanagari.
+$_noto-sans-subsets: map.merge($_roboto-subsets, (
+  "devanagari": "U+0900-097F,U+1CD0-1CF9,U+200C-200D,U+20A8,U+20B9,U+20F0,U+25CC,U+A830-A839,U+A8E0-A8FF,U+11B00-11B09",
+));
 
-  @font-face {
-    font-family: "Material Symbols Sharp";
-    font-style: normal;
-    font-weight: 100 700;
-    font-display: block;
-    src: url("#{$expressive-font-path}/material-symbols-sharp.woff2") format("woff2");
-  }
+$_noto-sans-arabic-subsets: (
+  "arabic": "U+0600-06FF,U+0750-077F,U+0870-088E,U+0890-0891,U+0897-08E1,U+08E3-08FF,U+200C-200E,U+2010-2011,U+204F,U+2E41,U+FB50-FDFF,U+FE70-FE74,U+FE76-FEFC,U+102E0-102FB,U+10E60-10E7E,U+10EC2-10EC4,U+10EFC-10EFF,U+1EE00-1EEFF",
+);
 
-  @font-face {
-    font-family: "Roboto";
-    font-style: normal;
-    font-weight: 400;
-    font-display: swap;
-    src: url("#{$expressive-font-path}/roboto-latin-400.woff2") format("woff2");
-  }
+$_noto-sans-hebrew-subsets: (
+  "hebrew": "U+0307-0308,U+0590-05FF,U+200C-2010,U+20AA,U+25CC,U+FB1D-FB4F",
+);
 
-  @font-face {
-    font-family: "Roboto";
-    font-style: normal;
-    font-weight: 500;
-    font-display: swap;
-    src: url("#{$expressive-font-path}/roboto-latin-500.woff2") format("woff2");
-  }
+$_noto-sans-thai-subsets: (
+  "thai": "U+02D7,U+0303,U+0331,U+0E01-0E5B,U+200C-200D,U+25CC",
+);
 
-  @font-face {
-    font-family: "Noto Sans";
-    font-style: normal;
-    font-weight: 400;
-    font-display: swap;
-    src: url("#{$expressive-font-path}/noto-sans-latin-400.woff2") format("woff2");
+@if $expressive-include-fonts {
+  @each $style in "Outlined", "Rounded", "Sharp" {
+    @font-face {
+      font-family: "Material Symbols #{$style}";
+      font-style: normal;
+      font-weight: 100 700;
+      font-display: block;
+      src: url("#{$expressive-font-path}/material-symbols-#{string.to-lower-case($style)}.woff2") format("woff2");
+    }
   }
 
-  @font-face {
-    font-family: "Noto Sans";
-    font-style: normal;
-    font-weight: 500;
-    font-display: swap;
-    src: url("#{$expressive-font-path}/noto-sans-latin-500.woff2") format("woff2");
+  // One face per subset and weight. unicode-range lets the browser fetch
+  // only the subsets the page's text uses, and 700 only when it is rendered.
+  @each $file, $family, $subsets in
+    ("roboto", "Roboto", $_roboto-subsets),
+    ("noto-sans", "Noto Sans", $_noto-sans-subsets),
+    ("noto-sans-arabic", "Noto Sans Arabic", $_noto-sans-arabic-subsets),
+    ("noto-sans-hebrew", "Noto Sans Hebrew", $_noto-sans-hebrew-subsets),
+    ("noto-sans-thai", "Noto Sans Thai", $_noto-sans-thai-subsets)
+  {
+    @each $subset, $range in $subsets {
+      @each $weight in (400, 500, 700) {
+        @font-face {
+          font-family: $family;
+          font-style: normal;
+          font-weight: $weight;
+          font-display: swap;
+          src: url("#{$expressive-font-path}/#{$file}-#{$subset}-#{$weight}.woff2") format("woff2");
+          unicode-range: string.unquote($range);
+        }
+      }
+    }
   }
 }

package/src/sass/base/_global.scss

@@ -1,11 +1,15 @@
 @use "../abstracts" as *;
 
-// Element-level defaults only: box-sizing, links, blockquotes, icons, tables.
+// Element-level defaults only: box-sizing, links, blockquotes, tables, meters.
 //
 // Helper classes belong in utilities/, and anything that serves a single widget
 // belongs in that widget's partial - nothing here should name a component.
 
-html {
+// Each document anchor pairs with :host so a shadow-only load (see
+// src/sass/README.md, "Shadow roots") inherits the same defaults. The page
+// background stays on body: on :host it would paint the host element.
+html,
+:host {
   box-sizing: border-box;
 }
 
@@ -15,7 +19,11 @@ html {
 
 body {
   background-color: var(--md-sys-color-surface);
-  color: var(--md-sys-color-on-background);
+}
+
+body,
+:host {
+  color: $text-color;
 }
 
 button,
@@ -32,18 +40,18 @@ a {
   -webkit-tap-highlight-color: transparent; // Gets rid of tap active state
 }
 
-//  Blockquote
-blockquote { margin: 20px 0; padding-left: 1.5rem; border-left: 5px solid var(--md-sys-color-primary); }
-
-// <i> as an element - italics. The icon modifiers (.left, .right, .tiny ..)
-// used to live here, keyed on `i`, which silently tied them to one element:
-// writing an icon as the canonical <span class="material-symbols"> dropped
-// them. They now hang off the icon class list in components/_icons-material-design,
-// where the size modifiers already were, so they follow the class instead.
-i {
-  line-height: inherit;
+// A link inside running text needs a cue besides its color (WCAG 1.4.1), so
+// it keeps the underline. A link with a class is a component or a deliberate
+// style and stays bare; so does every link outside these text containers,
+// which is where navigation lists, menus and tabs put theirs.
+:where(p, dd, blockquote, figcaption, td) a:not([class]) {
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
 }
 
+//  Blockquote
+blockquote { margin: 20px 0; padding-inline-start: 1.5rem; border-inline-start: 5px solid var(--md-sys-color-primary); }
+
 // Tables
 table, th, td {
   border: none;
@@ -60,15 +68,15 @@ table {
       border-bottom: none;
     }
     tbody > tr:nth-child(odd) {
-      background-color: rgba(0, 0, 0, 0.08);
+      background-color: var(--md-sys-color-surface-container-high);
     }
   }
 
   &.highlight > tbody > tr {
-    transition: background-color .25s ease;
+    transition: background-color var(--md-sys-motion-duration-medium1) ease;
 
     &:hover {
-      background-color: rgba(0, 0, 0, 0.04);
+      background-color: state-layer(var(--md-sys-color-on-surface), "hover");
     }
   }
 
@@ -89,19 +97,14 @@ tr {
 
 td, th {
   padding: 15px 5px;
-  display: table-cell;
-  text-align: left;
+  text-align: start;
   vertical-align: middle;
-  border-radius: 0;
 }
 
 // Responsive Table
 @include bp-down("expanded") {
 
   table.responsive-table {
-    width: 100%;
-    border-collapse: collapse;
-    border-spacing: 0;
     display: block;
     position: relative;
 
@@ -113,16 +116,17 @@ td, th {
       margin: 0;
       vertical-align: top;
     }
-    th {
-      text-align: left;
-    }
     thead {
       display: block;
-      float: left;
+      float: inline-start;
+      // sort out borders
+      border: 0;
+      border-inline-end: 1px solid var(--md-sys-color-outline-variant);
 
       tr {
         display: block;
-        padding: 0 10px 0 0;
+        padding-block: 0;
+        padding-inline: 0 10px;
 
         th::before {
           content: "\00a0";
@@ -143,21 +147,88 @@ td, th {
     }
     th {
       display: block;
-      text-align: right;
+      text-align: end;
     }
     td {
       display: block;
       min-height: 1.25em;
-      text-align: left;
     }
     tr {
       border-bottom: none;
       padding: 0 10px;
     }
-    /* sort out borders */
-    thead {
-      border: 0;
-      border-right: 1px solid var(--md-sys-color-outline-variant);
-    }
+  }
+}
+
+// Meter: a measurement within a known range, such as storage used or password
+// strength, where <progress> is progress toward completion. The fill follows
+// the native low/high/optimum regions: primary in the optimum region, tertiary
+// one region away, error two away. Each engine's pseudo-element sits in its
+// own rule, because an engine drops a whole selector list naming one it does
+// not know.
+meter {
+  --md-comp-meter-track: var(--md-sys-color-secondary-container);
+  --md-comp-meter-optimum: var(--md-sys-color-primary);
+  --md-comp-meter-suboptimum: var(--md-sys-color-tertiary);
+  --md-comp-meter-even-less-good: var(--md-sys-color-error);
+  --md-comp-meter-thickness: 8px;
+  --md-comp-meter-shape: var(--md-sys-shape-corner-extra-small);
+
+  width: 100%;
+  height: var(--md-comp-meter-thickness);
+  border: 0;
+  border-radius: var(--md-comp-meter-shape);
+  background: var(--md-comp-meter-track);
+  vertical-align: middle;
+  appearance: none;
+
+  // Chromium puts the bar in the middle row of a 1fr 2fr 1fr grid, which
+  // halves it; spanning every row gives it the meter's full height.
+  &::-webkit-meter-bar {
+    grid-row: 1 / -1;
+    height: 100%;
+    border: 0;
+    border-radius: var(--md-comp-meter-shape);
+    background: var(--md-comp-meter-track);
+  }
+
+  &::-webkit-meter-optimum-value {
+    border-radius: var(--md-comp-meter-shape);
+    background: var(--md-comp-meter-optimum);
+  }
+
+  &::-webkit-meter-suboptimum-value {
+    border-radius: var(--md-comp-meter-shape);
+    background: var(--md-comp-meter-suboptimum);
+  }
+
+  &::-webkit-meter-even-less-good-value {
+    border-radius: var(--md-comp-meter-shape);
+    background: var(--md-comp-meter-even-less-good);
+  }
+
+  &::-moz-meter-bar {
+    border-radius: var(--md-comp-meter-shape);
+    background: var(--md-comp-meter-optimum);
+  }
+
+  &:-moz-meter-sub-optimum::-moz-meter-bar {
+    background: var(--md-comp-meter-suboptimum);
+  }
+
+  &:-moz-meter-sub-sub-optimum::-moz-meter-bar {
+    background: var(--md-comp-meter-even-less-good);
+  }
+
+  // Forced colors would repaint track and fill as the same Canvas.
+  @media (forced-colors: active) {
+    --md-comp-meter-track: Canvas;
+    --md-comp-meter-optimum: CanvasText;
+    --md-comp-meter-suboptimum: CanvasText;
+    --md-comp-meter-even-less-good: CanvasText;
+
+    forced-color-adjust: none;
+    outline: 1px solid CanvasText;
+    outline-offset: 1px;
   }
 }

package/src/sass/base/_index.scss

@@ -1,6 +1,8 @@
 // Element-level styling: no component classes live here.
 
 @forward "normalize";
-@forward "global";      // z-depth, spacing helpers, positioning, element defaults
+@forward "global";      // element defaults: links, blockquotes, tables
 @forward "typography";
 @forward "grid";        // .container, .row, .s1–.s12 … .xxl1–.xxl12
+@forward "prose";       // .prose: long-form content written as bare HTML
+@forward "print";       // paper defaults: light scheme, link targets, page breaks