# #116 Effect 操作ガイド

Version: Runtime 1.0.14 Candidate  
Status: Development  
HTML Functional Class: `bf-effect`  
DOC: DOC-0116 / TOC-0116

## 1. はじめに
#116 Effectは、Consumerが所有する対象Elementへ視覚効果を適用するMotion UIです。正式Development Orderは9種類だけです。#117 Animation、#118 Transitionとは別Componentです。

## 2. 責務境界
- #116: Effectの種類、Effect適用/解除、Effect色Property、Effect出力状態。
- #017 Text: Preview/Consumerの文字表示そのもの。
- #040 ColorPicker: Shadow / Glow / Color Changeなどの色選択。Consumerは#040内部Paletteを複製しません。
- #002 Bone Joint: #116 Effect → #017 Textの接続、WAIT/FIFO/BLOCKED、異常表示。
- #118 Transition: #116の直接依存ではありません。#040 Picker内部のOPEN/CLOSEで利用されるだけです。

## 3. HTML Functional Class
通常利用Classは `bf-effect` 1つです。Public API名をClassへ変換しません。

#017 TextへEffectを適用する最小例:

```html
<span class="bf-text bf-effect" data-effect="fade">Effect Text</span>
```

同じElementが#017 Textの表示対象であり、#116 EffectのTargetです。Generic Targetや `effectTarget` のような独自Fieldは使用しません。

## 4. 設定付きHTML
```html
<span
  class="bf-text bf-effect"
  data-effect="glow"
  data-glow-color="#35F4FF"
  data-glow-blur-1="6"
  data-glow-blur-2="14">
  Glow Text
</span>
```

Shadow:
```html
<span class="bf-text bf-effect"
      data-effect="shadow"
      data-shadow-color="#FFB84D">Shadow Text</span>
```

Color Change:
```html
<span class="bf-text bf-effect"
      data-effect="color-change"
      data-color-change="#FF4FD8">Color Change Text</span>
```

## 5. HTML属性
| 属性 | 必須 | 内容 |
|---|---:|---|
| `data-effect` | 省略可 | 9種類のEffect。省略時は `fade` |
| `data-shadow-color` | Shadow時 | #040 Solid `#RRGGBB` |
| `data-glow-color` | Glow時 | #040 Solid `#RRGGBB` |
| `data-color-change` | Color Change時 | #040 Solid `#RRGGBB` |
| `data-fade-opacity` | Fade | 0.00–1.00 / Default `0.30` |
| `data-fade-saturation` | Fade | 0以上 / Default `0.55` |
| `data-glow-blur-1` | Glow | px / 0以上 / Default `6` |
| `data-glow-blur-2` | Glow | px / 0以上 / Default `14` |
| `data-shadow-x` | Shadow | px / Default `4` |
| `data-shadow-y` | Shadow | px / Default `4` |
| `data-shadow-blur` | Shadow | px / 0以上 / Default `7` |
| `data-blur-radius` | Blur | px / 0以上 / Default `2` |
| `data-opacity` | Opacity | 0.00–1.00 / Default `0.58` |
| `data-scale` | Scale | 0より大きい値 / Default `1.12` |
| `data-rotate-angle` | Rotate | deg / Default `8` |
| `data-shake-duration` | Shake | 秒 / 0より大きい値 / Default `0.62` |
| `data-shake-distance` | Shake | px / 0以上 / Default `7` |

`intensity` のような曖昧な共通Propertyは使用せず、Effectごとの実値を直接指定します。

## 6. Runtime Default
- effect: `fade`
- shadowColor: `null`
- glowColor: `null`
- colorChangeColor: `null`
- fadeOpacity: `0.30`
- fadeSaturation: `0.55`
- glowBlur1: `6`
- glowBlur2: `14`
- shadowX: `4`
- shadowY: `4`
- shadowBlur: `7`
- blurRadius: `2`
- opacity: `0.58`
- scale: `1.12`
- rotateAngle: `8`
- shakeDuration: `0.62`
- shakeDistance: `7`

