@wcstack/notification 1.15.0 → 1.16.0

package/README.ja.md

@@ -8,7 +8,7 @@ Notifications API をリアクティブな state と state 駆動のコマンド
 `@wcstack/state` と組み合わせると、`<wcs-notify>` はパス契約で直接バインドできます:
 
 - **command サーフェス**: `request`, `notify`, `close`, `closeAll`
-- **input サーフェス**: `notice`（reactive な表示）, `mode`, `body`, `icon`, `badge`, `tag`, `lang`, `dir`, `require-interaction`, `silent`, `renotify`
+- **input サーフェス**: `notice`（reactive な表示）, `mode`, `body`, `icon`, `badge`, `tag`, `lang`, `dir`, `require-interaction`, `silent`, `renotify`, `manual`
 - **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）アーキテクチャに従います:
@@ -90,6 +90,10 @@ npm install @wcstack/notification
 
 ### 4. クリックを読む
 
+```html
+<wcs-notify data-wcs="command.notify: $command.notify; eventToken.clicked: opened"></wcs-notify>
+```
+
 `clicked` / `closed` / `shown` は `{ tag, data, action }` を運びます。`tag` は通知の識別子（あなたの `options.tag`、省略時は生成された `wcs-<n>`）、`data` は `options.data` に渡した値、`action` は Service Worker のアクションボタン id（コンストラクタ経路では常に `""`）です。
 
 完全なデモは `examples/state-notification-chat` を参照。
@@ -155,10 +159,45 @@ wireNotificationClicks();
 ## 注意・制限
 
 - **通知はページより長生きする。** `<wcs-notify>` の切断（または Core の `dispose()`）は購読を解除しますが、開いている通知は**閉じません** —— 通知はページの終了後も残ることが意図です。閉じるには `close` / `closeAll` を使ってください。
+- **`mode` は接続時に固定される。** バックエンドは要素の接続時（`observe(mode)`）に一度だけ選択され、`mode` の `observedAttributes` エントリはありません。接続済みの要素で `mode` 属性を変更しても、要素を再接続（削除して再挿入）するまで効果はありません。
+- **SW バックエンドは `close` を中継しない。** `@wcstack/notification/sw` ヘルパは `notificationclick` のみを配線し、`notificationclose` は配線しません。そのため `sw` バックエンドでは `closed` / `wcs-notify:close` は発火しません（close 用のワーカー越え中継がない）。`clicked` はクリック中継で動作しますが、`closed` は constructor バックエンド限定の信号です。
 - **Push API はスコープ外。** 本パッケージは Notifications API（ローカル通知）をラップします。サーバ起点の Push は別の関心事です。
 - **サイレント失敗（zero-log）。** wcstack のゼロ依存哲学に沿い、`<wcs-notify>` は決してログ出力も throw もしません。API 不在 → `permission = "unsupported"`、未許可や表示失敗 → `error` プロパティ。`error` / `permission` をバインドして反応してください。
 - **SSR（`@wcstack/server`）。** `static hasConnectedCallbackPromise = true` を宣言し `connectedCallbackPromise` を公開するため、サーバレンダラは接続時の権限プローブが解決するまで待ってからスナップショットします。
 
+## 設定
+
+`<wcs-notify>` はクリック **autoTrigger** を同梱しており、**既定で有効**です。有効な場合、最初に接続した `<wcs-notify>` が document レベルの `click` リスナーを 1 つ設置します。トリガ属性（`data-notifytarget="<id>"`）を持つ要素をクリックすると、その `id` の `<wcs-notify>` の `notify()` が呼ばれます:
+
+```html
+<wcs-notify id="app-notify"></wcs-notify>
+<button data-notifytarget="app-notify" data-notifybody="新着メッセージが1件あります">
+  通知する
+</button>
+```
+
+- タイトルは `data-notifytitle` があればそれ、無ければトリガ要素の trim 済み `textContent`。body は任意の `data-notifybody`。
+- **document 全域**のクリックリスナーが既定で設置されるため、ショートカットを使わないなら無効化してください。設定は `bootstrapNotification(userConfig?)`（要素登録と設定適用を 1 回で行う）で適用し、`getConfig()` で実効設定（deep-frozen）を読み取れます:
+
+```js
+import { bootstrapNotification, getConfig } from "@wcstack/notification";
+
+// <wcs-notify> を登録しつつ document クリックリスナーを無効化:
+bootstrapNotification({ autoTrigger: false });
+// あるいはトリガ属性名を変更:
+bootstrapNotification({ triggerAttribute: "data-notify" });
+
+getConfig(); // deep-frozen の実効設定を読む
+```
+
+| 設定キー           | 型        | 既定                | 説明                                                               |
+| ------------------ | --------- | ------------------- | ------------------------------------------------------------------ |
+| `autoTrigger`      | `boolean` | `true`              | `data-notifytarget` 用の document レベルクリックリスナーを設置。   |
+| `triggerAttribute` | `string`  | `data-notifytarget` | クリック要素が `<wcs-notify>` を id で指すのに使う属性。            |
+| `tagNames.notify`  | `string`  | `wcs-notify`        | 登録するカスタム要素タグ名。                                        |
+
+`bootstrapNotification()` は要素が接続される**前に**呼ぶと変更が反映されます。
+
 ## ヘッドレス利用（`NotificationCore`）
 
 Core は DOM 依存が無く、`@wc-bindable/core` の `bind()` と直接使えます:

