Change behaviour of data-star-ignore (#505)

* Change behaviour of `data-star-ignore`, add mod

* Improve example

CHANGELOG.md

@@ -5,14 +5,16 @@
 ### Added
 
 - Added the `data-on-interval` attribute.
-- Added the `__delay` modifier for `data-on-*` attributes.
+- Added the `__delay` modifier to `data-on-*` attributes.
+- Added the `__self` modifier to the `data-star-ignore` attribute.
 - Added the entire context to error messages output in the browser console.
 - Added the ability to use an empty value when using the `data-signals-*` syntax, which sets the value to an empty string.
 
 ### Changed
 
 - Changed the order in which plugins are applied to elements to be depth-first per element, then per `data` attribute ([#495](https://github.com/starfederation/datastar/issues/495)).
 - Improved the handling of invalid expressions and signals, and made error handling generally more granular ([#452](https://github.com/starfederation/datastar/issues/452)).
+- The `data-star-ignore` attribute now ignores descendant elements by default.
 
 ### Fixed
 

library/src/engine/engine.ts

@@ -91,9 +91,6 @@ export class Engine {
       // Cleanup any previous plugins
       this.#cleanup(el)
 
-      // Skip elements with empty dataset or marked to be ignored
-      if (!el.dataset || 'starIgnore' in el.dataset) return
-
       // Apply the plugins to the element in order of application
       // since DOMStringMap is ordered, we can be deterministic
       for (const rawKey of Object.keys(el.dataset)) {
@@ -287,9 +284,16 @@ export class Engine {
     if (
       !element ||
       !(element instanceof HTMLElement || element instanceof SVGElement)
-    )
+    ) {
+      return null
+    }
+    const dataset = element.dataset
+    if ('starIgnore' in dataset) {
       return null
-    callback(element)
+    }
+    if (!('starIgnore__self' in dataset)) {
+      callback(element)
+    }
     let el = element.firstElementChild
     while (el) {
       this.#walkDownDOM(el, callback)

site/routes_examples.go

@@ -57,6 +57,7 @@ func setupExamples(ctx context.Context, router chi.Router, signals sessions.Stor
 			Links: []*SidebarLink{
 				{ID: "plugin_order"},
 				{ID: "polling"},
+				{ID: "ignore_attributes"},
 				{ID: "bind_keys"},
 				{ID: "classes"},
 				{ID: "scroll_into_view"},

site/static/md/examples/ignore_attributes.md

@@ -0,0 +1,29 @@
+## Ignore Attributes
+
+## Demo
+
+<div data-signals-foo="'A valid signal'" class="text-primary">
+  <div data-star-ignore__self data-text="$notASignal">
+    <div data-text="$foo"></div>
+  </div>
+</div>
+
+## Explanation
+
+```html
+<div data-signals-foo="'A valid signal'">
+  <div data-star-ignore__self data-text="$notASignal">
+    <div data-text="$foo"></div>
+  </div>
+</div>
+```
+
+This demonstrates how adding the `data-star-ignore__self` attribute to an element prevents the element from being processed by Datastar.
+
+The `__self` modifier limits the behavior to the element itself. Removing the `__self` modifier would cause Datastar also ignore the descendant elements.
+
+```html
+<div data-star-ignore data-text="$notASignal">
+    <div data-text="$alsoNotASignal"></div>
+</div>
+```

site/static/md/reference/attribute_plugins.md

@@ -388,10 +388,16 @@ The signal name can be specified in the key (as above), or in the value (as belo
 
 ### `data-star-ignore`
 
-Datastar walks the entire DOM and applies plugins to each element it encounters. It's possible to tell Datastar to ignore an element by placing a `data-star-ignore` attribute on it. This can be useful for preventing naming conflicts with third-party libraries.
+Datastar walks the entire DOM and applies plugins to each element it encounters. It's possible to tell Datastar to ignore an element and its descendants by placing a `data-star-ignore` attribute on it. This can be useful for preventing naming conflicts with third-party libraries.
 
 ```html
 <div data-star-ignore data-show-thirdpartylib>
-  This element’s attributes will not be processed by Datastar.
+  <div data-show-thirdpartylib>
+    These element will not be processed by Datastar.
+  </div>
 </div>
 ```
+
+#### Modifiers
+
+- `__self` - Only ignore the element itself, not its descendants.