@alpinejs/docs 3.5.1-revision.1 → 3.6.1-revision.1

package/package.json

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

package/src/en/directives/id.md

@@ -0,0 +1,33 @@
+---
+order: 17
+title: id
+---
+
+# x-id
+`x-id` allows you to declare a new "scope" for any new IDs generated using `$id()`. It accepts an array of strings (ID names) and adds a suffix to each `$id('...')` generated within it that is unique to other IDs on the page.
+
+`x-id` is meant to be used in conjunction with the `$id(...)` magic.
+
+[Visit the $id documentation](/magics/id) for a better understanding of this feature.
+
+Here's a brief example of this directive in use:
+
+```alpine
+<div x-id="['text-input']">
+    <label :for="$id('text-input')">Username</label>
+    <!-- for="text-input-1" -->
+
+    <input type="text" :id="$id('text-input')">
+    <!-- id="text-input-1" -->
+</div>
+
+<div x-id="['text-input']">
+    <label :for="$id('text-input')">Username</label>
+    <!-- for="text-input-2" -->
+
+    <input type="text" :id="$id('text-input')">
+    <!-- id="text-input-2" -->
+</div>
+```
+
+

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

package/src/en/magics/id.md

@@ -0,0 +1,106 @@
+---
+order: 9
+prefix: $
+title: id
+---
+
+# $id
+
+`$id` is a magic property that can be used to generate an element's ID and ensure that it is within on the page and won't conflict with other IDs of the same name.
+
+This utility is extremely helpful when building re-usable components (presumably in a back-end template) that might occur multiple times on a page, and make use of ID attributes.
+
+Things like input components, modals, listboxes, etc. will all benefit from this utility.
+
+<a name="basic-usage"></a>
+## Basic usage
+
+Suppose you have two input elements on a page, and you want them to have a unique ID from each other, you can do the following:
+
+```alpine
+<input type="text" :id="$id('text-input')">
+<!-- id="text-input-1" -->
+
+<input type="text" :id="$id('text-input')">
+<!-- id="text-input-2" -->
+```
+
+As you can see, `$id` takes in a string and spits out an appended suffix that is unique on the page.
+
+<a name="groups-with-x-id"></a>
+## Grouping with x-id
+
+Now let's say you want to have those same two input elements, but this time you want `<label>` elements for each of them.
+
+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:
+
+```alpine
+<div x-data="{ id: $id('text-input') }">
+    <label :for="id"> <!-- "text-input-1" -->
+    <input type="text" :id="id"> <!-- "text-input-1" -->
+</div>
+
+<div x-data="{ id: $id('text-input') }">
+    <label :for="id"> <!-- "text-input-2" -->
+    <input type="text" :id="id"> <!-- "text-input-2" -->
+</div>
+```
+
+This approach is fine, however, having to name and store the ID in your component scope feels cumbersome.
+
+To accomplish this same task in a more flexible way, you can use Alpine's `x-id` directive to declare an "id scope" for a set of IDs:
+
+```alpine
+<div x-id="['text-input']">
+    <label :for="$id('text-input')"> <!-- "text-input-1" -->
+    <input type="text" :id="$id('text-input')"> <!-- "text-input-1" -->
+</div>
+
+<div x-id="['text-input']">
+    <label :for="$id('text-input')"> <!-- "text-input-2" -->
+    <input type="text" :id="$id('text-input')"> <!-- "text-input-2" -->
+</div>
+```
+
+As you can see, `x-id` accepts an array of ID names. Now any usages of `$id()` within that scope, will all use the same ID. Think of them as "id groups".
+
+<a name="nesting"></a>
+## Nesting
+
+As you might have intuited, you can freely nest these `x-id` groups, like so:
+
+```alpine
+<div x-id="['text-input']">
+    <label :for="$id('text-input')"> <!-- "text-input-1" -->
+    <input type="text" :id="$id('text-input')"> <!-- "text-input-1" -->
+
+    <div x-id="['text-input']">
+        <label :for="$id('text-input')"> <!-- "text-input-2" -->
+        <input type="text" :id="$id('text-input')"> <!-- "text-input-2" -->
+    </div>
+</div>
+```
+
+<a name="keyed-ids"></a>
+## Keyed IDs (For Looping)
+
+Sometimes, it is helpful to specify an additional suffix on the end of an ID for the purpose of identifying it within a loop.
+
+For this, `$id()` accepts an optional second parameter that will be added as a suffix on the end of the generated ID.
+
+A common example of this need is something like a listbox component that uses the `aria-activedescendant` attribute to tell assistive technologies which element is "active" in the list:
+
+```alpine
+<ul
+    x-id="['list-item']"
+    :aria-activedescendant="$id('list-item', activeItem.id)"
+>
+    <template x-for="item in items" :key="item.id">
+        <li :id="$id('list-item', item.id)">...</li>
+    </template>
+</ul>
+```
+
+This is an incomplete example of a listbox, but it should still be helpful to demonstrate a scenario where you might need each ID in a group to still be unique to the page, but also be keyed within a loop so that you can reference individual IDs within that group.

package/src/en/plugins/morph.md

@@ -0,0 +1,252 @@
+---
+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'
+
+window.Alpine = Alpine
+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/portal.md

