@expressivecss/expressive 0.15.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expressivecss/expressive",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "ExpressiveCSS - a Material Design 3 front-end framework.",
   "license": "MIT",
   "author": "BaezFJ <baezdevs@gmail.com>",
@@ -73,16 +73,15 @@
     "build:css": "run-s build:fonts build:css:expanded build:css:min",
     "build:css:expanded": "sass src/sass/expressive.scss dist/css/expressive.css --style=expanded --source-map --load-path=src/sass",
     "build:css:min": "sass src/sass/expressive.scss dist/css/expressive.min.css --style=compressed --source-map --load-path=src/sass",
-    "build:js": "run-s build:js:esm build:js:cjs build:js:iife build:js:iife-min",
+    "build:js": "node scripts/build-js.mjs",
     "build:js:esm": "node scripts/build-esm.mjs",
     "build:js:cjs": "esbuild src/ts/index.ts --bundle --format=cjs --target=es2020 --outfile=dist/js/expressive.cjs --sourcemap",
     "build:js:iife": "esbuild src/ts/index.ts --bundle --format=iife --global-name=Expressive --target=es2020 --outfile=dist/js/expressive.js --sourcemap",
     "build:js:iife-min": "esbuild src/ts/index.ts --bundle --format=iife --global-name=Expressive --target=es2020 --outfile=dist/js/expressive.min.js --minify --sourcemap",
     "build:types": "tsc -p tsconfig.build.json",
-    "build:skill": "node scripts/gen-expressivecss-skill.mjs && node mcp/expressivecss/scripts/sync-guides.mjs",
+    "build:skill": "node scripts/gen-expressivecss-skill.mjs",
     "build:semantics": "node scripts/gen-semantics.mjs",
-    "resolve:expressivecss": "node skills/expressivecss/scripts/resolve-version.mjs",
-    "test:skill": "node --test tests/expressivecss-skill.test.js tests/expressivecss-version-resolution.test.js tests/expressivecss-component-decisions.test.js tests/expressivecss-skill-evals.test.js tests/expressivecss-codex-adapter.test.js tests/expressivecss-skill-benchmark.test.js tests/expressivecss-eval-browser.test.js tests/expressivecss-interface-quality.test.js tests/expressivecss-material-quality.test.js tests/expressivecss-eval-provenance.test.js tests/expressivecss-natural-discovery.test.js && npm run test:skill-evals",
+    "test:skill": "node --test tests/expressivecss-skill.test.js tests/expressivecss-version-resolution.test.js tests/expressivecss-component-decisions.test.js tests/expressivecss-skill-evals.test.js tests/expressivecss-codex-adapter.test.js tests/expressivecss-skill-benchmark.test.js tests/expressivecss-eval-browser.test.js tests/expressivecss-interface-quality.test.js tests/expressivecss-material-quality.test.js tests/expressivecss-eval-provenance.test.js tests/expressivecss-natural-discovery.test.js tests/expressivecss-migration-skill.test.js && npm run test:skill-evals",
     "test:skill-evals": "node scripts/eval-expressivecss-skill.mjs --responses=tests/fixtures/expressivecss-skill-evals/passing-responses.json",
     "docs:dev": "run-s build docs:watch",
     "docs:watch": "run-p watch:css watch:js docs:server",
@@ -91,7 +90,7 @@
     "docs:build:astro": "astro build --root docs",
     "docs:preview": "astro preview --root docs",
     "docs:verify": "node scripts/verify-site.mjs",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && npm run typecheck:strict",
     "test": "run-s build:js build:css test:run",
     "test:run": "node --test",
     "test:browser": "run-s build:js build:css test:browser:run",
@@ -100,19 +99,19 @@
     "test:visual:docker": "node scripts/run-docker.mjs --visual",
     "test:packages:docker": "node scripts/run-docker.mjs sh -c 'npm ci --prefix mcp/expressivecss && npm test --prefix mcp/expressivecss && npm run verify:packages'",
     "test:browser:critical": "node scripts/check-browser.mjs && node --test tests/expressivecss-cross-browser.test.js",
-    "test:browser:run": "node scripts/check-browser.mjs && node --test tests/*-browser.test.js",
-    "test:watch": "node --test --watch",
+    "test:browser:run": "node scripts/check-browser.mjs && node scripts/run-node-tests.mjs --browser",
     "test:visual": "node visual/run.mjs",
     "test:visual:report": "playwright show-report visual/report",
     "watch": "run-p watch:css watch:js",
     "watch:css": "sass --watch src/sass/expressive.scss:dist/css/expressive.css --style=expanded --source-map --load-path=src/sass",
-    "watch:js": "esbuild src/ts/index.ts --bundle --format=iife --global-name=Expressive --target=es2020 --outfile=dist/js/expressive.js --sourcemap --watch=forever",
-    "check:generated": "node scripts/gen-semantics.mjs --check && node scripts/gen-expressivecss-skill.mjs --check && node mcp/expressivecss/scripts/sync-guides.mjs --check",
+    "watch:js": "node scripts/build-js.mjs --watch",
+    "check:generated": "node scripts/gen-semantics.mjs --check && node scripts/gen-expressivecss-skill.mjs --check",
     "verify": "run-s build typecheck test:run check:generated docs:build:astro docs:verify",
     "verify:packages": "node scripts/verify-packages.mjs",
     "test:node": "node scripts/run-node-tests.mjs",
     "record:capabilities": "node scripts/record-capability-evidence.mjs --record",
