@wcstack/debounce 1.12.0

package/README.ja.md

@@ -0,0 +1,153 @@
+# @wcstack/debounce
+
+`@wcstack/debounce` は wcstack エコシステム向けのヘッドレスな debounce / throttle コンポーネントです。
+
+これは見た目を持つ UI ウィジェットではありません。
+ノイズの多いシグナルの連打を、静止後の1回の発火に集約する **非同期プリミティブノード** です（`@wcstack/timer` が時間経過をリアクティブな状態にするのと同じ発想）。
+
+1つのエンジンの上に2つのカスタム要素を提供します。
+
+- `<wcs-debounce>` — シグナルが `wait` ms 静止したら1回発火。
+- `<wcs-throttle>` — 最大で `wait` ms に1回発火（`maxWait === wait`・leading 既定 on の debounce）。
+
+[CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います。
+
+- **Core**（`DebounceCore`）が lodash の debounce アルゴリズム（`leading` / `trailing` / `maxWait`）を移植し、結果をイベントで公開。
+- **Shell**（`<wcs-debounce>` / `<wcs-throttle>`）が DOM 属性・ライフサイクル・宣言的コマンドへ接続。
+- **Binding Contract**（`static wcBindable`）が観測可能な `properties`・書き込み可能な `inputs`・呼び出し可能な `commands` を宣言。
+
+## 2つのサーフェス
+
+本質は「シグナルのデバウンス」です。シグナルは **値** を運ぶか、**引数付きのパルス** かのどちらかなので、サーフェスは2つあります（1要素につき片方を使う）。
+
+### 値サーフェス — `source` → `value`
+
+`source` に書き込むと、静止後にデバウンス済みの値が `value` プロパティ（イベント `wcs-debounce:settled`）で公開されます。`source: src; value: debounced` と配線すると `value` が state に書き戻ります。
+
+### シグナルサーフェス — `trigger(...args)` → `fired`
+
+`trigger` コマンドを連打すると、静止後に `wcs-debounce:fired` イベント1発が最後の args を載せて発火します。state は一過性のパルスを値として読めないため、中継にはトークンを使います。
+
+```
+source →(command-token)→ debounce.trigger →[coalesce]→ fired →(event-token)→ state → target.method
+```
+
+state は [command-token プロトコル](../state/)（`command.trigger: $command.X`）で入口を撃ち、[event-token プロトコル](../state/)（`eventToken.fired: Y`）で集約された1発を受け、本来のメソッドへ再配線します。
+
+> 1つの要素インスタンスは **片方** のサーフェス専用です。同じ要素で `source` と `trigger` を両方駆動すると、最後にスケジュールされたシグナルが勝ちます（lodash の last-args セマンティクス）。
+
+## インストール
+
+```bash
+npm install @wcstack/debounce
+```
+
+## クイックスタート
+
+### 1. 入力値のデバウンス
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/debounce/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default { query: "", debouncedQuery: "" };
+  </script>
+</wcs-state>
+
+<input data-wcs="value: query">
+<wcs-debounce wait="300" data-wcs="source: query; value: debouncedQuery"></wcs-debounce>
+<p>検索: {{ debouncedQuery }}</p>
+```
+
+### 2. メソッド呼び出しのデバウンス（シグナルサーフェス）
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["search"],
+      $eventTokens: ["searchSettled"],
+      query: "",
+      $on: {
+        searchSettled: (state, event) => {
+          const [q] = event.detail.args; // 最後のキー入力から 300ms 後に1回だけ
+          state.results = doSearch(q);
+        }
+      }
+    };
+  </script>
+</wcs-state>
+
+<input data-wcs="oninput: $command.search">
+<wcs-debounce
+  wait="300"
+  data-wcs="command.trigger: $command.search; eventToken.fired: searchSettled">
+</wcs-debounce>
+```
+
+### 3. 高頻度な値ストリームのスロットル
+
+```html
+<wcs-throttle wait="100" data-wcs="source: scrollY; value: throttledScrollY"></wcs-throttle>
+```
+
+`<wcs-throttle>` は既定で leading（即時発火し、以後は最大 `wait` ms に1回）。
+
+## 属性 / Inputs
+
+| 属性          | 型      | 既定 (`<wcs-debounce>`) | 既定 (`<wcs-throttle>`) | 説明 |
+| ------------- | ------- | ----------------------- | ----------------------- | ---- |
+| `wait`        | number  | `250`                   | `250`                   | 静止期間 (ms)。不正・負・非数値は既定値にフォールバック。 |
+| `leading`     | boolean | off                     | **on**（`no-leading` で無効化） | バースト先頭で発火。 |
+| `no-trailing` | boolean | off（trailing 有効）    | off（trailing 有効）    | 末尾発火を無効化。 |
+| `max-wait`    | number  | なし                    | `wait`                  | 連続入力中でも最大 `max-wait` ms ごとに発火を強制。`>= wait` にクランプ。 |
+| `source`      | any     | —                       | —                       | 値サーフェスの入力。デバウンス結果は `value` に返る。 |
+
+## 観測可能プロパティ（outputs）
+
+| プロパティ | イベント                       | 説明                                       |
+| ---------- | ------------------------------ | ------------------------------------------ |
+| `value`    | `wcs-debounce:settled`         | 最後の `source` 書き込みのデバウンス済み値。 |
+| `fired`    | `wcs-debounce:fired`           | 最後の `trigger()` パルスの集約 args。       |
+| `pending`  | `wcs-debounce:pending-changed` | デバウンス進行中は `true`。                  |
+
+`<wcs-throttle>` は同じ形を `wcs-throttle:*` 名前空間で公開します。
+
+## コマンド
+
+| コマンド  | 説明                                                       |
+| --------- | ---------------------------------------------------------- |
+| `trigger` | シグナルサーフェスの入口。`...args` を載せてパルスを集約。  |
+| `cancel`  | 保留中の発火を捨てる（getter は前回値を保持）。            |
+| `flush`   | 保留中のペイロードを即発火（保留がなければ no-op）。       |
+
+## 任意の DOM トリガー
+
+`config.autoTrigger` が有効（既定）なら、`data-debouncetarget="<id>"` を持つ要素のクリックで、参照先の `<wcs-debounce>` / `<wcs-throttle>` に対し集約済みの `trigger()` を1発撃ちます（クリックの既定動作は抑制）。
+
+## ヘッドレス利用（`DebounceCore`）
+
+Core は DOM 非依存で、`@wc-bindable/core` の `bind()` から直接利用できます。
+
+```typescript
+import { DebounceCore } from "@wcstack/debounce";
+
+const core = new DebounceCore("wcs-debounce", undefined, { wait: 300 });
+core.addEventListener("wcs-debounce:settled", (e) => {
+  console.log((e as CustomEvent).detail.value);
+});
+core.setSource("a");
+core.setSource("b"); // "b" だけが 300ms 後に settle
+```
+
+throttle は prefix と `maxWait === wait` を変えた同じエンジンです。
+
+```typescript
+const throttle = new DebounceCore("wcs-throttle", undefined, { wait: 100, leading: true, maxWait: 100 });
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,157 @@
+# @wcstack/debounce
+
+`@wcstack/debounce` is a headless debounce / throttle component for the wcstack ecosystem.
+
+It is not a visual UI widget.
+It is an **async primitive node** that coalesces a noisy stream of signals into a single quiet-period emission — the same way `@wcstack/timer` turns the passage of time into reactive state.
+
+It ships two custom elements over one engine:
+
+- `<wcs-debounce>` — emit once after the signal has been idle for `wait` ms.
+- `<wcs-throttle>` — emit at most once per `wait` ms (debounce with `maxWait === wait`, leading on).
+
+`@wcstack/debounce` follows the [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md) (Core / Shell / Binding Contract) architecture:
+
+- **Core** (`DebounceCore`) ports lodash's debounce algorithm (`leading` / `trailing` / `maxWait`) and publishes results as events.
+- **Shell** (`<wcs-debounce>` / `<wcs-throttle>`) connects that engine to DOM attributes, lifecycle, and declarative commands.
+- **Binding Contract** (`static wcBindable`) declares observable `properties`, writable `inputs`, and callable `commands`.
+
+## Two surfaces
+
+The essence is "debouncing a signal". A signal can carry a **value** or be a bare **pulse with arguments**, so there are two surfaces — use one per element.
+
+### Value surface — `source` → `value`
+
+Write to `source`; after the quiet period the debounced value is published on the `value` property (event `wcs-debounce:settled`). Wire it as `source: src; value: debounced` — `value` flows back into state.
+
+### Signal surface — `trigger(...args)` → `fired`
+
+Call the `trigger` command repeatedly; after the quiet period one `wcs-debounce:fired` event carries the last args. Because state cannot read a transient pulse as a value, the relay uses tokens:
+
+```
+source →(command-token)→ debounce.trigger →[coalesce]→ fired →(event-token)→ state → target.method
+```
+
+State fires the entry with the [command-token protocol](../state/) (`command.trigger: $command.X`) and receives the single coalesced pulse with the [event-token protocol](../state/) (`eventToken.fired: Y`), then re-dispatches it to the real method.
+
+> A single element instance is meant for **one** surface. If both `source` and `trigger` are driven on the same element, the last scheduled signal wins (lodash's last-args semantics).
+
+## Install
+
+```bash
+npm install @wcstack/debounce
+```
+
+## Quick Start
+
+### 1. Debounce an input value
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/debounce/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      query: "",
+      debouncedQuery: ""
+    };
+  </script>
+</wcs-state>
+
+<input data-wcs="value: query">
+<wcs-debounce wait="300" data-wcs="source: query; value: debouncedQuery"></wcs-debounce>
+<p>Searching for: {{ debouncedQuery }}</p>
+```
+
+### 2. Debounce a method call (signal surface)
+
+```html
+<wcs-state>
+  <script type="module">
+    export default {
+      $commandTokens: ["search"],
+      $eventTokens: ["searchSettled"],
+      query: "",
+      $on: {
+        searchSettled: (state, event) => {
+          // fires once, 300ms after the last keystroke
+          const [q] = event.detail.args;
+          state.results = doSearch(q);
+        }
+      }
+    };
+  </script>
+</wcs-state>
+
+<input data-wcs="oninput: $command.search">
+<wcs-debounce
+  wait="300"
+  data-wcs="command.trigger: $command.search; eventToken.fired: searchSettled">
+</wcs-debounce>
+```
+
+### 3. Throttle a fast value stream
+
+```html
+<wcs-throttle wait="100" data-wcs="source: scrollY; value: throttledScrollY"></wcs-throttle>
+```
+
+`<wcs-throttle>` leads by default (emits immediately, then at most once per `wait` ms).
+
+## Attributes / Inputs
+
+| Attribute     | Type    | Default (`<wcs-debounce>`) | Default (`<wcs-throttle>`) | Description |
+| ------------- | ------- | -------------------------- | -------------------------- | ----------- |
+| `wait`        | number  | `250`                      | `250`                      | Quiet period in ms. Invalid / negative / non-numeric values fall back to the default. |
+| `leading`     | boolean | off                        | **on** (`no-leading` opts out) | Emit on the first signal of a burst. |
+| `no-trailing` | boolean | off (trailing on)          | off (trailing on)          | Opt out of the trailing-edge emission. |
+| `max-wait`    | number  | none                       | `wait`                     | Force an emission at least every `max-wait` ms under continuous input. Clamped to `>= wait`. |
+| `source`      | any     | —                          | —                          | Value-surface input; its debounced echo returns on `value`. |
+
+## Observable Properties (outputs)
+
+| Property  | Event                          | Description                                          |
+| --------- | ------------------------------ | ---------------------------------------------------- |
+| `value`   | `wcs-debounce:settled`         | The debounced value of the latest `source` write.    |
+| `fired`   | `wcs-debounce:fired`           | The coalesced args of the latest `trigger()` pulse.  |
+| `pending` | `wcs-debounce:pending-changed` | `true` while a debounce is in flight.                |
+
+`<wcs-throttle>` publishes the same shape under the `wcs-throttle:*` namespace.
+
+## Commands
+
+| Command   | Description                                                       |
+| --------- | ---------------------------------------------------------------- |
+| `trigger` | Signal-surface entry: coalesce a pulse carrying `...args`.       |
+| `cancel`  | Drop any pending emission without firing (getters keep values).  |
+| `flush`   | Emit any buffered payload immediately (no-op if nothing pending). |
+
+## Optional DOM Triggering
+
+When `config.autoTrigger` is on (default), a click on an element carrying `data-debouncetarget="<id>"` fires a single coalesced `trigger()` pulse on the referenced `<wcs-debounce>` / `<wcs-throttle>` (the click's default action is suppressed).
+
+## Headless usage (`DebounceCore`)
+
+The Core has no DOM dependency and can be used directly with `bind()` from `@wc-bindable/core`:
+
+```typescript
+import { DebounceCore } from "@wcstack/debounce";
+
+const core = new DebounceCore("wcs-debounce", undefined, { wait: 300 });
+core.addEventListener("wcs-debounce:settled", (e) => {
+  console.log((e as CustomEvent).detail.value);
+});
+core.setSource("a");
+core.setSource("b"); // only "b" settles, 300ms later
+```
+
+Throttle is the same engine with a different prefix and `maxWait === wait`:
+
+```typescript
+const throttle = new DebounceCore("wcs-throttle", undefined, { wait: 100, leading: true, maxWait: 100 });
+```
+
+## License
+
+MIT

package/dist/auto.js

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

package/dist/auto.min.js

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

package/dist/index.d.ts

@@ -0,0 +1,245 @@
+interface ITagNames {
+    readonly debounce: string;
+    readonly throttle: string;
+}
+interface IWritableTagNames {
+    debounce?: string;
+    throttle?: string;
+}
+interface IConfig {
+    readonly autoTrigger: boolean;
+    readonly triggerAttribute: string;
+    readonly tagNames: ITagNames;
+}
+interface IWritableConfig {
+    autoTrigger?: boolean;
+    triggerAttribute?: string;
+    tagNames?: IWritableTagNames;
+}
+interface IWcBindableProperty {
+    readonly name: string;
+    readonly event: string;
+    readonly getter?: (event: Event) => any;
+}
+interface IWcBindableInput {
+    readonly name: string;
+    readonly attribute?: string;
+}
+interface IWcBindableCommand {
+    readonly name: string;
+    readonly async?: boolean;
+}
+interface IWcBindable {
+    readonly protocol: "wc-bindable";
+    readonly version: number;
+    readonly properties: IWcBindableProperty[];
+    readonly inputs?: IWcBindableInput[];
+    readonly commands?: IWcBindableCommand[];
+}
+/**
+ * Tuning options for {@link DebounceCore}. Mirrors lodash's `debounce` knobs.
+ * - `wait`: quiet period (ms) the signal must be idle before a trailing fire.
+ * - `leading`: fire on the first signal of a burst.
+ * - `trailing`: fire after the quiet period at the end of a burst.
+ * - `maxWait`: cap the total time a fire can be deferred under continuous input.
+ *   (Throttle is expressed as `maxWait === wait`.)
+ */
+interface DebounceOptions {
+    wait?: number;
+    leading?: boolean;
+    trailing?: boolean;
+    maxWait?: number;
+}
+/**
+ * Payload carried by the `<prefix>:settled` event (the value surface).
+ * `value` is the debounced value of the most recent `source` write.
+ */
+interface WcsDebounceSettledDetail {
+    value: any;
+}
+/**
+ * Payload carried by the `<prefix>:fired` event (the signal surface).
+ * `args` are the coalesced arguments of the most recent `trigger(...args)` pulse.
+ */
+interface WcsDebounceFiredDetail {
+    args: any[];
+}
+/**
+ * Value types for DebounceCore (headless) — the observable state properties.
+ * Use with `bind()` from `@wc-bindable/core` for compile-time type checking.
+ */
+interface WcsDebounceCoreValues {
+    value: any;
+    fired: any[];
+    pending: boolean;
+}
+/**
+ * Value types for the Shell (`<wcs-debounce>` / `<wcs-throttle>`) — identical
+ * observable surface to the Core.
+ */
+type WcsDebounceValues = WcsDebounceCoreValues;
+interface WcsDebounceInputs {
+    source: any;
+    wait: number;
+    leading: boolean;
+    trailing: boolean;
+    maxWait?: number;
+}
+interface WcsDebounceCoreCommands {
+    trigger(...args: any[]): void;
+    cancel(): void;
+    flush(): void;
+}
+type WcsDebounceCommands = WcsDebounceCoreCommands;
+
+declare function bootstrapDebounce(userConfig?: IWritableConfig): void;
+
+declare function getConfig(): IConfig;
+
+/**
+ * Headless debounce/throttle primitive. A framework-agnostic port of lodash's
+ * `debounce` algorithm (`shouldInvoke` / `leadingEdge` / `trailingEdge` /
+ * `remainingWait`, timed via `Date.now()`), exposed through the wc-bindable
+ * protocol.
+ *
+ * It coalesces a stream of *signals* and emits at most one per quiet period.
+ * Two surfaces share the single timer:
+ *
+ * - **value** — writing {@link setSource} schedules a settle; on fire the
+ *   debounced value is published via the `<prefix>:settled` event and the
+ *   `value` getter. Wire it as `source: src; value: debounced`.
+ * - **signal** — calling {@link trigger}`(...args)` coalesces a burst of pulses;
+ *   on fire one `<prefix>:fired` event carries the latest args (relayed by state
+ *   through the command-token / event-token protocols).
+ *
+ * A given instance is meant to be used for one surface at a time. Because each
+ * surface keeps its own field (`_value` vs `_lastArgs`), the getters never
+ * pollute each other; if both are driven on one instance the *last* scheduled
+ * signal wins (lodash's last-args semantics).
+ *
+ * Throttle is the same engine with `maxWait === wait` (and `leading` on by
+ * default), so `<wcs-throttle>` reuses this class with a different `eventPrefix`.
+ */
+declare class DebounceCore extends EventTarget {
+    static wcBindable: IWcBindable;
+    private readonly _prefix;
+    private _target;
+    private _wait;
+    private _leading;
+    private _trailing;
+    private _maxWait;
+    private _hasMaxWait;
+    private _lastCallTime;
+    private _lastInvokeTime;
+    private _timerId;
+    private _pendingKind;
+    private _pendingValue;
+    private _pendingArgs;
+    private _value;
+    private _lastArgs;
+    private _pending;
+    constructor(prefix?: string, target?: EventTarget, options?: DebounceOptions);
+    /**
+     * Update the tuning knobs. The Shell calls this with the element's current
+     * attributes before each schedule, so live attribute edits take effect on the
+     * next signal. `maxWait` is clamped to at least `wait` (lodash semantics); an
+     * absent / invalid `maxWait` disables maxWait entirely.
+     */
+    configure(options?: DebounceOptions): void;
+    get value(): any;
+    get fired(): any[];
+    get pending(): boolean;
+    /** Value surface: schedule a settle carrying `value` (last write wins). */
+    setSource(value: any): void;
+    /** Signal surface: coalesce a pulse carrying `args` (last call wins). */
+    trigger(...args: any[]): void;
+    /** Drop any pending fire without emitting. Getters keep their last values. */
+    cancel(): void;
+    /**
+     * Emit any buffered payload immediately, then clear pending. Unlike lodash's
+     * `flush` (which honours `trailing`), this fires whatever is buffered — the
+     * command's intent is "publish now" — but is a no-op when nothing is pending.
+     */
+    flush(): void;
+    private _schedule;
+    private _shouldInvoke;
+    private _remainingWait;
+    private _timerExpired;
+    private _leadingEdge;
+    private _trailingEdge;
+    private _invoke;
+    private _setPending;
+    private _dispatch;
+    private _clearTimer;
+}
+
+/**
+ * Build the wc-bindable `properties` list for a debounce/throttle element, with
+ * every event name derived from a single `prefix`. `<wcs-debounce>` uses
+ * `"wcs-debounce"`, `<wcs-throttle>` uses `"wcs-throttle"`, so the two tags share
+ * one engine (DebounceCore) yet advertise distinct event namespaces from one
+ * source of truth — no hand-duplicated property tables (cf. the geolocation Shell
+ * which overrode its wcBindable by hand).
+ *
+ * - `value`   — the debounced value of the latest `source` write (value surface),
+ *               read from the `<prefix>:settled` event.
+ * - `fired`   — the coalesced args of the latest `trigger()` pulse (signal
+ *               surface), read from the `<prefix>:fired` event. Declared as a
+ *               property (not just an event) so state can subscribe via the
+ *               event-token protocol (`eventToken.fired: <name>`).
+ * - `pending` — whether a debounce is currently in flight.
+ */
+declare function makeDebounceProperties(prefix: string): IWcBindableProperty[];
+
+/**
+ * `<wcs-debounce>` — declarative debounce. See {@link DebounceCore} for the
+ * engine. The `eventPrefix` defaults to `"wcs-debounce"`; `<wcs-throttle>`
+ * subclasses this with `"wcs-throttle"` and throttle defaults.
+ */
+declare class Debounce extends HTMLElement {
+    static hasConnectedCallbackPromise: boolean;
+    protected static eventPrefix: string;
+    static wcBindable: IWcBindable;
+    protected _core: DebounceCore;
+    private _source;
+    constructor();
+    get wait(): number;
+    set wait(value: number);
+    get leading(): boolean;
+    set leading(value: boolean);
+    get trailing(): boolean;
+    set trailing(value: boolean);
+    get maxWait(): number | undefined;
+    set maxWait(value: number);
+    get source(): any;
+    set source(value: any);
+    get value(): any;
+    get fired(): any[];
+    get pending(): boolean;
+    trigger(...args: any[]): void;
+    cancel(): void;
+    flush(): void;
+    protected _defaultWait(): number;
+    protected _resolveLeading(): boolean;
+    protected _defaultMaxWait(): number | undefined;
+    protected _options(): DebounceOptions;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+
+/**
+ * `<wcs-throttle>` — the same {@link DebounceCore} engine biased to throttle:
+ * `maxWait === wait` (a fire happens at least every `wait` ms under continuous
+ * input) and `leading` on by default. It advertises its own `wcs-throttle:*`
+ * event namespace (via `makeDebounceProperties("wcs-throttle")`), and the Core
+ * dispatches under that prefix because the constructor passes it through.
+ */
+declare class Throttle extends Debounce {
+    protected static eventPrefix: string;
+    static wcBindable: IWcBindable;
+    protected _resolveLeading(): boolean;
+    protected _defaultMaxWait(): number | undefined;
+}
+
+export { DebounceCore, Debounce as WcsDebounce, Throttle as WcsThrottle, bootstrapDebounce, getConfig, makeDebounceProperties };
+export type { DebounceOptions, IWritableConfig, IWritableTagNames, WcsDebounceCommands, WcsDebounceCoreCommands, WcsDebounceCoreValues, WcsDebounceFiredDetail, WcsDebounceInputs, WcsDebounceSettledDetail, WcsDebounceValues };