Cluster menu items by a gap, as Expressive does

Plan step 22, actions.md § Missing (Grouped menu layout by gap): M3
Expressive's "Grouped" layout separates clusters with a gap rather than a
divider, and `<x-menu-group>` only had the labelled form.

`<x-menu-group gap>` holds its items in a box 2px apart
(SegmentedMenuTokens.SegmentedGap) whose ends round like a list's, and
stands 8px off its neighbours — the same 8px the separator keeps around
its line. `label` is now optional, so a cluster can be a gap alone. The
header says when to reach for which: the divider first, and always in a
menu long enough to scroll, where M3 says gaps are unsupported.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9

resources/boost/skills/livewire-material-development/SKILL.md

@@ -274,6 +274,8 @@ M3's plain tooltip, standalone around any trigger: `<x-tooltip text="Copy link"
 
 The item says so with `aria-haspopup="menu"`, `aria-expanded` and a chevron; Right, Enter or Space open it on its first item, Left or Escape close it and come back, and on a fine pointer resting on the item opens it. Choosing anything inside closes the whole menu. Arrows stay inside the list they are in. M3 calls submenus a large-screen pattern — on a phone give the menu `sheet-at-compact`, or keep the list flat.
 
+Clusters: `<x-menu-separator />` draws M3's line, `<x-menu-group gap>` M3 Expressive's grouped layout — no line, the cluster set 8px off its neighbours with its items 2px apart and its ends rounded. Reach for the divider first (M3: "on web, use dividers to separate items", and it is the only one a scrolling menu may use); reach for the gap for one or two clusters in a menu short enough not to scroll, and never vary the gap. `<x-menu-group>` takes `label` (optional) and `gap`; a labelled group without `gap` is the plain heading it always was.
+
 ### `<x-button-group>`
 
 A row of `<x-button>`s: `<x-button-group label="View" size="md">…</x-button-group>`. `connected` sets them 2px apart with small inner corners (a selected toggle rounds fully). Pass the `size` of the buttons inside.

resources/views/components/menu-group.blade.php

