@wcstack/storage 1.17.0 → 1.19.0

package/README.ja.md

@@ -52,7 +52,12 @@ npm install @wcstack/storage
 
 <wcs-state>
   <script type="module">
-    export default { username: "" };
+    export default {
+      // 意図的に undefined — "" や null で初期化すると双方向バインディング
+      // 経由で書き戻され、リロードのたびに保存値を上書きしてしまう
+      // （下記「5. load-before-bind」参照）
+      username: undefined,
+    };
   </script>
 </wcs-state>
 
@@ -67,6 +72,7 @@ npm install @wcstack/storage
 - `key` を設定すると接続時に自動読み込み
 - `value` にバインドすると双方向永続化
 - 任意で `loading`、`error` もバインド
+- バインドする state スロットは `undefined` で開始する — 完全な idiom は「5. load-before-bind」を参照
 
 ### 2. オブジェクトの永続化と `$trackDependency`
 
@@ -137,7 +143,10 @@ localStorage の変更は、別のタブからの更新も自動的に検知さ
 ```html
 <wcs-state>
   <script type="module">
-    export default { sharedCounter: 0 };
+    export default {
+      // 意図的に undefined — 下記「5. load-before-bind」参照
+      sharedCounter: undefined,
+    };
   </script>
 </wcs-state>
 
@@ -151,6 +160,49 @@ localStorage の変更は、別のタブからの更新も自動的に検知さ
 
 > **注意**: `storage` イベントは同一オリジンの他のタブでの変更時にのみ発火します。sessionStorage はタブ間で共有されないため、クロスタブ同期は localStorage でのみ動作します。
 
+### 5. load-before-bind: 永続スロットの idiom
+
+`<wcs-storage>` は自身の `connectedCallback` で永続値をロードして通知します。スクリプトのロード状況によっては、これは `<wcs-state>` のバインディング確立**前**に起こりえます — 帰結は 2 つ:
+
+1. **上書き消去（clobber）**: バインドした state スロットが `""` / `0` / `null` / `[]` で始まると、初期の state→element 適用がその値を `value` に書き込み、write-through 保存が**リロードのたびに永続データを上書き**します。
+2. **ロードの取り逃し**: ロード完了を知らせる value イベントが誰も聴いていない間に発火し、state スロットが初期値のまま残ることがあります。
+
+両方を塞ぐ idiom:
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      // 1. undefined =「無意見」: 初期適用がスキップされ、
+      //    永続値が上書きされることはない
+      todos: undefined,
+      // 読み出しは正規化 getter 経由
+      get list() {
+        return Array.isArray(this.todos) ? this.todos : [];
+      },
+      // 2. <wcs-storage> がロード済みの値を一度だけ pull する
+      $connectedCallback() {
+        (async () => {
+          await customElements.whenDefined("wcs-storage");
+          const el = document.querySelector("wcs-storage");
+          if (!el) return;
+          await el.connectedCallbackPromise;
+          if (!Array.isArray(this.todos) && Array.isArray(el.value)) {
+            this.todos = el.value;
+          }
+        })();
+      },
+    };
+  </script>
+</wcs-state>
+
+<wcs-storage key="todos" type="local" data-wcs="value: todos"></wcs-storage>
+```
+
+- 原則: **`value` に双方向バインドする state スロットは `undefined` で開始する** — `""` / `0` / `null` / `[]` にしない。
+- `$connectedCallback` の pull が必要なのは、永続値を初回描画で表示したい場合だけです。ユーザー操作後にしか書かないスロットなら `undefined` だけで十分です。
+- 動作する実例: `examples/state-cross-tab-todo`、`examples/state-color-palette`。
+
 ## ステートサーフェス vs コマンドサーフェス
 
 `<wcs-storage>` は 2 種類のプロパティを公開します。
