offline docs

offline-docs/alpinejs/magics/dispatch.md

@@ -0,0 +1,146 @@
+# Alpine.js Documentation - Magics
+
+Magics are special properties that are available inside Alpine expressions. They provide convenient access to common functionality.
+
+## [$dispatch](/magics/dispatch)
+
+`$dispatch` is a helpful shortcut for dispatching browser events.
+
+```
+<div @notify="alert('Hello World!')">
+
+
+n<button @click="$dispatch('notify')">
+
+
+nNotify
+
+
+n</button>
+
+
+n</div>
+```
+
+You can also pass data along with the dispatched event if you wish. This data will be accessible as the `.detail` property of the event:
+
+```
+<div @notify="alert($event.detail.message)">
+
+
+n<button @click="$dispatch('notify', { message: 'Hello World!' })">
+
+
+nNotify
+
+
+n</button>
+
+
+n</div>
+```
+
+Under the hood, `$dispatch` is a wrapper for the more verbose API: `element.dispatchEvent(new CustomEvent(...))`
+
+**Note on event propagation**
+
+Notice that, because of [event bubbling](https://en.wikipedia.org/wiki/Event_bubbling), when you need to capture events dispatched from nodes that are under the same nesting hierarchy, you'll need to use the [`.window`](https://github.com/alpinejs/alpine#x-on) modifier:
+
+**Example:**
+
+```
+<!-- 🚫 Won't work -->
+
+
+n<div x-data>
+
+
+n<span @notify="..."></span>
+
+
+n<button @click="$dispatch('notify')">Notify</button>
+
+
+n</div>
+
+
+n<!-- ✅ Will work (because of .window) -->
+
+
+n<div x-data>
+
+
+n<span @notify.window="..."></span>
+
+
+n<button @click="$dispatch('notify')">Notify</button>
+
+
+n</div>
+```
+
+> The first example won't work because when `notify` is dispatched, it'll propagate to its common ancestor, the `div`, not its sibling, the `<span>`. The second example will work because the sibling is listening for `notify` at the `window` level, which the custom event will eventually bubble up to.
+
+### [Dispatching to other components](#dispatching-to-components)
+
+You can also take advantage of the previous technique to make your components talk to each other:
+
+**Example:**
+
+```
+<div
+
+
+nx-data="{ title: 'Hello' }"
+
+
+n@set-title.window="title = $event.detail"
+
+
+n>
+
+
+nh1 x-text="title"></h1>
+
+
+n</div>
+
+
+n<div x-data>
+
+
+n<button @click="$dispatch('set-title', 'Hello World!')">Click me</button>
+
+
+n</div>
+
+
+n<!-- When clicked, the content of the h1 will set to "Hello World!. -->
+```
+
+### [Dispatching to x-model](#dispatching-to-x-model)
+
+You can also use `$dispatch()` to trigger data updates for `x-model` data bindings. For example:
+
+```
+<div x-data="{ title: 'Hello' }">
+
+
+n<span x-model="title">
+
+
+n<button @click="$dispatch('input', 'Hello World!')">Click me</button>
+
+
+n<!-- After the button is pressed, `x-model` will catch the bubbling "input" event, and update title. -->
+
+
+n</span>
+
+
+n</div>
+```
+
+This opens up the door for making custom input components whose value can be set via `x-model`.
+
+Code highlighting provided by [Torchlight](https://torchlight.dev/)

offline-docs/alpinejs/magics/el.md

@@ -0,0 +1,17 @@
+# Alpine.js Documentation - Magics
+
+Magics are special properties that are available inside Alpine expressions. They provide convenient access to common functionality.
+
+## [$el](/magics/el)
+
+`$el` is a magic property that can be used to retrieve the current DOM node.
+
+```
+<button @click="$el.innerHTML = 'Hello World!'">Replace me with "Hello World!"</button>
+```
+
+[← x-id](/directives/id)
+
+[$refs →](/magics/refs)
+
+Code highlighting provided by [Torchlight](https://torchlight.dev/)

offline-docs/alpinejs/magics/watch.md

@@ -0,0 +1,79 @@
+# Alpine.js Documentation - Magics
+
+Magics are special properties that are available inside Alpine expressions. They provide convenient access to common functionality.
+
+## [$watch](/magics/watch)
+
+You can "watch" a component property using the `$watch` magic method. For example:
+
+```
+<div x-data="{ open: false }" x-init="$watch('open', value => console.log(value))">
+
+
+n<button @click="open = ! open">Toggle Open</button>
+
+
+n</div>
+```
+
+In the above example, when the button is pressed and `open` is changed, the provided callback will fire and `console.log` the new value:
+
+You can watch deeply nested properties using "dot" notation
+
+```
+<div x-data="{ foo: { bar: 'baz' }}" x-init="$watch('foo.bar', value => console.log(value))">
+
+
+n<button @click="foo.bar = 'bob'">Toggle Open</button>
+
+
+n</div>
+```
+
+When the `<button>` is pressed, `foo.bar` will be set to "bob", and "bob" will be logged to the console.
+
+### [Getting the "old" value](#getting-the-old-value)
+
+`$watch` keeps track of the previous value of the property being watched, You can access it using the optional second argument to the callback like so:
+
+```
+<div x-data="{ open: false }" x-init="$watch('open', (value, oldValue) => console.log(value, oldValue))">
+
+
+n<button @click="open = ! open">Toggle Open</button>
+
+
+n</div>
+```
+
+### [Deep watching](#deep-watching)
+
+`$watch` automatically watches from changes at any level but you should keep in mind that, when a change is detected, the watcher will return the value of the observed property, not the value of the subproperty that has changed.
+
+```
+<div x-data="{ foo: { bar: 'baz' }}" x-init="$watch('foo', (value, oldValue) => console.log(value, oldValue))">
+
+
+n<button @click="foo.bar = 'bob'">Update</button>
+
+
+n</div>
+```
+
+When the `<button>` is pressed, `foo.bar` will be set to "bob", and "{bar: 'bob'} {bar: 'baz'}" will be logged to the console (new and old value).
+
+> ⚠️ Changing a property of a "watched" object as a side effect of the `$watch` callback will generate an infinite loop and eventually error.
+
+```
+<!-- 🚫 Infinite loop -->
+
+<div x-data="{ foo: { bar: 'baz', bob: 'lob' }}" x-init="$watch('foo', value => foo.bob = foo.bar)">
+
+
+n<button @click="foo.bar = 'bob'">Update</button>
+
+
+n</div>
+```
+
+Code highlighting provided by [Torchlight](https://torchlight.dev/)