@alpinejs/docs 3.4.2-revision.2 → 3.5.2-revision.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@alpinejs/docs",
-    "version": "3.4.2-revision.2",
+    "version": "3.5.2-revision.1",
     "description": "The documentation for Alpine",
     "author": "Caleb Porzio",
     "license": "MIT"

package/src/en/directives/bind.md

@@ -3,7 +3,7 @@ order: 4
 title: bind
 ---
 
-# `x-bind`
+# x-bind
 
 `x-bind` allows you to set HTML attributes on elements based on the result of JavaScript expressions.
 
@@ -124,6 +124,14 @@ Just like the class objects, this syntax is entirely optional. Only use it if it
 <div style="color: red; display: flex;" ...>
 ```
 
+Conditional inline styling is possible using expressions just like with x-bind:class. Short circuit operators can be used here as well by using a styles object as the second operand.
+```alpine
+<div x-bind:style="true && { color: 'red' }">
+
+<!-- Will render: -->
+<div style="color: red;">
+```
+
 One advantage of this approach is being able to mix it in with existing styles on an element:
 
 ```alpine

package/src/en/directives/cloak.md

@@ -3,7 +3,7 @@ order: 12
 title: cloak
 ---
 
-# `x-cloak`
+# x-cloak
 
 Sometimes, when you're using AlpineJS for a part of your template, there is a "blip" where you might see your uninitialized template after the page loads, but before Alpine loads.
 

package/src/en/directives/data.md

@@ -3,7 +3,7 @@ order: 1
 title: data
 ---
 
-# `x-data`
+# x-data
 
 Everything in Alpine starts with the `x-data` directive.
 

package/src/en/directives/effect.md

@@ -3,7 +3,7 @@ order: 11
 title: effect
 ---
 
-# `x-effect`
+# x-effect
 
 `x-effect` is a useful directive for re-evaluating an expression when one of its dependencies change. You can think of it as a watcher where you don't have to specify what property to watch, it will watch all properties used within it.
 

package/src/en/directives/for.md

@@ -3,7 +3,7 @@ order: 8
 title: for
 ---
 
-# `x-for`
+# x-for
 
 Alpine's `x-for` directive allows you to create DOM elements by iterating through a list. Here's a simple example of using it to create a list of colors based on an array.
 

package/src/en/directives/html.md

@@ -3,7 +3,7 @@ order: 7
 title: html
 ---
 
-# `x-html`
+# x-html
 
 `x-html` sets the "innerHTML" property of an element to the result of a given expression.
 

package/src/en/directives/if.md

@@ -3,7 +3,7 @@ order: 16
 title: if
 ---
 
-# `x-if`
+# x-if
 
 `x-if` is used for toggling elements on the page, similarly to `x-show`, however it completely adds and removes the element it's applied to rather than just changing its CSS display property to "none".
 

package/src/en/directives/ignore.md

@@ -3,7 +3,7 @@ order: 11
 title: ignore
 ---
 
-# `x-ignore`
+# x-ignore
 
 By default, Alpine will crawl and initialize the entire DOM tree of an element containing `x-init` or `x-data`.
 

package/src/en/directives/init.md

@@ -3,7 +3,7 @@ order: 2
 title: init
 ---
 
-# `x-init`
+# x-init
 
 The `x-init` directive allows you to hook into the initialization phase of any element in Alpine.
 

package/src/en/directives/model.md

@@ -3,7 +3,7 @@ order: 7
 title: model
 ---
 
-# `x-model`
+# x-model
 
 `x-model` allows you to bind the value of an input element to Alpine data.
 
@@ -336,3 +336,39 @@ The default throttle interval is 250 milliseconds, you can easily customize this
 ```alpine
 <input type="text" x-model.throttle.500ms="search">
 ```
