# Bone Flow #018 Icon ガイド

## このガイドについて

- DOC ID: `DOC-0018`
- UI ID: `UI-018`
- Component: `#018 Icon`
- Runtime Version: `1.0.21`
- DOC Version: `1.0.0`

このDOCは、#018 Iconを初めて使う人が「何を設定すると、実際に何が変わるのか」まで確認できる操作ガイド兼正式仕様です。画面Help、HTML Functional Classガイド、印刷説明書、PDF、Help検索から同じ `DOC-0018` を再利用します。

各Propertyは **説明 → 正式仕様 → 全許容値 → 使用サンプル → 使用結果** の順で説明します。コードブロックには「コピー」ボタンが表示され、そのまま利用できます。

実行時初期値（Runtime Default）と、#018テスト画面の設定欄（Property Editor）の初期値は同じとは限りません。異なる場合は両方を明記します。

### このガイドで使う用語

- **Runtime（実行本体）**: ブラウザ上でIconを生成・更新する `BoneIcon` 本体。
- **Runtime Default（実行時初期値）**: 何も指定しなかったときにRuntimeが使用する値。
- **Property（設定項目）**: Iconの表示、状態、OUT、表示領域を変更する設定。
- **Property Editor（画面の設定欄）**: `bone-icon.html` の「プロパティ設定」で変更できる設定欄。
- **Public API（JavaScript高度操作）**: HTMLだけでは表現できない設定をJavaScriptから操作する正式機能。
- **HTML Functional Class**: `class="bf-icon"` を付けてHTMLからIconを使い始める入口。
- **OUT**: Jointなど次の処理へ渡すIconの出力値。
- **表示領域**: Icon本体、Name、Unicodeを格納する `bone-icon-view` の領域。

英語のProperty名やError Codeは正式仕様名なので残しますが、必ず日本語で「何が変わるのか」を併記します。

## 最初に

#018 Iconの最小利用は、`bf-icon` とFont AwesomeのアイコンClassを同じ要素へ付けます。アイコン名を要素内の文字列で指定しません。

```html
<span class="bf-icon fa-solid fa-star" aria-label="お気に入り"></span>
```

使用結果: Font Awesome Solidの `star` を#018 RuntimeでIconとして生成します。`aria-label` は読み上げ用の名前として使用されます。

別のIconへ変える場合は `fa-star` を変更します。

```html
<span class="bf-icon fa-solid fa-play" aria-label="再生"></span>
```

使用結果: `play` アイコンを表示します。#018は `fontawesome-icons.json` の正式1,944件から `fa-play` を解決し、`name=play`、`unicode=f04b`、`className="fa-solid fa-play"` をRuntimeへ渡します。

## Iconとは

#018 IconはFont Awesome Free SolidのIconを表示し、Icon本体・アイコン名・Unicode・表示領域設定を管理するPrimitive UIです。

主な責務:

- Font Awesome Solid 1,944件の検索・選択・表示
- Iconのサイズ、色、回転、反転
- 10種類のAnimation
- 通常背景 / Active背景
- Icon / Name / Unicodeの表示ON/OFF
- Icon / Name / UnicodeのOUT ON/OFF
- Name / Unicodeの文字サイズ、色、Font、位置、Iconとの間隔
- 表示領域の幅、高さ、最小/最大、Padding、Border、形状、配置、Overflow、Opacity、Shadow
- Active / Disabled表示
- #040 ColorPickerから返されたSolid / Transparent / Gradient値の反映
- #002 Bone Jointの接続イメージ
- Smoke Test / Validation / Completion
- Public APIによる高度操作

## HTML Functional Class

### 正式Class

一般利用向けHTML Functional Classは **`bf-icon` 1件だけ**です。Public API 16件をHTML Classへ1対1変換しません。

```html
<span class="bf-icon fa-solid fa-star"></span>
```

### 対応HTML要素

- `span`
- `i`

それ以外の要素へ `bf-icon` を付けた場合は `BONE_ICON_HTML_CLASS_ELEMENT_UNSUPPORTED` です。

### Iconの指定方法

`bf-icon` と一緒に `fa-<name>` Classを付けます。

```html
<i class="bf-icon fa-solid fa-bell" aria-label="通知"></i>
```

`fa-bell` はFont Awesomeカタログから検索され、Unicodeと正式Classを自動解決します。要素内TextはIcon名として使用しません。

### HTMLから直接指定できるもの

HTML Functional Classは、既存HTML/CSSの意味が明確な指定だけをRuntimeへ渡します。独自の汎用イベント引数方式は使用しません。

- `fa-<name>` Class → `name / unicode / className` を1,944件カタログから解決
- `aria-label` → `title` の優先値
- `title` → `title`
- `aria-disabled="true"` → `disabled=true`
- `style="font-size:32px"` → `size=32`
- `style="color:#RRGGBB"` → `color`
- `style="background-color:#RRGGBB"` → `backgroundColor`
- `width / height / min-width / max-width / min-height / max-height` のpx値 → `containerStyle`
- `padding-top / right / bottom / left` のpx値 → `containerStyle`
- 対応する `border-width / border-style / border-color` → Border設定
- px指定の `border-radius` → `shape=custom / borderRadius`
- `justify-content:start|center|end` → `containerStyle.justify`
- `align-content:start|center|end` → `containerStyle.align`
- `overflow:visible|hidden|auto` → `containerStyle.overflow`
- `opacity` → 0〜1へ補正して `containerStyle.opacity`

