@expressivecss/expressive 0.12.0 → 0.13.1

package/CHANGELOG.md

@@ -5,6 +5,234 @@ the format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [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 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 +2147,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.12.0...HEAD
+[Unreleased]: https://github.com/BaezFJ/ExpressiveCSS/compare/v0.13.1...HEAD
+[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.13.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: