# #124 Filter 操作・HTML Functional Class ガイド

## このガイドについて
このガイドだけで #124 Filter の役割、HTMLからの基本利用、設定値、Runtime、Joint連携、検証方法まで確認できるようにします。#124 の正式責務は Development Order v1.1.1 の「表示フィルターを管理する」です。正式Typeは Blur / Brightness / Contrast / Saturation / Grayscale / Sepia / Hue Rotate の7種です。

## 最初に
#124 Filter は「表示結果に静的な視覚フィルターを適用する」Motion Componentです。検索条件やデータ抽出のフィルターではありません。#116 Effectの演出、#117 Animationの時間経過、#120 Triggerの開始条件、#121 Timelineの時間制御、#123 Particle、#125 Blendの描画合成は #124 の責務ではありません。

## Filterとは
Filterは対象DOMへ CSS `filter` を適用するための表現です。#124 は `{type, value}` のExpressionを受け取り、Runtimeが `blur(4px)` や `brightness(120%)` のようなCSS文字列へ変換して対象要素へ反映します。

## HTML Functional Class
通常利用Classは **`bf-filter` の1件だけ**です。Public APIの数だけClassを作る方式ではありません。一般利用者は `bf-filter` から基本利用を開始できます。

### Class一覧
- `bf-filter` — #124 FilterをHTMLから利用する正式入口。

### いつ使用するか
画像、カード、Preview、任意のHTML要素などへ Blur / Brightness / Contrast / Saturation / Grayscale / Sepia / Hue Rotate を静的に適用したいときに使用します。

### どこで使用するか
フィルターを掛けたい要素そのものへ `class="bf-filter"` を付けます。子要素ではなく、その要素全体の描画結果にCSS filterが掛かります。

### 参照するデータ
HTML Functional Classが直接参照する公開属性は次の2つです。

| 指定 | 意味 | 例 |
|---|---|---|
| `class="bf-filter"` | #124 Filterを有効にする正式Class | `class="bf-filter"` |
| `data-filter-type` | 7種のFilter Type | `data-filter-type="Blur"` |
| `data-filter-value` | Typeに渡す数値 | `data-filter-value="4"` |

Runtimeがmountした後に付く `bone-filter` class、`data-bone-filter-type`、`data-bone-filter-value`、`data-bone-filter-runtime` はRuntime側の状態表示です。通常利用者が初期設定として直接書く入口は `bf-filter` / `data-filter-type` / `data-filter-value` です。

### 最小HTML
Blurの既定値を使う最小例です。

```html
<div class="bf-filter" data-filter-type="Blur">
  Filter target
</div>
```

必要Runtimeを読み込む完全な例です。

```html
<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <title>Bone Flow #124 Filter sample</title>
  <link rel="stylesheet" href="/boneflow/css/bone-filter.css">
</head>
<body>
  <div class="bf-filter" data-filter-type="Blur">
    Filter target
  </div>

  <script src="/boneflow/js/bone-filter.js"></script>
  <script src="/boneflow/js/bone-filter-functional-class.js"></script>
</body>
</html>
```

### 最小HTMLの結果
`bf-filter` が自動mountされ、BlurのRuntime Default `4` が使われます。対象要素の実CSS filterは **`blur(4px)`** になります。

### 設定付きHTML
TypeとValueをHTMLから指定する例です。

```html
<div class="bf-filter"
     data-filter-type="Brightness"
     data-filter-value="80">
  Brightness 80%
</div>
```

この例の実CSS filterは **`brightness(80%)`** です。

Hue Rotateの例です。

```html
<div class="bf-filter"
     data-filter-type="Hue Rotate"
     data-filter-value="180">
  Hue Rotate 180deg
</div>
```

この例の実CSS filterは **`hue-rotate(180deg)`** です。

### HTML各指定の意味
`data-filter-type` は大文字小文字を含め正式Typeと完全一致させます。`blur` のような小文字へ自動補正しません。`data-filter-value` は数値として解釈され、選択Typeの範囲外はValidation Errorです。属性を省略した場合、TypeはBlur、ValueはそのTypeのRuntime Defaultを使用します。

### HTML Functional ClassのJavaScript操作
HTML mount後に動的変更する場合は `BoneFilterFunctionalClass` を使用できます。

```html
<div id="photo" class="bf-filter" data-filter-type="Grayscale" data-filter-value="100">
  Target
</div>
<script>
  const target = document.getElementById("photo");
  BoneFilterFunctionalClass.setType(target, "Sepia");
  BoneFilterFunctionalClass.setValue(target, 60);
  console.log(BoneFilterFunctionalClass.getCssFilter(target));
  // sepia(60%)
</script>
```

## Runtime Default / 数値範囲
Development Order v1.1.1は7つのType名を定義しますが、数値Range/Defaultまでは定義していません。次の数値は #124 Runtime 1.0.0 の現在の実装値です。Specification Frozenの別仕様として扱わないでください。

