@expressivecss/expressive 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,235 @@ the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-10-01
+
+### Added
+
+- Utility classes for shrinking flex and grid children, scrolling or clipping
+  overflow, logical inline spacing and text alignment, and text wrapping.
+  Physical spacing and alignment classes retain their existing behavior.
+- `.visually-hidden-focusable` hides skip links and other content until the
+  element or a descendant receives focus. Use it independently of `.visually-hidden`.
+
+### Fixed
+
+- Spacing output and documentation omit padding-auto classes, since CSS does
+  not accept `auto` for padding. Margin-auto helpers remain available.
+- Carousel preserves an active mouse drag when delayed resize work completes.
+- Snackbar ignores flick velocity after a pause of 100ms or more before release;
+  dragging past the distance threshold still dismisses it.
+- Tooltip supports `open()` in its public TypeScript declarations and honors
+  `open(true)` without requiring hover or focus.
+- NavigationRail leaves Escape to a nested component that already handled it.
+  Its own Escape collapse restores focus to the rail toggle while preserving
+  outside focus and focus moved by close callbacks.
+- Menu respects `closeOnClick` inside open and closed shadow roots, preserving
+  submenu navigation, outside dismissal, and touch scrolling.
+- Multiple FormSelect options with the same value can be selected and
+  deselected independently, matching their native option state.
+- Chips supports programmatic addition without an editable input and accepts
+  numeric ID `0` during initialization and addition. An empty autocomplete menu
+  does not prevent adding a custom chip.
+- Autocomplete keeps its open state synchronized with its Menu, accepts
+  preselected IDs before data loads, and bubbles selection changes to form
+  listeners. Chips lets an open suggestion menu handle Enter.
+- Timepicker reloads edited host values when opened and cancels obsolete clock
+  updates, so delayed transitions cannot overwrite newer edits or update a
+  destroyed instance.
+- Datepicker honors custom parsers during initialization and reopening, rejects
+  reversed range edits through every input path, and preserves an empty
+  single-date selection after clearing.
+- Each Datepicker range input emits its own change event. Generated date inputs
+  opt out of AutoInit so repeated initialization cannot create duplicate pickers.
+- Component `init()` methods return an empty array for empty element collections,
+  matching their TypeScript return types.
+- Datepicker can reopen a range when only its end date is set. Clearing
+  either endpoint preserves the other and removes incomplete range shading.
+- A cancelled Snackbar swipe cannot carry its velocity into the next gesture.
+- Bottom and side sheets recognize a recent flick when the release coordinates
+  match the last pointer move, while paused or reversed short drags stay open.
+- Carousel preserves ordinary button and link clicks inside slides while keeping
+  mouse dragging available, including in swipeable tab panels.
+- Chips autocomplete preserves the query while filtering and clears it after
+  an item is selected.
+- Destroying a Timepicker cancels pending automatic submission, so an old
+  instance cannot overwrite a replacement input value.
+- Datepicker and Timepicker confirmation buttons invoke their callbacks once
+  per Enter press. Both TypeScript option interfaces accept `autoSubmit: false`.
+- Closing a Menu preserves focus on an outside input or another control.
+- Docked Datepicker and Timepicker popovers account for their positioning
+  parent, including `.field` wrappers and scrolled containers.
+- Destroying Chips also destroys its owned Autocomplete and Menu.
+- Tooltip teardown restores authored rich content and preserves existing
+  description associations, allowing the same content to be initialized again.
+- Snackbars can reuse an element supplied through `snackbarId` without deleting
+  it or retaining callbacks and controls from an earlier instance.
+- A vertical touch swipe that starts on a carousel scrolls the page again, and
+  pinch-zoom works over it. The carousel tracks no longer restrict
+  `touch-action`.
+- In Firefox the top app bar is `surface` at rest instead of
+  `surface-container`. The scroll fill now runs only where `animation-timeline`
+  is supported.
+- `.slider.stops` draws its dots. Each dot sits at a step position on the
+  active track, including centered and right-to-left sliders. Vertical and
+  two-handle sliders show no dots.
+- In Firefox an indeterminate `<progress class="progress">` shows its track and
+  a moving 40% bar, which stays still under reduced motion.
+- In Firefox a date input with a Datepicker shows its value. The formatted
+  overlay only applies in engines that render it.
+- Mouse drag moves the carousel track again in the horizontal full-screen
+  layout and in `.uncontained.snap`. Snapping used to pull the track back on
+  every move.
+- Editing or clearing a Datepicker `<input type="date">` with the keyboard
+  updates the formatted date painted over the field in Chrome and Safari.
+  After the field lost focus it used to show the previous date.
+- Clicking a Datepicker date input no longer opens the browser's date picker on
+  top of a visible Datepicker calendar (`openByDefault` or `container`). When
+  the calendar is hidden, the default, the browser picker still opens.
+- Leading `.prefix` and trailing `.suffix` icons stay visible on a Datepicker
+  date input in Chrome and Safari. The input's filled background used to cover
+  them.
+- `.slider.stops` puts each dot at `min` plus a whole number of steps, so a
+  `step` that does not divide the range no longer spreads the dots over the
+  whole track. With no `step`, `step="any"`, or a zero or negative step, the
+  slider shows no dots. Dots follow the range input's direction and leave the
+  inset icon uncovered.
+- `Slider.destroy()` removes the custom properties it set on the input and its
+  host, so stop dots and the track fill no longer stay painted. Inline values
+  set before init come back.
+- A `<header>` that holds only a `nav.tabs` is no longer styled as a top app
+  bar, so it no longer sticks to the top of the page or takes the app bar fill.
+- Medium and large app bars no longer send the page back to the top when they
+  collapse. A short or slow scroll near the top used to snap back and leave the
+  bar switching between sizes. The bar now collapses once the page has
+  scrolled by the height it gives up, and expands when the page returns to the
+  top of the bar.
+
+### Changed
+
+- The ExpressiveCSS skill bundles the starter page and the five layout
+  templates under `assets/templates/`, and the Install and Design guides point
+  to them. The Install guide gives a plain `npm install` command, and its
+  minimum page no longer puts the page heading in an app bar without
+  destinations.
+- Skill guides put their steps under their own headings instead of under
+  "Do not use when". The framework contribution path moved to
+  `references/contributing.md`.
+- Component guides list the API reference subsections they leave out. Their
+  examples use real link targets, and menu actions are buttons. The Buttons
+  reference calls `circle` a round common button and points icon buttons to
+  `.icon-button`.
+- Documentation examples no longer use `href="#!"` in copyable code. Menu,
+  split-button, app-bar and tooltip actions are `<button type="button">`,
+  and code samples link to realistic paths. Live navigation demos on the docs
+  site keep `#!`. The app-bar Search icon is a button. The API reference drops
+  rendered demo text that had been copied into it, and the Lightbox guide
+  includes its options and methods.
+- The footer partial no longer carries sticky-footer rules. Their nested
+  `:has()` selector was invalid, so browsers had always dropped them. The
+  Footer page now gives the two rules to add yourself, as the API reference
+  already did.
+- The Auto Init page and the API reference list every component `AutoInit()`
+  starts. They add AppBar and ExpandingCard, give Cards its real selector, and
+  list both picker spellings, `.datepicker, .date-picker` and
+  `.timepicker, .time-picker`. Both name all eight
+  behaviors the bundle starts on import, including Dialogs, BottomSheets and
+  SideSheets, and call the range control Slider instead of Range.
+- Documentation code samples match their demos and the current framework. The
+  Date picker and Time picker samples select `.date-picker` and `.time-picker`,
+  the Slider samples and the M3 guidelines use `Expressive.Slider`, and card
+  samples drop the unstyled `supporting-text` class. The Grid, circular image,
+  character counter, snackbar dismiss and full-screen dialog samples now match
+  the demos next to them. The Scrollspy sample uses the canonical
+  `hide-on-compact-only` instead of the legacy `hide-on-small-only` alias.
+- Documentation no longer describes removed classes or markup. Typography
+  names `body-large`, `body-medium` and `body-small`, and Select describes the
+  `.field` wrapper the plugin reuses or creates instead of `.select-wrapper`.
+  Tabs no longer mentions `tabs-horizontal`, and Tooltips no longer says the
+  plugin adds `.material-tooltip`. Grid offsets use the Compact through
+  Extra-large breakpoint names.
+- Getting started lists `fonts/` and `modular.mjs` in the `dist/` tree and
+  the minified files in the project tree. Its README link opens the "Reduce
+  page downloads" section.
+- On the docs site, the Start navigation item opens the landing page again.
+  Slider demos keep their stop dots, and carousel demo links no longer point
+  at anchors that do not exist.
+
+## [0.11.0] - 2026-09-30
+
+### Added
+
+- `.visually-hidden` hides an element from sight and keeps it in the
+  accessibility tree, so screen readers still announce it. It exposes the
+  existing `visually-hidden` mixin, which now also clears the border and takes
+  an `$important` flag for the utility. The filter chip's checkbox uses the
+  mixin instead of its own copy.
+- `fieldset.plain` groups radios or checkboxes inside a surface that already
+  frames them. It has no outline, fill, padding, or margin from a preceding
+  fieldset, and its legend starts flush with the content.
+- The docs ship a downloadable starter page (`docs/public/starter.html`) and five
+  copyable responsive layouts: compact, navigation rail, expanded rail,
+  list-detail and dashboard.
+
+### Changed
+
+- Common buttons (`button`, `a.button`, `label.button`, every size and style)
+  reflow a label that does not fit. The label wraps between words, the button
+  grows from its size's container height, which is now a minimum, and it never
+  grows wider than its parent. A label that fits renders at the same size as
+  before; 4dp of block padding keeps wrapped lines off the edges. Circle
+  buttons, FABs, extended FABs, the chip delete button, carousel dots, Timepicker
+  AM/PM controls, and buttons in button groups, split buttons, toolbars, top app
+  bars, dialog and
+  sheet headers, navigation bars and rails, tabs, pagination and snackbars keep
+  one line at a fixed height. The file input trigger grows from its 48dp
+  minimum the same way. Dialog action rows drop their own copy of this rule.
+- Chips add 4dp of block padding, so a wrapped label no longer touches the
+  chip's edges. A chip that fits on one line keeps its 32dp height.
+- Every top app bar is pinned to the top of the page with `position: sticky`.
+  It no longer needs the `fixed` class.
+
+### Migration
+
+- A common button's container height is now a `min-height`. A rule that gives
+  a button a smaller `height` must also set `min-height`, or set
+  `--md-comp-filled-button-container-height` instead.
+- Remove `fixed` from top app bar headers; it has no effect. To let a bar
+  scroll away with the page, set `position: static` on its `<header>`.
+
+### Fixed
+
+- ScrollSpy honors per-section offsets and active classes, isolates tables of
+  contents through shared `getActiveElement` callbacks, and restores authored
+  offset styles on teardown. Native anchor navigation remains unchanged.
+
+- Carousel ignores stale scroll-completion events from earlier navigation, so
+  selecting a swipeable tab immediately after initialization keeps that selection.
+
+- FormSelect preserves every associated label when enhanced, including naming
+  order, label activation and authored naming overrides. Teardown restores label
+  attributes and removes generated label IDs.
+
+- FormSelect hides the native control from assistive technology, leaving one
+  named combobox. Required and custom validation errors appear beside the visible
+  field; the native select retains form values and validation rules. Static
+  validity checks preserve focus, and interactive validation forwards native
+  focus to the visible field, including in forms with mixed native controls.
+
+- Tabs resolves panel IDs directly, so numeric IDs and IDs containing dots,
+  colons or brackets work in normal and swipeable modes without selector errors
+  or accidental matches against other elements.
+
+- Autocomplete searches on input events, including paste, replacement and deletion
+  without key events. Keyboard typing does not repeat the search on keyup.
+
+- FormSelect restores the authored label and node order during teardown and
+  reinitialization, including when it creates the field wrapper.
+
+- Datepicker treats `YYYY-MM-DD` input as a local calendar date during
+  initialization, editing and reopening, so dates no longer shift backward in
+  timezones west of UTC. Impossible dates such as `2023-02-29` are rejected.
+
 ## [0.10.1] - 2026-09-22
 
 ### Added