HTMLから直接指定しないもの: `rotate`、`flip`、`animation`、`active`、表示/OUT選択、Name/Unicode書式、Gradient、Shadow詳細、Active Style詳細、Disabled Style詳細、Completion。これらはPublic APIを使用します。

### HTML使用サンプル: サイズと色

```html
<span class="bf-icon fa-solid fa-heart"
      aria-label="お気に入り"
      style="font-size:40px; color:#FF5A7A;"></span>
```

使用結果: `heart` を40px、`#FF5A7A`で表示します。

### HTML使用サンプル: 背景・枠・表示領域

```html
<span class="bf-icon fa-solid fa-check"
      aria-label="完了"
      style="font-size:28px;
             color:#FFFFFF;
             background-color:#1F7A4D;
             width:72px;
             height:72px;
             padding:10px;
             border:2px solid #55E6A5;
             border-radius:12px;
             overflow:hidden;"></span>
```

使用結果: 72×72pxの表示領域にPadding、Border、背景を設定した `check` Iconになります。

## 使用サンプル

ここは値一覧ではなく、実際に使う場面をそのままコピーするためのサンプルです。

### 1. 通知Icon

```html
<span class="bf-icon fa-solid fa-bell" aria-label="通知"></span>
```

使用結果: 通知を表すBell IconをRuntime Defaultで表示します。

### 2. 大きい警告Icon

```html
<span class="bf-icon fa-solid fa-triangle-exclamation"
      aria-label="警告"
      style="font-size:64px; color:#FFB454;"></span>
```

使用結果: 64pxの警告Iconになります。

### 3. 無効状態をHTMLから表示

```html
<span class="bf-icon fa-solid fa-lock"
      aria-label="利用不可"
      aria-disabled="true"></span>
```

使用結果: `disabled=true` として生成され、Runtime DefaultのDisabled opacity `0.45` が適用されます。

### 4. 90度回転 + spin Animation

HTML Functional Classは高度設定を無理に独自属性へ割り当てません。Public APIで指定します。

```html
<div id="icon-host"></div>
<script>
BoneIcon.render(document.getElementById("icon-host"), {
  name: "spinner",
  unicode: "f110",
  className: "fa-solid fa-spinner",
  size: 40,
  color: "#55E6A5",
  rotate: 90,
  animation: "spin"
});
</script>
```

使用結果: Spinnerを90度回転した状態で連続回転Animation表示します。

### 5. Icon名とUnicodeも同時表示

```html
<div id="icon-detail"></div>
<script>
BoneIcon.render(document.getElementById("icon-detail"), {
  name: "star",
  unicode: "f005",
  className: "fa-solid fa-star",
  visible: { icon: true, name: true, unicode: true },
  nameStyle: { position: "bottom", fontSize: 16, gap: 8 },
  unicodeStyle: { position: "right", fontSize: 14, gap: 8 }
});
</script>
```

使用結果: Iconの下に `star`、右側に `f005` を表示します。

### 6. 表示とOUTを分離

```html
<div id="icon-output"></div>
<script>
const icon = BoneIcon.render(document.getElementById("icon-output"), {
  name: "play",
  unicode: "f04b",
  className: "fa-solid fa-play",
  visible: { icon: true, name: false, unicode: false },
  output: { icon: true, name: true, unicode: true }
});
console.log(BoneIcon.getOutput(icon));
</script>
```

使用結果: 画面にはIconだけを表示し、OUTにはIcon Class・Icon名・Unicodeをすべて保持します。

### 7. 円形Container

```html
<div id="status-icon"></div>
<script>
BoneIcon.render(document.getElementById("status-icon"), {
  name: "check",
  unicode: "f00c",
  className: "fa-solid fa-check",
  color: "#FFFFFF",
  backgroundColor: "#1F7A4D",
  containerStyle: {
    width: 72,
    height: 72,
    shape: "circle",
    paddingTop: 10,
    paddingRight: 10,
    paddingBottom: 10,
    paddingLeft: 10
  }
});
</script>
```

使用結果: 72×72pxの円形背景内へCheck Iconを表示します。

### 8. Gradient Icon

```html
<div id="gradient-icon"></div>
<script>
BoneIcon.render(document.getElementById("gradient-icon"), {
  name: "star",
  unicode: "f005",
  className: "fa-solid fa-star",
  size: 56,
  color: {
    kind: "gradient",
    type: "linear",
    angle: 90,
    stops: [
      { position: 0, color: "#55E6A5" },
      { position: 100, color: "#5BA6FF" }
    ]
  }
});
</script>
```

使用結果: Icon文字へ90°の2-stop Linear Gradientを適用します。


## Runtime Property Schema / #048 Table

#018 Icon v1.0.21 は、#054 Display Timeline のRuntime-owned Property Schema方式を参考に、正式API **`BoneIcon.getPropertySchema()`** を公開します。目的は #048 Table などのConsumerが #018 のProperty Editorを構成するとき、#018のProperty定義をRuntimeから直接取得できるようにすることです。

重要な契約:

