# Bone Flow #018 Icon Guide

## About this guide

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

This document is the usage guide and formal specification for #018 Icon. Each property is explained as purpose → formal contract → complete selectable values → copyable usage sample → expected result. Runtime defaults and the current Property Editor values are kept separate.

### Terms

- **Runtime**: the `BoneIcon` object that creates and updates icons.
- **Runtime Default**: the value used when an option is omitted.
- **Property Editor**: the controls on `bone-icon.html`.
- **HTML Functional Class**: the normal HTML entry point, `bf-icon`.
- **Public API**: the separate JavaScript API for advanced control.
- **OUT**: values delivered to the next consumer/Joint.

## Start here

Use one general-purpose class, plus the Font Awesome Solid icon class. Icon identity is not read from element text.

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

Result: `fa-star` is resolved through the formal 1,944-item catalog and rendered by #018.

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

Result: `play / f04b / fa-solid fa-play` is resolved and passed to the runtime.

## What Icon does

#018 manages the Font Awesome glyph, name, Unicode, display/output selection, text labels, container styling, active/disabled state, ColorPicker values, Joint image, Smoke/Validation and Completion.

## HTML Functional Class

### Formal class

The only general-use HTML Functional Class is **`bf-icon`**. The 14 Public API methods are not converted into 13 HTML classes.

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

### Supported elements

- `span`
- `i`

Other elements raise `BONE_ICON_HTML_CLASS_ELEMENT_UNSUPPORTED`.

### Direct HTML mapping

The bridge reads only well-defined HTML/CSS values:

- `fa-<name>` → resolves `name / unicode / className`
- `aria-label`, `title`
- `aria-disabled="true"`
- inline `font-size`, `color`, `background-color`
- px width/height/min/max sizes and padding
- supported border width/style/color and px border radius
- `justify-content:start|center|end`
- `align-content:start|center|end`
- `overflow:visible|hidden|auto`
- `opacity`

Advanced options such as rotate, flip, animation, visible/output maps, label styles, gradients, shadows, active details, disabled details and Completion use the Public API.

### Size and color sample

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

Result: a 40px heart in `#FF5A7A`.

## Usage samples

### Notification

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

Result: renders the Bell icon with Runtime Defaults.

### Large warning icon

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

Result: renders a 64px warning icon in `#FFB454`.

### Disabled icon

```html
<span class="bf-icon fa-solid fa-lock"
      aria-label="Unavailable"
      aria-disabled="true"></span>
```

Result: runtime disabled state with default disabled opacity 0.45.

### Animation via 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",
  animation: "spin"
});
</script>
```

### Icon name and Unicode shown with the glyph

```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>
```

Result: shows `star` below the icon and `f005` to its right.

### Visible and OUT kept separate

```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>
```

Result: displays only the glyph while keeping icon class, name, and Unicode available in OUT.

### Circular 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>
```

Result: places the Check icon inside a 72x72 circular background.