@@ -19,7 +248,7 @@ the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - **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
+  anatomy cheat sheet, and retired 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
@@ -628,7 +857,7 @@ semantics sweep keeps rendering — nothing warns at runtime — so each
   the same promise with no keyboard model behind it. `semantics.json` records
   the rejection.
 
-  **Migration.** `.searchbar`, the pre-1.0 Materialize navbar search field,
+  **Migration.** `.searchbar`, the pre-1.0 navbar search field,
   is now an alias of `.search-bar` and moves out of `forms/_input-fields.scss`
   into `components/_search.scss`. Old markup keeps working and picks up the M3
   container; `tests/m3-naming.test.js` holds the alias to every rule.
@@ -974,7 +1203,7 @@ semantics sweep keeps rendering — nothing warns at runtime — so each
   `height` above and leave `full-screen` off.
 
 - **The coverflow carousel layout is gone.** `.coverflow` was the 3D
-  perspective tween inherited from the vendored MaterializeCSS source, and
+  perspective tween inherited from the older source, and
   Material 3 defines it at no layout and no size. It hand-wrote a momentum
   simulation the browser already performs — velocity smoothing over a
   `Date.now()` delta, exponential-decay easing toward a target, modular index
@@ -1141,7 +1370,7 @@ semantics sweep keeps rendering — nothing warns at runtime — so each
   instead of the spec's 56. Keyed on the shared `$icon` list now, the way
   `_buttons` and `_toolbar` already were.
 - **Five more tokens were declared or referenced but not both**, found by the
-  new check below. The time picker's AM/PM buttons referenced Materialize's
+  new check below. The time picker's AM/PM buttons referenced retired
   `--btn-padding` and `--btn-border-radius`, which no longer exist — the
   declarations were invalid at computed-value time, which does *not* fall back
   to the rule underneath, so the padding rendered as 0 while a base button rule
@@ -1522,7 +1751,7 @@ LLM-facing documentation, and the docs site's own templates.
 ### Fixed
 
 - **`llm.md` taught classes that do not exist.** It is the markup contract other
-  tools and models read, and several sections still carried Materialize-era
+  tools and models read, and several sections still carried retired
   names the Material Design 3 rewrite removed. Each replacement was verified
   against `dist/css/expressive.css` and `src/ts`:
   - `.btn-floating`, `.btn-large` and `.btn-small` (16 references) — a FAB is
@@ -1605,7 +1834,7 @@ guidelines document. No breaking changes.
 
 ## [0.5.0] - 2026-08-19
 
-The release that finishes moving the vendored Materialize surface onto Material
+The release that finishes moving the older component set onto Material
 Design 3 Expressive. Components with no M3 counterpart are gone, several were
 renamed to their M3 names, and the color layer now carries the full role set.
 Pre-1.0, so the breaking changes below are not gated behind a deprecation cycle