- Property定義の所有者は #018 Runtimeです。#048 Table側へ#018 Property一覧を複製しません。
- `getPropertySchema()` はProperty定義の配列を返します。各要素は最低限 `key / label / labelJa / type / group / default / defaultValue / path` を持ち、選択型では `options`、数値型では必要に応じて `min / max / step` を持ちます。
- `default / defaultValue` は `BoneIcon.normalize({})` の結果から毎回取得するため、GuideやConsumer側の別Defaultを正本にしません。
- Nested Propertyは `visible.icon`、`nameStyle.fontSize`、`containerStyle.width` のようなdot pathを `key` として持ち、同時に `path` 配列も公開します。
- Schema追加によって既存 `normalize / create / render / update` のProperty契約を変更しません。
- #048 Table本体と #054 Display Timeline本体はこの修正では変更しません。

Consumer側は `BoneIcon.getPropertySchema()` を `propertySchema` providerとして使用します。#048の正式方針どおり、UI番号が増えたという理由でTable本体へProperty分岐を追加しません。

```javascript
const iconPropertySchema = BoneIcon.getPropertySchema();
// #048 Cell Renderer登録時は、このRuntime-owned SchemaをpropertySchemaとして使用する。
```

## Runtime Default / Property Editor

### Runtime Default 全件

`BoneIcon.normalize()` が何も指定されなかったPropertyへ適用する正式Defaultです。

| Property | Runtime Default | 型 / Runtime許容 |
|---|---|---|
| `name` | `star` | 空でないstring |
| `unicode` | `f005` | 3〜6桁hex |
| `className` | `fa-solid fa-star` | string |
| `size` | `56` | number、1以上 |
| `color` | `#55E6A5` | Color Value |
| `rotate` | `0` | Number化した値。Runtimeに角度範囲検査なし |
| `flip` | `none` | 4値 |
| `title` | 空文字 | string |
| `animation` | `none` | 10値 |
| `backgroundColor` | `null` | Color Value / null |
| `activeBackgroundColor` | `null` | Color Value / null |
| `active` | `false` | Boolean化 |
| `disabled` | `false` | Boolean化 |
| `visible.icon` | `true` | truthy/falsy |
| `visible.name` | `false` | truthy/falsy |
| `visible.unicode` | `false` | truthy/falsy |
| `output.icon` | `true` | truthy/falsy |
| `output.name` | `true` | truthy/falsy |
| `output.unicode` | `true` | truthy/falsy |
| `nameStyle.fontSize` | `16` | number、1以上 |
| `nameStyle.color` | `#DCE8F8` | Color Value |
| `nameStyle.fontFamily` | `inherit` | string |
| `nameStyle.position` | `bottom` | top/bottom/left/right |
| `nameStyle.gap` | `8` | number、0以上 |
| `unicodeStyle.fontSize` | `14` | number、1以上 |
| `unicodeStyle.color` | `#9FC5F8` | Color Value |
| `unicodeStyle.fontFamily` | `monospace` | string |
| `unicodeStyle.position` | `right` | top/bottom/left/right |
| `unicodeStyle.gap` | `8` | number、0以上 |
| `containerStyle.width` | `null` | null / auto / number 0以上 |
| `containerStyle.height` | `null` | null / auto / number 0以上 |
| `containerStyle.minWidth` | `null` | null / auto / number 0以上 |
| `containerStyle.maxWidth` | `null` | null / auto / number 0以上 |
| `containerStyle.minHeight` | `null` | null / auto / number 0以上 |
| `containerStyle.maxHeight` | `null` | null / auto / number 0以上 |
| `containerStyle.paddingTop` | `10` | number、0以上 |
| `containerStyle.paddingRight` | `10` | number、0以上 |
| `containerStyle.paddingBottom` | `10` | number、0以上 |
| `containerStyle.paddingLeft` | `10` | number、0以上 |
| `containerStyle.borderEnabled` | `false` | Boolean化 |
| `containerStyle.borderColor` | `#425A78` | Color Value |
| `containerStyle.borderWidth` | `1` | number、0以上 |
| `containerStyle.borderStyle` | `solid` | 4値 |
| `containerStyle.shape` | `rounded` | 6値 |
| `containerStyle.borderRadius` | `8` | number、0以上 |
| `containerStyle.justify` | `center` | Runtimeはstringを列挙検査しない |
| `containerStyle.align` | `center` | Runtimeはstringを列挙検査しない |
| `containerStyle.overflow` | `visible` | 3値 |
| `containerStyle.opacity` | `1` | 数値化後0〜1へclamp。不正数値は1 |
| `containerStyle.shadowEnabled` | `false` | Boolean化 |
| `containerStyle.shadowInset` | `false` | Boolean化 |
| `containerStyle.shadowX` | `0` | number、-999以上 |
| `containerStyle.shadowY` | `4` | number、-999以上 |
| `containerStyle.shadowBlur` | `12` | number、0以上 |
| `containerStyle.shadowSpread` | `0` | number、-999以上 |
| `containerStyle.shadowColor` | `#00000066` | #RRGGBB / #RRGGBBAA / transparent、Gradient不可 |
| `containerStyle.output` | `true` | Boolean化 |
| `activeStyle.borderColor` | `null` | Color Value / null |
| `activeStyle.borderWidth` | `null` | Runtime normalizeで範囲検査なし |
| `activeStyle.shadowColor` | `null` | 現行Runtimeでは描画へ未使用 |
| `disabledStyle.opacity` | `0.45` | 現行Runtimeでは範囲正規化なし |
| `disabledStyle.backgroundColor` | `null` | Color Value / null |
| `disabledStyle.borderColor` | `null` | Color Value / null |

