@next2d/events 2.13.1 → 3.0.1

package/README.md

@@ -1,11 +1,307 @@
-@next2d/events
-=============
+# @next2d/events
 
-## Installation
+**重要**: `@next2d/events` は他の packages の import を禁止しています。このパッケージは基盤モジュールであり、循環依存を避けるために独立を維持する必要があります。
 
-```
+**Important**: `@next2d/events` prohibits importing other packages. This package is a foundational module that must remain independent to avoid circular dependencies.
+
+## 概要 / Overview
+
+`@next2d/events` パッケージは、EventDispatcher パターンに基づく包括的なイベント処理システムを提供します。このパッケージは、イベントのバブリング、キャプチャリング、およびインタラクティブアプリケーションで一般的に使用される様々なイベントタイプをサポートする堅牢なイベントフロー機構を実装しています。
+
+The `@next2d/events` package provides a comprehensive event handling system based on the EventDispatcher pattern. This package implements a robust event flow mechanism with support for event bubbling, capturing, and various event types commonly used in interactive applications.
+
+## インストール / Installation
+
+```bash
 npm install @next2d/events
 ```
 
-## License
+## 特徴 / Features
+
+- **EventDispatcher パターン**: イベント駆動型アーキテクチャのためのオブザーバーパターンの完全な実装
+  - Complete implementation of the observer pattern for event-driven architecture
+- **イベントフロー制御**: イベント伝播制御を備えたキャプチャリングフェーズとバブリングフェーズのサポート
+  - Support for capturing and bubbling phases with event propagation control
+- **複数のイベントタイプ**: 一般的なユースケース（ポインター、キーボード、フォーカス、ビデオなど）のための事前定義されたイベントクラス
+  - Pre-defined event classes for common use cases (pointer, keyboard, focus, video, etc.)
+- **型安全性**: 包括的な型定義による完全な TypeScript サポート
+  - Full TypeScript support with comprehensive type definitions
+- **サービスベースアーキテクチャ**: イベントディスパッチャー操作のためのモジュラーサービス層
+  - Modular service layer for event dispatcher operations
+
+## ディレクトリ構造 / Directory Structure
+
+```
+@next2d/events/
+├── src/
+│   ├── Event.ts                      # 基本イベントクラス / Base event class
+│   ├── EventDispatcher.ts            # イベントディスパッチャーの実装 / Event dispatcher implementation
+│   ├── EventPhase.ts                 # イベントフェーズ定数 / Event phase constants
+│   ├── EventUtil.ts                  # イベントユーティリティ関数 / Event utility functions
+│   │
+│   ├── EventDispatcher/
+│   │   └── service/                  # イベントディスパッチャーサービス層 / Event dispatcher service layer
+│   │       ├── EventDispatcherAddEventListenerService.ts
+│   │       ├── EventDispatcherDispatchEventService.ts
+│   │       ├── EventDispatcherHasEventListenerService.ts
+│   │       ├── EventDispatcherRemoveEventListenerService.ts
+│   │       ├── EventDispatcherRemoveAllEventListenerService.ts
+│   │       └── EventDispatcherWillTriggerService.ts
+│   │
+│   ├── interface/                    # TypeScript インターフェース / TypeScript interfaces
+│   │   ├── IEvent.ts
+│   │   ├── IEventDispatcher.ts
+│   │   ├── IEventListener.ts
+│   │   └── IURLRequestHeader.ts
+│   │
+│   └── [イベントタイプ / Event Types]
+│       ├── PointerEvent.ts           # マウスとタッチイベント / Mouse and touch events
+│       ├── KeyboardEvent.ts          # キーボード入力イベント / Keyboard input events
+│       ├── FocusEvent.ts             # フォーカス変更イベント / Focus change events
+│       ├── WheelEvent.ts             # マウスホイールイベント / Mouse wheel events
+│       ├── VideoEvent.ts             # ビデオ再生イベント / Video playback events
+│       ├── JobEvent.ts               # Tween ジョブイベント / Tween job events
+│       ├── HTTPStatusEvent.ts        # HTTP ステータスイベント / HTTP status events
+│       ├── IOErrorEvent.ts           # I/O エラーイベント / I/O error events
+│       └── ProgressEvent.ts          # ロード進捗イベント / Load progress events
+```
+
+## イベントフロー / Event Flow
+
+イベントシステムは、W3C DOM イベントモデルと同様の3フェーズイベントフロー機構を実装しています。
+
+The event system implements a three-phase event flow mechanism similar to the W3C DOM event model.
+
+```mermaid
+sequenceDiagram
+    participant Stage as Stage / ステージ
+    participant Parent as Parent / 親
+    participant Target as Target / ターゲット
+
+    Note over Stage,Target: Phase 1: Capturing Phase / キャプチャリングフェーズ
+    Stage->>Parent: eventPhase = CAPTURING_PHASE (1)
+    Parent->>Target: eventPhase = CAPTURING_PHASE (1)
+
+    Note over Target: Phase 2: Target Phase / ターゲットフェーズ
+    Target->>Target: eventPhase = AT_TARGET (2)
+
+    Note over Target,Stage: Phase 3: Bubbling Phase (if bubbles=true) / バブリングフェーズ
+    Target->>Parent: eventPhase = BUBBLING_PHASE (3)
+    Parent->>Stage: eventPhase = BUBBLING_PHASE (3)
+
+    Note over Stage,Target: Event Flow Control / イベントフロー制御
+    rect rgb(255, 240, 240)
+        Note over Target: stopPropagation()<br/>Stops further propagation / 以降の伝播を停止
+    end
+    rect rgb(255, 230, 230)
+        Note over Target: stopImmediatePropagation()<br/>Stops all listeners immediately / すべてのリスナーを即座に停止
+    end
+```
+
+## コアクラス / Core Classes
+
+### Event
+
+すべてのイベントの基本クラス。コアイベントプロパティと伝播制御メソッドを提供します。
+
+The base class for all events. Provides core event properties and propagation control methods.
+
+**主要プロパティ / Key Properties:**
+- `type`: イベントタイプ識別子 / Event type identifier
+- `bubbles`: イベントがバブリングフェーズに参加するかどうか / Whether the event participates in the bubbling phase
+- `target`: イベントリスナーを登録したオブジェクト / The object that registered the event listener
+- `currentTarget`: 現在イベントを処理しているオブジェクト / The object currently processing the event
+- `eventPhase`: イベントフローの現在のフェーズ / Current phase of event flow (CAPTURING_PHASE, AT_TARGET, BUBBLING_PHASE)
+
+**メソッド / Methods:**
+- `stopPropagation()`: 後続ノードでの処理を防止 / Prevents processing in subsequent nodes
+- `stopImmediatePropagation()`: 残りのすべてのリスナーの処理を防止 / Prevents processing of all remaining listeners
+
+### EventDispatcher
+
+イベントを送出するすべてのクラスの基本クラス。イベントリスナーの登録とイベントの送出を管理します。
+
+The base class for all classes that dispatch events. Manages event listener registration and event dispatching.
+
+**メソッド / Methods:**
+- `addEventListener(type, listener, useCapture, priority)`: イベントリスナーを登録 / Register an event listener
+- `removeEventListener(type, listener, useCapture)`: イベントリスナーを削除 / Remove an event listener
+- `removeAllEventListener(type, useCapture)`: 特定タイプのすべてのリスナーを削除 / Remove all listeners of a specific type
+- `dispatchEvent(event)`: イベントをイベントフローに送出 / Dispatch an event into the event flow
+- `hasEventListener(type)`: イベントタイプのリスナーが存在するか確認 / Check if a listener exists for an event type
+- `willTrigger(type)`: このオブジェクトまたは祖先がイベントタイプのリスナーを持つか確認 / Check if this object or ancestors have listeners for an event type
+
+### EventPhase
+
+イベントフローの現在のフェーズを定義する定数。
+
+Constants defining the current phase of event flow.
+
+- `CAPTURING_PHASE = 1`: キャプチャフェーズ / The capture phase
+- `AT_TARGET = 2`: ターゲットフェーズ / The target phase
+- `BUBBLING_PHASE = 3`: バブリングフェーズ / The bubbling phase
+
+## イベントタイプ / Event Types
+
+### PointerEvent
+
+ポインターデバイスの操作（マウス、ペン、タッチ）を処理します。
+
+Handles pointer device interactions (mouse, pen, touch).
+
+**イベントタイプ / Event Types:**
+- `POINTER_DOWN`: ボタンの押下開始 / Button press started
+- `POINTER_UP`: ボタンの解放 / Button released
+- `POINTER_MOVE`: ポインター座標の変化 / Pointer coordinates changed
+- `POINTER_OVER`: ポインターがヒットテスト境界に入った / Pointer entered hit test boundary
+- `POINTER_OUT`: ポインターがヒットテスト境界を出た / Pointer left hit test boundary
+- `POINTER_LEAVE`: ポインターが要素領域を離れた / Pointer left element area
+- `POINTER_CANCEL`: ポインター操作がキャンセルされた / Pointer interaction canceled
+- `DOUBLE_CLICK`: ダブルクリック/タップが発生 / Double-click/tap occurred
+
+### KeyboardEvent
+
+キーボード入力を処理します。
+
+Handles keyboard input.
+
+**イベントタイプ / Event Types:**
+- `KEY_DOWN`: キーが押された / Key pressed
+- `KEY_UP`: キーが離された / Key released
+
+### FocusEvent
+
+表示オブジェクト間のフォーカス変更を処理します。
+
+Handles focus changes between display objects.
+
+**イベントタイプ / Event Types:**
+- `FOCUS_IN`: 要素がフォーカスを受け取った / Element received focus
+- `FOCUS_OUT`: 要素がフォーカスを失った / Element lost focus
+
+### WheelEvent
+
+マウスホイールの操作を処理します。
+
+Handles mouse wheel interactions.
+
+**イベントタイプ / Event Types:**
+- `WHEEL`: マウスホイールが回転した / Mouse wheel rotated
+
+### VideoEvent
+
+ビデオ再生の状態変化を処理します。
+
+Handles video playback state changes.
+
+**イベントタイプ / Event Types:**
+- `PLAY`: ビデオ再生がリクエストされた / Video play requested
+- `PLAYING`: ビデオ再生が開始された / Video playback started
+- `PAUSE`: ビデオが一時停止された / Video paused
+- `SEEK`: ビデオシーク操作 / Video seek operation
+
+### JobEvent
+
+Tween アニメーションイベントを処理します。
+
+Handles tween animation events.
+
+**イベントタイプ / Event Types:**
+- `UPDATE`: Tween プロパティが更新された / Tween property updated
+- `STOP`: Tween ジョブが停止した / Tween job stopped
+
+### ProgressEvent
+
+ファイルやデータのロード進捗を処理します。
+
+Handles loading progress for files and data.
+
+**プロパティ / Properties:**
+- `bytesLoaded`: これまでにロードされたバイト数 / Bytes loaded so far
+- `bytesTotal`: ロードする合計バイト数 / Total bytes to load
+
+**イベントタイプ / Event Types:**
+- `PROGRESS`: ロード進捗の更新 / Loading progress update
+
+### HTTPStatusEvent
+
+HTTP レスポンスステータスを処理します。
+
+Handles HTTP response status.
+
+**プロパティ / Properties:**
+- `status`: HTTP ステータスコード / HTTP status code
+- `responseURL`: レスポンス URL / Response URL
+- `responseHeaders`: レスポンスヘッダーの配列 / Array of response headers
+
+**イベントタイプ / Event Types:**
+- `HTTP_STATUS`: HTTP ステータスを受信 / HTTP status received
+
+### IOErrorEvent
+
+I/O 操作エラーを処理します。
+
+Handles I/O operation errors.
+
+**プロパティ / Properties:**
+- `text`: エラーメッセージテキスト / Error message text
+
+**イベントタイプ / Event Types:**
+- `IO_ERROR`: I/O エラーが発生 / I/O error occurred
+
+## 使用例 / Usage Example
+
+```typescript
+import { EventDispatcher, Event, PointerEvent } from '@next2d/events';
+
+// イベントディスパッチャーを作成 / Create an event dispatcher
+const dispatcher = new EventDispatcher();
+
+// イベントリスナーを追加 / Add event listener
+dispatcher.addEventListener(PointerEvent.POINTER_DOWN, (event: Event) => {
+    console.log('ポインターダウン / Pointer down:', event.target);
+});
+
+// イベントを送出 / Dispatch event
+const event = new PointerEvent(PointerEvent.POINTER_DOWN, true);
+dispatcher.dispatchEvent(event);
+
+// イベントリスナーを削除 / Remove event listener
+dispatcher.removeEventListener(PointerEvent.POINTER_DOWN, listener);
+```
+
+### イベントバブリングの例 / Event Bubbling Example
+
+```typescript
+import { EventDispatcher, Event } from '@next2d/events';
+
+const stage = new EventDispatcher();
+const parent = new EventDispatcher();
+const child = new EventDispatcher();
+
+// 階層を設定（child -> parent -> stage）
+// Setup hierarchy (child -> parent -> stage)
+
+// キャプチャフェーズリスナーを追加 / Add capturing phase listener
+stage.addEventListener(Event.ADDED, (e) => {
+    console.log('ステージ / Stage: Capturing', e.eventPhase); // 1
+}, true);
+
+// ターゲットフェーズリスナーを追加 / Add target phase listener
+child.addEventListener(Event.ADDED, (e) => {
+    console.log('子 / Child: Target', e.eventPhase); // 2
+});
+
+// バブリングフェーズリスナーを追加 / Add bubbling phase listener
+parent.addEventListener(Event.ADDED, (e) => {
+    console.log('親 / Parent: Bubbling', e.eventPhase); // 3
+});
+
+// 子からバブリングイベントを送出 / Dispatch bubbling event from child
+const event = new Event(Event.ADDED, true); // bubbles = true
+child.dispatchEvent(event);
+```
+
+## ライセンス / License
+
 This project is licensed under the [MIT License](https://opensource.org/licenses/MIT) - see the [LICENSE](LICENSE) file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next2d/events",
-  "version": "2.13.1",
+  "version": "3.0.1",
   "description": "Next2D Events Package",
   "author": "Toshiyuki Ienaga<ienaga@next2d.app> (https://github.com/ienaga/)",
   "license": "MIT",