@alpinejs/docs 3.7.0-revision.1 → 3.8.0-revision.1

package/package.json

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

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/on.md

@@ -234,6 +234,14 @@ The above example is a great use case of throttling. Without `.throttle`, the `h
 
 > Fun Fact: This exact strategy is used on this very documentation site to update the currently highlighted section in the right sidebar.
 
+Just like with `.debounce`, you can add a custom duration to your throttled event:
+
+```alpine
+<div @scroll.window.throttle.750ms="handleScroll">...</div>
+```
+
+Now, `handleScroll` will only be called every 750 milliseconds.
+
 <a name="self"></a>
 ### .self
 

package/src/en/directives/teleport.md

@@ -5,18 +5,22 @@ description: Send Alpine templates to other parts of the DOM
 graph_image: https://alpinejs.dev/social_teleport.jpg
 ---
 
-# Teleport Plugin
+# x-teleport
 
-Alpine's Teleport plugin allows you to transport part of your Alpine template to another part of the DOM on the page entirely.
+The `x-teleport` directive 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.
 
+> Warning: if you are a [Livewire](https://laravel-livewire.com) user, this functionality does not currently work inside Livewire components. Support for this is on the roadmap.
+
 <a name="x-teleport"></a>
 ## x-teleport
 
 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`
+> 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)
 
 Here's a contrived modal example:
 
@@ -61,11 +65,11 @@ Notice how when toggling the modal, the actual modal contents show up AFTER the
 <a name="forwarding-events"></a>
 ## Forwarding events
 
-Alpine tries it's best to make the experience of telporting seemless. Anything you would normally do in a template, you should be able to do inside an `x-teleport` template. Teleported content can access the normal Alpine scope of the component as well as other features like `$refs`, `$root`, etc...
+Alpine tries its best to make the experience of teleporting seamless. Anything you would normally do in a template, you should be able to do inside an `x-teleport` template. Teleported 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 teleportation, so if, for example, you trigger a "click" event from inside a teleported element, that event will bubble up the DOM tree as it normally would.
 
-To make this experience more seemless, you can "forward" events by simply registering event listeners on the `<template x-teleport...>` element itself like so:
+To make this experience more seamless, you can "forward" events by simply registering event listeners on the `<template x-teleport...>` element itself like so:
 
 ```alpine
 <div x-data="{ open: false }">

package/src/en/directives/transition.md

@@ -138,11 +138,11 @@ For direct control over exactly what goes into your transitions, you can apply C
     <div
         x-show="open"
         x-transition:enter="transition ease-out duration-300"
-        x-transition:enter-start="opacity-0 transform scale-90"
-        x-transition:enter-end="opacity-100 transform scale-100"
+        x-transition:enter-start="opacity-0 scale-90"
+        x-transition:enter-end="opacity-100 scale-100"
         x-transition:leave="transition ease-in duration-300"
-        x-transition:leave-start="opacity-100 transform scale-100"
-        x-transition:leave-end="opacity-0 transform scale-90"
+        x-transition:leave-start="opacity-100 scale-100"
+        x-transition:leave-end="opacity-0 scale-90"
     >Hello 👋</div>
 </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.7.0/dist/cdn.min.js"></script>
+<script defer src="https://unpkg.com/alpinejs@3.8.0/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/magics/watch.md

@@ -35,3 +35,25 @@ When the `<button>` is pressed, `foo.bar` will be set to "bob", and "bob" will b
     <button @click="open = ! open">Toggle Open</button>
 </div>
 ```
+
+<a name="deep-watching"></a>
+### Deep watching
+
+`$watch` will automatically watches from changes at any level but you should keep in mind that, when a change is detected, the watcher will return the value of the observed property, not the value of the subproperty that has changed.
+
+```alpine
+<div x-data="{ foo: { bar: 'baz' }}" x-init="$watch('foo', (value, oldValue) => console.log(value, oldValue))">
+    <button @click="foo.bar = 'bob'">Update</button>
+</div>
+```
+
+When the `<button>` is pressed, `foo.bar` will be set to "bob", and "{bar: 'bob'} {bar: 'baz'}" will be logged to the console (new and old value).
+
+> ⚠️ Changing a property of a "watched" object as a side effect of the `$watch` callback will generate an infinite loop and eventually error. 
+
+```alpine
+<!-- 🚫 Infinite loop -->
+<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,15 @@
 ---
 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
+# Focus Plugin
 
-Alpine's Trap plugin allows you to conditionally trap focus inside an element.
+Alpine's Focus plugin allows you to manage focus on a page.
 
-This is useful for modals and other dialog elements.
+> 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 +22,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 +30,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 +50,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 +99,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 +180,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 +214,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 +251,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>

package/src/en/start-here.md

@@ -88,7 +88,7 @@ You can listen for other events as you'd imagine. For example, listening for a `
 
 When a `click` event happens, Alpine will call the associated JavaScript expression, `count++` in our case. As you can see, we have direct access to data declared in the `x-data` expression.
 
-> You will often see `@` instead of `x-on`. This is a shorter, friendlier syntax that many prefer. From now on, this documentation will likely use `@` instead of `x-on`.
+> You will often see `@` instead of `x-on:`. This is a shorter, friendlier syntax that many prefer. From now on, this documentation will likely use `@` instead of `x-on:`.
 
 [→ Read more about `x-on`](/directives/on)