### Property Editor 初期値

現在の `bone-icon.html` 画面設定欄は、Runtime Defaultと異なる実表示用初期値を含みます。

- Icon: `star / f005 / fa-solid fa-star`
- Size: `56`、Editor範囲 `8〜256`
- Icon Color: `#55E6A5`
- Rotate: `0`、Editor範囲 `0〜359`
- Flip: `none`
- Animation: `none`
- Background: OFF。色保持値 `#172943`
- Active Background: OFF。色保持値 `#245A91`
- Preview Active: 通常（false）
- Container Width / Height: `220 / 150`。Runtime Defaultはauto/null
- Min Width / Min Height: `0 / 0`。Runtime Defaultはnull
- Max Width / Max Height: 空欄（制限なし）
- Border: OFF / solid / 1px / `#425A78`
- Shape: `rounded` / Radius `8`
- Padding: 上右下左すべて `10`
- justify / align: `center / center`
- overflow: `visible`
- opacity: `1`
- Shadow: OFF、Inset OFF、X `0`、Y `4`、Blur `12`、Spread `0`、Color UI保持 `#000000`。Runtimeへはalpha `66`を付けて渡す
- Active Border: `#5BA6FF / 2px`
- Disabled Preview: OFF、Opacity `0.45`、Background `#222B38`、Border `#687386`
- Container Style OUT: ON
- Display Mode: `icon-only`
- Preview visible: Icon ON / Name OFF / Unicode OFF
- OUT: Icon ON / Name ON / Unicode ON
- Name Style: `16px / #DCE8F8 / inherit / bottom / gap 8`
- Unicode Style: `14px / #9FC5F8 / monospace / right / gap 8`


## 正式Property定義（Runtime Schema）

#018のProperty正本はテストHTML側の固定一覧ではなく、**BoneIcon Runtime自身**です。#054 Display Timelineの方式を参考に、次の3 APIを正式公開します。

- `BoneIcon.getPropertySchema()` — 63 Propertyの正式定義を返す。
- `BoneIcon.getPropertyDefaults()` — Runtime正規化後の既定値一式を返す。
- `BoneIcon.getPropertyDefinition(key)` — 指定したProperty 1件の正式定義を返す。不存在は `null`。

`bone-icon.html` の **「正式Property定義（Runtime Schema）」** 表は `getPropertySchema()` の戻り値から実行時に生成します。画面側へProperty名・既定値・許容値・意味の別一覧を複製しません。

#048 TableなどのConsumerは、#018をCell Rendererとして登録するときにこのRuntime-owned SchemaをProperty生成元として利用します。#048側へ#018の63 Propertyをハードコードして別管理してはいけません。

各定義には最低限 `key / label / labelJa / type / default / defaultValue / description / descriptionJa` を持たせ、必要に応じて `options / min / max / step / pattern / nullable / format / required` を公開します。

## HTML Functional Classを使うときの基準

#017 Textと同じく、通常利用の入口は **1つの正式Class** です。#018では `bf-icon` だけを通常利用入口とします。

```html
<span class="bf-icon fa-solid fa-star" aria-label="お気に入り"></span>
```

`bf-icon` はPublic APIをClass名へ1対1展開する仕組みではありません。HTMLで自然に表せるClass・属性・inline CSSだけを読み、`BoneIconHTMLClass` から `BoneIcon 1.0.21` Runtimeへ渡します。高度な状態・OUT・Animation・Gradient・Shadow詳細などへ、仕様にない `data-*` 属性を勝手に追加しません。

## Icon識別 Property

### name

Iconの論理名です。Runtime Defaultは `star`。空文字は `BONE_ICON_NAME_REQUIRED`。

HTML Functional Classでは `fa-star` の `star` 部分を正式カタログから解決します。

### unicode

Font Awesome GlyphのUnicode hexです。3〜6桁の16進文字列。Runtime Default `f005`。不正値は `BONE_ICON_UNICODE_INVALID`。

### className

Font Awesomeの描画Class文字列です。Runtime Default `fa-solid fa-star`。Runtime自体は文字列の内容検証をしていませんが、`name / unicode / className` は同じIconを表す組合せで使用します。

## size / rotate

### size

Icon GlyphのFont Sizeをpxで設定します。

- Runtime Default: `56`
- Runtime: 1以上
- Property Editor: 8〜256、初期56
- HTML Functional Class: inline `font-size:...px` を読取可能
- Invalid: `BONE_ICON_SIZE_INVALID`

### rotate

Icon GlyphへCSS `rotate(<value>deg)` を適用します。

- Runtime Default: `0`
- Property Editor: 0〜359
- Runtime: `Number(value) || 0`。Editorと異なり0〜359へ制限していない
- HTML Functional Class: 直接指定不可。Public API使用

## flip 全4値

