Merge branch 'main' into patch-1

.github/ISSUE_TEMPLATE/config.yml

@@ -1,7 +1,7 @@
 blank_issues_enabled: false
 contact_links:
   - name: Bug Report
-    url: https://github.com/alpinejs/alpine/issues/new
+    url: https://github.com/alpinejs/alpine/discussions/new
     about: Submit a GitHub issue
   - name: Feature Request
     url: https://github.com/alpinejs/alpine/discussions/new

packages/alpinejs/src/directives/x-text.js

@@ -2,7 +2,7 @@ import { evaluateLater } from '../evaluator'
 import { directive } from '../directives'
 import { mutateDom } from '../mutation'
 
-directive('text', (el, { expression }, { effect, cleanup }) => {
+directive('text', (el, { expression }, { effect }) => {
     let evaluate = evaluateLater(el, expression)
 
     effect(() => {

packages/docs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@alpinejs/docs",
-    "version": "3.0.0-alpha.0",
+    "version": "3.0.1-revision.3",
     "description": "The documentation for Alpine",
     "author": "Caleb Porzio",
     "license": "MIT"

packages/docs/src/en/advanced/async.md

@@ -20,7 +20,7 @@ function getLabel() {
 
 Because `getLabel` is synchronous, everything works as expected.
 
-Now let's pretend that `getLabel` makes a network request to retrieve the label and can't return one instantaniously (asynchronous). By making `getLabel` an async function, you can call it from Alpine using JavaScript's `await` syntax.
+Now let's pretend that `getLabel` makes a network request to retrieve the label and can't return one instantaneously (asynchronous). By making `getLabel` an async function, you can call it from Alpine using JavaScript's `await` syntax.
 
 ```js
 async function getLabel() {

packages/docs/src/en/advanced/csp.md

@@ -9,7 +9,7 @@ In order for Alpine to be able to execute plain strings from HTML attributes as
 
 > Under the hood, Alpine doesn't actually use eval() itself because it's slow and problematic. Instead it uses Function declarations, which are much better, but still violate "unsafe-eval".
 
-In order to accomodate environments where this CSP is necessary, Alpine offers an alternate build that doesn't violate "unsafe-eval", but has a more restrictive syntax.
+In order to accommodate environments where this CSP is necessary, Alpine offers an alternate build that doesn't violate "unsafe-eval", but has a more restrictive syntax.
 
 <a name="installation"></a>
 ## Installation
@@ -38,9 +38,9 @@ window.Alpine.start()
 <a name="restrictions"></a>
 ## Restrictions
 
-Because Alpine can no longer interpret strings as plain JavaScript, it has to parse and construct JavaScript functions from them manually.
+Since Alpine can no longer interpret strings as plain JavaScript, it has to parse and construct JavaScript functions from them manually.
 
-Because of this limitation, you must use `Alpine.data` to register your `x-data` objects, and must reference properties and methods from it by key only.
+Due to this limitation, you must use `Alpine.data` to register your `x-data` objects, and must reference properties and methods from it by key only.
 
 For example, an inline component like this will not work.
 

packages/docs/src/en/advanced/extending.md

@@ -11,7 +11,7 @@ Alpine has a very open codebase that allows for extension in a number of ways. I
 ## Lifecycle concerns
 Before we dive into each individual API, let's first talk about where in your codebase you should consume these APIs.
 
-Because these APIs have an impact on how Alpine intiailizes the page, they must be registered AFTER Alpine is downloaded and available on the page, but BEFORE it has initialized the page itself.
+Because these APIs have an impact on how Alpine initializes the page, they must be registered AFTER Alpine is downloaded and available on the page, but BEFORE it has initialized the page itself.
 
 There are two different techniques depending on if you are importing Alpine into a bundle, or including it directly via a `<script>` tag. Let's look at them both:
 
@@ -124,7 +124,7 @@ Alpine.directive('log', (el, { expression }, { evaluate }) => {
     // expression === 'message'
 
     console.log(
-        evaluate(el, expression)
+        evaluate(expression)
     )
 })
 ```
@@ -176,7 +176,7 @@ effect(() => {
 })
 ```
 
-By passing in a callback to `effect()`, we are telling Alpine to run the callback immediately, then track any dependancies it uses (`x-data` properties like `message` in our case). Now as soon as one of the dependancies changes, this callback will be re-run. This gives us our "reactivity".
+By passing in a callback to `effect()`, we are telling Alpine to run the callback immediately, then track any dependencies it uses (`x-data` properties like `message` in our case). Now as soon as one of the dependencies changes, this callback will be re-run. This gives us our "reactivity".
 
 You may recognize this functionality from `x-effect`. It is the same mechanism under the hood.
 
@@ -192,7 +192,7 @@ getThingToLog(thingToLog => {
 })
 ```
 
-Now we will call `getThingToLog`, which if you recall is the actual JavaScript function version of the string expression: "message"
+Now we will call `getThingToLog`, which if you recall is the actual JavaScript function version of the string expression: "message".
 
 You might expect `getThingToCall()` to return the result right away, but instead Alpine requires you to pass in a callback to receive the result.
 
@@ -227,7 +227,7 @@ Now if the directive is removed from this element or the element is removed itse
 <a name="custom-magics"></a>
 ## Custom magics
 
-Alpine allows you to register custom "magics" (properties or methods) using `Alpine.magic()`. Any magic you register will be available to all your application's Alpine code with the `$` prefix.
+Alpine allows you to register custom "magic" (properties or methods) using `Alpine.magic()`. Any magic you register will be available to all your application's Alpine code with the `$` prefix.
 
 <a name="method-signature"></a>
 ### Method Signature
@@ -260,12 +260,12 @@ Now the `<span>` tag will contain the current time, resembling something like "1
 
 As you can see `$now` behaves like a static property, but under the hood is actually a getter that evaluates every time the property is accessed.
 
-Because of this, you can impliment magic "functions" by returning a function from the getter.
+Because of this, you can implement magic "functions" by returning a function from the getter.
 
 <a name="magic-functions"></a>
 ### Magic Functions
 
-For example, if we wanted to create a `$clipboard()` magic function that accepts a string to copy to clipboard, we could impliement it like so:
+For example, if we wanted to create a `$clipboard()` magic function that accepts a string to copy to clipboard, we could implement it like so:
 
 ```js
 Alpine.magic('clipboard', () => {
@@ -295,7 +295,7 @@ You can get started quickly with Alpine's official "plugin-blueprint" package. I
 
 Otherwise, let's create a pretend Alpine plugin by hand called `Foo` that includes both a directive (`x-foo`) and a magic (`$foo`).
 
-We'll start with what producing this plugin for consumption as a simple `<script>` tag alongside Alpine, then we'll level it up to a module for importing into a bundle:
+We'll start producing this plugin for consumption as a simple `<script>` tag alongside Alpine, then we'll level it up to a module for importing into a bundle:
 
 <a name="script-include"></a>
 ### Script include

packages/docs/src/en/advanced/reactivity.md

@@ -5,7 +5,7 @@ title: Reactivity
 
 # Reactivity
 
-Alpine is "reactive" in the sense that when you change a peice of data, everything that depends on that data "reacts" automatically to that change.
+Alpine is "reactive" in the sense that when you change a piece of data, everything that depends on that data "reacts" automatically to that change.
 
 Every bit of reactivity that takes place in Alpine, happens because of two very important reactive functions in Alpine's core: `Alpine.reactive()`, and `Alpine.effect()`.
 
@@ -62,7 +62,7 @@ Alpine.effect(() => {
 })
 ```
 
-When this code is firt run, "1" will be logged to the console. Any time `data.count` changes, it's value will be logged to the console again.
+When this code is first run, "1" will be logged to the console. Any time `data.count` changes, it's value will be logged to the console again.
 
 This is the mechanism that unlocks all of the reactivity at the core of Alpine.
 
@@ -98,4 +98,4 @@ button.addEventListener('click', () => {
 
 As you can see, you can make any data reactive, and you can also wrap any functionality in `Alpine.effect`.
 
-This combination unlocks an incredibly powerful programming paradaigm for web development. Run wild and free.
+This combination unlocks an incredibly powerful programming paradigm for web development. Run wild and free.

packages/docs/src/en/alpine-101.md

@@ -12,7 +12,7 @@ Using a text editor, fill the file with these contents:
 ```html
 <html>
 <head>
-    <script defer src="https://something.com/alpine.js"></script>
+    <script defer src="https://unpkg.com/alpinejs@3.0.1/dist/cdn.min.js"></script>
 </head>
 <body>
     <h1 x-data="{ message: 'I ❤️ Alpine' }" x-text="message"></h1>
@@ -22,7 +22,7 @@ Using a text editor, fill the file with these contents:
 
 Open your file in a web browser, if you see `I ❤️ Alpine`, you're ready to rumble!
 
-Now that you're all set up to play around, let's look at three practical examples as a foundation for teaching you the basics of Alpine. By the end of this excercise, you should be more than equipped to start building stuff on your own. Let's goooooo.
+Now that you're all set up to play around, let's look at three practical examples as a foundation for teaching you the basics of Alpine. By the end of this exercise, you should be more than equipped to start building stuff on your own. Let's goooooo.
 
 <!-- START_VERBATIM -->
 <ul class="flex flex-col space-y-2 list-inside !list-decimal">
@@ -153,7 +153,7 @@ The `x-data` and `x-on` directives should be familiar to you from the previous e
 <div ... @click.outside="open = false">Contents...</div>
 ```
 
-You'll notice something new in this example: `.outside`. Many directives in Alpine accept "modifiers" that are chained onto the end of the directive and are seperated by periods.
+You'll notice something new in this example: `.outside`. Many directives in Alpine accept "modifiers" that are chained onto the end of the directive and are separated by periods.
 
 In this case, `.outside` tells Alpine to instead of listening for a click INSIDE the `<div>`, to listen for the click only if it happens OUTSIDE the `<div>`.
 
@@ -262,7 +262,7 @@ The next bit I'd like to draw your attention to is the `items` and `filteredItem
 }
 ```
 
-The `items` property should be self-explanitory. Here we are setting the value of `items` to a JavaScript array of 3 different items (foo, bar, and baz).
+The `items` property should be self-explanatory. Here we are setting the value of `items` to a JavaScript array of 3 different items (foo, bar, and baz).
 
 The interesting part of this snippet is the `filteredItems` property.
 

packages/docs/src/en/directives/bind.md

@@ -50,7 +50,7 @@ In cases like these, if you prefer a less verbose syntax you can use JavaScript'
 
 ```html
 <div :class="show ? '' : 'hidden'">
-<!-- Is equivelant to: -->
+<!-- Is equivalant to: -->
 <div :class="show || 'hidden'">
 ```
 
@@ -58,7 +58,7 @@ The inverse is also available to you. Suppose instead of `open`, we use a variab
 
 ```html
 <div :class="closed ? 'hidden' : ''">
-<!-- Is equivelant to: -->
+<!-- Is equivalant to: -->
 <div :class="closed && 'hidden'">
 ```
 

packages/docs/src/en/directives/cloak.md

@@ -23,7 +23,7 @@ Now, the following example will hide the `<span>` tag until Alpine has set its t
 
 When Alpine loads on the page, it removes all `x-cloak` property from the element, which also removes the `display: none;` applied by CSS, therefore showing the element.
 
-If you'd like to achieve this same behavior, but avoid having to include a global style, you can use the following cool, but admittadly odd trick:
+If you'd like to achieve this same behavior, but avoid having to include a global style, you can use the following cool, but admittedly odd trick:
 
 ```html
 <template x-if="true">

packages/docs/src/en/directives/data.md

@@ -155,7 +155,7 @@ Here's a quick example:
 </div>
 
 <script>
-    document.addEventListener('alpine:intializing', () => {
+    document.addEventListener('alpine:initializing', () => {
         Alpine.data('dropdown', () => ({
             open: false,
 

packages/docs/src/en/directives/effect.md

@@ -5,7 +5,7 @@ title: effect
 
 # `x-effect`
 
-`x-effect` is a useful directive for re-evaluating an expression when one of its dependancies 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.
+`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.
 
 If this definition is confusing for you, that's ok. It's better explained through an example:
 
@@ -17,4 +17,4 @@ If this definition is confusing for you, that's ok. It's better explained throug
 
 When this component is loaded, the `x-effect` expression will be run and "Hello" will be logged into the console.
 
-Because Alpine knows about any property references contained within `x-effect`, when the button is clicked and `label` is changed", the effect will be retriggered and "Hello World!" will be logged to the console.
+Because Alpine knows about any property references contained within `x-effect`, when the button is clicked and `label` is changed", the effect will be re-triggered and "Hello World!" will be logged to the console.

packages/docs/src/en/directives/if.md

@@ -15,4 +15,4 @@ Because of this difference in behavior, `x-if` should not be applied directly to
 </template>
 ```
 
-> Unlike `x-show`, `x-if`, does NOT support tansitioning toggles with `x-transition`.
+> Unlike `x-show`, `x-if`, does NOT support transitioning toggles with `x-transition`.

packages/docs/src/en/directives/model.md

@@ -55,7 +55,7 @@ We can use the same example as above but this time, we'll add a button to change
 
 Now when the `<button>` is clicked, the input element's value will instantly be updated to "changed".
 
-`x-model` works with the following inputy elements:
+`x-model` works with the following input elements:
 
 * `<input type="text">`
 * `<textarea>`
@@ -238,7 +238,7 @@ Color: <span x-text="color"></span>
     <option>Yellow</option>
 </select>
 
-Colors: <span x-text="colors"></span>
+Colors: <span x-text="color"></span>
 ```
 
 <!-- START_VERBATIM -->
@@ -268,6 +268,20 @@ Colors: <span x-text="colors"></span>
 Color: <span x-text="color"></span>
 ```
 
+<!-- START_VERBATIM -->
+<div class="demo">
+    <div x-data="{ color: '' }">
+        <select x-model="color">
+            <template x-for="color in ['Red', 'Orange', 'Yellow']">
+                <option x-text="color"></option>
+            </template>
+        </select>
+
+        <div class="pt-4">Color: <span x-text="color"></span></div>
+    </div>
+</div>
+<!-- END_VERBATIM -->
+
 <a name="modifiers"></a>
 ## Modifiers
 

packages/docs/src/en/directives/on.md

@@ -121,7 +121,7 @@ Alpine offers a number of directive modifiers to customize the behavior of your
 <a name="prevent"></a>
 ### .prevent
 
-`.prevent` is the equivelant of calling `.preventDefault()` inside a listener on the browser event object.
+`.prevent` is the equivalant of calling `.preventDefault()` inside a listener on the browser event object.
 
 ```html
 <form @submit.prevent="console.log('submitted')" action="/foo">
@@ -134,7 +134,7 @@ In the above example, with the `.prevent`, clicking the button will NOT submit t
 <a name="stop"></a>
 ### .stop
 
-Similar to `.prevent`, `.stop` is the equivelant of calling `.stopPropagation()` inside a listener on the browser event object.
+Similar to `.prevent`, `.stop` is the equivalant of calling `.stopPropagation()` inside a listener on the browser event object.
 
 ```html
 <div @click="console.log('I will not get logged')">

packages/docs/src/en/directives/show.md

@@ -26,7 +26,7 @@ When the "Toggle Dropdown" button is clicked, the dropdown will show and hide ac
 <a name="with-transitions"></a>
 ## With transitions
 
-If you want to apply smooth transitions to the `x-show` behavior, you can use it in conjunction with `x-transition`. You can learn more about that directive [here](), but here's a quick example of the same component as above, just with transitions applied.
+If you want to apply smooth transitions to the `x-show` behavior, you can use it in conjunction with `x-transition`. You can learn more about that directive [here](/directives/transition), but here's a quick example of the same component as above, just with transitions applied.
 
 ```html
 <div x-data="{ open: false }">

packages/docs/src/en/essentials/events.md

@@ -52,7 +52,7 @@ For example, if you want to listen for a form submission but prevent the browser
 <form @submit.prevent="...">...</form>
 ```
 
-You can also apply `.stop` to achieve the equivelant of `event.stopPropagation()`.
+You can also apply `.stop` to achieve the equivalent of `event.stopPropagation()`.
 
 <a name="accessing-the-event-object"></a>
 ## Accessing the event object
@@ -60,13 +60,13 @@ You can also apply `.stop` to achieve the equivelant of `event.stopPropagation()
 Sometimes you may want to access the native browser event object inside your own code. To make this easy, Alpine automatically injects an `$event` magic variable:
 
 ```html
-<button @click="$event.target.delete()">Remove Me</button>
+<button @click="$event.target.remove()">Remove Me</button>
 ```
 
 <a name="dispatching-custom-events"></a>
 ## Dispatching custom events
 
-In addition to listening for browser events, you can dispatch them as well. This is extremely useful for communicating with other Alpine components or event in tools outside of Alpine itself.
+In addition to listening for browser events, you can dispatch them as well. This is extremely useful for communicating with other Alpine components or triggering events in tools outside of Alpine itself.
 
 Alpine exposes a magic helper called `$dispatch` for this:
 

packages/docs/src/en/essentials/lifecycle.md

@@ -31,7 +31,7 @@ Alpine.data('dropdown', () => ({
 <a name="after-a-state-change"></a>
 ## After a state change
 
-Alpine allows you to execute code when a peice of data (state) changes. It offers two different APIs for such a task: `$watch` and `x-effect`.
+Alpine allows you to execute code when a piece of data (state) changes. It offers two different APIs for such a task: `$watch` and `x-effect`.
 
 <a name="watch"></a>
 ### `$watch`
@@ -40,16 +40,16 @@ Alpine allows you to execute code when a peice of data (state) changes. It offer
 <div x-data="{ open: false }" x-init="$watch('open', value => console.log(value))">
 ```
 
-As you can see above, `$watch` allows you to hook into data changes using a dot-notation key. When that peice of data changes, Alpine will call the passed callback and pass it the new value. along with the old value before the change.
+As you can see above, `$watch` allows you to hook into data changes using a dot-notation key. When that piece of data changes, Alpine will call the passed callback and pass it the new value. along with the old value before the change.
 
 [→ Read more about $watch](/magics/watch)
 
 <a name="x-effect"></a>
 ### `x-effect`
 
-`x-effect` uses the same mechanism under the hood as `x-watch` but has very different usage.
+`x-effect` uses the same mechanism under the hood as `$watch` but has very different usage.
 
-Instead of specifying which data key you wish to watch, `x-effect` will call the provided code and intelligently look for any Alpine data used within it. Now when one of those peices of data changes, the `x-effect` expression will be re-run.
+Instead of specifying which data key you wish to watch, `x-effect` will call the provided code and intelligently look for any Alpine data used within it. Now when one of those pieces of data changes, the `x-effect` expression will be re-run.
 
 Here's the same bit of code from the `$watch` example rewritten using `x-effect`:
 

packages/docs/src/en/globals/alpine-data.md

@@ -60,7 +60,7 @@ export default function () => ({
 <a name="init-functions"></a>
 ## Init functions
 
-If your component contains an `init()` method, Livewire will automatically execute it before it renders the component. For example:
+If your component contains an `init()` method, Alpine will automatically execute it before it renders the component. For example:
 
 ```js
 Alpine.data('dropdown', () => ({

packages/docs/src/en/magics/dispatch.md

@@ -86,7 +86,7 @@ You can also take advantage of the previous technique to make your components ta
 <div x-data>
     <button @click="$dispatch('set-title', 'Hello World!')">...</button>
 </div>
-<!-- When clicked, will console.log "Hello World!". -->
+<!-- When clicked, the content of the h1 will set to "Hello World!". -->
 ```
 
 <a name="dispatching-to-x-model"></a>

packages/docs/src/en/magics/el.md

@@ -9,7 +9,7 @@ title: el
 `$el` is a magic property that can be used to retrieve the current DOM node.
 
 ```html
-<button @click="$el.innerHTML = 'foo'">Replace me with "foo"</button>
+<button @click="$el.innerHTML = 'Hello World!'">Replace me with "Hello World!"</button>
 ```
 
 <!-- START_VERBATIM -->

packages/docs/src/en/upgrade-guide.md

@@ -182,7 +182,7 @@ Alpine V2 observes a return value of `false` as a desire to run `preventDefault`
 
 ```html
 <!-- 🚫 Before -->
-<div x-data="{ blockInput() { return false }">
+<div x-data="{ blockInput() { return false } }">
     <input type="text" @input="blockInput()">
 </div>
 
@@ -230,7 +230,7 @@ One of Alpine's stories for re-using functionality is abstracting Alpine directi
             },
         }
     }
-</template>
+</script>
 ```
 
 [→ Read more about binding directives using x-bind](/directives/bind#bind-directives)
@@ -290,16 +290,18 @@ However, using V3's new custom directive API, it's trivial to reintroduce this f
             let getHtml = evaluateLater(expression)
 
             effect(() => {
-                el.innerHTML = getHTML()
+                getHTML(html => {
+                    el.innerHTML = html
+                })
             })
         })
     })
 </script>
 ```
 
-## Depricated APIs
+## Deprecated APIs
 
-The following 2 APIs will still work in V3, but are considered depricated and are likely to be removed at some point in the future.
+The following 2 APIs will still work in V3, but are considered deprecated and are likely to be removed at some point in the future.
 
 <a name="away-replace-with-outside"></a>
 ### Event listener modifier `.away` should be replaced with `.outside`