Add the surface layout component

Plan step 35: <x-surface level padding corner outlined>, a tonal region in surface or a surface-container step, padded with a spacing token, rounded with a corner token and optionally edged in outline-variant. A pane on a surface keeps its margin again, since the surface is a new edge. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Qwx5USif3wFFmxtHg5U1g9
2026-09-14 14:50:55 +02:00
parent da7a05a619
commit e99c5993d8
7 changed files with 253 additions and 0 deletions
@@ -783,6 +783,13 @@ 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-surface>`
+
+A tonal region: `<x-surface level="surface-container-low" padding="space300" corner="lg" outlined>…</x-surface>`.
+
+- `level`: `surface`, `surface-dim`, `surface-bright`, `surface-container-lowest`, `surface-container-low`, `surface-container` (default), `surface-container-high`, `surface-container-highest`; the text on it is `on-surface`. A higher container step reads as nearer — how M3 separates regions without a shadow.
+- `padding`: a spacing token. `corner`: `none`, `xs`, `sm`, `md`, `lg`, `lg-increased`, `xl`, `xl-increased`, `xxl`, `full`. `outlined`: M3's 1dp outline-variant edge.
+
 #### `<x-stack>`

 Children one under another inside a pane: `<x-stack gap="space200">…</x-stack>`. `align` across it: `stretch` (default), `start`, `center`, `end`.
@@ -9,3 +9,4 @@
@import './layout/stack.css';
@import './layout/row.css';
@import './layout/grid.css';
+@import './layout/surface.css';
@@ -0,0 +1,107 @@
+/*
+ * <x-surface>: a tonal region, M3's surface or one of its container steps.
+ *
+ * `data-md-level` names the colour role the region is filled with — `surface`, `surface-dim`,
+ * `surface-bright`, or `surface-container-lowest` … `surface-container-highest` — and its text is
+ * `on-surface`, the role M3 pairs with every one of them (docs/reference/m3/styles.md § Color →
+ * surface roles). The container steps are how M3 separates regions without a shadow: a higher step
+ * reads as nearer. `data-md-corner` rounds it with a corner token (`xs` … `full`,
+ * resources/css/tokens/shape.css), `data-md-padding` pads it with a spacing token (spacing.css),
+ * and `data-md-outlined` draws the 1dp outline-variant edge M3 gives an outlined container, for a
+ * boundary where the tones alone would be too close.
+ *
+ * A surface is an edge of its own: a pane or a canonical layout on it keeps its content off the
+ * surface's edge by M3's margin again, even inside a region that already drew one (pane.css,
+ * `--md-layout-margin`), which `initial` puts back to "not drawn yet".
+ *
+ * In `material.layout`, under every component, so a component drawn on a surface keeps its own
+ * container; `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 {
+    [data-md-surface] {
+        background-color: var(--md-sys-color-surface-container);
+        color: var(--md-sys-color-on-surface);
+    }
+
+    [data-md-surface][data-md-level='surface'] {
+        background-color: var(--md-sys-color-surface);
+    }
+
+    [data-md-surface][data-md-level='surface-dim'] {
+        background-color: var(--md-sys-color-surface-dim);
+    }
+
+    [data-md-surface][data-md-level='surface-bright'] {
+        background-color: var(--md-sys-color-surface-bright);
+    }
+
+    [data-md-surface][data-md-level='surface-container-lowest'] {
+        background-color: var(--md-sys-color-surface-container-lowest);
+    }
+
+    [data-md-surface][data-md-level='surface-container-low'] {
+        background-color: var(--md-sys-color-surface-container-low);
+    }
+
+    [data-md-surface][data-md-level='surface-container-high'] {
+        background-color: var(--md-sys-color-surface-container-high);
+    }
+
+    [data-md-surface][data-md-level='surface-container-highest'] {
+        background-color: var(--md-sys-color-surface-container-highest);
+    }
+
+    [data-md-surface][data-md-corner='none'] {
+        border-radius: var(--md-sys-shape-corner-none);
+    }
+
+    [data-md-surface][data-md-corner='xs'] {
+        border-radius: var(--md-sys-shape-corner-xs);
+    }
+
+    [data-md-surface][data-md-corner='sm'] {
+        border-radius: var(--md-sys-shape-corner-sm);
+    }
+
+    [data-md-surface][data-md-corner='md'] {
+        border-radius: var(--md-sys-shape-corner-md);
+    }
+
+    [data-md-surface][data-md-corner='lg'] {
+        border-radius: var(--md-sys-shape-corner-lg);
+    }
+
+    [data-md-surface][data-md-corner='lg-increased'] {
+        border-radius: var(--md-sys-shape-corner-lg-increased);
+    }
+
+    [data-md-surface][data-md-corner='xl'] {
+        border-radius: var(--md-sys-shape-corner-xl);
+    }
+
+    [data-md-surface][data-md-corner='xl-increased'] {
+        border-radius: var(--md-sys-shape-corner-xl-increased);
+    }
+
+    [data-md-surface][data-md-corner='xxl'] {
+        border-radius: var(--md-sys-shape-corner-xxl);
+    }
+
+    [data-md-surface][data-md-corner='full'] {
+        border-radius: var(--md-sys-shape-corner-full);
+    }
+
+    [data-md-surface][data-md-outlined] {
+        border: 1px solid var(--md-sys-color-outline-variant);
+    }
+
+    [data-md-surface] > * {
+        --md-layout-margin: initial;
+    }
+}
@@ -0,0 +1,48 @@
+{{-- A tonal region: M3's surface, or a step of its surface containers.
+
+         <x-surface level="surface-container-low" padding="space300" corner="lg" outlined>…</x-surface>
+
+     `level` is the colour role it is filled with: `surface`, `surface-dim`, `surface-bright`,
+     `surface-container-lowest`, `surface-container-low`, `surface-container` (the default),
+     `surface-container-high` or `surface-container-highest`; the text on it is `on-surface`
+     (docs/reference/m3/styles.md § Color). Higher steps read as nearer, which is how M3 sets
+     regions apart without a shadow. An unknown level is the default.
+
+     `padding` is a spacing token's name, `space25` … `space900`
+     (docs/reference/m3/styles-supplement.md § Spacing); anything else is no padding. `corner` is a
+     corner token, `none`, `xs`, `sm`, `md`, `lg`, `lg-increased`, `xl`, `xl-increased`, `xxl` or
+     `full` (resources/css/tokens/shape.css); anything else leaves it square. `outlined` draws
+     the 1dp outline-variant edge.
+
+     Like every layout component it takes `as` (the element, `div` by default: `section`,
+     `article`, `aside` …) and `hide-below` / `hide-from` (`medium`, `expanded`, `large` or
+     `extra-large`), and the caller's `class` and `style` land on it untouched. Drawn by
+     resources/css/layout/surface.css; the props are read in src/Support/Layout.php. --}}
+
+@props([
+    'as' => null,
+    'level' => null,
+    'padding' => null,
+    'corner' => null,
+    'outlined' => false,
+    'hideBelow' => null,
+    'hideFrom' => null,
+])
+
+@php
+    $layout = \NoNameWeb\LivewireMaterial\Support\Layout::class;
+    $element = $layout::element($as);
+
+    $attributes = $attributes->merge(array_filter([
+        'data-md-surface' => true,
+        'data-md-level' => $layout::choice($level, [
+            'surface', 'surface-dim', 'surface-bright', 'surface-container-lowest', 'surface-container-low',
+            'surface-container', 'surface-container-high', 'surface-container-highest',
+        ], 'surface-container'),
+        'data-md-padding' => $layout::spacing($padding),
+        'data-md-corner' => $layout::choice($corner, ['none', 'xs', 'sm', 'md', 'lg', 'lg-increased', 'xl', 'xl-increased', 'xxl', 'full']),
+        'data-md-outlined' => $outlined ? true : null,
+    ] + $layout::visibility($hideBelow, $hideFrom), fn ($value): bool => $value !== null));
+@endphp
+
+<{{ $element }} {{ $attributes }}>{{ $slot }}</{{ $element }}>
@@ -113,6 +113,7 @@
        </p>

        <x-livewire-material::stack as="ul" gap="space100" class="md-type-body-md">
