DOC-0022 — Bone Flow #022 Hover Border Effect 操作・HTML Functional Classガイド

0. 文書情報

DOC ID: DOC-0022
TOC ID: TOC-0022
対象UI: UI-022
Component: #022 Hover Border Effect
現行Runtime: BoneHoverBorderEffect v1.0.10
DOC Version: 1.0.0
Status: active
HTML Functional Class: bf-hover-border-effect

このDOCは、現行の bone-hover-border-effect.js v1.0.10、bone-hover-border-effect.css v1.0.10、bone-hover-border-effect.html v1.0.10 の実装を基準にします。DOC本文はUI HTMLへ複製せず、UI-022 -> DOC-0022 -> DOC Registry -> DOC Loader -> Guide の経路で表示します。

1. #022 Hover Border Effectとは

#022は、既存のHTMLElementへ視覚的な枠Effectを重ねる共通UI Componentです。対象要素そのもののDOM内容を書き換えず、document.body 直下へ専用Overlayを生成し、対象要素の位置・幅・高さ・角丸に追従させます。

#022が担当するのは 枠Effectの表示と、その表示条件 です。対象Componentの値、入力、配送、Security、WAIT/FIFO/BLOCKED、業務上のActive判定は#022の責務ではありません。

責務分離

mouseover: DOMのMouse Enter / Leaveを#022が監視します。
active: 何をActiveとみなすかは利用Componentが決め、setActive(target, true/false) で#022へ伝えます。
both: Mouse OverまたはActiveのどちらかが真なら表示します。
#117 Animation: 要素自体の時間変化Motionを担当します。#022の枠Effectとは別責務です。
#040 ColorPicker: Property画面の色選択UIだけを担当します。#022のEffect意味やRuntime状態は#040へ移しません。
#002 Bone Joint: Test画面の接続イメージ検証に使用します。#022 Effect stateや対象DOMはJointのデータ配送先ではありません。

2. 最初に確認する場所

ページ上部の 操作ガイド DOC-0022 からこのDOCを開きます。
プロパティ設定 でTrigger / Effect / 色 / 方向 / 速度 / Spin設定を変更します。
対象要素 でButton / Input / Panelを切り替えます。
Preview でMouse OverとActiveを実操作します。
Class リスト / HTML Functional Class では通常利用Class bf-hover-border-effect 1つだけを確認します。
接続イメージ は#002 Bone Jointの共通3ケースを確認するための表示です。
Smoke Test / Validationは実際に実行し、画面を開いただけでPASS扱いしません。

3. HTML Functional Class — `bf-hover-border-effect`

通常利用Classは bf-hover-border-effect 1つだけです。

<button class="bf-hover-border-effect">保存</button>

このClassを付けたHTMLElementは、Runtime読込後に BoneHoverBorderEffect.attach(host, BoneHoverBorderEffect.defaults()) で自動マウントされます。

3.1 Classだけで使う場合のDefault

trigger: mouseover
effect: normal
color: #35f4ff
direction: clockwise
speed: normal
spinWidth: 2px
spinGlow: 12px

3.2 HTML側で直接指定するProperty

今回の正式Class契約では、Class指定だけを通常利用入口にします。data-effect、data-trigger、data-speed などの#022専用data属性は定義しません。

詳細設定が必要な場合はProperty Editorまたは正式Public APIを使います。Public API名をHTML Classへ増殖させません。

3.3 不採用の旧方式

通常利用では次を使用しません。

bone-html-class-use
data-bone-event
data-bone-args
data-bone-arg-N
Public API 11件を11個のHTML Classへ1対1変換する方式

これらは現在の bf-hover-border-effect 1-Class契約ではありません。

3.4 動的追加

ページ表示後に .bf-hover-border-effect 要素を追加した場合も、Functional Class bridgeのMutationObserverでscanされ、自動マウントされます。

4. Runtime Default / Property詳細

4.1 `trigger`

型: string / Enum
Default: mouseover
全値:
- mouseover: Mouse Enterで表示、Mouse Leaveで非表示。
- active: Mouse Overは表示条件にせず、利用Componentの setActive() だけで制御。
- both: Mouse OverまたはActiveのどちらかがtrueなら表示。
無効値: BONE_022_TRIGGER_INVALID
HTML Functional Class: Class単独ではDefault mouseover。変更はProperty EditorまたはPublic API。