| Type | CSS | Range | Step | Default |
|---|---|---:|---:|---:|
| Blur | `blur(px)` | 0–40 | 1 | 4 |
| Brightness | `brightness(%)` | 0–200 | 1 | 120 |
| Contrast | `contrast(%)` | 0–200 | 1 | 120 |
| Saturation | `saturate(%)` | 0–200 | 1 | 140 |
| Grayscale | `grayscale(%)` | 0–100 | 1 | 100 |
| Sepia | `sepia(%)` | 0–100 | 1 | 100 |
| Hue Rotate | `hue-rotate(deg)` | 0–360 | 1 | 90 |

## Property Editor
Property Languageで日本語 / Englishを切り替え、Filter TypeとFilter Valueを設定します。Filter Type変更時はそのTypeのRuntime Defaultへ切り替わります。Valueはスライダーと数値入力を同期し、Filter適用でPreviewへ反映します。

## 正式7種
- Blur — ぼかし。
- Brightness — 明るさ。
- Contrast — コントラスト。
- Saturation — 彩度。
- Grayscale — グレースケール。
- Sepia — セピア。
- Hue Rotate — 色相回転。

## 操作方法
通常利用では、(1) `bf-filter` を対象要素へ付ける、(2) `data-filter-type` でTypeを選ぶ、(3) 必要なら `data-filter-value` で値を指定する、の3点です。動的変更が必要な場合だけ Functional Class API または BoneFilter Public APIを使用します。TEST画面のSmoke / Security / Completionを順番に押すこと自体を、Filterの利用方法とはしません。

## Preview
TEST画面のFilter Previewは、選択したExpressionを実際の CSS `filter` へ変換して表示します。Type / Value / CSS / Expression / Runtimeを同時に確認できます。

## Dependencies / 責務境界
基盤は #001 Bone Core。Connection ImageとDelivery QAは正式 #002 Bone Joint 1.1.36へ委譲します。#124内で独自Jointを作りません。#116 Effect、#117 Animation、#120 Trigger、#121 Timeline、#123 Particle、#125 Blendの責務を#124へ追加しません。

## Connection Image / Joint
正常接続ではSourceのExpression(Object)をFilterへ渡し、Filterから生成したCSS文字列(String)をTargetへ渡す関係を確認します。不存在Fieldや型不一致は #002 Bone Joint の正式異常表示を使用します。

## WAIT / FIFO / BLOCKED
OUT配送は #002 `createDeliveryChannel()` の正式状態を使用します。WAITではTarget未Readyの間Queueへ保持し、READY後はFIFOで配送します。BLOCKEDではTargetへ配送されないことを確認します。`getState()` に存在しない `connectionEstablished` を捏造しません。

## Security
未知Type、正式表記と異なるType、範囲外Value、配列、null、getter/setterを持つuntrusted objectを拒否します。Validationのためにgetterを実行しません。

## Smoke Test / Validation
Smoke TestはRuntime、7種、Functional Class、Preview、#002 Joint、Deliveryなどの実装状態を確認します。Validationは責務境界、HTML ID、Completion gate、Connection異常系などを確認します。localhostで未実行の結果をALL PASSとは扱いません。

## Completion
Smoke / Validationの実行結果に加え、Filter Preview、Joint、WAIT→READY→FIFO、BLOCKEDの4項目をlocalhostで目視確認してから完了操作を行います。USER LOCALHOST確認前はDevelopment / Candidateです。

## Public API
### BoneFilter Runtime
`getFormalTypes`, `getFilterDefinition`, `normalizeType`, `normalizeValue`, `normalizeExpression`, `validateExpression`, `toCssFilter`, `create`, `mount`, `setExpression`, `setType`, `setValue`, `getExpression`, `getType`, `getValue`, `getCssFilter`, `getState`, `complete`, `reopen`, `destroy`, `isInstance`。

### BoneFilterFunctionalClass
`mount`, `mountAll`, `refresh`, `setExpression`, `setType`, `setValue`, `getExpression`, `getCssFilter`, `unmount`, `isMounted`。

HTML Functional Classは通常利用入口、Public APIは高度な動的操作です。両者をClass一覧で混同しません。

## Error / Troubleshooting
- Filterが掛からない: `/boneflow/js/bone-filter.js` と `/boneflow/js/bone-filter-functional-class.js` の読み込み、`bf-filter`、`data-filter-type` を確認します。
- `FILTER_TYPE_INVALID`: Typeが正式7種と完全一致しているか確認します。
- `FILTER_VALUE_RANGE`: 選択TypeのRange内か確認します。
- `FILTER_UNTRUSTED_ACCESSOR`: getter/setter付きobjectをExpressionとして渡していないか確認します。
- HTMLから設定したのに反映されない: `data-filter-type` / `data-filter-value` を変更した後は `BoneFilterFunctionalClass.refresh(element)` を使用します。

## Version / Status
Package Version 1.0.1 / Runtime BoneFilter 1.0.0 / HTML Functional Class `bf-filter` 1.0.0。現在はDevelopment / Candidateで、USER LOCALHOST確認前にCompleted / Specification Frozenとは扱いません。