`flip` はIcon Glyphを上下・左右に反転します。Runtime Default `none`。

- `none`: 反転なし
- `horizontal`: 左右反転。`scaleX(-1)`
- `vertical`: 上下反転。`scaleY(-1)`
- `both`: 左右と上下の両方を反転

不正値は `BONE_ICON_FLIP_INVALID`。

使用サンプル:

```html
<div id="flip-icon"></div>
<script>
BoneIcon.render(document.getElementById("flip-icon"), {
  name: "arrow-right",
  unicode: "f061",
  className: "fa-solid fa-arrow-right",
  flip: "horizontal"
});
</script>
```

使用結果: 右矢印Glyphを左右反転して見た目は左方向になります。

## animation 全10値

`animation` はIcon Glyphの時間変化を設定します。Runtime Default `none`。

- `none`: Animationなし
- `beat`: 拡大・縮小を繰り返す
- `beat-fade`: 拡大・縮小とOpacity変化を組み合わせる
- `bounce`: 上下に跳ねる動き
- `fade`: Opacityを周期的に変化
- `flip`: 3D方向へ反転する動き
- `shake`: 左右へ小刻みに振動
- `spin`: 一定速度で連続回転
- `spin-pulse`: 段階的な回転
- `spin-reverse`: 逆方向へ連続回転

不正値は `BONE_ICON_ANIMATION_INVALID`。

Animationは#018 Runtime/CSSの責務です。#118 Transitionの状態遷移補間とは別の設定です。

## color / Background / #040 ColorPicker

### Color Value正式仕様

#018の色Propertyは文字列または2-stop Linear Gradientを使用します。

**Solid**

- `#RRGGBB`

**Transparent**

- `transparent`

**Gradient V1**

```javascript
{
  kind: "gradient",
  type: "linear",
  angle: 90,
  stops: [
    { position: 0, color: "#55E6A5" },
    { position: 100, color: "#5BA6FF" }
  ]
}
```

Gradientの正式条件:

- `kind`: `gradient`
- `type`: `linear`
- `angle`: 0以上360未満
- `stops`: 正確に2件
- 各`position`: 0〜100
- 1件目のposition < 2件目のposition
- 各`color`: `#RRGGBB`

不正Colorは `BONE_ICON_COLOR_INVALID`、不正Gradient構造は `BONE_ICON_GRADIENT_INVALID`。

### #040 ColorPicker連携

#018テスト画面では #040 ColorPicker v1.0.18 の `attachCaller()` を使用します。#018側はColorPicker内部DOM/CSSを複製しません。

ColorPicker対象10色:

1. Icon Color
2. Background Color
3. Active Background Color
4. Container Border Color
5. Container Shadow Color
6. Active Border Color
7. Disabled Background Color
8. Disabled Border Color
9. Name Color
10. Unicode Color

Shadow Colorだけは既存 `shadowColor + alpha` 契約を維持するため、Solid / TransparentのみでGradient不可です。

## Background / Active / Disabled

### backgroundColor

通常状態の表示領域背景。Default `null`（無色）。Solid / Transparent / Gradient。

### activeBackgroundColor

`active=true` のとき使用する背景。Default `null`。値がnullなら通常 `backgroundColor` を使用します。

### active

Default `false`。trueで `is-active` Classが付き、Active背景・Active Borderを適用します。

### disabled

Default `false`。trueで `is-disabled` Classが付き、Disabled Styleを優先して適用します。

### disabledStyle

- `opacity`: Default `0.45`
- `backgroundColor`: Default `null`
- `borderColor`: Default `null`

`disabledStyle.backgroundColor / borderColor` が指定されている場合にDisabled時へ反映します。

## 表示（visible）/ OUT（output）

表示とOUTは独立です。「画面に表示しないがOUTへ渡す」が可能です。

### visible

- `visible.icon`: Default `true`
- `visible.name`: Default `false`
- `visible.unicode`: Default `false`

### output

- `output.icon`: Default `true` → OUT key `icon`
- `output.name`: Default `true` → OUT key `iconName`
- `output.unicode`: Default `true` → OUT key `unicode`

`containerStyle.output=true` の場合は `containerStyle` もOUTへ追加します。

### Property EditorのDisplay Mode 全5値

これはRuntime Propertyではなく、画面上で3つのvisible checkboxをまとめて操作する補助UIです。

- `icon-only`: Iconだけ表示
- `icon-name`: Icon + Name
- `icon-unicode`: Icon + Unicode
- `icon-name-unicode`: Icon + Name + Unicode
- `custom`: checkboxの組合せが上記4件に一致しない状態

## Name / Unicode表示位置 全4値

`nameStyle.position` と `unicodeStyle.position` は同じ4値です。

- `top`: Iconの上側slotへ表示。gapはLabelの下Margin
- `bottom`: Iconの下側slotへ表示。gapはLabelの上Margin
- `left`: Iconの左側slotへ表示。gapはLabelの右Margin
- `right`: Iconの右側slotへ表示。gapはLabelの左Margin

不正値は `BONE_ICON_POSITION_INVALID`。

## Name Style

### nameStyle.fontSize

Default `16`。Runtime 1以上。Editor 8〜128。

### nameStyle.color

Default `#DCE8F8`。Solid / Transparent / Gradient。

