From 1ab7b6b6bfab2172c428032e6a320586a78bf925 Mon Sep 17 00:00:00 2001
From: Eric Kwoka <43540491+ekwoka@users.noreply.github.com>
Date: Tue, 15 Oct 2024 15:16:38 +0400
Subject: [PATCH] :memo: Updates docs with notes for x-data usage (#4307)

---
 packages/docs/src/en/directives/bind.md       | 2 ++
 packages/docs/src/en/directives/for.md        | 4 +++-
 packages/docs/src/en/directives/id.md         | 3 ++-
 packages/docs/src/en/directives/if.md         | 8 ++++++--
 packages/docs/src/en/directives/model.md      | 2 ++
 packages/docs/src/en/directives/on.md         | 2 ++
 packages/docs/src/en/directives/ref.md        | 2 ++
 packages/docs/src/en/directives/transition.md | 2 ++
 packages/docs/src/en/start-here.md            | 2 ++
 9 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/packages/docs/src/en/directives/bind.md b/packages/docs/src/en/directives/bind.md
index cc5b81d1f..9bcaa4f9e 100644
--- a/packages/docs/src/en/directives/bind.md
+++ b/packages/docs/src/en/directives/bind.md
@@ -24,6 +24,8 @@ If `x-bind:` is too verbose for your liking, you can use the shorthand: `:`. For
 <input type="text" :placeholder="placeholder">
 ```
 
+> Despite not being included in the above snippet, `x-bind` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
+
 <a name="binding-classes"></a>
 ## Binding classes
 
diff --git a/packages/docs/src/en/directives/for.md b/packages/docs/src/en/directives/for.md
index 4803071b9..97df4d23c 100644
--- a/packages/docs/src/en/directives/for.md
+++ b/packages/docs/src/en/directives/for.md
@@ -51,7 +51,7 @@ You may also pass objects to `x-for`.
 
 There are two rules worth noting about `x-for`:
 
->`x-for` MUST be declared on a `<template>` element.
+> `x-for` MUST be declared on a `<template>` element.
 > That `<template>` element MUST contain only one root element
 
 <a name="keys"></a>
@@ -110,6 +110,8 @@ If you need to simply loop `n` number of times, rather than iterate through an a
 
 `i` in this case can be named anything you like.
 
+> Despite not being included in the above snippet, `x-for` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
+
 <a name="contents-of-a-template"></a>
 ## Contents of a `<template>`
 
diff --git a/packages/docs/src/en/directives/id.md b/packages/docs/src/en/directives/id.md
index b1faedd50..df86aa957 100644
--- a/packages/docs/src/en/directives/id.md
+++ b/packages/docs/src/en/directives/id.md
@@ -4,6 +4,7 @@ title: id
 ---
 
 # x-id
+
 `x-id` allows you to declare a new "scope" for any new IDs generated using `$id()`. It accepts an array of strings (ID names) and adds a suffix to each `$id('...')` generated within it that is unique to other IDs on the page.
 
 `x-id` is meant to be used in conjunction with the `$id(...)` magic.
@@ -30,4 +31,4 @@ Here's a brief example of this directive in use:
 </div>
 ```
 
-
+> Despite not being included in the above snippet, `x-id` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
diff --git a/packages/docs/src/en/directives/if.md b/packages/docs/src/en/directives/if.md
index b8300f330..03429923d 100644
--- a/packages/docs/src/en/directives/if.md
+++ b/packages/docs/src/en/directives/if.md
@@ -15,6 +15,10 @@ Because of this difference in behavior, `x-if` should not be applied directly to
 </template>
 ```
 
-> Unlike `x-show`, `x-if`, does NOT support transitioning toggles with `x-transition`.
+> Despite not being included in the above snippet, `x-if` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
 
-> Remember: `<template>` tags can only contain one root level element.
+## Caveats
+
+Unlike `x-show`, `x-if`, does NOT support transitioning toggles with `x-transition`.
+
+`<template>` tags can only contain one root element.
diff --git a/packages/docs/src/en/directives/model.md b/packages/docs/src/en/directives/model.md
index 5a68b51c9..4c75276f0 100644
--- a/packages/docs/src/en/directives/model.md
+++ b/packages/docs/src/en/directives/model.md
@@ -83,6 +83,8 @@ Now when the `<button>` is clicked, the input element's value will instantly be
 </div>
 <!-- END_VERBATIM -->
 
+> Despite not being included in the above snippet, `x-model` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
+
 <a name="textarea-inputs"></a>
 ## Textarea inputs
 
diff --git a/packages/docs/src/en/directives/on.md b/packages/docs/src/en/directives/on.md
index 32c997afd..7ccf7a0ec 100644
--- a/packages/docs/src/en/directives/on.md
+++ b/packages/docs/src/en/directives/on.md
@@ -26,6 +26,8 @@ Here's the same component as above, but using the shorthand syntax instead:
 <button @click="alert('Hello World!')">Say Hi</button>
 ```
 
+> Despite not being included in the above snippet, `x-on` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
+
 <a name="the-event-object"></a>
 ## The event object
 
diff --git a/packages/docs/src/en/directives/ref.md b/packages/docs/src/en/directives/ref.md
index 075307614..9c70d2f99 100644
--- a/packages/docs/src/en/directives/ref.md
+++ b/packages/docs/src/en/directives/ref.md
@@ -22,3 +22,5 @@ title: ref
     </div>
 </div>
 <!-- END_VERBATIM -->
+
+> Despite not being included in the above snippet, `x-ref` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
diff --git a/packages/docs/src/en/directives/transition.md b/packages/docs/src/en/directives/transition.md
index d44b43fe1..fcddb7a76 100644
--- a/packages/docs/src/en/directives/transition.md
+++ b/packages/docs/src/en/directives/transition.md
@@ -65,6 +65,8 @@ If you wish to customize the durations specifically for entering and leaving, yo
 >
 ```
 
+> Despite not being included in the above snippet, `x-transition` cannot be used if no parent element has `x-data` defined. [→ Read more about `x-data`](/directives/data)
+
 <a name="customizing-delay"></a>
 ### Customizing delay
 
diff --git a/packages/docs/src/en/start-here.md b/packages/docs/src/en/start-here.md
index 7d5d6c080..3f0cda649 100644
--- a/packages/docs/src/en/start-here.md
+++ b/packages/docs/src/en/start-here.md
@@ -71,6 +71,8 @@ Everything in Alpine starts with an `x-data` directive. Inside of `x-data`, in p
 
 Every property inside this object will be made available to other directives inside this HTML element. In addition, when one of these properties changes, everything that relies on it will change as well.
 
+> `x-data` is required on a parent element for most Alpine directives to work.
+
 [→ Read more about `x-data`](/directives/data)
 
 Let's look at `x-on` and see how it can access and modify the `count` property from above: