@expressivecss/expressive 0.9.1 → 0.10.1

package/CHANGELOG.md

@@ -5,6 +5,187 @@ the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.10.1] - 2026-09-22
+
+### Added
+
+- Flex helpers: `.flex`, `.inline-flex`, `.flex-column`, `.flex-wrap`,
+  `.justify-start|center|end|between`, `.align-start|center|end|stretch`,
+  `.flex-1`, `.flex-none`, and `.gap-0` to `.gap-6` on the spacing scale. One
+  declaration per class, in the utilities layer; the helpers page, `llm.md`,
+  and the skill's helper reference document them.
+
+### Changed
+
+- **Offline design context for the ExpressiveCSS skill.** The generator now
+  copies the hard rules, window-size tables, component chooser, screen recipes,
+  anatomy cheat sheet, and Materialize name map from `m3-guidelines.md` into
+  `skills/expressivecss/references/design-rules.md`, and the root, Design,
+  Usage, and Install guides route to it. JavaScript component guides inline the
+  options table and method names from `llm.md`. The Install guide carries a
+  complete page skeleton. The Design guide states the framework spacing scale
+  and control-text rules. Six catalogue entries that repeated their page tagline
+  as the selection rule now say when to use the component.
+
+- The ExpressiveCSS skill tells agents without an MCP client to run
+  `expressivecss-lint` from `@expressivecss/mcp-server` on the markup files they
+  touched before finishing.
+
+## [0.10.0] - 2026-09-18
+
+### Fixed
+
+- Connected button groups preserve equal-width items when translated labels
+  exceed the available width. The group expands inside an overflow container
+  instead of letting labels overlap adjacent controls.
+
+- Bottom and floating sheets keep long bodies scrollable and action rows reachable
+  at compact widths with enlarged text. Shared dialog headings and action labels
+  wrap instead of overflowing their inset container without resizing icon buttons
+  or FABs.
+
+- Datepicker initializes multiple-date defaults safely, keeps generated inputs
+  synchronized when selections shrink or grow, and preserves the original input
+  when cleared. Range-end inputs supplied by applications receive input and
+  keyboard handlers. Teardown removes generated fields and their listeners.
+
+- Timepicker digital fields synchronize native input events, including paste,
+  without depending on keyup. Invalid edits restore the last valid value on blur;
+  empty fields display the same fallback values they submit. Twelve-hour defaults
+  handle midnight, noon, 24-hour input strings and lowercase AM/PM consistently.
+
+- Lightbox cancels interrupted transitions, honors mounted reduced-motion changes,
+  preserves teardown focus and releases shared ancestor overflow after the last
+  open instance closes. Canceled transitions no longer report completion.
+  Overlay dismissal stays closed inside button triggers, and shadow-root teardown
+  respects focus moved outside the root by application handlers.
+
+- Enhanced selects synchronize native form resets, selection semantics and
+  refreshed disabled states. Disabled optgroups cannot be selected, and refresh
+  preserves focus on a surviving option in an open menu and rebinds reset handling
+  after form-owner changes.
+
+- Pane layouts use the nearest ancestor query-container width, with viewport
+  fallback, for columns, compact visibility, margins and dividers. Long footer
+  actions wrap without changing application-owned pane selection or icon-button sizes.
+
+- App-bar search dialogs stay closed during native focus restoration and reopen
+  on a fresh focus or click. Teardown removes the search activation listeners.
+
+- Tabs keep swipe selection, `aria-current`, and the `onShow` panel synchronized
+  without duplicate callbacks. Swipeable teardown restores panel positions and
+  owned state; initialization above `responsiveThreshold` uses ordinary panels.
+  Initial hash selection takes precedence over stale authored panel state.
+
+- Side sheets mirror dragging, entry motion and modal corners in RTL while
+  preserving logical start/end aliases. Long headings and action rows wrap.
+  Side and bottom sheets ignore secondary-pointer cancellation and clear drag
+  state when closed, removed, or interrupted by another primary press, including
+  close/reopen and remove/reattach sequences within one JavaScript task.
+
+- Carousel mirrors horizontal navigation and scroll placement in RTL, leaves
+  editable keys alone, and keeps auto-advance suspended during internal focus
+  moves. Mounted reduced-motion changes preserve explicit pause and stop
+  in-flight smooth scrolling. Native gestures cancel deferred recentering. Teardown
+  cancels scroll-completion timers and listeners. The docs demonstrate an
+  application-owned pause/resume button using the existing methods.
+
+- Slider labels and track gaps account for native handle travel in LTR, RTL and
+  vertical layouts. Paired inputs accept native track clicks and their vertical
+  track resizes with the inputs. Application input events update values without
+  dragging, and forced-colors tracks use system colors.
+
+- Chips delete the focused token with Backspace/Delete and recover focus without
+  overriding deletion callbacks. Destroying one instance preserves other instances'
+  keyboard handlers. Input chips no longer inherit floating-label positioning;
+  long labels wrap without shrinking their delete controls.
+
+- Closing menus immediately exclude their content from keyboard focus and
+  preserve focus moved by close callbacks. Nested keyboard navigation and
+  typeahead stay in their active menu; RTL flyouts mirror their keys and avoid
+  either viewport edge. Returning focus to a parent no longer reopens a flyout.
+
+- Native and custom progress indicators use system colors in forced-colors mode.
+  Empty linear tracks remain outlined, circular values retain a visible track,
+  and the legacy preloader stops rotating under reduced motion.
+
+- Custom linear progress fills and indeterminate motion follow the inherited
+  text direction, including RTL and nested direction overrides. Reduced-motion
+  static fills use the same starting edge.
+
+- Autocomplete exposes localized loading, result and multi-selection updates
+  through a polite live region. Teardown removes owned status elements and Menu
+  listeners, and late results after destruction are ignored.
+
+- Date picker calendars support a single Tab stop, arrow keys, Home/End,
+  PageUp/PageDown and Shift for year navigation. Redraws preserve calendar focus,
+  and disabled days expose their unavailable state without allowing selection.
+
+- Time picker hour/minute inputs have localized accessible names. Native AM/PM
+  buttons expose selected state and support Enter and Space without submitting
+  forms. Docked opening focuses the visible hour input; 24-hour entry accepts 00.
+
+### Migration
+
+- Snackbars with `action` now default to `displayLength: Infinity` and
+  `dismissible: true`. Explicit options still override these defaults. Custom
+  template controls need these options explicitly. Timed feedback needs an
+  equivalent persistent message in the application.
+
+- Replace `circle extra small` with `circle extra` for the 56dp FAB.
+  Extended FABs require an explicit size: replace sizeless `extend` with
+  `extend small`, or choose `extend medium` or `extend large`.
+  Use primary, secondary or tertiary container colors instead of surface-colored
+  FABs. General surface utilities remain available for other components.
+
+- Replace FAB speed-dial wrappers `.fab` and `.fixed-action-btn` with
+  `.fab-menu` and labelled actions. Remove `direction`, `hoverEnabled`,
+  `toolbarEnabled` and their markup switches. Use a toolbar for persistent
+  commands instead of FAB-to-toolbar expansion.
+
+- Replace banners with native inline messages for persistent nonblocking issues,
+  snackbars for temporary feedback, or dialogs for blocking decisions.
+  Remove banner classes, tokens and custom Sass imports. The existing
+  `/banners.html` route now explains the migration.
+
+- Replace `.floating-sheet` with a dialog for blocking work, a bottom sheet on
+  compact layouts, or a side sheet for optional content on wider layouts.
+
+- Replace `.bottom-app-bar` with `.toolbar.docked` or `.toolbar.fixed`. Place an
+  adjacent FAB in `.toolbar-group` when the layout needs one.
+- Replace `.navigation-drawer`, `.sidenav`, `NavigationDrawer`, and `Sidenav`
+  with `NavigationRail`. Use a navigation bar on compact layouts when the same
+  hierarchy fits; use a native full-screen dialog for a larger compact menu.
+- Replace `.segmented-button` with `.button-group.connected`. Keep native radio
+  or checkbox inputs when form submission is required, and synchronize button
+  state with those inputs in application code.
+
+### Changed
+
+- Escape dismisses a focused snackbar without closing its parent dialog.
+  Dismissal and replacement recover focus when it remains inside the snackbar;
+  closing controls are inert, and application-directed focus is preserved.
+
+- The documentation shell now uses a five-category rail with a page list on
+  wide layouts and a native full-screen navigation dialog on compact layouts.
+  Removed component URLs redirect to their replacement documentation.
+
+### Removed
+
+- The 40dp small FAB and baseline sizeless extended FAB styling. Current small
+  extended FABs, medium/large FABs and FAB menus remain supported.
+
+- FAB speed-dial styling, hover/directional layouts, toolbar expansion, and
+  legacy AutoInit selectors. The `FloatingActionButton` API now serves FAB menus.
+
+- Banner Sass, component semantics, generated component guides and variant tests.
+
+- Floating sheet Sass, documentation, semantics, generated guides and tests.
+
+- Bottom app bar Sass, navigation drawer Sass and runtime APIs, segmented
+  button Sass, their documentation pages, semantics, generated guides, and
+  component-specific tests.
+
 ## [0.9.1] - 2026-09-08
 
 Includes the fixes from [#140](https://github.com/BaezFJ/ExpressiveCSS/pull/140).
@@ -1509,7 +1690,9 @@ are no compatibility aliases.
 - `.tabs` nested in a header or app bar as a secondary row. `.tabs` is a
   standalone component; the `.tabs.transparent` app bar variant is gone with it.
 
-[Unreleased]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.9.1...HEAD
+[Unreleased]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.10.1...HEAD
+[0.10.1]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.10.0...v0.10.1
+[0.10.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.9.1...v0.10.0
 [0.9.1]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.9.0...v0.9.1
 [0.9.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.7.0...v0.8.0

package/README.md

@@ -4,7 +4,7 @@ ExpressiveCSS is a Material Design 3 front-end framework built with Sass and
 TypeScript. It provides theme tokens, layout and utility classes, styled form
 controls, and JavaScript components in browser, ES module, and CommonJS builds.
 
-> ExpressiveCSS is currently at version `0.9.1` and under active development.
+> ExpressiveCSS version `0.10.1` is under active development.
 
 Documentation: [www.expressivecss.com](https://www.expressivecss.com)
 
@@ -24,14 +24,14 @@ Documentation: [www.expressivecss.com](https://www.expressivecss.com)
 - [Node.js](https://nodejs.org/) 20 or newer
 - npm
 
-Use Node 24 for repository development, selected by `.nvmrc`. The framework's
-runtime compatibility range remains unchanged. See [CONTRIBUTING.md](CONTRIBUTING.md)
+Use Node 24 for repository development, selected by `.nvmrc`. The framework still
+supports its existing runtime compatibility range. See [CONTRIBUTING.md](CONTRIBUTING.md)
 for setup, checks, and the community workflow.
 
 ## MCP server for AI workflows
 
-This repository includes a local MCP server at `mcp/expressivecss/` that exposes an
-ExpressiveCSS design-to-QA workflow:
+A local MCP server at `mcp/expressivecss/` provides an ExpressiveCSS design-to-QA
+workflow:
 
 - Setup Expert
 - Rules Enforcer
@@ -43,7 +43,7 @@ ExpressiveCSS design-to-QA workflow:
 The MCP entry point is `mcp/expressivecss/server.js`, with sample config in
 `mcp/expressivecss/mcp.json`.
 
-Quick start:
+Start the server:
 
 ```sh
 cd mcp/expressivecss
@@ -51,7 +51,7 @@ npm ci
 node server.js
 ```
 
-To use it with your MCP client, point the command to:
+Configure your MCP client with either command:
 
 - `node mcp/expressivecss/server.js`
 - or `node ./server.js` from `mcp/expressivecss` as the working directory.
@@ -65,7 +65,7 @@ npm ci
 npm run build
 ```
 
-The compiled assets are written to `dist/`:
+The build writes compiled assets to `dist/`:
 
 ```text
 dist/
@@ -88,16 +88,15 @@ dist/
 └── types/
 ```
 
-Source maps are produced alongside the CSS and JavaScript bundles. The
-stylesheet loads fonts from `../fonts/`, so keep `dist/fonts/` next to
-`dist/css/`.
+The build writes source maps beside the CSS and JavaScript bundles. The stylesheet
+loads fonts from `../fonts/`, so keep `dist/fonts/` next to `dist/css/`.
 
 ## Usage
 
 ### Browser bundle
 
-Include the compiled stylesheet and browser bundle, then initialize components
-after the page has loaded:
+Load the compiled stylesheet and browser bundle, then initialize components after
+the page loads:
 
 ```html
 <link rel="stylesheet" href="dist/css/expressive.min.css">
@@ -127,9 +126,8 @@ const element = document.querySelector('.custom-tooltip');
 Tooltip.init(element, { position: 'top' });
 ```
 
-`AutoInit()` scans `document.body` by default. Pass a container to limit the
-scan, or add the `no-autoinit` class to an element that should be initialized
-manually:
+`AutoInit()` scans `document.body` by default. Pass a container to limit the scan.
+Add the `no-autoinit` class to any element you want to initialize manually:
 
 ```js
 AutoInit(document.querySelector('#app'), {
@@ -148,8 +146,164 @@ Use the framework's Sass entry point in another Sass project:
 @use "@expressivecss/expressive/src/sass/expressive";
 ```
 
-When working directly in this repository, the entry point is
-`src/sass/expressive.scss`.
+For work in this repository, the Sass entry point is `src/sass/expressive.scss`.
+
+### Reduce page downloads
+
+Use the optional ESM entry so a bundler can remove unused components:
+
+```ts
+import { Tabs } from '@expressivecss/expressive/modular';
+import type { TabsOptions } from '@expressivecss/expressive/modular';
+
+const tabs = Tabs.init(document.querySelector('.tabs'));
+```
+
+The type import supports TypeScript consumers. Initialize Tabs after its markup
+exists, and call `tabs.destroy()` when removing it. The modular entry does not
+initialize components on import. `AutoInit` remains available, but calling it
+includes the full registry. The root entry retains the existing shared behaviors.
+Both ESM entries share constructors. Copy the entire `dist/js` directory when
+hosting ESM files directly. Direct browser imports do not remove unused exports.
+The existing single-file IIFE and CommonJS builds remain available.
+
+| Feature | Initialization with the modular entry |
+| --- | --- |
+| AppBar, Autocomplete, FloatingActionButton, ButtonGroup, Carousel, CharacterCounter, Datepicker, Menu, Lightbox, ScrollSpy, FormSelect, NavigationRail, Tabs, Timepicker, Tooltip | Call the component's `.init(element, options)` |
+| Cards, ExpandingCard, Slider | Call `.init(element, options)` for owned elements, or `.Init()` once to discover matching document elements |
+| Chips | Call `.init()` for managed chips; use `Chips.Init()` once for removal of static chips |
+| Snackbar | Use the existing Snackbar constructor |
+| Input validation, textarea resize, file input paths | Call `Forms.Init()` once after choosing these enhancements |
+| Dialog light dismissal | Call `Dialogs.Init()` once |
+| Bottom-sheet drag dismissal | Call `BottomSheets.Init()` once; add `Dialogs.Init()` for light dismissal |
+| Side-sheet drag dismissal | Call `SideSheets.Init()` once; add `Dialogs.Init()` for light dismissal |
+
+`Range` retains its Slider alias. Component initializers include internal
+dependencies such as Menu in FormSelect, FormSelect in Datepicker, and Carousel in
+swipeable Tabs. Do not initialize those instances separately. Document behaviors
+apply to the whole page, so do not repeat their `.Init()` calls on route changes or
+alongside the root entry.
+
+Choose Sass partials with the custom entry. With Sass's Node package importer,
+compile using `sass --pkg-importer=node app.scss app.css`:
+
+```scss
+@use "pkg:@expressivecss/expressive/scss/custom" with (
+  $components: ("icons-material-design", "tabs", "carousel"),
+  $utilities: ()
+);
+```
+
+This Tabs recipe includes styling for the swipeable option. For FormSelect and
+Datepicker, use this complete recipe instead:
+
+```scss
+@use "pkg:@expressivecss/expressive/scss/custom" with (
+  $components: ("icons-material-design", "buttons", "menu", "forms", "datepicker"),
+  $utilities: ()
+);
+```
+
+```js
+import { Forms, FormSelect, Datepicker } from '@expressivecss/expressive/modular';
+
+Forms.Init();
+const select = FormSelect.init(document.querySelector('#choice'));
+const datepicker = Datepicker.init(document.querySelector('#date'), { openByDefault: true });
+```
+
+Destroy both component instances when removing that view. Add `"docked-display"`
+before `"forms"` if using the picker's optional docked display plugin.
+
+Tokens and base styles are always included. Lists load in the order written within
+the original cascade layers. Partial names are relative to `components/` or
+`utilities/`, without underscores or extensions. Keep icons first and follow the
+order in the corresponding `_index.scss` when combining recipes. Add the supporting
+partials required by your markup. For example, `$utilities: ("spacing",
+"visibility")` includes those helpers. A `null` list includes the complete group by
+default; `()` omits it. An unknown partial fails compilation.
+
+Bundlers that resolve Sass package paths can use
+`@expressivecss/expressive/scss/custom`; plain Sass with a `node_modules` load path
+can use `@expressivecss/expressive/src/sass/custom`. Import one framework Sass
+entry per stylesheet. The original full entry and compiled CSS are unchanged.
+
+#### Smaller icon fonts
+
+Browsers fetch only the font families used on the page. Using outlined icons alone
+avoids downloading the rounded and sharp fonts. To reduce the outlined font, create
+a subset with your own font tooling and turn off the bundled font declarations:
+
+```scss
+@use "pkg:@expressivecss/expressive/scss/custom" with (
+  $components: ("icons-material-design", "tabs", "carousel"),
+  $utilities: (),
+  $expressive-include-fonts: false
+);
+
+@font-face {
+  font-family: "Material Symbols Outlined";
+  font-style: normal;
+  font-weight: 100 700;
+  font-display: block;
+  src: url("/assets/icons-outlined-subset.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Roboto";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("/assets/roboto-latin-400.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Roboto";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url("/assets/roboto-latin-500.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Noto Sans";
+  font-style: normal;
+  font-weight: 400;
+  font-display: swap;
+  src: url("/assets/noto-sans-latin-400.woff2") format("woff2");
+}
+
+@font-face {
+  font-family: "Noto Sans";
+  font-style: normal;
+  font-weight: 500;
+  font-display: swap;
+  src: url("/assets/noto-sans-latin-500.woff2") format("woff2");
+}
+```
+
+Copy the four text fonts from `dist/fonts` into `/assets`, along with their license
+notices. Turning off the bundled faces also disables the text fonts. The declarations
+above restore their existing names and weights. Supply corresponding subset faces
+for rounded or sharp icons if the site uses them. Retain ligature shaping and the
+`opsz`, `wght`, `FILL`, and `GRAD` axes in each variable subset.
+
+Include icon names from templates, dynamic content, and framework-generated UI:
+
+| Source | Required icon name |
+| --- | --- |
+| Chips removal buttons | `close`, using the configurable `closeIconClass` family |
+| Snackbar dismissal button | `close` when the dismissal button is enabled |
+| Expandable navigation rail summaries | `expand_more`, generated by CSS |
+
+FormSelect uses CSS masks for its caret and selection marks. Datepicker uses text
+for its configurable previous/next labels. By default, neither requires an
+icon-font glyph. Custom markup and option values may add requirements. Subsets do
+not cover new icons automatically, so retain full fonts for unrestricted icon names.
+
+After building, run `node --test tests/selective-builds.test.js`. It records raw,
+gzip, and Brotli sizes in `.cache/selective-builds/sizes.json`. The browser suite
+records font requests and full/selective screenshots separately in that directory.
 
 ### Themes
 
@@ -167,7 +321,7 @@ document.documentElement.setAttribute('theme', 'dark');
 
 ## Development
 
-Available npm commands include:
+The repository provides these npm commands:
 
 | Command | Purpose |
 | --- | --- |
@@ -190,13 +344,12 @@ Run the documentation and smoke-test site:
 npm run docs:dev
 ```
 
-This builds the framework, then starts the Sass and esbuild watchers alongside
-the documentation server. Refresh the browser to see source changes. Astro
-prints the server URL.
+This command builds the framework, then starts the Sass and esbuild watchers with
+the documentation server. Refresh the browser to see source changes. Astro prints
+the server URL.
 
-It is the same site published at
-[www.expressivecss.com](https://www.expressivecss.com), authored in
-`docs/src/`.
+The documentation source lives in `docs/src/` and is published at
+[www.expressivecss.com](https://www.expressivecss.com).
 
 ## Project structure