### nameStyle.fontFamily

Runtime Default `inherit`。Runtimeは任意string。Property Editor選択肢は全6件:

- `inherit`: 親Fontを継承
- `Meiryo, sans-serif`: Meiryo優先
- `'Yu Gothic', sans-serif`: 游ゴシック優先
- `sans-serif`: Sans Serif系
- `serif`: Serif系
- `monospace`: 等幅Font

### nameStyle.position

Default `bottom`。4値は「Name / Unicode表示位置 全4値」を参照。

### nameStyle.gap

Default `8` px。Runtime 0以上。Editor 0〜100。

## Unicode Style

### unicodeStyle.fontSize

Default `14`。Runtime 1以上。Editor 8〜128。

### unicodeStyle.color

Default `#9FC5F8`。Solid / Transparent / Gradient。

### unicodeStyle.fontFamily

Runtime Default `monospace`。Property Editor選択肢はNameと同じ6件。

### unicodeStyle.position

Default `right`。4値。

### unicodeStyle.gap

Default `8` px。Runtime 0以上。Editor 0〜100。

## Container Size

`width / height / minWidth / maxWidth / minHeight / maxHeight` は表示領域サイズです。

- `null` / 空文字 / `auto`: CSSサイズ指定を外す
- 数値: pxとして使用
- Runtime数値範囲: 0以上
- Invalid: `BONE_ICON_CONTAINER_SIZE_INVALID`

Runtime Defaultは6項目すべて `null`。Property Editorはwidth `220`、height `150`、minWidth `0`、minHeight `0`、maxWidth/maxHeight空欄です。

## Padding

4方向を個別にpx指定します。

- `paddingTop`: Default 10
- `paddingRight`: Default 10
- `paddingBottom`: Default 10
- `paddingLeft`: Default 10

Runtimeは0以上。不正値は `BONE_ICON_PADDING_INVALID` コードではなく、現行実装では共通 `BONE_ICON_PADDING_INVALID` をnumber()へ渡しています。

## Border Style 全4値

- `solid`: 実線
- `dotted`: 点線
- `dashed`: 破線
- `double`: 二重線

Runtime Default `solid`。不正値 `BONE_ICON_BORDER_STYLE_INVALID`。

関連Property:

- `borderEnabled`: Default false
- `borderColor`: Default `#425A78`
- `borderWidth`: Default 1、Runtime 0以上、Editor 0〜20

`borderEnabled=false` のときBorder Color/Width/Styleを設定していても描画Borderは `none` です。

## Shape 全6値

`shape` は表示領域の角丸計算を決めます。

- `square`: Radius 0。四角
- `rounded`: `borderRadius` をpxで使用。Default
- `circle`: Radius 50%
- `ellipse`: Radius 50%。width/heightが異なる場合は楕円
- `capsule`: Radius 9999px。長方形をカプセル状にする
- `custom`: `borderRadius` をpxで使用

不正値 `BONE_ICON_SHAPE_INVALID`。

`borderRadius` Runtime Default 8、0以上。Editor 0〜999。

## justify 全3値 / align 全3値

### Property Editorの正式選択肢

`justify`（横配置）:

- `start`: 左
- `center`: 中央
- `end`: 右

`align`（縦配置）:

- `start`: 上
- `center`: 中央
- `end`: 下

両方のEditor Defaultは `center`。

### Runtimeとの差

現行v1.0.21 Runtimeは `justify / align` を列挙値として検証せず、その文字列をCSS `justifyContent / alignContent` へ設定します。したがって正式画面では上記3値を使用し、Public APIから任意文字列を渡した場合はブラウザCSS側の解釈結果になります。RuntimeがEditor 3値と同じValidationを行うとは扱いません。

## overflow 全3値

- `visible`: はみ出した内容を表示。Default
- `hidden`: 表示領域外を切る
- `auto`: 必要に応じてスクロール領域化

不正値 `BONE_ICON_OVERFLOW_INVALID`。

## opacity

`containerStyle.opacity` は表示領域全体のOpacityです。

- Default: 1
- Runtime: Number化し0〜1へclamp
- 数値化できない場合: 1
- Property Editor: 0〜1、step 0.05

Disabled時は `disabledStyle.opacity` が上書きします。

## Shadow

### shadowEnabled

Default false。falseならShadow関連値が存在しても `box-shadow:none`。

### shadowInset

Default false。trueなら `inset` Shadow。

### shadowX / shadowY / shadowBlur / shadowSpread

- X Default 0、Runtime -999以上
- Y Default 4、Runtime -999以上
- Blur Default 12、Runtime 0以上
- Spread Default 0、Runtime -999以上

### shadowColor

Default `#00000066`。許容は `#RRGGBB`、`#RRGGBBAA`、`transparent`。Gradient不可。

#018 Property Editorは#040から受けたSolid色 `#RRGGBB` に既存alpha `66` を加えてRuntimeへ渡します。

## Active Style

### activeStyle.borderColor

Default null。ActiveかつBorder Enabledのとき、通常Border Colorを上書きします。Solid / Transparent / Gradient / null。

### activeStyle.borderWidth

Default null。ActiveかつBorder Enabled時にBorder Widthを上書き。Property Editor初期値2、min 0。現行Runtime normalizeはこのPropertyの数値範囲を検証していません。

