@wcstack/state 1.6.4 → 1.7.0

package/README.ja.md

@@ -1015,6 +1015,106 @@ customElements.define("my-component", MyComponent);
 </template>
 ```
 
+## 宣言的カスタムコンポーネント (DCC)
+
+JavaScript のクラス定義なしで、**HTML だけ**でカスタム要素を定義できます。`data-wc-definition` と Declarative Shadow DOM (`<template shadowrootmode>`) を使い、リアクティブな状態を持つ再利用可能なコンポーネントをインラインで宣言します。
+
+### 基本的な定義
+
+```html
+<!-- 1. コンポーネントを定義（CSSで非表示） -->
+<my-counter data-wc-definition>
+  <template shadowrootmode="open">
+    <p>{{ count }}</p>
+    <button data-wcs="onclick: increment">+1</button>
+    <wcs-state>
+      <script type="module">
+        export default {
+          count: 0,
+          increment() { this.count++; },
+          $bindables: ["count"]
+        };
+      </script>
+    </wcs-state>
+  </template>
+</my-counter>
+
+<!-- 2. 使う — 各インスタンスが独自の状態を持つ -->
+<my-counter></my-counter>
+<my-counter></my-counter>
+```
+
+`<wcs-state>` が `data-wc-definition` 付きのホスト内にあることを検出すると：
+
+1. 状態オブジェクトをロード（`<script type="module">` または `src="*.js"`）
+2. getter/setter/メソッドをプロトタイプに定義したカスタム要素クラスを生成
+3. `customElements.define()` で登録
+
+定義要素は非表示になり、各インスタンスはテンプレートを自身の Shadow DOM にクローンして、独自の `<wcs-state>` を初期化します。
+
+### 推奨 CSS
+
+```css
+:not(:defined) { display: none; }
+[data-wc-definition] { display: none; }
+```
+
+### `$bindables` と wc-bindable プロトコル
+
+`$bindables` 配列は、変更イベント付きのコンポーネントプロパティとして公開する状態プロパティを宣言します。[wc-bindable プロトコル](https://github.com/nicenemo/nicenemo/blob/main/docs/wc-bindable-protocol.md)に準拠しています：
+
+```javascript
+export default {
+  count: 0,
+  increment() { this.count++; },
+  $bindables: ["count"]
+};
+```
+
+これにより以下が生成されます：
+
+- クラスの `static wcBindable` — フレームワークアダプタ用のプロトコルメタデータ
+- プロトタイプの getter/setter — リアクティブプロキシ経由で読み書き
+- `CustomEvent` のディスパッチ — 値が変更されるたびに `my-counter:count-changed` が発火
+
+### DCC プロパティへのバインディング
+
+他の `<wcs-state>` インスタンスから、通常の Web Component と同じように DCC プロパティにバインドできます：
+
+```html
+<my-counter data-wcs="count: parentCount"></my-counter>
+
+<wcs-state>
+  <script type="module">
+    export default { parentCount: 0 };
+  </script>
+</wcs-state>
+<div data-wcs="textContent: parentCount"></div>
+```
+
+### Shadow Root モード
+
+`open` と `closed` の両モードに対応しています：
+
+```html
+<my-component data-wc-definition>
+  <template shadowrootmode="closed">
+    <!-- closed shadow DOM -->
+  </template>
+</my-component>
+```
+
+### 内部プロパティ
+
+`$` プレフィックス付きのプロパティは内部用で、コンポーネントのプロトタイプには公開されません：
+
+| プロパティ | 用途 |
+|----------|---------|
+| `$bindables` | 観測可能プロパティの宣言 |
+| `$connectedCallback` | ライフサイクルフック（各インスタンスで実行） |
+| `$disconnectedCallback` | クリーンアップフック |
+| `$updatedCallback` | 状態変更後に呼ばれる |
+
 ## SVG サポート
 
 全てのバインディングが `<svg>` 要素内で動作します。SVG 属性には `attr.*` を使用します：

package/README.md

@@ -1015,6 +1015,106 @@ customElements.define("my-component", MyComponent);
 </template>
 ```
 
