# Bone Flow #019 Image 操作ガイド

## 1. 最初に — #019を使う最短手順

このガイドは **#019 Imageを実際に操作・利用するための手順書** です。内部仕様だけを並べる文書ではありません。

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

最初は次の5手順だけで確認できます。

1. 「プロパティ設定」の **サンプル** から表示したい種類を選びます。
2. 必要なら **TYPE / Source / 表示領域 / 表示方法 / 拡大率 / 表示位置** を変更します。
3. ICONまたは絵文字なら、表示される一覧から項目を選びます。
4. **変更を確定** を押します。
5. 右側の **合算プレビュー** と、その下の **OUT値** を確認します。

Propertyを変更するとPreviewはその場で更新されます。「未確定の変更あり」と表示されたら、決定する時に **変更を確定** を押してください。

## 2. テスト画面で画像を1枚表示する

### 2.1 サンプルから始める

一番簡単なのは「サンプル」を使う方法です。

1. 「サンプル」を開きます。
2. `PNG 実ファイル`、`SVG 実ファイル`、`#018 Bone Icon`、`絵文字` などを選びます。
3. TYPE、Source、サイズなどがサンプル値へ切り替わります。
4. 右の「合算プレビュー」で結果を確認します。
5. 必要なPropertyを変更します。
6. **変更を確定** を押します。

サンプルは操作確認用です。実際の画像を使う場合は次の「画像ファイルを使う」を利用してください。

### 2.2 TYPEを直接選ぶ

「TYPE」で画像の種類を選びます。現行Runtimeの正式TYPEは次の13種類です。

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

TYPEに応じて必要な操作欄が切り替わります。

- `ICON` → #018 Bone Iconのアイコン一覧を使用します。
- `EMOJI` → Emoji一覧を使用します。
- 通常画像TYPE → Sourceまたは画像ファイルを使用します。
- `DATAURL` → Data URL文字列をSourceへ指定します。

## 3. PNG / JPG / SVGなど画像ファイルを使う

### 3.1 画像ファイルを選ぶ

1. TYPEを `PNG`、`JPG`、`JPEG`、`SVG`、`GIF`、`WEBP`、`AVIF`、`BMP`、`ICO` などへ変更します。
2. 「用途」で通常表示なら **画像として使用** を選びます。
3. 「画像ファイル」欄が表示されたら、画像をドラッグ＆ドロップするか **ファイルを選択** を押します。
4. `Source / Icon value`、元画像幅・高さなどを確認します。
5. 「代替テキスト」と「タイトル」を必要に応じて入力します。
6. **変更を確定** を押します。
7. 「合算プレビュー」と「#019 Image OUT」を確認します。

### 3.2 表示領域

「表示領域」は画像をどの領域へ合わせるかを決めます。

- **親要素に合わせる** — 親側の表示領域へ合わせます。
- **元画像サイズ** — 元画像の幅・高さを基準にします。
- **幅に合わせる** — 幅を基準に表示します。
- **高さに合わせる** — 高さを基準に表示します。

### 3.3 表示方法

- **FIT** — `contain`。画像全体が入るように表示します。
- **そのまま表示** — `none`。画像を自動FITしません。

「拡大率（%）」は1〜500の範囲で変更できます。

### 3.4 表示位置

「表示位置」は9方向です。

`左上 / 上中央 / 右上 / 左中央 / 中央 / 右中央 / 左下 / 下中央 / 右下`

画像を選んだあと、ここを変更すると合算プレビューで位置を確認できます。

## 4. ICONを使う

TYPEを `ICON` にすると、#019は正式 #018 Bone Iconを内部解決します。利用者がList Keyを管理する必要はありません。

### 4.1 画面内のアイコン一覧から選ぶ

1. TYPEを `ICON` にします。
2. アイコン一覧が表示されます。
3. 検索欄へ名前を入力して絞り込みます。
4. 使用するアイコンをクリックします。
5. `Source / Icon value` に `fa-...` が設定されたことを確認します。
6. 必要なら「画像アイコン表示設定」を開きます。
7. サイズ、色、回転、反転、Name表示などを設定します。
8. **変更を確定** を押します。

### 4.2 別画面のアイコン一覧を使う

1. TYPEを `ICON` にします。
2. **別画面でアイコン一覧** を押します。
3. 別画面で検索します。
4. 項目をクリックして選択します。
5. 必要ならアイコン色を #040 ColorPickerで変更します。
6. **選択を#019へ反映** を押します。
7. #019画面へ戻り、Source / Name / Previewを確認します。
8. **変更を確定** を押します。

ダブルクリックは選択値のコピーです。#019へ戻す場合は「選択を#019へ反映」を使います。

### 4.3 ICONの表示設定

「画像アイコン表示設定」では主に次を設定できます。

- 画像アイコンサイズ
- アイコン色
- 回転角度
- 反転
- Nameの文字サイズ / 色 / フォント / 位置 / 間隔
- Icon / Name の「表示」と「OUT」
- 背景色
- Active背景色
- Containerの幅・高さ・最小/最大サイズ
- 枠線、形状、角丸、padding、配置、overflow、透明度、影
- Active時の枠
- Disabled時の透明度 / 背景 / 枠

色の四角ボタンは正式 #040 ColorPicker Callerです。native color inputではありません。

## 5. 絵文字を使う

### 5.1 画面内のEmoji一覧から選ぶ