### activeStyle.shadowColor

Default null。Objectには存在しますが、現行v1.0.21の `applyContainer()` はこの値をShadow描画へ使用していません。画面設定欄にも入力欄はありません。存在するPropertyを「Active Shadowが描画される」と誤説明しません。

## Container OUT

`containerStyle.output` Default true。

trueの場合、`BoneIcon.getOutput()` は `containerStyle` を返します。返却値には通常Container設定に加え、背景、Active背景、Active/Disabled Styleも含まれます。

falseの場合、Container設定は画面へ反映されてもOUTの `containerStyle` keyは生成されません。

## 操作方法 / Keyboard

### Property Editor

1. Icon一覧または検索からIconを選択。
2. 基本設定、表示領域、表示/OUT、Name/Unicode設定を変更。
3. 右側「合算プレビュー」で全設定を確認。
4. 色は各Color Triggerから#040 ColorPickerを開く。
5. Smoke Test / Validationを実行。
6. 両方ALL PASSの場合のみCompletion操作が有効になります。

### Keyboard

- 通常の `Tab / Shift+Tab`: 入力、select、Color Trigger、Icon Card、テストボタンへ移動
- `Enter / Space`: Button・Icon Card・Color Triggerの実行
- ColorPickerのKeyboard操作は#040責務
- DOC Guide: Escapeで閉じる

#018 RuntimeのIcon表示自体はButtonではありません。クリック動作を必要とする場合は親Buttonなど適切な操作Componentを使用します。

## Joint / 接続イメージ

Jointは#002 Bone Joint責務です。#018は見た目だけの独自線を作りません。

接続イメージでは:

- IN 接続線: 青
- OUT 接続線: 緑
- 型不一致: オレンジ
- 接続エラー / Target不存在: 赤

IconのOUT候補:

- `icon`: Font Awesome Class
- `iconName`: Icon名
- `unicode`: Unicode hex
- `containerStyle`: output=trueの場合

実際のEndpoint互換性、Target不存在、型不一致は#002の評価結果に従います。

## Smoke / Validation

#018テスト画面には正式Smoke TestとValidationがあります。

SmokeではRuntime、ColorPicker Caller、Font Awesome全1,944件、表示/OUT、Container、Jointなどの正常系を確認します。

Validationでは少なくとも次のErrorを実動作で検査します。

- 空Icon名
- 不正Unicode
- 不正Size
- 不正Flip
- 不正Animation
- 不正Gradient
- Shadow Gradient拒否
- 不正Border Style
- 不正Shape
- 不正Overflow
- 不正Position
- Instance以外へのAPI操作

テスト期待値を書き換えてPASSにしません。

## Completion

CompletionはSmoke TestとValidationの双方ALL PASSが前提です。

`BoneIcon.complete(validation)` は、次がすべてtrueでなければ `BONE_ICON_COMPLETION_VALIDATION_REQUIRED` です。

- `allPass`
- `smokePassed`
- `validationPassed`

Completion後:

- `completionFlag=true`
- `status=Release Ready`
- `validationStatus=ALL PASS`
- `completedAt` 記録

`BoneIcon.reopen()` でDevelopmentへ戻します。

ユーザーlocalhost確認前にDOC統合作業をCompleted / Specification Frozenと断定しません。

## JavaScript高度操作（Public API）

HTML Functional Class `bf-icon` とPublic APIは別です。Public APIは16件です。

### normalize(options)

設定Objectを正式な#018契約へ正規化します。DOMは生成しません。

### getPropertySchema()

#048 Table等のConsumer向けに、#018 Runtime自身が所有する正式Property定義を返します。63 Propertyを `key / type / defaultValue / path` 等のSchema metadataとして取得できます。返却配列は呼出しごとに新しく生成され、Consumer側の変更をRuntime正本へ持ち込みません。

### create(options)

新しい `bone-icon-view` Elementを生成します。Documentがない場合 `BONE_ICON_DOCUMENT_UNAVAILABLE`。

### getCompletionState()

localStorageのCompletion状態を取得します。

### complete(validation)

Smoke/Validation結果を確認してCompletionを確定します。

### reopen()

Completionを解除します。

### render(target, options)

`target` Elementへ新しいIconをappendします。Elementでない場合 `BONE_ICON_TARGET_INVALID`。

### update(el, options)

既存#018 Instanceの設定を合成し、新しいElementで置換します。戻り値は置換後の新Instanceです。

### getOptions(el)

現在の正規化済み設定をCloneして返します。

### getOutput(el)

現在の `output` と `containerStyle.output` に従ったOUT Objectを返します。

### setActive(el, active)

`active` をBoolean化してupdateします。updateによりElementが置換されるため、戻り値の新Instanceを保持してください。

```html
<div id="active-host"></div>
<script>
let icon = BoneIcon.render(document.getElementById("active-host"), {
  name: "star",
  unicode: "f005",
  className: "fa-solid fa-star"
});
icon = BoneIcon.setActive(icon, true);
</script>
```

### setDisabled(el, disabled)

Disabled状態を更新し、新Instanceを返します。

### isInstance(el)

Elementが現在のBoneIcon InstanceかBooleanで返します。

### destroy(el)

