# #125 Blend 操作・HTML Functional Class ガイド

## このガイドについて
このガイドだけで #125 Blend の役割、HTMLからの基本利用、正式8種、Runtime、Joint連携、検証方法まで確認できます。Development Order v1.1.1 の正式責務は「描画時の合成方法を管理する」です。

## 最初に
#125 Blend は、重なった描画同士をどの方法で合成するかを管理するMotion Componentです。透明度そのものや #124 Filterの blur / brightness / grayscale 等は #125 の責務ではありません。

## Blendとは
前景要素とその背後の描画が重なるときの合成方法です。Runtime 1.0.0ではDOMに CSS `mix-blend-mode` を適用します。

## 正式8種の意味
日本語表示では、先に「何をする合成か」が分かるように意味を表示し、正式Mode名は併記します。HTML属性・JavaScript APIへ渡す値は正式Mode名を使用します。

| 意味（日本語） | 正式Mode | Runtime CSS |
|---|---|---|
| 通常合成 | Normal | `normal` |
| 乗算・暗く合成 | Multiply | `multiply` |
| スクリーン・明るく合成 | Screen | `screen` |
| オーバーレイ・明暗を強調 | Overlay | `overlay` |
| 暗い方を採用 | Darken | `darken` |
| 明るい方を採用 | Lighten | `lighten` |
| 差分 | Difference | `difference` |
| 加算合成 | Add | `plus-lighter` |

`Add` はBone Flowの正式名称です。RuntimeのCSS表現として `plus-lighter` を使用します。

## HTML Functional Class
通常利用Classは **`bf-blend` の1件だけ**です。Public APIの数だけClassを作りません。

### Class一覧
- `bf-blend` — #125 BlendをHTMLから利用する正式入口。

### いつ使用するか
画像、カード、Shape、Previewなど、前景と背景の色を Multiply / Screen / Overlay 等で合成したいときに使用します。単なる透過率設定ではなく、重なった描画の色計算を変えたい場合に使用します。

### どこで使用するか
合成モードを適用したい前景要素そのものへ `class="bf-blend"` を付けます。背後に描画があるとき、重なり部分でBlend結果を確認できます。

### 参照するデータ
| 指定 | 意味 | 例 |
|---|---|---|
| `class="bf-blend"` | #125 Blendを有効にする正式Class | `class="bf-blend"` |
| `data-blend-mode` | 正式8種のBlend Mode | `data-blend-mode="Multiply"` |

Runtime mount後の `bone-blend` class、`data-bone-blend-mode`、`data-bone-blend-runtime` はRuntime状態表示です。通常利用者の初期設定入口は `bf-blend` / `data-blend-mode` です。

### 最小HTML
```html
<div class="bf-blend">
  Blend target
</div>
```
Mode省略時は `Normal` です。結果は **`mix-blend-mode: normal`** です。

### 完全な読み込み例
```html
<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="/boneflow/css/bone-blend.css">
</head>
<body>
  <div style="background:#ff5b8a;padding:30px">
    <div class="bf-blend" data-blend-mode="Multiply" style="background:#5ba6ff;padding:30px">
      Multiply target
    </div>
  </div>
  <script src="/boneflow/js/bone-blend.js"></script>
  <script src="/boneflow/js/bone-blend-functional-class.js"></script>
</body>
</html>
```

この完全な読み込み例では `data-blend-mode="Multiply"` のため、実CSS結果は **`mix-blend-mode: multiply`** です。

### 設定付きHTML
```html
<div class="bf-blend" data-blend-mode="Screen">Screen target</div>
```
結果は **`mix-blend-mode: screen`** です。

```html
<div class="bf-blend" data-blend-mode="Add">Add target</div>
```
結果は **`mix-blend-mode: plus-lighter`** です。

### HTML各指定の意味
`data-blend-mode` は大文字小文字を含め正式Modeと完全一致させます。`multiply` のような小文字へ自動補正しません。属性省略時は Normal です。

### HTML Functional ClassのJavaScript操作
```js
const target = document.querySelector('.bf-blend');
BoneBlendFunctionalClass.setMode(target, 'Overlay');
console.log(BoneBlendFunctionalClass.getCssBlendMode(target));
// overlay
```

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

## Preview
TEST画面では背景と前景を重ね、選択したModeを実際のCSS `mix-blend-mode` として適用します。Mode / CSS Value / CSS / Expression / Runtimeを同時に確認できます。

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

## Connection Image / Joint
正常接続では Source.mode (String) → Blend.mode (String)、Blend.cssBlendMode (String) → Target.cssBlendMode (String) を確認します。不存在Fieldや型不一致は #002 Bone Joint の正式異常表示を使用します。

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

## Security
未知Mode、正式表記と異なるMode、配列、null、getter/setter付きuntrusted objectを拒否します。Validationのためにgetterを実行しません。

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

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

## Public API
### BoneBlend Runtime
`getFormalModes`, `getBlendDefinition`, `normalizeMode`, `normalizeExpression`, `validateExpression`, `toCssBlendMode`, `toCssDeclaration`, `create`, `mount`, `setExpression`, `setMode`, `getExpression`, `getMode`, `getCssBlendMode`, `getCssDeclaration`, `getState`, `complete`, `reopen`, `destroy`, `isInstance`。

### BoneBlendFunctionalClass
`mount`, `mountAll`, `refresh`, `setExpression`, `setMode`, `getExpression`, `getMode`, `getCssBlendMode`, `unmount`, `isMounted`。

## Error / Troubleshooting
- Blendが変わらない: 背後に別色の描画が重なっているか、`/boneflow/js/bone-blend.js` と `/boneflow/js/bone-blend-functional-class.js` の読み込み、`bf-blend`、`data-blend-mode` を確認します。
- `BLEND_MODE_INVALID`: Modeが正式8種と完全一致しているか確認します。
- `BLEND_UNTRUSTED_ACCESSOR`: getter/setter付きobjectをExpressionとして渡していないか確認します。
- HTML属性変更が反映されない: `data-blend-mode` を変更した後は `BoneBlendFunctionalClass.refresh(element)` を使用します。

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