これらはv1.0.13まで固定だった見た目を、そのままv1.0.14の変更可能Defaultへ昇格した値です。色が必要なEffectで色が未指定の場合はエラーとして拒否します。RuntimeのDefaultと、テストページで効果を見やすくするDemo Sample色を混同しません。

## 7. 正式Effect 9種類
| 設定値 | 日本語名 | English | 説明 |
|---|---|---|---|
| `fade` | フェード | Fade | 対象を薄く見せる静的視覚効果。#118のENTER/EXITとは別。 |
| `glow` | 発光 | Glow | 指定色で文字の周囲を発光させる。Glow Colorは#040 Solid。 |
| `shadow` | 影 | Shadow | 指定色で文字に影を付ける。Shadow Colorは#040 Solid。 |
| `blur` | ぼかし | Blur | 対象をぼかして表示する。 |
| `opacity` | 不透明度 | Opacity | 対象の不透明度を下げる。Fadeとは別の固定視覚状態。 |
| `color-change` | 色変更 | Color Change | 文字色を#040で選択したSolid色へ変更する。 |
| `scale` | 拡大 | Scale | 対象を拡大して見せる。 |
| `rotate` | 回転 | Rotate | 対象を回転して見せる。 |
| `shake` | シェイク | Shake | 対象を左右に揺らして見せる。 |

## 8. Fade
`fade` は対象を薄く見せる静的Effectです。`fadeOpacity` と `fadeSaturation` を変更できます。Defaultは `0.30 / 0.55` です。状態A→Bの視覚遷移は#118 Transitionの責務であり、#116 FadeはTransitionの代用品ではありません。

## 9. Glow
`glow` は `glowBlur1` / `glowBlur2` / `glowColor` を使用します。Defaultは `6px / 14px`。色は#040 Solidのみです。

## 10. Shadow
`shadow` は `shadowX` / `shadowY` / `shadowBlur` / `shadowColor` を使用します。Defaultは `4px / 4px / 7px`。Previewでは背景色と異なるDemo Sample色を使い、影が見えることを確認します。

## 11. Blur / Opacity
Blurは `blurRadius`（Default `2px`）、Opacityは `opacity`（Default `0.58`）を変更できます。共通Intensityではなく実値を直接指定します。

## 12. Color Change
Color Changeは文字色を指定Solid色へ変更します。CSS named colorやGradient objectは受け入れません。

## 13. Scale / Rotate / Shake
Scaleは `scale`（Default `1.12`）、Rotateは `rotateAngle`（Default `8deg`）、Shakeは `shakeDuration`（Default `0.62s`）と `shakeDistance`（Default `7px`）を変更できます。#117 AnimationのTimeline/Job/Schedule責務を#116へ持ち込みません。

## 14. #040 ColorPicker Caller
テストページの色Propertyはnative `<input type="color">` を使いません。Consumer所有の色ボタンから:

```js
BoneColorPicker.attachCaller(trigger, {
  id: "effect-glow-color",
  type: "COLORPICKER",
  value: "#35F4FF"
}, {
  allowedKinds: ["solid"],
  onReturn(output) {
    BoneEffect.setOptions(effectInstance, {
      glowColor: output.value
    });
  }
});
```

#040内部chip/Overlay/CSSを#116へコピーしません。

## 15. #118 Transition
#118 Transitionは、**状態Aから状態Bへ移るときの一回のENTER / EXIT視覚補間**を担当するComponentです。#116 Effectの正式9種類とは責務が違います。

### #116 Effectとの違い
| 項目 | #116 Effect | #118 Transition |
|---|---|---|
| 主目的 | 対象へEffect状態をapply / clearする | ENTER / EXIT時の一回の視覚補間 |
| 状態所有 | Effectの適用状態を#116が管理 | open / closed / hidden等の意味状態はConsumerが管理 |
| `fade` | 対象を薄く見せる固定Effect | Fade In / Fade OutのENTER / EXIT |
| `scale` | 対象を拡大したEffect状態 | Scale In / Scale OutのENTER / EXIT |
| HTML Functional Class | `bf-effect` | `bf-transition` |
| #116の直接依存 | ― | **直接依存ではない** |

