From f02fa1a78d6cda2eeb6249d96295941089dd1c8c Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 05:53:46 +0200 Subject: [PATCH 01/16] Give the bottom sheet's drag handle a 48dp target MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plan step 12, containment.md C-01. The handle button was 32x4px: the padding that makes M3's 48dp hit target sat on the wrapper, which is not the control. `touch-target` on the button and 22px above and below it — SheetDefaults.kt's DragHandleVerticalPadding — make the pressed area 48x48 while the handle is still drawn 32x4. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- resources/views/components/bottom-sheet.blade.php | 10 +++++++--- tests/Feature/Components/OverlayTest.php | 2 ++ 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/resources/views/components/bottom-sheet.blade.php b/resources/views/components/bottom-sheet.blade.php index c0847572..428e8510 100644 --- a/resources/views/components/bottom-sheet.blade.php +++ b/resources/views/components/bottom-sheet.blade.php @@ -9,7 +9,11 @@ SheetBottomTokens (androidx Compose Material 3, Apache-2.0): surface-container-low, extra-large top corners, elevation 1, a 32×4px drag handle in on-surface-variant; 640px wide at most, centred on a wide screen; it rises on emphasized decelerate. `title` and `actions` as on a dialog. - `height` caps it (default: 90% of the screen); content scrolls inside. --}} + `height` caps it (default: 90% of the screen); content scrolls inside. + + The handle is drawn 32×4px and pressed 48×48: `touch-target` on the button and 22px above and + below it, which is M3's "drag handle has an accessible 48dp hit target" and SheetDefaults.kt's + `DragHandleVerticalPadding = 22.dp` (docs/reference/m3/components-actions-communication-containment.md § Bottom sheets → Specs). --}} @props([ 'title' => null, @@ -56,8 +60,8 @@ $attributes->get('class'), ]) }} > -
- +
+
diff --git a/tests/Feature/Components/OverlayTest.php b/tests/Feature/Components/OverlayTest.php index 6e20420b..325f477d 100644 --- a/tests/Feature/Components/OverlayTest.php +++ b/tests/Feature/Components/OverlayTest.php @@ -86,6 +86,8 @@ it('draws a modal bottom sheet with a drag handle, or a standard one without a s ->toContain('rounded-t-corner-xl bg-surface-container-low') ->toContain('data-drag-handle') ->toContain('aria-modal="true"') + ->toContain('py-5.5') + ->toContain('touch-target h-1 w-8') ->and((string) $this->blade('Body')) ->toContain('...materialBottomSheet(true)') ->not->toContain('bg-scrim/32') From 7f678569167bd54cf7cf45a4a0e72dec94c9fda5 Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 05:54:25 +0200 Subject: [PATCH 02/16] Stop a disabled list item answering the keyboard Plan step 12, containment.md C-02. `pointer-events-none` blocked the pointer but not Tab and Enter: the item's `` stayed in the tab order and navigated, and nothing announced it disabled. A disabled item now renders its title as text, is no longer a `data-list-row`, and carries `aria-disabled="true"`. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- resources/views/components/list-item.blade.php | 7 +++++-- tests/Feature/Components/ListTest.php | 9 +++++++++ 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/resources/views/components/list-item.blade.php b/resources/views/components/list-item.blade.php index f9791dbe..c87a38ad 100644 --- a/resources/views/components/list-item.blade.php +++ b/resources/views/components/list-item.blade.php @@ -13,7 +13,9 @@ `link` makes the whole item the link. Otherwise, to make it open something while its trailing controls keep their own presses, give it `data-list-row` and put `data-list-open` on the one control that opens — see resources/js/list-rows.js. `selected` (true) is M3's selected item, - in secondary-container; `disabled` greys it. --}} + in secondary-container; `disabled` greys it to 38%, drops its link and announces it + `aria-disabled` — M3's states model treats disabled as not interactive, so a disabled item + answers neither the pointer nor the keyboard. --}} @props([ 'title' => null, @@ -32,7 +34,7 @@ ]) @php - $isLink = filled($link); + $isLink = filled($link) && ! $disabled; $lines = (filled($overline) ? 1 : 0) + (filled($description) ? 1 : 0); $initials = filled($avatar) && ! str_contains((string) $avatar, '/') && ! str_contains((string) $avatar, '.'); @endphp @@ -42,6 +44,7 @@ data-list-item @if ($isLink) data-list-row @endif @if ($selected) data-selected @endif + @if ($disabled) aria-disabled="true" @endif {{ $attributes->class([ 'relative flex items-center gap-3 px-4 text-on-surface', 'min-h-14 py-2' => $lines === 0, diff --git a/tests/Feature/Components/ListTest.php b/tests/Feature/Components/ListTest.php index 7da5a031..c01436ef 100644 --- a/tests/Feature/Components/ListTest.php +++ b/tests/Feature/Components/ListTest.php @@ -38,6 +38,15 @@ it('makes a linked item a row that opens from anywhere', function () { ->toContain('wire:navigate'); }); +it('leaves a disabled item out of the keyboard and announces it disabled', function () { + expect((string) $this->blade('')) + ->toContain('aria-disabled="true"') + ->toContain('pointer-events-none text-on-surface/38') + ->not->toContain('href="/settings"') + ->not->toContain('data-list-open') + ->not->toContain('data-list-row'); +}); + it('marks a selected item and takes controls in its slots', function () { expect((string) $this->blade('')) ->toContain('data-selected') From d64fb9130314f705b0031052318f9d52ca945123 Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 05:57:00 +0200 Subject: [PATCH 03/16] Announce a selectable list as M3's list box of options Plan step 12, containment.md C-03. `selected` was colour alone on a `listitem`, which cannot carry a selected state at all. `` (or `selection="single|multi"`) now makes the container a `role="listbox"` and each item an `option` with `aria-selected`; a plain list keeps `role="list"` and marks a selected item `aria-current`. A selected option draws a trailing check as M3's second cue, which `icon-right` replaces. The item reads its list's mode with `@aware`. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- .../livewire-material-development/SKILL.md | 2 ++ .../views/components/list-item.blade.php | 20 +++++++++++-- resources/views/components/list.blade.php | 28 ++++++++++++++++--- .../showcase/sections/containment.blade.php | 8 ++++++ tests/Feature/Components/ListTest.php | 22 +++++++++++++++ 5 files changed, 74 insertions(+), 6 deletions(-) diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index 38ecc56c..ba47d3bb 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -433,6 +433,8 @@ A card or list item that opens something is a **row**: `data-list-row` on it and ``: `label`, `dividers`, `segmented` (M3 Expressive: separate tiles 2px apart). ``: `title` (or slot), `overline`, `description`, leading `icon` / `avatar` (image URL or initials) / `image` / `leading` slot, trailing `trailing` text / `icon-right` / `end` slot, `link` (the whole item becomes a row that opens it), `selected`, `disabled`. One-, two- and three-line heights follow from the content. +A list a person chooses from is `` (or `selection="single"` / `selection="multi"`): M3 maps those to a **list box** of **options**, so the container becomes `role="listbox"` (`aria-multiselectable` when multi) and each item an `option` announcing `aria-selected`. A selected option also draws a trailing check — M3 never allows colour as the only cue — which `icon-right` or a leading checkbox replaces. A plain list stays `role="list"`, where `selected` is `aria-current`. `disabled` renders no link and announces `aria-disabled`. + ```blade @foreach ($files as $file) diff --git a/resources/views/components/list-item.blade.php b/resources/views/components/list-item.blade.php index c87a38ad..04c720f4 100644 --- a/resources/views/components/list-item.blade.php +++ b/resources/views/components/list-item.blade.php @@ -15,7 +15,12 @@ control that opens — see resources/js/list-rows.js. `selected` (true) is M3's selected item, in secondary-container; `disabled` greys it to 38%, drops its link and announces it `aria-disabled` — M3's states model treats disabled as not interactive, so a disabled item - answers neither the pointer nor the keyboard. --}} + answers neither the pointer nor the keyboard. + + It takes its role from the `` around it: a `listitem` in a plain list, where + `selected` is `aria-current`, and an `option` announcing `aria-selected` in a `selectable` + one. M3 asks for two cues on a selected item, never colour alone, so a selected option also + draws a trailing check unless `icon-right` says otherwise. --}} @props([ 'title' => null, @@ -33,14 +38,23 @@ 'disabled' => false, ]) +{{-- Whether the `` around it is one a person chooses from, and how many it takes. --}} +@aware([ + 'selectable' => false, + 'selection' => null, +]) + @php $isLink = filled($link) && ! $disabled; $lines = (filled($overline) ? 1 : 0) + (filled($description) ? 1 : 0); $initials = filled($avatar) && ! str_contains((string) $avatar, '/') && ! str_contains((string) $avatar, '.'); + $option = $selectable || $selection !== null; + $check = $option && $selected && blank($iconRight); @endphp
+ @elseif ($check) + @endif
diff --git a/resources/views/components/list.blade.php b/resources/views/components/list.blade.php index 527e0db4..582eaeaa 100644 --- a/resources/views/components/list.blade.php +++ b/resources/views/components/list.blade.php @@ -5,18 +5,38 @@ apart, with small corners that open to large at the ends and while hovered, pressed or selected (ListTokens, androidx Compose Material 3, Apache-2.0). - It is a `role="list"`; for keyboard walking between rows, `j`/`k` or arrows, the application - can use `data-list` (resources/js/list-rows.js marks rows; a list keyboard arrives with the - list-detail pane). `label` names the list. --}} + A plain list is a `role="list"` of `listitem`s. `selectable` (or `selection="single"` / + `selection="multi"`) makes it the list a person chooses from: M3 maps single- and + multi-select lists on the web to a **list box** of **options** with a selected state + (docs/reference/m3/components-actions-communication-containment.md § Lists → Accessibility), + so the container becomes `role="listbox"` (`aria-multiselectable` when multi) and each item + an `option` that announces `aria-selected`. A selected option also draws a trailing check, so + selection is never colour alone; give the items a leading checkbox or radio instead and pass + `icon-right` to keep the check off. + + For keyboard walking between rows, `j`/`k` or arrows, the application can use `data-list` + (resources/js/list-rows.js marks rows; a list keyboard arrives with the list-detail pane). + `label` names the list. --}} @props([ 'segmented' => false, 'dividers' => false, 'label' => null, + 'selectable' => false, + 'selection' => null, ]) +@php + $selection = match (true) { + in_array($selection, ['single', 'multi'], true) => $selection, + $selectable || $selection !== null => 'single', + default => null, + }; +@endphp +
class([ diff --git a/resources/views/showcase/sections/containment.blade.php b/resources/views/showcase/sections/containment.blade.php index 169fe1bb..45080614 100644 --- a/resources/views/showcase/sections/containment.blade.php +++ b/resources/views/showcase/sections/containment.blade.php @@ -40,9 +40,17 @@ +
BLADE, + 'A list to choose from' => <<<'BLADE' + + + + + + BLADE, 'Dividers and collapse' => <<<'BLADE'
diff --git a/tests/Feature/Components/ListTest.php b/tests/Feature/Components/ListTest.php index c01436ef..09b87260 100644 --- a/tests/Feature/Components/ListTest.php +++ b/tests/Feature/Components/ListTest.php @@ -38,6 +38,28 @@ it('makes a linked item a row that opens from anywhere', function () { ->toContain('wire:navigate'); }); +it('is a list box of options when it is one a person chooses from', function () { + expect((string) $this->blade('')) + ->toContain('role="listbox"') + ->toMatch('/role="option"\s+aria-selected="true"/') + ->toMatch('/role="option"\s+aria-selected="false"/') + ->not->toContain('aria-multiselectable') + ->and((string) $this->blade('')) + ->toContain('role="listbox"') + ->toContain('aria-multiselectable="true"') + ->and((string) $this->blade('')) + ->toContain('role="list"') + ->toMatch('/role="listitem"\s+aria-current="true"/') + ->not->toContain('aria-selected'); +}); + +it('draws a second cue on a selected option, which icon-right replaces', function () { + expect(substr_count((string) $this->blade(''), 'toBe(1) + ->and(substr_count((string) $this->blade(''), 'toBe(1) + ->and(substr_count((string) $this->blade(''), 'toBe(0) + ->and(substr_count((string) $this->blade(''), 'toBe(0); +}); + it('leaves a disabled item out of the keyboard and announces it disabled', function () { expect((string) $this->blade('')) ->toContain('aria-disabled="true"') From 335ea4f4f1d0b5706ef22f16199f13be1d9a1b86 Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 05:57:55 +0200 Subject: [PATCH 04/16] Give every side sheet the close affordance M3 requires Plan step 12, containment.md C-04. `with-close-button` defaulted to false, so a drawer could render with no exit at all once `close-on-escape` and the scrim were off. It now defaults to true, and `:with-close-button="false"` is ignored where nothing else closes the sheet: Escape off, the scrim off, or a pane, which has neither. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- .../livewire-material-development/SKILL.md | 2 +- resources/views/components/drawer.blade.php | 17 ++++++++++++++--- tests/Feature/Components/OverlayTest.php | 9 +++++++++ 3 files changed, 24 insertions(+), 4 deletions(-) diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index ba47d3bb..7cd9c5d9 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -479,7 +479,7 @@ Props: `title`, `subtitle`, `icon` (centred hero icon), `separator`, `persistent ### `` -An M3 side sheet, bound like ``; `close()` in scope. Props: `title`, `subtitle`, `separator`, `side` (`end` default, `start`), `width` (`25rem`), `with-close-button`, `close-on-escape` (default true), `without-backdrop-close`, `actions` slot. `pane` (with `pane-width`, `22.5rem` — M3's 360dp fixed pane) turns it into a second pane from `expanded`, where M3 shows two panes: render it after the list inside `
`. Escape leaves a pane open unless `pane-close-on-escape`. Its body is a size container — lay out inside with `@md:` (a *container* query), never a window class. +An M3 side sheet, bound like ``; `close()` in scope. Props: `title`, `subtitle`, `separator`, `side` (`end` default, `start`), `width` (`25rem`), `with-close-button` (**default true** — M3 requires a close affordance; `:with-close-button="false"` is ignored when Escape or the scrim is off, and on a pane), `close-on-escape` (default true), `without-backdrop-close`, `actions` slot. `pane` (with `pane-width`, `22.5rem` — M3's 360dp fixed pane) turns it into a second pane from `expanded`, where M3 shows two panes: render it after the list inside `
`. Escape leaves a pane open unless `pane-close-on-escape`. Its body is a size container — lay out inside with `@md:` (a *container* query), never a window class. ### `` diff --git a/resources/views/components/drawer.blade.php b/resources/views/components/drawer.blade.php index e7847ba4..33d67b2b 100644 --- a/resources/views/components/drawer.blade.php +++ b/resources/views/components/drawer.blade.php @@ -25,6 +25,13 @@ a size container, so its contents lay out by the room the sheet or pane actually has (`@md:`), never by the viewport. + M3 **requires** a close affordance on a side sheet — without one nobody can predict the + sheet's open/close flow or tell whether it is transient or permanent + (docs/reference/m3/components-actions-communication-containment.md § Side sheets → + Accessibility) — so `with-close-button` is on by default, and `:with-close-button="false"` is + ignored where nothing else closes the sheet: Escape off, the scrim off, or a pane, which has + neither. + maryUI's API, kept: `title`, `subtitle`, `separator`, `with-close-button`, `close-on-escape`, `without-backdrop-close`, `right` (ignored; use `side`), and an `actions` slot. --}} @@ -34,7 +41,7 @@ 'separator' => false, 'side' => 'end', 'right' => true, - 'withCloseButton' => false, + 'withCloseButton' => true, 'closeOnEscape' => true, 'withoutBackdropClose' => false, 'width' => '25rem', @@ -47,6 +54,10 @@ $model = $attributes->wire('model')->value() ?: null; $id = $attributes->get('id') ?? 'material-sheet-'.substr(md5($model.'|'.$title), 0, 10); $start = $side === 'start'; + + // M3 requires a close affordance; the prop can only ever add one, never take away the last + // way out of the sheet. + $closeButton = $withCloseButton || ! $closeOnEscape || $withoutBackdropClose || ($pane && ! $paneCloseOnEscape); @endphp
get('class'), ]) }} > - @if (filled($title) || $withCloseButton) + @if (filled($title) || $closeButton)
@@ -118,7 +129,7 @@ @endif
- @if ($withCloseButton) + @if ($closeButton) diff --git a/tests/Feature/Components/OverlayTest.php b/tests/Feature/Components/OverlayTest.php index 325f477d..932bbe1c 100644 --- a/tests/Feature/Components/OverlayTest.php +++ b/tests/Feature/Components/OverlayTest.php @@ -64,6 +64,15 @@ it('leaves a pane open on Escape unless it is asked to close then too', function ->not->toContain('keydown.window.escape'); }); +it('always offers a way out of a side sheet, as M3 requires', function () { + expect((string) $this->blade('Body'))->toContain('aria-label="Close"') + ->and((string) $this->blade('Body'))->not->toContain('aria-label="Close"') + ->and((string) $this->blade('Body'))->toContain('aria-label="Close"') + ->and((string) $this->blade('Body'))->toContain('aria-label="Close"') + ->and((string) $this->blade('Body'))->toContain('aria-label="Close"') + ->and((string) $this->blade('Body'))->not->toContain('aria-label="Close"'); +}); + it('slides a side sheet in from either edge, and is a pane from expanded when asked', function () { expect((string) $this->blade('Body')) ->toContain('x-trap.inert.noscroll="open && ! wide"') From f895b553b65891f4d7fbad0d76f8b7ceac1edb8a Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 05:58:50 +0200 Subject: [PATCH 05/16] Leave carousel items unmasked under reduced motion Plan step 12, containment.md C-05. Only the parallax half of M3's rule was honoured: the mask was still written every frame, so items kept growing and shrinking between the keylines. Under reduced motion the inset, the shift and the label fade are now all zero, so every item stays at the strategy's large size and the keylines only decide where the row snaps. `--material-carousel-pin` went with it: with no mask there is nothing to pin the content to. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- resources/js/carousel.js | 26 +++++++++++-------- .../views/components/carousel-item.blade.php | 2 +- resources/views/components/carousel.blade.php | 6 +++-- tests/Browser/CarouselTest.php | 7 +++-- 4 files changed, 23 insertions(+), 18 deletions(-) diff --git a/resources/js/carousel.js b/resources/js/carousel.js index f02e0fb2..734fdf37 100644 --- a/resources/js/carousel.js +++ b/resources/js/carousel.js @@ -23,9 +23,10 @@ * records. A ResizeObserver does the same for a new width. RTL is read when measuring: * scroll offsets are negative there and shifts mirror, as Compose's `translationX` does. * - * Under reduced motion the buttons and keys scroll instantly, and the content stays pinned to - * the mask's leading edge instead of sliding inside it: the frame still opens and closes with - * the scroll the user makes, but nothing moves on its own. + * Under reduced motion the buttons and keys scroll instantly and nothing is masked at all: M3 + * says the parallax goes and items "should no longer expand as they come into view — all items + * are the same size", so every item stays at the strategy's large size and the keylines only + * decide where the row snaps. * * --------------------------------------------------------------------------------------- * Keyline maths ported from androidx (https://github.com/androidx/androidx), commit @@ -872,7 +873,6 @@ document.addEventListener('alpine:init', () => { .map((element) => ({ element, surface: element.querySelector('[data-material-carousel-surface]'), - content: element.querySelector('[data-material-carousel-content]'), label: element.querySelector('[data-material-carousel-label]'), labelWidth: 0, written: '', @@ -963,7 +963,13 @@ document.addEventListener('alpine:init', () => { const scroll = this.scrollOffset() const keylines = keylinesForScrollOffset(strategy, scroll, state.maxScroll) const size = strategy.itemSize - const pinned = state.reducedMotion.matches + + // M3: "When reduced motion settings are turned on, the parallax effect should be + // removed and carousel items should no longer expand as they come into view. All + // items are the same size" (docs/reference/m3/styles.md § Motion → Accessibility + // requirements). The keylines still decide where the row snaps; nothing is masked, + // moved or faded, so every item stays at strategy.itemSize. + const still = state.reducedMotion.matches state.items.forEach((item, index) => { const center = index * (size + strategy.itemSpacing) + size / 2 - scroll @@ -978,11 +984,10 @@ document.addEventListener('alpine:init', () => { translation += (center - keyline.unadjustedOffset) / keyline.size } - const inset = clamp((size - keyline.size) / 2, 0, size / 2) - const shift = state.rtl ? -translation : translation - const pin = pinned ? (state.rtl ? -inset : inset) : 0 - const opacity = item.labelWidth > 0 ? clamp((item.labelWidth - size + keyline.size) / item.labelWidth, 0, 1) : 1 - const written = `${inset.toFixed(2)}|${shift.toFixed(2)}|${pin.toFixed(2)}|${opacity.toFixed(3)}` + const inset = still ? 0 : clamp((size - keyline.size) / 2, 0, size / 2) + const shift = still ? 0 : state.rtl ? -translation : translation + const opacity = still || item.labelWidth === 0 ? 1 : clamp((item.labelWidth - size + keyline.size) / item.labelWidth, 0, 1) + const written = `${inset.toFixed(2)}|${shift.toFixed(2)}|${opacity.toFixed(3)}` if (written === item.written) { return @@ -993,7 +998,6 @@ document.addEventListener('alpine:init', () => { item.written = written item.surface.style.setProperty('--material-carousel-inset', `${inset.toFixed(2)}px`) item.surface.style.setProperty('--material-carousel-shift', `${shift.toFixed(2)}px`) - item.surface.style.setProperty('--material-carousel-pin', `${pin.toFixed(2)}px`) item.surface.style.setProperty('--material-carousel-label-shift', `${(state.rtl ? -inset : inset).toFixed(2)}px`) item.surface.style.setProperty('--material-carousel-label', opacity.toFixed(3)) }) diff --git a/resources/views/components/carousel-item.blade.php b/resources/views/components/carousel-item.blade.php index 81b2f05d..3d5eb0b8 100644 --- a/resources/views/components/carousel-item.blade.php +++ b/resources/views/components/carousel-item.blade.php @@ -34,7 +34,7 @@ data-material-carousel-surface class="relative size-full overflow-hidden rounded-corner-xl bg-surface-container-highest text-on-surface translate-x-(--material-carousel-shift) [clip-path:inset(0_var(--material-carousel-inset,0px)_round_var(--md-sys-shape-corner-xl))]" > -
+
{{ $slot }}
diff --git a/resources/views/components/carousel.blade.php b/resources/views/components/carousel.blade.php index ef2af072..1e79686d 100644 --- a/resources/views/components/carousel.blade.php +++ b/resources/views/components/carousel.blade.php @@ -40,8 +40,10 @@ keys move one item, Home and End to the ends; focus moving into an item, or a press on one that is not fully open, brings it into focus. `controls` adds previous and next icon buttons under the row — by default only where the pointer is fine (a mouse or trackpad); - `true` always, `false` never. Under reduced motion they scroll instantly and content no - longer slides inside its mask. RTL mirrors the keylines, keys and buttons. + `true` always, `false` never. Under reduced motion they scroll instantly and nothing is + masked: every item stays at its large size, which is M3's rule for a carousel under reduced + motion (docs/reference/m3/styles.md § Motion → Accessibility requirements). RTL mirrors the + keylines, keys and buttons. Re-measures itself when resized, when a Livewire morph resets its styles and when items come and go. The row's id, which the buttons control, is new with every render; the row diff --git a/tests/Browser/CarouselTest.php b/tests/Browser/CarouselTest.php index 06d0c3d7..2ea928c1 100644 --- a/tests/Browser/CarouselTest.php +++ b/tests/Browser/CarouselTest.php @@ -146,15 +146,14 @@ it('brings a partly hidden item into focus when it is pressed', function () { $page->assertScript(onCarousel(0, 'return inset(4) < 0.5 && scroller.scrollLeft > 0')); }); -it('scrolls instantly and keeps content pinned to its mask under reduced motion', function () { +it('scrolls instantly and leaves every item unmasked under reduced motion', function () { carouselShowcase(['reducedMotion' => 'reduce']) ->assertScript(onCarousel(0, <<<'JS' root.querySelector('[aria-label="Next"]').click() const arrived = at(1) await pause(50) - const last = items.length - 1 - return arrived && inset(last) > 0.5 - && surface(last).style.getPropertyValue('--material-carousel-pin') === surface(last).style.getPropertyValue('--material-carousel-inset') + return arrived && items.every((_, i) => inset(i) === 0) + && items.every((item) => Math.abs(item.getBoundingClientRect().width - size) < 1.5) JS)); }); From 02d908c5264849adede2696c703fd9d75932bd71 Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 06:01:42 +0200 Subject: [PATCH 06/16] Pin a dialog's headline and actions, and let it be an alert dialog Plan step 19, containment.md C-06, C-17 and C-20. The whole box scrolled, so a long dialog scrolled its headline and its buttons away; the header, the body and the action row are now separate rows of the flex column, each carrying the 24dp padding the box used to hold, and only the body scrolls. `separator` draws the divider under the header and above the actions, where it now stays put. The full-screen header is M3's 56dp (was 64) and its action bar 56 (was ~72). New `alert` prop for M3's "on web, basic dialogs should have the alert dialog role", and a `subtitle` is always the dialog's `aria-describedby`. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- .../livewire-material-development/SKILL.md | 2 +- resources/views/components/modal.blade.php | 87 +++++++++++++------ .../showcase/sections/containment.blade.php | 2 +- tests/Feature/Components/OverlayTest.php | 41 ++++++++- 4 files changed, 98 insertions(+), 34 deletions(-) diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index 7cd9c5d9..f591786c 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -475,7 +475,7 @@ An M3 dialog on native ``. Bind with `wire:model` to a flag or an id; cl ``` -Props: `title`, `subtitle`, `icon` (centred hero icon), `separator`, `persistent` (no Escape or scrim), `fullscreen` (whole screen on a compact window, below `medium`, for forms — M3 allows a full-screen dialog only there), `box-class`. Never remove its `wire:ignore.self` behaviour by re-rendering it conditionally with `@if`; toggle the bound property instead. +Props: `title`, `subtitle`, `icon` (centred hero icon), `separator` (a divider under the headline and above the actions), `persistent` (no Escape or scrim), `fullscreen` (whole screen on a compact window, below `medium`, for forms — M3 allows a full-screen dialog only there), `alert` (`role="alertdialog"` for a dialog that interrupts to say something important — not for forms), `box-class`. The headline and the action row are pinned and only the body between them scrolls, as M3 requires, so do not put `overflow` on `box-class`. Never remove its `wire:ignore.self` behaviour by re-rendering it conditionally with `@if`; toggle the bound property instead. ### `` diff --git a/resources/views/components/modal.blade.php b/resources/views/components/modal.blade.php index 190a539e..6be807d1 100644 --- a/resources/views/components/modal.blade.php +++ b/resources/views/components/modal.blade.php @@ -20,9 +20,21 @@ on-surface-variant, and the `actions` slot at the end. `icon` puts a secondary-coloured icon above a centred title, as M3 draws a dialog with a hero icon. `fullscreen` makes a dialog that holds a form take the whole screen on a compact window (below `medium`, 600px — M3 uses - full-screen dialogs "only in compact breakpoints"), with a close button and the title in a top bar - clear of the notch. `persistent` ignores Escape and the scrim, for a dialog that must be - answered. It opens on the fast spatial spring and closes at once, as M3's do. --}} + full-screen dialogs "only in compact breakpoints"), with a 56px close-and-title bar clear of + the notch. `persistent` ignores Escape and the scrim, for a dialog that must be + answered. It opens on the fast spatial spring and closes at once, as M3's do. + + "Dialog content generally shouldn't scroll; if it must, the title stays pinned at the top and + the buttons at the bottom" (docs/reference/m3/components-actions-communication-containment.md + § Dialogs → Behaviour): the header and the action row are their own rows of the flex column + and only the body between them scrolls, each with the 24dp padding the box used to carry. + `separator` draws M3's divider under the pinned header and above the pinned actions. + + `alert` is M3's "on web, basic dialogs should have the alert dialog role": it sets + `role="alertdialog"` and points `aria-describedby` at the body, for the dialog that + interrupts to say something important. It is opt-in, because ARIA-APG keeps `alertdialog` + for exactly that and a form dialog would over-announce with it. A `subtitle` is always the + dialog's description. --}} @props([ 'title' => null, @@ -31,12 +43,18 @@ 'separator' => false, 'persistent' => false, 'fullscreen' => false, + 'alert' => false, 'boxClass' => null, ]) @php $model = $attributes->wire('model')->value() ?: null; $id = $attributes->get('id') ?? 'material-dialog-'.substr(md5($model.'|'.$title), 0, 10); + $header = filled($title) || filled($subtitle) || $icon; + $describedBy = implode(' ', array_filter([ + filled($subtitle) ? $id.'-subtitle' : null, + $alert && $slot->isNotEmpty() ? $id.'-body' : null, + ])); @endphp whereDoesntStartWith('wire:model')->except(['id', 'class'])->merge(['id' => $id]) }} @class([ 'm-auto max-h-[calc(100dvh-3rem)] w-[calc(100vw-3rem)] max-w-[35rem] min-w-70 overflow-visible bg-transparent p-0 text-on-surface', @@ -64,12 +84,12 @@ ]) >
$fullscreen, + 'flex max-h-[inherit] flex-col overflow-hidden rounded-corner-xl bg-surface-container-high shadow-elevation-3', + 'max-medium:h-full max-medium:rounded-corner-none max-medium:pt-[var(--material-safe-top,env(safe-area-inset-top))]' => $fullscreen, $boxClass, ])> @if ($fullscreen) -
+
@if (filled($title)) @@ -78,35 +98,46 @@
@endif -
$fullscreen])> - @if (filled($title) || filled($subtitle) || $icon) - {{-- A full-screen dialog's bar names it on a phone, so only the subtitle stays there. --}} -
$fullscreen && ! $icon && blank($subtitle), 'text-center' => $icon])> - @if ($icon) - - @endif + @if ($header) + {{-- A full-screen dialog's bar names it on a phone, so only the subtitle stays there. --}} +
$fullscreen && ! $icon && blank($subtitle), 'text-center' => $icon])> + @if ($icon) + + @endif - @if (filled($title)) -

$fullscreen && ! $icon])>{{ $title }}

- @endif + @if (filled($title)) +

$fullscreen && ! $icon])>{{ $title }}

+ @endif - @if (filled($subtitle)) -

filled($title) || $icon, 'max-medium:mt-0' => $fullscreen && ! $icon])>{{ $subtitle }}