+            <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>
    </x-livewire-material::stack>
@@ -126,3 +126,19 @@ it('fills a grid with columns of a minimum width, capped by the count', function
        ->assertScript(layoutColumns('#fill').' === 3')
        ->assertScript(layoutColumns('#capped').' === 2');
 });
+
+it('draws a surface in its role, padding and corner, and hides it below a breakpoint', function () {
+    $body = '<x-surface id="surface" level="surface-container-high" padding="space300" corner="lg" outlined hide-below="medium">Surface</x-surface>'
+        .'<div id="role" style="background-color: var(--md-sys-color-surface-container-high)"></div>';
+
+    layoutPage($body, 599)
+        ->assertScript(layoutStyle('#surface', 'display')." === 'none'");
+
+    layoutPage($body, 600)
+        ->assertScript(layoutStyle('#surface', 'display')." === 'block'")
+        ->assertScript(layoutStyle('#surface', 'backgroundColor').' === '.layoutStyle('#role', 'backgroundColor'))
+        ->assertScript(layoutStyle('#surface', 'paddingTop')." === '24px'")
+        ->assertScript(layoutStyle('#surface', 'borderTopLeftRadius')." === '16px'")
+        ->assertScript(layoutStyle('#surface', 'borderTopWidth')." === '1px'")
+        ->assertNoJavaScriptErrors();
+});
@@ -0,0 +1,73 @@
+<?php
+
+it('draws a tonal region in surface-container by default, as a div', function () {
+    $root = layoutRoot((string) $this->blade('<x-surface>Content</x-surface>'));
+
+    expect($root)->toMatchArray(['<' => 'div', 'data-md-surface' => 'data-md-surface', 'data-md-level' => 'surface-container'])
+        ->not->toHaveKeys(['data-md-padding', 'data-md-corner', 'data-md-outlined', 'data-md-hide-below', 'data-md-hide-from', 'class', 'style']);
+});
+
+it('fills the surface with each of M3\'s surface roles, and the default for any other', function () {
+    foreach (['surface', 'surface-dim', 'surface-bright', 'surface-container-lowest', 'surface-container-low', 'surface-container', 'surface-container-high', 'surface-container-highest'] as $level) {
+        expect(layoutRoot((string) $this->blade('<x-surface :level="$level" />', ['level' => $level]))['data-md-level'])->toBe($level);
+    }
+
+    expect(layoutRoot((string) $this->blade('<x-surface level="primary-container" />'))['data-md-level'])->toBe('surface-container');
+});
+
+it('pads the surface with a spacing token only, and with none for anything else', function () {
+    expect(layoutRoot((string) $this->blade('<x-surface padding="space300" />'))['data-md-padding'])->toBe('space300');
+
+    foreach (['24px', '3', 'space1000', 'roomy'] as $padding) {
+        expect(layoutRoot((string) $this->blade('<x-surface :padding="$padding" />', ['padding' => $padding]))['data-md-padding'])->toBe('none');
+    }
+});
+
+it('rounds the surface with a corner token, and leaves it square for anything else', function () {
+    foreach (['none', 'xs', 'sm', 'md', 'lg', 'lg-increased', 'xl', 'xl-increased', 'xxl', 'full'] as $corner) {
+        expect(layoutRoot((string) $this->blade('<x-surface :corner="$corner" />', ['corner' => $corner]))['data-md-corner'])->toBe($corner);
+    }
+
+    expect(layoutRoot((string) $this->blade('<x-surface corner="huge" />')))->not->toHaveKey('data-md-corner');
+});
+
+it('draws an outline only when asked', function () {
+    expect(layoutRoot((string) $this->blade('<x-surface outlined />')))->toHaveKey('data-md-outlined')
+        ->and(layoutRoot((string) $this->blade('<x-surface :outlined="false" />')))->not->toHaveKey('data-md-outlined');
+});
+
+it('draws the element it is asked for, and a div for one it does not take', function () {
+    expect(layoutRoot((string) $this->blade('<x-surface as="section">Content</x-surface>'))['<'])->toBe('section')
+        ->and((string) $this->blade('<x-surface as="section">Content</x-surface>'))->toContain('</section>')
+        ->and(layoutRoot((string) $this->blade('<x-surface as="script">Content</x-surface>'))['<'])->toBe('div')
+        ->and(layoutRoot((string) $this->blade('<x-surface as="input" />'))['<'])->toBe('div');
+});
+
+it('hides below and from a breakpoint, never below or from compact', function () {
+    expect(layoutRoot((string) $this->blade('<x-surface hide-below="expanded" hide-from="extra-large" />')))
+        ->toMatchArray(['data-md-hide-below' => 'expanded', 'data-md-hide-from' => 'extra-large']);
+
+    foreach (['compact', 'tablet', 'Medium', '840'] as $breakpoint) {
+        expect(layoutRoot((string) $this->blade('<x-surface :hide-below="$b" :hide-from="$b" />', ['b' => $breakpoint])))
+            ->not->toHaveKeys(['data-md-hide-below', 'data-md-hide-from']);
+    }
+});
+
+it('puts the caller\'s class and style on the surface untouched', function () {
+    expect(layoutRoot((string) $this->blade('<x-surface class="upload-zone" style="min-height: 12rem" data-test="zone" />')))
+        ->toMatchArray(['class' => 'upload-zone', 'style' => 'min-height: 12rem;', 'data-test' => 'zone']);
+});
+
+it('draws the surface from a stylesheet in the layout layer, imported by layout.css', function () {
+    $css = (string) file_get_contents(__DIR__.'/../../../resources/css/layout/surface.css');
+
+    expect($css)->toContain('@layer material.layout')
+        ->toContain("[data-md-surface][data-md-level='surface-container-high'] {")
+        ->toContain('background-color: var(--md-sys-color-surface-container-high);')
+        ->toContain('border: 1px solid var(--md-sys-color-outline-variant);')
+        ->toContain("@import './spacing.css';")
+        ->toContain("@import './visibility.css';")
+        // A pane on a surface keeps its content off the surface's edge again.
+        ->toContain("[data-md-surface] > * {\n        --md-layout-margin: initial;")
+        ->and((string) file_get_contents(__DIR__.'/../../../resources/css/layout.css'))->toContain("@import './layout/surface.css';");
+});