したがって、`bf-effect`へ `data-transition` / `data-direction` / `data-speed` を追加してはいけません。Transition設定は#116の正式Propertyではありません。

### #116で#040 ColorPickerを使うときの#118
#116のShadow / Glow / Color Change色Propertyは#040 ColorPicker Callerを使います。このときの実経路は次です。

```text
#116 色Propertyボタン
  -> BoneColorPicker.attachCaller(...)
  -> #040 Picker Panel
  -> #040内部の bf-transition
  -> #118 ENTER / EXIT
  -> Solid色を選択
  -> RETURN
  -> BoneEffect.setOptions(...)
```

ここで#118を直接操作するのは#116ではありません。**#040がPicker Panelのopen / closed状態を所有し、#118はそのPanelのENTER / EXITだけを担当**します。#116側は#040からRETURNされた色だけを受け取ります。

### Effect TargetそのものにもTransitionを使いたい場合
ConsumerがEffect Target自体へENTER / EXITも掛けたい場合は、#116へTransition Propertyを追加するのではなく、#118を**別Componentとして明示的に構成**します。例えばEffect Targetを包むTarget Partを `bf-transition` にします。

```html
<div
  class="bf-transition"
  data-transition-ui-no="UI-118-EFFECT-001"
  data-target-ui-no="UI-116-EFFECT-TARGET"
  data-target-part="effect-wrapper"
  data-transition="slide-fade"
  data-direction="down"
  data-speed="normal"
  data-respect-reduced-motion="true">

  <span class="bf-text bf-effect"
        data-effect="glow"
        data-glow-color="#35F4FF">
    Effect Text
  </span>
</div>
```

`bf-transition`を置くだけではENTER / EXITは自動実行されません。Consumerがmount済みinstanceを取得して呼びます。

```js
const host = document.querySelector('.bf-transition');
const transition = BoneTransitionFunctionalClass.getInstance(host);

async function enterTarget() {
  host.hidden = false;
  await BoneTransition.enter(transition);
}

async function exitTarget() {
  await BoneTransition.exit(transition);
  host.hidden = true;
}
```

`hidden`、`open`、`closed`などの意味状態はConsumer責務です。#118はその意味状態を所有しません。

### #118の正式設定値
`data-transition` は次の23値です。

`fade`, `slide`, `slide-fade`, `scale`, `scale-fade`, `zoom`, `zoom-fade`, `dissolve`, `wipe`, `reveal`, `expand`, `drop`, `pop`, `flip-x`, `flip-y`, `curtain-horizontal`, `curtain-vertical`, `shutter-horizontal`, `shutter-vertical`, `fold`, `rise`, `teleport-up`, `iris`

その他の正式設定:
- `data-direction`: `up / down / left / right`
- `data-speed`: `slow / normal / fast`
- `data-respect-reduced-motion`: `true / false`
- `bf-transition`ではRelation 3属性 `data-transition-ui-no` / `data-target-ui-no` / `data-target-part` が必須です。

#118の23 Transition各種の詳細な動作説明は、完成済み#118の操作ガイドを正式基準とします。#116はこの23種を自分のEffect種類として取り込みません。

## 16. Demo Background / Text Color
BackgroundとText ColorはテストページでEffectの見分けを良くするためのDemo表示値です。BoneEffectの正式Propertyではありません。Shadow / Glow / Color Changeの正式色Propertyと分離します。

## 17. #002 Joint 接続イメージ
接続イメージは装飾線ではなく、#002 Bone Joint v1.1.36 の `BoneJoint.evaluate()` と `BoneJoint.drawLine()` の実結果を描画します。全カードで `Source Exists / Target Exists / Source Field Exists / Target Field Exists / Compatibility / Joint State / Raw State` を分離表示します。

正式6ケース:

