npm - @alpinejs/docs - Versions diffs - 3.14.7-revision.1 → 3.15.0 - Mend

@alpinejs/docs 3.14.7-revision.1 → 3.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/package.json +1 -1
package/src/en/advanced/csp.md +101 -60
package/src/en/essentials/installation.md +1 -1
package/src/en/plugins/focus.md +1 -1
package/src/en/plugins/morph.md +12 -0

package/package.json CHANGED Viewed

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

package/src/en/advanced/csp.md CHANGED Viewed

@@ -5,11 +5,11 @@ title: CSP
 # CSP (Content-Security Policy) Build
-In order for Alpine to be able to execute plain strings from HTML attributes as JavaScript expressions, for example `x-on:click="console.log()"`, it needs to rely on utilities that violate the "unsafe-eval" [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) that some applications may enforce for security purposes.
+In order for Alpine to execute JavaScript expressions from HTML attributes like `x-on:click="console.log()"`, it needs to use utilities that violate the "unsafe-eval" [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) that some applications enforce for security purposes.
 > Under the hood, Alpine doesn't actually use eval() itself because it's slow and problematic. Instead it uses Function declarations, which are much better, but still violate "unsafe-eval".
-In order to accommodate environments where this CSP is necessary, Alpine offer's an alternate build that doesn't violate "unsafe-eval", but has a more restrictive syntax.
+Alpine offers an alternate build that doesn't violate "unsafe-eval" and supports most of Alpine's inline expression syntax.
 <a name="installation"></a>
 ## Installation
@@ -46,98 +46,139 @@ Alpine.start()
 <a name="basic-example"></a>
 ## Basic Example
-To provide a glimpse of how using the CSP build might feel, here is a copy-pastable HTML file with a working counter component using a common CSP setup:
+Here's a working counter component using Alpine's CSP build. Notice how most expressions work exactly like regular Alpine:
 ```alpine
 <html>
     <head>
         <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'nonce-a23gbfz9e'">
         <script defer nonce="a23gbfz9e" src="https://cdn.jsdelivr.net/npm/@alpinejs/csp@3.x.x/dist/cdn.min.js"></script>
     </head>
     <body>
-        <div x-data="counter">
-            <button x-on:click="increment"></button>
+        <div x-data="{ count: 0, message: 'Hello' }">
+            <button x-on:click="count++">Increment</button>
+            <button x-on:click="count = 0">Reset</button>
             <span x-text="count"></span>
+            <span x-text="message + ' World'"></span>
+            <span x-show="count > 5">Count is greater than 5!</span>
         </div>
-        <script nonce="a23gbfz9e">
-            document.addEventListener('alpine:init', () => {
-                Alpine.data('counter', () => {
-                    return {
-                        count: 1,
-                        increment() {
-                            this.count++;
-                        },
-                    }
-                })
-            })
-        </script>
     </body>
 </html>
 ```
-<a name="api-restrictions"></a>
-## API Restrictions
-Since Alpine can no longer interpret strings as plain JavaScript, it has to parse and construct JavaScript functions from them manually.
+<a name="whats-supported"></a>
+## What's Supported
-Due to this limitation, you must use `Alpine.data` to register your `x-data` objects, and must reference properties and methods from it by key only.
-For example, an inline component like this will not work.
+The CSP build supports most JavaScript expressions you'd want to use in Alpine:
+### Object and Array Literals
 ```alpine
-<!-- Bad -->
-<div x-data="{ count: 1 }">
-    <button @click="count++">Increment</button>
+<!-- ✅ These work -->
+<div x-data="{ user: { name: 'John', age: 30 }, items: [1, 2, 3] }">
+    <span x-text="user.name"></span>
+    <span x-text="items[0]"></span>
+</div>
+```
-    <span x-text="count"></span>
+### Basic Operations
+```alpine
+<!-- ✅ These work -->
+<div x-data="{ count: 5, name: 'Alpine' }">
+    <span x-text="count + 10"></span>
+    <span x-text="count > 3"></span>
+    <span x-text="count === 5 ? 'Yes' : 'No'"></span>
+    <span x-text="'Hello ' + name"></span>
+    <div x-show="!loading && count > 0"></div>
 </div>
 ```