-    "verify:consumer": "node scripts/lib/verify-consumer.mjs"
+    "verify:consumer": "node scripts/lib/verify-consumer.mjs",
+    "typecheck:strict": "tsc -p tsconfig.strict.json"
   },
   "engines": {
     "node": ">=20"
@@ -128,14 +127,18 @@
     "@fontsource-variable/material-symbols-rounded": "^5.3.4",
     "@fontsource-variable/material-symbols-sharp": "^5.3.4",
     "@fontsource/noto-sans": "^5.3.0",
+    "@fontsource/noto-sans-arabic": "^5.3.0",
+    "@fontsource/noto-sans-hebrew": "^5.3.0",
+    "@fontsource/noto-sans-thai": "^5.3.0",
     "@fontsource/roboto": "^5.3.0",
     "@playwright/test": "^1.56.0",
     "@tiptap/core": "^3.31.4",
     "@tiptap/pm": "^3.31.4",
     "@tiptap/starter-kit": "^3.31.4",
+    "alpinejs": "^3.17.5",
     "astro": "^7.2.8",
     "esbuild": "^0.28.2",
-    "fallow": "^3.23.0",
+    "fallow": "^3.33.1",
     "jsdom": "^30.0.1",
     "maplibre-gl": "^6.13.0",
     "npm-run-all2": "^9.0.3",
@@ -143,6 +146,7 @@
     "smol-toml": "^1.8.0",
     "turndown": "^7.2.4",
     "turndown-plugin-gfm": "^1.0.2",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "yaml": "^2.9.1"
   }
 }

package/src/sass/README.md

@@ -1,8 +1,8 @@
 # src/sass
 
 ```
-expressive.scss     entry point - decides cascade order, nothing else
-custom.scss         optional entry - selected partials in the same layers
+expressive.scss     entry point - forwards custom.scss with its defaults
+custom.scss         decides cascade order; optionally loads selected partials
 abstracts/          variables, functions, mixins        (emits no CSS)
 tokens/             M3 design tokens as :root custom properties
 base/               normalize, element defaults, typography, grid
@@ -13,7 +13,8 @@ utilities/          single-purpose helper classes
 `custom.scss` accepts `$components` and `$utilities` lists of partial names,
 in load order. `null` loads the complete group; `()` loads none. Tokens and base
 are always loaded, and the existing font configuration still applies. Its
-default output must equal `expressive.scss`. Use one entry per consumer sheet.
+default output is `expressive.scss`, which forwards it with `$components` and
+`$utilities` hidden. Use one entry per consumer sheet.
 Keep selections in the order of the existing indexes, with icons first, and
 include supporting partials. See the README's smaller-build recipes.
 
@@ -34,7 +35,7 @@ Everything else was removed.
 
 ## Two rules
 
-**1. Every partial starts with the same line.**
+**1. A partial that needs the shared helpers starts with the same line.**
 
 ```scss
 @use "../abstracts" as *;   // components/, base/, tokens/, utilities/
@@ -43,13 +44,13 @@ Everything else was removed.
 
 That single line brings in the breakpoint mixins, the Sass variables (grid,
 font sizes), `z-depth()`, and the `btn-*` mixins.
-There is never a second project-local `@use` to work out — if you find yourself
-adding one, see rule 2.
+A partial that uses none of them leaves the line out. There is never a second
+project-local `@use` to work out — if you find yourself adding one, see rule 2.
 
 **2. Nothing outside `abstracts/` is ever imported by another partial.**
 
 Dependencies point one way: everything depends on `abstracts`, `abstracts`
-depends on nothing. This is what keeps `expressive.scss` the only place cascade
+depends on nothing. This is what keeps `custom.scss` the only place cascade
 order is decided. (This is the Sass dependency graph, not the CSS `@layer`
 list — they happen to be described by the same word.)
 
@@ -61,11 +62,11 @@ decided where its CSS landed in the output. Use a mixin instead:
 ```scss
 // no
 @extend .z-depth-1;
-@extend .surface-variant;
+@extend .surface-container-highest;
 
 // yes
 @include z-depth("1");
-background-color: var(--md-sys-color-surface-variant);
+background-color: var(--md-sys-color-surface-container-highest);
 ```
 
 `@extend` within a single file (placeholders, `.btn-large { @extend .btn; }`) is
@@ -112,6 +113,11 @@ Setting `--md-source` re-themes the whole system at runtime, with no rebuild:
 :root { --md-source: #6750a4; }   /* everything but the error ramp follows */
 ```
 
+To change the compiled default instead, configure the Sass variable:
+`@use "expressive" with ($md-source: #6750a4);`. It lives in
+`abstracts/_variables.scss`, because only `abstracts` is forwarded and
+`meta.load-css()` passes no configuration to the layers.
+
 Two things about that file are load-bearing and non-obvious. **M3 "tone" is
 CIELAB L\*, not OKLCH lightness** — `oklch(40% c h)` is not tone 40, and using it
 drifts far past the just-noticeable difference; the `$tones` table is the
@@ -124,10 +130,10 @@ so they stay. Consume the live name:
 
 ```scss
 // no - locks the rule to one theme
-border-bottom: 1px solid var(--md-sys-color-surface-variant-light);
+border-bottom: 1px solid var(--md-sys-color-outline-variant-light);
 
 // yes
-border-bottom: 1px solid var(--md-sys-color-surface-variant);
+border-bottom: 1px solid var(--md-sys-color-outline-variant);
 ```
 
 `light-dark()` resolves against the element's used `color-scheme` at the point
@@ -222,11 +228,11 @@ the wrong file.
 | A colour/type token | `tokens/_reference.scss` | wire it up in `tokens/_theme.scss` |
 
 Anything under `abstracts/` that emits a selector is a bug: it would put CSS in
-the output at a position `expressive.scss` does not control.
+the output at a position `custom.scss` does not control.
 
 ## Cascade layers
 
-`expressive.scss` declares `@layer tokens, base, components, utilities;` and
+`custom.scss` declares `@layer tokens, base, components, utilities;` and
 loads each layer with `meta.load-css()` — `@forward` cannot appear inside
 `@layer`, which is the only reason the entry file uses a different mechanism
 from every other index file.
@@ -247,8 +253,11 @@ it is not. Layer order *reverses* for important declarations, but the rule that
 matters here is simpler: a normal declaration inside a layer loses to any
 unlayered declaration. Drop the flag from `.hide` and it stops beating a
 consumer's own `display` — silently, and in the common case. Classes whose whole
-job is to be unconditional (`.hide`, `.m-3`, the palette classes) keep it.
-
-A few rules in `components/` still use `!important` for UA resets
-(modal float, staggered-list transitions, textarea padding), not for
-JS-driven geometry. Tap target and the preloader no longer need the flag.
+job is to be unconditional (`.hide`, `.m-3`) keep it.
+
+A few rules in `components/` still use `!important`: reduced-motion resets,
+`.scale-transition` (it must replace the transition of whatever component it
+is added to), the map's overrides of MapLibre's own `!important` styles, and
+the print rules that hide navigation, snackbars, tooltips and the FAB menu.
+None of them is for JS-driven geometry. Tap target, the circular progress
+indicator and `.expressive-textarea` padding no longer need the flag.

package/src/sass/abstracts/_elevation.scss

@@ -6,8 +6,9 @@
 // only resolves if the extending partial loads the module that defines the
 // class, which forced every component to `@use` a CSS-emitting file and let
 // the dependency graph - not expressive.scss - decide the output order.
-// The `.z-depth-N` classes in utilities/_z-depth.scss are generated from this map,
-// so the class list and the mixin can never drift apart.
+// The `.z-depth-N` classes in utilities/_z-depth.scss and the
+// --md-sys-elevation-level* tokens in tokens/_elevation.scss are generated
+// from this map, so the classes, the tokens and the mixin cannot drift apart.
 
 $elevations: (
   "0": none,
@@ -19,15 +20,20 @@ $elevations: (
   "5": (0 24px 38px 3px rgba(0, 0, 0, 0.14), 0 9px 46px 8px rgba(0, 0, 0, 0.12), 0 11px 15px -7px rgba(0, 0, 0, 0.2))
 ) !default;
 
-@mixin z-depth($level) {
+@mixin z-depth($level, $important: false) {
   $key: "#{$level}";
   @if not map.has-key($elevations, $key) {
     @error "Unknown elevation `#{$level}`. Available: #{map.keys($elevations)}.";
   }
-  $shadow: map.get($elevations, $key);
-  @if $shadow == none {
-    // Level 0 stays !important: it is used to cancel a shadow a component set.
-    box-shadow: none !important;
+  // Read the system token, so a theme can change a level at runtime;
+  // tokens/_elevation.scss emits one per key of this map.
+  $shadow: var(--md-sys-elevation-level#{$key});
+  // Only the .z-depth-0 utility and the map popup pass $important; the popup
+  // has to beat maplibre-gl.css, which is unlayered. Inside the components
+  // layer an !important would beat every unlayered consumer rule, so a
+  // component that cancels a shadow has to out-specify the rule that set it.
+  @if $important {
+    box-shadow: $shadow !important;
   } @else {
     box-shadow: $shadow;
   }

package/src/sass/abstracts/_index.scss

@@ -5,3 +5,4 @@
 @forward "breakpoints";  // $breakpoints map + bp-up()/bp-down()/bp-between()
 @forward "variables";    // Sass-time knobs: grid, font sizes, flow text
 @forward "mixins";       // btn-*, focus-visible, chart()
+@forward "spring";       // spring(), spring-duration(): M3 springs as linear() easings