# Bone Flow #020 Label — Usage
> Browser表示は `/boneflow/test/bone-label.html` の「ガイドを開く」から確認できます。Markdown直開きに依存しません。


Package Version: 1.0.69
Runtime: BoneLabel 1.0.60  
対象: 親Component実装者 / #020利用側

## 1. 基本方針

親Componentが保持する正本参照は、#020内部DOMではなく `BoneLabel.Component` instanceです。

禁止する依存例:

- `.bone-label` を親側から検索して値を操作する。
- `.bone-label-text` を直接書き換える。
- #020内部CSS classやDOM階層を親の仕様として固定する。

## 2. Label単体生成

```javascript
const label = BoneLabel.createInstance(labelBone);
container.appendChild(label.getElement());
```

`new BoneLabel.Component(labelBone)` でも同じClassを生成できます。

## 3. 親へ吸着してinstanceを保持

```javascript
const label = BoneLabel.attachInstance(parentElement, labelBone);
parentComponentState.label = label;
```

親は以後 `parentComponentState.label` を利用します。

## 4. 既存親からinstance取得

```javascript
const label = BoneLabel.getInstance(parentElement);
```

これは `attachInstance()` だけでなく、既存 `attachToParent()` で吸着された#020にも使えます。

## 5. 値を取得・更新

```javascript
const current = label.getValue();
label.update({ text: "氏名" });
label.setValue(nextFullProperty);
```

`update()` は現在値へ部分Propertyをmergeします。

## 6. INPUT / OUT / State

```javascript
const input = label.getInput();
const output = label.getOutput();
const state = label.getState();
```

親ComponentはLabelのDOM解析をせず、正式データを直接取得できます。

## 7. 親から解除・再吸着

```javascript
label.detach();
label.attach(nextParentElement);
```

`detach()` 後もinstanceは生存し、Label単体として再利用できます。

## 8. 破棄

```javascript
label.destroy();
```

破棄後の操作は `BONE_LABEL_CLASS_DESTROYED` になります。

## 9. Callback

```javascript
const label = BoneLabel.attachInstance(parentElement, labelBone, {
  onAttach(state, instance) {},
  onUpdate(state, instance) {},
  onDetach(state, instance) {},
  onDestroy(state, instance) {}
});
```

## 10. Event

親吸着時は現在ownerである親要素から `bone-label:attach` 等を受け取れます。`event.detail` にStateが入ります。

## 11. #040 ColorPickerとの関係

#020の色Propertyは #040 ColorPicker 1.0.18 のCaller方式を利用します。v1.0.55では背景を1つのPropertyへ統合し、文字色 / 背景 / 枠色はSolid / Transparent / Gradient、影色 / 発光色はSolid / Transparentを扱います。Class API側へ#040内部DOM・palette・CSSをコピーしません。

## 12. Completion前確認

親吸着後に以下を確認します。

1. instanceを保持または `getInstance()` で取得できる。
2. `update()` がLabel表示へ反映される。
3. `getInput()` / `getOutput()` / `getState()` を取得できる。
4. `detach()` 後に親からLabelが解除される。
5. `destroy()` 後に破棄済み状態になる。
6. 親側が#020内部DOMを直接操作していない。


## 親要素へ吸着してFITする
1. 親DOM要素を取得する。
2. `BoneLabel.attachInstance(parentElement, { text: "氏名", parentPlacement: "fit" })` でinstanceを生成・吸着する。
3. 親は返されたinstanceを保持し、`setValue()` / `getOutput()` / `getState()` を使う。内部DOMを直接検索しない。

背景はテストUIの1つの「背景」Propertyから#040 ColorPickerを開き、単色・透過・グラデーションを選択できる。


## #022 Hover Border Effect

`hoverBorderEffect.enabled=true` の場合、#020内部DOMを親が直接触らず、#020が#022 Public APIへ委譲します。Label単体ではLabel、親吸着時は親要素が#022 targetです。


## #117 Animation

要素本体のMotionは#020内で実装せず、#117 Animationへ委譲します。BoneLabel Runtimeの依存判定は1.0.9以上（同一major.minor）です。

- `animationUiNo`: Animation UI番号
- `targetUiNo`: 対象UI番号
- `targetPart`: `whole` または `text`
- `type`: #117 Animation種類
- `direction`: `forward / reverse`
- `axis`: `horizontal / vertical`
- `speed`: `slow / normal / fast`
- `distance`: 移動距離
- `loop`: Loop ON/OFF
- `loopWaitMs`: Loop間WAIT
- `reducedMotion`: reduced-motion尊重

`BoneLabel.playEffect()` は内部で #117 `restart()` / `play()` を使用します。親吸着解除・Class `detach()` / `destroy()` 時は #117 `stop()` / `destroy()` も連動します。

#022 Hover Border Effectとは責務を分離します。#022は枠、#117は要素本体Motionです。