@alpinejs/docs 3.9.6-revision.1 → 3.10.0-revision.1

package/package.json

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

package/src/en/directives/bind.md

@@ -159,7 +159,7 @@ And like most expressions in Alpine, you can always use the result of a JavaScri
 
 `x-bind` allows you to bind an object of different directives and attributes to an element.
 
-The object keys can be anything you would normally write as an attribute name in Alpine. This includes Alpine directives and modifiers, but also plain HTML attributes. The object values are either plain strings, or in the case of dynamic Alpine directoves, callbacks to be evaluated by Alpine.
+The object keys can be anything you would normally write as an attribute name in Alpine. This includes Alpine directives and modifiers, but also plain HTML attributes. The object values are either plain strings, or in the case of dynamic Alpine directives, callbacks to be evaluated by Alpine.
 
 ```alpine
 <div x-data="dropdown()">
@@ -174,6 +174,7 @@ The object keys can be anything you would normally write as an attribute name in
             open: false,
 
             trigger: {
+                ['x-ref']: 'trigger',
                 ['@click']() {
                     this.open = true
                 },

package/src/en/directives/for.md

@@ -33,7 +33,7 @@ There are two rules worth noting about `x-for`:
 <a name="keys"></a>
 ## Keys
 
-It is important to specify keys for each `x-for` iteration if you are going to be re-ordering items. Without dynamic keys, Alpine may have a hard time keeping track of what re-orders and will cause odd side-effects.
+It is important to specify unique keys for each `x-for` iteration if you are going to be re-ordering items. Without dynamic keys, Alpine may have a hard time keeping track of what re-orders and will cause odd side-effects.
 
 ```alpine
 <ul x-data="{ colors: [

package/src/en/directives/model.md

@@ -288,7 +288,7 @@ Color: <span x-text="color"></span>
 <a name="lazy"></a>
 ### `.lazy`
 
-On text inputs, by default, `x-model` updates the property on every key-stroke. By adding the `.lazy` modifier, you can force an `x-model` input to only update the property when user focuses away from the input element.
+On text inputs, by default, `x-model` updates the property on every keystroke. By adding the `.lazy` modifier, you can force an `x-model` input to only update the property when user focuses away from the input element.
 
 This is handy for things like real-time form-validation where you might not want to show an input validation error until the user "tabs" away from a field.
 

package/src/en/directives/on.md

@@ -89,6 +89,7 @@ For easy reference, here is a list of common keys you may want to listen for.
 | `.caps-lock`                | Caps Lock                   |
 | `.equal`                    | Equal, `=`                  |
 | `.period`                   | Period, `.`                 |
+| `.slash`                    | Foward Slash, `/`           |
 
 <a name="custom-events"></a>
 ## Custom events
@@ -165,7 +166,7 @@ In the above example, clicking the button WON'T log the message. This is because
 
 In the above example, after showing the dropdown contents by clicking the "Toggle" button, you can close the dropdown by clicking anywhere on the page outside the content.
 
-This is because `.outside` is listening for clicks that DONT originate from the element it's registered on.
+This is because `.outside` is listening for clicks that DON'T originate from the element it's registered on.
 
 > It's worth noting that the `.outside` expression will only be evaluated when the element it's registered on is visible on the page. Otherwise, there would be nasty race conditions where clicking the "Toggle" button would also fire the `@click.outside` handler when it is not visible.
 

package/src/en/directives/teleport.md

@@ -101,7 +101,7 @@ To make this experience more seamless, you can "forward" events by simply regist
 
 Notice how we are now able to listen for events dispatched from within the teleported element from outside the `<template>` element itself?
 
