@alpinejs/docs 3.13.10-revision.1 → 3.14.0-revision.1

package/package.json

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

package/src/en/directives/on.md

@@ -13,7 +13,7 @@ Here's an example of simple button that shows an alert when clicked.
 <button x-on:click="alert('Hello World!')">Say Hi</button>
 ```
 
-> `x-on` can only listen for events with lower case names, as HTML attributes are case-insensitive. Writing `x-on:CLICK` will listen for an event named `click`. If you need to listen for a custom event with a camelCase name, you can use the [`.camel` helper](#camel) to work around this limitation. Alternatively, you can use  [`x-bind`](/directives/bind#bind-directives) to attach an `x-on` directive to an element in javascript code (where case will be preserved).
+> `x-on` can only listen for events with lower case names, as HTML attributes are case-insensitive. Writing `x-on:CLICK` will listen for an event named `click`. If you need to listen for a custom event with a camelCase name, you can use the [`.camel` helper](#camel) to work around this limitation. Alternatively, you can use [`x-bind`](/directives/bind#bind-directives) to attach an `x-on` directive to an element in javascript code (where case will be preserved).
 
 <a name="shorthand-syntax"></a>
 ## Shorthand syntax
@@ -74,23 +74,64 @@ You can directly use any valid key names exposed via [`KeyboardEvent.key`](https
 
 For easy reference, here is a list of common keys you may want to listen for.
 
-| Modifier                   | Keyboard Key                |
-| -------------------------- | --------------------------- |
-| `.shift`                    | Shift                       |
-| `.enter`                    | Enter                       |
-| `.space`                    | Space                       |
-| `.ctrl`                     | Ctrl                        |
-| `.cmd`                      | Cmd                         |
-| `.meta`                     | Cmd on Mac, Windows key on Windows |
-| `.alt`                      | Alt                         |
-| `.up` `.down` `.left` `.right` | Up/Down/Left/Right arrows   |
-| `.escape`                   | Escape                      |
-| `.tab`                      | Tab                         |
-| `.caps-lock`                | Caps Lock                   |
-| `.equal`                    | Equal, `=`                  |
-| `.period`                   | Period, `.`                 |
-| `.comma`                    | Comma, `,`                  |
-| `.slash`                    | Forward Slash, `/`           |
+| Modifier                       | Keyboard Key                       |
+| ------------------------------ | ---------------------------------- |
+| `.shift`                       | Shift                              |
+| `.enter`                       | Enter                              |
+| `.space`                       | Space                              |
+| `.ctrl`                        | Ctrl                               |
+| `.cmd`                         | Cmd                                |
+| `.meta`                        | Cmd on Mac, Windows key on Windows |
+| `.alt`                         | Alt                                |
+| `.up` `.down` `.left` `.right` | Up/Down/Left/Right arrows          |
+| `.escape`                      | Escape                             |
+| `.tab`                         | Tab                                |
+| `.caps-lock`                   | Caps Lock                          |
+| `.equal`                       | Equal, `=`                         |
+| `.period`                      | Period, `.`                        |
+| `.comma`                       | Comma, `,`                         |
+| `.slash`                       | Forward Slash, `/`                 |
+
+<a name="mouse-events"></a>
+## Mouse events
+
+Like the above Keyboard Events, Alpine allows the use of some key modifiers for handling `click` events.
+
+| Modifier | Event Key |
+| -------- | --------- |
+| `.shift` | shiftKey  |
+| `.ctrl`  | ctrlKey   |
+| `.cmd`   | metaKey   |
+| `.meta`  | metaKey   |
+| `.alt`   | altKey    |
+
+These work on `click`, `auxclick`, `context` and `dblclick` events, and even `mouseover`, `mousemove`, `mouseenter`, `mouseleave`, `mouseout`, `mouseup` and `mousedown`.
+
+Here's an example of a button that changes behaviour when the `Shift` key is held down.
+
+```alpine
+<button type="button"
+    @click="message = 'selected'"
+    @click.shift="message = 'added to selection'">
+    @mousemove.shift="message = 'add to selection'"
+    @mouseout="message = 'select'"
+    x-text="message"></button>
+```
+
+<!-- START_VERBATIM -->
+<div class="demo">
+    <div x-data="{ message: '' }">
+        <button type="button"
+            @click="message = 'selected'"
+            @click.shift="message = 'added to selection'"
+            @mousemove.shift="message = 'add to selection'"
+            @mouseout="message = 'select'"
+            x-text="message"></button>
+    </div>
+</div>
+<!-- END_VERBATIM -->
+
+> Note: Normal click events with some modifiers (like `ctrl`) will automatically become `contextmenu` events in most browsers. Similarly, `right-click` events will trigger a `contextmenu` event, but will also trigger an `auxclick` event if the `contextmenu` event is prevented.
 
 <a name="custom-events"></a>
 ## Custom events
@@ -311,4 +352,3 @@ Add this modifier if you want to execute this listener in the event's capturing
 ```
 
 [→ Read more about the capturing and bubbling phase of events](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#usecapture)
-

package/src/en/directives/transition.md

@@ -21,9 +21,9 @@ The simplest way to achieve a transition using Alpine is by adding `x-transition
 <div x-data="{ open: false }">
     <button @click="open = ! open">Toggle</button>
 
-    <span x-show="open" x-transition>
+    <div x-show="open" x-transition>
         Hello 👋
-    </span>
+    </div>
 </div>
 ```
 
@@ -32,9 +32,9 @@ The simplest way to achieve a transition using Alpine is by adding `x-transition
     <div x-data="{ open: false }">
         <button @click="open = ! open">Toggle</button>
 
-        <span x-show="open" x-transition>
+        <div x-show="open" x-transition>
             Hello 👋
-        </span>
+        </div>
     </div>
 </div>
 <!-- END_VERBATIM -->

package/src/en/essentials/installation.md

@@ -33,11 +33,13 @@ 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://cdn.jsdelivr.net/npm/alpinejs@3.13.10/dist/cdn.min.js"></script>
+<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.14.0/dist/cdn.min.js"></script>
 ```
 
 That's it! Alpine is now available for use inside your page.
 
+Note that you will still need to define a component with `x-data` in order for any Alpine.js attributes to work. See <https://github.com/alpinejs/alpine/discussions/3805> for more information.
+
 <a name="as-a-module"></a>
 ## As a module
 

package/src/en/plugins/sort.md

@@ -65,9 +65,9 @@ The primary API for using this plugin is the `x-sort` directive. By adding `x-so
 <!-- START_VERBATIM -->
 <div x-data>
     <ul x-sort>
-        <li x-sort:item>foo</li>
-        <li x-sort:item>bar</li>
-        <li x-sort:item>baz</li>
+        <li x-sort:item class="cursor-pointer">foo</li>
+        <li x-sort:item class="cursor-pointer">bar</li>
+        <li x-sort:item class="cursor-pointer">baz</li>
     </ul>
 </div>
 <!-- END_VERBATIM -->
@@ -88,9 +88,9 @@ You can react to sorting changes by passing a handler function to `x-sort` and a
 <!-- START_VERBATIM -->
 <div x-data>
     <ul x-sort="alert($item + ' - ' + $position)">
-        <li x-sort:item="1">foo</li>
-        <li x-sort:item="2">bar</li>
-        <li x-sort:item="3">baz</li>
+        <li x-sort:item="1" class="cursor-pointer">foo</li>
+        <li x-sort:item="2" class="cursor-pointer">bar</li>
+        <li x-sort:item="3" class="cursor-pointer">baz</li>
     </ul>
 </div>
 <!-- END_VERBATIM -->
@@ -161,13 +161,13 @@ By default, each `x-sort:item` element is draggable by clicking and dragging any
 <div x-data>
     <ul x-sort>
         <li x-sort:item>
-            <span x-sort:handle> - </span>foo
+            <span x-sort:handle class="cursor-pointer"> - </span>foo
         </li>
         <li x-sort:item>
-            <span x-sort:handle> - </span>bar
+            <span x-sort:handle class="cursor-pointer"> - </span>bar
         </li>
         <li x-sort:item>
-            <span x-sort:handle> - </span>baz
+            <span x-sort:handle class="cursor-pointer"> - </span>baz
         </li>
     </ul>
 </div>
@@ -195,9 +195,9 @@ If you would like to show a "ghost" of the original element in its place instead
 <!-- START_VERBATIM -->
 <div x-data>
     <ul x-sort.ghost>
-        <li x-sort:item>foo</li>
-        <li x-sort:item>bar</li>
-        <li x-sort:item>baz</li>
+        <li x-sort:item class="cursor-pointer">foo</li>
+        <li x-sort:item class="cursor-pointer">bar</li>
+        <li x-sort:item class="cursor-pointer">baz</li>
     </ul>
 </div>
 <!-- END_VERBATIM -->
@@ -226,9 +226,9 @@ This makes it easy to add any custom styling you would like:
 <!-- START_VERBATIM -->
 <div x-data>
     <ul x-sort.ghost x-sort:config="{ ghostClass: 'opacity-50' }">
-        <li x-sort:item>foo</li>
-        <li x-sort:item>bar</li>
-        <li x-sort:item>baz</li>
+        <li x-sort:item class="cursor-pointer">foo</li>
+        <li x-sort:item class="cursor-pointer">bar</li>
+        <li x-sort:item class="cursor-pointer">baz</li>
     </ul>
 </div>
 <!-- END_VERBATIM -->
@@ -280,9 +280,9 @@ If you drag one of the elements in the list below you will see that the hover ef
 <!-- START_VERBATIM -->
 <div x-data>
     <ul x-sort class="flex flex-col items-start">
-        <li x-sort:item class="hover:border border-black">foo</li>
-        <li x-sort:item class="hover:border border-black">bar</li>
-        <li x-sort:item class="hover:border border-black">baz</li>
+        <li x-sort:item class="hover:border border-black cursor-pointer">foo</li>
+        <li x-sort:item class="hover:border border-black cursor-pointer">bar</li>
+        <li x-sort:item class="hover:border border-black cursor-pointer">baz</li>
     </ul>
 </div>
 <!-- END_VERBATIM -->
@@ -304,9 +304,9 @@ Now you can see below that the hover effect is only applied to the dragging elem
 <!-- START_VERBATIM -->
 <div x-data>
     <ul x-sort class="flex flex-col items-start">
-        <li x-sort:item class="[body:not(.sorting)_&]:hover:border border-black">foo</li>
-        <li x-sort:item class="[body:not(.sorting)_&]:hover:border border-black">bar</li>
-        <li x-sort:item class="[body:not(.sorting)_&]:hover:border border-black">baz</li>
+        <li x-sort:item class="[body:not(.sorting)_&]:hover:border border-black cursor-pointer">foo</li>
+        <li x-sort:item class="[body:not(.sorting)_&]:hover:border border-black cursor-pointer">bar</li>
+        <li x-sort:item class="[body:not(.sorting)_&]:hover:border border-black cursor-pointer">baz</li>
     </ul>
 </div>
 <!-- END_VERBATIM -->
@@ -327,9 +327,9 @@ Alpine chooses sensible defaults for configuring [SortableJS](https://github.com
 <!-- START_VERBATIM -->
 <div x-data>
     <ul x-sort x-sort:config="{ animation: 0 }">
-        <li x-sort:item>foo</li>
-        <li x-sort:item>bar</li>
-        <li x-sort:item>baz</li>
+        <li x-sort:item class="cursor-pointer">foo</li>
+        <li x-sort:item class="cursor-pointer">bar</li>
+        <li x-sort:item class="cursor-pointer">baz</li>
     </ul>
 </div>
 <!-- END_VERBATIM -->

package/src/en/start-here.md

@@ -96,14 +96,14 @@ When a `click` event happens, Alpine will call the associated JavaScript express
 ### Reacting to changes
 
 ```alpine
-<h1 x-text="count"></h1>
+<span x-text="count"></span>
 ```
 
 `x-text` is an Alpine directive you can use to set the text content of an element to the result of a JavaScript expression.
 
-In this case, we're telling Alpine to always make sure that the contents of this `h1` tag reflect the value of the `count` property.
+In this case, we're telling Alpine to always make sure that the contents of this `span` tag reflect the value of the `count` property.
 
-In case it's not clear, `x-text`, like most directives accepts a plain JavaScript expression as an argument. So for example, you could instead set its contents to: `x-text="count * 2"` and the text content of the `h1` will now always be 2 times the value of `count`.
+In case it's not clear, `x-text`, like most directives accepts a plain JavaScript expression as an argument. So for example, you could instead set its contents to: `x-text="count * 2"` and the text content of the `span` will now always be 2 times the value of `count`.
 
 [→ Read more about `x-text`](/directives/text)