@expressivecss/expressive 0.12.0 → 0.14.1

package/CHANGELOG.md

@@ -5,6 +5,340 @@ the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-10-11
+
+### Fixed
+
+- The capability roadmap's source links point at a commit on `master`. The
+  0.14.0 links pointed at a pull request commit that the squash merge left
+  off `master`, which stopped the 0.14.0 release before it reached npm. A
+  test now fails when the pinned commit is not an ancestor of the checkout.
+  0.14.1 contains the 0.14.0 changes below.
+
+## [0.14.0] - 2026-10-11
+
+### Added
+
+- The `expressivecss-review` agent skill reviews a page, template, fragment
+  or screenshot with five specialist subagents (theme and tokens, layout,
+  component markup, lifecycle and accessibility, framework rules). It reuses
+  the `expressivecss` guides, version resolver and `expressivecss-lint`, and
+  returns one report scored out of 100 with five 20-point sections. One or two
+  critical findings cap the score at 69, and three or more at 49.
+- `.map` is an interactive map built on MapLibre. The page installs
+  `maplibre-gl` and passes the module to `MapView.init()`; ExpressiveCSS does
+  not bundle it. `.map-marker` children sit at their `data-lng-lat`, can open
+  a `.map-popup` named by `aria-controls`, show a `.map-marker-label` and be
+  dragged with `data-draggable`. `.map-controls` buttons zoom, reset north,
+  locate the reader and go full screen. `addRoute()`, `addArcs()` and
+  `addClusters()` draw data in theme colors. The default OpenFreeMap style
+  follows the light or dark theme.
+- `.confetti` bursts theme-colored confetti. A button with the class bursts
+  from its center over the page when clicked, a `<canvas class="confetti">`
+  bursts inside its own box, and `Expressive.Confetti.fire(options)` bursts
+  over the page from script. Options cover the count, angle, spread, speed,
+  gravity, drift, colors, shapes and size. The page canvas draws above an
+  open modal dialog and lets clicks through. Nothing is drawn when the reader
+  prefers reduced motion.
+- `<canvas class="particles">` fills its positioned ancestor with drifting
+  dots in the theme's on-surface color that lean toward the pointer. Options
+  cover the count, size, color, drift and how far and how fast the dots
+  follow the pointer. The canvas lets clicks through, and under reduced
+  motion the dots are drawn once and stay still.
+
+### Changed
+
+- The docs site has a new shell. A rail holds the five catalogue groups from
+  840px, with the current group's pages beside it from 1200px. Below 1200px
+  the menu button opens the catalogue in a side sheet. Each page opens with a
+  breadcrumb, title, description and a "View as Markdown" link, and the table
+  of contents sits in a sticky column. Page content and URLs are unchanged.
+- The `expressivecss` skill is version 0.10.0. It adds guides for map,
+  confetti and particles. Its version resolver sizes file reads to the file
+  and reports a file that grows during a read as changed.
+
+### Fixed
+
+- Idle components no longer listen to the whole document. Carousel attaches
+  its pointer listeners while a mouse press is down, Tooltip listens for Escape
+  while open, and the docked date picker listens for outside clicks while
+  shown.
+- Calling `Forms.Init()`, `BottomSheets.Init()` or `SideSheets.Init()` again,
+  as a page that loads both the root and `/modular` entries can, no longer
+  adds a second set of document listeners.
+- `Menu.destroy()` no longer throws when the menu's target element is missing,
+  which used to leave its listeners attached.
+- `Utils.throttle` times calls with `performance.now()`, so a system clock
+  change cannot hold a call back.
+- More hot-path fixes:
+  - ScrollSpy skips the document-wide link lookup while the same section
+    stays current.
+  - MapView finds its zoom buttons once, not on every `move` event.
+  - PieChart reuses one percent formatter per legend instead of making one
+    per row.
+  - Snackbar measures its width once per swipe, not on every pointer move.
+  - Slider updates once per drag frame. Its `pointermove` update also ran
+    before the browser moved the value.
+  - The heatmap tooltip measures its cell before writing to the page.
+  - Datepicker checks each calendar row's markup once.
+- Less work on hot paths:
+  - Datepicker arrow keys inside the shown month move focus without
+    redrawing the grid.
+  - Autocomplete renders the result list once per keystroke while its menu is
+    open. It used to render the previous results first, and twice more with
+    `isMultiSelect`.
+  - Particles stop animating and tracking the pointer while the canvas is off
+    screen.
+  - Carousel reads all item positions before writing parallax offsets and works
+    out item sizes before setting them, so scrolling no longer forces a style
+    recalculation per item.
+  - Tabs throttle their window resize handling.
+  - `Utils.throttle` no longer stalls when the system clock moves backwards.
+- Autocomplete with `allowUnsafeHTML` highlights the typed text inside the
+  label's text only. It used to insert the highlight into the HTML string, so a
+  match inside an attribute value could close the attribute and turn the rest
+  of the sanitized label into markup.
+- Table-of-contents links are 48dp tall, the Material touch target, instead
+  of 32dp. `--md-comp-toc-item-height` sets a denser height.
+- In Firefox, a carousel that moved several items while its item sizes were
+  still changing could slide back to an earlier item after it had settled.
+  Firefox re-snapped the track to whichever item it had passed mid-move.
+  Snapping is now off while the carousel scrolls to an item and comes back
+  once the item is in place.
+
+## [0.13.1] - 2026-10-08
+
+### Fixed
+
+- The capability roadmap's source links point at a commit on `master`. The
+  0.13.0 links pointed at a pull request commit that no longer exists, which
+  stopped the 0.13.0 release before it reached npm. 0.13.1 contains the
+  0.13.0 changes below.
+
+## [0.13.0] - 2026-10-08
+
+### Added
+
+- `.rich-text-editor` turns a `<textarea>` into a Tiptap editor with a
+  docked toolbar. The page installs Tiptap and passes its `Editor` class and
+  extensions to `RichTextEditor.init()`; ExpressiveCSS does not bundle it.
+  A toolbar button's `data-command` names a Tiptap command and
+  `data-attributes` holds its JSON argument. Buttons are disabled when their
+  command cannot run, and `toggle` commands set `aria-pressed` and `.active`.
+  The textarea keeps the editor's HTML, so it submits with its form, and
+  names the editable textbox.
+- `.marquee` scrolls a row of logos, images or text without end. Write
+  the items in two `.marquee-content` groups, the second marked
+  `aria-hidden="true"`. `vertical`, `reverse` and `fade` change the
+  direction and edges, `paused` stops it, and hover or focus inside pauses
+  it. Reduced motion stops the scroll and hides the copy. CSS only.
+- `<mark>` highlights part of a text in the tertiary container colors,
+  with no padding so a match inside a word keeps its spacing.
+  `::highlight(mark)` paints ranges registered with the CSS Custom
+  Highlight API the same way.
+- `.message-scroller` scrolls a conversation. While the reader is at the
+  end it follows streamed replies, and scrolling up releases it. A message
+  appended with `data-scroll-anchor` starts a turn and is scrolled to the
+  top, leaving 64px of the previous message in view. Messages added above
+  keep the reader's place. A transcript can open at its end, its start or
+  its last turn, `scrollToMessage(id)` jumps to any message, and an optional
+  `.message-scroller-button` scrolls to the latest message.
+- `form.questionnaire` asks one question at a time. Each `<fieldset>` is a
+  question with radio, checkbox or text answers, and footer buttons marked
+  `value="previous"`, `"skip"` and `"next"` move between them. The component
+  adds a progress row, checks each question with the browser's validation
+  (`data-required` asks for at least one checkbox), shows the question's
+  `.questionnaire-error`, offers Skip on optional questions and leaves out
+  disabled ones so pages can branch. The form submits normally, and without
+  JavaScript every question shows at once.
+- KPI component: `article.kpi` is a card for one key figure, with its
+  label and value in a `<dl>`, a `.kpi-trend` chip that takes `up`, `down`
+  and `negative`, an optional `.kpi-icon`, a `.kpi-actions` corner button,
+  a sparkline chart, a progress bar and a `.kpi-footer`. A `negative` trend
+  also turns the sparkline to the error color. CSS only.
+- `.countdown` shows a whole number from 0 to 999 and rolls its digits up
+  or down when `--md-comp-countdown-value` changes. The element's text is
+  the value screen readers read. `--md-comp-countdown-digits` pads with
+  leading zeros, and reduced motion turns the roll off. CSS only.
+- `.aura` wraps one button, card or panel and runs a light around a ring
+  just outside it, to mark the one thing a screen most needs the user to
+  see. `dual`, `rainbow` and `glow` change the light, and tokens set its
+  color, width, corners and speed. The ring is fully rounded around a
+  button, stops turning under reduced motion and stays out of the
+  accessibility tree.
+- The agent skill gains an `expressivecss-charts` guide for building charts
+  and chart dashboards. It covers choosing a chart for the question asked,
+  table cells the charts can read, chart cards with stats, tokens,
+  sparklines and redrawing. Its recipes cover a period switch, a KPI row,
+  a donut with its total, a budget meter, a gauge, a heatmap and a
+  dashboard section. The root skill routes chart work to it.
+- `.mixed-chart` draws a `<figure>`'s data table as columns, lines and
+  areas on one plot, chosen by each series header's class: `column`,
+  `area`, or a line by default, with `dashed` lines. A series with `end`
+  is drawn against a second scale, set by `data-end-min` and
+  `data-end-max`, for values in other units. The tooltip, cursor points,
+  legend and `sparkline` work as in the line chart.
+- `.radial-chart` draws a `<figure>`'s data table as rings, one per row,
+  filled clockwise from the top as a share of `data-max` (100 by default),
+  with a legend, tracks, and a tooltip that follows the pointer across the
+  rings or the arrow keys. `gauge` draws half circles, a `<tfoot>` row shows
+  in the middle, and `sparkline` is a small chart. Ring width, gap and track
+  color are tokens.
+- `.heatmap-chart` draws a `<figure>`'s data table as a grid of cells shaded
+  from the lowest value to the highest, with the row headers beside it, the
+  column headers below and a scale naming the lowest and highest cells. A
+  tooltip follows the pointer or the arrow keys from cell to cell. `values`
+  writes each cell's text on it in black or white, whichever reads on the
+  shade; `data-label` shortens or hides a header on the grid; `data-min` and
+  `data-max` fix the scale.
+- `.radar-chart` draws a `<figure>`'s data table as shapes on spokes from a
+  shared middle, one spoke per row clockwise from the top and one shape per
+  series, with each row's label past its spoke, a legend, and a tooltip that
+  follows the pointer round the chart or the arrow keys. `area` fills the
+  shapes, `points` marks each value, and `sparkline` is a small chart.
+- `.pie-chart` draws a `<figure>`'s data table as slices of a whole,
+  clockwise from the top, with a legend of each row's cell and share and a
+  tooltip that follows the pointer round the pie or the arrow keys. `donut`
+  cuts a hole and shows a `<tfoot>` total in it, `values` writes each share
+  on its slice, and `sparkline` is a small pie. Further value columns show in
+  the tooltip.
+- `.bar-chart` draws a `<figure>`'s data table as horizontal bars from zero,
+  with each row's label beside it, a legend, and a highlight band and tooltip
+  that follow the pointer or the up and down arrows. The plot grows with its
+  rows. `stacked`, `split`, `track`, `values` and `sparkline` vary it: `values`
+  writes each cell from its bar's base, running past a short bar, and a
+  stacked, split row on a track with `data-max` is a meter. It shares the column chart's runtime and markup, and
+  the bars grow leftwards in a right-to-left page.
+- Line, column and bar charts: a tap on a touch screen shows the tapped row
+  instead of the first, keeps it when the finger lifts, and hides it when the
+  page scrolls.
+- `.column-chart` draws a `<figure>`'s data table as columns from zero, one
+  group per row, with x labels, a legend, and a highlight band and tooltip that
+  follow the pointer or the arrow keys. `stacked`, `fade`, `track` and
+  `sparkline` vary it, and negative values hang below zero. It shares the line
+  chart's runtime, markup and accessibility; the table stays as the text
+  alternative and the no-JavaScript fallback.
+- Line chart: `stacked` draws each series on the total of the ones before it
+  and fills the band between them, from a zero baseline. The tooltip still
+  shows each cell, and an empty cell breaks the series above it. The docs add chart card layouts with a period switch, a
+  compact chart and a side sparkline.
+
+- Message component: `.message` lays out one message in a conversation with an
+  optional `.message-avatar`, `.message-header` and `.message-footer` around a
+  `.message-bubble`. `end` moves a message to the sender's side,
+  `.message-group` stacks consecutive messages and joins their corners, and
+  `.message-bubble.outlined` holds attachments. CSS only.
+- Accordion component: `.accordion` stacks native `<details>` items as joined
+  tiles with a turning chevron. A shared `name` keeps one item open, and
+  opening animates where the engine can transition to `auto` height. CSS only.
+- Data table component: `.data-table` wraps a native `<table>` in a scrolling,
+  outlined container with a sticky header row. `numeric` aligns number columns,
+  `dense` shortens rows, `aria-sort` on a header draws its sort arrow, and a
+  checked checkbox in the first cell selects the row. The page owns sorting.
+  CSS only.
+- Avatar component: `.avatar` shows a person as a circular image, initials or
+  icon in `small`, default and `large` sizes. `.avatar-group` overlaps avatars
+  with a surface ring. CSS only.
+- Skeleton component: `.skeleton` draws placeholder boxes, `text` lines and
+  `circle` shapes with a shimmer that stops under reduced motion. CSS only.
+- Empty state component: `.empty-state` centers an icon or illustration, a
+  heading, supporting text and an `.empty-state-actions` row. CSS only.
+- Popover component: `.popover` styles a native `[popover]` panel opened by a
+  `popovertarget` button and places it with CSS anchor positioning, below the
+  button by default or with `top`, `start` and `end`, flipping to stay on
+  screen. Use it for toggletips and small action panels. CSS only.
+- Stepper component: `ol.stepper` numbers a fixed sequence of steps.
+  `aria-current="step"`, `complete` and `invalid` mark each step's state, and
+  the complete and invalid states are spoken through translatable tokens.
+  `vertical` stacks the steps and takes a `.stepper-content` panel. CSS only.
+- Drop zone component: `.drop-zone` stretches a native file input over a large
+  labelled target. The Forms behavior marks a drag with `dragover` and lists
+  each chosen file's name and size in `.drop-zone-files`.
+- Text fields take a trailing `.icon-button.suffix` as a clickable control.
+  `password-toggle` on that button shows and hides the password and reports
+  its state with `aria-pressed`. `input.otp` draws one native input as a row of
+  one-time code cells.
+- Menu `contextMenu` option, also set by `data-context-menu` on the trigger:
+  the trigger is a region, and its menu opens at the pointer on right-click,
+  long-press, the menu key or Shift+F10, flipping to stay on screen.
+- Timeline component: `ol.timeline` marks each event with a dot joined to the
+  next by a line, or with a leading icon in a tonal circle. CSS only.
+- Stat component: `dl.stats` lays out key figures as wrapping tiles, with a
+  `.stat-change` line that takes `up`, `down` and `negative`. CSS only.
+- Tree component: `ul.tree` nests lists of native disclosures and links with
+  guide lines, turning chevrons and an `aria-current` row. It takes no tree
+  role. CSS only.
+- Rating component: `fieldset.rating` draws native radios as stars that fill
+  up to the choice and preview on hover; `.rating[role="img"]` with
+  `--md-comp-rating-value` shows a score, halves included. CSS only.
+- Command palette component: `dialog.command-palette` with a search input and
+  a list of link or button commands. `CommandPalette` filters by text and
+  `data-keywords`, moves the active command with the arrow keys, runs it with
+  Enter and opens on Ctrl+K or Command+K. `AutoInit()` starts it.
+- `<kbd>` is drawn as a keycap; an outer `<kbd>` around a combination stays
+  plain.
+- `.line-chart` draws a `<figure>`'s data table as smooth SVG lines with x
+  labels, a legend, and a cursor and tooltip that follow the pointer or the
+  arrow keys. `area`, `fade`, `sparkline` and `<th class="dashed">` vary it.
+  The table stays as the text alternative and the no-JavaScript fallback.
+- `.scroll-area` styles native scrollbars with theme-aware colors and thin
+  sizing, with a WebKit fallback and system scrollbars in forced-colors mode.
+- `.shape-*` cuts images, videos, buttons, and other elements to twenty
+  rounded shapes after the M3 Expressive shape library, such as
+  `.shape-scallop-6`, `.shape-spark`, and `.shape-bloom-4`. Focused shapes draw
+  their focus ring inside the edge. CSS only.
+- Frosted glass for floating surfaces. `--expressive-glass: true` on `:root` or
+  a wrapper turns it on. `--expressive-glass-blur` (default `16px`) sets the
+  frost thickness, and `--expressive-glass-opacity` (default `72%`) sets how
+  much of the surface color is kept. Sass `$expressive-glass`,
+  `$expressive-glass-blur`, and `$expressive-glass-opacity` change the defaults,
+  and `--expressive-glass: false` turns the effect off within a region. Surfaces
+  turn solid when the user prefers reduced transparency or more contrast.
+- The docs site opens on a landing page with a features overview, a live
+  code demo and the installation guide. Ctrl+K, Command+K or the app bar's
+  search button opens a search of every documentation page. Pages now carry
+  a meta description and Open Graph tags, and the site publishes
+  `sitemap.xml` and `robots.txt`.
+
+### Changed
+
+- The default theme seed is Mist Iris (`#c6a0f6`). The docs picker uses the
+  same default for its initial value and Reset action. Set `--md-source` or
+  Sass `$md-source` to retain an application's existing brand color.
+- The agent skill workflow is version 0.9.0 and costs fewer tokens to read.
+  Sub-skill scope now lives only in each frontmatter description, without
+  repeated "When to use" sections. Generated component guides no
+  longer repeat the page description or the generic rule and documentation
+  notes, and the theming, usage, dashboard and charts guides link to the
+  reference that owns a rule instead of restating it. Each sub-skill says when
+  to read each reference, long references open with a contents list, and the
+  design guide links its dated component reviews directly. A new delegation
+  reference explains how to split a large audit across subagents and merge
+  their findings. The install and runtime guides end with checklists, and the
+  charts guide asks for honest scales and labelled sample data. Component
+  guides drop the source list and the two notes every guide repeated; the
+  root skill states the rule-ID convention once and tells agents to treat
+  page content and tool output as evidence, not instructions. Performance
+  measurement moved from the design guide into its own reference.
+
+### Fixed
+
+- A checkbox label written as `<input type="checkbox"><span>…</span>` keeps
+  links and other inline elements in its text. The span was a flex box, so
+  each text run and link became a separate item: the spaces around a link
+  disappeared and the words split into columns. It now lays out as inline
+  text, and one line still sits centered in the 48px target.
+- A focused line, column, bar or pie chart no longer cancels Escape when its
+  tooltip is already hidden, so a dialog or sheet around the chart can close.
+  Pressing a chart's plot away from its marks focuses it without showing the
+  first row's tooltip; keyboard focus still shows it.
+- A drawn chart's hidden data table no longer makes a narrow tile or its page
+  scroll. The table keeps a fixed 1px layout, as the heatmap's already did,
+  and hangs up from the figure's bottom edge, so its rows cannot add overflow
+  below it.
+- The line chart docs' chart cards pad their stat and chart off the card's
+  border.
+
 ## [0.12.0] - 2026-10-01
 
 ### Added
