# Bone Flow #020 - Label

## 0. Document information

DOC ID: `DOC-0020` / UI ID: `UI-020` / Runtime: `BoneLabel 1.0.60` / HTML Functional Class: `bf-label` / Package: `1.0.69`

This document is a **usage guide for actually using #020 Label**. It explains how the HTML Functional Class, Property Editor and JavaScript Component Class are used, instead of merely listing TEST-page controls.

## 1. Start here

For one ordinary Label in HTML, remember this line first.

```html
<div class="bf-label">Name</div>
```

The `Name` text becomes Runtime Property `text`. `bf-label` is the normal-use entry point; Public APIs are not split into separate HTML classes.

#020 owns Label text, placement, fit/fixed sizing, distribution, decoration and IN/OUT. Joint rendering is delegated to #002, Hover Border Effect to #022, color selection to #040, and element motion to #117. #040 Overlay OPEN/CLOSE belongs to #118.

## 2. What Label is

Label is not the input field itself. The subject can be a standalone Label or an existing parent attached through `BoneLabel.Component.attach(parentElement)`. Normal `bf-label` usage first creates a standalone Label.

## HTML Functional Class

Formal class: `bf-label`

The “Open HTML Functional Class Guide” button jumps directly to this section. Use it in this order.

1. Load `bone-label.css`.
2. Add `class="bf-label"` to the target element and put the Label text inside it.
3. Load `bone-label.js`.
4. Load `bone-label-html-class.js`.
5. The bridge auto-mounts a BoneLabel Runtime instance inside the host.

### 3. HTML Functional Class `bf-label`

`bf-label` is the **formal entry point for showing a basic Label from HTML without knowing the Public API**.

### 3.1 When to use it

Use it for fixed field names, headings and descriptive labels in ordinary HTML. You do not need to build the full Runtime Property object first.

### 3.2 Where to write it

Write a normal HTML element at the place where the Label should appear.

```html
<div class="bf-label">Name</div>
```

The element `innerText` becomes the initial Label text.

### 3.3 Required assets and minimum setup

Load CSS → BoneLabel Runtime → HTML Functional Class bridge.

```html
<link rel="stylesheet" href="/boneflow/css/bone-label.css">

<div class="bf-label">Name</div>

<script src="/boneflow/js/bone-label.js"></script>
<script src="/boneflow/js/bone-label-html-class.js"></script>
```

In this example, `Name` is the displayed text.

### 3.4 Complete copyable HTML file

```html
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Bone Label Sample</title>
  <link rel="stylesheet" href="/boneflow/css/bone-label.css">
</head>
<body>
  <div id="employee-name-label" class="bf-label">Name</div>

  <script src="/boneflow/js/bone-label.js"></script>
  <script src="/boneflow/js/bone-label-html-class.js"></script>
</body>
</html>
```

When the browser loads this file, the bridge scans `.bf-label` and mounts a formal Runtime instance equivalent to `BoneLabel.createInstance({ text: "Name" })`.

### 3.5 What happens after mount

The original `.bf-label` host remains in place and the BoneLabel Runtime-generated Label element is inserted inside it. The bridge adds these state markers to the host.

- `data-bf-label-mounted="true"` — mounted marker; do not write it manually.
- `data-bf-label-runtime="1.0.60"` — Runtime confirmation marker; do not write it manually.

Calling `mount()` again for the same host returns the existing instance instead of mounting twice.

### 3.6 What HTML can specify directly

The formal bridge reads **`class="bf-label"` and the element text** as user input.

| Input | Syntax | Meaning |
|---|---|---|
| Component entry | `class="bf-label"` | Mount as #020 Label |
| Initial text | `<div class="bf-label">Name</div>` | Pass `text="Name"` to Runtime |
| Other Runtime Properties | Not directly supported in HTML | Use Property Editor or JavaScript API |

Do **not invent unsupported HTML attributes** such as `data-font-size`, `data-label-width` or `data-border-color`.