### 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>
```

Result: applies a two-stop 90-degree linear gradient to the icon glyph.


## Runtime Property Schema / #048 Table

#018 Icon v1.0.21 exposes the formal **`BoneIcon.getPropertySchema()`** API, following the runtime-owned Property Schema approach used by #054 Display Timeline. This lets consumers such as #048 Table obtain the Icon property definition directly from the #018 Runtime.

Formal contract:

- #018 Runtime owns the property definition. #048 Table must not maintain a duplicated #018 property list.
- `getPropertySchema()` returns an array of definitions. Every entry contains at least `key / label / labelJa / type / group / default / defaultValue / path`; select entries also expose `options`, and numeric entries may expose `min / max / step`.
- `default / defaultValue` are derived from `BoneIcon.normalize({})` on every call so the Runtime remains the single source of truth for defaults.
- Nested properties use dot-path keys such as `visible.icon`, `nameStyle.fontSize`, and `containerStyle.width`, and also expose a `path` array.
- Adding the schema does not change the existing `normalize / create / render / update` property contract.
- This change does not modify #048 Table or #054 Display Timeline.

Consumers should use `BoneIcon.getPropertySchema()` as the `propertySchema` provider when registering #018 as a #048 Cell Renderer instead of copying the property list into Table code.

```javascript
const iconPropertySchema = BoneIcon.getPropertySchema();
// Use this runtime-owned schema as the propertySchema provider for the #048 Cell Renderer registration.
```

## Runtime Default / Property Editor

### Runtime defaults

| Property | Default | Runtime contract |
|---|---|---|
| `name` | `star` | non-empty string |
| `unicode` | `f005` | 3-6 hex digits |
| `className` | `fa-solid fa-star` | string |
| `size` | 56 | number >=1 |
| `color` | `#55E6A5` | Color Value |
| `rotate` | 0 | Number conversion; runtime has no 0-359 validation |
| `flip` | `none` | 4 values |
| `title` | empty | string |
| `animation` | `none` | 10 values |
| `backgroundColor` | null | Color Value / null |
| `activeBackgroundColor` | null | Color Value / null |
| `active` | false | Boolean conversion |
| `disabled` | false | Boolean conversion |
| `visible` | icon true, name false, unicode false | truthy/falsy map |
| `output` | icon/name/unicode true | truthy/falsy map |
| `nameStyle` | 16px, #DCE8F8, inherit, bottom, gap 8 | object |
| `unicodeStyle` | 14px, #9FC5F8, monospace, right, gap 8 | object |
| Container sizes | null | null/auto or number >=0 |
| Padding | 10/10/10/10 | number >=0 |
| Border | disabled, #425A78, 1px, solid | object |
| Shape | rounded, radius 8 | 6 shape values |
| justify / align | center / center | runtime does not enum-validate these strings |
| overflow | visible | 3 values |
| opacity | 1 | clamp to 0-1; invalid numeric input becomes 1 |
| Shadow | off, outer, 0/4/12/0, #00000066 | object |
| `containerStyle.output` | true | Boolean conversion |
| `activeStyle` | borderColor null, borderWidth null, shadowColor null | object |
| `disabledStyle` | opacity .45, background null, border null | object |

### Current Property Editor defaults

The page starts at 220×150 container size even though Runtime width/height defaults are null/auto. It starts with border/shadow/background/active/disabled OFF, visible Icon only, OUT Icon+Name+Unicode ON, container OUT ON, Name bottom 16px, Unicode right 14px. Editor ranges are narrower than several Runtime ranges and are not to be treated as identical contracts.

## Identity properties

### name

Logical icon name. Default `star`. Empty names raise `BONE_ICON_NAME_REQUIRED`.

### unicode

3-6 hexadecimal digits. Default `f005`. Invalid values raise `BONE_ICON_UNICODE_INVALID`.

### className

Font Awesome class string. Default `fa-solid fa-star`.

## size / rotate

`size` is the glyph font size: runtime >=1, editor 8-256, default 56. Invalid runtime values raise `BONE_ICON_SIZE_INVALID`.

`rotate` becomes CSS `rotate(<value>deg)`. Editor uses 0-359. Runtime performs Number conversion and does not enforce that editor range.

## flip: all 4 values

- `none`: no flip
- `horizontal`: horizontal mirror
- `vertical`: vertical mirror
- `both`: horizontal and vertical mirror

Default `none`. Invalid values raise `BONE_ICON_FLIP_INVALID`.

## animation: all 10 values

- `none`: no animation
- `beat`: scale pulse
- `beat-fade`: scale + opacity pulse
- `bounce`: bouncing motion
- `fade`: opacity cycle
- `flip`: 3D flip motion
- `shake`: shake motion
- `spin`: continuous rotation
- `spin-pulse`: stepped rotation
- `spin-reverse`: reverse continuous rotation

Default `none`. Invalid values raise `BONE_ICON_ANIMATION_INVALID`.

## Colors / #040 ColorPicker

Formal Color Values are `#RRGGBB`, `transparent`, or a two-stop linear gradient object. Gradient angle is 0 <= angle < 360, there must be exactly two stops, positions are 0-100 and strictly increasing, and stop colors are `#RRGGBB`.

Container shadow color is special: it allows `#RRGGBB`, `#RRGGBBAA` or `transparent`, but no gradient.

The #018 page delegates its ten color pickers to #040 ColorPicker v1.0.18 through `attachCaller()` rather than copying ColorPicker internals.

## visible / output

Display and OUT are independent.