-However, breaking out the expressions into external APIs, the following is valid with the CSP build:
+### Assignments and Updates
+```alpine
+<!-- ✅ These work -->
+<div x-data="{ count: 0, user: { name: '' } }">
+    <button x-on:click="count++">Increment</button>
+    <button x-on:click="count = 0">Reset</button>
+    <input x-model="user.name">
+</div>
+```
+### Method Calls
 ```alpine
-<!-- Good -->
-<div x-data="counter">
-    <button @click="increment">Increment</button>
+<!-- ✅ These work -->
+<div x-data="{ items: ['a', 'b'], getMessage: () => 'Hello' }">
+    <span x-text="getMessage()"></span>
+    <button x-on:click="items.push('c')">Add Item</button>
+</div>
+```
-    <span x-text="count"></span>
+### Global Variables and Functions
+```alpine
+<!-- ✅ These work -->
+<div x-data="{ count: 42 }">
+    <button x-on:click="console.log('Count is:', count)">Log Count</button>
+    <span x-text="Math.max(count, 100)"></span>
+    <span x-text="parseInt('123') + count"></span>
+    <span x-text="JSON.stringify({ value: count })"></span>
 </div>
 ```
-```js
-Alpine.data('counter', () => ({
-    count: 1,
+<a name="whats-not-supported"></a>
+## What's Not Supported
+Some advanced JavaScript features aren't supported:
-    increment() {
-        this.count++
-    },
-}))
+```alpine
+<!-- ❌ These don't work -->
+<div x-data>
+    <!-- Arrow functions -->
+    <button x-on:click="() => console.log('hi')">Bad</button>
+    <!-- Destructuring -->
+    <div x-text="{ name } = user">Bad</div>
+    <!-- Template literals -->
+    <div x-text="`Hello ${name}`">Bad</div>
+    <!-- Spread operator -->
+    <div x-data="{ ...defaults }">Bad</div>
+</div>
 ```
-The CSP build supports accessing nested properties (property accessors) using the dot notation.
+<a name="when-to-extract-logic"></a>
+## When to Extract Logic
+While the CSP build supports simple inline expressions, you'll want to extract complex logic into dedicated functions or Alpine.data() components for better organization:
 ```alpine
-<!-- This works too -->
-<div x-data="counter">
-    <button @click="foo.increment">Increment</button>
+<!-- Instead of this -->
+<div x-data="{ users: [] }" x-show="users.filter(u => u.active && u.role === 'admin').length > 0">
+```
-    <span x-text="foo.count"></span>
-</div>
+```alpine
+<!-- Do this -->
+<div x-data="userManager" x-show="hasActiveAdmins">
+<script nonce="...">
+    Alpine.data('userManager', () => ({
+        users: [],
+        get hasActiveAdmins() {
+            return this.users.filter(u => u.active && u.role === 'admin').length > 0
+        }
+    }))
+</script>
 ```
-```js
-Alpine.data('counter', () => ({
-    foo: {
-        count: 1,
-        increment() {
-            this.count++
-        },
-    },
-}))
+This approach makes your code more readable, testable, and maintainable, especially for complex applications.
+<a name="csp-headers"></a>
+## CSP Headers
+Here's an example CSP header that works with Alpine's CSP build:
+```
+Content-Security-Policy: default-src 'self'; script-src 'nonce-[random]' 'strict-dynamic';
 ```
+The key is removing `'unsafe-eval'` from your `script-src` directive while still allowing your nonce-based scripts to run.

package/src/en/essentials/installation.md CHANGED Viewed

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

package/src/en/plugins/focus.md CHANGED Viewed

@@ -228,7 +228,7 @@ For example:
 ```alpine
 <div x-data="{ open: false }">
-    <button>Open Dialog</button>
+    <button @click="open = true">Open Dialog</button>
     <div x-show="open" x-trap.noscroll="open">
         Dialog Contents

package/src/en/plugins/morph.md CHANGED Viewed

@@ -250,3 +250,15 @@ By adding keys to each node, we can accomplish this like so:
 Now that there are "keys" on the `<li>`s, Morph will match them in both trees and move them accordingly.
 You can configure what Morph considers a "key" with the `key:` configuration option. [More on that here](#lifecycle-hooks)
+<a name="alpine-morph-between"></a>
+## Alpine.morphBetween()
+The `Alpine.morphBetween(startMarker, endMarker, newHtml, options)` method allows you to morph a range of DOM nodes between two marker elements based on passed in HTML. This is useful when you want to update only a specific section of the DOM without providing a single root node.
+| Parameter | Description |
+| ---       | --- |
+| `startMarker` | A DOM node (typically a comment node) that marks the beginning of the range to morph |
+| `endMarker` | A DOM node (typically a comment node) that marks the end of the range to morph |
+| `newHtml` | A string of HTML or a DOM element to replace the content between the markers |
+| `options` | An object of options (same as `Alpine.morph()`) |