@next2d/ui 2.13.0 → 3.0.0

package/README.md

@@ -1,11 +1,298 @@
-@next2d/ui
-=============
+# @next2d/ui
 
-## Installation
+Animation utilities package for Next2D Player / Next2Dプレイヤー向けアニメーションユーティリティパッケージ
 
-```
+## Overview / 概要
+
+`@next2d/ui` provides a powerful animation system with Tween and comprehensive Easing functions for creating smooth, professional animations in your Next2D applications.
+
+`@next2d/ui` は、Next2Dアプリケーションでスムーズでプロフェッショナルなアニメーションを作成するための、TweenとEasing機能を備えた強力なアニメーションシステムを提供します。
+
+### Key Features / 主な機能
+
+- **Tween System**: Easy-to-use tweening API for animating object properties / オブジェクトプロパティをアニメーションするための使いやすいトゥイーンAPI
+- **Easing Functions**: 32 built-in easing functions for natural motion / 自然な動きのための32種類のイージング関数
+- **Job Chaining**: Chain multiple animations sequentially / 複数のアニメーションを連続して実行
+- **Event-Driven**: EventDispatcher-based architecture for animation lifecycle events / アニメーションライフサイクルイベント用のEventDispatcherベースアーキテクチャ
+
+## Installation / インストール
+
+```bash
 npm install @next2d/ui
 ```
 
-## License
+## Usage / 使い方
+
+### Basic Tween Animation / 基本的なトゥイーンアニメーション
+
+```typescript
+import { Tween, Easing } from "@next2d/ui";
+
+// Create a target object / 対象オブジェクトを作成
+const sprite = { x: 0, y: 0, alpha: 1 };
+
+// Create a tween animation / トゥイーンアニメーションを作成
+const job = Tween.add(
+    sprite,                    // Target object / 対象オブジェクト
+    { x: 0, y: 0, alpha: 0 },  // Start values / 開始値
+    { x: 100, y: 100, alpha: 1 }, // End values / 終了値
+    0,                         // Delay (seconds) / 遅延時間（秒）
+    2,                         // Duration (seconds) / 実行時間（秒）
+    Easing.inOutQuad           // Easing function / イージング関数
+);
+
+// Start the animation / アニメーションを開始
+job.start();
+```
+
+### Chaining Animations / アニメーションの連結
+
+```typescript
+const job1 = Tween.add(sprite, { x: 0 }, { x: 100 }, 0, 1, Easing.outQuad);
+const job2 = Tween.add(sprite, { x: 100 }, { x: 200 }, 0, 1, Easing.inQuad);
+
+// Chain animations / アニメーションを連結
+job1.chain(job2);
+job1.start();
+```
+
+## Directory Structure / ディレクトリ構造
+
+```
+src/
+├── Tween.ts                    # Tween class / Tweenクラス
+├── Job.ts                      # Job class / Jobクラス
+│   ├── service/                # Job service layer / Jobサービスレイヤー
+│   │   ├── JobStopService.ts           # Stop animation / アニメーション停止
+│   │   ├── JobEntriesService.ts        # Property entries management / プロパティエントリ管理
+│   │   ├── JobUpdateFrameService.ts    # Frame update processing / フレーム更新処理
+│   │   └── JobUpdatePropertyService.ts # Property update processing / プロパティ更新処理
+│   └── usecase/                # Job use case layer / Jobユースケースレイヤー
+│       ├── JobStartUseCase.ts          # Start animation / アニメーション開始
+│       └── JobBootUseCase.ts           # Boot animation loop / アニメーションループ起動
+├── Easing.ts                   # Easing class / Easingクラス
+│   └── service/                # All easing implementations (32 functions) / 全イージング実装（32関数）
+│       ├── EasingLinearService.ts
+│       ├── EasingInQuadService.ts / EasingOutQuadService.ts / EasingInOutQuadService.ts
+│       ├── EasingInCubicService.ts / EasingOutCubicService.ts / EasingInOutCubicService.ts
+│       ├── EasingInQuartService.ts / EasingOutQuartService.ts / EasingInOutQuartService.ts
+│       ├── EasingInQuintService.ts / EasingOutQuintService.ts / EasingInOutQuintService.ts
+│       ├── EasingInSineService.ts / EasingOutSineService.ts / EasingInOutSineService.ts
+│       ├── EasingInExpoService.ts / EasingOutExpoService.ts / EasingInOutExpoService.ts
+│       ├── EasingInCircService.ts / EasingOutCircService.ts / EasingInOutCircService.ts
+│       ├── EasingInElasticService.ts / EasingOutElasticService.ts / EasingInOutElasticService.ts
+│       ├── EasingInBackService.ts / EasingOutBackService.ts / EasingInOutBackService.ts
+│       └── EasingInBounceService.ts / EasingOutBounceService.ts / EasingInOutBounceService.ts
+├── interface/                  # TypeScript interfaces / TypeScriptインターフェース
+│   ├── IObject.ts
+│   └── IEntriesObject.ts
+└── index.ts                    # Package exports / パッケージエクスポート
+```
+
+## Available Easing Functions / 利用可能なイージング関数
+
+The `Easing` class provides 32 easing functions across 11 easing types with In, Out, and InOut variants.
+
+`Easing`クラスは、11種類のイージングタイプでIn、Out、InOutのバリエーションを含む32種類のイージング関数を提供します。
+
+### Linear / リニア
+- `Easing.linear` - Constant speed / 一定速度
+
+### Quadratic (Quad) / 二次関数
+- `Easing.inQuad` - Accelerating from zero velocity / ゼロ速度から加速
+- `Easing.outQuad` - Decelerating to zero velocity / ゼロ速度まで減速
+- `Easing.inOutQuad` - Acceleration until halfway, then deceleration / 中間まで加速、その後減速
+
+### Cubic / 三次関数
+- `Easing.inCubic` - Accelerating from zero velocity / ゼロ速度から加速
+- `Easing.outCubic` - Decelerating to zero velocity / ゼロ速度まで減速
+- `Easing.inOutCubic` - Acceleration until halfway, then deceleration / 中間まで加速、その後減速
+
+### Quartic (Quart) / 四次関数
+- `Easing.inQuart` - Accelerating from zero velocity / ゼロ速度から加速
+- `Easing.outQuart` - Decelerating to zero velocity / ゼロ速度まで減速
+- `Easing.inOutQuart` - Acceleration until halfway, then deceleration / 中間まで加速、その後減速
+
+### Quintic (Quint) / 五次関数
+- `Easing.inQuint` - Accelerating from zero velocity / ゼロ速度から加速
+- `Easing.outQuint` - Decelerating to zero velocity / ゼロ速度まで減速
+- `Easing.inOutQuint` - Acceleration until halfway, then deceleration / 中間まで加速、その後減速
+
+### Sinusoidal (Sine) / 正弦波
+- `Easing.inSine` - Accelerating from zero velocity / ゼロ速度から加速
+- `Easing.outSine` - Decelerating to zero velocity / ゼロ速度まで減速
+- `Easing.inOutSine` - Acceleration until halfway, then deceleration / 中間まで加速、その後減速
+
+### Exponential (Expo) / 指数関数
+- `Easing.inExpo` - Accelerating from zero velocity / ゼロ速度から加速
+- `Easing.outExpo` - Decelerating to zero velocity / ゼロ速度まで減速
+- `Easing.inOutExpo` - Acceleration until halfway, then deceleration / 中間まで加速、その後減速
+
+### Circular (Circ) / 円形
+- `Easing.inCirc` - Accelerating from zero velocity / ゼロ速度から加速
+- `Easing.outCirc` - Decelerating to zero velocity / ゼロ速度まで減速
+- `Easing.inOutCirc` - Acceleration until halfway, then deceleration / 中間まで加速、その後減速
+
+### Elastic / 弾性
+- `Easing.inElastic` - Elastic effect at the beginning / 開始時に弾性効果
+- `Easing.outElastic` - Elastic effect at the end / 終了時に弾性効果
+- `Easing.inOutElastic` - Elastic effect at both ends / 両端で弾性効果
+
+### Back / バック
+- `Easing.inBack` - Back up before moving forward / 前進する前に後退
+- `Easing.outBack` - Overshoot and settle / オーバーシュートして落ち着く
+- `Easing.inOutBack` - Back up and overshoot / 後退とオーバーシュート
+
+### Bounce / バウンス
+- `Easing.inBounce` - Bounce at the beginning / 開始時にバウンス
+- `Easing.outBounce` - Bounce at the end / 終了時にバウンス
+- `Easing.inOutBounce` - Bounce at both ends / 両端でバウンス
+
+### Easing Function Parameters / イージング関数のパラメータ
+
+All easing functions accept four parameters: / すべてのイージング関数は4つのパラメータを受け取ります:
+
+```typescript
+ease(t: number, b: number, c: number, d: number): number
+```
+
+- `t`: Current time / 現在の時間 (0 to d)
+- `b`: Beginning value / 開始値
+- `c`: Change in value / 変化量 (end value - beginning value)
+- `d`: Duration / 継続時間
+
+## Animation Flow / アニメーションフロー
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Tween
+    participant Job
+    participant JobStartUseCase
+    participant JobStopService
+    participant Easing
+    participant Target
+
+    User->>Tween: Tween.add(target, from, to, delay, duration, ease)
+    Tween->>Job: new Job(target, from, to, delay, duration, ease)
+    Job-->>User: Return Job instance
+
+    User->>Job: job.start()
+    Job->>JobStartUseCase: execute(job)
+
+    alt Has delay
+        JobStartUseCase->>JobStartUseCase: setTimeout(delay)
+        JobStartUseCase->>JobStartUseCase: Wait for delay
+    end
+
+    JobStartUseCase->>JobStartUseCase: Initialize entries
+    JobStartUseCase->>JobStartUseCase: Set startTime
+
+    loop Animation loop (requestAnimationFrame)
+        JobStartUseCase->>JobStartUseCase: Calculate currentTime
+
+        alt currentTime < duration
+            JobStartUseCase->>Easing: Calculate eased value
+            Easing-->>JobStartUseCase: Return eased value
+            JobStartUseCase->>Target: Update target properties
+            JobStartUseCase->>Job: Dispatch "enterFrame" event
+        else currentTime >= duration
+            JobStartUseCase->>Target: Set final values
+            JobStartUseCase->>Job: Dispatch "complete" event
+
+            alt Has nextJob
+                JobStartUseCase->>Job: Start nextJob
+            end
+
+            JobStartUseCase->>JobStartUseCase: Exit loop
+        end
+    end
+
+    opt User stops animation
+        User->>Job: job.stop()
+        Job->>JobStopService: execute(job)
+        JobStopService->>JobStopService: Clear timer
+        JobStopService->>JobStopService: Set stopFlag
+    end
+```
+
+## API Reference / APIリファレンス
+
+### Tween Class
+
+#### `Tween.add(target, from, to, delay, duration, ease): Job`
+
+Creates and returns a new Job instance for animation.
+
+アニメーション用の新しいJobインスタンスを作成して返します。
+
+**Parameters / パラメータ:**
+- `target: any` - Target object to animate / アニメーション対象オブジェクト
+- `from: IObject` - Starting property values / 開始プロパティ値
+- `to: IObject` - Ending property values / 終了プロパティ値
+- `delay: number = 0` - Delay before animation starts (seconds) / アニメーション開始前の遅延（秒）
+- `duration: number = 1` - Animation duration (seconds) / アニメーション継続時間（秒）
+- `ease: Function | null = null` - Easing function (defaults to linear) / イージング関数（デフォルトはlinear）
+
+**Returns / 戻り値:**
+- `Job` - Job instance / Jobインスタンス
+
+### Job Class
+
+Job class extends EventDispatcher and manages individual animation jobs.
+
+JobクラスはEventDispatcherを継承し、個別のアニメーションジョブを管理します。
+
+#### `job.start(): void`
+
+Starts the animation. / アニメーションを開始します。
+
+#### `job.stop(): void`
+
+Stops the animation. / アニメーションを停止します。
+
+#### `job.chain(nextJob: Job | null): Job | null`
+
+Chains another job to start after this one completes.
+
+このジョブの完了後に別のジョブを連結します。
+
+**Parameters / パラメータ:**
+- `nextJob: Job | null` - Next job to execute, or null to clear / 実行する次のジョブ、またはクリアするnull
+
+**Returns / 戻り値:**
+- `Job | null` - The chained job / 連結されたジョブ
+
+#### Properties / プロパティ
+
+- `target: any` - Target object / 対象オブジェクト
+- `from: IObject` - Start values / 開始値
+- `to: IObject` - End values / 終了値
+- `delay: number` - Delay time / 遅延時間
+- `duration: number` - Duration time / 継続時間
+- `ease: Function` - Easing function / イージング関数
+- `currentTime: number` - Current animation time / 現在のアニメーション時間
+- `nextJob: Job | null` - Next chained job / 次の連結ジョブ
+
+## Events / イベント
+
+Job class dispatches the following events: / Jobクラスは以下のイベントを発行します:
+
+- `enterFrame` - Dispatched on each animation frame / 各アニメーションフレームで発行
+- `complete` - Dispatched when animation completes / アニメーション完了時に発行
+
+```typescript
+job.addEventListener("complete", (event) => {
+    console.log("Animation completed!");
+});
+
+job.addEventListener("enterFrame", (event) => {
+    console.log("Current time:", job.currentTime);
+});
+```
+
+## License / ライセンス
+
 This project is licensed under the [MIT License](https://opensource.org/licenses/MIT) - see the [LICENSE](LICENSE) file for details.
+
+このプロジェクトは[MITライセンス](https://opensource.org/licenses/MIT)の下でライセンスされています - 詳細は[LICENSE](LICENSE)ファイルを参照してください。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@next2d/ui",
-  "version": "2.13.0",
+  "version": "3.0.0",
   "description": "Next2D UI Package",
   "author": "Toshiyuki Ienaga<ienaga@next2d.app> (https://github.com/ienaga/)",
   "license": "MIT",
@@ -24,6 +24,6 @@
     "url": "git+https://github.com/Next2D/Player.git"
   },
   "dependencies": {
-    "@next2d/events": "2.13.0"
+    "@next2d/events": "3.0.0"
   }
 }