package/README.md

@@ -8,7 +8,7 @@ It is an **async primitive node** that turns the Notifications API into reactive
 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`
+- **input surface**: `notice` (reactive show), `mode`, `body`, `icon`, `badge`, `tag`, `lang`, `dir`, `require-interaction`, `silent`, `renotify`, `manual`
 - **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:
@@ -159,10 +159,45 @@ It relays each click over `BroadcastChannel("wcs-notify")` (primary) and `client
 ## 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.
+- **`mode` is fixed at connect time.** The backend is chosen once, when the element connects (`observe(mode)`); there is no `observedAttributes` entry for `mode`. Changing the `mode` attribute on an already-connected element has no effect until you re-connect it (remove and re-insert).
+- **The SW backend does not relay `close`.** The `@wcstack/notification/sw` helper wires `notificationclick` only, not `notificationclose`. So under the `sw` backend `closed` / `wcs-notify:close` never fires (there is no cross-worker relay for close). `clicked` still works via the click relay; `closed` is a constructor-backend-only signal.
 - **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.
 
+## Configuration
+
+`<wcs-notify>` ships a **click autoTrigger** that is **enabled by default**. When enabled, the first `<wcs-notify>` to connect installs a single document-level `click` listener. A click on any element carrying the trigger attribute (`data-notifytarget="<id>"`) calls `notify()` on the `<wcs-notify>` with that `id`:
+
+```html
+<wcs-notify id="app-notify"></wcs-notify>
+<button data-notifytarget="app-notify" data-notifybody="You have 1 new message">
+  Notify me
+</button>
+```
+
+- The title is `data-notifytitle` if present, otherwise the trigger element's trimmed `textContent`; the body is the optional `data-notifybody`.
+- Because it is a **document-wide** click listener installed by default, disable it if you do not use the shortcut. Configuration is applied through `bootstrapNotification(userConfig?)` (which registers the element and applies the config in one call); `getConfig()` reads back the effective, deep-frozen config:
+
+```js
+import { bootstrapNotification, getConfig } from "@wcstack/notification";
+
+// Register <wcs-notify> and opt out of the document click listener:
+bootstrapNotification({ autoTrigger: false });
+// Or rename the trigger attribute:
+bootstrapNotification({ triggerAttribute: "data-notify" });
+
+getConfig(); // read the (deep-frozen) effective config
+```
+
+| Config key         | Type      | Default             | Description                                                        |
+| ------------------ | --------- | ------------------- | ----------------------------------------------------------------- |
+| `autoTrigger`      | `boolean` | `true`              | Install the document-level click listener for `data-notifytarget`. |
+| `triggerAttribute` | `string`  | `data-notifytarget` | Attribute a clickable element uses to target a `<wcs-notify>` by id. |
+| `tagNames.notify`  | `string`  | `wcs-notify`        | Custom-element tag name to register.                              |
+
+Call `setConfig()` / `bootstrapNotification()` **before** the elements connect for the change to take effect.
+
 ## Headless usage (`NotificationCore`)
 
 The Core has no DOM dependency and can be used directly with `bind()` from `@wc-bindable/core`:

package/dist/index.d.ts

@@ -51,8 +51,9 @@ type NotificationPermissionRaw = "default" | "granted" | "denied";
  * Which API actually shows the notification.
  * - `"constructor"` — `new Notification(title, options)` (desktop only).
  * - `"sw"` — `ServiceWorkerRegistration.showNotification()` (required on mobile/Android Chrome).
- * - `"auto"` — pick SW when a registration is ready and `new Notification` is unusable,
- *   otherwise the constructor; fall back to SW if the constructor throws `TypeError`.
+ * - `"auto"` — always try the `Notification` constructor first (no registration
+ *   pre-check), and fall back to the SW backend only if the constructor throws a
+ *   `TypeError` (e.g. on mobile, where `new Notification()` is illegal).
  */
 type NotifyBackend = "auto" | "sw" | "constructor";
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wcstack/notification",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Declarative desktop-notification component for Web Components. Framework-agnostic Notifications API wrapper via wc-bindable-protocol, with Service Worker support.",
   "type": "module",
   "main": "./dist/index.esm.js",