### 3.7 Change settings from JavaScript

Retrieve the auto-mounted instance with `BoneLabelHTMLClass.getInstance(host)`.

```html
<div id="employee-name-label" class="bf-label">Name</div>
<script src="/boneflow/js/bone-label.js"></script>
<script src="/boneflow/js/bone-label-html-class.js"></script>
<script>
  const host = document.getElementById("employee-name-label");
  const label = BoneLabelHTMLClass.getInstance(host);

  label.update({
    text: "Employee ID",
    textStyle: {
      fontSize: 16,
      color: "#DCE8F8"
    },
    labelSize: {
      mode: "fit"
    }
  });
</script>
```

This keeps `bf-label` as the entry point while changing formal Runtime Properties through the API.

### 3.8 Read state and OUT

```js
const host = document.getElementById("employee-name-label");
const label = BoneLabelHTMLClass.getInstance(host);

console.log(label.getValue());
console.log(label.getOutput());
console.log(label.getState());
```

`getValue()` returns current Properties, `getOutput()` returns #020 OUT, and `getState()` returns instance state.

### 3.9 Elements added later by JavaScript

The bridge performs the initial scan and also watches added DOM through `MutationObserver`.

```js
const host = document.createElement("div");
host.className = "bf-label";
host.textContent = "Label added later";
document.body.appendChild(host);
```

The new element is mounted with the same `bf-label` contract.

### 3.10 Direct Runtime creation without HTML Functional Class

For advanced operation, call `BoneLabel.createInstance()` directly.

```js
const label = BoneLabel.createInstance({
  text: "Employee ID",
  position: "top",
  labelSize: { mode: "fixed", width: 160, height: 32 }
});

document.body.appendChild(label.getElement());
```

`bf-label` and `BoneLabel.Component` / Public API are separate entry points. Public API names are not HTML classes.

### 3.11 Common mistakes

- Do not assume detailed Runtime Properties automatically become HTML attributes.
- Do not manually write `data-bf-label-mounted` or `data-bf-label-runtime`.
- Do not load only the bridge before the BoneLabel Runtime.
- Do not use Public API names as HTML classes.
- Do not copy examples containing `...`; examples in this guide are written without omitted code.

## 4. Property Editor and combined Preview

Property changes are reflected into Preview. Property Editor is a different entry point from the HTML Functional Class, but both feed the same BoneLabel Runtime Property contract.

## 5. Runtime-owned Property Schema

BoneLabel Runtime owns the Property definitions. UI-local definitions are not the source of truth.

```js
BoneLabel.getPropertySchema();
BoneLabel.getPropertyDefaults();
BoneLabel.getPropertyDefinition("text");
```

These APIs define Property names, types, Defaults and enum/range constraints.

## 6. Runtime Default / Property details

The following values are **generated from the BoneLabel 1.0.60 Runtime-owned Property Schema**. Only `text`, through element innerText, is direct HTML Functional Class input.

### Basic (`basic`)

Controls Label text, association, base position and visibility state.

| Property | Type | Runtime Default | Allowed values / Range | Purpose | Direct HTML Functional Class input |
|---|---|---|---|---|---|
| `text` | `string` | `項目ラベル` | — | Displayed Label text. With the HTML Functional Class, the element innerText becomes this value. | `innerText` |
| `forId` | `string` | `` | — | When non-empty, Runtime creates a label element and assigns this value to its for attribute. | Property Editor / Public API |
| `position` | `enum` | `top` | `top` / `right` / `bottom` / `left` | Base standalone Label position: top / right / bottom / left. | Property Editor / Public API |
| `parentPlacement` | `enum` | `top-left` | `top-left` / `top-center` / `top-right` / `middle-left` / `center` / `middle-right` / `bottom-left` / `bottom-center` / `bottom-right` / `fit` | Placement inside a parent after attach. Ten values including fit. | Property Editor / Public API |
| `gap` | `number` | `6` | min `0` | Gap between the Label and its target. | Property Editor / Public API |
| `disabled` | `boolean` | `false` | — | Disabled state. Runtime reflects it as aria-disabled. | Property Editor / Public API |
| `hidden` | `boolean` | `false` | — | Hidden state. Runtime reflects it to the hidden property. | Property Editor / Public API |
| `title` | `string` | `` | — | title of the generated element. | Property Editor / Public API |

### Text (`textStyle`)

Controls font, size, weight, color, line height and letter spacing.

| Property | Type | Runtime Default | Allowed values / Range | Purpose | Direct HTML Functional Class input |
|---|---|---|---|---|---|
| `textStyle.fontFamily` | `string` | `Meiryo, Yu Gothic, sans-serif` | — | font-family for Label text. | Property Editor / Public API |
| `textStyle.fontSize` | `number` | `14` | min `8` | Label font size in px. | Property Editor / Public API |
| `textStyle.fontWeight` | `number` | `700` | min `100`; max `900`; step `100` | Label font weight, 100 to 900. | Property Editor / Public API |
| `textStyle.color` | `color` | `#dce8f8` | — | Label text color. | Property Editor / Public API |
| `textStyle.lineHeight` | `number` | `1.5` | min `0.1` | Label line-height. | Property Editor / Public API |
| `textStyle.letterSpacing` | `number` | `0` | — | Label letter-spacing. | Property Editor / Public API |

### Distribution (`distribution`)

Controls distributing text across Label width or parent width.

| Property | Type | Runtime Default | Allowed values / Range | Purpose | Direct HTML Functional Class input |
|---|---|---|---|---|---|
| `distribution.mode` | `enum` | `none` | `none` / `label-width` / `parent-width` | Text distribution mode: none / label-width / parent-width. | Property Editor / Public API |

### Size (`labelSize`)

Controls fixed versus fit sizing and fixed width/height.

| Property | Type | Runtime Default | Allowed values / Range | Purpose | Direct HTML Functional Class input |
|---|---|---|---|---|---|
| `labelSize.mode` | `enum` | `fixed` | `fixed` / `fit` | Label size mode: fixed or fit. | Property Editor / Public API |
| `labelSize.width` | `number` | `160` | min `20` | Label width in px when fixed. | Property Editor / Public API |
| `labelSize.height` | `number` | `32` | min `16` | Label height in px when fixed. | Property Editor / Public API |

### Decoration (`decoration`)

Controls background, gradient, border, padding, shadow, glow, outline, rotation and scale.