+## Declarative Custom Components (DCC)
+
+Define custom elements **entirely in HTML** — no JavaScript class definition needed. Using `data-wc-definition` and Declarative Shadow DOM (`<template shadowrootmode>`), you can declare reusable components with reactive state inline.
+
+### Basic Definition
+
+```html
+<!-- 1. Define the component (hidden by CSS) -->
+<my-counter data-wc-definition>
+  <template shadowrootmode="open">
+    <p>{{ count }}</p>
+    <button data-wcs="onclick: increment">+1</button>
+    <wcs-state>
+      <script type="module">
+        export default {
+          count: 0,
+          increment() { this.count++; },
+          $bindables: ["count"]
+        };
+      </script>
+    </wcs-state>
+  </template>
+</my-counter>
+
+<!-- 2. Use it — each instance gets its own state -->
+<my-counter></my-counter>
+<my-counter></my-counter>
+```
+
+When `<wcs-state>` detects it is inside a `data-wc-definition` host, it:
+
+1. Loads the state object (from `<script type="module">` or `src="*.js"`)
+2. Generates a custom element class with getter/setter/method properties on the prototype
+3. Registers it via `customElements.define()`
+
+The definition element is hidden; each instance clones the template into its own Shadow DOM and initializes its own `<wcs-state>`.
+
+### Recommended CSS
+
+```css
+:not(:defined) { display: none; }
+[data-wc-definition] { display: none; }
+```
+
+### `$bindables` and wc-bindable Protocol
+
+The `$bindables` array declares which state properties are exposed as component properties with change events, following the [wc-bindable protocol](https://github.com/nicenemo/nicenemo/blob/main/docs/wc-bindable-protocol.md):
+
+```javascript
+export default {
+  count: 0,
+  increment() { this.count++; },
+  $bindables: ["count"]
+};
+```
+
+This generates:
+
+- `static wcBindable` on the class — protocol metadata for framework adapters
+- Getter/setter on the prototype — reads/writes go through the reactive proxy
+- `CustomEvent` dispatch — `my-counter:count-changed` fires on every mutation
+
+### Binding to DCC Properties
+
+Other `<wcs-state>` instances can bind to DCC properties just like any Web Component:
+
+```html
+<my-counter data-wcs="count: parentCount"></my-counter>
+
+<wcs-state>
+  <script type="module">
+    export default { parentCount: 0 };
+  </script>
+</wcs-state>
+<div data-wcs="textContent: parentCount"></div>
+```
+
+### Shadow Root Mode
+
+Both `open` and `closed` modes are supported:
+
+```html
+<my-component data-wc-definition>
+  <template shadowrootmode="closed">
+    <!-- closed shadow DOM -->
+  </template>
+</my-component>
+```
+
+### Internal Properties
+
+Properties prefixed with `$` are internal and not exposed on the component prototype:
+
+| Property | Purpose |
+|----------|---------|
+| `$bindables` | Declares observable properties |
+| `$connectedCallback` | Lifecycle hook (runs on each instance) |
+| `$disconnectedCallback` | Cleanup hook |
+| `$updatedCallback` | Called after state mutations |
+
 ## SVG Support
 
 All bindings work inside `<svg>` elements. Use `attr.*` for SVG attributes:

package/dist/index.esm.js

@@ -59,7 +59,7 @@ function setConfig(partialConfig) {
     }
 }
 
-var version$1 = "1.6.4";
+var version$1 = "1.7.0";
 var pkg = {
 	version: version$1};
 
@@ -186,6 +186,8 @@ const STATE_CONNECTED_CALLBACK_NAME = "$connectedCallback";
 const STATE_DISCONNECTED_CALLBACK_NAME = "$disconnectedCallback";
 const STATE_UPDATED_CALLBACK_NAME = "$updatedCallback";
 const WEBCOMPONENT_STATE_READY_CALLBACK_NAME = "$stateReadyCallback";
+const STATE_BINDABLES_NAME = "$bindables";
+const DCC_DEFINITION_ATTRIBUTE = "data-wc-definition";
 
 const _cache$4 = new Map();
 let id = 0;
@@ -4819,6 +4821,153 @@ function createLoopContextStack() {
     return new LoopContextStack();
 }
 
