react-material-expressive 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. package/CHANGELOG.md +54 -1
  2. package/README.md +28 -23
  3. package/dist/index.cjs +1241 -491
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +110 -9
  6. package/dist/index.d.ts +110 -9
  7. package/dist/index.js +1240 -492
  8. package/dist/index.js.map +1 -1
  9. package/dist/styles.css +1 -1
  10. package/dist/theme.css +5 -0
  11. package/docs/components/Combobox.md +119 -0
  12. package/docs/components/DatePicker.md +14 -2
  13. package/docs/components/Dropdown.md +4 -0
  14. package/docs/components/Layers.md +3 -0
  15. package/docs/components/Menu.md +4 -0
  16. package/docs/components/NavigationRail.md +3 -0
  17. package/docs/components/OverflowMenu.md +5 -1
  18. package/docs/components/Search.md +9 -1
  19. package/docs/components/SplitButton.md +3 -1
  20. package/docs/components/TextElement.md +15 -0
  21. package/llms.txt +64 -59
  22. package/package.json +5 -2
package/CHANGELOG.md CHANGED
@@ -10,6 +10,58 @@ what to adjust when upgrading.
10
10
 
11
11
  ## [Unreleased]
12
12
 
13
+ ## [1.1.0] - 2026-06-20
14
+
15
+ ### Added
16
+
17
+ - **`ComboboxOutlined` / `ComboboxFilled`** — an ARIA combobox (text field +
18
+ portaled `role="listbox"`) with consumer-controlled async options: type to
19
+ fire `onInputChange`, feed back already-filtered `options`, with `loading`,
20
+ `clearable`, error states and full keyboard. Closes the gap that forced
21
+ integrators to use `Search` as a combobox substitute.
22
+ - **Documented `--md-sys-z-*` stacking tokens** — every overlay (menus,
23
+ tooltips, dialogs/sheets, snackbar) now layers through one ascending,
24
+ consumer-overridable z-index scale instead of scattered hard-coded values.
25
+ See FOUNDATIONS.md → Stacking & z-index.
26
+ - **`DatePickerDocked` error state** — accepts `error` / `errorText` /
27
+ `supportingText`, forwarded to its underlying outlined field (MD3 error role
28
+ with `aria-invalid` / `role="alert"` / `aria-describedby`).
29
+ - **`SearchInput` clear button** — opt-in `clearable` renders a trailing clear
30
+ (×) button while the input has a value; it clears (controlled or
31
+ uncontrolled), refocuses the input, fires `onClear`, hides the inconsistent
32
+ native search clear, and yields to an explicit `rightElement`. Adds
33
+ `labels.clear`.
34
+ - **Polymorphic `TextElement`** — new `as` / `titleAs` / `labelAs` / `bodyAs`
35
+ props set each rendered element (defaults preserved: div/p/h2/p) so the
36
+ heading level follows content hierarchy (M3 a11y). With a single slot the
37
+ text element now renders directly, without the wrapper `<div>`.
38
+ - **`llms.txt` discoverability** — exposed as the
39
+ `react-material-expressive/llms.txt` export subpath and pointed to by an
40
+ `llmsTxt` field in `package.json`, plus a prominent pointer at the top of the
41
+ README.
42
+
43
+ ### Changed
44
+
45
+ - **`llms.txt` review** — every entry now carries a one-line description, the
46
+ new components/props are reflected, a FOUNDATIONS pointer was added, and the
47
+ stale pre-1.0 versioning note was corrected. Links stay relative (the package
48
+ bundles `docs/`).
49
+
50
+ ### Fixed
51
+
52
+ - **Top-level menus no longer clip inside `overflow` ancestors** — `Dropdown`,
53
+ `OverflowMenu` and `SplitButton` now render their menu in a portal on
54
+ `document.body` with fixed positioning (like `Menu.Sub` already did),
55
+ auto-flipping above the trigger when there's no room below and tracking it
56
+ on scroll/resize. Positioning is unified in a shared internal helper.
57
+ - **NavigationRail no longer shows a needless scrollbar** — the destinations
58
+ area is the sole flexible region and scrolls only on real overflow; the
59
+ header and bottom slot keep their natural size.
60
+ - **README links resolve on npm** — the relative links (component docs,
61
+ `LICENSE`, `llms.txt`, `CHANGELOG`, `AGENTS.md`, `CONTRIBUTING.md`) are now
62
+ absolute GitHub URLs, so they work on the npmjs.com package page (where
63
+ relative links 404) as well as on GitHub.
64
+
13
65
  ## [1.0.0] - 2026-06-17
