# Bone Flow #019 Image Guide

## 1. Start here — shortest way to use #019

This is a **practical operation and usage guide** for #019 Image. It is not only an internal specification reference.

- UI ID: `UI-019`
- DOC ID: `DOC-0019`
- Package: `1.0.110 Candidate`
- Runtime: `BoneImage 1.0.83`
- HTML Functional Class: `bf-image`
- Test URL: `/boneflow/test/bone-image.html`

For the quickest check:

1. In **Property**, choose a sample.
2. Adjust **TYPE / Source / Region / Fit / Display Rate / Position** as needed.
3. For ICON or EMOJI, select an item from its catalog.
4. Press **Confirm Changes**.
5. Check **Combined Preview** and the **OUT values** below it.

Property edits are previewed immediately. When the page shows uncommitted changes, press **Confirm Changes** when you decide to keep the settings.

## 2. Show one image on the test page

### 2.1 Start from a sample

1. Open **Sample**.
2. Choose `PNG file`, `SVG file`, `#018 Bone Icon`, `Emoji`, or another sample.
3. TYPE, Source, and related fields are filled from the sample.
4. Check the Combined Preview.
5. Adjust any Property you need.
6. Press **Confirm Changes**.

### 2.2 Select TYPE directly

The formal Runtime TYPE values are:

`ICON / EMOJI / BITMAP / SVG / JPEG / JPG / PNG / GIF / WEBP / AVIF / BMP / ICO / DATAURL`

- `ICON` uses the formal #018 Bone Icon path.
- `EMOJI` uses the Emoji catalog.
- Normal image types use Source or an image file.
- `DATAURL` uses a Data URL string as Source.

## 3. Use a PNG / JPG / SVG or other image file

1. Select an image TYPE such as `PNG`, `JPG`, `JPEG`, `SVG`, `GIF`, `WEBP`, `AVIF`, `BMP`, or `ICO`.
2. For normal display, select **Use as image** in Usage.
3. When the Image File area appears, drag and drop a file or press **Choose File**.
4. Check `Source / Icon value` and the original width / height.
5. Enter Alt Text and Title when needed.
6. Press **Confirm Changes**.
7. Check Combined Preview and #019 Image OUT.

### Display region

- **Match parent** — use the parent display region.
- **Original image size** — use the image dimensions.
- **Match width** — size from width.
- **Match height** — size from height.

### Display method

- **FIT** — `contain`.
- **Original / none** — no automatic fitting.

Display Rate accepts 1–500%.

### Position

Nine positions are available: top-left, top-center, top-right, center-left, center, center-right, bottom-left, bottom-center, bottom-right.

## 4. Use an ICON

TYPE=`ICON` makes #019 resolve the formal #018 Bone Icon internally. Users do not need to administer List Key.

### Select from the in-page icon list

1. Set TYPE to `ICON`.
2. Use the icon list and search box.
3. Click the icon to use.
4. Confirm that `Source / Icon value` contains the selected `fa-...` value.
5. Open Image Icon Display Settings if needed.
6. Set size, color, rotation, flip, Name display, and container state.
7. Press **Confirm Changes**.

### Select from the separate Icon Catalog

1. Set TYPE to `ICON`.
2. Press **Open Icon Catalog**.
3. Search and click an item.
4. Change icon color with the formal #040 ColorPicker when needed.
5. Press **Apply selection to #019**.
6. Return to #019 and check Source / Name / Preview.
7. Press **Confirm Changes**.

Double-click copies the selected value. Use **Apply selection to #019** to send the selection back to #019.

### Main ICON display settings

You can configure icon size, icon color, rotation, flip, Name font settings, Icon / Name visibility and OUT, backgrounds, container size, border, shape, radius, padding, alignment, overflow, opacity, shadow, Active border, and Disabled state.

The color-square buttons are formal #040 ColorPicker callers. They are not native color inputs.

## 5. Use an Emoji

### Select from the in-page Emoji list

1. Set TYPE to `EMOJI`.
2. Choose a group or browse the list.
3. Click an Emoji.
4. Confirm that Source and Name are updated.
5. Adjust image-icon display settings if needed.
6. Press **Confirm Changes**.

Emoji does not require a List Key.

### Select from the separate Emoji Catalog

1. Set TYPE to `EMOJI`.
2. Press **Open Emoji Catalog**.
3. Search or filter by group.
4. Click an Emoji.
5. Press **Apply selection to #019**.
6. Return to #019 and check Preview.
7. Press **Confirm Changes**.

`🎌` is only a normal Emoji Catalog entry. It is not a dedicated holiday feature.

## 6. Configure #022 Hover Border Effect

The #022 section controls the **Hover / Active effect on Icon / Emoji Catalog items**. It is not a custom effect applied to the whole final Image Preview.

- Trigger: `mouseover / active / both`
- Effect: `normal / neon / spin / cross / blink`
- Color: selected through #040 ColorPicker
- Direction: `clockwise / counterclockwise`
- Speed: `slow / normal / fast`
- Spin Width: `1..24`
- Spin Glow: `0..40`

## 7. Use colors and #040 ColorPicker

Press the square color button beside a color Property to open the formal #040 ColorPicker Overlay.