+
+<a name="programmatic access"></a>
+## Programmatic access
+
+Alpine exposes under-the-hood utilities for getting and setting properties bound with `x-model`. This is useful for complex Alpine utilities that may want to override the default x-model behavior, or instances where you want to allow `x-model` on a non-input element.
+
+You can access these utilities through a property called `_x_model` on the `x-model`ed element. `_x_model` has two methods to get and set the bound property:
+
+* `el._x_model.get()` (returns the value of the bound property)
+* `el._x_model.set()` (sets the value of the bound property)
+
+```alpine
+<div x-data="{ username: 'calebporzio' }">
+    <div x-ref="div" x-model="username"></div>
+
+    <button @click="$refs.div._x_model.set('phantomatrix')">
+        Change username to: 'phantomatrix'
+    </button>
+
+    <span x-text="$refs.div._x_model.get()"></span>
+</div>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+    <div x-data="{ username: 'calebporzio' }">
+        <div x-ref="div" x-model="username"></div>
+
+        <button @click="$refs.div._x_model.set('phantomatrix')">
+            Change username to: 'phantomatrix'
+        </button>
+
+        <span x-text="$refs.div._x_model.get()"></span>
+    </div>
+</div>
+<!-- END_VERBATIM -->

package/src/en/directives/on.md

@@ -3,7 +3,7 @@ order: 5
 title: on
 ---
 
-# `x-on`
+# x-on
 
 `x-on` allows you to easily run code on dispatched DOM events.
 
@@ -13,6 +13,8 @@ Here's an example of simple button that shows an alert when clicked.
 <button x-on:click="alert('Hello World!')">Say Hi</button>
 ```
 