1. **CONNECTED** — #116 Effect `output` (STRING) → #017 Text `input` (STRING)。`connected`。
2. **Effect不存在** — Source Bone不存在。存在しないSource側へ通常Endpoint markerを置かず、赤系dashed line + 前面error cross。アニメーションなし。
3. **Text不存在** — Target Bone不存在。Source markerを残し、予定Target位置へ赤系dashed line + 前面error cross。アニメーションなし。
4. **TYPE-MISMATCH** — #116 Effect `output` (STRING) → #017 Text `number` (INT)。`JOINT_TYPE_INCOMPATIBLE` / connectionAllowed=false。NUMBER → STRINGは#002でcoercibleなので型不一致fixtureには使いません。
5. **DISCONNECTED** — Source / Target / Field / Compatibilityは存在したまま、`state: disconnected`。#002のdisconnected色、dashed line、中央 `//` break、アニメーションなし。
6. **RECONNECT** — `state: reconnecting`。#002のreconnecting色と専用アニメーションを使用し、#116独自の緑色へ上書きしません。

描画Z順は **Joint line → Source/Target Node → 異常marker/WAIT/BLOCK overlay** です。異常markerはNodeより前面に置きます。

## 18. WAIT / FIFO / BLOCKED
OUTは通常Previewと分離したDelivery Sandboxで確認します。実配送は `BoneEffect.connectOutput()` → #002 `createDeliveryChannel()` です。

- **WAIT**: Target BUSYでも接続線を維持します。#002の `bf-joint-waiting-spinner` をTarget側前面に表示し、WAIT-A / WAIT-B / WAIT-C の3件をQueueへ入れます。3秒後にTarget READYへ戻し、`WAIT-A → WAIT-B → WAIT-C` の順でFIFO配送されたことをTarget受信ログで確認します。
- **BLOCKED**: 接続は維持します。#002の `bf-joint-blocked-ban`（Font Awesome `fa-ban`）+ `data-animation="beat-fade"` をTarget側前面に表示します。BLOCK対象はTargetへ配送されません。
- **DISCONNECT / RECONNECT**: WAIT/BLOCKとは別状態です。切断はdashed + `//`、再接続中は#002 reconnecting表示を使用します。

WAIT/BLOCKテストが実際に成功した後だけ各目視確認checkboxを有効化します。checkboxをユーザーが確認するまではCompletion条件を満たしません。

## 19. Security
Securityは通常Previewと独立した **Source / Joint IN → #116 Security Gate → #116 Effect Sandbox (#017 Text)** の3ノードで表示します。Sandboxは実 `BoneText.create()` + `BoneEffect.create()/attach()/apply()` です。

- Valid Glow: ACCEPTEDしSecurity Sandboxだけを更新。
- Unknown Effect / CSS named color / Gradient object / Accessor object: BLOCKED。
- accessor getter/setterは評価しません。
- BLOCK時は#002の接続維持BLOCKED line + 前面 `fa-ban + beat-fade` を表示。
- BLOCK時はSecurity Sandboxの直前Optionと通常Previewを保持。

結果は状態表示とResult JSONの両方で確認します。

## 20. Property Editor
Property Editorは日本語 / Englishを実切替できます。言語切替は表示ラベルだけを変更し、Runtime値は変えません。

正式Property:
- Effect種類
- Fade: Opacity / Saturation
- Glow: Blur 1 / Blur 2 / Glow Color
- Shadow: X / Y / Blur / Shadow Color
- Blur: Blur Radius
- Opacity: Opacity
- Color Change: Color
- Scale: Scale
- Rotate: Angle
- Shake: Duration / Distance

Effect種類を選ぶと該当Effect固有設定だけを表示し、「Propertyを適用」で実 `BoneEffect.setOptions()` → Preview実CSSへ反映します。色Propertyは#040 ColorPicker Callerを使い、native `input[type=color]` は使用しません。

## 21. Preview
Preview Targetは実 #017 Textです。`BoneText.create()` で生成したElementへ `BoneEffect.attach()` し、Property変更を `BoneEffect.setOptions()` / `apply()` で反映します。Generic Targetや独自 `effectTarget` Fieldは作りません。

