From acd6ba21ae5a79253ad85bef5ec634c5c505e4d0 Mon Sep 17 00:00:00 2001
From: Andreas Reinhold / reini <reini@kadenpartner.ch>
Date: Mon, 14 Sep 2026 14:51:30 +0200
Subject: [PATCH] Add the feed canonical layout

Plan step 35: <x-feed min-item gap>, following the reference's feed rules
- one column below medium, then as many equal columns of at least the
minimum item width as the feed has room for, 24px apart from medium,
items in their source order.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9
---
 .../livewire-material-development/SKILL.md    | 16 ++++++
 resources/css/layout.css                      |  1 +
 resources/css/layout/feed.css                 | 49 +++++++++++++++++++
 resources/views/components/feed.blade.php     | 49 +++++++++++++++++++
 .../views/showcase/sections/layout.blade.php  |  1 +
 tests/Browser/LayoutTest.php                  | 21 ++++++++
 tests/Feature/Components/FeedTest.php         | 42 ++++++++++++++++
 7 files changed, 179 insertions(+)
 create mode 100644 resources/css/layout/feed.css
 create mode 100644 resources/views/components/feed.blade.php
 create mode 100644 tests/Feature/Components/FeedTest.php

diff --git a/resources/boost/skills/livewire-material-development/SKILL.md b/resources/boost/skills/livewire-material-development/SKILL.md
index fbee6172..f96a3cea 100644
--- a/resources/boost/skills/livewire-material-development/SKILL.md
+++ b/resources/boost/skills/livewire-material-development/SKILL.md
@@ -850,6 +850,22 @@ M3's supporting-pane canonical layout, for content that only means something bes
 - Below `expanded`: `compact="below"` (default) stacks it under the focus pane; `compact="sheet"` docks it to the bottom of the window as a bottom sheet (surface-container-low, extra-large top corners), shown as its drag handle and `label` until the handle — a button with `aria-expanded` — opens it; open, it scrolls within half the window, and Escape inside it closes it and returns focus to the handle. It clears the navigation bar and the bottom safe area and never covers the end of the focus pane.
 - `label` names the supporting `<aside>` and the sheet's handle.
 
+#### `<x-feed>`
+
+M3's feed canonical layout: cards or items to browse, in columns that multiply as the room grows.
+
+```blade
+<x-feed min-item="280px">
+    @foreach ($posts as $post)
+        <x-card wire:key="post-{{ $post->id }}" :title="$post->title">…</x-card>
+    @endforeach
+</x-feed>
+```
+
+- One column below `medium` (M3: one card per row, full width). From `medium`, as many equal columns of at least `min-item` as fit (`240px` default; `280px`, `18rem`, `20ch`, or a number of px) — more on a wider window. It follows the feed's own width, so a feed in a narrow pane stays sensible.
+- The gap is M3's spacer, 16px below `medium` and 24px from it, unless `gap` names a spacing token.
+- Items keep their order, which M3 makes the reading order. A card that should span two columns says so in its own `style`.
+
 #### `<x-surface>`
 
 A tonal region: `<x-surface level="surface-container-low" padding="space300" corner="lg" outlined>…</x-surface>`.
diff --git a/resources/css/layout.css b/resources/css/layout.css
index 72c11346..bb6802f0 100644
--- a/resources/css/layout.css
+++ b/resources/css/layout.css
@@ -13,3 +13,4 @@
 @import './layout/pane.css';
 @import './layout/list-detail.css';
 @import './layout/supporting-pane.css';