-Alpine does this by looking for event listeners registered on `<template x-teleport...>` and stops those events from propogating past the live, teleported, DOM element. Then, it creates a copy of that event and re-dispatches it from `<template x-teleport...>`.
+Alpine does this by looking for event listeners registered on `<template x-teleport...>` and stops those events from propagating past the live, teleported, DOM element. Then, it creates a copy of that event and re-dispatches it from `<template x-teleport...>`.
 
 <a name="nesting"></a>
 ## Nesting

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.9.6/dist/cdn.min.js"></script>
+<script defer src="https://unpkg.com/alpinejs@3.10.0/dist/cdn.min.js"></script>
 ```
 
 That's it! Alpine is now available for use inside your page.

package/src/en/essentials/state.md

@@ -54,7 +54,7 @@ Although this may seem obvious to some, it's worth mentioning that Alpine data c
 <a name="data-less-alpine"></a>
 ### Data-less Alpine
 
-Sometimes you may want to use Alpine functionality, but don't need any reactive data. In these cases, you can opt-out of passing an expression to `x-data` entirely. For example:
+Sometimes you may want to use Alpine functionality, but don't need any reactive data. In these cases, you can opt out of passing an expression to `x-data` entirely. For example:
 
 ```alpine
 <button x-data @click="alert('I\'ve been clicked!')">Click Me</button>

package/src/en/magics/id.md

@@ -34,7 +34,7 @@ Now let's say you want to have those same two input elements, but this time you
 
 This presents a problem, you now need to be able to reference the same ID twice. One for the `<label>`'s `for` attribute, and the other for the `id` on the input.
 
-Here's is a way that you might think to accomplish this and is totally valid:
+Here is a way that you might think to accomplish this and is totally valid:
 
 ```alpine
 <div x-data="{ id: $id('text-input') }">

package/src/en/magics/nextTick.md

@@ -21,3 +21,22 @@ title: nextTick
 ```
 
 In the above example, rather than logging "Hello" to the console, "Hello World!" will be logged because `$nextTick` was used to wait until Alpine was finished updating the DOM.
+
+<a name="promises"></a>
+
+## Promises
+
+`$nextTick` returns a promise, allowing the use of `$nextTick` to pause an async function until after pending dom updates. When used like this, `$nextTick` also does not require an argument to be passed.
+
+```alpine
+<div x-data="{ title: 'Hello' }">
+    <button
+        @click="
+            title = 'Hello World!';
+            await $nextTick();
+            console.log($el.innerText);
+        "
+        x-text="title"
+    ></button>
+</div>
+```

package/src/en/plugins/focus.md

@@ -187,7 +187,7 @@ Here is nesting in action:
 <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.
+When building things like dialogs/modals, it's recommended to hide all the other elements on the page from screen readers 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.
 
@@ -218,7 +218,7 @@ By adding `.inert` to `x-trap`, when focus is trapped, all other elements on the
 <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.
+When building dialogs/modals with Alpine, it's recommended that you disable scrolling for the surrounding content when the dialog is open.
 
 `x-trap` allows you to do this automatically with the `.noscroll` modifiers.
 

package/src/en/plugins/intersect.md

@@ -1,5 +1,5 @@
 ---
-order: 1
+order: 2
 title: Intersect
 description: An Alpine convenience wrapper for Intersection Observer that allows you to easily react when an element enters the viewport.
 graph_image: https://alpinejs.dev/social_intersect.jpg

package/src/en/plugins/mask.md

