@wcstack/timer 1.12.0

package/README.ja.md

@@ -0,0 +1,184 @@
+# @wcstack/timer
+
+`@wcstack/timer` は wcstack エコシステム向けのヘッドレスなタイマーコンポーネントです。
+
+これは視覚的な UI ウィジェットではありません。
+`@wcstack/fetch` がネットワークリクエストをリアクティブな状態に変えるのと同じように、**時間の経過をリアクティブな状態に変える非同期プリミティブノード**です。
+
+`@wcstack/state` と組み合わせると、`<wcs-timer>` はパス契約を通じて直接バインドできます。
+
+- **入力面**: `interval`, `once`, `repeat`, `immediate`, `manual`, `trigger`
+- **出力状態面**: `tick`, `elapsed`, `running`
+- **コマンド**: `start`, `stop`, `reset`, `pause`, `resume`
+
+> `trigger` はコマンドではなく、モーメンタリな命令*プロパティ*（入力）です。`false`→`true` の書き込みでタイマーが開始します。状態から command-token プロトコルで起動する場合は `command.start:` を使ってください（[コマンド](#コマンド)参照）。`command.trigger` は存在しません。
+
+つまり、繰り返し処理を HTML 上で宣言的に表現でき、UI 層に `setInterval()` / `clearInterval()` や後始末のグルーコードを書く必要がありません。
+
+`@wcstack/timer` は [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md)（Core / Shell / Binding Contract）アーキテクチャに従います。
+
+- **Core**（`TimerCore`）がスケジューリング・tick カウント・経過時間・pause/resume を担当
+- **Shell**（`<wcs-timer>`）がその状態を DOM 属性・ライフサイクル・宣言的コマンドに接続
+- **Binding Contract**（`static wcBindable`）が観測可能な `properties`・書き込み可能な `inputs`・呼び出し可能な `commands` を宣言
+
+## なぜ存在するのか
+
+タイマーは `fetch` と同様、時間とともに値を生み出す非同期ソースです。命令的に書くと、開始・クリア・カウント・切断時の後始末といったライフサイクル管理が必要になります。
+
+`@wcstack/timer` はそのロジックを再利用可能なコンポーネントに押し込み、結果をバインド可能な状態として公開します。時間が命令的なイベント配線ではなく、**状態遷移**になります。
+
+## インストール
+
+```bash
+npm install @wcstack/timer
+```
+
+## クイックスタート
+
+### 1. 状態へのリアクティブな tick
+
+`<wcs-timer>` が DOM に接続されると、自動的にインターバルタイマーを開始します。`tick` / `elapsed` / `running` を状態パスにバインドします。
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/timer/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      count: 0,
+      isRunning: false,
+      get statusLabel() {
+        return this.isRunning ? "動作中" : "停止";
+      }
+    };
+  </script>
+</wcs-state>
+
+<wcs-timer
+  interval="1000"
+  data-wcs="tick: count; running: isRunning">
+</wcs-timer>
+
+<p data-wcs="textContent: count"></p>
+<p data-wcs="textContent: statusLabel"></p>
+```
+
+### 2. ワンショット（`setTimeout` 相当）
+
+`once` は `interval` ミリ秒後に1回だけ tick して自動停止します（`once` は `repeat="1"` の糖衣構文です）。
+
+```html
+<wcs-timer interval="3000" once data-wcs="tick: showBanner"></wcs-timer>
+```
+
+### 3. 回数制限付きの繰り返し
+
+`repeat="N"` は N 回 tick して停止します（`running` が `false` になります）。
+
+```html
+<wcs-timer interval="1000" repeat="5" data-wcs="tick: countdownStep"></wcs-timer>
+```
+
+### 4. 即時発火
+
+`immediate` は最初の1回を、1インターバル待たずに開始時点で発火します。
+
+```html
+<wcs-timer interval="5000" immediate data-wcs="tick: pollNow"></wcs-timer>
+```
+
+## 属性 / Inputs
+
+| 属性        | 型      | 既定値  | 説明                                                            |
+| ----------- | ------- | ------- | --------------------------------------------------------------- |
+| `interval`  | number  | `1000`  | tick の周期（ミリ秒）。有限かつ `> 0` であること。不正値（`0`・負数・非数値）は `1000` にフォールバック。 |
+| `once`      | boolean | `false` | 1回だけ発火して停止。`repeat="1"` の糖衣構文。                  |
+| `repeat`    | number  | `0`     | N 回で停止（`0` = 無制限）。`once` より優先されます。           |
+| `immediate` | boolean | `false` | 最初の tick を開始時点で発火（1インターバル待たない）。         |
+| `manual`    | boolean | `false` | 接続時に自動開始しない。コマンド / trigger で開始します。       |
+
+## 観測プロパティ（出力）
+
+| プロパティ | イベント                    | 説明                                                          |
+| ---------- | --------------------------- | ------------------------------------------------------------- |
+| `tick`     | `wcs-timer:tick`            | 発火ごとに増えるカウンタ（`reset` で 0 に戻る）。             |
+| `elapsed`  | `wcs-timer:tick`            | 最後の reset からの経過時間（ミリ秒）。                       |
+| `running`  | `wcs-timer:running-changed` | tick 中は `true`、停止 / 一時停止中は `false`。               |
+
+## コマンド
+
+| コマンド  | 説明                                                             |
+| --------- | ---------------------------------------------------------------- |
+| `start`   | tick を開始（既に動作中なら no-op）。                            |
+| `stop`    | tick を停止。`tick` / `elapsed` は保持されます。                 |
+| `reset`   | 停止し `tick` / `elapsed` を `0` に戻します。                    |
+| `pause`   | 周期の途中経過と経過時間を保持したまま一時停止します。           |
+| `resume`  | `pause` から、周期の残り時間を尊重して再開します。               |
+
+`interval` のライブ変更が即時反映されるのは**動作中**のときだけです。**一時停止中**に `interval` を変更しても現在の周期には影響せず、次の `start` で新しい値が反映されます。
+
+状態駆動の呼び出しには command-token プロトコルを使います。
+
+```html
+<wcs-timer manual data-wcs="command.start: $command.beginPolling"></wcs-timer>
+```
+
+## 任意の DOM トリガ
+
+`autoTrigger` が有効（既定）なら、`data-timertarget="<id>"` を持つ要素のクリックで、参照先の `<wcs-timer>` の `start()` が呼ばれます。
+
+```html
+<button data-timertarget="poll">ポーリング開始</button>
+<wcs-timer id="poll" interval="5000" manual data-wcs="tick: pollNow"></wcs-timer>
+```
+
+イベント委譲を使うため動的に追加された要素でも動作し、`closest()` によりネストした要素（ボタン内のアイコンなど）にも対応します。一致したクリックは `start()` の前に `event.preventDefault()` を呼ぶため、要素の既定動作は抑制されます。既定動作も必要な要素（実際の `<a href>` リンクや form 送信ボタンなど）には `data-timertarget` を付けないでください（キャンセルされます）。
+
+## 設定
+
+`bootstrapTimer()` が `<wcs-timer>` を登録し、必要に応じて既定値を上書きします。部分的な設定を渡せます。
+
+```javascript
+import { bootstrapTimer } from "@wcstack/timer";
+
+bootstrapTimer({
+  autoTrigger: true,             // data-timertarget クリックトリガを有効化（既定: true）
+  triggerAttribute: "data-timertarget", // クリックトリガで走査する属性
+  tagNames: {
+    timer: "wcs-timer",          // カスタム要素のタグ名
+  },
+});
+```
+
+`getConfig()` は現在の設定の deep-frozen なスナップショットを返します。
+
+```javascript
+import { getConfig } from "@wcstack/timer";
+
+const { autoTrigger, triggerAttribute, tagNames } = getConfig();
+```
+
+| オプション          | 型      | 既定               | 説明                                         |
+| ------------------ | ------- | ------------------ | -------------------------------------------- |
+| `autoTrigger`      | boolean | `true`             | `data-timertarget` クリックトリガを有効化。   |
+| `triggerAttribute` | string  | `data-timertarget` | DOM クリックトリガで走査する属性。            |
+| `tagNames.timer`   | string  | `wcs-timer`        | 登録するカスタム要素のタグ名。                |
+
+## ヘッドレス利用（`TimerCore`）
+
+Core は DOM に依存せず、`@wc-bindable/core` の `bind()` と直接組み合わせられます。
+
+```typescript
+import { TimerCore } from "@wcstack/timer";
+
+const timer = new TimerCore();
+timer.addEventListener("wcs-timer:tick", (e) => {
+  console.log((e as CustomEvent).detail); // { count, elapsed }
+});
+timer.start({ interval: 1000, repeat: 10 });
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,191 @@
+# @wcstack/timer
+
+`@wcstack/timer` is a headless timer component for the wcstack ecosystem.
+
+It is not a visual UI widget.
+It is an **async primitive node** that turns the passage of time into reactive state — the same way `@wcstack/fetch` turns a network request into reactive state.
+
+With `@wcstack/state`, `<wcs-timer>` can be bound directly through path contracts:
+
+- **input surface**: `interval`, `once`, `repeat`, `immediate`, `manual`, `trigger`
+- **output state surface**: `tick`, `elapsed`, `running`
+- **commands**: `start`, `stop`, `reset`, `pause`, `resume`
+
+> `trigger` is a momentary command-*property* (an input), not a command: a `false`→`true` write starts the timer. To start from state via the command-token protocol use `command.start:` (see [Commands](#commands)) — there is no `command.trigger`.
+
+This means recurring work can be expressed declaratively in HTML, without writing `setInterval()`, `clearInterval()`, or teardown glue in your UI layer.
+
+`@wcstack/timer` follows the [CSBC](https://github.com/csbc-dev/arch/blob/main/README.md) (Core / Shell / Binding Contract) architecture:
+
+- **Core** (`TimerCore`) handles scheduling, tick counting, elapsed time, and pause/resume
+- **Shell** (`<wcs-timer>`) connects that state to DOM attributes, lifecycle, and declarative commands
+- **Binding Contract** (`static wcBindable`) declares observable `properties`, writable `inputs`, and callable `commands`
+
+## Why this exists
+
+A timer is, like `fetch`, an asynchronous source of values over time. Imperatively it requires lifecycle management: starting, clearing, counting, and cleanup on disconnect.
+
+`@wcstack/timer` moves that logic into a reusable component and exposes the result as bindable state. Time becomes a **state transition**, not imperative event wiring.
+
+With `@wcstack/state`, the flow becomes:
+
+1. `<wcs-timer>` is connected to the DOM and starts ticking
+2. each tick increments `tick` and updates `elapsed`
+3. UI binds to those paths with `data-wcs`
+4. a state getter can react to `tick` changes and chain into other commands (e.g. trigger a `<wcs-fetch>` poll)
+
+## Install
+
+```bash
+npm install @wcstack/timer
+```
+
+## Quick Start
+
+### 1. Reactive ticking from state
+
+When `<wcs-timer>` is connected to the DOM, it automatically starts an interval timer. Bind `tick` / `elapsed` / `running` to state paths.
+
+```html
+<script type="module" src="https://esm.run/@wcstack/state/auto"></script>
+<script type="module" src="https://esm.run/@wcstack/timer/auto"></script>
+
+<wcs-state>
+  <script type="module">
+    export default {
+      count: 0,
+      isRunning: false,
+      get statusLabel() {
+        return this.isRunning ? "Running" : "Stopped";
+      }
+    };
+  </script>
+</wcs-state>
+
+<wcs-timer
+  interval="1000"
+  data-wcs="tick: count; running: isRunning">
+</wcs-timer>
+
+<p data-wcs="textContent: count"></p>
+<p data-wcs="textContent: statusLabel"></p>
+```
+
+### 2. One-shot timeout (`setTimeout` equivalent)
+
+`once` fires exactly one tick after `interval` ms, then auto-stops. (`once` is sugar for `repeat="1"`.)
+
+```html
+<wcs-timer interval="3000" once data-wcs="tick: showBanner"></wcs-timer>
+```
+
+### 3. Bounded repetition
+
+`repeat="N"` fires `N` ticks and then stops (`running` becomes `false`).
+
+```html
+<wcs-timer interval="1000" repeat="5" data-wcs="tick: countdownStep"></wcs-timer>
+```
+
+### 4. Fire immediately
+
+`immediate` fires the first tick at start instead of waiting one full interval.
+
+```html
+<wcs-timer interval="5000" immediate data-wcs="tick: pollNow"></wcs-timer>
+```
+
+## Attributes / Inputs
+
+| Attribute   | Type    | Default | Description                                                        |
+| ----------- | ------- | ------- | ------------------------------------------------------------------ |
+| `interval`  | number  | `1000`  | Tick period in milliseconds. Must be a finite value `> 0`; invalid values (`0`, negative, non-numeric) fall back to `1000`. |
+| `once`      | boolean | `false` | Fire a single tick, then stop. Sugar for `repeat="1"`.             |
+| `repeat`    | number  | `0`     | Stop after N ticks (`0` = unlimited). Takes precedence over `once`. |
+| `immediate` | boolean | `false` | Fire one tick at start instead of waiting the first interval.      |
+| `manual`    | boolean | `false` | Do not auto-start on connect; start via command / trigger.        |
+
+## Observable Properties (outputs)
+
+| Property  | Event                       | Description                                            |
+| --------- | --------------------------- | ------------------------------------------------------ |
+| `tick`    | `wcs-timer:tick`            | Tick counter, increments on every fire (reset to 0 on `reset`). |
+| `elapsed` | `wcs-timer:tick`            | Running time in ms since the last reset.               |
+| `running` | `wcs-timer:running-changed` | `true` while ticking, `false` when stopped/paused.     |
+
+## Commands
+
+| Command   | Description                                                              |
+| --------- | ----------------------------------------------------------------------- |
+| `start`   | Begin ticking (no-op if already running).                               |
+| `stop`    | Stop ticking; `tick` / `elapsed` are retained.                          |
+| `reset`   | Stop and reset `tick` / `elapsed` to `0`.                               |
+| `pause`   | Suspend ticking, preserving the partial period and elapsed time.        |
+| `resume`  | Continue from a `pause`, honoring the remaining time of the period.     |
+
+A live `interval` change is applied immediately only while the timer is **running**. Changing `interval` while **paused** has no effect on the current period; the new value takes effect on the next `start`.
+
+State-driven invocation uses the command-token protocol:
+
+```html
+<wcs-timer manual data-wcs="command.start: $command.beginPolling"></wcs-timer>
+```
+
+## Optional DOM Triggering
+
+If `autoTrigger` is enabled (default), clicking an element carrying `data-timertarget="<id>"` calls `start()` on the referenced `<wcs-timer>`:
+
+```html
+<button data-timertarget="poll">Start polling</button>
+<wcs-timer id="poll" interval="5000" manual data-wcs="tick: pollNow"></wcs-timer>
+```
+
+Event delegation is used, so it also works for dynamically added elements, and `closest()` handles nested targets (e.g. an icon inside the button). A matched click calls `event.preventDefault()` before starting the timer, so the element's default action is suppressed — do not put `data-timertarget` on an element whose default action you also want (a real `<a href>` link, a form-submit button), as it will be cancelled.
+
+## Configuration
+
+`bootstrapTimer()` registers `<wcs-timer>` and optionally overrides defaults. Pass a partial config:
+
+```javascript
+import { bootstrapTimer } from "@wcstack/timer";
+
+bootstrapTimer({
+  autoTrigger: true,             // enable data-timertarget click triggering (default: true)
+  triggerAttribute: "data-timertarget", // attribute scanned for click triggering
+  tagNames: {
+    timer: "wcs-timer",          // custom element tag name
+  },
+});
+```
+
+`getConfig()` returns a deep-frozen snapshot of the current configuration:
+
+```javascript
+import { getConfig } from "@wcstack/timer";
+
+const { autoTrigger, triggerAttribute, tagNames } = getConfig();
+```
+
+| Option             | Type                 | Default            | Description                                         |
+| ------------------ | -------------------- | ------------------ | --------------------------------------------------- |
+| `autoTrigger`      | boolean              | `true`             | Enable `data-timertarget` click triggering.         |
+| `triggerAttribute` | string               | `data-timertarget` | Attribute scanned for DOM click triggering.         |
+| `tagNames.timer`   | string               | `wcs-timer`        | Custom element tag name to register.                |
+
+## Headless usage (`TimerCore`)
+
+The Core has no DOM dependency and can be used directly with `bind()` from `@wc-bindable/core`:
+
+```typescript
+import { TimerCore } from "@wcstack/timer";
+
+const timer = new TimerCore();
+timer.addEventListener("wcs-timer:tick", (e) => {
+  console.log((e as CustomEvent).detail); // { count, elapsed }
+});
+timer.start({ interval: 1000, repeat: 10 });
+```
+
+## License
+
+MIT

package/dist/auto.js

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

package/dist/auto.min.js

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

package/dist/index.d.ts

@@ -0,0 +1,180 @@
+interface ITagNames {
+    readonly timer: string;
+}
+interface IWritableTagNames {
+    timer?: 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[];
+}
+/**
+ * Payload carried by the `wcs-timer:tick` event.
+ * `count` is the number of ticks fired since the last reset; `elapsed` is the
+ * milliseconds the timer has been running since the last reset.
+ */
+interface WcsTimerTickDetail {
+    count: number;
+    elapsed: number;
+}
+/**
+ * Value types for TimerCore (headless) — the observable state properties.
+ * Use with `bind()` from `@wc-bindable/core` for compile-time type checking.
+ *
+ * @example
+ * ```typescript
+ * const core = new TimerCore();
+ * bind(core, (name: keyof WcsTimerCoreValues, value) => { ... });
+ * ```
+ */
+interface WcsTimerCoreValues {
+    tick: number;
+    elapsed: number;
+    running: boolean;
+}
+/**
+ * Value types for the Shell (`<wcs-timer>`) — identical observable surface to
+ * the Core, plus the DOM-driven `trigger` command-property.
+ */
+interface WcsTimerValues extends WcsTimerCoreValues {
+    trigger: boolean;
+}
+interface WcsTimerInputs {
+    interval: number;
+    once: boolean;
+    repeat: number;
+    immediate: boolean;
+    manual: boolean;
+    trigger: boolean;
+}
+interface WcsTimerCoreCommands {
+    start(options?: {
+        interval?: number;
+        repeat?: number;
+        immediate?: boolean;
+    }): void;
+    stop(): void;
+    reset(): void;
+    pause(): void;
+    resume(): void;
+}
+interface WcsTimerCommands {
+    start(): void;
+    stop(): void;
+    reset(): void;
+    pause(): void;
+    resume(): void;
+}
+
+declare function bootstrapTimer(userConfig?: IWritableConfig): void;
+
+declare function getConfig(): IConfig;
+
+interface TimerStartOptions {
+    interval?: number;
+    repeat?: number;
+    immediate?: boolean;
+}
+/**
+ * Headless timer primitive. A thin, framework-agnostic wrapper around
+ * `setInterval` exposed through the wc-bindable protocol: it streams `tick`
+ * (a monotonically increasing counter), `elapsed` (running time in ms) and a
+ * `running` flag, and is driven by the `start` / `stop` / `reset` / `pause` /
+ * `resume` commands.
+ *
+ * `tick` and `elapsed` are both surfaced via the single `wcs-timer:tick` event
+ * (read through getters, mirroring how FetchCore exposes value/status from one
+ * `wcs-fetch:response` event), so an observer that binds either property is
+ * notified on every fire.
+ */
+declare class TimerCore extends EventTarget {
+    static wcBindable: IWcBindable;
+    private _target;
+    private _timerId;
+    private _tick;
+    private _running;
+    private _paused;
+    private _runStartTick;
+    private _interval;
+    private _repeat;
+    private _accumulatedElapsed;
+    private _segmentStart;
+    constructor(target?: EventTarget);
+    get tick(): number;
+    get elapsed(): number;
+    get running(): boolean;
+    private _dispatchTick;
+    private _setRunning;
+    start(options?: TimerStartOptions): void;
+    changeInterval(interval: number): void;
+    stop(): void;
+    reset(): void;
+    pause(): void;
+    resume(): void;
+    private _onResumeBoundary;
+    private _fire;
+    private _clearTimer;
+    private _foldElapsed;
+    private _currentElapsed;
+}
+
+declare class Timer extends HTMLElement {
+    static hasConnectedCallbackPromise: boolean;
+    static wcBindable: IWcBindable;
+    static get observedAttributes(): string[];
+    private _core;
+    private _trigger;
+    constructor();
+    get interval(): number;
+    set interval(value: number);
+    get once(): boolean;
+    set once(value: boolean);
+    get repeat(): number;
+    set repeat(value: number);
+    get immediate(): boolean;
+    set immediate(value: boolean);
+    get manual(): boolean;
+    set manual(value: boolean);
+    get tick(): number;
+    get elapsed(): number;
+    get running(): boolean;
+    get trigger(): boolean;
+    set trigger(value: boolean);
+    start(): void;
+    stop(): void;
+    reset(): void;
+    pause(): void;
+    resume(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+
+export { TimerCore, Timer as WcsTimer, bootstrapTimer, getConfig };
+export type { IWritableConfig, IWritableTagNames, TimerStartOptions, WcsTimerCommands, WcsTimerCoreCommands, WcsTimerCoreValues, WcsTimerInputs, WcsTimerTickDetail, WcsTimerValues };