@mschop/alpine-web-components 1.0.9 → 2.0.0

package/AlpineWebComponent.ts

@@ -20,6 +20,7 @@ export interface State {
 abstract class AlpineWebComponent extends HTMLElement {
 
     public static isAlpineInitStarted: boolean = false
+    private isInitialized: boolean = false
     protected state: State = {attributes: {}}
     protected abstract template: string
     protected styles: () => string = () => ``
@@ -33,15 +34,11 @@ abstract class AlpineWebComponent extends HTMLElement {
         }
     }
 
-    public connectedCallback() {
-        if (AlpineWebComponent.isAlpineInitStarted) {
-            this.init()
-        } else {
-            document.addEventListener('alpine:init', this.alpineInitHandler);
-        }
-    }
-
     public init() {
+        if (this.isInitialized) {
+            return;
+        }
+        this.isInitialized = true;
         AlpineWebComponent.isAlpineInitStarted = true
 
         this.loadTemplate();
@@ -81,7 +78,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 +89,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)
@@ -136,6 +144,21 @@ abstract class AlpineWebComponent extends HTMLElement {
         })
     }
 
+    protected initChildren(): void {
+        const root = this.getRoot();
+        if (root === null) {
+            return;
+        }
+        root.querySelectorAll('*').forEach((node) => {
+            if (node === this) {
+                return;
+            }
+            if (node instanceof AlpineWebComponent) {
+                node.init();
+            }
+        });
+    }
+
     protected updateAttribute(key: string): void
     {
         const newValue = this.castToAttribute(key, this.state.attributes[key]);
@@ -163,4 +186,4 @@ document.addEventListener('alpine:initialized', () => {
     AlpineWebComponent.isAlpineInitStarted = true
 })
 
-export default AlpineWebComponent
+export default AlpineWebComponent

package/README.md

@@ -5,7 +5,7 @@ This library helps you with using AlpineJS with web components. This includes we
 ## Install
 
 1. Make sure you have AlpineJS installed and ready.
-2. Install this library by running  `npm i alpine-web-components`
+2. Install this library by running  `npm i @mschop/alpine-web-components`
 3. Use classes AlpineWebComponent or AlpineComponent as base classes.
 
 ## How to use it
@@ -45,6 +45,37 @@ class Counter extends AlpineWebComponent {
 window.customElements.define('my-counter', Counter);
 ```
 
-You should now be able to reference the counter with `<my-counter></my-counter>`
+You should now be able to reference the counter with `<my-counter></my-counter>`.
+
+Note: components do not auto-initialize on connect. Call `init()` on your top-level component when you want Alpine to boot. Sub-components will be automatically initialized.
+
+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": "2.0.0",
   "description": "Use alpinejs with web components and shadow root",
   "main": "index.js",
   "scripts": {