Add the pane layout component

Plan step 35: <x-pane>, a content region with M3's margins (16px below
medium, 24px from it) drawn once however panes and layouts nest, a width
cap, and an optional pane app bar - <x-app-bar> as a direct child of the
pane with title, subtitle, actions, a back link or action, a leading
slot, and the section navigation under it.

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

@@ -783,6 +783,25 @@ Breakpoints are M3's five, in px: compact below 600, `medium` 600, `expanded` 84
 
 M3's margin — 16px on a compact window, 24px from `medium` — is drawn once: by the scaffold's content region, or by the outermost pane or canonical layout when there is no scaffold. A pane inside one of those draws none, and one on an `<x-surface>`, a new edge, draws it again.
 
+#### `<x-pane>`
+
+A content region: M3 puts all content in panes, and each may carry its own top app bar.
+
+```blade
+<x-pane title="Settings" subtitle="Your account" width="narrow">
+    <x-slot:actions><x-button icon="help" tooltip="Help" /></x-slot:actions>
+    <x-slot:navigation><x-section-nav :items="$sections" /></x-slot:navigation>
+
+    …
+</x-pane>
+```
+
+- The body keeps M3's margin (16px below `medium`, 24px from it) unless something around it already does — the scaffold's content region, a canonical layout, another pane's body; on an `<x-surface>` it keeps it again.
+- `width`: `full` (default, the room it has), `narrow` (40rem, M3's 40–60 characters a line), `medium` (60rem), `wide` (80rem); capped widths are centred.
+- The app bar is an `<x-app-bar>`, a direct child of the pane so it spans the pane and stays sticky for its height; it is drawn when there is a `title`, `actions`, a `leading` slot or `back`. `title`, `subtitle`, `heading` (`h1` default — the second pane of a canonical layout passes `h2`), `sticky` (default true), the `actions` slot.
+- The bar's leading button: the `leading` slot, or `back` — a URL makes it a link, `true` calls `back()` from `<x-list-detail>` around it (hidden there where both panes show). The arrow mirrors in a right-to-left document.
+- `navigation` is the pane's section navigation (`<x-section-nav>`, `<x-tabs>`), under the bar and above the body with the body's margins — not the bar's leading button.
+
 #### `<x-surface>`
 
 A tonal region: `<x-surface level="surface-container-low" padding="space300" corner="lg" outlined>…</x-surface>`.

resources/css/layout.css

@@ -10,3 +10,4 @@
 @import './layout/row.css';
 @import './layout/grid.css';
 @import './layout/surface.css';
+@import './layout/pane.css';

resources/css/layout/pane.css

@@ -0,0 +1,72 @@
+/*
+ * <x-pane>: a content region, with M3's margins and, optionally, a top app bar of its own.
+ *
+ * M3 puts all content in panes (docs/reference/m3/foundations.md § Layout → Scaffold, "all content
+ * must live in a pane") and lets each carry its own app bar. The margin is the space between the
+ * window's edge and what is inside: 16px below medium and 24px from it (600px), from the
+ * per-breakpoint table in docs/reference/m3/foundations-supplement.md § Breakpoints, as
+ * `--md-sys-measurement-space200` and `space300`.
+ *
+ * The margin sits on the pane's body and its section navigation, not on the pane: the app bar is a
+ * direct child of the pane, so it spans the pane from edge to edge and its `position: sticky` holds
+ * for the pane's whole height (a sticky element never leaves its parent). A margin is drawn once:
+ * a region that already keeps its content off the window's edge — a pane's body, the canonical
+ * layouts, the scaffold's content region — sets `--md-layout-margin` to 0px for what is inside it,
+ * and a pane there draws none of its own, until an <x-surface> gives it a new edge to keep off.
+ *
+ * `data-md-width` caps the pane and centres it: `narrow` 40rem, M3's 40–60 characters a line
+ * (§ Layout → Breakpoints, "keep text to 40–60 characters per line"), in rem because it is a measure
+ * of text; `medium` 60rem and `wide` 80rem are the package's steps above it; `full` (the default)
+ * fills the room it has, M3's flexible pane. The back button of `data-md-pane-back` points the
+ * way it goes, so it mirrors in a right-to-left document (§ Layout → Bidirectionality / RTL).
+ *
+ * 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 './visibility.css';
+
+@layer material.layout {
+    [data-md-pane] {
+        display: flex;
+        flex-direction: column;
+        inline-size: 100%;
+        min-inline-size: 0;
+        margin-inline: auto;
+    }
+
+    [data-md-pane][data-md-width='narrow'] {
+        max-inline-size: 40rem;
+    }
+
+    [data-md-pane][data-md-width='medium'] {
+        max-inline-size: 60rem;
+    }
+
+    [data-md-pane][data-md-width='wide'] {
+        max-inline-size: 80rem;
+    }
+
+    [data-md-pane-navigation],
+    [data-md-pane-body] {
+        padding-inline: var(--md-layout-margin, var(--md-sys-measurement-space200));
+
+        @media (width >= 600px) {
+            padding-inline: var(--md-layout-margin, var(--md-sys-measurement-space300));
+        }
+    }
+
+    [data-md-pane-body] {
+        flex: 1 1 auto;
+        min-inline-size: 0;
+    }
+
+    [data-md-pane-body] > * {
+        --md-layout-margin: 0px;
+    }
+
+    [data-md-pane-back] [data-md-icon]:dir(rtl) {
+        transform: scaleX(-1);
+    }
+}

resources/views/components/pane.blade.php

@@ -0,0 +1,88 @@
+{{-- A pane: a content region with M3's margins, and its own top app bar if it has a title.
+
+         <x-pane title="Settings" subtitle="Your account" width="narrow">
+             <x-slot:actions><x-button icon="help" tooltip="Help" /></x-slot:actions>
+             <x-slot:navigation><x-section-nav :items="$sections" /></x-slot:navigation>
+             …
+         </x-pane>
+
+     M3 puts every piece of content in a pane and lets each carry its own top app bar
+     (docs/reference/m3/foundations.md § Layout → Scaffold). The body is kept off the window's edge
+     by M3's margin, 16px below medium (600px) and 24px from it
+     (docs/reference/m3/foundations-supplement.md § Breakpoints); a pane inside something that
+     already keeps that margin — the scaffold's content region, a canonical layout, another pane's
+     body — draws none, so the margin is never doubled; on an `<x-surface>` it draws it again.
+
+     `width` caps the pane and centres it: `narrow` (40rem, M3's 40–60 characters a line),
+     `medium` (60rem), `wide` (80rem) or `full` (the default, all the room it has).
+
+     The app bar is `<x-app-bar>`, drawn when there is a `title`, `actions`, a `leading` slot or
+     `back`: `title` and `subtitle`, `heading` (`h1` by default; the second pane of a canonical
+     layout passes `h2`), `sticky` (true: it holds to the top of the window for as long as the pane
+     is on screen), the `actions` slot at its end. Its leading icon button is the `leading` slot,
+     or `back`: a URL makes it a link back there, and `true` calls `back()` in the Alpine scope
+     around it, which `<x-list-detail>` provides — and which it hides where both panes show, as M3
+     shows a back button only in a single-pane list-detail. The back arrow mirrors in a
+     right-to-left document.
+
+     `navigation` is the pane's section navigation (`<x-section-nav>`, `<x-tabs>`), under the bar
+     and above the body, with the body's margins; it is not the bar's leading button.
+
+     It takes `as` (`div` by default: `section`, `article`, `main` …), `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/pane.css. --}}
+
+@props([
+    'as' => null,
+    'title' => null,
+    'subtitle' => null,
+    'heading' => 'h1',
+    'sticky' => true,
+    'back' => null,
+    'width' => null,
+    'hideBelow' => null,
+    'hideFrom' => null,
+])
+
+@php
+    $layout = \NoNameWeb\LivewireMaterial\Support\Layout::class;
+    $element = $layout::element($as);
+    $backLink = is_string($back) && $back !== '' ? $back : null;
+    $backAction = $back === true;
+    $bar = filled($title) || isset($actions) || isset($leading) || $backLink !== null || $backAction;
+
+    $attributes = $attributes->merge(array_filter([
+        'data-md-pane' => true,
+        'data-md-width' => $layout::choice($width, ['full', 'narrow', 'medium', 'wide']),
+    ] + $layout::visibility($hideBelow, $hideFrom), fn ($value): bool => $value !== null));
+@endphp
+
+<{{ $element }} {{ $attributes }}>
+    @if ($bar)
+        <x-livewire-material::app-bar :title="$title" :subtitle="$subtitle" :heading="$heading" :sticky="$sticky" data-md-pane-bar>
+            @if (isset($leading))
+                <x-slot:navigation>{{ $leading }}</x-slot:navigation>
+            @elseif ($backLink !== null || $backAction)
+                <x-slot:navigation>
+                    <span data-md-pane-back @if ($backAction) data-md-list-detail-back @endif>
+                        @if ($backLink !== null)
+                            <x-livewire-material::button icon="arrow_back" :tooltip="__('Back')" :link="$backLink" />
+                        @else
+                            <x-livewire-material::button icon="arrow_back" :tooltip="__('Back')" x-on:click="back()" />
+                        @endif
+                    </span>
+                </x-slot:navigation>
+            @endif
+
+            @isset($actions)
+                <x-slot:actions>{{ $actions }}</x-slot:actions>
+            @endisset
+        </x-livewire-material::app-bar>
+    @endif
+
+    @isset($navigation)
+        <div data-md-pane-navigation>{{ $navigation }}</div>
+    @endisset
+
+    <div data-md-pane-body>{{ $slot }}</div>
+</{{ $element }}>

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

@@ -113,6 +113,7 @@
         </p>
 
         <x-livewire-material::stack as="ul" gap="space100" class="md-type-body-md">
+            <li><code>&lt;x-pane&gt;</code> — a content region with M3's margins and its own app bar.</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>