Head a group with M3's divider-with-subheader

Plan step 23, containment.md § Missing ("Divider: the divider-with-text /
subheader configuration"). `<x-divider text="…">` draws the label at the
start and the rule running on from it, with the divider specs table's
geometry: 4dp between the words and the rule, 8dp right margin, 8dp
bottom margin. The label is M3's subhead — title-small in
on-surface-variant, the only subhead type M3 publishes (the rich
tooltip's specs), since the divider page names none. The words stay text
naming the group; only the rule is the separator.

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

@@ -458,6 +458,8 @@ A list a person chooses from is `<x-list selectable>` (or `selection="single"` /
 
 `<x-divider />` — outline-variant line; `vertical`, `inset` (16px start), `middle`, `decorative` (hidden from assistive tech).
 
+`<x-divider text="Earlier this week" />` is M3's divider with a subheader, to head a group in a list or a menu: the label (title-small, on-surface-variant) at the start, the rule 4px after it and 8px short of the end, 8px under the row. The words stay text; only the rule is the separator (`decorative` hides just the rule). Horizontal only.
+
 ### `<x-collapse>`
 
 A disclosure on native `<details>`: `<x-collapse title="Advanced" icon="tune" open variant="filled">…</x-collapse>` (`variant` `plain` or `filled`; `heading` slot for rich titles). Keeps its state through a morph.

resources/views/components/divider.blade.php

@@ -2,23 +2,49 @@
 
      Horizontal by default; `vertical` stands it between items in a row (give the row a height).
      `inset` indents it from the start by 16px, as under a list's leading icon; `middle` from both
-     ends. It is `role="separator"`; with `decorative` it is hidden from assistive tech. --}}
+     ends. It is `role="separator"`; with `decorative` it is hidden from assistive tech.
+
+     `text` is the divider with a subheader, as M3 draws it to head a group in a list or a menu:
+     the label at the start and the rule running on from it. The divider specs table gives the
+     geometry — "space between divider & supporting text 4dp", "divider right margin 8dp",
+     "divider bottom margin 8dp" — so the rule starts 4px after the words, stops 8px short of the
+     end and leaves 8px under the row. The label is M3's subhead: title-small in
+     on-surface-variant, the type the rich tooltip's specs give a subhead, since the divider's own
+     page names none (docs/reference/m3/components-actions-communication-containment.md
+     § Divider → Specs, § Tooltips → Specs). The words stay readable text that names the group
+     after them; only the rule is the separator, and `decorative` hides the rule and leaves the
+     words. `text` is for a horizontal divider; a vertical one ignores it. --}}
 
 @props([
     'vertical' => false,
     'inset' => false,
     'middle' => false,
     'decorative' => false,
+    'text' => null,
 ])
 
-<div
+@if (filled($text) && ! $vertical)
-    @if ($decorative) aria-hidden="true" @else role="separator" aria-orientation="{{ $vertical ? 'vertical' : 'horizontal' }}" @endif
+    <div {{ $attributes->class([
-    {{ $attributes->class([
+        'flex shrink-0 items-center gap-1 pb-2',
-        'shrink-0 bg-outline-variant',
+        'ms-4' => $inset,
-        'h-px w-auto' => ! $vertical,
+        'mx-4' => $middle,
-        'w-px self-stretch' => $vertical,
+    ]) }}>
-        'ms-4' => $inset && ! $vertical,
+        <span class="shrink-0 type-title-sm text-on-surface-variant">{{ $text }}</span>
-        'mx-4' => $middle && ! $vertical,
+        <div
-        'my-2' => $middle && $vertical,
+            @if ($decorative) aria-hidden="true" @else role="separator" aria-orientation="horizontal" @endif
-    ]) }}
+            class="me-2 h-px min-w-0 flex-1 bg-outline-variant"
-></div>
+        ></div>
+    </div>
+@else
+    <div
+        @if ($decorative) aria-hidden="true" @else role="separator" aria-orientation="{{ $vertical ? 'vertical' : 'horizontal' }}" @endif
+        {{ $attributes->class([
+            'shrink-0 bg-outline-variant',
+            'h-px w-auto' => ! $vertical,
+            'w-px self-stretch' => $vertical,
+            'ms-4' => $inset && ! $vertical,
+            'mx-4' => $middle && ! $vertical,
+            'my-2' => $middle && $vertical,
+        ]) }}
+    ></div>
+@endif

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

@@ -98,6 +98,19 @@
                 <div class="flex h-10 items-center gap-4"><span>Left</span><x-divider vertical /><span>Right</span></div>
             </div>
             BLADE,
+        'A divider with a subheader' => <<<'BLADE'
+            <div class="w-full max-w-md">
+                <x-divider text="Today" />
+                <x-list label="Today">
+                    <x-list-item title="holiday-photos.zip" description="Shared with 3 people" icon="folder_zip" />
+                    <x-list-item title="contract.pdf" description="Downloaded twice" icon="picture_as_pdf" />
+                </x-list>
+                <x-divider text="Earlier this week" class="mt-2" />
+                <x-list label="Earlier this week">
+                    <x-list-item title="minutes.docx" description="Expired" icon="description" />
+                </x-list>
+            </div>
+            BLADE,
         'Collapse bound to a property' => <<<'BLADE'
             <div x-data="{ advanced: false }" class="w-full space-y-4">
                 <div class="flex flex-wrap items-center gap-4">

tests/Feature/Components/DividerTest.php

@@ -6,3 +6,21 @@ it('separates horizontally or vertically, inset on request', function () {
         ->and((string) $this->blade('<x-divider inset />'))->toContain('ms-4')
         ->and((string) $this->blade('<x-divider decorative />'))->toContain('aria-hidden="true"')->not->toContain('role="separator"');
 });
+
+it('heads a group with a subheader, the rule running on from the words', function () {
+    $html = (string) $this->blade('<x-divider text="Recent" />');
+
+    expect($html)
+        ->toContain('flex shrink-0 items-center gap-1 pb-2')
+        ->toContain('<span class="shrink-0 type-title-sm text-on-surface-variant">Recent</span>')
+        ->toMatch('/role="separator" aria-orientation="horizontal"\s+class="me-2 h-px min-w-0 flex-1 bg-outline-variant"/')
+        ->and(strpos($html, 'Recent'))->toBeLessThan(strpos($html, 'role="separator"'))
+        ->and((string) $this->blade('<x-divider text="Recent" inset />'))->toContain('flex shrink-0 items-center gap-1 pb-2 ms-4')
+        ->and((string) $this->blade('<x-divider text="Recent" decorative />'))
+        ->toContain('>Recent</span>')
+        ->toContain('aria-hidden="true"')
+        ->not->toContain('role="separator"')
+        ->and((string) $this->blade('<x-divider text="Recent" vertical />'))
+        ->not->toContain('Recent')
+        ->toContain('aria-orientation="vertical"');
+});