@mschop/alpine-web-components 1.0.9 → 1.0.10

package/AlpineWebComponent.ts

@@ -81,7 +81,7 @@ abstract class AlpineWebComponent extends HTMLElement {
         let state = this.state;
 
         // @ts-ignore
-        state.component = this;
+        state.component = this.markRaw(this);
 
         if (typeof state.attributes === 'undefined') {
             state.attributes = {};
@@ -92,6 +92,17 @@ abstract class AlpineWebComponent extends HTMLElement {
         this.state = Alpine.reactive(state);
     }
 
+    protected markRaw<T>(value: T): T {
+        if (value !== null && typeof value === 'object') {
+            Object.defineProperty(value, '__v_skip', {
+                value: true,
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        return value;
+    }
+
     protected bootAlpine() {
         // @ts-ignore
         Alpine.addScopeToNode(this.getRoot(), this.state)
@@ -163,4 +174,4 @@ document.addEventListener('alpine:initialized', () => {
     AlpineWebComponent.isAlpineInitStarted = true
 })
 
-export default AlpineWebComponent
+export default AlpineWebComponent

package/README.md

@@ -47,4 +47,33 @@ window.customElements.define('my-counter', Counter);
 
 You should now be able to reference the counter with `<my-counter></my-counter>`
 
+The component instance is attached as `state.component` but marked raw, so Alpine won't proxy the full custom element. You can call component methods from the Alpine scope:
+
+```html
+<button @click="component.resetCounter()">Reset</button>
+```
+
 Please see directory `example` for example on how to bind / update attributes etc..
+
+## Attribute-based state (string-only, isolated)
+
+The default behavior mirrors component state to HTML attributes (and reads attributes back into state). This keeps the component interface purely declarative and works well for primitives (string/number/boolean).
+
+Key points:
+- Attributes are always strings, so complex data must be serialized (e.g. JSON) via `attributeCasts`.
+- When state changes, the attribute is updated and an `updated-<key>` event is emitted.
+- When an attribute changes externally, the component state is updated.
+
+This approach is useful when you want a clean HTML-only API and strict isolation between components. For complex data, consider property binding with `x-effect` (see section above).
+
+## Passing complex data (avoid JSON in attributes)
+
+Attributes are strings, so passing objects requires JSON encoding/decoding. If you want to share complex data (objects, arrays, reactive proxies) between components, bind a **property** instead of an attribute.
+
+Alpine's `x-effect` runs once on init and re-runs when dependencies change, so you can declaratively sync a property without serialization:
+
+```html
+<my-child x-effect="$el.state.shared = parentState"></my-child>
+```
+
+This keeps the template declarative while passing the actual object reference. Use attributes for primitives and properties for complex data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mschop/alpine-web-components",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "Use alpinejs with web components and shadow root",
   "main": "index.js",
   "scripts": {