@@ -1,9 +1,48 @@
-{{-- A labelled group of items in an `<x-menu>`: "Sort by", "Share with". --}}
+{{-- A group of items in an `<x-menu>`, labelled ("Sort by", "Share with"), set apart by a gap, or
+     both.
 
-@props(['label'])
+     M3 Expressive gives a menu two ways to break its items into clusters, and they are not
+     interchangeable:
 
-<div role="group" aria-label="{{ $label }}" {{ $attributes->class('py-1 first:pt-0 last:pb-0') }}>
-    <div aria-hidden="true" class="px-4 pt-2 pb-1 type-label-lg text-on-surface-variant">{{ $label }}</div>
+       - `<x-menu-separator />`, a line. M3: "dividers are more subtle and are the right choice for
+         scrollable menus or text-field dropdowns", and "on web, use dividers to separate items".
+         The default answer, and the only one for a menu long enough to scroll.
+       - `<x-menu-group gap>`, the Expressive "Grouped" layout: no line, a gap. M3: "gaps are the
+         more expressive way to separate item clusters" — but "limit to one or two gaps per menu",
+         "don't vary gap size", and "never use gaps in a scrollable menu" (unsupported).
 
-    {{ $slot }}
+     A gapped cluster sets its items 2px apart (SegmentedMenuTokens.SegmentedGap = 2dp) and holds
+     them in a box of their own, so the two ends of the cluster round the way the ends of a whole
+     list round and each cluster reads as one block. Clusters stand 8px apart, the same 8px a
+     separator keeps above and below its line, so a menu is the same height whichever it uses.
+     SegmentedMenuTokens' own GroupShape is 8dp where the library's list ends are 12dp; the
+     library's shape wins, so a cluster's ends and a list's ends match. --}}
+
+@props([
+    'label' => null,
+    'gap' => false,
+])
+
+@php
+    $attributes = $attributes
+        ->class([
+            'py-1 first:pt-0 last:pb-0' => ! $gap,
+            'not-first:mt-2' => $gap,
+        ])
+        ->merge(array_filter([
+            'role' => 'group',
+            'aria-label' => $label,
+        ], fn ($value): bool => filled($value)));
+@endphp
+
+<div {{ $attributes }}>
+    @if (filled($label))
+        <div aria-hidden="true" class="px-4 pt-2 pb-1 type-label-lg text-on-surface-variant">{{ $label }}</div>
+    @endif
+
+    @if ($gap)
+        <div class="space-y-0.5">{{ $slot }}</div>
+    @else
+        {{ $slot }}
+    @endif
 </div>

resources/views/showcase/sections/menus.blade.php

@@ -60,6 +60,37 @@
                 <x-menu-item label="Delete" icon="delete" />
             </x-menu>
             BLADE,
+        'Clusters: a gap, or a divider' => <<<'BLADE'
+            <x-menu label="Grouped by a gap">
+                <x-slot:trigger>
+                    <x-button label="A gap" icon-right="arrow_drop_down" variant="outlined" />
+                </x-slot:trigger>
+
+                <x-menu-group gap>
+                    <x-menu-item label="Cut" icon="content_cut" shortcut="⌘X" />
+                    <x-menu-item label="Copy" icon="content_copy" shortcut="⌘C" />
+                    <x-menu-item label="Paste" icon="content_paste" shortcut="⌘V" />
+                </x-menu-group>
+
+                <x-menu-group label="Then" gap>
+                    <x-menu-item label="Rename" icon="edit" />
+                    <x-menu-item label="Delete" icon="delete" />
+                </x-menu-group>
+            </x-menu>
+
+            <x-menu label="Separated by a divider">
+                <x-slot:trigger>
+                    <x-button label="A divider" icon-right="arrow_drop_down" variant="outlined" />
+                </x-slot:trigger>
+
+                <x-menu-item label="Cut" icon="content_cut" shortcut="⌘X" />
+                <x-menu-item label="Copy" icon="content_copy" shortcut="⌘C" />
+                <x-menu-item label="Paste" icon="content_paste" shortcut="⌘V" />
+                <x-menu-separator />
+                <x-menu-item label="Rename" icon="edit" />
+                <x-menu-item label="Delete" icon="delete" />
+            </x-menu>
+            BLADE,
         'Icons in their own colour' => <<<'BLADE'
             <x-menu label="New plan">
                 <x-slot:trigger>

tests/Feature/Components/MenuTest.php

@@ -103,6 +103,25 @@ it('separates and labels groups', function () {
         ->assertSee('role="group" aria-label="Sort by"', false);
 });
 
+it('separates clusters by a gap instead of a divider when asked', function () {
+    $html = (string) $this->blade('<x-menu-group gap><x-menu-item label="Cut" /></x-menu-group>');
+
+    // M3 Expressive's grouped layout: 2px between the items of a cluster, 8px between clusters —
+    // the same 8px the divider keeps above and below its line.
+    expect($html)
+        ->toContain('role="group"')
+        ->toContain('not-first:mt-2')
+        ->toContain('space-y-0.5')
+        ->not->toContain('aria-label')
+        ->not->toContain('py-1 first:pt-0')
+        ->and((string) $this->blade('<x-menu-group label="Then" gap><x-menu-item label="Cut" /></x-menu-group>'))
+        ->toContain('aria-label="Then"')
+        ->toContain('space-y-0.5')
+        ->and((string) $this->blade('<x-menu-group label="Sort by"><x-menu-item label="Newest" /></x-menu-group>'))
+        ->toContain('py-1 first:pt-0 last:pb-0')
+        ->not->toContain('space-y-0.5');
+});
+
 it('adds icon-class to the leading icon, over its own colour but not over disabled', function () {
     $leading = fn (string $html): string => preg_match('/<svg[^>]*class="([^"]*)"/', $html, $icon) ? $icon[1] : '';