@@ -0,0 +1,143 @@
+---
+order: 1
+title: Mask
+description: Automatically format text fields as users type
+graph_image: https://alpinejs.dev/social_mask.jpg
+---
+
+# Mask Plugin
+
+Alpine's Mask plugin allows you to automatically format a text input field as a user types.
+
+This is useful for many different types of inputs: phone numbers, credit cards, dollar amounts, account numbers, dates, etc.
+
+<a name="installation"></a>
+## Installation
+
+<div x-data="{ expanded: false }">
+<div class=" relative">
+<div x-show="! expanded" class="absolute inset-0 flex justify-start items-end bg-gradient-to-t from-white to-[#ffffff66]"></div>
+<div x-show="expanded" x-collapse.min.80px class="markdown">
+
+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/mask@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 Mask from NPM for use inside your bundle like so:
+
+```shell
+npm install @alpinejs/mask
+```
+
+Then initialize it from your bundle:
+
+```js
+import Alpine from 'alpinejs'
+import mask from '@alpinejs/mask'
+
+Alpine.plugin(mask)
+
+...
+```
+
+</div>
+</div>
+<button :aria-expanded="expanded" @click="expanded = ! expanded" class="text-aqua-600 font-medium underline">
+    <span x-text="expanded ? 'Hide' : 'Show more'">Show</span> <span x-text="expanded ? '↑' : '↓'">↓</span>
+</button>
+ </div>
+
+<a name="x-mask"></a>
+## x-mask
+
+The primary API for using this plugin is the `x-mask` directive.
+
+Let's start by looking at the following simple example of a date field:
+
+```alpine
+<input x-mask="99/99/9999" placeholder="MM/DD/YYYY">
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+    <input x-data x-mask="99/99/9999" placeholder="MM/DD/YYYY">
+</div>
+<!-- END_VERBATIM -->
+
+Notice how the text you type into the input field must adhere to the format provided by `x-mask`. In addition to enforcing numeric characters, the forward slashes `/` are also automatically added if a user doesn't type them first.
+
+The following wildcard characters are supported in masks:
+
+| Wildcard                   | Description                 |
+| -------------------------- | --------------------------- |
+| `*` | Any character |
+| `a` | Only alpha characters (a-z, A-Z) |
+| `9` | Only numeric characters (0-9) |
+
+<a name="mask-functions"></a>
+## Custom Mask Functions
+
+Sometimes simple mask literals (i.e. `(999) 999-9999`) are not sufficient. In these cases, `x-mask:function` allows you to dynamically generate masks on the fly based on user input.
+
+Here's an example of a credit card input that needs to change it's mask based on if the number starts with the numbers "34" or "37" (which means it's an Amex card and therefore has a different format).
+
+```alpine
+<input x-mask:function="
+    $input.startsWith('34') || $input.startsWith('37')
+        ? '9999 999999 99999' : '9999 9999 9999 9999'
+">
+```
+
+As you can see in the above example, every time a user types in the input, that value is passed to the function as `$input`. Based on the `$input`, a different mask is utilized in the field.
+
+Try it for yourself by typing a number that starts with "34" and one that doesn't.
+
+<!-- START_VERBATIM -->
+<div class="demo">
+    <input x-data x-mask:function="
+        $input.startsWith('34') || $input.startsWith('37')
+            ? '9999 999999 99999' : '9999 9999 9999 9999'
+    ">
+</div>
+<!-- END_VERBATIM -->
+
+<a name="money-inputs"></a>
+## Money Inputs
+
+Because writing your own custom mask function for money inputs is fairly complex, Alpine offers a prebuilt one and makes it available as `$money()`.
+
+Here is a fully functioning money input mask:
+
+```alpine
+<input x-mask:function="$money($input)">
+```
+
+<!-- START_VERBATIM -->
+<div class="demo" x-data>
+    <input type="text" x-mask:function="$money($input)" placeholder="0.00">
+</div>
+<!-- END_VERBATIM -->
+
+If you wish to swap the periods for commas and vice versa (as is required in certain currencies), you can do so using the second optional parameter:
+
+```alpine
+<input x-mask:function="$money($input, ',')">
+```
+
+<!-- START_VERBATIM -->
+<div class="demo" x-data>
+    <input type="text" x-mask:function="$money($input, ',')"  placeholder="0.00">
+</div>
+<!-- END_VERBATIM -->

package/src/en/plugins/morph.md

@@ -137,7 +137,7 @@ Here's an example of using `Alpine.morph()` to update an Alpine component with n
 
 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.
+Morph walks both trees simultaneously 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.
 
@@ -249,4 +249,4 @@ By adding keys to each node, we can accomplish this like so:
 
 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)
+You can configure what Morph considers a "key" with the `key:` configuration option. [More on that here](#lifecycle-hooks)

package/src/en/upgrade-guide.md

@@ -299,7 +299,7 @@ In Alpine V2 for below code
 </div>
 ```
 
-after clicking button all `$refs` were displayed. However in Alpine V3 it's possible to access only `$refs` for elements created statically, so only first ref will be returned as expected.
+after clicking button all `$refs` were displayed. However, in Alpine V3 it's possible to access only `$refs` for elements created statically, so only first ref will be returned as expected.
 
 
 <a name="no-ie-11"></a>