@alpinejs/docs 3.7.1-revision.1 → 3.8.1-revision.1

package/package.json

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

package/src/en/directives/bind.md

@@ -157,9 +157,9 @@ And like most expressions in Alpine, you can always use the result of a JavaScri
 <a name="bind-directives"></a>
 ## Binding Alpine Directives Directly
 
-`x-bind` allows you to bind an object of different properties to an element.
+`x-bind` allows you to bind an object of different directives and attributes to an element.
 
-The object keys are the directives (can be any directive including modifiers), and the values are 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 directoves, callbacks to be evaluated by Alpine.
 
 ```alpine
 <div x-data="dropdown()">

package/src/en/directives/effect.md

@@ -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 re-triggered 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.

package/src/en/directives/teleport.md

@@ -18,7 +18,7 @@ This is useful for things like modals (especially nesting them), where it's help
 
 By attaching `x-teleport` to a `<template>` element, you are telling Alpine to "append" that element to the provided selector.
 
-> The `x-template` selector can be any string you would normally pass into something like `document.querySelector`. It will find the first element that matches, be it a tag name (`body`), class name (`.my-class`), ID (`#my-id`), or any other valid CSS selector.
+> The `x-teleport` selector can be any string you would normally pass into something like `document.querySelector`. It will find the first element that matches, be it a tag name (`body`), class name (`.my-class`), ID (`#my-id`), or any other valid CSS selector.
 
 [→ Read more about `document.querySelector`](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector)
 

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

package/src/en/essentials/templating.md

@@ -303,7 +303,7 @@ Here is an example of a dynamically bound `class` attribute:
 As a shortcut, you can leave out the `x-bind` and use the shorthand `:` syntax directly:
 
 ```alpine
-<button ... :class="red ? 'bg-red' : ''>"
+<button ... :class="red ? 'bg-red' : ''">
 ```
 
 Toggling classes on and off based on data inside Alpine is a common need. Here's an example of toggling a class using Alpine's `class` binding object syntax: (Note: this syntax is only available for `class` attributes)

package/src/en/globals/alpine-bind.md