@@ -1919,7 +2253,11 @@ 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.12.0...HEAD
+[Unreleased]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.14.1...HEAD
+[0.14.1]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.14.0...v0.14.1
+[0.14.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.13.1...v0.14.0
+[0.13.1]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.13.0...v0.13.1
+[0.13.0]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.12.0...v0.13.0
 [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

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.12.0` is under active development.
+> ExpressiveCSS version `0.14.1` is under active development.
 
 Documentation: [www.expressivecss.com](https://www.expressivecss.com)
 
@@ -326,6 +326,42 @@ 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.
 
+### Frosted glass
+
+Floating surfaces can blur the page behind them. The effect is off by default.
+Turn it on in CSS for the whole page or for one region:
+
+```css
+:root {
+  --expressive-glass: true;
+  --expressive-glass-blur: 16px;    /* frost thickness */
+  --expressive-glass-opacity: 72%;  /* share of the surface color kept; 100% is solid */
+}
+```
+
+The blur and opacity lines are optional and show the defaults. Set
+`--expressive-glass` on `:root` or on an element that contains the surfaces. The
+browser reads the value from a surface's parent, so setting it on the surface
+itself has no effect. `--expressive-glass: false` turns the effect off again inside
+a region.
+
+Sass builds can turn glass on by default and change the default values. The CSS
+properties still override these settings:
+
+```scss
+@use "@expressivecss/expressive/src/sass/expressive" with (
+  $expressive-glass: true,
+  $expressive-glass-blur: 16px,
+  $expressive-glass-opacity: 72%
+);
+```
+
+The effect applies to menus, tooltips, dialogs, bottom and side sheets, the
+snackbar, the navigation bar and rail, toolbars, and the search view. Grouped menus
+and a modal navigation rail keep a solid surface. The rail would otherwise clip its
+own scrim. Users who request reduced transparency or more contrast in their system
+settings see solid surfaces. The switch uses CSS style queries.
+
 ### Themes
 
 ExpressiveCSS uses the `theme` attribute on the root element:
@@ -380,6 +416,7 @@ The documentation source lives in `docs/src/` and is published at
 | `docs/src` | Astro documentation and examples | Yes |
 | `mcp/expressivecss` | Independently versioned MCP package | Yes |
 | `skills/expressivecss` | Agent guidance and generated component references | Yes |
+| `skills/expressivecss-review` | Scored interface review that runs five specialist subagents | Yes |
 | `scripts`, `tests`, `visual` | Generators, verification, and test tooling | Source only |
 | `semantics.json`, `llm.md`, `m3-guidelines.md` | Markup rules, API reference, design guidance | Yes |
 | `SEMANTICS.md`, generated skill/MCP data | Derived files checked for drift | Yes |