@alpinejs/docs 3.5.2-revision.1 → 3.6.1-revision.3

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@alpinejs/docs",
-    "version": "3.5.2-revision.1",
+    "version": "3.6.1-revision.3",
     "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.2/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

@@ -61,6 +61,7 @@ Then initialize it from your bundle:
 import Alpine from 'alpinejs'
 import morph from '@alpinejs/morph'
 
+window.Alpine = Alpine
 Alpine.plugin(morph)
 
 ...

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.1-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="modals1">
+            <div x-show="open">
+                Modal contents...
+            </div>
+        </template>
+
+        <div class="py-4">Some other content...</div>
+    </div>
+
+    <template x-portal-target="modals1"></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="modals2" @click="open = false">
+            <div x-show="open">
+                Modal contents...<br>
+                (click to close)
+            </div>
+        </template>
+    </div>
+
+    <template x-portal-target="modals2"></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="modals3">
+            <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="modals3">
+                        <div class="pt-4" x-show="open">
+                            Nested modal contents...
+                        </div>
+                    </template>
+                </div>
+            </div>
+        </template>
+    </div>
+
+    <template x-portal-target="modals3"></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.