Add the Material 3 Expressive foundation

Colour, shape, type, elevation and motion as tokens and Tailwind utilities; `php artisan material:scheme`, which generates an app's colour roles with Google's material-color-utilities (spec 2025); the theme head script with light, dark and system and its Alpine store; Google Sans Flex; every Material Symbol (4,135, outlined and filled) drawn by <x-icon> without blade-icons; all 35 M3 Expressive shapes, ported from androidx, as <x-shape>; the x-figure directive; the Toasts concern; DesignGuard for applications' tests; and a showcase with every token, both themes side by side and an icon search. Colour utilities are `@theme inline`, so a section with its own data-theme repaints; without it they resolve once on :root. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V9NnLxnPp8vaaurb3Z1MFy
2026-09-13 05:24:11 +02:00
parent 9b53891a8e
commit b48e879254
8364 changed files with 12720 additions and 28 deletions
@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * The theme <html> shows. A bare `html` selector would be read as text to search for.
+ */
+function theme(string $attribute, string $value): string
+{
+    return "document.documentElement.getAttribute('{$attribute}') === '{$value}'";
+}
+
+it('follows the operating system while the visitor has not chosen', function () {
+    visit('/material')->inDarkMode()
+        ->assertScript(theme('data-theme', 'dark'))
+        ->assertScript(theme('data-theme-choice', 'system'))
+        ->assertNoJavaScriptErrors();
+
+    visit('/material')->inLightMode()
+        ->assertScript(theme('data-theme', 'light'));
+});
+
+it('keeps the visitor\'s choice over the operating system', function () {
+    $page = visit('/material')->inDarkMode()
+        ->assertScript(theme('data-theme', 'dark'));
+
+    $page->click('@theme-light')
+        ->assertScript(theme('data-theme', 'light'))
+        ->assertAttribute('@theme-light', 'aria-pressed', 'true')
+        ->assertScript("localStorage.getItem('material-theme') === 'light'");
+
+    $page->refresh()
+        ->assertScript(theme('data-theme', 'light'))
+        ->assertScript(theme('data-theme-choice', 'light'));
+});
+
+it('adopts an earlier toggle\'s choice once', function () {
+    config(['livewire-material.theme.legacy_keys' => ['mary-theme']]);
+
+    $page = visit('/material')->inLightMode()
+        ->assertScript(theme('data-theme', 'light'));
+
+    $page->script("localStorage.setItem('mary-theme', JSON.stringify('dark'))");
+
+    $page->refresh()
+        ->assertScript(theme('data-theme', 'dark'))
+        ->assertScript("localStorage.getItem('mary-theme') === null")
+        ->assertScript("localStorage.getItem('material-theme') === 'dark'");
+});
+
+it('repaints a section that sets its own theme', function () {
+    $swatch = fn (int $index): string => "getComputedStyle(document.querySelectorAll('#colour [data-theme] .bg-primary')[{$index}]).backgroundColor";
+
+    visit('/material')->inLightMode()
+        ->assertScript(theme('data-theme', 'light'))
+        ->assertScript("{$swatch(0)} !== {$swatch(1)}");
+});
@@ -0,0 +1,57 @@
+<?php
+
+use Illuminate\View\ViewException;
+use NoNameWeb\LivewireMaterial\Support\SvgFile;
+
+it('draws a symbol inline, hidden from screen readers, 24px by default', function () {
+    $this->blade('<x-icon name="calendar_month" />')
+        ->assertSee('class="shrink-0 size-6"', false)
+        ->assertSee('aria-hidden="true"', false)
+        ->assertSee('fill="currentColor"', false)
+        ->assertSee('viewBox="0 -960 960 960"', false);
+});
+
+it('leaves the size to a caller who gives one', function () {
+    $this->blade('<x-icon name="calendar_month" class="size-4 text-primary" />')
+        ->assertSee('class="shrink-0 size-4 text-primary"', false)
+        ->assertDontSee('size-6', false);
+});
+
+it('names the icon for a screen reader when it carries the meaning alone', function () {
+    $this->blade('<x-icon name="lock" label="Password protected" />')
+        ->assertSee('aria-label="Password protected"', false)
+        ->assertSee('role="img"', false)
+        ->assertDontSee('aria-hidden', false);
+});
+
+it('draws the filled symbol when asked', function () {
+    $outlined = (string) $this->blade('<x-icon name="favorite" />');
+    $filled = (string) $this->blade('<x-icon name="favorite" filled />');
+
+    expect($filled)->not->toBe($outlined)
+        ->and($filled)->toContain('<path d=');
+});
+
+it('refuses a name that is not a symbol', function () {
+    expect(fn () => $this->blade('<x-icon name="not_a_symbol_at_all" />'))
+        ->toThrow(ViewException::class, 'There is no Material Symbol named [not_a_symbol_at_all].');
+});
+
+it('points a Heroicon name at the symbol catalogue', function () {
+    expect(fn () => $this->blade('<x-icon name="o-calendar-days" />'))
+        ->toThrow(ViewException::class, 'is not a Material Symbol name');
+});
+
+it('ships every symbol outlined and filled, painted in the text colour', function () {
+    $symbols = SvgFile::symbolNames();
+    $filled = array_map(fn (string $file): string => basename($file, '.svg'), glob(__DIR__.'/../../../resources/svg/symbols/filled/*.svg'));
+
+    expect(count($symbols))->toBeGreaterThan(4000)
+        ->and($filled)->toEqual($symbols);
+
+    foreach (['home', 'search', 'cloud_upload', 'content_copy', 'delete'] as $name) {
+        expect(file_get_contents(__DIR__."/../../../resources/svg/symbols/outlined/{$name}.svg"))
+            ->toStartWith('<svg fill="currentColor" xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path')
+            ->not->toContain('width=');
+    }
+});
@@ -0,0 +1,35 @@
+<?php
+
+use Illuminate\View\ViewException;
+use NoNameWeb\LivewireMaterial\Support\SvgFile;
+
+it('ships M3 Expressive\'s 35 shapes', function () {
+    expect(SvgFile::shapeNames())->toHaveCount(35)
+        ->toContain('circle', 'cookie-9', 'clover-4', 'soft-burst', 'pixel-triangle', 'heart');
+});
+
+it('draws every shape as one path in the text colour, filling a 100-unit box', function () {
+    foreach (SvgFile::shapeNames() as $shape) {
+        $svg = file_get_contents(__DIR__."/../../../resources/svg/shapes/{$shape}.svg");
+
+        expect($svg)->toMatch('#^<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" fill="currentColor"><path d="[MCZ0-9. -]+"/></svg>\n$#');
+
+        preg_match_all('/-?\d+(?:\.\d+)?/', str($svg)->after(' d="')->before('"')->toString(), $numbers);
+        $xs = array_map('floatval', array_filter($numbers[0], fn ($key) => $key % 2 === 0, ARRAY_FILTER_USE_KEY));
+        $ys = array_map('floatval', array_filter($numbers[0], fn ($key) => $key % 2 === 1, ARRAY_FILTER_USE_KEY));
+
+        expect(min([...$xs, ...$ys]))->toBeGreaterThanOrEqual(0)
+            ->and(max([...$xs, ...$ys]))->toBeLessThanOrEqual(100)
+            ->and(max(max($xs) - min($xs), max($ys) - min($ys)))->toBeGreaterThanOrEqual(96, "{$shape} does not fill its box");
+    }
+});
+
+it('renders a shape hidden from assistive tech', function () {
+    $this->blade('<x-shape name="cookie-9" class="size-20 text-secondary-container" />')
+        ->assertSee('<svg aria-hidden="true" focusable="false" class="size-20 text-secondary-container" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"', false);
+});
+
+it('refuses a shape that does not exist', function () {
+    expect(fn () => $this->blade('<x-shape name="blob" />'))
+        ->toThrow(ViewException::class, 'There is no M3 Expressive shape named [blob].');
+});
@@ -0,0 +1,24 @@
+<?php
+
+it('follows the operating system until the visitor chooses, by default', function () {
+    $this->blade('<x-theme-script />')
+        ->assertSee('({"default":"system","key":"material-theme","legacy":[]})', false);
+});
+
+it('takes the application\'s default, key and legacy keys', function () {
+    config(['livewire-material.theme' => [
+        'default' => 'dark',
+        'storage_key' => 'sealshare-theme',
+        'legacy_keys' => ['mary-theme'],
+    ]]);
+
+    $this->blade('<x-theme-script />')
+        ->assertSee('({"default":"dark","key":"sealshare-theme","legacy":["mary-theme"]})', false);
+});
+
+it('falls back to the operating system for a default it does not know', function () {
+    config(['livewire-material.theme.default' => 'blue']);
+
+    $this->blade('<x-theme-script />')
+        ->assertSee('"default":"system"', false);
+});
@@ -0,0 +1,48 @@
+<?php
+
+use NoNameWeb\LivewireMaterial\Testing\DesignGuard;
+
+const GUARD_FIXTURES = __DIR__.'/../Fixtures/design-guard';
+
+/**
+ * @param  list<string>  $violations
+ * @return list<string>
+ */
+function fixtureRelative(array $violations): array
+{
+    return array_map(fn (string $violation): string => str_replace(realpath(GUARD_FIXTURES).'/', '', $violation), $violations);
+}
+
+it('finds what compiles to nothing', function () {
+    expect(fixtureRelative(DesignGuard::scan(realpath(GUARD_FIXTURES))->violations()))->toBe([
+        'app/Status.php:14 colour the theme does not declare `text-red-500`',
+        'views/page.blade.php:3 daisyUI class `card`',
+        'views/page.blade.php:6 daisyUI class `btn-primary`',
+        'views/page.blade.php:4 unknown Material Symbol `o-home`',
+        'views/page.blade.php:5 unknown Material Symbol `not_a_symbol`',
+        'views/page.blade.php:2 maryUI component `<x-mary-button`',
+        'views/page.blade.php:3 colour the theme does not declare `bg-base-200`',
+        'views/page.blade.php:6 colour the theme does not declare `text-red-600`',
+    ]);
+});
+
+it('bans the roles an application leaves out', function () {
+    $violations = fixtureRelative(DesignGuard::scan(realpath(GUARD_FIXTURES.'/views'))
+        ->forbidColours(['tertiary'])
+        ->violations());
+
+    expect($violations)->toContain('views/page.blade.php:7 colour the theme does not declare `text-tertiary`');
+});
+
+it('bans any further pattern', function () {
+    $violations = fixtureRelative(DesignGuard::scan(realpath(GUARD_FIXTURES.'/views'))
+        ->forbid('/\bfocus-ring\b/', 'a retired utility')
+        ->violations());
+
+    expect($violations)->toContain('views/page.blade.php:7 a retired utility');
+});
+
+it('passes the package\'s own views', function () {
+    expect(DesignGuard::scan([__DIR__.'/../../resources/views', __DIR__.'/../../resources/js', __DIR__.'/../../src'])->violations())
+        ->toBe([]);
+});
@@ -0,0 +1,80 @@
+<?php
+
+use Illuminate\Support\Facades\File;
+use Illuminate\Support\Str;
+
+beforeEach(function () {
+    $this->stylesheet = sys_get_temp_dir().'/material-scheme-'.Str::random(8).'.css';
+    $this->data = Str::replaceLast('.css', '.json', $this->stylesheet);
+});
+
+afterEach(function () {
+    File::delete([$this->stylesheet, $this->data]);
+});
+
+it('writes the scheme as a stylesheet and as data', function () {
+    $this->artisan('material:scheme', ['seed' => '#4F46E5', '--output' => $this->stylesheet])
+        ->assertSuccessful();
+
+    $scheme = json_decode(File::get($this->data), true);
+    $stylesheet = File::get($this->stylesheet);
+
+    expect($scheme)
+        ->seed->toBe('#4f46e5')
+        ->variant->toBe('tonal-spot')
+        ->spec->toBe('2025')
+        ->and(array_keys($scheme['dark']))->toEqual(array_keys($scheme['light']))
+        ->and($scheme['light'])->toHaveKeys(['primary', 'on-primary', 'tertiary-container', 'surface-container-high', 'outline-variant', 'success', 'on-warning-container', 'info-container'])
+        ->and($scheme['light']['surface'])->not->toBe($scheme['dark']['surface'])
+        ->and($scheme['light']['inverse-success'])->toBe($scheme['dark']['success']);
+
+    foreach (['light' => "[data-theme='light']", 'dark' => "[data-theme='dark']"] as $theme => $selector) {
+        $block = Str::of($stylesheet)->after($selector)->before('}')->toString();
+
+        expect($block)->toContain("color-scheme: {$theme};");
+
+        foreach ($scheme[$theme] as $role => $hex) {
+            expect($block)->toContain("--md-sys-color-{$role}: {$hex};");
+        }
+    }
+
+    expect($stylesheet)->toContain('php artisan material:scheme "#4f46e5" --variant=tonal-spot');
+});
+
+it('generates a different scheme per variant', function () {
+    $this->artisan('material:scheme', ['seed' => '#4f46e5', '--variant' => 'vibrant', '--output' => $this->stylesheet])
+        ->assertSuccessful();
+
+    $vibrant = json_decode(File::get($this->data), true);
+
+    $this->artisan('material:scheme', ['seed' => '#4f46e5', '--output' => $this->stylesheet])
+        ->assertSuccessful();
+
+    $tonalSpot = json_decode(File::get($this->data), true);
+
+    expect($vibrant['variant'])->toBe('vibrant')
+        ->and($vibrant['light']['primary'])->not->toBe($tonalSpot['light']['primary']);
+});
+
+it('refuses a seed that is not a colour', function () {
+    $this->artisan('material:scheme', ['seed' => 'indigo', '--output' => $this->stylesheet])
+        ->expectsOutputToContain('#rrggbb')
+        ->assertFailed();
+
+    expect(File::exists($this->stylesheet))->toBeFalse();
+});
+
+it('refuses an unknown variant', function () {
+    $this->artisan('material:scheme', ['seed' => '#4f46e5', '--variant' => 'loud', '--output' => $this->stylesheet])
+        ->expectsOutputToContain('Unknown variant "loud"')
+        ->assertFailed();
+});
+
+it('fails without writing anything when node cannot run', function () {
+    config(['livewire-material.node' => '/nonexistent/node']);
+
+    $this->artisan('material:scheme', ['seed' => '#4f46e5', '--output' => $this->stylesheet])
+        ->assertFailed();
+
+    expect(File::exists($this->stylesheet))->toBeFalse();
+});
@@ -30,3 +30,15 @@ it('does not mount the showcase when disabled', function () {

    $this->get('/material')->assertNotFound();
 });