1. TYPEを `絵文字` にします。
2. Emoji一覧が表示されます。
3. グループを選ぶか、一覧から探します。
4. 使用するEmojiをクリックします。
5. SourceとNameが更新されたことを確認します。
6. 必要なら画像アイコン表示設定を変更します。
7. **変更を確定** を押します。

EmojiではList Keyは不要です。

### 5.2 別画面のEmoji一覧を使う

1. TYPEを `絵文字` にします。
2. **別画面で絵文字一覧** を押します。
3. 検索またはグループで絞り込みます。
4. Emojiをクリックします。
5. **選択を#019へ反映** を押します。
6. #019へ戻り、Previewを確認します。
7. **変更を確定** を押します。

`🎌` も通常のEmoji Catalog項目の1つです。祝日専用の固定表示機能ではありません。

## 6. #022 Hover Border Effectを設定する

「#022 Hover Border Effect」は **Icon / Emoji Catalogの各itemへ付けるHover/Active表示** です。最終Image Preview全体へ独自CSSを付ける機能ではありません。

設定項目は次です。

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

変更すると一覧itemへ反映されます。

## 7. 色と#040 ColorPickerを使う

色Propertyの右にある四角ボタンを押すと、正式 #040 ColorPicker Overlayが開きます。

主な対象は次です。

- アイコン色
- Name色
- 背景色
- Active背景色
- Container枠色
- Container影色
- Active枠色
- Disabled背景色
- Disabled枠色
- #022 Hover Border Effect色

背景色やActive背景色は「適用」チェックと色選択が分離されています。色を選んだだけでは適用ONにならない項目があります。

#118 Transitionは **#040 ColorPicker OverlayのOPEN / CLOSEだけ** に使用します。Image Preview全体やCombined Previewへは適用しません。

## 8. PreviewとOUTを読む

右側の「合算プレビュー」は現在の #019 Propertyを合算した結果です。

Previewの下には3種類のJSONがあります。

### 8.1 #019 Image OUT

#019 Image自身が上位Componentへ返すOUTです。

### 8.2 子Component Input

#019から子Componentへ渡す入力です。ICONでは#018 Bone Iconへ渡す値を確認できます。子Componentを使わない状態では `null` になる場合があります。

### 8.3 子Component OUT

子Component側から返るOUTです。ICONなど子Componentを使う場合に確認します。

設定変更中は「未確定の変更あり」と表示されます。最終的に採用する内容を決めたら **変更を確定** を押してください。

## 9. Runtime Property Schemaを確認する

「正式Property定義（Runtime Schema）」は **操作欄ではなく、Runtime定義を確認するための表示** です。

1. Property GroupのAccordionを開きます。
2. Property名、型、Default、現在値、許容値/制約、説明を確認します。
3. 実際の編集は上部の「プロパティ設定」で行います。

正本APIは次です。

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

Guide側へ84 Propertyを別定義として複製しません。

## 10. HTMLで実際に使う — `bf-image`

通常利用の入口は **`class="bf-image"`** です。

### 10.1 PNGを表示する

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

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

### 10.3 ICONを表示する

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

ICONではRuntimeが `018-icon-fontawesome` を内部解決します。通常利用側で独自List Keyを発明しません。

### 10.4 Emojiを表示する

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

### 10.5 `bf-image` が読む主なHTML指定

- `src` または `data-source`
- `data-image-type` または `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`

TYPE未指定時はSourceや要素内容からRuntimeが判定できる範囲で判定します。明示したい場合は `data-image-type` を使用してください。

## 11. JavaScript Public APIで使う

HTML Functional Classでは足りない場合だけPublic APIを使います。

### 11.1 Boneを作って表示する

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

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

### 11.2 OUTを取得する

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

### 11.3 Property Schemaを読む

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

現行RuntimeのPublic APIは `BoneImage 1.0.83` を正本とします。

## 12. よくある操作ミス

### Previewが表示されない

- TYPEとSourceの組み合わせを確認します。
- 通常画像TYPEではSourceが空でないか確認します。
- EmojiではEmoji文字がSourceへ入っているか確認します。
- ICONでは#018依存が利用可能かDependency表示を確認します。

### ICON / Emoji一覧ボタンが出ない

一覧ボタンはTYPE連動です。

- TYPE=`ICON` → アイコン一覧
- TYPE=`EMOJI` → 絵文字一覧
- その他 → 両方非表示

### 色を変えたのに背景へ出ない

背景色系は「適用」チェックを確認してください。ColorPickerで色を選ぶことと、背景色を有効にすることは別操作です。

### List Keyが操作できない

正常です。UI Registry / List Keyは #019 Runtime内部の子UI解決用です。利用者向けRegistry管理UIではありません。

## 13. Smoke Test / Validation

画面下部で次を実行できます。

1. **Smoke Test 実行** — 基本Runtime、UI、依存、Preview等を確認します。
2. **Validation 実行** — 異常系・正式契約も含めて確認します。
3. **全テスト実行** — 両方をまとめて実行します。
4. 必要ならJSON / MDレポートを保存します。

未実行をPASSにはしません。localhostで実結果が確認される前にCompleted / Specification Frozenとはしません。

## HTML Functional Class

正式HTML Functional Classは `bf-image` です。

テストページ下部の **HTML Functional Class ガイドを開く** は、この項目へ直接移動します。

最小例はこれです。

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