guidelines: livewire: improve

Author: ashleyhindle

.ai/livewire/2/.gitkeep

@@ -0,0 +1,16 @@
+- `wire:model` is live by default.
+- **Namespace**: Components typically exist in `App\Http\Livewire`.
+- **Events**: Use `emit()`, `emitTo()`, `emitSelf()` and `dispatchBrowserEvent()` for events.
+- Alpine is included separately to Livewire.
+- You can listen for `livewire:load` to hook into Livewire initialization, and `Livewire.onPageExpired` for when the page expires:
+@verbatim
+<code-snippet name="livewire:load example" lang="js">
+document.addEventListener('livewire:load', function () {
+    Livewire.onPageExpired(() => {
+        alert('Your session expired');
+    });
+
+    Livewire.onError(status => console.error(status));
+});
+</code-snippet>
+@endverbatim

.ai/livewire/2/core.blade.php

@@ -1,8 +1,31 @@
-#### Key Changes from Livewire 2
-- These changed in Livewire 2, but may not have in this project. Verify this project's setup to ensure you conform with conventions.
-
+## Key Changes from Livewire 2
+- These changed in Livewire 2, but may not have been updated in this project. Verify this project's setup to ensure you conform with project conventions.
+- **Wire:model**: Use `wire:model.live` for real-time updates, `wire:model` is now deferred by default.
 - **Namespace**: Components now use `App\Livewire` (not `App\Http\Livewire`).
 - **Events**: Use `$this->dispatch()` (not `emit` or `dispatchBrowserEvent`).
 - **Layout path**: `components.layouts.app` (not `layouts.app`).
-- **Deferred by default**: Use `wire:model.live` for real-time updates.
-- **Alpine included**: Don't manually include Alpine.js.
+
+## New directives
+- `wire:show`, `wire:transition`, `wire:cloak, `wire:offline`, `wire:target` are available for use. Use the docs to find usages.
+
+## Alpine
+- Alpine is now included with Livewire, don't manually include Alpine.js.
+- Plugins built in to Alpine: persist, intersect, collapse, and focus.
+
+## Lifecycle hooks
+- You can listen for `livewire:init` to hook into Livewire initialization, and `fail.status === 419` for the page expiring:
+@verbatim
+<code-snippet name="livewire:load example" lang="js">
+document.addEventListener('livewire:init', function () {
+    Livewire.hook('request', ({ fail }) => {
+        if (fail && fail.status === 419) {
+            alert('Your session expired');
+        }
+    });
+
+    Livewire.hook('message.failed', (message, component) => {
+        console.error(message);
+    });
+});
+</code-snippet>
+@endverbatim

.ai/livewire/3/core.blade.php

@@ -1,11 +1,13 @@
 ## Livewire Core
-- Use the `search-docs` tool to find exact version specific documentation for how to write Livewire.
-
+- Use the `search-docs` tool to find exact version specific documentation for how to write Livewire & Livewire tests.
+- Use the `php artisan make:livewire [Posts\\CreatePost]` artisan command to create new components
+- State should live on the server, with the UI reflecting it.
+- All Livewire requests hit the Laravel backend, they're like regular HTTP requests. Always validate form data, and run authorization checks in Livewire actions.
 
 ## Livewire Best Practices
-- **Single root element** in Blade components
-- **Loading states**: Use `wire:loading` and `wire:dirty`.
-- **Add wire:key** in loops:
+- Livewire components require a single root element.
+- Use `wire:loading` and `wire:dirty` for delightful loading states.
+- Add `wire:key` in loops:
 @verbatim
     ```blade
     @foreach ($items as $item)
@@ -15,3 +17,28 @@
     @endforeach
     ```
 @endverbatim
+- Prefer lifecycle hooks like `mount()`, `updatedFoo()`) for initialization and reactive side effects:
+@verbatim
+<code-snippet name="Lifecycle hook examples" lang="php">
+    public function mount(User $user) { $this->user = $user; }
+    public function updatedSearch() { $this->resetPage(); }
+</code-snippet>
+@endverbatim
+
+## Testing Livewire
+@verbatim
+<code-snippet name="Example Livewire component test" lang="php">
+    Livewire::test(Counter::class)
+        ->assertSet('count', 0)
+        ->call('increment')
+        ->assertSet('count', 1)
+        ->assertSee(1)
+        ->assertStatus(200);
+</code-snippet>
+@endverbatim
+@verbatim
+    <code-snippet name="Testing a Livewire component exists within a page" lang="php">
+        $this->get('/posts/create')
+        ->assertSeeLivewire(CreatePost::class);
+    </code-snippet>
+@endverbatim

.ai/livewire/core.blade.php

@@ -1,5 +1,6 @@
 - This project uses Livewire Volt for interactivity within its pages. New pages requiring interactivity must also use Livewire Volt. There is documentation available for it.
-- Volt is an elegantly crafted **functional** API for Livewire that supports single-file components, allowing a component's PHP logic and Blade templates to coexist in the same file
+- Make new Volt components using `php artisan make:volt [name] [--test] [--pest]`
+- Volt is a **functional** API for Livewire that supports single-file components, allowing a component's PHP logic and Blade templates to coexist in the same file
 - **Single-File Components**: Livewire Volt allows PHP logic and Blade templates in one file. Components use the `@volt` directive.
 - You must check existing Volt components to find out if they're functional or class based. If you can't detect that, ask the user which they prefer before writing a Volt component.