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'))