diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index bb3087a3..145cc8e0 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -261,7 +261,7 @@ M3's plain tooltip, standalone around any trigger: ` ``` -``: `trigger` slot (its first button or link becomes the menu button, and the menu hangs on that button — a `position: fixed` trigger such as `` carries it along, and a menu with no room flips to the other side, end or both), `label`, `position` (`bottom-start` default, `bottom-end`, `top-start`, `top-end`), `vibrant`. ``: `label`, `icon`, `icon-class` (classes for the leading icon; a colour there paints it, a selected item's too, but not a disabled one's — `icon-class="text-sport-run"`), `icon-right`, `description`, `shortcut`, `link`, `external`, `selected` (makes it a `menuitemcheckbox`, ticked at its end unless it has an `icon-right`), `current` (for a menu of places: marks the page you are on with `aria-current="page"` in secondary-container, never a checked choice), `badge` (`true` for a dot, or a count, at the end of the row), `disabled`, `keep-open`, `submenu`. Choosing an item closes the menu unless `keep-open`; a second press on the menu button closes it too. An open menu stays open while the Livewire component around it renders, a `keep-open` item's own `wire:click` included. Keyboard: arrows, Home, End, a letter, Escape (focus returns to the trigger), Tab; a `disabled` item keeps its place in that order, as M3 asks, but cannot be activated. A menu longer than the window scrolls. +``: `trigger` slot (its first button or link becomes the menu button, and the menu hangs on that button — a `position: fixed` trigger such as `` carries it along, and a menu with no room flips to the other side, end or both), `label`, `position` (`bottom-start` default, `bottom-end`, `top-start`, `top-end`), `vibrant`, `filter`. ``: `label`, `icon`, `icon-class` (classes for the leading icon; a colour there paints it, a selected item's too, but not a disabled one's — `icon-class="text-sport-run"`), `icon-right`, `description`, `shortcut`, `link`, `external`, `selected` (makes it a `menuitemcheckbox`, ticked at its end unless it has an `icon-right`), `current` (for a menu of places: marks the page you are on with `aria-current="page"` in secondary-container, never a checked choice), `badge` (`true` for a dot, or a count, at the end of the row), `disabled`, `keep-open`, `submenu`. Choosing an item closes the menu unless `keep-open`; a second press on the menu button closes it too. An open menu stays open while the Livewire component around it renders, a `keep-open` item's own `wire:click` included. Keyboard: arrows, Home, End, a letter, Escape (focus returns to the trigger), Tab; a `disabled` item keeps its place in that order, as M3 asks, but cannot be activated. A menu longer than the window scrolls. `submenu` makes an item a menu of its own — the slot holds the nested ``s instead of a label, and they open beside it, on its end, flipping to its start where the window has no room: @@ -274,6 +274,8 @@ M3's plain tooltip, standalone around any trigger: ``); a query that leaves nothing says "Nothing matches". Reach for it once a menu is long enough to hunt through; for a value bound to a property, `` is the field, not the menu. + Clusters: `` draws M3's line, `` M3 Expressive's grouped layout — no line, the cluster set 8px off its neighbours with its items 2px apart and its ends rounded. Reach for the divider first (M3: "on web, use dividers to separate items", and it is the only one a scrolling menu may use); reach for the gap for one or two clusters in a menu short enough not to scroll, and never vary the gap. `` takes `label` (optional) and `gap`; a labelled group without `gap` is the plain heading it always was. ### `` diff --git a/resources/css/components/menu.css b/resources/css/components/menu.css index 5226b775..ac785bf5 100644 --- a/resources/css/components/menu.css +++ b/resources/css/components/menu.css @@ -43,6 +43,53 @@ color: var(--material-menu-ink, var(--md-sys-color-on-surface)); } +/* + * ``: M3's menu as a filtering surface. The field stays put while the list scrolls + * under it and takes the menu's own container, so a vibrant menu's field is vibrant too. It is a + * plain with no field chrome — M3's menus embed a text field, not a text field component. + */ +[data-menu-filter] { + position: sticky; + inset-block-start: 0; + z-index: 1; + display: flex; + align-items: center; + gap: 0.75rem; + min-block-size: 3rem; + padding-inline: 1rem; + border-block-end: 1px solid var(--md-sys-color-outline-variant); + background: var(--material-menu-surface, var(--md-sys-color-surface-container-low)); +} + +[data-menu-filter] input { + flex: 1; + min-inline-size: 0; + border: 0; + background: transparent; + padding: 0; + color: inherit; + font: var(--md-sys-typescale-body-lg); + letter-spacing: var(--md-sys-typescale-body-lg-tracking); + outline: none; +} + +[data-menu-filter] input::placeholder { + color: color-mix(in srgb, var(--material-menu-ink, var(--md-sys-color-on-surface)) 70%, transparent); +} + +/* The filter hides what the query leaves out with the `hidden` attribute; a row's own + `display: flex` utility would otherwise beat the user agent's `[hidden] { display: none }`. */ +[data-menu] [hidden] { + display: none; +} + +/* `data-active` is the row the arrow keys are on while the focus stays in the field — the state + layer the roving focus would have drawn, without taking the focus off the field. A chosen or + current row keeps its own colour. */ +[data-menu] [role^="menuitem"][data-active]:not([aria-checked="true"], [aria-current="page"]) { + background: color-mix(in srgb, var(--material-menu-ink, var(--md-sys-color-on-surface)) 8%, transparent); +} + .field-menu { max-block-size: 18rem; overflow-y: auto; diff --git a/resources/js/menu.js b/resources/js/menu.js index f51379be..38836293 100644 --- a/resources/js/menu.js +++ b/resources/js/menu.js @@ -20,6 +20,12 @@ * that exist only for a wrapper (moving the anchor name, and finding the button inside the trigger * slot) are overridden away. `items()` stops at the popover it belongs to, so the arrow keys in a * menu never walk into an open submenu's rows, nor a submenu's back out into its parent's. + * + * `` adds a text field at the top of the same list. The field keeps the focus while + * the arrow keys move a highlight — APG's combobox, which is what a text field inside a popup + * asks for — so `refine()`, `visible()`, `mark()` and `search()` work on `aria-activedescendant` + * and the `hidden` attribute rather than on the roving focus the rest of this file uses. They do + * nothing at all in a menu with no field: `$refs.filter` is what turns them on. */ const ITEMS = '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]' @@ -95,6 +101,12 @@ const menu = () => ({ } this.focusWasInside = false + + // A filtered menu opens on the whole list again: the query belonged to that visit. + if (this.$refs.filter) { + this.$refs.filter.value = '' + this.refine() + } }) // A press outside closes the menu without pulling focus back to the trigger. @@ -174,6 +186,16 @@ const menu = () => ({ this.control()?.setAttribute('aria-expanded', 'true') + // A filtering menu hands the focus to its field, not to a row: the field is where the + // typing goes, and `aria-activedescendant` says which row the arrows are on meanwhile. + if (this.$refs.filter) { + this.$refs.filter.focus() + this.$refs.filter.select() + this.mark(this.visible()[0] ?? null) + + return + } + // `false` opens without taking the focus: a submenu the pointer rested on belongs to the // pointer, and taking the focus out from under the keyboard would be the wrong answer. if (focus !== false) { @@ -263,6 +285,106 @@ const menu = () => ({ } }, + /** + * ``: M3's menu as a filtering surface. The rows are already rendered, so this + * only hides the ones the query leaves out — with the `hidden` attribute, which menu.css turns + * into `display: none` over the row's own `display: flex`. A divider means nothing between two + * filtered clusters, and a group whose every row has gone is a heading over nothing. + */ + refine() { + const query = this.$refs.filter.value.trim().toLowerCase() + + for (const item of this.items()) { + item.hidden = query !== '' && !(item.textContent ?? '').trim().toLowerCase().includes(query) + } + + for (const rule of this.$refs.menu.querySelectorAll('[role="separator"]')) { + rule.hidden = query !== '' + } + + for (const group of this.$refs.menu.querySelectorAll('[role="group"]')) { + group.hidden = ![...group.querySelectorAll(ITEMS)].some((item) => !item.hidden) + } + + const left = this.visible() + + this.$refs.empty.hidden = left.length > 0 + this.mark(left[0] ?? null) + }, + + /** The rows a query has left, in the order they are read. */ + visible() { + return this.items().filter((item) => !item.hidden && item.closest('[hidden]') === null) + }, + + /** + * Moves the highlight the arrow keys carry while the focus stays in the field. The row needs + * an id for `aria-activedescendant` to name it, and gets one if the caller wrote none. + */ + mark(item) { + for (const each of this.items()) { + if (each !== item) { + each.removeAttribute('data-active') + } + } + + if (!item) { + this.$refs.filter.removeAttribute('aria-activedescendant') + + return + } + + item.id ||= `${this.$refs.menu.id}-item-${this.items().indexOf(item)}` + item.setAttribute('data-active', '') + this.$refs.filter.setAttribute('aria-activedescendant', item.id) + + if (this.isOpen()) { + item.scrollIntoView({ block: 'nearest' }) + } + }, + + /** The APG combobox keyboard, on the field: the list moves under it and Enter takes a row. */ + search(event) { + const left = this.visible() + const current = left.findIndex((item) => item.hasAttribute('data-active')) + + const move = (index) => { + event.preventDefault() + + if (left.length > 0) { + this.mark(left[(index + left.length) % left.length]) + } + } + + switch (event.key) { + case 'ArrowDown': + return move(current + 1) + case 'ArrowUp': + return move(current < 0 ? left.length - 1 : current - 1) + case 'Home': + return move(0) + case 'End': + return move(left.length - 1) + case 'Enter': + event.preventDefault() + + if (left[current] && left[current].getAttribute('aria-disabled') !== 'true') { + left[current].click() + } + + return + case 'Escape': + // The browser's own light dismiss closes the popover; this only says where the + // focus goes after it. + this.returnFocus = true + + return + case 'Tab': + this.returnFocus = false + this.close() + } + }, + activate(event) { const item = event.target.closest(ITEMS) diff --git a/resources/views/components/menu.blade.php b/resources/views/components/menu.blade.php index e86fbec6..ee31e313 100644 --- a/resources/views/components/menu.blade.php +++ b/resources/views/components/menu.blade.php @@ -40,6 +40,16 @@ It opens by growing out of the corner nearest its trigger and fades as it goes (`popover-transition`), which is the transition M3 asks to tie a menu to what opened it. + `filter` is M3's menu as a filtering surface ("autocomplete"): a text field at the top of the + list, which stays put while the list scrolls under it, narrowing the items to those whose + label holds what has been typed — in the browser, over the items already rendered, so nothing + is fetched and a `wire:click` stays where it was. `filter="Find a person"` names the field; + bare `filter` calls it "Filter". The field, not the list, holds the focus, so a person can + type and steer at once: the arrow keys, Home and End move a highlighted row and say which one + through `aria-activedescendant`, and Enter chooses it — the APG combobox keyboard, the same + one `` uses. The list around it stays a `role="menu"` of its own inside + the popover, because a text field is not a thing a menu may contain. + The container is Expressive's standard menu (surface-container-low, 16px corner, elevation 2), or `vibrant` in tertiary-container — StandardMenuTokens and VibrantMenuTokens from androidx Compose Material 3 (Apache-2.0). --}} @@ -48,12 +58,16 @@ 'label' => null, 'position' => 'bottom-start', 'vibrant' => false, + 'filter' => false, ]) @php $position = in_array($position, ['bottom-start', 'bottom-end', 'top-start', 'top-end'], true) ? $position : 'bottom-start'; $key = \Illuminate\Support\Str::lower(\Illuminate\Support\Str::random(10)); $anchor = "--material-menu-{$key}"; + + $filtering = $filter !== false && $filter !== null && $filter !== ''; + $filterLabel = is_string($filter) && filled($filter) ? $filter : __('Filter'); @endphp
class('relative inline-flex') }}> @@ -68,16 +82,17 @@ {{ new \Illuminate\View\ComponentAttributeBag(['wire:key' => 'material-menu']) }} id="material-menu-{{ $key }}" popover="auto" - role="menu" + @unless ($filtering) role="menu" @endunless data-menu @if ($vibrant) data-vibrant @endif - @if ($label) aria-label="{{ $label }}" @endif + @if ($label && ! $filtering) aria-label="{{ $label }}" @endif tabindex="-1" style="position-anchor: {{ $anchor }}" x-on:keydown="navigate($event)" x-on:click="activate($event)" @class([ - 'm-0 min-w-28 max-w-70 max-h-[min(18rem,calc(100dvh-2rem))] overflow-y-auto border-0 p-1 rounded-corner-lg shadow-elevation-2 [inset:auto]', + 'm-0 min-w-28 max-w-70 max-h-[min(18rem,calc(100dvh-2rem))] overflow-y-auto border-0 rounded-corner-lg shadow-elevation-2 [inset:auto]', + 'p-1' => ! $filtering, 'my-1 [position-try-fallbacks:flip-block,flip-inline,flip-block_flip-inline]', 'popover-transition', 'bg-surface-container-low text-on-surface' => ! $vibrant, @@ -88,6 +103,36 @@ 'origin-bottom [position-area:top_span-left]' => $position === 'top-end', ]) > - {{ $slot }} + @if ($filtering) +
+ + + +
+ +
"material-menu-{$key}-list", + 'role' => 'menu', + 'aria-label' => $label, + ], fn ($value): bool => filled($value))) }} class="p-1"> + {{ $slot }} + + +
+ @else + {{ $slot }} + @endif
diff --git a/resources/views/showcase/sections/menus.blade.php b/resources/views/showcase/sections/menus.blade.php index c8330721..c4e95cfe 100644 --- a/resources/views/showcase/sections/menus.blade.php +++ b/resources/views/showcase/sections/menus.blade.php @@ -91,6 +91,22 @@
BLADE, + 'A menu that filters as you type' => <<<'BLADE' + + + + + + + + + + + + + + + BLADE, 'Icons in their own colour' => <<<'BLADE' diff --git a/tests/Feature/Components/MenuTest.php b/tests/Feature/Components/MenuTest.php index 2f7b0da8..635e928f 100644 --- a/tests/Feature/Components/MenuTest.php +++ b/tests/Feature/Components/MenuTest.php @@ -176,6 +176,37 @@ it('marks a submenu item with a chevron instead of a tick', function () { ->not->toContain($chevron); }); +it('embeds a text field that filters the list, as a combobox over the menu', function () { + $html = (string) $this->blade(''); + + preg_match('/id="(material-menu-[a-z0-9]+)"/', $html, $id); + + expect($id)->not->toBeEmpty() + ->and($html) + ->toContain('data-menu-filter') + ->toContain('x-ref="filter"') + ->toContain('role="combobox"') + ->toContain('aria-autocomplete="list"') + ->toContain("aria-controls=\"{$id[1]}-list\"") + ->toContain('aria-label="Find a person"') + ->toContain('placeholder="Find a person"') + ->toContain('x-on:input="refine()"') + ->toContain('x-on:keydown.stop="search($event)"') + ->toContain('Nothing matches') + // A text field is not something a `role="menu"` may hold, so the list moves inside it. + ->toContain("
toMatch('/]*popover="auto"(?![^>]*role="menu")/'); +}); + +it('names a bare filter field, and leaves a plain menu alone', function () { + expect((string) $this->blade('')) + ->toContain('aria-label="Filter"') + ->and((string) $this->blade('')) + ->not->toContain('data-menu-filter') + ->not->toContain('x-ref="filter"') + ->toMatch('/]*popover="auto"[^>]*role="menu"/'); +}); + it('tells a vibrant menu apart, so the submenus inside it take the same container', function () { expect((string) $this->blade('')) ->toContain('data-menu')