- visible default: icon ON, name OFF, unicode OFF
- output default: icon ON, name ON, unicode ON
- containerStyle.output default: ON

`getOutput()` returns `icon`, `iconName`, `unicode` only when their output flags are enabled, and returns `containerStyle` only when container output is enabled.

## Name / Unicode position: all 4 values

- `top`: top slot, gap below label
- `bottom`: bottom slot, gap above label
- `left`: left slot, gap on label right
- `right`: right slot, gap on label left

Invalid values raise `BONE_ICON_POSITION_INVALID`.

## Name Style

Default: fontSize 16, color #DCE8F8, family inherit, position bottom, gap 8. Runtime font size >=1 and gap >=0. Current editor family choices are inherit, Meiryo, Yu Gothic, sans-serif, serif, monospace.

## Unicode Style

Default: fontSize 14, color #9FC5F8, family monospace, position right, gap 8. Runtime font size >=1 and gap >=0. Editor uses the same six family choices.

## Container Size

width, height, minWidth, maxWidth, minHeight, maxHeight accept null/empty/`auto` or numbers >=0. Runtime defaults are null. Invalid values raise `BONE_ICON_CONTAINER_SIZE_INVALID`.

## Border Style: all 4 values

- `solid`
- `dotted`
- `dashed`
- `double`

Default solid. Invalid values raise `BONE_ICON_BORDER_STYLE_INVALID`. `borderEnabled=false` suppresses the border regardless of stored width/color/style.

## Shape: all 6 values

- `square`: radius 0
- `rounded`: uses borderRadius
- `circle`: 50%
- `ellipse`: 50%
- `capsule`: 9999px
- `custom`: uses borderRadius

Default rounded, radius 8. Invalid values raise `BONE_ICON_SHAPE_INVALID`.

## justify / align: all Editor values

Editor justify: start(left), center, end(right). Editor align: start(top), center, end(bottom). Defaults center/center. Runtime v1.0.21 does not enum-validate these strings, so the browser CSS engine handles arbitrary Public API strings.

## overflow: all 3 values

- `visible`: show overflow, default
- `hidden`: clip overflow
- `auto`: automatic scroll area

Invalid values raise `BONE_ICON_OVERFLOW_INVALID`.

## Shadow

Default off. `shadowInset` controls inset. X/Y/Spread require >=-999, Blur >=0. Default values are 0 / 4 / 12 / 0. Shadow gradient is not accepted.

## Active / Disabled

Active background falls back to normal background when its value is null. Active border override is applied only when the normal container border is enabled. `activeStyle.shadowColor` exists in normalized state but is not used by the current v1.0.21 renderer and has no Property Editor control; this guide does not claim it renders.

Disabled style defaults: opacity .45, background null, border null.

## Keyboard / operation

Use the Icon search/picker, Property Editor, combined preview, #040 color triggers, then Smoke/Validation. Normal Tab/Shift+Tab navigation and Enter/Space button activation apply. The Icon view itself is not a Button; use an action component when click behavior is needed. Escape closes the DOC guide.

## Joint

Connection lines and compatibility are #002 Bone Joint responsibility. #018 does not draw a fake independent connection line. The page keeps blue IN, green OUT, orange type mismatch, and red error/missing-target indications.

## Smoke / Validation

The formal page checks Runtime, #040 Caller integration, 1,944 Font Awesome items, visible/output behavior, container behavior and Joint behavior. Validation includes invalid name, Unicode, size, flip, animation, gradient, shadow gradient, border style, shape, overflow, position and instance API cases.

## Completion

`complete(validation)` requires `allPass`, `smokePassed` and `validationPassed` all true or raises `BONE_ICON_COMPLETION_VALIDATION_REQUIRED`. `reopen()` returns the component state to Development.

## Public API

The 14 methods are separate from `bf-icon`:

1. `normalize(value)`
2. `getPropertySchema()`
3. `create(options)`
4. `getCompletionState()`
5. `complete(validation)`
6. `reopen()`
7. `render(target, options)`
8. `update(el, options)`
9. `getOptions(el)`
10. `getOutput(el)`
11. `setActive(el, active)`
12. `setDisabled(el, disabled)`
13. `isInstance(el)`
14. `destroy(el)`