14
66
 
15
67
  Initial public release — the first complete implementation of **Material 3
@@ -35,5 +87,6 @@ baseline).
35
87
  - React 19+, **ESM + CJS** builds and **TypeScript** types, plus
36
88
  machine-readable per-component docs and an LLM index.
37
89
 
38
- [Unreleased]: https://github.com/gersilva96/react-material-expressive/compare/v1.0.0...HEAD
90
+ [Unreleased]: https://github.com/gersilva96/react-material-expressive/compare/v1.1.0...HEAD
91
+ [1.1.0]: https://github.com/gersilva96/react-material-expressive/compare/v1.0.0...v1.1.0
39
92
  [1.0.0]: https://github.com/gersilva96/react-material-expressive/releases/tag/v1.0.0
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # react-material-expressive
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/react-material-expressive.svg)](https://www.npmjs.com/package/react-material-expressive)
3
+ [![npm version](https://img.shields.io/npm/v/react-material-expressive)](https://www.npmjs.com/package/react-material-expressive)
4
4
  [![CI](https://github.com/gersilva96/react-material-expressive/actions/workflows/ci.yml/badge.svg)](https://github.com/gersilva96/react-material-expressive/actions/workflows/ci.yml)
5
- [![license: MIT](https://img.shields.io/npm/l/react-material-expressive.svg)](LICENSE)
5
+ [![license: MIT](https://img.shields.io/npm/l/react-material-expressive)](https://github.com/gersilva96/react-material-expressive/blob/main/LICENSE)
6
6
 
7
7
  React component system implementing **Material 3 Expressive**: official M3
8
8
  design tokens, state layers, the full type/shape/elevation scales and
@@ -10,12 +10,17 @@ motion — framework-agnostic (no `next/*`), RSC/SSR friendly, with
10
10
  **precompiled CSS** (you don't set up Tailwind) and runtime theming via CSS
11
11
  variables.
12
12
 
13
+ > **🤖 LLM- and agent-friendly.** Start from the machine-readable index
14
+ > [`llms.txt`](https://github.com/gersilva96/react-material-expressive/blob/main/llms.txt)
15
+ > — every component linked with a one-line description. It's also resolvable as
16
+ > `react-material-expressive/llms.txt` and pointed to by the `llmsTxt` field in
17
+ > `package.json`.
18
+
13
19
  - React `>= 19` (peer dependency). ESM + CJS + TypeScript types.
14
20
  - Pure UI kit: presentational, controllable components. No business logic,
15
21
  no data fetching, no app state.
16
- - Machine-readable docs per component in [`docs/components/`](docs/components)
17
- and an LLM index in [`llms.txt`](llms.txt).
18
- - **Live demo**: [ger-material-expressive.vercel.app](https://ger-material-expressive.vercel.app)
22
+ - Machine-readable docs per component in [`docs/components/`](https://github.com/gersilva96/react-material-expressive/tree/main/docs/components).
23
+ - **Live demo**: [react-material-expressive.vercel.app](https://react-material-expressive.vercel.app)
19
24
  (the Storybook, redeployed on every push).
20
25
 
21
26
  ## Installation
@@ -231,23 +236,23 @@ The theme-name strings of `ToggleThemeMenu` stay in its `themes` list (an
231
236
 
232
237
  | Family | Docs |
233
238
  | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
234
- | Buttons | [Button](docs/components/Button.md) · [ButtonGroup](docs/components/ButtonGroup.md) · [ButtonGroupConnected](docs/components/ButtonGroupConnected.md) · [IconButton](docs/components/IconButton.md) · [FAB / ExtendedFAB](docs/components/FAB.md) · [FABMenu](docs/components/FABMenu.md) · [SplitButton](docs/components/SplitButton.md) |
235
- | Communication | [Badge](docs/components/Badge.md) · [Progress / Circle](docs/components/Progress.md) · [LoadingIndicator](docs/components/LoadingIndicator.md) · [Snackbar](docs/components/Snackbar.md) · [Tooltip](docs/components/Tooltip.md) · [Loading](docs/components/Loading.md) |
236
- | Containment | [Card](docs/components/Card.md) · [Dialog](docs/components/Dialog.md) · [Sheets](docs/components/Sheets.md) · [Divider](docs/components/Divider.md) · [List](docs/components/List.md) · [Table](docs/components/Table.md) |
237
- | Selection & input | [Checkbox](docs/components/Checkbox.md) · [Radio](docs/components/Radio.md) · [Switch](docs/components/Switch.md) · [Chips](docs/components/Chips.md) · [Slider / SliderDual](docs/components/Slider.md) · [TextField](docs/components/TextField.md) · [Select](docs/components/Select.md) · [Amount](docs/components/Amount.md) · [DatePicker](docs/components/DatePicker.md) · [TimePicker](docs/components/TimePicker.md) |
238
- | Navigation | [NavigationBar](docs/components/NavigationBar.md) · [NavigationRail](docs/components/NavigationRail.md) · [TopAppBar](docs/components/TopAppBar.md) · [Toolbars](docs/components/Toolbar.md) · [Tabs](docs/components/Tabs.md) · [Link](docs/components/Link.md) · [Search](docs/components/Search.md) |
239
- | Menus | [Menu](docs/components/Menu.md) · [Dropdown](docs/components/Dropdown.md) · [OverflowMenu](docs/components/OverflowMenu.md) · [ToggleTheme](docs/components/ToggleTheme.md) |
240
- | Media & showcase | [Avatar](docs/components/Avatar.md) · [AvatarStack](docs/components/AvatarStack.md) · [Img](docs/components/Img.md) · [MediaFrame](docs/components/MediaFrame.md) · [Gallery](docs/components/Gallery.md) · [Stories](docs/components/Stories.md) · [Video](docs/components/Video.md) · [Perspective](docs/components/Perspective.md) · [Blob](docs/components/Blob.md) |
241
- | Text & icons | [TextElement](docs/components/TextElement.md) · [Icon](docs/components/Icon.md) · [MaterialSymbol](docs/components/MaterialSymbol.md) |
242
- | Layout | [Layers](docs/components/Layers.md) |
239
+ | Buttons | [Button](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Button.md) · [ButtonGroup](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/ButtonGroup.md) · [ButtonGroupConnected](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/ButtonGroupConnected.md) · [IconButton](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/IconButton.md) · [FAB / ExtendedFAB](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/FAB.md) · [FABMenu](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/FABMenu.md) · [SplitButton](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/SplitButton.md) |
240
+ | Communication | [Badge](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Badge.md) · [Progress / Circle](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Progress.md) · [LoadingIndicator](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/LoadingIndicator.md) · [Snackbar](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Snackbar.md) · [Tooltip](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Tooltip.md) · [Loading](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Loading.md) |
241
+ | Containment | [Card](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Card.md) · [Dialog](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Dialog.md) · [Sheets](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Sheets.md) · [Divider](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Divider.md) · [List](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/List.md) · [Table](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Table.md) |
242
+ | Selection & input | [Checkbox](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Checkbox.md) · [Radio](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Radio.md) · [Switch](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Switch.md) · [Chips](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Chips.md) · [Slider / SliderDual](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Slider.md) · [TextField](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/TextField.md) · [Select](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Select.md) · [Combobox](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Combobox.md) · [Amount](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Amount.md) · [DatePicker](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/DatePicker.md) · [TimePicker](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/TimePicker.md) |
243
+ | Navigation | [NavigationBar](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/NavigationBar.md) · [NavigationRail](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/NavigationRail.md) · [TopAppBar](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/TopAppBar.md) · [Toolbars](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Toolbar.md) · [Tabs](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Tabs.md) · [Link](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Link.md) · [Search](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Search.md) |
244
+ | Menus | [Menu](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Menu.md) · [Dropdown](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Dropdown.md) · [OverflowMenu](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/OverflowMenu.md) · [ToggleTheme](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/ToggleTheme.md) |
245
+ | Media & showcase | [Avatar](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Avatar.md) · [AvatarStack](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/AvatarStack.md) · [Img](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Img.md) · [MediaFrame](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/MediaFrame.md) · [Gallery](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Gallery.md) · [Stories](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Stories.md) · [Video](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Video.md) · [Perspective](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Perspective.md) · [Blob](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Blob.md) |
246
+ | Text & icons | [TextElement](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/TextElement.md) · [Icon](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Icon.md) · [MaterialSymbol](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/MaterialSymbol.md) |
247
+ | Layout | [Layers](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Layers.md) |
243
248
 
244
249
  ### Expressive-only
245
250
 
246
251
  This kit is **Material 3 Expressive only**. Components and variants that the
247
252
  M3 Expressive spec marks "no longer recommended" are not shipped: the
248
- NavigationDrawer (→ expanded [NavigationRail](docs/components/NavigationRail.md)),
249
- BottomAppBar (→ [DockedToolbar](docs/components/Toolbar.md)) and SegmentedButtons
250
- (→ [ButtonGroupConnected](docs/components/ButtonGroupConnected.md) with toggles)
253
+ NavigationDrawer (→ expanded [NavigationRail](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/NavigationRail.md)),
254
+ BottomAppBar (→ [DockedToolbar](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Toolbar.md)) and SegmentedButtons
255
+ (→ [ButtonGroupConnected](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/ButtonGroupConnected.md) with toggles)
251
256
  components were removed, as were the FAB `surface` color / small (40dp) size,
252
257
  the Slider `classic` prop, the TopAppBar `Medium`/`Large` `baseline` prop and
253
258
  the NavigationBar `tall` height. The expressive default is the only path.
@@ -257,15 +262,15 @@ default and the alternative stays available:
257
262
 
258
263
  | Component | Default (recommended) | Still-available alternative |
259
264
  | ------------------------------------------------ | ------------------------------ | --------------------------- |
260
- | [List](docs/components/List.md) | `variant="expressive"` (tiles) | `variant="plain"` |
261
- | [Search](docs/components/Search.md) | contained (gapped card) | `divided` prop |
262
- | [Progress / Circle](docs/components/Progress.md) | flat indicator | `wavy` prop |
265
+ | [List](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/List.md) | `variant="expressive"` (tiles) | `variant="plain"` |
266
+ | [Search](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Search.md) | contained (gapped card) | `divided` prop |
267
+ | [Progress / Circle](https://github.com/gersilva96/react-material-expressive/blob/main/docs/components/Progress.md) | flat indicator | `wavy` prop |
263
268
 
264
269
  ## Versioning
265
270
 
266
271
  This project follows [Semantic Versioning](https://semver.org/): breaking
267
272
  changes bump the _major_ version, new features the _minor_, and fixes the
268
- _patch_. See the [CHANGELOG](CHANGELOG.md) for every release, with a
273
+ _patch_. See the [CHANGELOG](https://github.com/gersilva96/react-material-expressive/blob/main/CHANGELOG.md) for every release, with a
269
274
  **migration note** on each breaking change so you know exactly what to adjust
270
275
  when upgrading.
271
276
 
@@ -277,8 +282,8 @@ npm run build # dist/: css + esm + cjs + dts + themes
277
282
  npm run typecheck && npm run lint && npm test
278
283
  ```
279
284
 
280
- See [AGENTS.md](AGENTS.md) for architecture and conventions, and
281
- [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute. The interactive
285
+ See [AGENTS.md](https://github.com/gersilva96/react-material-expressive/blob/main/AGENTS.md) for architecture and conventions, and
286
+ [CONTRIBUTING.md](https://github.com/gersilva96/react-material-expressive/blob/main/CONTRIBUTING.md) for how to contribute. The interactive
282
287
  component workbench (Storybook) lives in a separate repository.
283
288
 
284
289
  ## License