| Server IP : 167.235.224.122 / Your IP : 216.73.216.110 Web Server : Apache/2.4.58 (Ubuntu) System : Linux newplayground 6.8.0-136-generic #136-Ubuntu SMP PREEMPT_DYNAMIC Wed Jul 1 21:33:11 UTC 2026 aarch64 User : deploy ( 1000) PHP Version : 8.4.23 Disable Function : NONE MySQL : OFF | cURL : ON | WGET : ON | Perl : ON | Python : OFF | Sudo : ON | Pkexec : OFF Directory : /var/www/html/reef_analytics/vendor/livewire/livewire/ |
Upload File : |
# wire:model Modifier Layering PRD
## Problem
`wire:model` modifiers (`.blur`, `.change`, `.debounce`) only control network request timing. Ephemeral (client-side) state ALWAYS syncs immediately as user types. Users can't delay ephemeral sync until blur/enter/change.
## Feature
Split modifiers into two layers: modifiers BEFORE `.live` control ephemeral sync timing (forwarded to x-model), modifiers AFTER `.live` control network timing. Breaking change for v4.
## Before
```blade
wire:model {{-- ephemeral immediate, no network --}}
wire:model.blur {{-- ephemeral immediate, network on blur --}}
wire:model.live {{-- ephemeral immediate, network debounced --}}
wire:model.live.debounce.500ms {{-- ephemeral immediate, network debounced 500ms --}}
```
- All modifiers only affect network layer
- No way to control ephemeral sync timing
- `.blur`/`.change` don't affect when x-model syncs
## After
```blade
wire:model {{-- ephemeral immediate, no network --}}
wire:model.blur {{-- ephemeral on blur, no network --}}
wire:model.change {{-- ephemeral on change, no network --}}
wire:model.enter {{-- ephemeral on enter, no network --}}
wire:model.blur.enter {{-- ephemeral on blur OR enter, no network --}}
wire:model.live {{-- ephemeral immediate, network debounced --}}
wire:model.live.blur {{-- ephemeral immediate, network on blur (OLD .blur behavior) --}}
wire:model.blur.live {{-- ephemeral on blur, network on blur --}}
wire:model.blur.live.debounce.500ms {{-- ephemeral on blur, network debounced 500ms after --}}
```
- Modifiers before `.live` → forwarded to x-model (controls ephemeral sync)
- Modifiers after `.live` → handled by Livewire (controls network)
- Everything chains sequentially: ephemeral syncs first, then network fires
## Relevant Files
- `js/directives/wire-model.js` — main implementation (lines 1-186)
- `node_modules/alpinejs/src/directives/x-model.js` — reference for how Alpine handles `.blur`/`.change`/`.enter` (lines 58-98)
- `src/Features/SupportDataBinding/BrowserTest.php` — existing browser tests
## Current Logic (wire-model.js:34-82)
```js
let isLive = modifiers.includes('live')
let isLazy = modifiers.includes('lazy') || modifiers.includes('change')
let onBlur = modifiers.includes('blur')
// ... these only control WHEN update() is called for network
// x-model always gets modifiers minus 'lazy','defer','debounce','throttle'
// meaning .blur/.change still get forwarded but DON'T affect ephemeral sync
// because wire:model uses get/set object pattern, not event listeners
```
Problem: `getModifierTail()` forwards `.blur` to x-model, but wire:model uses getter/setter pattern (`x-model.blur() { get(), set() }`), not Alpine's event-listener approach. So Alpine's `.blur` modifier has no effect.
## Changes Needed
1. **Parse modifiers into two groups** — split at `.live` boundary
- `ephemeralModifiers` = everything before `.live`
- `networkModifiers` = everything after `.live`
2. **Create extraction function** with clean interface:
```js
let {
ephemeralModifiers, // forwarded to x-model tail
onEphemeralSync, // callback when ephemeral state changes
shouldSendNetwork, // fn to check if network should fire
} = parseWireModelModifiers(modifiers)
```
3. **Forward ephemeral modifiers to x-model** — these get added to `x-model.blur.change.enter` etc.
4. **Add event listeners for network triggers** — if network modifiers include `.blur`, add `@blur` handler. Same for `.change`, `.enter`.
5. **Handle debounce/throttle at network layer** — wrap network callbacks in debounce/throttle based on network modifiers.
6. **x-model set() callback triggers network** — when x-model syncs (based on its modifiers), check if `.live` is present and call network update.
### Implementation Sketch
```js
directive('model', ({ el, directive, component, cleanup }) => {
let { expression, modifiers } = directive
// Split modifiers at .live boundary
let liveIndex = modifiers.indexOf('live')
let ephemeralModifiers = liveIndex === -1 ? modifiers : modifiers.slice(0, liveIndex)
let networkModifiers = liveIndex === -1 ? [] : modifiers.slice(liveIndex + 1)
let isLive = liveIndex !== -1
// Build x-model modifier tail from ephemeral modifiers
let xModelTail = buildModifierTail(ephemeralModifiers)
// Build network update function with debounce/throttle
let networkUpdate = buildNetworkUpdate(networkModifiers, component, expression, el, directive)
// Determine network trigger events
let networkTriggers = extractNetworkTriggers(networkModifiers)
Alpine.bind(el, {
['@blur']() {
if (networkTriggers.blur) networkUpdate()
},
['@change']() {
if (networkTriggers.change) networkUpdate()
},
['@keydown.enter']() {
if (networkTriggers.enter) networkUpdate()
},
['x-model' + xModelTail]() {
return {
get() {
return dataGet(component.$wire, expression)
},
set(value) {
dataSet(component.$wire, expression, value)
// If live with no specific triggers, fire on every sync
if (isLive && networkTriggers.immediate) {
networkUpdate()
}
},
}
}
})
})
```
## Decisions
- **Breaking change in v4** — acceptable since v4 is ~2 weeks old
- **`.live` is the delimiter** — everything before controls ephemeral, after controls network
- **Modifiers compound** — `.blur.enter` means blur OR enter (both trigger sync)
- **Network inherits ephemeral timing by default** — if no network modifiers, network fires when ephemeral syncs
- **`.live` alone = debounced immediate** — current behavior, ephemeral immediate + network debounced
- **`.live.blur` = ephemeral immediate, network on blur** — preserves old `.blur` behavior for migration
- **Empty network modifiers with `.live`** — means "fire network when ephemeral syncs" (for `.blur.live`)
## Test File
`src/Features/SupportDataBinding/BrowserTest.php` (add to existing file)
### New Test Cases
Single consolidated test with multiple scenarios:
1. `wire:model` — ephemeral syncs on input, no network
2. `wire:model.blur` — ephemeral syncs on blur only, no network
3. `wire:model.change` — ephemeral syncs on change only, no network
4. `wire:model.enter` — ephemeral syncs on enter only, no network
5. `wire:model.blur.enter` — ephemeral syncs on blur OR enter, no network
6. `wire:model.live` — ephemeral immediate, network debounced
7. `wire:model.live.blur` — ephemeral immediate, network on blur (old behavior)
8. `wire:model.blur.live` — ephemeral on blur, network on blur
9. `wire:model.blur.live.debounce.500ms` — ephemeral on blur, network debounced
9. `wire:model.blur.live.throttle.500ms` — ephemeral on blur, network throttled
Each scenario: type into input, verify ephemeral state via `x-text="$wire.prop"`, verify server state via `{{ $prop }}`, trigger blur/enter/change, verify both states.
## Manual Testing
1. **Test ephemeral-only blur**
- Create input with `wire:model.blur="title"`
- Type "hello" — ephemeral should NOT update
- Click away — ephemeral updates to "hello"
- Server still shows old value
2. **Test network on blur (old behavior)**
- Create input with `wire:model.live.blur="title"`
- Type "hello" — ephemeral updates immediately
- Click away — network request fires, server updates
3. **Test full blur.live**
- Create input with `wire:model.blur.live="title"`
- Type "hello" — ephemeral stays unchanged
- Click away — ephemeral updates, network fires, server updates
## Documentation
**File:** `docs/wire-model.md`
**Section to modify:** "Customizing update timing" (line ~51) and "Reference" table (line ~291)
**Add:**
- Explain modifier layering concept
- Update examples to show new syntax
- Add migration note about breaking change
- Update modifier reference table
## Git
**Commit message:**
```
feat(wire:model): control ephemeral sync timing with modifiers
BREAKING: Modifiers before .live now control ephemeral (x-model) sync
timing, not just network timing. Previous .blur behavior is now .live.blur.
- wire:model.blur syncs ephemeral on blur (no network)
- wire:model.live.blur syncs ephemeral immediate, network on blur
- wire:model.blur.live syncs both on blur
- Supports .blur, .change, .enter and combinations
Migration: Replace wire:model.blur with wire:model.live.blur for old behavior.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
```
**PR Title:**
`feat(wire:model)!: control ephemeral sync timing with modifiers`
**PR Description:**
```
## Summary
- Modifiers before `.live` control ephemeral (x-model) sync timing
- Modifiers after `.live` control network timing
- BREAKING: `wire:model.blur` now delays ephemeral sync, use `.live.blur` for old behavior
## Test plan
- [ ] `wire:model.blur` delays ephemeral sync until blur
- [ ] `wire:model.live.blur` matches old `.blur` behavior
- [ ] `wire:model.blur.live` delays both ephemeral and network until blur
- [ ] Compound modifiers work (`.blur.enter`)
- [ ] Debounce/throttle work on network layer
```