+@import './layout/feed.css';
diff --git a/resources/css/layout/feed.css b/resources/css/layout/feed.css
new file mode 100644
index 00000000..500e4a27
--- /dev/null
+++ b/resources/css/layout/feed.css
@@ -0,0 +1,49 @@
+/*
+ * <x-feed>: M3's feed canonical layout — cards or items in a grid that adds columns as it widens.
+ *
+ * Its rules across breakpoints, row by row (docs/reference/m3/foundations-supplement.md § Canonical
+ * layouts → Feed):
+ *
+ *   Compact (below 600px)          "stack vertically, one card per row, full pane width"
+ *   Medium (600–839)               "multiple equal-width columns"
+ *   Expanded, large, extra-large   "more columns than medium", each usually wider as it grows
+ *
+ * So below 600px the feed is one column. From 600px it is equal columns of at least
+ * `--md-min-item` (written inline on every feed, 240px unless the caller says otherwise, so a feed
+ * never inherits another's): as many as fit in the room the feed has, which is more on a wider
+ * window, and each column widens until the next one fits. M3 gives no minimum width or column
+ * count for the web ("no explicit numeric column-count or gutter table", docs/reference/m3/
+ * foundations.md § Layout → Grids & spacing); the minimum is the package's, and a feed inside a
+ * narrow pane stays one column where a window-keyed count would crush it. The space between items
+ * is M3's spacer, 16px on a compact window and 24px from medium (§ Breakpoints), unless
+ * `data-md-gap` names a spacing token. Items keep their source order — M3: "item order is
+ * determined by position" — and no dense packing reorders them. Columns run in the inline
+ * direction, so a right-to-left document fills them from the right.
+ *
+ * In `material.layout`; `hide-below`/`hide-from` come from visibility.css.
+ */
+
+@layer material.reset, material.tokens, material.base, material.layout, material.components, material.text, material.visibility;
+
+@import './spacing.css';
+@import './visibility.css';
+
+@layer material.layout {
+    :where([data-md-feed]) {
+        --md-gap: var(--md-sys-measurement-space200);
+
+        @media (width >= 600px) {
+            --md-gap: var(--md-sys-measurement-space300);
+        }
+    }
+
+    [data-md-feed] {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr);
+        gap: var(--md-gap);
+
+        @media (width >= 600px) {
+            grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--md-min-item, 240px)), 1fr));
+        }
+    }
+}
diff --git a/resources/views/components/feed.blade.php b/resources/views/components/feed.blade.php
new file mode 100644
index 00000000..db76a710
--- /dev/null
+++ b/resources/views/components/feed.blade.php
@@ -0,0 +1,49 @@
+{{-- M3's feed canonical layout: cards or items to browse, in columns that multiply as the room
+     grows — news, photos, posts.
+
+         <x-feed min-item="280px">
+             @foreach ($posts as $post)
+                 <x-card wire:key="post-{{ $post->id }}" :title="$post->title">…</x-card>
+             @endforeach
+         </x-feed>
+
+     M3's feed rules, row by row (docs/reference/m3/foundations-supplement.md § Canonical layouts →
+     Feed): a compact window (below 600px) stacks one card per row at the full width of the pane;
+     medium (600–839) splits into equal-width columns; expanded, large and extra-large have more
+     columns than medium, each usually wider. So below 600px it is one column, and from 600px it
+     fits as many equal columns of at least `min-item` as the feed has room for — more on a wider
+     window, and wider until another fits. M3 publishes no minimum or count for the web, so
+     `min-item` (`240px` by default; `280px`, `18rem`, `20ch` or a number of px) is yours to set
+     by the content. It follows the feed's own width, so a feed inside a pane beside another
+     stays sensible.
+
+     The items keep their order, which M3 makes the reading order ("item order is determined by
+     position"). The space between them is M3's spacer, 16px on a compact window and 24px from
+     medium, unless `gap` names a spacing token (`space25` … `space900`; an unknown name is no
+     gap). A card that should span two columns can say so in its own `style`.
+
+     It takes `as` (`div` by default; `ul` for a list of items, with `li` children), `hide-below`
+     and `hide-from` like every layout component, and the caller's `class` and `style` land on it
+     untouched. Drawn by resources/css/layout/feed.css. --}}
+
+@props([
+    'as' => null,
+    'minItem' => null,
+    'gap' => null,
+    'hideBelow' => null,
+    'hideFrom' => null,
+])
+
+@php
+    $layout = \NoNameWeb\LivewireMaterial\Support\Layout::class;
+    $element = $layout::element($as);
+    $minItem = $layout::length($minItem) ?? '240px';
+
+    $attributes = $attributes->merge(array_filter([
+        'data-md-feed' => true,
+        'data-md-gap' => $layout::spacing($gap),
+        'style' => "--md-min-item: {$minItem};",
+    ] + $layout::visibility($hideBelow, $hideFrom), fn ($value): bool => $value !== null));
+@endphp
+
+<{{ $element }} {{ $attributes }}>{{ $slot }}</{{ $element }}>
diff --git a/resources/views/showcase/sections/layout.blade.php b/resources/views/showcase/sections/layout.blade.php
index bf1d032d..9eda5824 100644
--- a/resources/views/showcase/sections/layout.blade.php
+++ b/resources/views/showcase/sections/layout.blade.php
@@ -116,6 +116,7 @@
             <li><code>&lt;x-pane&gt;</code> — a content region with M3's margins and its own app bar.</li>
             <li><code>&lt;x-list-detail&gt;</code> — a list and the detail of its selection: one pane below 840px, two from it.</li>
             <li><code>&lt;x-supporting-pane&gt;</code> — a focus pane and a pane beside it from 840px, below it or a bottom sheet before.</li>
+            <li><code>&lt;x-feed&gt;</code> — cards in columns that multiply as the room grows, one column below 600px.</li>
             <li><code>&lt;x-surface&gt;</code> — a tonal region: a surface role, padding, a corner and an outline.</li>
             <li><code>&lt;x-stack&gt;</code>, <code>&lt;x-row&gt;</code> and <code>&lt;x-grid&gt;</code> — arrangement inside a pane.</li>
         </x-livewire-material::stack>