| Property | Type | Runtime Default | Allowed values / Range | Purpose | Direct HTML Functional Class input |
|---|---|---|---|---|---|
| `decoration.backgroundType` | `enum` | `solid` | `solid` / `gradient` | Background mode: solid or gradient. | Property Editor / Public API |
| `decoration.backgroundColor` | `color` | `transparent` | — | Solid background color; transparent is supported. | Property Editor / Public API |
| `decoration.gradientStart` | `color` | `#1c6fd1` | — | Gradient start color. | Property Editor / Public API |
| `decoration.gradientEnd` | `color` | `#7c3aed` | — | Gradient end color. | Property Editor / Public API |
| `decoration.gradientAngle` | `number` | `90` | min `0`; max `360` | Gradient angle in degrees. | Property Editor / Public API |
| `decoration.borderEnabled` | `boolean` | `false` | — | Enables the Label border. | Property Editor / Public API |
| `decoration.borderColor` | `color` | `#5ba6ff` | — | Label border color. | Property Editor / Public API |
| `decoration.borderWidth` | `number` | `1` | min `0` | Label border width in px. | Property Editor / Public API |
| `decoration.borderStyle` | `enum` | `solid` | `solid` / `dashed` / `dotted` / `double` | Border style: solid / dashed / dotted / double. | Property Editor / Public API |
| `decoration.borderRadius` | `number` | `6` | min `0` | Border radius in px. | Property Editor / Public API |
| `decoration.paddingX` | `number` | `6` | min `0` | Horizontal padding in px. | Property Editor / Public API |
| `decoration.paddingY` | `number` | `3` | min `0` | Vertical padding in px. | Property Editor / Public API |
| `decoration.shadowEnabled` | `boolean` | `false` | — | Enables box shadow. | Property Editor / Public API |
| `decoration.shadowX` | `number` | `0` | — | Shadow X offset in px. | Property Editor / Public API |
| `decoration.shadowY` | `number` | `3` | — | Shadow Y offset in px. | Property Editor / Public API |
| `decoration.shadowBlur` | `number` | `10` | min `0` | Shadow blur in px. | Property Editor / Public API |
| `decoration.shadowColor` | `color` | `rgba(0,0,0,.35)` | — | Shadow color. | Property Editor / Public API |
| `decoration.glowEnabled` | `boolean` | `false` | — | Enables glow. | Property Editor / Public API |
| `decoration.glowColor` | `color` | `#5ba6ff` | — | Glow color. | Property Editor / Public API |
| `decoration.outlineEnabled` | `boolean` | `false` | — | Enables text outline. | Property Editor / Public API |
| `decoration.outlineColor` | `color` | `#0b1220` | — | Outline color. | Property Editor / Public API |
| `decoration.outlineWidth` | `number` | `1` | min `0` | Outline width in px. | Property Editor / Public API |
| `decoration.rotation` | `number` | `0` | — | Label rotation angle. | Property Editor / Public API |
| `decoration.scale` | `number` | `1` | min `0` | Label scale. | Property Editor / Public API |

### #022 Hover Border Effect (`hoverBorderEffect`)

Formal settings passed to #022 Hover Border Effect; this is not a custom :hover renderer.

| Property | Type | Runtime Default | Allowed values / Range | Purpose | Direct HTML Functional Class input |
|---|---|---|---|---|---|
| `hoverBorderEffect.enabled` | `boolean` | `false` | — | Whether #022 Hover Border Effect is used. | Property Editor / Public API |
| `hoverBorderEffect.effect` | `enum` | `normal` | `normal` / `neon` / `spin` / `cross` / `blink` | Effect type passed to #022. | Property Editor / Public API |
| `hoverBorderEffect.color` | `color` | `#35f4ff` | — | Effect color passed to #022. | Property Editor / Public API |
| `hoverBorderEffect.direction` | `enum` | `clockwise` | `clockwise` / `counterclockwise` | Rotation direction passed to #022. | Property Editor / Public API |
| `hoverBorderEffect.speed` | `enum` | `normal` | `slow` / `normal` / `fast` | Speed passed to #022. | Property Editor / Public API |
| `hoverBorderEffect.spinWidth` | `number` | `2` | min `1`; max `24` | #022 spin line width. | Property Editor / Public API |
| `hoverBorderEffect.spinGlow` | `number` | `12` | min `0`; max `40` | #022 spin glow amount. | Property Editor / Public API |

### Animation Relation (`effect`)

Relation/motion settings delegated to #117 Animation; #020 does not own a motion engine.