## 22. Smoke Test
Smoke Testは初期状態 `NOT RUN` です。実行後に個別結果、実行時間、総件数、PASS、FAILを表示します。主な確認対象:

- #001 / #002 / #017 / #040正式Dependency
- 9 Effect実apply/clear
- `bf-effect` 実mount
- #040 Caller実Overlay
- #002 6接続ケースと実TYPE-MISMATCH
- Property 日本語 / English切替
- Security Sandbox実Instance
- Delivery Sandbox実Channel

## 23. Validation
ValidationはSecurity拒否、型境界、Joint異常描画、WAIT/FIFO/BLOCKED、Report/Completion UIを確認します。特に以下を固定します。

- TYPE-MISMATCH = STRING → INT / `JOINT_TYPE_INCOMPATIBLE`
- Effect/Text不存在 = animationなし + 前面error marker
- DISCONNECTED = dashed + `//`
- RECONNECT = #002 reconnecting animation
- WAIT spinner = `.bf-joint-waiting-spinner`
- BLOCK icon = `.bf-joint-blocked-ban` + `beat-fade`
- Security BLOCK = Sandbox/Preview保持
- native color input = 0

テスト期待値を変更して見た目の不一致をPASSにしません。

## 24. 累積Regression
`bone-development-order.html` の#116行はfresh iframeで `bone-effect.html` を開き、正式Smoke / Validation buttonを実clickして結果を読みます。

累積対象:
- #116 BoneEffect bundle
- #116 Smoke Test
- #116 Validation
- #116 Runtime 1.0.14

#116のどれか1件FAILなら#000 overallもFAILです。runtime DOM clone方式は使用しません。

## 25. Completion
Completion Flagは初期 `false` / Status `Development` です。Completionは次の全条件を満たした場合だけ有効です。

1. Smoke Test ALL PASS
2. Validation ALL PASS
3. WAIT 3秒 / FIFO 3件の実配送テスト成功
4. WAIT目視確認checkboxをユーザーがON
5. BLOCK非配送テスト成功
6. `fa-ban + beat-fade` / 接続維持を目視確認してcheckboxをON

完了操作は `BoneEffect.complete()` のRuntime保存へ接続します。ユーザーlocalhost確認前はDevelopment / Candidateのままです。

## 26. Public API
`normalizeEffect`, `normalizeOptions`, `inspectUntrustedOptions`, `create`, `attach`, `apply`, `clear`, `setOptions`, `getOptions`, `getState`, `buildOutput`, `connectOutput`, `disconnectOutput`, `setOutputTargetReady`, `clearOutputBlock`, `getOutputState`, `destroy`, `isInstance`, `getCompletionState`, `complete`, `reopen`.

## 27. Error / Troubleshooting
- `EFFECT_TYPE_INVALID`: 9種類以外。
- `EFFECT_ACCESSOR_BLOCKED`: getter/setterを拒否。
- `EFFECT_COLOR_KIND_INVALID`: Solid以外のEffect色。
- `EFFECT_GLOW_COLOR_REQUIRED`: Glow Color未指定。
- `EFFECT_SHADOW_COLOR_REQUIRED`: Shadow Color未指定。
- `EFFECT_COLOR_CHANGE_COLOR_REQUIRED`: Color Change色未指定。
- `EFFECT_TARGET_INVALID`: Target Element不正。
- `EFFECT_OUTPUT_UNBOUND`: Delivery Channel未接続。
- `EFFECT_NUMBER_INVALID`: Effect固有値が有限数値ではない。
- `EFFECT_NUMBER_RANGE`: Effect固有値が許容範囲外。

## 28. Version / Status
Runtime v1.0.14 Candidate。User localhost確認前はDevelopmentです。過去Assistant生成v1.0.0〜v1.0.12は実装基準として再利用しません。

## Joint Runtime path
Connection diagnostics use formal #002 `BoneJoint.evaluate()` results and delegate rendering to #002. Decorative/fake Joint compatibility is not used.