+
+it('serves a symbol for the icon search', function () {
+    $this->get('/material/symbols/filled/favorite.svg')
+        ->assertOk()
+        ->assertHeader('Content-Type', 'image/svg+xml')
+        ->assertSee('viewBox="0 -960 960 960"', false);
+});
+
+it('answers 404 for a symbol or style that does not exist', function () {
+    $this->get('/material/symbols/outlined/not_a_symbol_at_all.svg')->assertNotFound();
+    $this->get('/material/symbols/sharp/favorite.svg')->assertNotFound();
+});
@@ -0,0 +1,29 @@
+<?php
+
+use Livewire\Exceptions\MethodNotFoundException;
+use Livewire\Livewire;
+use NoNameWeb\LivewireMaterial\Tests\Fixtures\ToastingComponent;
+
+it('dispatches a toast for the snackbar', function () {
+    Livewire::test(ToastingComponent::class)
+        ->call('save')
+        ->assertDispatched('toast', type: 'success', title: 'Saved', description: 'Your settings are stored.', timeout: 4000);
+});
+
+it('passes a timeout through', function () {
+    Livewire::test(ToastingComponent::class)
+        ->call('fail')
+        ->assertDispatched('toast', type: 'error', title: 'Could not save', description: null, timeout: 8000);
+});
+
+it('keeps the toast across a redirect', function () {
+    Livewire::test(ToastingComponent::class)
+        ->call('leave')
+        ->assertDispatched('toast', type: 'info', title: 'Link copied')
+        ->assertRedirect('/elsewhere');
+});
+
+it('is not an action the browser can call', function () {
+    expect(fn () => Livewire::test(ToastingComponent::class)->call('success', 'Forged'))
+        ->toThrow(MethodNotFoundException::class);
+});
@@ -0,0 +1,78 @@
+<?php
+
+use Illuminate\Support\Facades\File;
+use Illuminate\Support\Str;
+
+function packageCss(string $path = ''): string
+{
+    return __DIR__.'/../../resources/css'.($path === '' ? '' : '/'.$path);
+}
+
+/**
+ * The custom properties one selector's block declares.
+ *
+ * @return array<string, string>
+ */
+function declarations(string $css, string $selector): array
+{
+    preg_match_all('/(--[\w-]+):\s*([^;]+);/', Str::of($css)->after($selector)->before('}')->toString(), $matches);
+
+    return array_combine($matches[1], $matches[2]);
+}
+
+it('ships a default scheme that declares every role in both themes', function () {
+    $scheme = json_decode(File::get(packageCss('tokens/scheme.json')), true);
+    $css = File::get(packageCss('tokens/scheme.css'));
+
+    $light = declarations($css, "[data-theme='light']");
+    $dark = declarations($css, "[data-theme='dark']");
+
+    expect(array_keys($light))->toEqual(array_keys($dark))
+        ->and(count($light))->toBe(count($scheme['light']))
+        ->and(Str::of($css)->after("[data-theme='light']")->before('}')->toString())->toContain('color-scheme: light;')
+        ->and(Str::of($css)->after("[data-theme='dark']")->before('}')->toString())->toContain('color-scheme: dark;');
+
+    foreach ($scheme['light'] as $role => $hex) {
+        expect($light["--md-sys-color-{$role}"])->toBe($hex)
+            ->and($dark["--md-sys-color-{$role}"])->toBe($scheme['dark'][$role]);
+    }
+});
+
+it('turns every role into a Tailwind colour', function () {
+    $roles = array_keys(json_decode(File::get(packageCss('tokens/scheme.json')), true)['light']);
+    $theme = File::get(packageCss('tokens/theme.css'));
+
+    foreach ($roles as $role) {
+        expect($theme)->toContain("--color-{$role}: var(--md-sys-color-{$role});");
+    }
+});
+
+it('resolves colour utilities on the element, so a nested data-theme repaints them', function () {
+    $theme = File::get(packageCss('tokens/theme.css'));
+
+    preg_match_all('/@theme inline \{(.*?)\}/s', $theme, $inline);
+
+    expect(implode("\n", $inline[1]))
+        ->toContain('--color-primary: var(--md-sys-color-primary);')
+        ->toContain('--color-body: var(--md-sys-color-on-surface-variant);')
+        ->not->toMatch('/--[\w-]+:\s*#/');
+});
+
+it('leaves the choice of theme to the head script, never to a media query', function () {
+    foreach (File::allFiles(packageCss()) as $file) {
+        expect($file->getContents())->not->toContain('prefers-color-scheme');
+    }
+});
+
+it('makes every motion token instant under reduced motion', function () {
+    $motion = File::get(packageCss('tokens/motion.css'));
+    $reduced = Str::of($motion)->after('prefers-reduced-motion: reduce')->toString();
+
+    preg_match_all('/(--md-sys-motion-[\w-]*duration[\w-]*):/', Str::before($motion, '@media'), $durations);
+
+    expect($durations[1])->not->toBeEmpty();
+
+    foreach ($durations[1] as $duration) {
+        expect($reduced)->toContain("{$duration}: 0ms;");
+    }
+});
@@ -0,0 +1,31 @@
+<?php
+
+namespace NoNameWeb\LivewireMaterial\Tests\Fixtures;
+
+use Livewire\Component;
+use NoNameWeb\LivewireMaterial\Concerns\Toasts;
+
+class ToastingComponent extends Component
+{
+    use Toasts;
+
+    public function save(): void
+    {
+        $this->success('Saved', 'Your settings are stored.');
+    }
+
+    public function fail(): void
+    {
+        $this->error('Could not save', timeout: 8000);
+    }
+
+    public function leave(): void
+    {
+        $this->info('Link copied', redirectTo: '/elsewhere');
+    }
+
+    public function render(): string
+    {
+        return '<div></div>';
+    }
+}
@@ -0,0 +1,17 @@
+<?php
+
+namespace App;
+
+enum Status: string
+{
+    case Active = 'active';
+    case Expired = 'expired';
+
+    public function textClass(): string
+    {
+        return match ($this) {
+            self::Active => 'text-success',
+            self::Expired => 'text-red-500',
+        };
+    }
+}
@@ -0,0 +1,9 @@
+{{-- <x-mary-button> and btn-primary in a comment are not violations --}}
+<x-mary-button label="Old" />
+<div class="card bg-base-200 p-4">
+    <x-icon name="o-home" />
+    <x-button icon="calendar_month" icon-right="not_a_symbol" label="Fine" />
+    <span @class(['btn-primary' => $active, 'select-none'])>text-red-600</span>
+    <p class="text-tertiary table collapse link focus-ring">Tailwind's and ours</p>
+    <x-icon :name="$dynamic" />
+</div>