Color callers include icon color, Name color, backgrounds, container border/shadow, Active border, Disabled colors, and #022 Hover Border Effect color.

For background properties, the **Apply** checkbox and the selected color are separate controls. Selecting a color does not necessarily enable the background.

#118 Transition is used **only for #040 ColorPicker Overlay OPEN / CLOSE**. It is not applied to Image Preview or Combined Preview.

## 8. Read Preview and OUT

The **Combined Preview** shows the combined current #019 Property result.

Below it are three JSON outputs:

### #019 Image OUT

The output returned by #019 Image to its parent component.

### Child Component Input

The value #019 passes to a child component. For ICON, this can show the input sent to #018 Bone Icon. It can be `null` when no child component is used.

### Child Component OUT

The output returned from the child component.

When the page shows uncommitted changes, press **Confirm Changes** after deciding the final settings.

## 9. Inspect Runtime Property Schema

**Formal Property Definition (Runtime Schema)** is for inspection, not the main editing UI.

1. Open a Property Group accordion.
2. Inspect Property, Type, Default, Current, Allowed / Constraints, and Description.
3. Edit actual values in the Property section above.

Canonical APIs:

- `BoneImage.getPropertySchema()`
- `BoneImage.getPropertyDefaults()`
- `BoneImage.getPropertyDefinition(key)`

The Guide does not maintain a second copy of all Runtime Property definitions.

## 10. Use it in HTML — `bf-image`

The normal-use entry point is **`class="bf-image"`**.

### PNG

```html
<img
  class="bf-image"
  src="/images/photo.png"
  alt="Product photo"
  title="Product photo"
  width="320"
  height="180"
  style="object-fit:contain;object-position:center;"
>
```

### Image with `data-source`

```html
<div
  class="bf-image"
  data-image-type="PNG"
  data-source="/images/photo.png"
  data-width="320"
  data-height="180"
  data-fit="contain"
  data-position="center"
></div>
```

### ICON

```html
<span
  class="bf-image"
  data-image-type="ICON"
  data-icon="fa-image"
  data-size="56"
  data-rotate="0"
  data-flip="none"
></span>
```

For ICON, the Runtime resolves `018-icon-fontawesome` internally.

### Emoji

```html
<span
  class="bf-image"
  data-image-type="EMOJI"
  data-emoji="😀"
  data-size="56"
  title="Smile"
>😀</span>
```

### Main HTML inputs read by `bf-image`

- `src` or `data-source`
- `data-image-type` or `data-type`
- `data-icon`
- `data-emoji`
- `data-usage`
- `data-list-key`
- `width` / `height`
- `data-width` / `data-height`
- `data-size`
- `data-fit`
- `data-position`
- `data-rotate`
- `data-flip`
- `alt`
- `title`
- `data-bone-id`

When TYPE is omitted, the Runtime can infer it from supported source/element information. Use `data-image-type` when you want to specify it explicitly.

## 11. Use the JavaScript Public API

Use Public API when the HTML Functional Class is not enough.

### Create and display a Bone

```javascript
const bone = BoneCore.create({
  id: "product-image",
  type: "IMAGE",
  value: {
    type: "PNG",
    usage: "image",
    listKey: "019-bitmap",
    source: "/images/photo.png",
    alt: "Product photo",
    title: "Product photo",
    width: 320,
    height: 180,
    fit: "contain",
    position: "center"
  }
});

const imageElement = BoneImage.create(bone);
document.querySelector("#preview").appendChild(imageElement);
```

### Read OUT

```javascript
const output = BoneImage.getOutput(imageElement);
const childInput = BoneImage.getChildInput(imageElement);
```

### Read Property Schema

```javascript
const schema = BoneImage.getPropertySchema();
const defaults = BoneImage.getPropertyDefaults();
const typeDefinition = BoneImage.getPropertyDefinition("type");
```

BoneImage Runtime 1.0.83 remains authoritative.

## 12. Common operation mistakes

### Preview does not show

Check TYPE and Source, confirm that normal image Source is not empty, confirm that Emoji Source contains an Emoji, and check #018 dependency status for ICON.

### Icon / Emoji catalog button does not appear

Catalog buttons follow TYPE:

- TYPE=`ICON` → Icon Catalog
- TYPE=`EMOJI` → Emoji Catalog
- Other TYPE → both hidden

### Background color does not appear

Check the **Apply** checkbox. Choosing a color and enabling the background are separate actions.

### List Key cannot be edited

That is expected. UI Registry / List Key is an internal child-UI resolution dependency for #019, not a user-facing Registry administration UI.

## 13. Smoke Test / Validation

At the bottom of the page:

1. **Run Smoke Test** checks core Runtime/UI/dependency/Preview behavior.
2. **Run Validation** checks formal contracts and error cases.
3. **Run All Tests** runs both.
4. Save JSON / MD reports when needed.

Do not show PASS before execution, and do not mark Completed / Specification Frozen before localhost verification.

## HTML Functional Class

The formal HTML Functional Class is `bf-image`.

The **Open HTML Functional Class Guide** button at the bottom of the test page opens this section directly.

Minimal example:

```html
<img class="bf-image" src="/images/photo.png" alt="photo">
```