+function getterFn(name) {
+    return function () {
+        const stateEl = this.stateElement;
+        if (!stateEl)
+            return undefined;
+        let value;
+        try {
+            stateEl.createState("readonly", (state) => {
+                value = state[name];
+            });
+        }
+        catch {
+            return undefined;
+        }
+        return value;
+    };
+}
+function setterFn(name) {
+    return function (value) {
+        const stateEl = this.stateElement;
+        if (!stateEl)
+            return;
+        stateEl.initializePromise.then(() => {
+            stateEl.createState("writable", (state) => {
+                state[name] = value;
+            });
+        });
+    };
+}
+function callFn(name, isAsync) {
+    if (isAsync) {
+        return function (...args) {
+            const stateEl = this.stateElement;
+            if (!stateEl)
+                return;
+            return stateEl.initializePromise.then(() => {
+                return stateEl.createStateAsync("writable", async (state) => {
+                    await state[name](...args);
+                });
+            });
+        };
+    }
+    return function (...args) {
+        const stateEl = this.stateElement;
+        if (!stateEl)
+            return;
+        stateEl.initializePromise.then(() => {
+            stateEl.createState("writable", (state) => {
+                state[name](...args);
+            });
+        });
+    };
+}
+function isInternalProperty(name) {
+    return name.startsWith("$");
+}
+
+function createWcBindable(tagName, bindables) {
+    const properties = bindables.map((propName) => ({
+        name: propName,
+        event: `${tagName}:${propName}-changed`,
+    }));
+    return {
+        protocol: "wc-bindable",
+        version: 1,
+        properties,
+    };
+}
+function createBindableEventMap(tagName, bindables) {
+    const map = {};
+    for (const propName of bindables) {
+        map[propName] = `${tagName}:${propName}-changed`;
+    }
+    return map;
+}
+
+function defineDCC(hostElement, shadowRoot, state) {
+    const tagName = hostElement.tagName.toLowerCase();
+    // バリデーション
+    if (!tagName.includes("-")) {
+        raiseError(`DCC: "${tagName}" is not a valid custom element name (must contain a hyphen).`);
+    }
+    if (customElements.get(tagName)) {
+        // 既に登録済みならスキップ
+        return;
+    }
+    // ShadowRoot は cloneNode 不可のため、template 経由で内容をクローン
+    const template = document.createElement("template");
+    template.innerHTML = shadowRoot.innerHTML;
+    const shadowRootMode = shadowRoot.mode;
+    // $bindables から wcBindable + bindableEventMap を生成
+    const bindables = Array.isArray(state[STATE_BINDABLES_NAME])
+        ? state[STATE_BINDABLES_NAME]
+        : [];
+    const wcBindable = bindables.length > 0
+        ? createWcBindable(tagName, bindables)
+        : null;
+    const bindableEventMap = bindables.length > 0
+        ? createBindableEventMap(tagName, bindables)
+        : {};
+    // DCC クラス生成
+    const stateTagSelector = `${config.tagNames.state}:not([name])`;
+    const DCCElement = class extends HTMLElement {
+        static template = template;
+        static shadowRootMode = shadowRootMode;
+        static wcBindable = wcBindable;
+        static bindableEventMap = bindableEventMap;
+        _shadow = null;
+        connectedCallback() {
+            if (this.hasAttribute(DCC_DEFINITION_ATTRIBUTE))
+                return;
+            this._shadow = this.attachShadow({ mode: DCCElement.shadowRootMode });
+            this._shadow.appendChild(DCCElement.template.content.cloneNode(true));
+            // bindableEventMap の設定
+            if (Object.keys(DCCElement.bindableEventMap).length > 0) {
+                const stateEl = this._shadow.querySelector(stateTagSelector);
+                if (stateEl) {
+                    stateEl.initializePromise.then(() => {
+                        stateEl.setBindableEventMap(DCCElement.bindableEventMap);
+                    });
+                }
+            }
+        }
+        get stateElement() {
+            return this._shadow?.querySelector(stateTagSelector);
+        }
+    };
+    // state プロパティを走査して DCC クラスのプロトタイプにgetter/setter/methodを定義
+    const descriptors = Object.getOwnPropertyDescriptors(state);
+    for (const [name, desc] of Object.entries(descriptors)) {
+        if (isInternalProperty(name))
+            continue;
+        const newDesc = { configurable: true, enumerable: true };
+        if (typeof desc.value === "function") {
+            const isAsync = desc.value.constructor?.name === "AsyncFunction";
+            newDesc.value = callFn(name, isAsync);
+        }
+        else {
+            newDesc.get = getterFn(name);
+            newDesc.set = setterFn(name);
+        }
+        Object.defineProperty(DCCElement.prototype, name, newDesc);
+    }
+    // カスタム要素登録
+    customElements.define(tagName, DCCElement);
+}
+
 /**
  * Cache for resolved path information.
  * Uses Map to safely handle property names including reserved words like "constructor" and "toString".
@@ -5470,6 +5619,17 @@ function setByAddress(target, address, value, receiver, handler) {
                 dirty: false
             });
         }
+        // DCC bindable イベントディスパッチ
+        const eventName = stateElement.bindableEventMap[address.pathInfo.path];
+        if (eventName) {
+            const rootNode = stateElement.rootNode;
+            if (rootNode instanceof ShadowRoot) {
+                rootNode.host.dispatchEvent(new CustomEvent(eventName, {
+                    detail: value,
+                    bubbles: true,
+                }));
+            }
+        }
     }
 }
 
@@ -6469,6 +6629,7 @@ class State extends HTMLElement {
     _rootNode = null;
     _boundComponent = null;
     _boundComponentStateProp = null;
+    _bindableEventMap = {};
     constructor() {
         super();
         this._initializePromise = new Promise((resolve) => {
@@ -6627,6 +6788,37 @@ class State extends HTMLElement {
             }
         });
     }
+    async _initializeDCC(hostElement, shadowRoot) {
+        let state;
+        try {
+            if (this.hasAttribute('src')) {
+                const src = this.getAttribute('src');
+                if (src.endsWith('.js')) {
+                    state = await loadFromScriptFile(src);
+                }
+                else {
+                    raiseError(`DCC: Unsupported src type: ${src}`);
+                }
+            }
+            else {
+                const script = this.querySelector('script[type="module"]');
+                if (script) {
+                    state = await loadFromInnerScript(script, hostElement.tagName.toLowerCase());
+                }
+                else {
+                    raiseError(`DCC: No state source found for "${hostElement.tagName.toLowerCase()}".`);
+                }
+            }
+        }
+        catch (e) {
+            raiseError(`DCC: Failed to load state: ${e}`);
+        }
+        defineDCC(hostElement, shadowRoot, state);
+        this._initialized = true;
+        this._rootNode = null; // disconnectedCallbackでのstate参照を防止
+        this._resolveInitialize?.();
+        this._resolveConnectedCallback?.();
+    }
     _callStateDisconnectedCallback() {
         this.createState("writable", (state) => {
             // stateに"$disconnectedCallback"があるか確認し、disconnectedCallbackAPIを呼び出す
@@ -6638,6 +6830,13 @@ class State extends HTMLElement {
     async connectedCallback() {
         this._rootNode = this.getRootNode();
         if (!this._initialized) {
+            // DCC 検出: ShadowRoot 内かつホストに data-wc-definition がある場合
+            const parentNode = this.parentNode;
+            if (parentNode instanceof ShadowRoot &&
+                parentNode.host.hasAttribute(DCC_DEFINITION_ATTRIBUTE)) {
+                await this._initializeDCC(parentNode.host, parentNode);
+                return;
+            }
             await this._initializeBindWebComponent();
             await this._initialize();
             this._initialized = true;
@@ -6707,6 +6906,12 @@ class State extends HTMLElement {
     get boundComponentStateProp() {
         return this._boundComponentStateProp;
     }
+    get bindableEventMap() {
+        return this._bindableEventMap;
+    }
+    setBindableEventMap(map) {
+        this._bindableEventMap = map;
+    }
     _addDependency(map, sourcePath, targetPath) {
         const deps = map.get(sourcePath);
         if (deps === undefined) {