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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@alpinejs/docs",
-    "version": "3.8.0-revision.1",
+    "version": "3.9.0-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/data.md

@@ -110,13 +110,13 @@ Occasionally, you want to create an Alpine component, but you don't need any dat
 In these cases, you can always pass in an empty object.
 
 ```alpine
-<div x-data="{}"...
+<div x-data="{}">
 ```
 
 However, if you wish, you can also eliminate the attribute value entirely if it looks better to you.
 
 ```alpine
-<div x-data...
+<div x-data>
 ```
 
 <a name="single-element-components"></a>

package/src/en/directives/modelable.md

@@ -0,0 +1,37 @@
+---
+order: 7
+title: modelable
+---
+
+# x-modelable
+
+`x-modelable` allows you to expose any value by name as the target of the `x-model` directive.
+
+Typically this feature would be used in conjunction with a backend templating framework like Laravel Blade. It's useful for abstracting away Alpine components into backend templates and exposing state to the outside through `x-model` as if it were a native input.
+
+Here's a simple example of using `x-modelable` to expose a variable for binding with `x-model`.
+
+```alpine
+<div x-data="{ number: 5 }">
+    <div x-data="{ count: 0 }" x-modelable="count" x-model="numberOfItems">
+        <button @click="count++">Increment</button>
+    </div>
+
+    Some Number: <span x-text="number"></span>
+</div>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+    <div x-data="{ number: 5 }">
+        <div x-data="{ count: 0 }" x-modelable="count" x-model="numberOfItems">
+            <button @click="count++">Increment</button>
+        </div>
+
+        Number: <span x-text="number"></span>
+    </div>
+</div>
+<!-- END_VERBATIM -->
+
+As you can see the outer scope property "number" is now bound to the inner scope property "count".
+

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

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

@@ -6,7 +6,7 @@ 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.
+`$id` is a magic property that can be used to generate an element's ID and ensure that it won't conflict with other IDs of the same name on the same page.
 
 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.
 

package/src/en/plugins/focus.md

@@ -5,6 +5,8 @@ description: Easily manage focus within the page
 graph_image: https://alpinejs.dev/social_focus.jpg
 ---
 
+> 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.
+
 # Focus Plugin
 
 Alpine's Focus plugin allows you to manage focus on a page.
@@ -252,6 +254,53 @@ For example:
 </div>
 <!-- END_VERBATIM -->
 
+<a name="noreturn"></a>
+#### .noreturn
+
+Sometimes you may not want focus to be returned to where it was previously. Consider a dropdown that's triggered upon focusing an input, returning focus to the input on close will just trigger the dropdown to open again.
+
+`x-trap` allows you to disable this behavior with the `.noreturn` modifier.
+
+By adding `.noreturn`, Alpine will not return focus upon x-trap evaluating to false.
+
+For example:
+
+```alpine
+<div x-data="{ open: false }" x-trap.noreturn="open">
+    <input type="search" placeholder="search for something" />
+
+    <div x-show="open">
+        Search results
+
+        <button @click="open = false">Close</button>
+    </div>
+</div>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+    <div
+        x-data="{ open: false }" 
+        x-trap.noreturn="open"
+        @click.outside="open = false"
+        @keyup.escape.prevent.stop="open = false"
+    >
+        <input type="search" placeholder="search for something"
+            @focus="open = true"
+            @keyup.escape.prevent="$el.blur()"
+        />
+
+        <div x-show="open">
+            <div class="mb-4 text-bold">Search results</div>
+
+            <p class="mb-4 text-gray-600 text-sm">Notice when closing this dropdown, focus is not returned to the input.</p>
+
+            <button class="mt-4" @click="open = false">Close Dialog</button>
+        </div>
+    </div>
+</div>
+<!-- END_VERBATIM -->
+
 <a name="focus-magic"></a>
 ## $focus
 

package/src/en/plugins/intersect.md

@@ -78,16 +78,18 @@ For example, in the following snippet, `shown` will remain `false` until the ele
 <a name="x-intersect-enter"></a>
 ### x-intersect:enter
 
-You can opt to only trigger x-intersect when the element ENTERS the viewport by adding the `:enter` suffix to `x-intersect` like so:
+The `:enter` suffix is an alias of `x-intersect`, and works the same way:
 
 ```alpine
 <div x-intersect:enter="shown = true">...</div>
 ```
 
+You may choose to use this for clarity when also using the `:leave` suffix.
+
 <a name="x-intersect-leave"></a>
 ### x-intersect:leave
 
-Similarly, you can add `:leave` to only trigger x-intersect when the element LEAVES the viewport:
+Appending `:leave` runs your expression when the element leaves the viewport:
 
 ```alpine
 <div x-intersect:leave="shown = true">...</div>
@@ -126,3 +128,25 @@ Useful for elements where it's important to show the whole element.
 ```alpine
 <div x-intersect.full="shown = true">...</div> // when `0.99` of the element is in the viewport
 ```
+
+<a name="margin"></a>
+### .margin
+
+Allows you to control the `rootMargin` property of the underlying `IntersectionObserver`.
+This effectively tweaks the size of the viewport boundary. Positive values
+expand the boundary beyond the viewport, and negative values shrink it inward. The values
+work like CSS margin: one value for all sides, two values for top/bottom, left/right, or
+four values for top, right, bottom, left. You can use `px` and `%` values, or use a bare number to
+get a pixel value.
+
+```alpine
+<div x-intersect.margin.200px="loaded = true">...</div> // Load when the element is within 200px of the viewport
+```
+
+```alpine
+<div x-intersect:leave.margin.10%.25px.25.25px="loaded = false">...</div> // Unload when the element gets within 10% of the top of the viewport, or within 25px of the other three edges
+```
+
+```alpine
+<div x-intersect.margin.-100px="visible = true">...</div> // Mark as visible when element is more than 100 pixels into the viewport.
+```

package/src/en/plugins/morph.md

@@ -158,7 +158,7 @@ Here are the available lifecycle hooks (passed in as the third parameter to `Alp
 | `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. |
+| `adding(el, skip)` | 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. |