4.2 `effect`

型: string / Enum
Default: normal
全値:
- normal: 2pxの固定色枠。弱い外側Glowを持つ。
- neon: 四辺を流れる破線状の周回線。方向・速度が反映される。
- spin: 固定外周の内側で大型conic-gradient Rotorだけを回転。外枠自体は回転しない。
- cross: 固定枠と中央側へ届くconic-gradient表現。独立Effectで、回転Animationは持たない。
- blink: 枠＋Glowを段階的に点滅。
無効値: BONE_022_EFFECT_INVALID

4.3 `color`

型: string
Runtime Default: #35f4ff
Test / Property正式契約: #RRGGBB
Property UI: #040 ColorPicker Caller APIへ委譲し、allowedKinds: ["solid"] の単色だけを受けます。
Runtime normalizeOptions() 自体は空でないstringを受け取りますが、正式Property UIでは #RRGGBB を維持します。
Gradient / Transparentを#022 Effect色として追加しません。

4.4 `direction`

型: string / Enum
Default: clockwise
全値:
- clockwise: 通常方向。
- counterclockwise: neon / spin のAnimation方向をreverseにする。
無効値: BONE_022_DIRECTION_INVALID
normal / cross / blink では視覚上の方向効果はありませんが、Options値として保持されます。

4.5 `speed`

型: string / Enum
Default: normal
全値とRuntime duration:
- slow: 2s
- normal: 1.2s
- fast: .65s
無効値: BONE_022_SPEED_INVALID
主に neon / spin / blink のAnimation durationへ使用します。

4.6 `spinWidth`

型: number
単位: px
Default: 2
Runtime範囲: 1 ～ 24
無効/範囲外: Number()化し、有限数ならclamp。非数値はDefault 2。
使用Effect: spin の外周幅。

4.7 `spinGlow`

型: number
単位: px
Default: 12
Runtime範囲: 0 ～ 40
無効/範囲外: Number()化し、有限数ならclamp。非数値はDefault 12。
使用Effect: spin のdrop-shadow Glow量。

4.8 Loop Property

#022には正式な loop Propertyは存在しません。neon / spin / blink のCSS AnimationはEffect表示中に継続しますが、Consumer向けに独自Loop Propertyを追加しません。

5. Effectごとの使い分け

normal

最も単純な選択です。入力欄、Button、Panelなどに「現在Mouse Over中」を静かに示したい場合に使います。回転や点滅が不要な場合の基準です。

neon

枠の周囲を流れる線で継続的な注意を示します。方向と速度が視認できます。spin と違い、四辺に沿う破線状周回線です。

spin

外周の内側でconic-gradient Rotorを回転させます。正式基準は#036 Select v1.1.1由来の表現です。外枠自体を回転させないため、対象要素の配置や文字は回転しません。

cross

中央側まで届くconic表現を固定表示します。spin の静止版ではなく独立Effectです。方向・速度を視覚Motionとしては使用しません。

blink

枠の明暗を切り替えて注意を促します。速度が点滅周期へ反映されます。常時強調したい場合ではなく、短時間の注意表示などに向きます。

`prefers-reduced-motion`

OS/Browserで prefers-reduced-motion: reduce の場合、neon / spin / blink のCSS Animationは停止します。枠自体は表示できます。

6. Triggerの実操作

Mouse Over

trigger = mouseover を選択します。
Preview対象へマウスを入れます。
mouseenter でEffect表示。
mouseleave でEffect非表示。

Active

trigger = active を選択します。
利用Component側の状態変化に合わせて BoneHoverBorderEffect.setActive(target, true) を呼びます。
解除時は setActive(target, false)。

ON/OFF、selected、focused、errorなどのどの状態をActiveと呼ぶかはConsumer責務です。#022が推測しません。

Both

hovered || active が表示条件です。Mouse OutしてもActive=trueなら表示し続け、Active=falseでもMouse Over中なら表示します。

7. Public API — 11件

`defaults()`

引数なし。Runtime Default Optionsのコピーを返します。

`normalizeOptions(input)`

Optionsを正式Enum・数値範囲へ正規化して返します。無効EnumはError、数値はclampします。

`attach(target, options)`

target: HTMLElement
options: #022 Options
戻り値: target

既にattach済みのtargetへ再attachした場合は、一度detachして新しい状態を作ります。Overlayは document.body 直下へ生成します。