@@ -0,0 +1,36 @@
+---
+order: 3
+title: bind()
+---
+
+# Alpine.bind
+
+`Alpine.bind(...)` provides a way to re-use [`x-bind`](/directives/bind#bind-directives) objects within your application.
+
+Here's a simple example. Rather than binding attributes manually with Alpine:
+
+```alpine
+<button type="button" @click="doSomething()" :disabled="shouldDisable"></button>
+```
+
+You can bundle these attributes up into a reusable object and use `x-bind` to bind to that:
+
+```alpine
+<button x-bind="SomeButton"></button>
+
+<script>
+    document.addEventListener('alpine:init', () => {
+        Alpine.bind('SomeButton', () => ({
+            type: 'button',
+
+            '@click'() {
+                this.doSomething()
+            },
+
+            ':disabled'() {
+                return this.shouldDisable
+            },
+        }))
+    })
+</script>
+```

package/src/en/globals/alpine-data.md

@@ -3,7 +3,7 @@ order: 1
 title: data()
 ---
 
-# `Alpine.data`
+# Alpine.data
 
 `Alpine.data(...)` provides a way to re-use `x-data` contexts within your application.
 

package/src/en/globals/alpine-store.md

@@ -3,7 +3,7 @@ order: 2
 title: store()
 ---
 
-# `Alpine.store`
+# Alpine.store
 
 Alpine offers global state management through the `Alpine.store()` API.
 

package/src/en/magics/watch.md

@@ -53,7 +53,7 @@ When the `<button>` is pressed, `foo.bar` will be set to "bob", and "{bar: 'bob'
 
 ```alpine
 <!-- 🚫 Infinite loop -->
-<div x-data="{ foo: { bar: 'baz', bob: 'lob' }}" x-init="$watch('foo', value => foo.bob = foo.bar">
+<div x-data="{ foo: { bar: 'baz', bob: 'lob' }}" x-init="$watch('foo', value => foo.bob = foo.bar)">
     <button @click="foo.bar = 'bob'">Update</button>
 </div>
 ```

package/src/en/plugins/{trap.md → focus.md}

@@ -1,15 +1,17 @@
 ---
 order: 3
-title: Trap
-description: Easily trap page focus within an element (modals, dialogs, etc...)
-graph_image: https://alpinejs.dev/social_trap.jpg
+title: Focus
+description: Easily manage focus within the page
+graph_image: https://alpinejs.dev/social_focus.jpg
 ---
 
-# Trap Plugin
+> Notice: This Plugin was previously called "Trap". Trap's functionality has been absorbed into this plugin along with additional functionality. You can swap Trap for Focus without any breaking changes.
 
-Alpine's Trap plugin allows you to conditionally trap focus inside an element.
+# Focus Plugin
 
-This is useful for modals and other dialog elements.
+Alpine's Focus plugin allows you to manage focus on a page.
+
+> This plugin internally makes heavy use of the open source tool: [Tabbable](https://github.com/focus-trap/tabbable). Big thanks to that team for providing a much needed solution to this problem.
 
 <a name="installation"></a>
 ## Installation
@@ -22,7 +24,7 @@ You can include the CDN build of this plugin as a `<script>` tag, just make sure
 
 ```alpine
 <!-- Alpine Plugins -->
-<script defer src="https://unpkg.com/@alpinejs/trap@3.x.x/dist/cdn.min.js"></script>
+<script defer src="https://unpkg.com/@alpinejs/focus@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>
@@ -30,19 +32,19 @@ You can include the CDN build of this plugin as a `<script>` tag, just make sure
 
 ### Via NPM
 
-You can install Trap from NPM for use inside your bundle like so:
+You can install Focus from NPM for use inside your bundle like so:
 
 ```shell
-npm install @alpinejs/trap
+npm install @alpinejs/focus
 ```
 
 Then initialize it from your bundle:
 
 ```js
 import Alpine from 'alpinejs'
-import trap from '@alpinejs/trap'
+import focus from '@alpinejs/focus'
 
-Alpine.plugin(trap)
+Alpine.plugin(focus)
 
 ...
 ```
@@ -50,7 +52,7 @@ Alpine.plugin(trap)
 <a name="x-trap"></a>
 ## x-trap
 
-The primary API for using this plugin is the `x-trap` directive.
+Focus offers a dedicated API for trapping focus within an element: the `x-trap` directive.
 
 `x-trap` accepts a JS expression. If the result of that expression is true, then the focus will be trapped inside that element until the expression becomes false, then at that point, focus will be returned to where it was previously.
 
@@ -99,7 +101,7 @@ For example:
 <!-- END_VERBATIM -->
 
 <a name="nesting"></a>
-## Nesting dialogs
+### Nesting dialogs
 
 Sometimes you may want to nest one dialog inside another. `x-trap` makes this trivial and handles it automatically.
 
@@ -180,10 +182,10 @@ Here is nesting in action:
 <!-- END_VERBATIM -->
 
 <a name="modifiers"></a>
-## Modifiers
+### Modifiers
 
 <a name="inert"></a>
-### .inert
+#### .inert
 
 When building things like dialogs/modals, it's recommended to hide all the other elements on the page from screenreaders when trapping focus.
 
@@ -214,7 +216,7 @@ By adding `.inert` to `x-trap`, when focus is trapped, all other elements on the
 ```
 
 <a name="noscroll"></a>
-### .noscroll
+#### .noscroll
 
 When building dialogs/modals with Alpine, it's recommended that you disable scrollling for the surrounding content when the dialog is open.
 
@@ -251,3 +253,121 @@ For example:
     </div>
 </div>
 <!-- END_VERBATIM -->
+
+<a name="focus-magic"></a>
+## $focus
+
+This plugin offers many smaller utilities for managing focus within a page. These utilities are exposed via the `$focus` magic.
+
+| Property | Description |
+| ---       | --- |
+| `focus(el)`   | Focus the passed element (handling annoyances internally: using nextTick, etc.) |
+| `focusable(el)`   | Detect weather or not an element is focusable |
+| `focusables()`   | Get all "focusable" elements within the current element |
+| `focused()`   | Get the currently focused element on the page |
+| `lastFocused()`   | Get the last focused element on the page |
+| `within(el)`   | Specify an element to scope the `$focus` magic to (the current element by default) |
+| `first()`   | Focus the first focusable element |
+| `last()`   | Focus the last focusable element |
+| `next()`   | Focus the next focusable element |
+| `previous()`   | Focus the previous focusable element |
+| `noscroll()`   | Prevent scrolling to the element about to be focused |
+| `wrap()`   | When retrieving "next" or "previous" use "wrap around" (ex. returning the first element if getting the "next" element of the last element) |
+| `getFirst()`   | Retrieve the first focusable element |
+| `getLast()`   | Retrieve the last focusable element |
+| `getNext()`   | Retrieve the next focusable element |
+| `getPrevious()`   | Retrieve the previous focusable element |
+
+Let's walk through a few examples of these utilities in use. The example below allows the user to control focus within the group of buttons using the arrow keys. You can test this by clicking on a button, then using the arrow keys to move focus around:
+
+```alpine
+<div
+    @keydown.right="$focus.next()"
+    @keydown.left="$focus.previous()"
+>
+    <button>First</button>
+    <button>Second</button>
+    <button>Third</button>
+</div>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+<div
+    x-data
+    @keydown.right="$focus.next()"
+    @keydown.left="$focus.previous()"
+>
+    <button class="focus:outline-none focus:ring-2 focus:ring-aqua-400">First</button>
+    <button class="focus:outline-none focus:ring-2 focus:ring-aqua-400">Second</button>
+    <button class="focus:outline-none focus:ring-2 focus:ring-aqua-400">Third</button>
+</div>
+(Click a button, then use the arrow keys to move left and right)
+</div>
+<!-- END_VERBATIM -->
+
+Notice how if the last button is focused, pressing "right arrow" won't do anything. Let's add the `.wrap()` method so that focus "wraps around":
+
+```alpine
+<div
+    @keydown.right="$focus.wrap().next()"
+    @keydown.left="$focus.wrap().previous()"
+>
+    <button>First</button>
+    <button>Second</button>
+    <button>Third</button>
+</div>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+<div
+    x-data
+    @keydown.right="$focus.wrap().next()"
+    @keydown.left="$focus.wrap().previous()"
+>
+    <button class="focus:outline-none focus:ring-2 focus:ring-aqua-400">First</button>
+    <button class="focus:outline-none focus:ring-2 focus:ring-aqua-400">Second</button>
+    <button class="focus:outline-none focus:ring-2 focus:ring-aqua-400">Third</button>
+</div>
+(Click a button, then use the arrow keys to move left and right)
+</div>
+<!-- END_VERBATIM -->
+
+Now, let's add two buttons, one to focus the first element in the button group, and another focus the last element:
+
+```alpine
+<button @click="$focus.within($refs.buttons).first()">Focus "First"</button>
+<button @click="$focus.within($refs.buttons).last()">Focus "Last"</button>
+
+<div
+    x-ref="buttons"
+    @keydown.right="$focus.wrap().next()"
+    @keydown.left="$focus.wrap().previous()"
+>
+    <button>First</button>
+    <button>Second</button>
+    <button>Third</button>
+</div>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo" x-data>
+<button @click="$focus.within($refs.buttons).first()">Focus "First"</button>
+<button @click="$focus.within($refs.buttons).last()">Focus "Last"</button>
+
+<hr class="mt-2 mb-2"/>
+
+<div
+    x-ref="buttons"
+    @keydown.right="$focus.wrap().next()"
+    @keydown.left="$focus.wrap().previous()"
+>
+    <button class="focus:outline-none focus:ring-2 focus:ring-aqua-400">First</button>
+    <button class="focus:outline-none focus:ring-2 focus:ring-aqua-400">Second</button>
+    <button class="focus:outline-none focus:ring-2 focus:ring-aqua-400">Third</button>
+</div>
+</div>
+<!-- END_VERBATIM -->
+
+Notice that we needed to add a `.within()` method for each button so that `$focus` knows to scope itself to a different element (the `div` wrapping the buttons).

package/src/en/plugins/morph.md

@@ -21,10 +21,10 @@ The best way to understand its purpose is with the following interactive visuali
 
     <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>
+            <button @click="slide = (slide === 1) ? 13 : slide - 1" class="w-full bg-aqua-400 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>
+            <button @click="slide = (slide % 13) + 1" class="w-full bg-aqua-400 rounded-full text-center py-3 font-bold text-white">Next</button>
         </div>
     </div>
 </div>