@@ -417,6 +469,7 @@ interface WcsStorageValues<T = unknown> extends WcsStorageCoreValues<T> {
 - `value` が状態パスにバインドされ、UI に反映
 - ユーザーが UI を操作すると状態が変わり、自動的にストレージに書き戻し
 - リロードしても状態が復元される
+- バインドするスロットは `undefined` で開始する（クイックスタート 5）ため、リロードが保存値を上書きしない
 
 永続化が通常の状態更新と同じように見えるようになります。
 

package/README.md

@@ -51,7 +51,12 @@ Primitive values (strings, numbers, booleans) work with just a `value` binding f
 
 <wcs-state>
   <script type="module">
-    export default { username: "" };
+    export default {
+      // undefined on purpose — a "" / null initial would be written back
+      // through the two-way binding and overwrite the saved value on
+      // reload (see "5. Load-before-bind" below)
+      username: undefined,
+    };
   </script>
 </wcs-state>
 
@@ -66,6 +71,7 @@ This is the default mode:
 - Set a `key` to auto-load on connection
 - Bind to `value` for two-way persistence
 - Optionally bind `loading` and `error` as well
+- Start the bound state slot as `undefined` — see [5. Load-before-bind](#5-load-before-bind-the-persistent-slot-idiom) for the full idiom
 
 ### 2. Persisting objects with `$trackDependency`
 
@@ -136,7 +142,10 @@ localStorage changes are automatically detected from other tabs:
 ```html
 <wcs-state>
   <script type="module">
-    export default { sharedCounter: 0 };
+    export default {
+      // undefined on purpose — see "5. Load-before-bind" below
+      sharedCounter: undefined,
+    };
   </script>
 </wcs-state>
 
@@ -150,6 +159,49 @@ localStorage changes are automatically detected from other tabs:
 
 > **Note**: The `storage` event only fires for changes made in other tabs of the same origin. Since sessionStorage is not shared across tabs, cross-tab sync only works with localStorage.
 
+### 5. Load-before-bind: the persistent-slot idiom
+
+`<wcs-storage>` loads and announces the persisted value in its own `connectedCallback`. Depending on script loading, that can happen **before** `<wcs-state>` finishes attaching its bindings — with two consequences:
+
+1. **Clobber**: if the bound state slot starts as `""` / `0` / `null` / `[]`, the initial state→element apply writes that value into `value`, and the write-through save **overwrites the persisted data on every reload**.
+2. **Missed load**: the value event announcing the loaded data fired before anyone was listening, so the state slot can stay at its initial value.
+
+The idiom that closes both:
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      // 1. undefined = "no opinion": the initial apply is skipped,
+      //    so the persisted value is never clobbered
+      todos: undefined,
+      // reads go through a normalizing getter
+      get list() {
+        return Array.isArray(this.todos) ? this.todos : [];
+      },
+      // 2. pull the value <wcs-storage> already loaded, once
+      $connectedCallback() {
+        (async () => {
+          await customElements.whenDefined("wcs-storage");
+          const el = document.querySelector("wcs-storage");
+          if (!el) return;
+          await el.connectedCallbackPromise;
+          if (!Array.isArray(this.todos) && Array.isArray(el.value)) {
+            this.todos = el.value;
+          }
+        })();
+      },
+    };
+  </script>
+</wcs-state>
+
+<wcs-storage key="todos" type="local" data-wcs="value: todos"></wcs-storage>
+```
+
+- Rule of thumb: **a state slot bound two-way to `value` must start as `undefined`** — never `""` / `0` / `null` / `[]`.
+- The `$connectedCallback` pull is only needed when the persisted value must render on first paint. If the slot is only ever written after user interaction, `undefined` alone is enough.
+- Working examples: `examples/state-cross-tab-todo`, `examples/state-color-palette`.
+
 ## State Surface vs Command Surface
 
 `<wcs-storage>` exposes two kinds of properties.
@@ -416,6 +468,7 @@ interface WcsStorageValues<T = unknown> extends WcsStorageCoreValues<T> {
 - `value` is bound to a state path, reflected in the UI
 - User interactions update state, which auto-saves back to storage
 - State survives page reloads
+- The bound slot starts as `undefined` (Quick Start 5), so a reload never overwrites what was saved
 
 Persistence looks just like any other state update.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wcstack/storage",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "Declarative persistent storage component for Web Components. Framework-agnostic localStorage/sessionStorage via wc-bindable-protocol.",
   "type": "module",
   "main": "./dist/index.esm.js",