`detach(target)`

Mouse listener、ResizeObserver、Overlay、内部stateを削除します。attachされていなければfalse、削除した場合true。

`update(target, patch)`

attach済みtargetのOptionsを更新します。未attachなら BONE_022_NOT_ATTACHED。

`setActive(target, value)`

value === true のときだけActive=true。それ以外はfalse。Active trigger / Both triggerの表示条件に反映します。

`refresh(target)`

現在の getBoundingClientRect() と getComputedStyle(target).borderRadius からOverlay Geometryを再計算します。未attachならError。

`getOptions(target)`

attach済みなら現在Optionsのread-onlyコピー、未attachならnull。

`getState(target)`

attach済みなら次を返します。

attached
hovered
active
visible
trigger
effect

未attachならnull。

`getOverlay(target)`

#022が生成したOverlay Elementを返します。未attachならnull。

`isAttached(target)`

内部WeakMapへ登録済みかBooleanで返します。

8. Runtime Error / Validation

Runtimeで明示されているError Code:

BONE_022_TRIGGER_INVALID
BONE_022_EFFECT_INVALID
BONE_022_DIRECTION_INVALID
BONE_022_SPEED_INVALID
BONE_022_DOCUMENT_UNAVAILABLE
BONE_022_TARGET_INVALID
BONE_022_NOT_ATTACHED

Target条件

attach() / update() / setActive() / refresh() で対象Elementが必要です。targetはDOM Elementで、getBoundingClientRect() を持つ必要があります。

9. #040 ColorPickerとの関係

Test / Property画面ではEffect色の入力UIを#040 ColorPickerへ委譲します。

minimum: 1.0.15
同一 1.0.x でminimum以上のpatchを互換とする
必須Caller API: attachCaller() / getCallerState()
allowedKinds: ["solid"]
Overlay / Tooltip所有: #040
Overlay配置: document.body 直下
RETURN: 単色 #RRGGBB を#022 color Propertyへ戻す

#022側で#040のPalette、Gradient、Overlay位置計算を複製しません。

10. #117 Animationとの責務分離

#022の neon / spin / blink は 枠Effect内部の表現です。対象Element自身をMove / Bounce / Pulse / Slide / Zoomさせる責務ではありません。

対象ElementのMotionは#117 Animationを使用します。Consumerは必要に応じて #022 と #117 を同じElementへ独立して適用できます。

11. #002 Joint / WAIT / FIFO / BLOCKED

Test画面の 接続イメージ はBone Flow共通状態の確認用です。

正常接続
IN型不一致
OUT型不一致

これらは#002 Bone Jointの実判定・実描画を使用しますが、#022 Effect state / Overlay / target DOMへ値を配送する機能ではありません。

#022 Runtimeは BoneJoint.createDeliveryChannel() を持たず、WAIT / FIFO / BLOCKED配送を担当しません。したがって、#022固有のWAIT QueueやBLOCK解除APIを作りません。

12. Security

#022 Runtimeには独立したUntrusted IN / Securityパイプラインはありません。外部データを受信・commit・配送するComponentではなく、HTMLElementとOptionsを受けて表示Effectを管理します。

安全性に関係する実装上の検査は、TargetがElementか、Enumが正式値か、数値を範囲内へ正規化することです。存在しないSecurity TestをDOCへ追加しません。

13. Lifecycle / Geometry

attach: listener / ResizeObserver / Overlayを生成。
mouseenter / mouseleave: hovered state更新。
setActive: active state更新。
resize / scroll: 表示中Overlay Geometryを再計算。
refresh: 明示的再計算。
detach: listener / observer / overlay / stateを削除。

対象ElementがDOMから外れた場合、Geometry更新時にOverlayをhiddenにします。

14. Smoke Test / Validation / Runtime Console / Completion

Smoke Test

Runtime API、attach、Trigger、5 Effect、接続イメージ、#040 ColorPicker Caller、HTML Functional Class、DOC入口などの実契約を確認します。

Validation

全Trigger / Direction / Speed、Spin既定値とGeometry recipe、各Effect、JP/EN切替、Version互換、Completion初期状態等を確認します。

Runtime Console

Boot ErrorやRuntime操作の診断表示に使用します。Runtime Error 0かどうかは実画面で確認します。

Completion