@@ -1690,7 +1919,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.10.1...HEAD
+[Unreleased]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.11.0...v0.12.0
+[0.11.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.10.1...v0.11.0
 [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

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 version `0.10.1` is under active development.
+> ExpressiveCSS version `0.12.0` is under active development.
 
 Documentation: [www.expressivecss.com](https://www.expressivecss.com)
 
@@ -93,6 +93,27 @@ loads fonts from `../fonts/`, so keep `dist/fonts/` next to `dist/css/`.
 
 ## Usage
 
+### Copy the starter
+
+After building the framework, copy the [basic starter](docs/public/starter.html)
+and the compiled assets into a new directory:
+
+```sh
+mkdir my-site
+cp docs/public/starter.html my-site/index.html
+cp -R dist my-site/dist
+```
+
+Open `my-site/index.html` in your browser. The template includes an app bar,
+responsive cards, a tooltip initialized with `AutoInit()`, and automatic light
+and dark themes. Edit the title and content to make it your own. Keep
+`dist/fonts/` beside `dist/css/` so the bundled fonts load.
+
+For complete app layouts, open the [layout gallery](https://www.expressivecss.com/layouts.html).
+The source templates are `docs/public/layout-*.html`: compact, navigation rail,
+expanded rail, list-detail, and dashboard. Copy any one as `index.html` with the
+same `dist/` directory.
+
 ### Browser bundle
 
 Load the compiled stylesheet and browser bundle, then initialize components after