npm package: @sarap422/textillin
Description: Scroll-Triggered Text Animation Library (Vanilla JS / jQuery-Free)
Author: sarap422
Latest version: 2.0.0

# Textillin

スクロール連動テキストアニメーションライブラリ（Vanilla JS / jQuery不要）

Intersection Observer API を使用し、要素がビューポートに入ったタイミングで文字単位のアニメーションを自動実行します。


## 必要ファイル

```
textillin.js    （JavaScript）
textillin.scss  （SCSS）または textillin.min.css（コンパイル済みCSS）
```

jQuery は不要です。


## 基本的な使い方

### 1. ファイルの読み込み

```html
<link rel="stylesheet" href="textillin.min.css">
<script src="textillin.js"></script>
```

### 2. HTML に `tlt-エフェクト名` クラスを付与

```html
<strong class="tlt-fadeInBottom">
  <span>テキストがふわっと下から表示されます</span>
</strong>
```

これだけで、要素がスクロールで画面内に入ると自動的にアニメーションが実行されます。


## 利用可能なエフェクト

| クラス名 | 効果 |
|----------|------|
| `tlt-fadeIn` | フェードイン |
| `tlt-fadeInBottom` | 下からフェードイン |
| `tlt-fadeInTop` | 上からフェードイン |
| `tlt-fadeInLeft` | 左からフェードイン |
| `tlt-fadeInRight` | 右からフェードイン |
| `tlt-bounceIn` | バウンスイン |
| `tlt-bounceInBottom` | 下からバウンスイン |
| `tlt-bounceInTop` | 上からバウンスイン |
| `tlt-bounceInLeft` | 左からバウンスイン |
| `tlt-bounceInRight` | 右からバウンスイン |
| `tlt-flipIn` | フリップイン |
| `tlt-flipInX` | X軸フリップイン |
| `tlt-flipInY` | Y軸フリップイン |
| `tlt-flashIn` | フラッシュ |
| `tlt-shakeIn` | シェイク |
| `tlt-pulseIn` | パルス |
| `tlt-rollIn` | ロールイン |


## data 属性によるカスタマイズ

要素に `data-in-*` 属性を追加することで、アニメーションの挙動を変更できます。

| 属性 | 説明 | デフォルト |
|------|------|-----------|
| `data-in-effect` | インエフェクト名 | クラス名から自動判定 |
| `data-in-shuffle` | 文字をランダム順でアニメーション | `false` |
| `data-in-reverse` | 文字を逆順でアニメーション | `false` |
| `data-in-sync` | 全文字を同時にアニメーション | `false` |
| `data-in-delay` | 文字間のディレイ（ms） | `30` |
| `data-in-delayScale` | ディレイの倍率 | `1` |
| `data-out-effect` | アウトエフェクト名 | `fadeOut` |
| `data-out-shuffle` | アウト時にランダム順 | `false` |
| `data-out-reverse` | アウト時に逆順 | `false` |
| `data-out-delay` | アウト時の文字間ディレイ（ms） | `30` |
| `data-loop` | ループ再生 | `false` |
| `data-minDisplayTime` | ループ時の表示時間（ms） | `1000` |
| `data-initialDelay` | 初期ディレイ（ms） | `0` |

### 使用例

```html
<!-- 文字がシャッフルされながらフェードイン -->
<strong class="tlt-fadeInBottom">
  <span data-in-shuffle="true">シャッフル表示</span>
</strong>

<!-- 逆順で遅めに表示 -->
<strong class="tlt-bounceInBottom">
  <span data-in-reverse="true" data-in-delay="60">逆順表示</span>
</strong>

<!-- ループアニメーション（複数テキスト切り替え） -->
<strong class="tlt-fadeIn" data-loop="true" data-minDisplayTime="2000">
  <ul class="texts">
    <li>最初のテキスト</li>
    <li>次のテキスト</li>
    <li>最後のテキスト</li>
  </ul>
</strong>
```


## CSS タイミング修飾クラス

`is-scloaded` クラスと組み合わせて使用するタイミング制御クラスです。通常は自動付与されますが、独自のスタイルで利用する場合に参照してください。

### ディレイ（delayed）

| クラス | 遅延時間 |
|--------|----------|
| `delayed-0` | 0s |
| `delayed-1` | 0.25s |
| `delayed-2` | 0.5s |
| `delayed-3` | 0.75s |
| `delayed-4` | 1s |
| `delayed-5` | 1.25s |
| `delayed-6` | 1.5s |

### 高速化（fasted）

| クラス | 再生時間 |
|--------|----------|
| `fasted-1` | 0.75s |
| `fasted-2` | 0.5s |
| `fasted-3` | 0.25s |

### 低速化（slowed）

| クラス | 再生時間 |
|--------|----------|
| `slowed-1` | 1.5s |
| `slowed-2` | 2s |
| `slowed-3` | 3s |
| `slowed-4` | 4s |
| `slowed-5` | 5s |
| `slowed-10` | 10s |
| `slowed-20` | 20s |
| `slowed-30` | 30s |
| `slowed-60` | 60s |
| `slowed-90` | 90s |
| `slowed-120` | 120s |


## JavaScript API

初期化後、`window.TextillinOptimized` からAPIにアクセスできます。

```js
// 手動でアニメーションを実行
TextillinOptimized.trigger(element, 'fadeInBottom');

// カスタムエフェクトを追加
TextillinOptimized.addEffect('customEffect', 'customCssClassName');

// 統計情報を取得
TextillinOptimized.getStats();
// → { registeredTypes: [...], observedCount: 0, animatedCount: 5, availableEffects: 19 }

// 破棄（Observer を切断しメモリを解放）
TextillinOptimized.destroy();

// デバッグモード
TextillinOptimized.enableDebug();   // コンソールにアニメーション情報を出力
TextillinOptimized.disableDebug();
```


## 動作の仕組み

1. ページ読み込み時に `tlt-*` クラスを持つ要素を検出し、IntersectionObserver に登録
2. 要素がビューポートに10%以上入ると（下端から50pxのマージンあり）アニメーション発火
3. テキストを1文字ずつ `<span>` に分割し、個別にCSSアニメーションを適用
4. アニメーション済みの要素は監視を自動解除（メモリ効率化）
5. MutationObserver により、動的に追加された要素も自動検出・登録


## 対応ブラウザ

IntersectionObserver API に対応したモダンブラウザで動作します。

- Chrome 51+
- Firefox 55+
- Safari 12.1+
- Edge 15+


## ライセンス / クレジット

- Textillate: [Jordan Schroter](https://github.com/jschr/textillate) (MIT License)
- Lettering.js: [Dave Rupert](https://github.com/davatron5000/Lettering.js) (WTFPL License)
- Vanilla JS Lettering: [Chris Ferdinandi](https://github.com/cferdinandi/lettering) (MIT License)
- Animate.css: [Daniel Eden](https://github.com/animate-css/animate.css) (MIT License)