diff --git a/tests/Browser/LayoutTest.php b/tests/Browser/LayoutTest.php
index 075793ff..43d51e2c 100644
--- a/tests/Browser/LayoutTest.php
+++ b/tests/Browser/LayoutTest.php
@@ -386,3 +386,24 @@ it('docks the supporting pane as a bottom sheet below expanded, opened and close
         ->assertScript(layoutRect(SUPPORTING_SIDE, 'width').' === 360')
         ->assertNoJavaScriptErrors();
 });
+
+it('lays a feed out in one column below medium and in columns of its minimum width from it, in order', function () {
+    $body = '<x-feed id="feed" min-item="240px">'
+        .collect(range(1, 6))->map(fn (int $item): string => "<article id=\"item-{$item}\">Item {$item}</article>")->implode('')
+        .'</x-feed>';
+
+    layoutPage($body, 599)
+        ->assertScript(layoutColumns('#feed').' === 1')
+        ->assertScript(layoutStyle('#feed', 'rowGap')." === '16px'");
+
+    // 600px, less no margins, fits two 240px columns with M3's 24px spacer between them.
+    layoutPage($body, 600)
+        ->assertScript(layoutColumns('#feed').' === 2')
+        ->assertScript(layoutStyle('#feed', 'columnGap')." === '24px'")
+        ->assertScript(layoutRect('#item-2', 'left').' > '.layoutRect('#item-1', 'left'))
+        ->assertScript(layoutRect('#item-3', 'top').' > '.layoutRect('#item-1', 'top'));
+
+    layoutPage($body, 1200)
+        ->assertScript(layoutColumns('#feed').' === 4')
+        ->assertScript(layoutRect('#item-5', 'left').' === '.layoutRect('#item-1', 'left'));
+});
diff --git a/tests/Feature/Components/FeedTest.php b/tests/Feature/Components/FeedTest.php
new file mode 100644
index 00000000..ca46019a
--- /dev/null
+++ b/tests/Feature/Components/FeedTest.php
@@ -0,0 +1,42 @@
+<?php
+
+it('lays out a feed with a 240px minimum item and M3\'s spacer', function () {
+    $html = (string) $this->blade('<x-feed><article>One</article><article>Two</article></x-feed>');
+
+    expect(layoutRoot($html))->toMatchArray(['<' => 'div', 'data-md-feed' => 'data-md-feed', 'style' => '--md-min-item: 240px;'])
+        ->not->toHaveKey('data-md-gap')
+        ->and($html)->toContain('<article>One</article><article>Two</article>');
+});
+
+it('takes a minimum item width as a length or a number of px', function () {
+    foreach (['280px' => '280px', '18rem' => '18rem', '320' => '320px'] as $given => $length) {
+        expect(layoutRoot((string) $this->blade('<x-feed :min-item="$m" />', ['m' => $given]))['style'])->toBe("--md-min-item: {$length};");
+    }
+
+    expect(layoutRoot((string) $this->blade('<x-feed min-item="a third" />'))['style'])->toBe('--md-min-item: 240px;');
+});
+
+it('replaces the spacer with a spacing token, and with no gap for an unknown one', function () {
+    expect(layoutRoot((string) $this->blade('<x-feed gap="space400" />'))['data-md-gap'])->toBe('space400')
+        ->and(layoutRoot((string) $this->blade('<x-feed gap="wide" />'))['data-md-gap'])->toBe('none');
+});
+
+it('takes the element, the visibility props, and the caller\'s class and style after its own', function () {
+    expect(layoutRoot((string) $this->blade('<x-feed as="ul" hide-below="medium" class="photos" style="padding-block: 1rem" />')))
+        ->toMatchArray([
+            '<' => 'ul',
+            'data-md-hide-below' => 'medium',
+            'class' => 'photos',
+            'style' => '--md-min-item: 240px; padding-block: 1rem;',
+        ]);
+});
+
+it('keeps one column on a compact window and fills columns from medium, in the layout layer', function () {
+    $css = (string) file_get_contents(__DIR__.'/../../../resources/css/layout/feed.css');
+
+    expect($css)->toContain('@layer material.layout')
+        ->toContain("[data-md-feed] {\n        display: grid;\n        grid-template-columns: minmax(0, 1fr);")
+        ->toContain("@media (width >= 600px) {\n            grid-template-columns: repeat(auto-fill, minmax(min(100%, var(--md-min-item, 240px)), 1fr));")
+        ->not->toContain('grid-auto-flow')
+        ->and((string) file_get_contents(__DIR__.'/../../../resources/css/layout.css'))->toContain("@import './layout/feed.css';");
+});