Instanceを管理対象から外してDOMから削除します。Instance以外は `BONE_ICON_INSTANCE_INVALID`。

## 発生イベント（HTML Functional Class）

### bone-icon-html-class-mounted

`bf-icon` が正式#018 Runtime Instanceへ変換された後に生成Elementから発火します。detailにcomponentId、className、iconName、elementを含みます。

### bone-icon-html-class-error

HTML Functional Classの解決・変換に失敗した場合に元要素から発火します。detailにcode/messageを含みます。

## Error / Troubleshooting

### Runtime Error Code

- `BONE_ICON_NAME_REQUIRED`: nameが空
- `BONE_ICON_UNICODE_INVALID`: Unicodeが3〜6桁hexではない
- `BONE_ICON_SIZE_INVALID`: sizeが1未満または数値でない
- `BONE_ICON_FLIP_INVALID`: flipが4値外
- `BONE_ICON_ANIMATION_INVALID`: animationが10値外
- `BONE_ICON_COLOR_INVALID`: Color Value不正
- `BONE_ICON_GRADIENT_INVALID`: Gradient構造不正
- `BONE_ICON_CONTAINER_SIZE_INVALID`: Container Size不正
- `BONE_ICON_FONT_SIZE_INVALID`: Name/Unicode Font Size不正
- `BONE_ICON_GAP_INVALID`: Name/Unicode Gap不正
- `BONE_ICON_PADDING_INVALID`: Padding不正
- `BONE_ICON_BORDER_WIDTH_INVALID`: Border Width不正
- `BONE_ICON_BORDER_STYLE_INVALID`: Border Style不正
- `BONE_ICON_SHAPE_INVALID`: Shape不正
- `BONE_ICON_RADIUS_INVALID`: Border Radius不正
- `BONE_ICON_OVERFLOW_INVALID`: Overflow不正
- `BONE_ICON_SHADOW_INVALID`: Shadow X/Y/Blur/Spread不正
- `BONE_ICON_POSITION_INVALID`: Name/Unicode Position不正
- `BONE_ICON_DOCUMENT_UNAVAILABLE`: create時Documentなし
- `BONE_ICON_TARGET_INVALID`: renderのtarget不正
- `BONE_ICON_INSTANCE_INVALID`: Instance必須APIへ別Elementを渡した
- `BONE_ICON_COMPLETION_VALIDATION_REQUIRED`: ALL PASS情報なしでCompletionしようとした

### HTML Functional Class Error Code

- `BONE_ICON_HTML_CLASS_RUNTIME_UNAVAILABLE`: `BoneIcon` が未読込
- `BONE_ICON_HTML_CLASS_ELEMENT_UNSUPPORTED`: span/i以外
- `BONE_ICON_HTML_CLASS_NAME_REQUIRED`: `fa-<name>` Classなし
- `BONE_ICON_HTML_CLASS_ICON_NOT_FOUND`: 1,944件に存在しないIcon Class
- `BONE_ICON_HTML_CLASS_FETCH_UNAVAILABLE`: Catalog読込に必要なfetchなし
- `BONE_ICON_HTML_CLASS_CATALOG_LOAD_FAILED`: `fontawesome-icons.json` 読込失敗
- `BONE_ICON_HTML_CLASS_CATALOG_EMPTY`: Catalogが空

### Iconが出ない

1. `bone-icon.js` と `bone-icon-html-class.js` が読み込まれているか。
2. `bone-icon.css` とFont Awesome webfontが読み込まれているか。
3. `bf-icon` と `fa-solid` と `fa-<name>` が同じspan/iにあるか。
4. `fa-<name>` が#018正式1,944件に存在するか。
5. DevTools ConsoleのHTML Class Error Codeを確認。

### 色が反映されない

Runtimeへ渡した色が `#RRGGBB / transparent / 正式Gradient` か確認します。ShadowはGradient不可です。

### Active Borderが見えない

`containerStyle.borderEnabled=true` が必要です。Active Borderだけ設定して通常BorderをOFFにしている場合、現行RuntimeはBorderを描画しません。

### maxWidth等が効かない

min/maxとwidth/heightを同時指定している場合はCSS sizing規則も関係します。Runtimeは数値をpxへ変換してstyleへ設定します。

## Dependencies / DOC再利用

現在の#018画面が検証する依存:

- #001 Bone Core v1.0.0
- #002 Bone Joint v1.1.36
- #020 Bone Label v1.0.61（#040経由）
- #022 Hover Border Effect v1.0.10（#040経由）
- #040 ColorPicker v1.0.18

#017 Textは画面構成・接続イメージの参照実装で、#018 Runtime依存ではありません。

DOC経路:

`UI-018 → DOC-0018 → doc-registry.json → content/DOC-0018/ja.md|en.md → BoneDocLoader → BoneDocGuide`

同じDOC資産をUI Help、HTML Functional Class Guide、印刷説明書、PDF、Help検索から再利用します。


## v1.0.21 追加契約
`BoneIcon.getPropertyDefaults()` はRuntime正規化後のDefault一式を返します。`BoneIcon.getPropertyDefinition(key)` は指定Propertyの正式Schema 1件を返し、存在しないkeyはnullです。#048 TableなどのConsumerは#018 Runtimeを正本として参照します。