Smoke TestとValidationが双方ALL PASSになった後にのみ完了操作が有効になります。ユーザーlocalhost確認前にDOCやAssistant側テストだけでCompleted / Frozenとは扱いません。

15. 日本語 / English切替

日本語 / English はProperty見出しだけでなく、Header説明、Effect/方向、対象、操作ボタン、Preview説明、接続イメージ、テスト操作、Runtime Console、Completion表示まで切り替えます。#040 ColorPicker Callerのlocaleも再接続して同期します。

16. 使用サンプル

16.1 最小 — Mouse Overで通常枠

何をする例か: ButtonへDefaultのHover Border Effectを付けます。
使用Class: bf-hover-border-effect
設定Property: Class単独なのでRuntime Default。

<button class="bf-hover-border-effect">保存</button>

実行結果: Mouse Over中だけ normal / #35f4ff の枠が表示されます。

16.2 PanelへClassを付ける

<div class="bf-hover-border-effect">設定パネル</div>

実行結果: HTMLElementの種類を限定せず、PanelにもDefault Effectをattachします。

16.3 Neonへ変更する

<button id="neon-target" class="bf-hover-border-effect">同期</button>
<script>
document.addEventListener("DOMContentLoaded", function () {
  BoneHoverBorderEffect.update(document.getElementById("neon-target"), {
    effect: "neon",
    speed: "fast",
    direction: "clockwise"
  });
});
</script>

注意: effect等を独自data属性へ書かず、正式Public APIを使用します。

16.4 Active状態だけで表示する

<button id="active-target">選択中</button>
<script>
const target = document.getElementById("active-target");
BoneHoverBorderEffect.attach(target, { trigger: "active", effect: "normal" });
BoneHoverBorderEffect.setActive(target, true);
</script>

実行結果: Mouse Overに関係なくActive=trueの間だけ表示します。

16.5 BothでHoverとActiveを併用する

<div id="both-target">選択カード</div>
<script>
const target = document.getElementById("both-target");
BoneHoverBorderEffect.attach(target, { trigger: "both", effect: "spin" });
BoneHoverBorderEffect.setActive(target, true);
</script>

実行結果: HoverまたはActiveのどちらかがtrueならEffectが見えます。

16.6 Spin幅とGlowを変更する

<button id="spin-target">実行</button>
<script>
const target = document.getElementById("spin-target");
BoneHoverBorderEffect.attach(target, {
  effect: "spin",
  spinWidth: 4,
  spinGlow: 18,
  speed: "slow"
});
</script>

範囲: spinWidth 1..24px、spinGlow 0..40px。

16.7 実行中に設定を更新する

<script>
BoneHoverBorderEffect.update(target, {
  effect: "blink",
  color: "#ff6b6b",
  speed: "fast"
});
</script>

既存attachを作り直さずOptionsを更新します。

16.8 Effectを完全に解除する

<script>
BoneHoverBorderEffect.detach(target);
</script>

Listener、ResizeObserver、Overlay、内部stateを削除します。

17. Dependencies

Runtime本体

bone-hover-border-effect.js はDOM APIを使用する独立Runtimeです。

Test / Property画面

#001 Bone Core: Bone Flow Test基盤の確認。
#002 Bone Joint: 接続イメージの実判定・実描画。
#020 Bone Label: #040 ColorPicker Callerが必要とするLabel APIの確認。
#040 ColorPicker: Effect色の正式Property選択UI。

これらのComponent内部実装を#022へ複製しません。

18. トラブル時の確認

Mouse Overしても表示されない

BoneHoverBorderEffect.isAttached(target) を確認。
trigger が active だけになっていないか確認。
targetがDOMへ接続されているか確認。

Activeで表示されない

trigger が active または both か確認。
Consumer側から setActive(target, true) を呼んだか確認。

Spinが動かない

effect = spin を確認。
prefers-reduced-motion: reduce が有効な場合はAnimation停止が正式挙動。

色が変更できない

#040 ColorPicker v1.0.15以上の互換patchとCaller APIを確認。
#022 Effect色はsolid #RRGGBB だけを使用。

DOCが開かない

bone-doc-loader.js
bone-doc-guide.js
doc-registry.json の DOC-0022
toc-registry.json の TOC-0022

を確認します。

#022 Hover Border Effect

bf-hover-border-effect

正式ガイド DOC-0022