@@ -0,0 +1,220 @@
+---
+order: 6
+title: Portal
+description: Send Alpine templates to other parts of the DOM
+graph_image: https://alpinejs.dev/social_portal.jpg
+---
+
+# Portal Plugin
+
+Alpine's Portal plugin allows you to transport part of your Alpine template to another part of the DOM on the page entirely.
+
+This is useful for things like modals (especially nesting them), where it's helpful to break out of the z-index of the current Alpine component.
+
+> Note: this plugin is currently in beta while it is being tested in the public. Be warned that it may change before being officially released.
+
+<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/portal@3.6.0-beta.0/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 Portal from NPM for use inside your bundle like so:
+
+```shell
+npm install @alpinejs/portal
+```
+
+Then initialize it from your bundle:
+
+```js
+import Alpine from 'alpinejs'
+import portal from '@alpinejs/portal'
+
+Alpine.plugin(portal)
+
+...
+```
+
+<a name="usage"></a>
+## Usage
+
+Everytime you use a portal, you will need two different directives: `x-portal` and `x-portal-target`.
+
+By attaching `x-portal` to a `<template>` element, you are telling Alpine to send that DOM content to another template element that has a matching `x-portal-target` on it.
+
+Here's a contrived modal example using portals:
+
+```alpine
+<div x-data="{ open: false }">
+    <button @click="open = ! open">Toggle Modal</button>
+
+    <template x-portal="modals">
+        <div x-show="open">
+            Modal contents...
+        </div>
+    </template>
+
+    <div class="py-4">Some other content placed AFTER the modal markup.</div>
+</div>
+
+<template x-portal-target="modals"></template>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo" x-ref="root">
+    <div x-data="{ open: false }">
+        <button @click="open = ! open">Toggle Modal</button>
+
+        <template x-portal="modals">
+            <div x-show="open">
+                Modal contents...
+            </div>
+        </template>
+
+        <div class="py-4">Some other content...</div>
+    </div>
+
+    <template x-portal-target="modals"></template>
+</div>
+<!-- END_VERBATIM -->
+
+Notice how when toggling the modal, the actual modal contents show up AFTER the "Some other content..." element? This is because when Alpine is initializing, it sees `x-portal="modals"` and takes that markup out of the page waiting until it finds an element with `x-portal-target="modals"` to insert it into.
+
+<a name="forwarding-events"></a>
+## Forwarding events
+
+Alpine tries it's best to make the experience of using portals seemless. Anything you would normally do in a template, you should be able to do inside a portal. Portal content can access the normal Alpine scope of the component as well as other features like `$refs`, `$root`, etc...
+
+However, native DOM events have no concept of portals, so if, for example, you trigger a "click" event from inside a portal, that event will bubble up the DOM tree as it normally would ignoring the fact that it is within a portal.
+
+To make this experience more seemless, you can "forward" events by simply registering event listeners on the portal's `<template>` element itself like so:
+
+```alpine
+<div x-data="{ open: false }">
+    <button @click="open = ! open">Toggle Modal</button>
+
+    <template x-portal="modals" @click="open = false">
+        <div x-show="open">
+            Modal contents...
+            (click to close)
+        </div>
+    </template>
+</div>
+
+<template x-portal-target="modals"></template>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo" x-ref="root">
+    <div x-data="{ open: false }">
+        <button @click="open = ! open">Toggle Modal</button>
+
+        <template x-portal="modals" @click="open = false">
+            <div x-show="open">
+                Modal contents...<br>
+                (click to close)
+            </div>
+        </template>
+    </div>
+
+    <template x-portal-target="modals"></template>
+</div>
+<!-- END_VERBATIM -->
+
+Notice how we are now able to listen for events dispatched from within the portal from outside the portal itself?
+
+Alpine does this by looking for event listeners registered on `<template x-portal...` and stops those events from propogating past the `<template x-portal-target...` element. Then it creates a copy of that event and re-dispatches it from `<template x-portal`.
+
+<a name="nesting-portals"></a>
+## Nesting portals
+
+Portals are especially helpful if you are trying to nest one modal within another. Alpine makes it simple to do so:
+
+```alpine
+<div x-data="{ open: false }">
+    <button @click="open = ! open">Toggle Modal</button>
+
+    <template x-portal="modals">
+        <div x-show="open">
+            Modal contents...
+            
+            <div x-data="{ open: false }">
+                <button @click="open = ! open">Toggle Nested Modal</button>
+
+                <template x-portal="modals">
+                    <div x-show="open">
+                        Nested modal contents...
+                    </div>
+                </template>
+            </div>
+        </div>
+    </template>
+</div>
+
+<template x-portal-target="modals"></template>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo" x-ref="root">
+    <div x-data="{ open: false }">
+        <button @click="open = ! open">Toggle Modal</button>
+
+        <template x-portal="modals">
+            <div x-show="open">
+                <div class="py-4">Modal contents...</div>
+                
+                <div x-data="{ open: false }">
+                    <button @click="open = ! open">Toggle Nested Modal</button>
+
+                    <template x-portal="modals">
+                        <div class="pt-4" x-show="open">
+                            Nested modal contents...
+                        </div>
+                    </template>
+                </div>
+            </div>
+        </template>
+    </div>
+
+    <template x-portal-target="modals"></template>
+</div>
+<!-- END_VERBATIM -->
+
+After toggling "on" both modals, they are authored as children, but will be rendered as sibling elements on the page, not within one another.
+
+<a name="multiple-portals"></a>
+## Handling multiple portals
+
+Suppose you have multiple modals on a page, but a single `<template x-portal-target="modal">` element.
+
+Alpine automatically appends extra elements with `x-portal="modals"` at the target. No need for any extra syntax:
+
+```alpine
+<template x-portal="modals">
+    ...
+</template>
+
+<template x-portal="modals">
+    ...
+</template>
+
+...
+
+<template x-portal-target="modals"></template>
+```
+
+Now both of these modals will be rendered where `<template x-portal-target="modals">` lives.