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


Version: 1.0.61  
Status: Development

## 1. Class一覧

### `BoneLabel.Component`

#020 Label 1個をComponent instanceとして保持し、生成・親吸着・値更新・INPUT / OUT・State・解除・破棄を正式API経由で操作するClassです。

親Componentは `.bone-label` や `.bone-label-text` を検索して内部DOMを直接操作せず、このinstanceを保持します。

Constructor:

`new BoneLabel.Component(input[, options])`

- `input`: LABEL Bone、またはLabelのvalue object。
- `options`: lifecycle callback指定。

## 2. Factory / 参照API

| API | 説明 |
|---|---|
| `BoneLabel.createInstance(input[, options])` | Label単体instanceを生成 |
| `BoneLabel.attachInstance(parentElement, input[, options])` | 生成と親吸着を同時に実行 |
| `BoneLabel.getInstance(element)` | Label要素または吸着済み親要素からinstanceを取得 |
| `BoneLabel.getClassList()` | 正式Class一覧とMethod / Callback / Eventを取得 |
| `BoneLabel.getState(element)` | 既存#020 ownerのserializable Stateを取得 |

既存 `BoneLabel.attachToParent()` で吸着したLabelも `BoneLabel.getInstance(parentElement)` からClass参照へ移行できます。

## 3. `BoneLabel.Component` Method一覧

| Method | 説明 | Return |
|---|---|---|
| `getElement()` | 内部DOM検索なしでLabel表示要素を取得 | `Element` |
| `getParentElement()` | 現在の吸着親要素を取得 | `Element \| null` |
| `getValue()` | 正規化済みLabel Property取得 | object |
| `setValue(value)` | Property全体を設定して再描画 | instance |
| `update(patch)` | 現在値へ部分Propertyをmergeして再描画 | instance |
| `getInput()` | #020 INPUT取得 | object |
| `getOutput()` | #020 OUT取得 | object |
| `getState()` | 現在State取得 | object |
| `attach(parent)` | 親へ吸着 / 別親へ再吸着 | instance |
| `detach()` | 親から解除し、Label単体instanceとして継続 | instance |
| `playEffect()` | 現在の要素Motionを #117 Animation で再生 / restart | boolean |
| `getAnimationState()` | #117 Animation の現在Stateを取得 | object / null |
| `getAnimationOutput()` | #117 Animation OUTを取得 | object / null |
| `destroy()` | DOM / bindingを破棄しinstanceを終了 | `true` |
| `isDestroyed()` | 破棄済みか確認 | boolean |

## 4. State

`getState()` には以下を含みます。

- `componentId`, `componentName`, `version`
- `className`
- `boneId`, `type`
- `subject`
- `attached`
- `parentPlacement`
- `value`
- `input`
- `output`
- `destroyed`

親ComponentはState確認のために#020内部DOM構造を知る必要がありません。

## 5. Callback

Constructor / Factory の `options` で指定できます。

- `onAttach(state, instance)`
- `onUpdate(state, instance)`
- `onDetach(state, instance)`
- `onDestroy(state, instance)`

## 6. Event

現在のowner要素から以下を通知します。

- `bone-label:attach`
- `bone-label:update`
- `bone-label:detach`
- `bone-label:destroy`

`event.detail` はserializableなState snapshotです。

## 7. Error

代表的なClass APIエラー:

- `BONE_LABEL_PARENT_ELEMENT_REQUIRED`: attach対象の親要素が不正。
- `BONE_LABEL_CLASS_DESTROYED`: `destroy()` 後のinstanceを操作した。
- 既存のLabel Property Validation errorは従来どおり維持。

## 8. 後方互換

v1.0.51以前の `create()` / `attachToParent()` / `getInput()` / `getOutput()` は削除しません。Class APIは追加仕様です。


## v1.0.55 親吸着とFIT
`BoneLabel.Component#attach(parentElement)` は実DOMの親要素を受け取り、instanceを保持したままLabelを吸着する。`getParentElement()` で現在の親を取得できる。`parentPlacement: "fit"` を指定すると親表示領域へLabelをFITする。テストページの「Classリスト / Public API」でもClass名・constructor・methods・events/callbacksを確認できる。


## #022 Hover Border Effect 連携

| Method / API | 説明 |
|---|---|
| `instance.getHoverBorderEffectState()` | 現在の#022接続Stateを取得 |
| `instance.refreshHoverBorderEffect()` | 吸着先変更・サイズ変更後に#022 Geometryを再計算 |
| `BoneLabel.getHoverBorderEffectState(element)` | elementの#022 Stateを取得 |
| `BoneLabel.refreshHoverBorderEffect(element)` | elementの#022表示位置を再計算 |

`detach()` / `destroy()` は#022接続も解除します。


## #117 Animation 連携

#020の要素本体Motionは **#117 Animation v1.0.9** へ委譲します。#020は独自keyframe / Web Animations実装 / timer / loop schedulerを持ちません。

| API | 用途 |
|---|---|
| `instance.playEffect()` | 現在のRelationで #117 を play / restart |
| `instance.getAnimationState()` | #117 `getState()` を取得 |
| `instance.getAnimationOutput()` | #117 `getOutput()` を取得 |
| `BoneLabel.getAnimationState(element)` | elementに紐づく#117 State |
| `BoneLabel.getAnimationOutput(element)` | elementに紐づく#117 OUT |
| `BoneLabel.getAnimationDependency()` | `{ componentId: "117", version: "1.0.9" }` を取得 |

Relationは `animationUiNo :: targetUiNo :: targetPart`。`targetPart` は表示主体全体なら `whole`、ラベル文字のみなら `text` です。