`getPropertySchema()` returns the #018-owned 63-property schema for consumers such as #048 Table. The returned definitions include runtime-derived defaults and fresh arrays/objects so consumer mutation does not alter the runtime source of truth.

## HTML Functional Class events

- `bone-icon-html-class-mounted`: emitted after a `bf-icon` element is converted.
- `bone-icon-html-class-error`: emitted when lookup or conversion fails.

## Errors / troubleshooting

Runtime errors include `BONE_ICON_NAME_REQUIRED`, `BONE_ICON_UNICODE_INVALID`, `BONE_ICON_SIZE_INVALID`, `BONE_ICON_FLIP_INVALID`, `BONE_ICON_ANIMATION_INVALID`, `BONE_ICON_COLOR_INVALID`, `BONE_ICON_GRADIENT_INVALID`, `BONE_ICON_CONTAINER_SIZE_INVALID`, `BONE_ICON_FONT_SIZE_INVALID`, `BONE_ICON_GAP_INVALID`, `BONE_ICON_PADDING_INVALID`, `BONE_ICON_BORDER_WIDTH_INVALID`, `BONE_ICON_BORDER_STYLE_INVALID`, `BONE_ICON_SHAPE_INVALID`, `BONE_ICON_RADIUS_INVALID`, `BONE_ICON_OVERFLOW_INVALID`, `BONE_ICON_SHADOW_INVALID`, `BONE_ICON_POSITION_INVALID`, `BONE_ICON_DOCUMENT_UNAVAILABLE`, `BONE_ICON_TARGET_INVALID`, `BONE_ICON_INSTANCE_INVALID`, and `BONE_ICON_COMPLETION_VALIDATION_REQUIRED`.

HTML class errors include `BONE_ICON_HTML_CLASS_RUNTIME_UNAVAILABLE`, `BONE_ICON_HTML_CLASS_ELEMENT_UNSUPPORTED`, `BONE_ICON_HTML_CLASS_NAME_REQUIRED`, `BONE_ICON_HTML_CLASS_ICON_NOT_FOUND`, `BONE_ICON_HTML_CLASS_FETCH_UNAVAILABLE`, `BONE_ICON_HTML_CLASS_CATALOG_LOAD_FAILED`, and `BONE_ICON_HTML_CLASS_CATALOG_EMPTY`.

If the icon is missing, verify `bone-icon.js`, `bone-icon-html-class.js`, `bone-icon.css`, the Font Awesome webfont, `bf-icon`, `fa-solid`, and a valid `fa-<name>` from the formal catalog.

## Dependencies / DOC reuse

The current page validates #001 Core v1.0.0, #002 Joint v1.1.36, #020 Label v1.0.61 and #022 Hover Border Effect v1.0.10 through #040, and #040 ColorPicker v1.0.18. #017 Text is a UI/connection-image reference, not a Runtime dependency.

DOC route: `UI-018 → DOC-0018 → registry → content/DOC-0018/{lang}.md → BoneDocLoader → BoneDocGuide`.


## v1.0.21 additional contract
`BoneIcon.getPropertyDefaults()` returns the normalized Runtime defaults. `BoneIcon.getPropertyDefinition(key)` returns one formal schema definition or null. Consumers such as #048 Table use the #018 Runtime as the property source of truth.


## Formal Property Definition (Runtime Schema)

The #018 property source of truth is the **BoneIcon Runtime**, following the Runtime-owned schema pattern used by #054 Display Timeline.

- `BoneIcon.getPropertySchema()` returns the 63 formal property definitions.
- `BoneIcon.getPropertyDefaults()` returns normalized Runtime defaults.
- `BoneIcon.getPropertyDefinition(key)` returns one formal definition or `null`.

The visible Runtime Schema table in `bone-icon.html` is generated from these APIs. Consumers such as #048 Table must use the #018 Runtime schema rather than maintaining a duplicated property list.

## HTML Functional Class baseline

As with #017 Text, normal HTML usage has one formal entry class: `bf-icon`.

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

`BoneIconHTMLClass` reads standard HTML classes, attributes, and inline CSS and bridges them to `BoneIcon 1.0.21`. It does not invent one class or arbitrary `data-*` attribute per Public API.