| Property | Type | Runtime Default | Allowed values / Range | Purpose | Direct HTML Functional Class input |
|---|---|---|---|---|---|
| `effect.type` | `enum` | `none` | `none` / `move` / `bounce` / `pulse` / `spin` / `blink` / `slide` / `zoom` / `flow` / `shimmer` / `glow-sweep` / `breathing-glow` | Animation type delegated to #117. none disables it. | Property Editor / Public API |
| `effect.trigger` | `enum` | `self` | `self` / `parent` | Animation trigger owner: self or parent. | Property Editor / Public API |
| `effect.target` | `enum` | `subject` | `subject` / `text` | Animation target: subject or text. | Property Editor / Public API |
| `effect.animationUiNo` | `string` | `UI-117-020-001` | — | #117 Animation UI identifier. | Property Editor / Public API |
| `effect.targetUiNo` | `string` | `UI-020-001` | — | Animation target UI identifier. | Property Editor / Public API |
| `effect.targetPart` | `string` | `whole` | — | Animation target-part identifier. | Property Editor / Public API |
| `effect.direction` | `enum` | `forward` | `forward` / `reverse` | Animation direction: forward / reverse. | Property Editor / Public API |
| `effect.axis` | `enum` | `horizontal` | `horizontal` / `vertical` | Animation axis: horizontal / vertical. | Property Editor / Public API |
| `effect.speed` | `enum` | `normal` | `slow` / `normal` / `fast` | Animation speed: slow / normal / fast. | Property Editor / Public API |
| `effect.distance` | `number` | `24` | min `0`; max `10000` | Animation travel distance. | Property Editor / Public API |
| `effect.loop` | `boolean` | `true` | — | Enables animation looping. | Property Editor / Public API |
| `effect.loopWaitMs` | `number` | `300` | min `0`; max `60000` | Wait time between loops in ms. | Property Editor / Public API |
| `effect.enabled` | `boolean` | `false` | — | Enables Animation integration. | Property Editor / Public API |
| `effect.reducedMotion` | `boolean` | `true` | — | Reduced-motion preference flag. | Property Editor / Public API |

### Container (`containerStyle`)

Controls appearance of the Label container.

| Property | Type | Runtime Default | Allowed values / Range | Purpose | Direct HTML Functional Class input |
|---|---|---|---|---|---|
| `containerStyle.minWidth` | `number` | `0` | min `0` | Container minimum width. | Property Editor / Public API |
| `containerStyle.maxWidth` | `number|null` | `null` | — | Container maximum width; null means no explicit maximum. | Property Editor / Public API |
| `containerStyle.paddingTop` | `number` | `0` | min `0` | Top padding in px. | Property Editor / Public API |
| `containerStyle.paddingRight` | `number` | `0` | min `0` | Right padding in px. | Property Editor / Public API |
| `containerStyle.paddingBottom` | `number` | `0` | min `0` | Bottom padding in px. | Property Editor / Public API |
| `containerStyle.paddingLeft` | `number` | `0` | min `0` | Left padding in px. | Property Editor / Public API |
| `containerStyle.backgroundColor` | `color|null` | `null` | — | Container background color; null means unspecified. | Property Editor / Public API |
| `containerStyle.borderEnabled` | `boolean` | `false` | — | Enables container border. | Property Editor / Public API |
| `containerStyle.borderColor` | `color` | `#425a78` | — | Container border color. | Property Editor / Public API |
| `containerStyle.borderWidth` | `number` | `1` | min `0` | Container border width in px. | Property Editor / Public API |
| `containerStyle.borderStyle` | `enum` | `solid` | `solid` / `dashed` / `dotted` / `double` | Container border style. | Property Editor / Public API |
| `containerStyle.borderRadius` | `number` | `6` | min `0` | Container border radius in px. | Property Editor / Public API |
| `containerStyle.opacity` | `number` | `1` | min `0`; max `1` | Container opacity, 0 to 1. | Property Editor / Public API |


## 7. Placement / FIT

`parentPlacement` has ten values: `top-left / top-center / top-right / middle-left / center / middle-right / bottom-left / bottom-center / bottom-right / fit`. `position` is `top / right / bottom / left`, `labelSize.mode` is `fixed / fit`, and `distribution.mode` is `none / label-width / parent-width`.

## 8. Text and decoration

Text color, background, gradient, border, shadow, glow, outline, rotation and scale are Runtime Properties. Color UI uses the formal #040 ColorPicker Caller route instead of a Consumer-owned native color picker.

## 9. #040 ColorPicker

The formal route is Property caller → `BoneColorPicker.attachCaller()` → #040 Overlay → RETURN → same Property → Preview. The Consumer does not manipulate #040 internal DOM.

## 10. #022 Hover Border Effect

`hoverBorderEffect` stores enabled/effect/color/direction/speed/spinWidth/spinGlow and attaches the formal #022 Runtime. It is not replaced by custom `:hover` border rendering.