+> `x-on` can only listen for events with lower case names, as HTML attribtes are case-insensitive. Writing `x-on:CLICK` will listen for an event named `click`. If you need to listen for a custom event with a camelCase name, you can use the [`.camel` helper](#camel) to work around this limitation. Alternatively, you can use  [`x-bind`](/directives/bind.md#bind-directives) to attach an `x-on` directive to an element in javascript code (where case will be preserved).
+
 <a name="shorthand-syntax"></a>
 ## Shorthand syntax
 
@@ -262,6 +264,19 @@ Sometimes you may want to listen for camelCased events such as `customEvent` in
 
 By adding `.camel` in the above example, Alpine is now listening for `customEvent` instead of `custom-event`.
 
+<a name="dot"></a>
+### .dot
+
+```alpine
+<div @custom-event.dot="handleCustomEvent">
+    ...
+</div>
+```
+
+Similar to the `.camelCase` modifier there may be situations where you want to listen for events that have dots in their name (like `custom.event`). Since dots within the event name are reserved by Alpine you need to write them with dashes and add the `.dot` modifier.
+
+In the code example above `custom-event.dot` will correspond to the event name `custom.event`.
+
 <a name="passive"></a>
 ### .passive
 

package/src/en/directives/ref.md

@@ -3,7 +3,7 @@ order: 11
 title: ref
 ---
 
-# `x-ref`
+# x-ref
 
 `x-ref` in combination with `$refs` is a useful utility for easily accessing DOM elements directly. It's most useful as a replacement for APIs like `getElementById` and `querySelector`.
 

package/src/en/directives/show.md

@@ -3,7 +3,7 @@ order: 3
 title: show
 ---
 
-# `x-show`
+# x-show
 
 `x-show` is one of the most useful and powerful directives in Alpine. It provides an expressive way to show and hide DOM elements.
 

package/src/en/directives/text.md

@@ -3,7 +3,7 @@ order: 6
 title: text
 ---
 
-# `x-text`
+# x-text
 
 `x-text` sets the text content of an element to the result of a given expression.
 

package/src/en/directives/transition.md

@@ -3,14 +3,14 @@ order: 10
 title: transition
 ---
 
-# `x-transition`
+# x-transition
 
 Alpine provides a robust transitions utility out of the box. With a few `x-transition` directives, you can create smooth transitions between when an element is shown or hidden.
 
 There are two primary ways to handle transitions in Alpine:
 
-* [The Transition Helper]()
-* [Applying CSS Classes]()
+* [The Transition Helper](#the-transition-helper)
+* [Applying CSS Classes](#applying-css-classes)
 
 <a name="the-transition-helper"></a>
 ## The transition helper

package/src/en/essentials/installation.md

@@ -33,7 +33,7 @@ This is by far the simplest way to get started with Alpine. Include the followin
 Notice the `@3.x.x` in the provided CDN link. This will pull the latest version of Alpine version 3. For stability in production, it's recommended that you hardcode the latest version in the CDN link.
 
 ```alpine
-<script defer src="https://unpkg.com/alpinejs@3.4.2/dist/cdn.min.js"></script>
+<script defer src="https://unpkg.com/alpinejs@3.5.2/dist/cdn.min.js"></script>
 ```
 
 That's it! Alpine is now available for use inside your page.

package/src/en/essentials/lifecycle.md

@@ -70,7 +70,7 @@ The two main behavioral differences with this approach are:
 ## Alpine initialization
 
 <a name="alpine-initializing"></a>
-### `Alpine.initializing`
+### `alpine:init`
 
 Ensuring a bit of code executes after Alpine is loaded, but BEFORE it initializes itself on the page is a necessary task.
 
@@ -85,7 +85,7 @@ document.addEventListener('alpine:init', () => {
 ```
 
 <a name="alpine-initialized"></a>
-### `Alpine.initialized`
+### `alpine:initialized`
 
 Alpine also offers a hook that you can use to execute code After it's done initializing called `alpine:initialized`:
 

package/src/en/magics/data.md

@@ -0,0 +1,45 @@
+---
+order: 8
+prefix: $
+title: data
+---
+
+# $data
+
+`$data` is a magic property that gives you access to the current Alpine data scope (generally provided by `x-data`).
+
+Most of the time, you can just access Alpine data within expressions directly. for example `x-data="{ message: 'Hello Caleb!' }"` will allow you to do things like `x-text="message"`.
+
+However, sometimes it is helpful to have an actual object that encapsulates all scope that you can pass around to other functions:
+
+```alpine
+<div x-data="{ greeting: 'Hello' }">
+    <div x-data="{ name: 'Caleb' }">
+        <button @click="sayHello($data)">Say Hello</button>
+    </div>
+</div>
+
+<script>
+    function sayHello({ greeting, name }) {
+        alert(greeting + ' ' + name + '!')
+    }
+</script>
+```
+
+<!-- START_VERBATIM -->
+<div x-data="{ greeting: 'Hello' }" class="demo">
+    <div x-data="{ name: 'Caleb' }">
+        <button @click="sayHello($data)">Say Hello</button>
+    </div>
+</div>
+
+<script>
+    function sayHello({ greeting, name }) {
+        alert(greeting + ' ' + name + '!')
+    }
+</script>
+<!-- END_VERBATIM -->
+
+Now when the button is pressed, the browser will alert `Hello Caleb!` because it was passed a data object that contained all the Alpine scope of the expression that called it (`@click="..."`).
+
+Most applications won't need this magic property, but it can be very helpful for deeper, more complicated Alpine utilities.

package/src/en/magics/dispatch.md

@@ -3,7 +3,7 @@ order: 5
 title: dispatch
 ---
 
-# `$dispatch`
+# $dispatch
 
 `$dispatch` is a helpful shortcut for dispatching browser events.
 
@@ -56,17 +56,17 @@ Notice that, because of [event bubbling](https://en.wikipedia.org/wiki/Event_bub
 <!-- 🚫 Won't work -->
 <div x-data>
     <span @notify="..."></span>
-    <button @click="$dispatch('notify')">
-<div>
+    <button @click="$dispatch('notify')">Notify</button>
+</div>
 
 <!-- ✅ Will work (because of .window) -->
 <div x-data>
     <span @notify.window="..."></span>
-    <button @click="$dispatch('notify')">
-<div>
+    <button @click="$dispatch('notify')">Notify</button>
+</div>
 ```
 
-> The first example won't work because when `custom-event` is dispatched, it'll propagate to its common ancestor, the `div`, not it's 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.
+> The first example won't work because when `custom-event` 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.
 
 <a name="dispatching-to-components"></a>
 ## Dispatching to other components
@@ -84,7 +84,7 @@ You can also take advantage of the previous technique to make your components ta
 </div>
 
 <div x-data>
-    <button @click="$dispatch('set-title', 'Hello World!')">...</button>
+    <button @click="$dispatch('set-title', 'Hello World!')">Click me</button>
 </div>
 <!-- When clicked, the content of the h1 will set to "Hello World!". -->
 ```
@@ -97,10 +97,10 @@ You can also use `$dispatch()` to trigger data updates for `x-model` data bindin
 ```alpine
 <div x-data="{ title: 'Hello' }">
     <span x-model="title">
-        <button @click="$dispatch('input', 'Hello World!')">
+        <button @click="$dispatch('input', 'Hello World!')">Click me</button>
         <!-- After the button is pressed, `x-model` will catch the bubbling "input" event, and update title. -->
     </span>
 </div>
 ```
 
-This opens up the door for making custom input components who's value can be set via `x-model`.
+This opens up the door for making custom input components whose value can be set via `x-model`.

package/src/en/magics/el.md

@@ -4,7 +4,7 @@ prefix: $
 title: el
 ---
 
-# `$el`
+# $el
 
 `$el` is a magic property that can be used to retrieve the current DOM node.
 

package/src/en/magics/nextTick.md

@@ -4,7 +4,7 @@ prefix: $
 title: nextTick
 ---
 
-# `$nextTick`
+# $nextTick
 
 `$nextTick` is a magic property that allows you to only execute a given expression AFTER Alpine has made its reactive DOM updates. This is useful for times you want to interact with the DOM state AFTER it's reflected any data updates you've made.
 

package/src/en/magics/refs.md

@@ -4,7 +4,7 @@ prefix: $
 title: refs
 ---
 
-# `$refs`
+# $refs
 
 `$refs` is a magic property that can be used to retrieve DOM elements marked with `x-ref` inside the component. This is useful when you need to manually manipulate DOM elements. It's often used as a more succinct, scoped, alternative to `document.querySelector`.
 

package/src/en/magics/root.md

@@ -4,7 +4,7 @@ prefix: $
 title: root
 ---
 
-# `$root`
+# $root
 
 `$root` is a magic property that can be used to retrieve the root element of any Alpine component. In other words the closest element up the DOM tree that contains `x-data`.
 

package/src/en/magics/store.md

@@ -4,7 +4,7 @@ prefix: $
 title: store
 ---
 
-# `$store`
+# $store
 
 You can use `$store` to conveniently access global Alpine stores registered using [`Alpine.store(...)`](#). For example:
 

package/src/en/magics/watch.md

@@ -3,7 +3,7 @@ order: 4
 title: watch
 ---
 
-# `$watch`
+# $watch
 
 You can "watch" a component property using the `$watch` magic method. For example:
 

package/src/en/plugins/intersect.md

@@ -104,3 +104,25 @@ Sometimes it's useful to evaluate an expression only the first time an element e
 ```alpine
 <div x-intersect.once="shown = true">...</div>
 ```
+
+<a name="half"></a>
+### .half
+
+Evaluates the expression once the intersection threshold exceeds `0.5`. 
+
+Useful for elements where it's important to show at least part of the element.
+
+```alpine
+<div x-intersect.half="shown = true">...</div> // when `0.5` of the element is in the viewport
+```
+
+<a name="full"></a>
+### .full
+
+Evaluates the expression once the intersection threshold exceeds `0.99`. 
+
+Useful for elements where it's important to show the whole element.
+
+```alpine
+<div x-intersect.full="shown = true">...</div> // when `0.99` of the element is in the viewport
+```

package/src/en/plugins/morph.md

@@ -0,0 +1,251 @@
+---
+order: 5
+title: Morph
+description: Morph an element into the provided HTML
+graph_image: https://alpinejs.dev/social_morph.jpg
+---
+
+# Morph Plugin
+
+Alpine's Morph plugin allows you to "morph" an element on the page into the provided HTML template, all while preserving any browser or Alpine state within the "morphed" element.
+
+This is useful for updating HTML from a server request without loosing Alpine's on-page state. A utility like this is at the core of full-stack frameworks like [Laravel Livewire](https://laravel-livewire.com/) and [Phoenix LiveView](https://dockyard.com/blog/2018/12/12/phoenix-liveview-interactive-real-time-apps-no-need-to-write-javascript).
+
+The best way to understand its purpose is with the following interactive visualization. Give it a try!
+
+<!-- START_VERBATIM -->
+<div x-data="{ slide: 1 }" class="border rounded">
+    <div>
+        <img :src="'/img/morphs/morph'+slide+'.png'">
+    </div>
+
+    <div class="flex w-full justify-between" style="padding-bottom: 1rem">
+        <div class="w-1/2 px-4">
+            <button @click="slide = (slide === 1) ? 13 : slide - 1" class="w-full bg-brand rounded-full text-center py-3 font-bold text-white">Previous</button>
+        </div>
+        <div class="w-1/2 px-4">
+            <button @click="slide = (slide % 13) + 1" class="w-full bg-brand rounded-full text-center py-3 font-bold text-white">Next</button>
+        </div>
+    </div>
+</div>
+<!-- END_VERBATIM -->
+
+<a name="installation"></a>
+## Installation
+
+You can use this plugin by either including it from a `<script>` tag or installing it via NPM:
+
+### Via CDN
+
+You can include the CDN build of this plugin as a `<script>` tag, just make sure to include it BEFORE Alpine's core JS file.
+
+```alpine
+<!-- Alpine Plugins -->
+<script defer src="https://unpkg.com/@alpinejs/morph@3.x.x/dist/cdn.min.js"></script>
+
+<!-- Alpine Core -->
+<script defer src="https://unpkg.com/alpinejs@3.x.x/dist/cdn.min.js"></script>
+```
+
+### Via NPM
+
+You can install Morph from NPM for use inside your bundle like so:
+
+```shell
+npm install @alpinejs/morph
+```
+
+Then initialize it from your bundle:
+
+```js
+import Alpine from 'alpinejs'
+import morph from '@alpinejs/morph'
+
+Alpine.plugin(morph)
+
+...
+```
+
+<a name="alpine-morph"></a>
+## Alpine.morph()
+
+The `Alpine.morph(el, newHtml)` allows you to imperatively morph a dom node based on passed in HTML. It accepts the following parameters:
+
+| Parameter | Description |
+| ---       | --- |
+| `el`      | A DOM element on the page. |
+| `newHtml` | A string of HTML to use as the template to morph the dom element into. |
+| `options` (optional) | An options object used mainly for [injecting lifecycle hooks](#lifecycle-hooks). |
+
+Here's an example of using `Alpine.morph()` to update an Alpine component with new HTML: (In real apps, this new HTML would likely be coming from the server)
+
+```alpine
+<div x-data="{ message: 'Change me, then press the button!' }">
+    <input type="text" x-model="message"> 
+    <span x-text="message"></span> 
+</div>
+
+<button>Run Morph</button>
+
+<script>
+    document.querySelector('button').addEventListener('click', () => {
+        let el = document.querySelector('div')
+
+        Alpine.morph(el, `
+            <div x-data="{ message: 'Change me, then press the button!' }">
+                <h2>See how new elements have been added</h2>
+                
+                <input type="text" x-model="message"> 
+                <span x-text="message"></span> 
+
+                <h2>but the state of this component hasn't changed? Magical.</h2>
+            </div>
+        `)
+    })
+</script>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+    <div x-data="{ message: 'Change me, then press the button!' }" id="morph-demo-1" class="space-y-2">
+        <input type="text" x-model="message" class="w-full">
+        <span x-text="message"></span> 
+    </div>
+    
+    <button id="morph-button-1" class="mt-4">Run Morph</button>
+</div>
+
+<script>
+    document.querySelector('#morph-button-1').addEventListener('click', () => {
+        let el = document.querySelector('#morph-demo-1')
+
+        Alpine.morph(el, `
+            <div x-data="{ message: 'Change me, then press the button!' }" id="morph-demo-1" class="space-y-2">
+                <h4>See how new elements have been added</h4>
+                <input type="text" x-model="message" class="w-full"> 
+                <span x-text="message"></span> 
+                <h4>but the state of this component hasn't changed? Magical.</h4>
+            </div>
+        `)
+    })
+</script>
+<!-- END_VERBATIM -->
+
+<a name="lifecycle-hooks"></a>
+### Lifecycle Hooks
+
+The "Morph" plugin works by comparing two DOM trees, the live element, and the passed in HTML.
+
+Morph walks both trees simultaneusly and compares each node and its children. If it finds differences, it "patches" (changes) the current DOM tree to match the passed in HTML's tree.
+
+While the default algorithm is very capable, there are cases where you may want to hook into its lifecycle and observe or change its behavior as it's happening.
+
+Before we jump into the available Lifecycle hooks themselves, let's first list out all the potential parameters they receive and explain what each one is:
+
+| Parameter | Description |
+| ---       | --- |
+| `el` | This is always the actual, current, DOM element on the page that will be "patched" (changed by Morph). |
+| `toEl` | This is a "template element". It's a temporary element representing what the live `el` will be patched to. It will never actually live on the page and should only be used for reference purposes. |
+| `childrenOnly()` | This is a function that can be called inside the hook to tell Morph to skip the current element and only "patch" its children. |
+| `skip()` | A function that when called within the hook will "skip" comparing/patching itself and the children of the current element. |
+
+Here are the available lifecycle hooks (passed in as the third parameter to `Alpine.morph(..., options)`):
+
+| Option | Description |
+| ---       | --- |
+| `updating(el, toEl, childrenOnly, skip)` | Called before patching the `el` with the comparison `toEl`.  |
+| `updated(el, toEl)` | Called after Morph has patched `el`. |
+| `removing(el, skip)` | Called before Morph removes an element from the live DOM. |
+| `removed(el)` | Called after Morph has removed an element from the live DOM. |
+| `adding(el, sip)` | Called before adding a new element. |
+| `added(el)` | Called after adding a new element to the live DOM tree. |
+| `key(el)` | A re-usable function to determine how Morph "keys" elements in the tree before comparing/patching. [More on that here](#keys) |
+| `lookahead` | A boolean value telling Morph to enable an extra feature in its algorithm that "looks ahead" to make sure a DOM element that's about to be removed should instead just be "moved" to a later sibling. |
+
+Here is code of all these lifecycle hooks for a more concrete reference:
+
+```js
+Alpine.morph(el, newHtml, {
+    updating(el, toEl, childrenOnly, skip) {
+        //
+    },
+
+    updated(el, toEl) {
+        //
+    },
+
+    removing(el, skip) {
+        //
+    },
+
+    removed(el) {
+        //
+    },
+
+    adding(el, skip) {
+        //
+    },
+
+    added(el) {
+        //
+    },
+
+    key(el) {
+        // By default Alpine uses the `key=""` HTML attribute.
+        return el.id
+    },
+
+    lookahead: true, // Default: false
+})
+```
+
+<a name="keys"></a>
+### Keys
+
+Dom-diffing utilities like Morph try their best to accurately "morph" the original DOM into the new HTML. However, there are cases where it's impossible to determine if an element should be just changed, or replaced completely.
+
+Because of this limitation, Morph has a "key" system that allows developers to "force" preserving certain elements rather than replacing them.
+
+The most common use-case for them is a list of siblings within a loop. Below is an example of why keys are necessary sometimes:
+
+```html
+<!-- "Live" Dom on the page: -->
+<ul>
+    <li>Mark</li>
+    <li>Tom</li>
+    <li>Travis</li>
+</ul>
+
+<!-- New HTML to "morph to": -->
+<ul>
+    <li>Travis</li>
+    <li>Mark</li>
+    <li>Tom</li>
+</ul>
+```
+
+Given the above situation, Morph has no way to know that the "Travis" node has been moved in the DOM tree. It just thinks that "Mark" has been changed to "Travis" and "Travis" changed to "Tom".
+
+This is not what we actually want, we want Morph to preserve the original elements and instead of changing them, MOVE them within the `<ul>`.
+
+By adding keys to each node, we can accomplish this like so:
+
+```html
+<!-- "Live" Dom on the page: -->
+<ul>
+    <li key="1">Mark</li>
+    <li key="2">Tom</li>
+    <li key="3">Travis</li>
+</ul>
+
+<!-- New HTML to "morph to": -->
+<ul>
+    <li key="3">Travis</li>
+    <li key="1">Mark</li>
+    <li key="2">Tom</li>
+</ul>
+```
+
+Now that there are "keys" on the `<li>`s, Morph will match them in both trees and move them accordingly.
+
+You can configure what Morph considers a "key" with the `key:` configutation option. [More on that here](#lifecycle-hooks)

package/src/en/plugins/persist.md

@@ -194,3 +194,14 @@ Alpine.data('dropdown', function () {
     }
 })
 ```
+
+<a name="using-alpine-persist-global"></a>
+## Using the Alpine.$persist global
+
+`Alpine.$persist` is exposed globally so it can be used outside of `x-data` contexts. This is useful to persist data from other sources such as `Alpine.store`.
+
+```js
+Alpine.store('darkMode', {
+    on: Alpine.$persist(true).as('darkMode_on')
+});
+```

package/src/en/plugins/trap.md

@@ -178,3 +178,76 @@ Here is nesting in action:
     </div>
 </div>
 <!-- END_VERBATIM -->
+
+<a name="modifiers"></a>
+## Modifiers
+
+<a name="inert"></a>
+### .inert
+
+When building things like dialogs/modals, it's recommended to hide all the other elements on the page from screenreaders when trapping focus.
+
+By adding `.inert` to `x-trap`, when focus is trapped, all other elements on the page will receive `aria-hidden="true"` attributes, and when focus trapping is disabled, those attributes will also be removed.
+
+```alpine
+<!-- When `open` is `false`: -->
+<body x-data="{ open: false }">
+    <div x-trap.inert="open" ...>
+        ...
+    </div>
+
+    <div>
+        ...
+    </div>
+</body>
+
+<!-- When `open` is `true`: -->
+<body x-data="{ open: true }">
+    <div x-trap.inert="open" ...>
+        ...
+    </div>
+
+    <div aria-hidden="true">
+        ...
+    </div>
+</body>
+```
+
+<a name="noscroll"></a>
+### .noscroll
+
+When building dialogs/modals with Alpine, it's recommended that you disable scrollling for the surrounding content when the dialog is open.
+
+`x-trap` allows you to do this automatically with the `.noscroll` modifiers.
+
+By adding `.noscroll`, Alpine will remove the scrollbar from the page and block users from scrolling down the page while a dialog is open.
+
+For example:
+
+```alpine
+<div x-data="{ open: false }">
+    <button>Open Dialog</button>
+
+    <div x-show="open" x-trap.noscroll="open">
+        Dialog Contents
+
+        <button @click="open = false">Close Dialog</button>
+    </div>
+</div>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+    <div x-data="{ open: false }">
+        <button @click="open = true">Open Dialog</button>
+
+        <div x-show="open" x-trap.noscroll="open" class="border mt-4 p-4">
+            <div class="mb-4 text-bold">Dialog Contents</div>
+
+            <p class="mb-4 text-gray-600 text-sm">Notice how you can no longer scroll on this page while this dialog is open.</p>
+
+            <button class="mt-4" @click="open = false">Close Dialog</button>
+        </div>
+    </div>
+</div>
+<!-- END_VERBATIM -->

package/src/en/upgrade-guide.md

@@ -40,7 +40,7 @@ Upgrading from Alpine V2 to V3 should be fairly painless. In many cases, NOTHING
 <a name="el-no-longer-root"></a>
 ### `$el` is now always the current element
 
-`$el` now always represents the element that an expression was executed on, not the root element of the component. This will replace most usages of `x-ref` and in the cases where you still want to access the root of a component, you can do so using `x-ref`. For example:
+`$el` now always represents the element that an expression was executed on, not the root element of the component. This will replace most usages of `x-ref` and in the cases where you still want to access the root of a component, you can do so using `$root`. For example:
 
 ```alpine
 <!-- 🚫 Before -->
@@ -50,30 +50,15 @@ Upgrading from Alpine V2 to V3 should be fairly painless. In many cases, NOTHING
 </div>
 
 <!-- ✅ After -->
-<div x-data x-ref="root">
-    <button @click="console.log($refs.root)"></button>
+<div x-data>
+    <button @click="console.log($root)"></button>
 </div>
 ```
 
-For a smoother upgrade experience, you can optionally replace all instances of `$el` with a custom magic called `$root`, then add the following code to your site to mimic the behavior:
-
-```alpine
-<script>
-    document.addEventListener('alpine:init', () => {
-        Alpine.magic('root', el => {
-            let closestRootEl = (node) => {
-                if (node.hasAttribute('x-data')) return node
-
-                return closestRootEl(node.parentNode)
-            }
-
-            return closestRootEl(el)
-        })
-    })
-</script>
-```
+For a smoother upgrade experience, you can replace all instances of `$el` with a custom magic called `$root`.
 
-[→ Read more about $el in V3](/magics/el)
+[→ Read more about $el in V3](/magics/el)  
+[→ Read more about $root in V3](/magics/root)
 
 <a name="auto-init"></a>
 ### Automatically evaluate `init()` functions defined on data object