- @endif + @if (filled($subtitle)) +

filled($title) || $icon, 'max-medium:mt-0' => $fullscreen && ! $icon])>{{ $subtitle }}

+ @endif - @if ($separator) - - @endif -
- @endif + @if ($separator) + + @endif +
+ @endif -
{{ $slot }}
-
+ @if ($slot->isNotEmpty()) +
$header, + 'pt-6' => ! $header, + 'pb-6' => ! isset($actions), + ])> + {{ $slot }} +
+ @endif @isset($actions) + @if ($separator) + + @endif +
$fullscreen, + 'flex shrink-0 flex-wrap items-center justify-end gap-2 px-6 pt-6 pb-6', + 'max-medium:min-h-14 max-medium:border-t max-medium:border-outline-variant max-medium:pt-2 max-medium:pb-2' => $fullscreen, ])> {{ $actions }}
diff --git a/resources/views/showcase/sections/containment.blade.php b/resources/views/showcase/sections/containment.blade.php index 45080614..1c810806 100644 --- a/resources/views/showcase/sections/containment.blade.php +++ b/resources/views/showcase/sections/containment.blade.php @@ -78,7 +78,7 @@ 'Dialogs' => <<<'BLADE'
- + diff --git a/tests/Feature/Components/OverlayTest.php b/tests/Feature/Components/OverlayTest.php index 932bbe1c..76733274 100644 --- a/tests/Feature/Components/OverlayTest.php +++ b/tests/Feature/Components/OverlayTest.php @@ -49,10 +49,43 @@ it('keeps a full-screen dialog\'s subtitle on a phone, where its bar carries the expect($html) ->toMatch('/

/') - ->toContain('

Scan the code

') - ->not->toContain('
') - ->and((string) $this->blade('Text'))->toContain('
') - ->and((string) $this->blade('Text'))->toContain('

Only a subtitle

'); + ->toMatch('/

Scan the code<\/p>/') + ->not->toContain('

') + ->and((string) $this->blade('Text'))->toContain('
') + ->and((string) $this->blade('Text'))->toMatch('/

Only a subtitle<\/p>/'); +}); + +it('pins a dialog\'s headline and actions and scrolls only the body between them', function () { + $html = (string) $this->blade('Body'); + + expect($html) + ->toContain('overflow-hidden rounded-corner-xl bg-surface-container-high shadow-elevation-3') + ->not->toContain('overflow-y-auto rounded-corner-xl') + ->toContain('

') + ->toMatch('/
/') + ->toContain('flex shrink-0 flex-wrap items-center justify-end gap-2 px-6 pt-6 pb-6') + ->and(substr_count($html, 'role="separator"'))->toBe(2); +}); + +it('is an alert dialog when it interrupts, and describes itself by its subtitle', function () { + $alert = (string) $this->blade('This cannot be undone.'); + + preg_match('/id="(material-dialog-[a-z0-9]+)"/', $alert, $id); + + expect($alert) + ->toContain('role="alertdialog"') + ->toContain("aria-describedby=\"{$id[1]}-subtitle {$id[1]}-body\"") + ->and((string) $this->blade('Body')) + ->not->toContain('role="alertdialog"') + ->toMatch('/aria-describedby="material-dialog-[a-z0-9]+-subtitle"/') + ->and((string) $this->blade('Body')) + ->not->toContain('aria-describedby'); +}); + +it('gives a full-screen dialog M3\'s 56px header and action bar', function () { + expect((string) $this->blade('Body')) + ->toContain('flex h-14 shrink-0 items-center gap-1 px-1 medium:hidden') + ->toContain('max-medium:min-h-14 max-medium:border-t max-medium:border-outline-variant max-medium:pt-2 max-medium:pb-2'); }); it('leaves a pane open on Escape unless it is asked to close then too', function () { From dcd28707dd2da269d7cc61a59079e8d66b911e8a Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 06:03:12 +0200 Subject: [PATCH 07/16] Let a segmented row answer, and inset a list's dividers Plan step 19, containment.md C-08, C-21, C-22 and C-16. The segmented fill was declared unlayered, so it beat every state layer in @layer components and a segmented row lit up for nothing: it now sits in the layer, `:where()`d to weigh nothing, ahead of the state rules. Its tone is `surface`, which is ListTokens' ItemSegmentedContainerColor, and a keyboard-focused row morphs to the large corner like a pressed one. `` draws ListTokens' 16dp-inset rule instead of a full-bleed `divide-y`. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- resources/css/components/list.css | 39 +++++++++++++++++++---- resources/views/components/list.blade.php | 10 +++--- tests/Feature/Components/ListTest.php | 7 ++-- 3 files changed, 43 insertions(+), 13 deletions(-) diff --git a/resources/css/components/list.css b/resources/css/components/list.css index e4c7d7ae..27431622 100644 --- a/resources/css/components/list.css +++ b/resources/css/components/list.css @@ -9,9 +9,36 @@ * * Unlayered where a component paints its fill as a utility (``): anything in a @layer loses * to a utility whatever its specificity. + * + * Every selector that paints a row is `:where()`, so they all weigh nothing and the later rule + * wins: the segmented list's own fill is declared first and a row's state layer, further down, + * paints over it. Written any other way — outside the layer, or with its real specificity — the + * fill would beat the state layer and a segmented row would answer nothing. */ @layer components { + /* + * M3 Expressive's segmented list gives each item its own container. ListTokens.kt:201 — + * `ItemSegmentedContainerColor get() = ColorSchemeKeyTokens.Surface`. + */ + :where([data-list='segmented'] > [data-list-item]) { + background-color: var(--md-sys-color-surface); + } + + /* + * ListTokens.kt:30,36 — `DividerLeadingSpace` and `DividerTrailingSpace` are 16dp, so a + * list's dividers are inset from both ends rather than full-bleed (``). + */ + :where([data-list][data-dividers] > [data-list-item]:not(:last-child))::after { + content: ''; + position: absolute; + inset-inline: 16px; + bottom: 0; + height: 1px; + background-color: var(--md-sys-color-outline-variant); + pointer-events: none; + } + :where([data-list-row]) { cursor: pointer; transition: background-color var(--md-sys-motion-effects-fast-duration) var(--md-sys-motion-effects-fast), @@ -39,10 +66,6 @@ outline: none; } -[data-list='segmented'] > [data-list-item] { - background-color: var(--md-sys-color-surface-container); -} - :is([data-list-row], [data-list-item])[data-selected]:not([data-card]) { background-color: var(--md-sys-color-secondary-container); color: var(--md-sys-color-on-secondary-container); @@ -73,8 +96,10 @@ /* * M3 Expressive's segmented list (``): each item its own surface, 2px apart, - * extra-small corners that open to large at the ends, and to large while hovered, pressed or - * selected (ListTokens, androidx Compose Material 3, Apache-2.0). + * extra-small corners that open to medium while hovered and to large at the ends and while + * focused, pressed or selected — the specs page's interaction-state expressive shapes, and + * ListTokens' `ItemPressedContainerExpressiveShape` / `ItemDraggedContainerExpressiveShape` + * (androidx Compose Material 3, Apache-2.0). */ [data-list='segmented'] > [data-list-item] { border-radius: var(--md-sys-shape-corner-xs); @@ -96,6 +121,6 @@ } } -[data-list='segmented'] > [data-list-item]:is([data-selected], [data-list-row]:active) { +[data-list='segmented'] > [data-list-item]:is([data-selected], [data-list-row]:active, [data-list-row]:has([data-list-open]:focus-visible)) { border-radius: var(--md-sys-shape-corner-lg); } diff --git a/resources/views/components/list.blade.php b/resources/views/components/list.blade.php index 582eaeaa..e5ba9aaa 100644 --- a/resources/views/components/list.blade.php +++ b/resources/views/components/list.blade.php @@ -1,9 +1,11 @@ {{-- An M3 list: ``s, one under another. Plain by default — the items sit on the surface around them, with `dividers` between them if - asked. `segmented` is M3 Expressive's list: each item its own surface-container tile, 2px - apart, with small corners that open to large at the ends and while hovered, pressed or - selected (ListTokens, androidx Compose Material 3, Apache-2.0). + asked, inset 16px from both ends as ListTokens' `DividerLeadingSpace`/`DividerTrailingSpace` + say (resources/css/components/list.css draws them). `segmented` is M3 Expressive's list: each + item its own surface tile, 2px apart, with small corners that open to large at the ends and + while hovered, pressed, focused or selected (ListTokens, androidx Compose Material 3, + Apache-2.0). A plain list is a `role="list"` of `listitem`s. `selectable` (or `selection="single"` / `selection="multi"`) makes it the list a person chooses from: M3 maps single- and @@ -38,11 +40,11 @@ role="{{ $selection === null ? 'list' : 'listbox' }}" @if ($selection === 'multi') aria-multiselectable="true" @endif data-list="{{ $segmented ? 'segmented' : 'plain' }}" + @if ($dividers && ! $segmented) data-dividers @endif @if ($label) aria-label="{{ $label }}" @endif {{ $attributes->class([ 'flex flex-col', 'gap-0.5' => $segmented, - 'divide-y divide-outline-variant' => $dividers && ! $segmented, ]) }} > {{ $slot }} diff --git a/tests/Feature/Components/ListTest.php b/tests/Feature/Components/ListTest.php index 09b87260..5e1c650c 100644 --- a/tests/Feature/Components/ListTest.php +++ b/tests/Feature/Components/ListTest.php @@ -5,8 +5,11 @@ it('draws a plain list, with dividers on request', function () { ->toContain('role="list"') ->toContain('aria-label="Files"') ->toContain('data-list="plain"') - ->toContain('divide-y divide-outline-variant') - ->toContain('role="listitem"'); + ->toContain('data-dividers') + ->not->toContain('divide-y') + ->toContain('role="listitem"') + ->and((string) $this->blade(''))->not->toContain('data-dividers') + ->and((string) $this->blade(''))->not->toContain('data-dividers'); }); it('draws M3 Expressive\'s segmented list', function () { From 26a9230a488fa2a20099d9a908681b2288a0837e Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 06:04:19 +0200 Subject: [PATCH 08/16] Give a list item M3's gaps, alignment and expressive icon size Plan step 19, containment.md C-14, C-15 and C-26. The leading and trailing gap was 12px where ListItem.kt's LeadingContentEndPadding and TrailingContentStartPadding are 16dp; a three-line item was middle-aligned and padded 10px where M3 top-aligns an 88dp item and Compose pads it 12; and a segmented list's icons stayed at the baseline 24dp instead of ListTokens' expressive 20dp, which the item now reads from its list with `@aware` and draws from the 20 optical cut. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- .../livewire-material-development/SKILL.md | 2 +- .../views/components/list-item.blade.php | 29 ++++++++++++++----- tests/Feature/Components/ListTest.php | 23 ++++++++++++--- 3 files changed, 41 insertions(+), 13 deletions(-) diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index f591786c..6f1b901a 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -431,7 +431,7 @@ A card or list item that opens something is a **row**: `data-list-row` on it and ### ``, `` -``: `label`, `dividers`, `segmented` (M3 Expressive: separate tiles 2px apart). ``: `title` (or slot), `overline`, `description`, leading `icon` / `avatar` (image URL or initials) / `image` / `leading` slot, trailing `trailing` text / `icon-right` / `end` slot, `link` (the whole item becomes a row that opens it), `selected`, `disabled`. One-, two- and three-line heights follow from the content. +``: `label`, `dividers`, `segmented` (M3 Expressive: separate tiles 2px apart). ``: `title` (or slot), `overline`, `description`, leading `icon` / `avatar` (image URL or initials) / `image` / `leading` slot, trailing `trailing` text / `icon-right` / `end` slot, `link` (the whole item becomes a row that opens it), `selected`, `disabled`. One-, two- and three-line heights follow from the content, and a three-line item top-aligns as M3 asks. Its icons are 24px, 20px in a `segmented` list. A list a person chooses from is `` (or `selection="single"` / `selection="multi"`): M3 maps those to a **list box** of **options**, so the container becomes `role="listbox"` (`aria-multiselectable` when multi) and each item an `option` announcing `aria-selected`. A selected option also draws a trailing check — M3 never allows colour as the only cue — which `icon-right` or a leading checkbox replaces. A plain list stays `role="list"`, where `selected` is `aria-current`. `disabled` renders no link and announces `aria-disabled`. diff --git a/resources/views/components/list-item.blade.php b/resources/views/components/list-item.blade.php index 04c720f4..f6ee5596 100644 --- a/resources/views/components/list-item.blade.php +++ b/resources/views/components/list-item.blade.php @@ -8,7 +8,11 @@ `avatar` (an image URL, or initials in primary-container) or `image` (a 56px thumbnail), or a `leading` slot (a checkbox, a switch). The trailing element is `trailing` text (label-small), `icon-right`, or an `end` slot for controls (a menu, a switch). One-, two- and three-line - heights (56, 72, 88px) follow from what is given (ListTokens, androidx Compose Material 3, Apache-2.0). + heights (56, 72, 88px) follow from what is given, 16px between the item and what leads or + trails it, and a three-line item top-aligns rather than centring — M3 aligns an item middle + "by default, top-aligned if the item is 88dp+ or has 3+ lines of text". Its icons are 24px, + or 20px in a `segmented` list, which is M3 Expressive's (ListTokens, androidx Compose + Material 3, Apache-2.0). `link` makes the whole item the link. Otherwise, to make it open something while its trailing controls keep their own presses, give it `data-list-row` and put `data-list-open` on the one @@ -38,10 +42,12 @@ 'disabled' => false, ]) -{{-- Whether the `` around it is one a person chooses from, and how many it takes. --}} +{{-- The `` around it: whether it is one a person chooses from and how many it takes, and + whether it is the expressive (segmented) one, whose icons are a size smaller. --}} @aware([ 'selectable' => false, 'selection' => null, + 'segmented' => false, ]) @php @@ -50,6 +56,11 @@ $initials = filled($avatar) && ! str_contains((string) $avatar, '/') && ! str_contains((string) $avatar, '.'); $option = $selectable || $selection !== null; $check = $option && $selected && blank($iconRight); + + // ListTokens.kt:153,156,332,335 — ItemLeading/TrailingIconExpressiveSize = 20dp against the + // baseline 24dp. At 20px the symbol is drawn from the 20 optical cut, not the 24 scaled down. + $iconSize = $segmented ? 'size-5' : 'size-6'; + $optical = $segmented ? '20' : '24'; @endphp
class([ - 'relative flex items-center gap-3 px-4 text-on-surface', + 'relative flex gap-4 px-4 text-on-surface', + 'items-center' => $lines !== 2, + 'items-start' => $lines === 2, 'min-h-14 py-2' => $lines === 0, - 'min-h-18 py-2.5' => $lines === 1, - 'min-h-22 py-2.5' => $lines === 2, + 'min-h-18 py-2' => $lines === 1, + 'min-h-22 py-3' => $lines === 2, 'pointer-events-none text-on-surface/38' => $disabled, ]) }} > @@ -78,7 +91,7 @@ @elseif ($image) @elseif ($icon) - + @endif
@@ -111,8 +124,8 @@ @endif @if ($iconRight) - + @elseif ($check) - + @endif
diff --git a/tests/Feature/Components/ListTest.php b/tests/Feature/Components/ListTest.php index 5e1c650c..4349175b 100644 --- a/tests/Feature/Components/ListTest.php +++ b/tests/Feature/Components/ListTest.php @@ -18,10 +18,25 @@ it('draws M3 Expressive\'s segmented list', function () { ->toContain('gap-0.5'); }); -it('grows an item from one to three lines', function () { - expect((string) $this->blade(''))->toContain('min-h-14') - ->and((string) $this->blade(''))->toContain('min-h-18')->toContain('248 MB') - ->and((string) $this->blade(''))->toContain('min-h-22')->toContain('Protected'); +it('grows an item from one to three lines, top-aligning the tallest', function () { + expect((string) $this->blade(''))->toContain('items-center')->toContain('min-h-14 py-2') + ->and((string) $this->blade(''))->toContain('items-center')->toContain('min-h-18 py-2')->toContain('248 MB') + ->and((string) $this->blade('')) + ->toContain('items-start') + ->toContain('min-h-22 py-3') + ->toContain('Protected') + ->not->toContain('items-center'); +}); + +it('leaves 16px between the item and what leads or trails it', function () { + expect((string) $this->blade(''))->toContain('flex gap-4 px-4'); +}); + +it('draws the expressive icon size in a segmented list', function () { + expect((string) $this->blade('')) + ->toContain('size-5') + ->not->toContain('size-6') + ->and((string) $this->blade(''))->toContain('size-6'); }); it('leads with an icon, an avatar or an image, and trails with text or an icon', function () { From 675cfc806aaa52cc02bdc1bb2a73c645d041ab37 Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 06:07:14 +0200 Subject: [PATCH 09/16] Give a card per-state elevation and M3's two keyboard models MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plan step 19, containment.md C-13, C-23 and the directly actionable card of C-13/C-18. A card had one elevation and never changed it, and its hover replaced the elevated card's shadow with the state layer; it now names its variant in `data-card` and moves a step on hover (elevated 1 to 2, filled and outlined 0 to 1) with the layer over it. The 12 to 16 corner morph on hover is gone: M3 gives a card one shape and lists shape morph for buttons, FABs and list items only. New `actionable` prop for M3's directly actionable card — the card is the one tab stop, with `role="button"` (or `link`), its `title` as the name, and Enter or Space reaching the opener from resources/js/list-rows.js. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- .../livewire-material-development/SKILL.md | 4 ++- resources/css/components/list.css | 25 ++++++++++--- resources/js/list-rows.js | 26 ++++++++++++++ resources/views/components/card.blade.php | 35 +++++++++++++++---- .../showcase/sections/containment.blade.php | 9 +++++ tests/Browser/ContainmentTest.php | 22 ++++++++++-- tests/Feature/Components/CardTest.php | 28 +++++++++++++-- 7 files changed, 131 insertions(+), 18 deletions(-) diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index 6f1b901a..361a3660 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -420,7 +420,7 @@ The `illustration` slot draws the application's own artwork in place of the shap `variant`: `filled` (default, surface-container-highest), `elevated`, `outlined`; medium corner. Props `title`, `subtitle`, `separator`; slots `figure` (full-bleed media), `menu` (top-end), `actions` (end-aligned). Do not pass `bg-*`; use `variant`. -A card or list item that opens something is a **row**: `data-list-row` on it and `data-list-open` on its one opener (the title link or a button). A press anywhere else on the row reaches the opener; its other controls keep their own presses. Never wrap a card in `` or use a stretched link. +A card or list item that opens something is a **row**: `data-list-row` on it and `data-list-open` on its one opener (the title link or a button). A press anywhere else on the row reaches the opener; its other controls keep their own presses. Never wrap a card in `` or use a stretched link. A row answers with the state layer and one step of elevation; its corner does not move. ```blade @@ -429,6 +429,8 @@ A card or list item that opens something is a **row**: `data-list-row` on it and ``` +That is M3's *non-actionable card with actionable elements*: Tab walks the controls inside. For M3's *directly actionable card*, where Tab lands on the card and then moves to the next card, add `actionable` (and `role="link"` where it goes somewhere) and put `tabindex="-1"` on the opener — the card is then the tab stop, named by its `title`, and Enter or Space on it reaches the opener while the card's other actions follow it. + ### ``, `` ``: `label`, `dividers`, `segmented` (M3 Expressive: separate tiles 2px apart). ``: `title` (or slot), `overline`, `description`, leading `icon` / `avatar` (image URL or initials) / `image` / `leading` slot, trailing `trailing` text / `icon-right` / `end` slot, `link` (the whole item becomes a row that opens it), `selected`, `disabled`. One-, two- and three-line heights follow from the content, and a three-line item top-aligns as M3 asks. Its icons are 24px, 20px in a `segmented` list. diff --git a/resources/css/components/list.css b/resources/css/components/list.css index 27431622..a0454748 100644 --- a/resources/css/components/list.css +++ b/resources/css/components/list.css @@ -71,17 +71,27 @@ color: var(--md-sys-color-on-secondary-container); } -/* A card that opens answers with its container one tone up and its corner opening a step. */ +/* + * A card that opens answers with M3's state layer and one step of elevation, both written as one + * box-shadow because the elevated card's rest level is a `shadow-elevation-1` utility that only + * an unlayered rule can replace. Per-state elevation from the token files (the specs page's + * Hovered / Focused / Pressed rows): elevated 1 → 2 hovered → 1 focused and pressed; filled and + * outlined 0 → 1 hovered → 0. Its corner does not move: M3 gives a card one shape and specifies + * shape morph for buttons, FABs and list items, never for cards. + */ [data-card][data-list-row] { - transition-property: border-radius, background-color, box-shadow; + transition-property: background-color, box-shadow; transition-duration: var(--md-sys-motion-spatial-default-duration); transition-timing-function: var(--md-sys-motion-spatial-default); } @media (hover: hover) { [data-card][data-list-row]:hover:not(:has(:is(a, button, input, select, textarea, label, summary):not([data-list-open]):hover)) { - border-radius: var(--md-sys-shape-corner-lg); - box-shadow: inset 0 0 0 100vmax color-mix(in srgb, var(--md-sys-color-on-surface) 8%, transparent); + box-shadow: var(--md-sys-elevation-1), inset 0 0 0 100vmax color-mix(in srgb, var(--md-sys-color-on-surface) 8%, transparent); + } + + [data-card='elevated'][data-list-row]:hover:not(:has(:is(a, button, input, select, textarea, label, summary):not([data-list-open]):hover)) { + box-shadow: var(--md-sys-elevation-2), inset 0 0 0 100vmax color-mix(in srgb, var(--md-sys-color-on-surface) 8%, transparent); } } @@ -89,7 +99,12 @@ box-shadow: inset 0 0 0 100vmax color-mix(in srgb, var(--md-sys-color-on-surface) 10%, transparent); } -[data-card][data-list-row]:has([data-list-open]:focus-visible) { +[data-card='elevated'][data-list-row]:active:not(:has(:is(a, button, input, select, textarea, label, summary):not([data-list-open]):active)) { + box-shadow: var(--md-sys-elevation-1), inset 0 0 0 100vmax color-mix(in srgb, var(--md-sys-color-on-surface) 10%, transparent); +} + +/* Focus is on the card itself when the card is the tab stop (``). */ +[data-card][data-list-row]:is(:focus-visible, :has([data-list-open]:focus-visible)) { outline: 3px solid var(--md-sys-color-secondary); outline-offset: 2px; } diff --git a/resources/js/list-rows.js b/resources/js/list-rows.js index 98669913..a9f624eb 100644 --- a/resources/js/list-rows.js +++ b/resources/js/list-rows.js @@ -11,6 +11,11 @@ * Not a stretched link (`::after { inset: 0 }`): Safari makes no containing block of a , so in * a table every overlay would cover the whole table; and not one +
diff --git a/tests/Feature/Components/OverlayTest.php b/tests/Feature/Components/OverlayTest.php index 76733274..316b444d 100644 --- a/tests/Feature/Components/OverlayTest.php +++ b/tests/Feature/Components/OverlayTest.php @@ -129,9 +129,12 @@ it('draws a modal bottom sheet with a drag handle, or a standard one without a s ->toContain('data-drag-handle') ->toContain('aria-modal="true"') ->toContain('py-5.5') - ->toContain('touch-target h-1 w-8') + ->toContain('touch-target h-1 w-8 rounded-corner-full bg-on-surface-variant ') + ->toContain('--sheet-max-height: min(50dvh, calc(100dvh - 72px))') ->and((string) $this->blade('Body')) ->toContain('...materialBottomSheet(true)') ->not->toContain('bg-scrim/32') - ->not->toContain('aria-modal'); + ->not->toContain('aria-modal') + ->and((string) $this->blade('Body')) + ->toContain('--sheet-max-height: min(90dvh, calc(100dvh - 72px))'); }); From 73937c372616fd9e5e92e90409b92cd8561c23a1 Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 06:08:13 +0200 Subject: [PATCH 11/16] Align a side sheet's actions left, in M3's 72dp row MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plan step 19, containment.md C-10. The action row was right-aligned with 24px above it; the side-sheet specs table puts bottom actions on the left in a 72dp row with 16dp above and 24dp below. A dialog's actions stay trailing-aligned — M3 specifies the two differently. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- .../boost/skills/livewire-material-development/SKILL.md | 2 +- resources/views/components/drawer.blade.php | 5 ++++- tests/Feature/Components/OverlayTest.php | 5 +++++ 3 files changed, 10 insertions(+), 2 deletions(-) diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index d5e7b2ef..4dfe7bfa 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -481,7 +481,7 @@ Props: `title`, `subtitle`, `icon` (centred hero icon), `separator` (a divider u ### `` -An M3 side sheet, bound like ``; `close()` in scope. Props: `title`, `subtitle`, `separator`, `side` (`end` default, `start`), `width` (`25rem`), `with-close-button` (**default true** — M3 requires a close affordance; `:with-close-button="false"` is ignored when Escape or the scrim is off, and on a pane), `close-on-escape` (default true), `without-backdrop-close`, `actions` slot. `pane` (with `pane-width`, `22.5rem` — M3's 360dp fixed pane) turns it into a second pane from `expanded`, where M3 shows two panes: render it after the list inside `
`. Escape leaves a pane open unless `pane-close-on-escape`. Its body is a size container — lay out inside with `@md:` (a *container* query), never a window class. +An M3 side sheet, bound like ``; `close()` in scope. Props: `title`, `subtitle`, `separator`, `side` (`end` default, `start`), `width` (`25rem`), `with-close-button` (**default true** — M3 requires a close affordance; `:with-close-button="false"` is ignored when Escape or the scrim is off, and on a pane), `close-on-escape` (default true), `without-backdrop-close`, `actions` slot (**left**-aligned in a 72dp row, which is what the side-sheet spec says; a dialog's are trailing-aligned). `pane` (with `pane-width`, `22.5rem` — M3's 360dp fixed pane) turns it into a second pane from `expanded`, where M3 shows two panes: render it after the list inside `
`. Escape leaves a pane open unless `pane-close-on-escape`. Its body is a size container — lay out inside with `@md:` (a *container* query), never a window class. ### `` diff --git a/resources/views/components/drawer.blade.php b/resources/views/components/drawer.blade.php index 33d67b2b..7d4c2d47 100644 --- a/resources/views/components/drawer.blade.php +++ b/resources/views/components/drawer.blade.php @@ -147,7 +147,10 @@
@isset($actions) -
+ {{-- The side-sheet specs table: bottom actions 72dp tall, 16dp above them, 24dp below + (the sheet's own padding), aligned **left** — a dialog's are trailing-aligned, and + M3 specifies the two differently. --}} +
{{ $actions }}
@endisset diff --git a/tests/Feature/Components/OverlayTest.php b/tests/Feature/Components/OverlayTest.php index 316b444d..af8632db 100644 --- a/tests/Feature/Components/OverlayTest.php +++ b/tests/Feature/Components/OverlayTest.php @@ -106,6 +106,11 @@ it('always offers a way out of a side sheet, as M3 requires', function () { ->and((string) $this->blade('Body'))->not->toContain('aria-label="Close"'); }); +it('puts a side sheet\'s actions on the left, in M3\'s 72dp row', function () { + expect((string) $this->blade('Body')) + ->toContain('flex min-h-18 shrink-0 flex-wrap items-center justify-start gap-2 pt-4'); +}); + it('slides a side sheet in from either edge, and is a pane from expanded when asked', function () { expect((string) $this->blade('Body')) ->toContain('x-trap.inert.noscroll="open && ! wide"') From a237d33426315871610b5698c3f57d0695c9bd38 Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 06:09:23 +0200 Subject: [PATCH 12/16] Ease a collapse open, which its own comment already promised Plan step 19, containment.md C-24. `interpolate-size: allow-keywords` was set and nothing transitioned, so the content snapped open. A new resources/css/components/collapse.css transitions `block-size` on `::details-content` over the fast spatial spring, with `content-visibility` `allow-discrete` beside it so the section stays rendered while it closes. The `
` carries `data-collapse` for the rule to find. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- resources/css/components/collapse.css | 30 +++++++++++++++++++ resources/css/material.css | 1 + resources/views/components/collapse.blade.php | 4 ++- tests/Feature/Components/CollapseTest.php | 6 ++-- 4 files changed, 38 insertions(+), 3 deletions(-) create mode 100644 resources/css/components/collapse.css diff --git a/resources/css/components/collapse.css b/resources/css/components/collapse.css new file mode 100644 index 00000000..0ba2d2cf --- /dev/null +++ b/resources/css/components/collapse.css @@ -0,0 +1,30 @@ +/* + * ``'s height, eased open. + * + * The native `
` opens and closes by itself; what it cannot do on its own is animate, so + * the component sets `interpolate-size: allow-keywords` (which makes `0` → `auto` an animatable + * pair) and this transitions `block-size` on `::details-content`, the pseudo-element that holds + * everything after the ``. `content-visibility` goes with it, `allow-discrete`, so the + * content stays rendered while it closes rather than vanishing on the first frame. + * + * The fast spatial spring, as the chevron beside it: M3's spatial track is for anything that + * changes size or position. Under reduced motion the duration token is zero + * (resources/css/tokens/motion.css), so the section snaps open with nothing else to do. + * + * Not an M3 component — M3 has expandable list items and menu expansion, no standalone disclosure + * — so the geometry is the library's and only the motion tokens are M3's. + */ + +@layer components { + [data-collapse]::details-content { + block-size: 0; + overflow: hidden; + transition: + block-size var(--md-sys-motion-spatial-fast-duration) var(--md-sys-motion-spatial-fast), + content-visibility var(--md-sys-motion-spatial-fast-duration) allow-discrete; + } + + [data-collapse][open]::details-content { + block-size: auto; + } +} diff --git a/resources/css/material.css b/resources/css/material.css index 4ffefa6c..43682ca3 100644 --- a/resources/css/material.css +++ b/resources/css/material.css @@ -22,6 +22,7 @@ @import './tokens/state.css'; @import './components/groups.css'; @import './components/list.css'; +@import './components/collapse.css'; @import './components/field.css'; @import './components/menu.css'; @import './components/selection.css'; diff --git a/resources/views/components/collapse.blade.php b/resources/views/components/collapse.blade.php index e1ed8913..ec7ef45e 100644 --- a/resources/views/components/collapse.blade.php +++ b/resources/views/components/collapse.blade.php @@ -5,7 +5,8 @@ and is announced as a disclosure. Drawn in M3's terms: a title-medium `title` (or a `heading` slot), an optional leading `icon`, a chevron that turns over on the spatial spring, and — where the browser supports animating `details` content (`interpolate-size`) — a height - that eases open. `open` starts it open. `variant`: `plain` (the default, on the surface around + that eases open on the same spring (`data-collapse`, resources/css/components/collapse.css). + `open` starts it open. `variant`: `plain` (the default, on the surface around it) or `filled` (a surface-container tile with a large corner). Its open state can be bound, both ways: @@ -38,6 +39,7 @@
toContain('wire:ignore.self') ->toContain(' open ') ->toContain('rounded-corner-lg bg-surface-container') + ->toContain('data-collapse') + ->toContain('[interpolate-size:allow-keywords]') ->toContain('How long do links last?') ->toContain('Until the expiry.') ->toContain('group-open/collapse:rotate-180'); @@ -20,12 +22,12 @@ it('has no Alpine on it without a binding', function () { $html = (string) $this->blade('Body'); expect($html) - ->toMatch('/toMatch('/not->toContain('x-data') ->not->toContain('x-modelable') ->not->toContain('x-on:toggle') ->and((string) $this->blade('Body')) - ->toMatch('/toMatch('/ Date: Mon, 14 Sep 2026 06:10:02 +0200 Subject: [PATCH 13/16] Put the mail card on M3's corner scale and its header at title-lg Plan step 19, containment.md C-27 and C-28. `.inner-body` was 24px, a value not on M3's 0/4/8/12/16/20/28/32/48 scale; it is 28px, the extra-large corner of the dialog and bottom-sheet surface it stands in for. `.header a` is title-large at weight 400, which its own section comment and the `h2` under it already said. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- resources/views/mail/theme.blade.php | 8 ++++---- tests/Feature/MailThemeTest.php | 15 ++++++++++++++- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/resources/views/mail/theme.blade.php b/resources/views/mail/theme.blade.php index 910d6527..3dff94a4 100644 --- a/resources/views/mail/theme.blade.php +++ b/resources/views/mail/theme.blade.php @@ -203,7 +203,7 @@ img { width: 100%; } -/* Header: the app name in title-lg, or the configured logo */ +/* Header: the app name in title-lg (22/28 at weight 400), or the configured logo */ .header { padding: 32px 0 24px; @@ -213,7 +213,7 @@ img { .header a { color: {{ $role['on-surface'] }}; font-size: 22px; - font-weight: 500; + font-weight: 400; letter-spacing: 0; line-height: 28px; text-decoration: none; @@ -226,7 +226,7 @@ img { margin: 0 auto; } -/* Body: the card, separated from the page by tone alone */ +/* Body: the card, separated from the page by tone alone, on M3's extra-large corner */ .body { -premailer-cellpadding: 0; @@ -245,7 +245,7 @@ img { -premailer-width: 570px; background-color: {{ $card }}; border: 0; - border-radius: 24px; + border-radius: 28px; margin: 0 auto; padding: 0; width: 570px; diff --git a/tests/Feature/MailThemeTest.php b/tests/Feature/MailThemeTest.php index cc4dca63..ee8a1dfe 100644 --- a/tests/Feature/MailThemeTest.php +++ b/tests/Feature/MailThemeTest.php @@ -118,7 +118,7 @@ it('inlines the application\'s scheme onto the mail', function () { ->toContain('border-top: 16px solid #123456') ->toContain('color: #fefefe') ->toContain('border-radius: 9999px') - ->and(inlineStyle($html, 'inner-body'))->toContain('background-color: #fdfdfd') + ->and(inlineStyle($html, 'inner-body'))->toContain('background-color: #fdfdfd')->toContain('border-radius: 28px') ->and(inlineStyle($html, 'wrapper'))->toContain('background-color: #eeeeee') ->and(inlineStyle($html, 'panel-content'))->toContain('background-color: #eeeeee') ->and($html) @@ -190,6 +190,19 @@ it('styles every button colour Laravel and M3 name', function () { expect($css)->not->toContain('@media'); }); +it('keeps every corner and weight on M3\'s scales', function () { + $css = view('livewire-material::mail.theme')->render(); + + preg_match_all('/border-radius: (\d+)px/', $css, $corners); + + // M3's shape scale, plus the `full` corner a button draws as a large pixel value. + expect(array_unique($corners[1]))->each->toBeIn(['0', '4', '8', '12', '16', '20', '28', '32', '48', '9999']) + ->and($css)->toContain(<<<'CSS' + .header a { + CSS) + ->toMatch('/\.header a \{[^}]*font-weight: 400/'); +}); + it('leaves the application\'s mail components alone unless asked', function () { expect(config('mail.markdown.paths'))->not->toContain(LivewireMaterialServiceProvider::mailComponentPath()); From ad37862a9f4311ad96f80e1e52bf7e78934005d8 Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 06:12:24 +0200 Subject: [PATCH 14/16] Give the carousel M3's end padding and a role for its label MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plan step 19, containment.md C-12 and C-25. `padding` defaulted to 0 where M3's specs table gives every layout 16dp of leading and trailing padding — leading only for `uncontained`, none for the edge-to-edge `full-screen` — so the default is 16 and each layout now says which ends it applies to (`data-padding`, `data-padding-end`). The row gains the 8dp above and below that goes with it, without shortening the items. The overlay label is `inverse-on-surface` instead of a literal `white`, which no scheme or contrast profile follows. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- .../livewire-material-development/SKILL.md | 2 +- resources/js/carousel.js | 3 ++- .../views/components/carousel-item.blade.php | 6 +++-- resources/views/components/carousel.blade.php | 23 ++++++++++++++----- tests/Feature/Components/CarouselTest.php | 11 ++++++--- 5 files changed, 32 insertions(+), 13 deletions(-) diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index 4dfe7bfa..8f408372 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -499,7 +499,7 @@ An M3 bottom sheet, bound like ``: modal by default (scrim, inert page, ``` -A row of items that change size between M3's keylines as it scrolls (native scroll snap; items are masked, content keeps its size). ``: `layout` (`multi-browse` default, `hero`, `uncontained`, `full-screen`), `item-width` (px or any CSS length; the large size multi-browse aims for, the fixed size uncontained keeps, the cap for hero; 186 by default), `height` (205px), `padding` (px at the ends, 0), `centered` (hero), `label` (the region's name, "Carousel" by default), `controls` (previous/next buttons: default fine pointers only, `true` always, `false` never). ``: slot is an `` (fills and crops) or an element sized `size-full`; `label` overlays a line of text. A focusable `region` of `slide` groups named "n of m"; arrow keys move one item while the row has focus, Home/End to the ends. Works after a Livewire morph, in RTL and under reduced motion. Give items a `wire:key` in a loop. +A row of items that change size between M3's keylines as it scrolls (native scroll snap; items are masked, content keeps its size). ``: `layout` (`multi-browse` default, `hero`, `uncontained`, `full-screen`), `item-width` (px or any CSS length; the large size multi-browse aims for, the fixed size uncontained keeps, the cap for hero; 186 by default), `height` (205px), `padding` (px at the ends, **16** — M3's specs table; leading only for `uncontained`, none for `full-screen`), `centered` (hero), `label` (the region's name, "Carousel" by default), `controls` (previous/next buttons: default fine pointers only, `true` always, `false` never). ``: slot is an `` (fills and crops) or an element sized `size-full`; `label` overlays a line of text. A focusable `region` of `slide` groups named "n of m"; arrow keys move one item while the row has focus, Home/End to the ends. Works after a Livewire morph, in RTL and under reduced motion. Give items a `wire:key` in a loop. ### `` diff --git a/resources/js/carousel.js b/resources/js/carousel.js index 734fdf37..afaaaa60 100644 --- a/resources/js/carousel.js +++ b/resources/js/carousel.js @@ -864,6 +864,7 @@ document.addEventListener('alpine:init', () => { const space = scroller.clientWidth const itemSpacing = parseFloat(getComputedStyle(scroller).columnGap) || 0 const padding = Number(root.dataset.padding) || 0 + const paddingEnd = Number(root.dataset.paddingEnd) || 0 const probe = this.$refs.probe const preferred = probe ? probe.getBoundingClientRect().width : null @@ -885,7 +886,7 @@ document.addEventListener('alpine:init', () => { 'full-screen': () => fullScreenKeylineList(space, itemSpacing), }[root.dataset.materialCarousel] ?? (() => multiBrowseKeylineList(space, preferred ?? 0, itemSpacing, count)) - const strategy = count === 0 ? createStrategy(EMPTY, space, itemSpacing, 0, 0) : createStrategy(keylines(), space, itemSpacing, padding, padding) + const strategy = count === 0 ? createStrategy(EMPTY, space, itemSpacing, 0, 0) : createStrategy(keylines(), space, itemSpacing, padding, paddingEnd) state.strategy = strategy diff --git a/resources/views/components/carousel-item.blade.php b/resources/views/components/carousel-item.blade.php index 3d5eb0b8..f4a530e9 100644 --- a/resources/views/components/carousel-item.blade.php +++ b/resources/views/components/carousel-item.blade.php @@ -7,7 +7,9 @@ `label` lays a short line of text over the bottom of the art, on a scrim, pinned to the item's visible edge and fading out as the item narrows — Compose's carousel sample, which - fades its label chip in once the mask is wide enough to hold it. + fades its label chip in once the mask is wide enough to hold it. The scrim is what M3 asks + for under text on an image; the text itself is `inverse-on-surface`, a role a scheme and a + contrast profile follow, rather than a literal white. A `group` with `aria-roledescription="slide"`, named "n of m" by the carousel around it (WAI-ARIA's carousel pattern). The item is laid out at the carousel's large size and masked: @@ -43,7 +45,7 @@ data-material-carousel-label class="pointer-events-none absolute inset-x-0 bottom-0 flex bg-linear-to-t from-scrim/60 to-transparent px-4 pt-10 pb-4 opacity-(--material-carousel-label)" > - {{ $label }} + {{ $label }}
@endif
diff --git a/resources/views/components/carousel.blade.php b/resources/views/components/carousel.blade.php index 1e79686d..b2cbad20 100644 --- a/resources/views/components/carousel.blade.php +++ b/resources/views/components/carousel.blade.php @@ -22,9 +22,11 @@ - `full-screen`: one item the width of the carousel at a time (FullScreenCarouselStrategy). `item-width` takes pixels or any CSS length. `height` is the items' height (205px, Compose's - sample). `padding` is Compose's `contentPadding` in pixels (0): the first and last items - rest that far in from the edges while items in between scroll to them. Items are 8px apart - with M3's extra-large corner. + sample). `padding` is Compose's `contentPadding` in pixels: the first and last items rest + that far in from the edges while items in between scroll to them. M3's specs table gives + every layout 16dp of it — `uncontained` at the leading edge only, `full-screen` none — so + that is the default, with the 8dp above and below the row that goes with it. Items are 8px + apart with M3's extra-large corner. The row is a native scroll container with CSS scroll snap, one item per swipe, as Compose's single-advance fling; touch, trackpad and Shift with the wheel scroll it. resources/js/ @@ -54,7 +56,7 @@ 'layout' => 'multi-browse', 'itemWidth' => null, 'height' => null, - 'padding' => 0, + 'padding' => 16, 'centered' => false, 'label' => null, 'controls' => null, @@ -99,12 +101,19 @@ $slides, ); + // The specs table's leading and trailing padding: 16dp for multi-browse and hero, leading + // only for uncontained, none for full-screen, which is edge to edge. + $padding = max(0, (float) $padding); + $paddingStart = $layout === 'full-screen' ? 0.0 : $padding; + $paddingEnd = in_array($layout, ['uncontained', 'full-screen'], true) ? 0.0 : $padding; + $attributes = $attributes ->class('relative') ->merge(array_filter([ 'data-material-carousel' => $layout, 'data-centered' => $layout === 'hero' && $centered ? true : null, - 'data-padding' => (string) max(0, (float) $padding), + 'data-padding' => (string) $paddingStart, + 'data-padding-end' => (string) $paddingEnd, 'style' => implode('; ', array_filter([ $preferredWidth ? "--material-carousel-item-width: {$preferredWidth}" : null, "--material-carousel-slot: {$slotWidth}", @@ -127,8 +136,10 @@ aria-label="{{ $label }}" tabindex="0" @class([ - 'focus-ring flex h-(--material-carousel-height) gap-2 overflow-x-auto overflow-y-hidden overscroll-x-contain', + 'focus-ring flex gap-2 overflow-x-auto overflow-y-hidden overscroll-x-contain', '[scrollbar-width:none] [&::-webkit-scrollbar]:hidden', + 'h-(--material-carousel-height)' => $layout === 'full-screen', + 'h-[calc(var(--material-carousel-height)+1rem)] py-2' => $layout !== 'full-screen', 'snap-x snap-mandatory' => $layout !== 'uncontained', ]) > diff --git a/tests/Feature/Components/CarouselTest.php b/tests/Feature/Components/CarouselTest.php index 47f48567..d9b31c10 100644 --- a/tests/Feature/Components/CarouselTest.php +++ b/tests/Feature/Components/CarouselTest.php @@ -56,7 +56,9 @@ it('browses many by default: 186px items that snap one at a time, 205px high', f ->toContain('aria-label="Carousel"') ->toContain('--material-carousel-item-width: 186px; --material-carousel-slot: 186px; --material-carousel-height: 205px') ->toContain('x-ref="probe"') - ->toContain('data-padding="0"') + ->toContain('data-padding="16"') + ->toContain('data-padding-end="16"') + ->toContain('h-[calc(var(--material-carousel-height)+1rem)] py-2') ->toContain('snap-x snap-mandatory') ->toContain('snap-start snap-always') ->toContain('rounded-corner-xl') @@ -65,9 +67,12 @@ it('browses many by default: 186px items that snap one at a time, 205px high', f }); it('takes the item width in pixels or as a CSS length, and a height and padding', function () { - expect((string) $this->blade('A')) + expect((string) $this->blade('A')) ->toContain('--material-carousel-item-width: 220px; --material-carousel-slot: 220px; --material-carousel-height: 18rem') + ->toContain('data-padding="24"') + ->and((string) $this->blade('A')) ->toContain('data-padding="16"') + ->toContain('data-padding-end="0"') ->and((string) $this->blade('A')) ->toContain('--material-carousel-item-width: 40%;'); }); @@ -136,7 +141,7 @@ it('lays a label over an item on a scrim, and passes attributes to the item', fu ->toContain('data-material-carousel-label') ->toContain('Lake Constance') ->toContain('from-scrim/60') - ->toContain('type-title-md text-white') + ->toContain('type-title-md text-inverse-on-surface') ->toContain('[&>img]:size-full [&>img]:object-cover') ->and((string) $this->blade('A')) ->not->toContain('data-material-carousel-label'); From 9875ba156e097fdbd40879f195ffddd0740fc4b4 Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 06:14:34 +0200 Subject: [PATCH 15/16] Put the carousel's tab stop on its items, as M3 asks Plan step 19, containment.md C-18. The row was the focusable `region` and the items were not focusable at all, which is the thing M3's accessibility page draws a Don't for: "use Tab to place initial focus on the first carousel item", "avoid focusing on the carousel container". Each item is now `tabindex="0"` with the focus ring drawn inside it, the row is out of the tab order, and from a focused item the arrows move one item (moving focus with them), Home and End go to the ends, and Space or Enter opens one that is not fully in view. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- .../livewire-material-development/SKILL.md | 2 +- resources/js/carousel.js | 49 ++++++++++++++----- .../views/components/carousel-item.blade.php | 10 ++-- resources/views/components/carousel.blade.php | 13 ++--- .../showcase/sections/carousel.blade.php | 2 +- tests/Browser/CarouselTest.php | 20 ++++---- tests/Feature/Components/CarouselTest.php | 8 +-- 7 files changed, 70 insertions(+), 34 deletions(-) diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index 8f408372..b999744c 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -499,7 +499,7 @@ An M3 bottom sheet, bound like ``: modal by default (scrim, inert page, ``` -A row of items that change size between M3's keylines as it scrolls (native scroll snap; items are masked, content keeps its size). ``: `layout` (`multi-browse` default, `hero`, `uncontained`, `full-screen`), `item-width` (px or any CSS length; the large size multi-browse aims for, the fixed size uncontained keeps, the cap for hero; 186 by default), `height` (205px), `padding` (px at the ends, **16** — M3's specs table; leading only for `uncontained`, none for `full-screen`), `centered` (hero), `label` (the region's name, "Carousel" by default), `controls` (previous/next buttons: default fine pointers only, `true` always, `false` never). ``: slot is an `` (fills and crops) or an element sized `size-full`; `label` overlays a line of text. A focusable `region` of `slide` groups named "n of m"; arrow keys move one item while the row has focus, Home/End to the ends. Works after a Livewire morph, in RTL and under reduced motion. Give items a `wire:key` in a loop. +A row of items that change size between M3's keylines as it scrolls (native scroll snap; items are masked, content keeps its size). ``: `layout` (`multi-browse` default, `hero`, `uncontained`, `full-screen`), `item-width` (px or any CSS length; the large size multi-browse aims for, the fixed size uncontained keeps, the cap for hero; 186 by default), `height` (205px), `padding` (px at the ends, **16** — M3's specs table; leading only for `uncontained`, none for `full-screen`), `centered` (hero), `label` (the region's name, "Carousel" by default), `controls` (previous/next buttons: default fine pointers only, `true` always, `false` never). ``: slot is an `` (fills and crops) or an element sized `size-full`; `label` overlays a line of text. A `region` of `slide` groups named "n of m", each item a tab stop and the row itself not one, as M3 asks; from a focused item the arrow keys move one item, Home/End go to the ends and Space/Enter opens one that is not fully in view. Works after a Livewire morph, in RTL and under reduced motion. Give items a `wire:key` in a loop. ### `` diff --git a/resources/js/carousel.js b/resources/js/carousel.js index afaaaa60..dc7086b8 100644 --- a/resources/js/carousel.js +++ b/resources/js/carousel.js @@ -1067,31 +1067,58 @@ document.addEventListener('alpine:init', () => { }) }, - /** The row's own keys, while the row itself has focus: a control inside an item keeps its keys. */ + /** + * The items' keys, while an item itself has focus — M3: "Tab or Arrows moves to the + * previous or next carousel item; Space or Enter activates the focused carousel item". + * A control inside an item keeps its own keys, because focus is then on the control + * and not on the item. + */ navigate(event) { - if (event.target !== this.$refs.scroller || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) { + if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) { + return + } + + const index = state.items.findIndex((item) => item.element === event.target) + + if (index < 0) { + return + } + + if (event.key === 'Enter' || event.key === ' ') { + if (this.isMasked(index)) { + event.preventDefault() + this.scrollToItem(index) + } + return } const forward = state.rtl ? 'ArrowLeft' : 'ArrowRight' const backward = state.rtl ? 'ArrowRight' : 'ArrowLeft' - const action = { - [forward]: () => this.next(), - [backward]: () => this.previous(), - Home: () => this.scrollToItem(0), - End: () => this.scrollToItem(state.items.length - 1), + const to = { + [forward]: index + 1, + [backward]: index - 1, + Home: 0, + End: state.items.length - 1, }[event.key] - if (action) { - event.preventDefault() - action() + const target = to === undefined ? undefined : state.items[to] + + if (!target) { + return } + + // The browser would jump the row to the newly focused item; the smooth scroll to + // its snap position is this script's. + event.preventDefault() + target.element.focus({ preventScroll: true }) + this.scrollToItem(to) }, /** Focus inside an item brings that item into focus, as Compose's bring-into-view does. */ reveal(event) { - const element = event.target === this.$refs.scroller ? null : event.target.closest(ITEM) + const element = event.target.closest?.(ITEM) const index = state.items.findIndex((item) => item.element === element) if (index >= 0 && this.isMasked(index)) { diff --git a/resources/views/components/carousel-item.blade.php b/resources/views/components/carousel-item.blade.php index f4a530e9..eefe0e0c 100644 --- a/resources/views/components/carousel-item.blade.php +++ b/resources/views/components/carousel-item.blade.php @@ -11,8 +11,11 @@ for under text on an image; the text itself is `inverse-on-surface`, a role a scheme and a contrast profile follow, rather than a literal white. - A `group` with `aria-roledescription="slide"`, named "n of m" by the carousel around it - (WAI-ARIA's carousel pattern). The item is laid out at the carousel's large size and masked: + A focusable `group` with `aria-roledescription="slide"`, named "n of m" by the carousel + around it. M3 puts the tab stop on the item, not on the row: Tab reaches the first item, the + arrow keys move between them and Space or Enter opens the focused one + (docs/reference/m3/components-actions-communication-containment.md § Carousel → + Accessibility). The item is laid out at the carousel's large size and masked: the surface inside is clipped by `--material-carousel-inset` from both sides with M3's extra-large corner (28px, CarouselDefaults' item shape) and moved by `--material-carousel-shift`, both written by resources/js/carousel.js. Without script the @@ -24,13 +27,14 @@
class([ - 'relative h-full w-(--material-carousel-slot) max-w-full shrink-0 snap-start snap-always', + 'focus-ring relative h-full w-(--material-carousel-slot) max-w-full shrink-0 snap-start snap-always rounded-corner-xl focus-visible:-outline-offset-3', ]) ->merge([ 'role' => 'group', 'aria-roledescription' => __('slide'), 'aria-label' => '[material-carousel-position]', 'data-material-carousel-item' => true, + 'tabindex' => '0', ]) }}>
$layout === 'full-screen', 'h-[calc(var(--material-carousel-height)+1rem)] py-2' => $layout !== 'full-screen', diff --git a/resources/views/showcase/sections/carousel.blade.php b/resources/views/showcase/sections/carousel.blade.php index fb8e6d6e..bd87e761 100644 --- a/resources/views/showcase/sections/carousel.blade.php +++ b/resources/views/showcase/sections/carousel.blade.php @@ -78,7 +78,7 @@

<x-carousel> and <x-carousel-item>: items that change size between M3's keylines as they scroll. - Swipe, scroll with Shift and the wheel, or focus a row and use the arrow keys. + Swipe, scroll with Shift and the wheel, or tab to an item and use the arrow keys.

@foreach ($examples as $title => $code) diff --git a/tests/Browser/CarouselTest.php b/tests/Browser/CarouselTest.php index 2ea928c1..ddf8022d 100644 --- a/tests/Browser/CarouselTest.php +++ b/tests/Browser/CarouselTest.php @@ -60,7 +60,7 @@ function onCarousel(int $index, string $body, string $scope = '#carousel'): stri JS; } -const FIRST_SCROLLER = '#carousel [role="region"] >> nth=0'; +const FIRST_ITEM = '#carousel [data-material-carousel-item] >> nth=0'; function carouselShowcase(array $options = []) { @@ -110,19 +110,21 @@ it('moves one item with the next and previous buttons', function () { it('moves one item with the arrow keys, and to the ends with Home and End', function () { $page = carouselShowcase(); - $page->keys(FIRST_SCROLLER, 'ArrowRight') - ->assertScript(onCarousel(0, 'return at(1)')); + // M3 puts the tab stop on the item, so the keys are the focused item's and each one moves + // focus to the item it scrolls to. + $page->keys(FIRST_ITEM, 'ArrowRight') + ->assertScript(onCarousel(0, 'return at(1) && document.activeElement === items[1]')); - $page->keys(FIRST_SCROLLER, 'ArrowRight') + $page->keys(':focus', 'ArrowRight') ->assertScript(onCarousel(0, 'return at(2)')); - $page->keys(FIRST_SCROLLER, 'ArrowLeft') + $page->keys(':focus', 'ArrowLeft') ->assertScript(onCarousel(0, 'return at(1)')); - $page->keys(FIRST_SCROLLER, 'End') + $page->keys(':focus', 'End') ->assertScript(onCarousel(0, 'return Math.abs(scroller.scrollLeft - (scroller.scrollWidth - scroller.clientWidth)) < 1.5 && inset(items.length - 1) < 0.5 && root.querySelector(\'[aria-label="Next"]\').disabled')); - $page->keys(FIRST_SCROLLER, 'Home') + $page->keys(':focus', 'Home') ->assertScript(onCarousel(0, 'return at(0)')); }); @@ -183,7 +185,7 @@ it('mirrors in a right-to-left page', function () { ->assertNoJavaScriptErrors() ->assertScript(onCarousel(0, 'return size > 0 && at(0) && inset(0) < 0.5 && inset(items.length - 1) > 0.5', 'body')); - $page->keys('[role="region"]', 'ArrowLeft') + $page->keys('[data-material-carousel-item] >> nth=0', 'ArrowLeft') ->assertScript(onCarousel(0, <<<'JS' return scroller.scrollLeft < -1 && at(1) && inset(0) > 0.5 && inset(1) < 0.5 && parseFloat(surface(0).style.getPropertyValue('--material-carousel-shift')) < 0 @@ -192,7 +194,7 @@ it('mirrors in a right-to-left page', function () { $page->click('button[aria-label="Next"]') ->assertScript(onCarousel(0, 'return at(2)', 'body')); - $page->keys('[role="region"]', 'ArrowRight') + $page->keys('[data-material-carousel-item] >> nth=2', 'ArrowRight') ->assertScript(onCarousel(0, 'return at(1)', 'body')); }); diff --git a/tests/Feature/Components/CarouselTest.php b/tests/Feature/Components/CarouselTest.php index d9b31c10..8fba442f 100644 --- a/tests/Feature/Components/CarouselTest.php +++ b/tests/Feature/Components/CarouselTest.php @@ -1,6 +1,6 @@ blade(<<<'BLADE' A lake @@ -17,14 +17,16 @@ it('is a focusable carousel region of slides named n of m', function () { ->toContain('role="region"') ->toContain('aria-roledescription="carousel"') ->toContain('aria-label="Recent uploads"') - ->toContain('tabindex="0"') ->toContain('aria-roledescription="slide"') ->toContain('aria-label="1 of 3"') ->toContain('aria-label="2 of 3"') ->toContain('aria-label="3 of 3"') ->toContain('A lake') ->not->toContain('[material-carousel-position]') - ->and(substr_count($html, 'role="group"'))->toBe(3); + ->and(substr_count($html, 'role="group"'))->toBe(3) + // M3 puts the tab stop on each item and tells you not to focus the container. + ->and(substr_count($html, 'tabindex="0"'))->toBe(3) + ->and($html)->toMatch('/])*>/'); }); it('counts the slides of a carousel inside a slide on their own', function () { From 5e58dd54490dbea730b653419ec0afcca74d261f Mon Sep 17 00:00:00 2001 From: Andreas Reinhold / reini Date: Mon, 14 Sep 2026 06:17:31 +0200 Subject: [PATCH 16/16] Scroll the full-screen carousel down the page, as M3's does Plan step 19, containment.md C-11. The full-screen layout was another horizontal row with a 28px corner and a mask, where M3's "shows one edge-to-edge large item at a time and scrolls vertically". It is now a vertical scroll-snap column: items fill the row with no corner and no mask, 16dp apart, no end padding, the previous/next buttons point up and down and the arrow keys are Up and Down. The row is capped at the 840px medium window, which with the portrait rule in the header comment is as far as CSS can hold M3's "compact and medium, portrait only". The ported FullScreenCarouselStrategy keylines go with it: nothing measures them any more. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9 --- .../livewire-material-development/SKILL.md | 2 +- resources/js/carousel.js | 102 ++++++++++++------ .../views/components/carousel-item.blade.php | 22 +++- resources/views/components/carousel.blade.php | 35 +++--- .../showcase/sections/carousel.blade.php | 4 +- tests/Feature/Components/CarouselTest.php | 18 +++- 6 files changed, 126 insertions(+), 57 deletions(-) diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md index b999744c..cd7656a8 100644 --- a/resources/boost/skills/livewire-material-development/SKILL.md +++ b/resources/boost/skills/livewire-material-development/SKILL.md @@ -499,7 +499,7 @@ An M3 bottom sheet, bound like ``: modal by default (scrim, inert page, ``` -A row of items that change size between M3's keylines as it scrolls (native scroll snap; items are masked, content keeps its size). ``: `layout` (`multi-browse` default, `hero`, `uncontained`, `full-screen`), `item-width` (px or any CSS length; the large size multi-browse aims for, the fixed size uncontained keeps, the cap for hero; 186 by default), `height` (205px), `padding` (px at the ends, **16** — M3's specs table; leading only for `uncontained`, none for `full-screen`), `centered` (hero), `label` (the region's name, "Carousel" by default), `controls` (previous/next buttons: default fine pointers only, `true` always, `false` never). ``: slot is an `` (fills and crops) or an element sized `size-full`; `label` overlays a line of text. A `region` of `slide` groups named "n of m", each item a tab stop and the row itself not one, as M3 asks; from a focused item the arrow keys move one item, Home/End go to the ends and Space/Enter opens one that is not fully in view. Works after a Livewire morph, in RTL and under reduced motion. Give items a `wire:key` in a loop. +A row of items that change size between M3's keylines as it scrolls (native scroll snap; items are masked, content keeps its size). ``: `layout` (`multi-browse` default, `hero`, `uncontained`, `full-screen` — one edge-to-edge item at a time scrolled **vertically**, which M3 gives to compact and medium windows in portrait only, and never to landscape), `item-width` (px or any CSS length; the large size multi-browse aims for, the fixed size uncontained keeps, the cap for hero; 186 by default), `height` (205px), `padding` (px at the ends, **16** — M3's specs table; leading only for `uncontained`, none for `full-screen`), `centered` (hero), `label` (the region's name, "Carousel" by default), `controls` (previous/next buttons: default fine pointers only, `true` always, `false` never). ``: slot is an `` (fills and crops) or an element sized `size-full`; `label` overlays a line of text. A `region` of `slide` groups named "n of m", each item a tab stop and the row itself not one, as M3 asks; from a focused item the arrow keys move one item, Home/End go to the ends and Space/Enter opens one that is not fully in view. Works after a Livewire morph, in RTL and under reduced motion. Give items a `wire:key` in a loop. ### `` diff --git a/resources/js/carousel.js b/resources/js/carousel.js index dc7086b8..eb0eb46b 100644 --- a/resources/js/carousel.js +++ b/resources/js/carousel.js @@ -40,8 +40,9 @@ * compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/carousel/Carousel.kt * (carouselItem, calculateMaxScrollOffset, CarouselDefaults) * - * The full-screen arrangement follows material-components-android's - * FullScreenCarouselStrategy (one large item the size of the container). + * The full-screen layout uses none of it: M3 gives it one edge-to-edge item at a time, scrolled + * vertically, so the browser's own scroll snap is the whole of it and this script only works out + * where each item comes to rest, for the buttons and the keys. * * Copyright 2023-2024 The Android Open Source Project * @@ -547,11 +548,6 @@ const heroKeylineList = (space, maxItemSize, itemSpacing, itemCount, isCentered) : leftAlignedKeylineList(space, itemSpacing, ANCHOR_SIZE, ANCHOR_SIZE, arrangement) } -const fullScreenKeylineList = (space, itemSpacing) => - space === 0 - ? EMPTY - : leftAlignedKeylineList(space, itemSpacing, ANCHOR_SIZE, ANCHOR_SIZE, { priority: 0, smallSize: 0, smallCount: 0, mediumSize: 0, mediumCount: 0, largeSize: space, largeCount: 1 }) - // Strategy.kt ------------------------------------------------------------------------------ const shiftedKeylineListForContentPadding = (from, space, itemSpacing, contentPadding, pivot, pivotIndex) => { @@ -806,6 +802,7 @@ document.addEventListener('alpine:init', () => { snaps: [], maxScroll: 0, rtl: false, + vertical: false, frame: null, target: null, targetAt: 0, @@ -861,14 +858,10 @@ document.addEventListener('alpine:init', () => { refresh() { const root = this.$root const scroller = this.$refs.scroller - const space = scroller.clientWidth - const itemSpacing = parseFloat(getComputedStyle(scroller).columnGap) || 0 - const padding = Number(root.dataset.padding) || 0 - const paddingEnd = Number(root.dataset.paddingEnd) || 0 - const probe = this.$refs.probe - const preferred = probe ? probe.getBoundingClientRect().width : null + const style = getComputedStyle(scroller) - state.rtl = getComputedStyle(scroller).direction === 'rtl' + state.rtl = style.direction === 'rtl' + state.vertical = root.dataset.materialCarousel === 'full-screen' state.items = [...scroller.children] .filter((element) => element.matches(ITEM)) .map((element) => ({ @@ -879,11 +872,33 @@ document.addEventListener('alpine:init', () => { written: '', })) + // M3's full-screen layout is one edge-to-edge item at a time, scrolled + // vertically: no keylines, no mask, no end padding — the browser's scroll snap + // does the whole of it, and this only works out where each item comes to rest. + if (state.vertical) { + const space = scroller.clientHeight + const spacing = parseFloat(style.rowGap) || 0 + + state.strategy = null + state.maxScroll = Math.max(0, (space + spacing) * state.items.length - spacing - space) + state.snaps = state.items.map((_, index) => clamp(index * (space + spacing), 0, state.maxScroll)) + + this.render() + + return + } + + const space = scroller.clientWidth + const itemSpacing = parseFloat(style.columnGap) || 0 + const padding = Number(root.dataset.padding) || 0 + const paddingEnd = Number(root.dataset.paddingEnd) || 0 + const probe = this.$refs.probe + const preferred = probe ? probe.getBoundingClientRect().width : null + const count = state.items.length const keylines = { hero: () => heroKeylineList(space, preferred, itemSpacing, count, root.dataset.centered !== undefined), uncontained: () => uncontainedKeylineList(space, preferred ?? 0, itemSpacing), - 'full-screen': () => fullScreenKeylineList(space, itemSpacing), }[root.dataset.materialCarousel] ?? (() => multiBrowseKeylineList(space, preferred ?? 0, itemSpacing, count)) const strategy = count === 0 ? createStrategy(EMPTY, space, itemSpacing, 0, 0) : createStrategy(keylines(), space, itemSpacing, padding, paddingEnd) @@ -942,10 +957,10 @@ document.addEventListener('alpine:init', () => { state.target = null - const left = state.snaps[target] + const offset = state.snaps[target] - if (left !== undefined && Math.abs(this.scrollOffset() - left) > 1) { - this.$refs.scroller.scrollTo({ left: state.rtl ? -left : left, behavior: 'instant' }) + if (offset !== undefined && Math.abs(this.scrollOffset() - offset) > 1) { + this.scrollTo(offset, 'instant') } }, SETTLE_MS) }, @@ -955,6 +970,14 @@ document.addEventListener('alpine:init', () => { cancelAnimationFrame(state.frame) state.frame = null + // Nothing is masked in the vertical full-screen layout; only the buttons change. + if (state.vertical) { + this.buttons() + state.mutations?.takeRecords() + + return + } + const strategy = state.strategy if (!strategy?.valid) { @@ -1003,6 +1026,15 @@ document.addEventListener('alpine:init', () => { item.surface.style.setProperty('--material-carousel-label', opacity.toFixed(3)) }) + this.buttons() + + state.mutations?.takeRecords() + }, + + /** A control that would scroll past an end is off. */ + buttons() { + const scroll = this.scrollOffset() + if (this.$refs.previous) { this.$refs.previous.disabled = scroll <= 1 } @@ -1010,13 +1042,21 @@ document.addEventListener('alpine:init', () => { if (this.$refs.next) { this.$refs.next.disabled = scroll >= state.maxScroll - 1 } - - state.mutations?.takeRecords() }, - /** The scroll offset from the start edge, positive in both directions. */ + /** The scroll offset from the start edge, positive in every direction. */ scrollOffset() { - return clamp(Math.abs(this.$refs.scroller.scrollLeft), 0, state.maxScroll) + const scroller = this.$refs.scroller + + return clamp(state.vertical ? scroller.scrollTop : Math.abs(scroller.scrollLeft), 0, state.maxScroll) + }, + + /** Scrolls to an offset on whichever axis this carousel runs along. */ + scrollTo(offset, behavior) { + this.$refs.scroller.scrollTo({ + ...(state.vertical ? { top: offset } : { left: state.rtl ? -offset : offset }), + behavior, + }) }, /** The item nearest the current scroll position. */ @@ -1052,19 +1092,14 @@ document.addEventListener('alpine:init', () => { }, scrollToItem(index) { - if (!state.strategy?.valid || state.snaps[index] === undefined) { + if (state.snaps[index] === undefined || (!state.vertical && !state.strategy?.valid)) { return } state.target = index state.targetAt = performance.now() - const left = state.snaps[index] - - this.$refs.scroller.scrollTo({ - left: state.rtl ? -left : left, - behavior: state.reducedMotion.matches ? 'instant' : 'smooth', - }) + this.scrollTo(state.snaps[index], state.reducedMotion.matches ? 'instant' : 'smooth') }, /** @@ -1093,8 +1128,8 @@ document.addEventListener('alpine:init', () => { return } - const forward = state.rtl ? 'ArrowLeft' : 'ArrowRight' - const backward = state.rtl ? 'ArrowRight' : 'ArrowLeft' + const forward = state.vertical ? 'ArrowDown' : state.rtl ? 'ArrowLeft' : 'ArrowRight' + const backward = state.vertical ? 'ArrowUp' : state.rtl ? 'ArrowRight' : 'ArrowLeft' const to = { [forward]: index + 1, @@ -1138,8 +1173,11 @@ document.addEventListener('alpine:init', () => { } }, + /** Whether item `index` is not fully in focus, so a press or focus should bring it there. */ isMasked(index) { - return parseFloat(state.items[index].surface.style.getPropertyValue('--material-carousel-inset')) > 0.5 + return state.vertical + ? Math.abs(state.snaps[index] - this.scrollOffset()) > 1 + : parseFloat(state.items[index].surface.style.getPropertyValue('--material-carousel-inset')) > 0.5 }, destroy() { diff --git a/resources/views/components/carousel-item.blade.php b/resources/views/components/carousel-item.blade.php index eefe0e0c..1dc80f68 100644 --- a/resources/views/components/carousel-item.blade.php +++ b/resources/views/components/carousel-item.blade.php @@ -19,15 +19,28 @@ the surface inside is clipped by `--material-carousel-inset` from both sides with M3's extra-large corner (28px, CarouselDefaults' item shape) and moved by `--material-carousel-shift`, both written by resources/js/carousel.js. Without script the - item shows unmasked, at its `item-width`. Only inside ``. --}} + item shows unmasked, at its `item-width`. In a `full-screen` carousel it is none of that: the + item fills the row, edge to edge, with no corner and no mask. Only inside ``. --}} @props([ 'label' => null, ]) +{{-- The layout of the `` around it: the full-screen one is a vertical row of + edge-to-edge items, which M3 gives no corner and no mask. --}} +@aware([ + 'layout' => 'multi-browse', +]) + +@php + $vertical = $layout === 'full-screen'; +@endphp +
class([ - 'focus-ring relative h-full w-(--material-carousel-slot) max-w-full shrink-0 snap-start snap-always rounded-corner-xl focus-visible:-outline-offset-3', + 'focus-ring relative h-full shrink-0 snap-start snap-always focus-visible:-outline-offset-3', + 'w-full' => $vertical, + 'w-(--material-carousel-slot) max-w-full rounded-corner-xl' => ! $vertical, ]) ->merge([ 'role' => 'group', @@ -38,7 +51,10 @@ ]) }}>
! $vertical, + ]) >
{{ $slot }} diff --git a/resources/views/components/carousel.blade.php b/resources/views/components/carousel.blade.php index 4a9c2463..bf180ed9 100644 --- a/resources/views/components/carousel.blade.php +++ b/resources/views/components/carousel.blade.php @@ -19,8 +19,13 @@ does. - `uncontained`: items keep `item-width`; the one cut off at the end narrows as it leaves — HorizontalUncontainedCarousel. No snapping, as Compose's uncontained fling. - - `full-screen`: one item the width of the carousel at a time - (FullScreenCarouselStrategy). + - `full-screen`: one edge-to-edge item at a time, scrolled **vertically** — M3: "this layout + works best with content that is taller than it is wide, and scrolls vertically. It only + works in portrait orientation in compact and medium breakpoints. Don't use this layout in + landscape orientation." Items have no corner and no mask, 16px apart, no end padding, and + the row is never wider than the 840px medium window it is meant for. `item-width` and + `padding` do not apply; `height` is the height of each item, so give it the room a + portrait image wants. `item-width` takes pixels or any CSS length. `height` is the items' height (205px, Compose's sample). `padding` is Compose's `contentPadding` in pixels: the first and last items rest that far in from the edges while items in between scroll to them. M3's specs table gives @@ -66,6 +71,7 @@ @php $layout = in_array($layout, ['multi-browse', 'hero', 'uncontained', 'full-screen'], true) ? $layout : 'multi-browse'; + $vertical = $layout === 'full-screen'; $controls = $controls === null ? null : filter_var($controls, FILTER_VALIDATE_BOOL); $label ??= __('Carousel'); $scrollerId = 'material-carousel-'.\Illuminate\Support\Str::lower(\Illuminate\Support\Str::random(10)); @@ -82,8 +88,9 @@ 'hero' => $cssLength($itemWidth), 'full-screen' => null, }; + // The full-screen item is `h-full w-full`: it takes the row, not a slot. $slotWidth = match (true) { - $layout === 'full-screen' => '100%', + $vertical => null, $preferredWidth === null => 'calc(100% - 64px)', default => $preferredWidth, }; @@ -106,8 +113,8 @@ // The specs table's leading and trailing padding: 16dp for multi-browse and hero, leading // only for uncontained, none for full-screen, which is edge to edge. $padding = max(0, (float) $padding); - $paddingStart = $layout === 'full-screen' ? 0.0 : $padding; - $paddingEnd = in_array($layout, ['uncontained', 'full-screen'], true) ? 0.0 : $padding; + $paddingStart = $vertical ? 0.0 : $padding; + $paddingEnd = $vertical || $layout === 'uncontained' ? 0.0 : $padding; $attributes = $attributes ->class('relative') @@ -118,7 +125,7 @@ 'data-padding-end' => (string) $paddingEnd, 'style' => implode('; ', array_filter([ $preferredWidth ? "--material-carousel-item-width: {$preferredWidth}" : null, - "--material-carousel-slot: {$slotWidth}", + $slotWidth ? "--material-carousel-slot: {$slotWidth}" : null, '--material-carousel-height: '.($cssLength($height) ?? '205px'), ])), ], fn ($value): bool => $value !== null)); @@ -137,11 +144,11 @@ aria-roledescription="{{ __('carousel') }}" aria-label="{{ $label }}" @class([ - 'flex gap-2 overflow-x-auto overflow-y-hidden overscroll-x-contain', + 'flex', '[scrollbar-width:none] [&::-webkit-scrollbar]:hidden', - 'h-(--material-carousel-height)' => $layout === 'full-screen', - 'h-[calc(var(--material-carousel-height)+1rem)] py-2' => $layout !== 'full-screen', - 'snap-x snap-mandatory' => $layout !== 'uncontained', + 'mx-auto h-(--material-carousel-height) max-w-210 snap-y snap-mandatory flex-col gap-4 overflow-x-hidden overflow-y-auto overscroll-y-contain' => $vertical, + 'h-[calc(var(--material-carousel-height)+1rem)] gap-2 overflow-x-auto overflow-y-hidden overscroll-x-contain py-2' => ! $vertical, + 'snap-x snap-mandatory' => ! $vertical && $layout !== 'uncontained', ]) > {!! $slides !!} @@ -154,22 +161,22 @@ 'flex' => $controls === true, ])>
@endif diff --git a/resources/views/showcase/sections/carousel.blade.php b/resources/views/showcase/sections/carousel.blade.php index bd87e761..11312911 100644 --- a/resources/views/showcase/sections/carousel.blade.php +++ b/resources/views/showcase/sections/carousel.blade.php @@ -55,8 +55,8 @@ @endforeach BLADE, - 'Full-screen' => <<<'BLADE' - + 'Full-screen: one item at a time, scrolled down' => <<<'BLADE' + @foreach ([ ['Morning', 'very-sunny', 'bg-linear-to-br from-primary-container to-tertiary-container text-on-primary-container'], ['Noon', 'clam-shell', 'bg-linear-to-br from-secondary-container to-primary-container text-on-secondary-container'], diff --git a/tests/Feature/Components/CarouselTest.php b/tests/Feature/Components/CarouselTest.php index 8fba442f..b66d932a 100644 --- a/tests/Feature/Components/CarouselTest.php +++ b/tests/Feature/Components/CarouselTest.php @@ -60,7 +60,7 @@ it('browses many by default: 186px items that snap one at a time, 205px high', f ->toContain('x-ref="probe"') ->toContain('data-padding="16"') ->toContain('data-padding-end="16"') - ->toContain('h-[calc(var(--material-carousel-height)+1rem)] py-2') + ->toContain('h-[calc(var(--material-carousel-height)+1rem)] gap-2 overflow-x-auto overflow-y-hidden overscroll-x-contain py-2') ->toContain('snap-x snap-mandatory') ->toContain('snap-start snap-always') ->toContain('rounded-corner-xl') @@ -95,15 +95,23 @@ it('lays out a hero that fills the width unless capped, centred on request', fun ->not->toContain('data-centered'); }); -it('leaves an uncontained carousel unsnapped, and a full-screen one a page wide', function () { +it('leaves an uncontained carousel unsnapped, and scrolls a full-screen one down the page', function () { expect((string) $this->blade('A')) ->toContain('data-material-carousel="uncontained"') ->toContain('--material-carousel-item-width: 180px') ->not->toContain('snap-mandatory') - ->and((string) $this->blade('A')) + ->and((string) $this->blade('A')) ->toContain('data-material-carousel="full-screen"') - ->toContain('--material-carousel-slot: 100%') - ->toContain('snap-mandatory') + // M3: one edge-to-edge item at a time, scrolled vertically, 16px apart, no end padding, + // no corner, no mask, and never wider than the medium window it is meant for. + ->toContain('mx-auto h-(--material-carousel-height) max-w-210 snap-y snap-mandatory flex-col gap-4 overflow-x-hidden overflow-y-auto overscroll-y-contain') + ->toContain('data-padding="0" data-padding-end="0"') + ->toContain('aria-label="Previous"') + ->not->toContain('--material-carousel-slot') + ->not->toContain('snap-x') + ->not->toContain('rounded-corner-xl') + ->not->toContain('clip-path') + ->not->toContain('rtl:-scale-x-100') ->not->toContain('x-ref="probe"') ->not->toContain('data-centered') ->and((string) $this->blade('A'))