## 11. #117 Animation

#020 Runtime delegates element motion to #117 instead of implementing its own motion engine. `effect` Properties describe the relation and target.

## 12. #118 Transition

#020 does not directly own #118. #040 ColorPicker Overlay OPEN/CLOSE uses #118 as a transitive dependency.

## 13. Preview / OUT

Property changes are reflected into combined Preview. OUT is read through `BoneLabel.getOutput()` or instance `getOutput()`.

## 14. #002 Bone Joint

Connection Image evaluation uses `BoneJoint.evaluate(...)`, and lines use #002 Runtime rendering APIs. #020 does not create its own Joint lines or markers.

## 15. JavaScript Component Class

`BoneLabel.Component` is the advanced-operation interface for creation, parent attach, value updates, IN/OUT/State, detach/destroy, and #022/#117 state access. It is separate from HTML Functional Class `bf-label`.

## 16. Public API

- `BoneLabel.defaults()`
- `BoneLabel.normalizeValue()`
- `BoneLabel.validateValue()`
- `BoneLabel.buildInput()`
- `BoneLabel.buildOutput()`
- `BoneLabel.renderOutput()`
- `BoneLabel.create()`
- `BoneLabel.attachToParent()`
- `BoneLabel.playEffect()`
- `BoneLabel.distributeLabels()`
- `BoneLabel.getInput()`
- `BoneLabel.getOutput()`
- `BoneLabel.getState()`
- `BoneLabel.isInstance()`
- `BoneLabel.createInstance()`
- `BoneLabel.attachInstance()`
- `BoneLabel.getInstance()`
- `BoneLabel.getClassList()`
- `BoneLabel.getPropertySchema()`
- `BoneLabel.getPropertyDefaults()`
- `BoneLabel.getPropertyDefinition()`
- `BoneLabel.getCompletionState()`
- `BoneLabel.getAnimationState()`
- `BoneLabel.getAnimationOutput()`
- `BoneLabel.getAnimationDependency()`
- `BoneLabel.getHoverBorderEffectState()`
- `BoneLabel.refreshHoverBorderEffect()`
- `BoneLabel.complete()`
- `BoneLabel.reopen()`

Use `BoneLabelHTMLClass.getInstance(host)` to retrieve an instance created through HTML Functional Class.

## 17. Smoke Test / Validation

Smoke tests normal execution. Validation checks abnormal cases and the UI/Guide/Functional Class/Schema contracts separately. NOT RUN is never treated as PASS.

For HTML Functional Class, verify at minimum: one `bf-label` class, innerText mount, duplicate-mount prevention, Runtime 1.0.60, `getInstance()`, and scanning of DOM nodes added later.

## 18. Completion

Completion may be passed to the Runtime API only after both Smoke and Validation have run and are ALL PASS. Do not mark Completed / Specification Frozen before user localhost confirmation.

## 19. Troubleshooting

### `bf-label` shows nothing

1. Check `/boneflow/css/bone-label.css`.
2. Check that `/boneflow/js/bone-label.js` loads before the bridge.
3. Check `/boneflow/js/bone-label-html-class.js`.
4. Check that the HTML contains `class="bf-label"` and visible text.
5. In DevTools, check the host for `data-bf-label-mounted="true"`.

### Need to set detailed Properties in HTML

The formal #020 HTML Functional Class bridge does not expose detailed Property data attributes. Use Property Editor or `BoneLabelHTMLClass.getInstance(host).update(...)`.

### HTML Functional Class guide button does not jump to the section

`Open HTML Functional Class guide` is the entry that opens DOC-0020 directly at `3. HTML Functional Class bf-label`. The normal `Operation guide DOC-0020` opens from the start of the guide.

## 20. Dependency summary

#001 Core / #002 Joint / #022 Hover Border Effect / #040 ColorPicker / #117 Animation. #118 Transition is a transitive dependency through #040.