@wcstack/notification 1.13.1

package/README.ja.md

@@ -0,0 +1,185 @@
+# @wcstack/notification
+
+`@wcstack/notification` は wcstack エコシステム向けのヘッドレスなデスクトップ通知コンポーネントです。
+
+ビジュアルな UI ウィジェットではありません。
+Notifications API をリアクティブな state と state 駆動のコマンドに変換する**非同期プリミティブノード**です —— `@wcstack/geolocation` がデバイスの位置をリアクティブな state に変えるのと同じ発想です。
+
+`@wcstack/state` と組み合わせると、`<wcs-notify>` はパス契約で直接バインドできます:
+
+- **command サーフェス**: `request`, `notify`, `close`, `closeAll`
+- **input サーフェス**: `notice`（reactive な表示）, `mode`, `body`, `icon`, `badge`, `tag`, `lang`, `dir`, `require-interaction`, `silent`, `renotify`
+- **output state サーフェス**: `permission`, `granted`, `denied`, `prompt`, `unsupported`, `error`, `clicked`, `closed`, `shown`
+
+`@wcstack/notification` は [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います:
+
+- **Core**（`NotificationCore`）が権限・表示（コンストラクタ or Service Worker）・クリック中継を担う
+- **Shell**（`<wcs-notify>`）がそれを DOM 属性・reactive な `notice` 入力・ライフサイクルに接続する
+- **Binding Contract**（`static wcBindable`）が observable な `properties`・`inputs`・`commands` を宣言する
+
+## なぜ存在するか —— 双方向が 1 つのタグで完結
+
+多くの wcstack IO ノードは片方向に寄っています: `<wcs-permission>` は*監視*のみ（Permissions API に `request()` が無いのでコマンドが無い）、`<wcs-speak>`/`<wcs-listen>` は双対を 2 タグに分割します。Notifications API は違い、**1 つの API で本当に双方向**です:
+
+- **表示**はコマンド（state → 要素）: `notify(title, options)`。
+- **クリック / クローズ / 表示**はイベント（要素 → state）: ユーザーが OS 通知を操作する。
+
+つまり `<wcs-notify>` は **command-token**（表示）と **event-token**（クリック）が 1 つのタグに同居する wcstack 初のノードです。さらに `<wcs-permission>` と違い Notifications API には `Notification.requestPermission()` があるため、このノードは**自己完結**します —— 権限の要求/監視と通知の表示を両方担います。
+
+> **secure context が必要。** Notifications API は secure context（HTTPS か `localhost`）でのみ動作します。利用できない環境では `<wcs-notify>` は throw せず `permission = "unsupported"` を報告します。権限要求と表示は通常ユーザージェスチャを要するため、タイマーから `notify` を撃っても何も表示されないことがあります。
+
+## インストール
+
+```bash
+npm install @wcstack/notification
+```
+
+## クイックスタート
+
+### 1. 要求してから表示する —— state から
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/notification/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["request", "notify"],
+      $eventTokens: ["opened"],
+      ask()  { this.$command.request.emit(); },
+      send() { this.$command.notify.emit("New message", { body: "Tap to open", tag: "chat", data: { room: 7 } }); },
+      $on: {
+        opened: (state, event) => { console.log("clicked", event.detail); }, // { tag, data, action }
+      },
+    };
+  </script>
+</wcs-state>
+
+<wcs-notify data-wcs="
+  command.request: $command.request;
+  command.notify:  $command.notify;
+  eventToken.clicked: opened
+"></wcs-notify>
+
+<button data-wcs="onclick: ask">Allow notifications</button>
+<button data-wcs="onclick: send">New message</button>
+```
+
+`notify.emit(title, options)` の位置引数はそのまま `notify(title, options)` へ素通しされます —— `<wcs-speak>`/`<wcs-fetch>` と同じ引数転送契約です。
+
+### 2. reactive な `notice` と 命令的な `notify`
+
+```html
+<!-- reactive: 束縛値が「変化」したときに表示（same-value ガードつき）。 -->
+<wcs-notify data-wcs="notice: statusMessage | debounce(1000)"></wcs-notify>
+```
+
+`notice` は `notify` の宣言的カウンターパートです: 変化した値を書くと表示し、同値の書き込みは抑制します。命令的な `notify` コマンドは毎回（同じテキストでも）発火します。state 変化のたびに自動発火すると通知スパムの危険があるため、束縛元を debounce し、`tag` を付けて OS 側で de-dup させるとよいです。
+
+### 3. 権限をバインド可能な state として
+
+```html
+<wcs-notify data-wcs="permission: notifyPerm; granted: canNotify"></wcs-notify>
+
+<!-- ブール 1 つでノードから直接 -->
+<div data-wcs="hidden: canNotify">通知を許可してアラートを受け取ってください。</div>
+```
+
+`permission` は `"prompt"` / `"granted"` / `"denied"` / `"unsupported"`。Notifications API 自身の `"default"` は `"prompt"` に正規化され、`@wcstack/permission` / `@wcstack/geolocation` と同じ 4 値サーフェスを共有します。
+
+### 4. クリックを読む
+
+`clicked` / `closed` / `shown` は `{ tag, data, action }` を運びます。`tag` は通知の識別子（あなたの `options.tag`、省略時は生成された `wcs-<n>`）、`data` は `options.data` に渡した値、`action` は Service Worker のアクションボタン id（コンストラクタ経路では常に `""`）です。
+
+完全なデモは `examples/state-notification-chat` を参照。
+
+## Service Worker / モバイル
+
+`new Notification()` はデスクトップでのみ動作します。Android Chrome では throw し、`ServiceWorkerRegistration.showNotification()` が必須です。`<wcs-notify>` は `mode` で経路を選びます:
+
+| `mode`        | 挙動                                                                              |
+| ------------- | --------------------------------------------------------------------------------- |
+| `auto`（既定）| `Notification` コンストラクタを試し、`TypeError`（モバイル）なら SW にフォールバック。 |
+| `constructor` | コンストラクタのみ。`TypeError` は `error` として表面化（フォールバック無し）。    |
+| `sw`          | 常に `ServiceWorkerRegistration.showNotification()`。                             |
+
+SW の `notificationclick` は**あなたの** Service Worker 内で発火し、本パッケージはそこにコードを注入できません。1 行のヘルパを import してクリックをページへ中継してください:
+
+```js
+// あなたの sw.js
+import { wireNotificationClicks } from "@wcstack/notification/sw";
+wireNotificationClicks();
+```
+
+各クリックを `BroadcastChannel("wcs-notify")`（主）と `clients.postMessage`（フォールバック）で中継し、ページの `NotificationCore` が 2 経路を de-dup して `wcs-notify:click` を発火します。
+
+## 属性 / Inputs
+
+| 属性                  | 型      | 既定    | 説明                                                                        |
+| --------------------- | ------- | ------- | --------------------------------------------------------------------------- |
+| `mode`                | string  | `auto`  | 表示経路: `auto` / `sw` / `constructor`。                                   |
+| `body`                | string  | `""`    | 通知の本文。                                                                |
+| `icon`                | string  | `""`    | アイコン URL。                                                              |
+| `badge`               | string  | `""`    | バッジ URL（モノクロ・モバイル）。                                          |
+| `tag`                 | string  | `""`    | 通知タグ（同一タグの通知は OS が置換する）。                                |
+| `lang`                | string  | `""`    | 言語タグ。                                                                  |
+| `dir`                 | string  | `""`    | 文字方向: `auto` / `ltr` / `rtl`。                                          |
+| `require-interaction` | boolean | `false` | ユーザーが閉じるまで表示し続ける。                                          |
+| `silent`              | boolean | `false` | 音/バイブを抑制。                                                           |
+| `renotify`            | boolean | `false` | 同一タグ通知の置換時に再アラート。                                          |
+| `manual`              | boolean | `false` | reactive な `notice` 経路をミュート（`notify` コマンドは有効なまま）。      |
+
+`notice` は reactive な入力（属性なし）: 変化した値を書くと通知を表示します。`notify(title, options)` の per-call オプションはこれら属性既定値にキー単位で優先します。
+
+## Observable プロパティ（出力）
+
+| プロパティ    | イベント                       | 説明                                                              |
+| ------------- | ------------------------------ | ----------------------------------------------------------------- |
+| `permission`  | `wcs-notify:permission-change` | `"prompt"` / `"granted"` / `"denied"` / `"unsupported"`、live。    |
+| `granted` / `denied` / `prompt` / `unsupported` | `wcs-notify:permission-change` | `permission` から派生する便宜ブール。 |
+| `error`       | `wcs-notify:error`             | 失敗時の `{ error, message }`（never-throw）、無ければ `null`。    |
+| `clicked`     | `wcs-notify:click`             | 直近クリックの `{ tag, data, action }`（event-token 源）。        |
+| `closed`      | `wcs-notify:close`             | 直近クローズの `{ tag, data, action }`。                          |
+| `shown`       | `wcs-notify:show`              | 直近表示の `{ tag, data, action }`。                              |
+
+## コマンド
+
+| コマンド     | 説明                                                                              |
+| ------------ | --------------------------------------------------------------------------------- |
+| `request()`  | `Notification.requestPermission()`。正規化した権限状態を解決する。                |
+| `notify(title, options?)` | 通知を表示し、識別タグを返す。                                       |
+| `close(tag)` | `tag` の通知を閉じる。                                                            |
+| `closeAll()` | この要素が表示した全通知を閉じる。                                                |
+
+## 注意・制限
+
+- **通知はページより長生きする。** `<wcs-notify>` の切断（または Core の `dispose()`）は購読を解除しますが、開いている通知は**閉じません** —— 通知はページの終了後も残ることが意図です。閉じるには `close` / `closeAll` を使ってください。
+- **Push API はスコープ外。** 本パッケージは Notifications API（ローカル通知）をラップします。サーバ起点の Push は別の関心事です。
+- **サイレント失敗（zero-log）。** wcstack のゼロ依存哲学に沿い、`<wcs-notify>` は決してログ出力も throw もしません。API 不在 → `permission = "unsupported"`、未許可や表示失敗 → `error` プロパティ。`error` / `permission` をバインドして反応してください。
+- **SSR（`@wcstack/server`）。** `static hasConnectedCallbackPromise = true` を宣言し `connectedCallbackPromise` を公開するため、サーバレンダラは接続時の権限プローブが解決するまで待ってからスナップショットします。
+
+## ヘッドレス利用（`NotificationCore`）
+
+Core は DOM 依存が無く、`@wc-bindable/core` の `bind()` と直接使えます:
+
+```typescript
+import { NotificationCore } from "@wcstack/notification";
+
+const notify = new NotificationCore();
+await notify.observe();          // 権限 + クリック中継の監視を開始
+await notify.request();          // ユーザーに要求
+
+notify.addEventListener("wcs-notify:click", (e) => {
+  console.log((e as CustomEvent).detail); // { tag, data, action }
+});
+
+const tag = notify.notify("Hello", { body: "world", data: { room: 1 } });
+// あとで:
+notify.close(tag);
+notify.dispose();                // 購読を解除（開いている通知は残る）
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,189 @@
+# @wcstack/notification
+
+`@wcstack/notification` is a headless desktop-notification component for the wcstack ecosystem.
+
+It is not a visual UI widget.
+It is an **async primitive node** that turns the Notifications API into reactive state and a state-driven command — the same way `@wcstack/geolocation` turns the device's location into reactive state.
+
+With `@wcstack/state`, `<wcs-notify>` can be bound directly through path contracts:
+
+- **command surface**: `request`, `notify`, `close`, `closeAll`
+- **input surface**: `notice` (reactive show), `mode`, `body`, `icon`, `badge`, `tag`, `lang`, `dir`, `require-interaction`, `silent`, `renotify`
+- **output state surface**: `permission`, `granted`, `denied`, `prompt`, `unsupported`, `error`, `clicked`, `closed`, `shown`
+
+`@wcstack/notification` follows the [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md) (Core / Shell / Binding Contract) architecture:
+
+- **Core** (`NotificationCore`) handles permission, showing (constructor or Service Worker), and click relaying
+- **Shell** (`<wcs-notify>`) connects that to DOM attributes, the reactive `notice` input, and lifecycle
+- **Binding Contract** (`static wcBindable`) declares observable `properties`, `inputs`, and `commands`
+
+## Why this exists — both directions in one tag
+
+Most wcstack IO nodes lean one way: `<wcs-permission>` only *watches* (it has no commands, because the Permissions API has no `request()`); `<wcs-speak>`/`<wcs-listen>` split a duo across two tags. The Notifications API is different — it is genuinely **bidirectional in a single API**:
+
+- **show** is a command (state → element): `notify(title, options)`.
+- **click / close / show** are events (element → state): the user interacting with the OS notification.
+
+So `<wcs-notify>` is the first wcstack node where the **command-token** (show) and **event-token** (click) directions live together in one tag. And unlike `<wcs-permission>`, the Notifications API *does* have `Notification.requestPermission()`, so this node is **self-contained**: it both requests/monitors the permission and shows notifications.
+
+> **Secure context required.** The Notifications API only works in a secure context (HTTPS, or `localhost`). Where it is absent, `<wcs-notify>` reports `permission = "unsupported"` instead of throwing. Requesting permission and showing also typically require a user gesture — firing `notify` from a timer may show nothing.
+
+## Install
+
+```bash
+npm install @wcstack/notification
+```
+
+## Quick Start
+
+### 1. Ask, then show — from state
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/notification/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["request", "notify"],
+      $eventTokens: ["opened"],
+      ask()  { this.$command.request.emit(); },
+      send() { this.$command.notify.emit("New message", { body: "Tap to open", tag: "chat", data: { room: 7 } }); },
+      $on: {
+        opened: (state, event) => { console.log("clicked", event.detail); }, // { tag, data, action }
+      },
+    };
+  </script>
+</wcs-state>
+
+<wcs-notify data-wcs="
+  command.request: $command.request;
+  command.notify:  $command.notify;
+  eventToken.clicked: opened
+"></wcs-notify>
+
+<button data-wcs="onclick: ask">Allow notifications</button>
+<button data-wcs="onclick: send">New message</button>
+```
+
+The positional args of `notify.emit(title, options)` pass straight through to `notify(title, options)` — the same argument-forwarding contract used by `<wcs-speak>`/`<wcs-fetch>`.
+
+### 2. Reactive `notice` vs imperative `notify`
+
+```html
+<!-- reactive: shows whenever the bound value *changes* (same-value guard). -->
+<wcs-notify data-wcs="notice: statusMessage | debounce(1000)"></wcs-notify>
+```
+
+`notice` is the declarative counterpart of `notify`: writing a *changed* value shows it; an identical write is suppressed. The imperative `notify` command fires every call (even the same text). Auto-firing a notification on every state change risks spam, so debounce the bound source and prefer a `tag` so the OS de-dups.
+
+### 3. Permission as bindable state
+
+```html
+<wcs-notify data-wcs="permission: notifyPerm; granted: canNotify"></wcs-notify>
+
+<!-- one boolean, straight from the node -->
+<div data-wcs="hidden: canNotify">Allow notifications to get alerts.</div>
+```
+
+`permission` is `"prompt"` / `"granted"` / `"denied"` / `"unsupported"`. The Notifications API's own `"default"` is normalized to `"prompt"`, so this node shares the exact four-value surface of `@wcstack/permission` / `@wcstack/geolocation`.
+
+### 4. Reading the click
+
+```html
+<wcs-notify data-wcs="command.notify: $command.notify; eventToken.clicked: opened"></wcs-notify>
+```
+
+`clicked` / `closed` / `shown` carry `{ tag, data, action }`. `tag` identifies the notification (your `options.tag`, or a generated `wcs-<n>` when omitted); `data` is whatever you passed in `options.data`; `action` is the Service Worker action-button id (always `""` for the constructor backend).
+
+See `examples/state-notification-chat` for the full demo.
+
+## Service Worker / mobile
+
+`new Notification()` works on desktop only. On Android Chrome it throws, and `ServiceWorkerRegistration.showNotification()` is required. `<wcs-notify>` picks the backend per `mode`:
+
+| `mode`        | Behavior                                                                          |
+| ------------- | --------------------------------------------------------------------------------- |
+| `auto` (default) | Try the `Notification` constructor; on a `TypeError` (mobile), fall back to the SW. |
+| `constructor` | Constructor only; a `TypeError` surfaces as an `error` (no fallback).             |
+| `sw`          | Always `ServiceWorkerRegistration.showNotification()`.                            |
+
+The SW's `notificationclick` fires inside **your** Service Worker, which this package cannot inject into. Import the one-line helper so clicks relay back to the page:
+
+```js
+// your sw.js
+import { wireNotificationClicks } from "@wcstack/notification/sw";
+wireNotificationClicks();
+```
+
+It relays each click over `BroadcastChannel("wcs-notify")` (primary) and `clients.postMessage` (fallback); `NotificationCore` on the page de-dups the two transports and emits `wcs-notify:click`.
+
+## Attributes / Inputs
+
+| Attribute             | Type    | Default | Description                                                                 |
+| --------------------- | ------- | ------- | --------------------------------------------------------------------------- |
+| `mode`                | string  | `auto`  | Show backend: `auto` / `sw` / `constructor`.                                |
+| `body`                | string  | `""`    | Notification body text.                                                     |
+| `icon`                | string  | `""`    | Icon URL.                                                                   |
+| `badge`               | string  | `""`    | Badge URL (monochrome, mobile).                                             |
+| `tag`                 | string  | `""`    | Notification tag (the OS replaces a notification with the same tag).        |
+| `lang`                | string  | `""`    | Language tag.                                                               |
+| `dir`                 | string  | `""`    | Text direction: `auto` / `ltr` / `rtl`.                                     |
+| `require-interaction` | boolean | `false` | Keep the notification visible until the user dismisses it.                  |
+| `silent`              | boolean | `false` | Suppress sound/vibration.                                                   |
+| `renotify`            | boolean | `false` | Re-alert when replacing a same-tag notification.                            |
+| `manual`              | boolean | `false` | Mute the reactive `notice` path (the `notify` command still works).         |
+
+`notice` is a reactive input (no attribute): writing a changed value shows a notification. Per-call `notify(title, options)` options win per-key over these attribute defaults.
+
+## Observable Properties (outputs)
+
+| Property      | Event                          | Description                                                       |
+| ------------- | ------------------------------ | ----------------------------------------------------------------- |
+| `permission`  | `wcs-notify:permission-change` | `"prompt"` / `"granted"` / `"denied"` / `"unsupported"`, live.    |
+| `granted` / `denied` / `prompt` / `unsupported` | `wcs-notify:permission-change` | Convenience booleans derived from `permission`. |
+| `error`       | `wcs-notify:error`             | `{ error, message }` on a failure (never-throw), else `null`.     |
+| `clicked`     | `wcs-notify:click`             | `{ tag, data, action }` of the last click (event-token source).   |
+| `closed`      | `wcs-notify:close`             | `{ tag, data, action }` of the last close.                        |
+| `shown`       | `wcs-notify:show`              | `{ tag, data, action }` of the last shown notification.           |
+
+## Commands
+
+| Command      | Description                                                                       |
+| ------------ | --------------------------------------------------------------------------------- |
+| `request()`  | `Notification.requestPermission()`; resolves to the normalized permission state.  |
+| `notify(title, options?)` | Show a notification; returns its identifying tag.                    |
+| `close(tag)` | Dismiss the notification(s) with `tag`.                                           |
+| `closeAll()` | Dismiss every notification this element has shown.                                |
+
+## Notes & limitations
+
+- **Notifications outlive the page.** Disconnecting `<wcs-notify>` (or calling `dispose()` on the Core) detaches its subscriptions but does **not** close open notifications — a notification is meant to persist past the page. Use `close` / `closeAll` to dismiss.
+- **Push API is out of scope.** This package wraps the Notifications API (local notifications). Server-initiated Push is a separate concern.
+- **Silent failure handling (zero-log).** Consistent with wcstack's zero-dependency philosophy, `<wcs-notify>` never logs or throws. A missing API → `permission = "unsupported"`; a not-granted permission or a show failure → the `error` property. Bind `error` / `permission` to react.
+- **SSR (`@wcstack/server`).** Declares `static hasConnectedCallbackPromise = true` and exposes `connectedCallbackPromise`, so the server renderer waits for the connect-time permission probe before snapshotting.
+
+## Headless usage (`NotificationCore`)
+
+The Core has no DOM dependency and can be used directly with `bind()` from `@wc-bindable/core`:
+
+```typescript
+import { NotificationCore } from "@wcstack/notification";
+
+const notify = new NotificationCore();
+await notify.observe();          // start watching permission + click relays
+await notify.request();          // ask the user
+
+notify.addEventListener("wcs-notify:click", (e) => {
+  console.log((e as CustomEvent).detail); // { tag, data, action }
+});
+
+const tag = notify.notify("Hello", { body: "world", data: { room: 1 } });
+// later:
+notify.close(tag);
+notify.dispose();                // detach subscriptions (open notifications stay)
+```
+
+## License
+
+MIT

package/dist/auto.js

@@ -0,0 +1,3 @@
+import { bootstrapNotification } from "./index.esm.js";
+
+bootstrapNotification();

package/dist/auto.min.js

@@ -0,0 +1 @@
+import{bootstrapNotification}from"./index.esm.min.js";bootstrapNotification();