# #040 Bone ColorPicker

Version: 1.0.17  
Status: Development

`#040 ColorPicker` is the Bone Flow Input UI for selecting a solid color, explicit transparency, or a safe two-stop linear gradient.

## Runtime

- Test: `/boneflow/test/bone-colorpicker.html`
- JS: `/boneflow/js/bone-colorpicker.js`
- CSS: `/boneflow/css/bone-colorpicker.css`

## Value contract

Solid:

```text
Bone.type  = COLORPICKER
Bone.value = #RRGGBB
```

Gradient:

```json
{
  "kind": "gradient",
  "type": "linear",
  "angle": 135,
  "stops": [
    { "position": 0, "color": "#0D6EFD" },
    { "position": 100, "color": "#0DCAF0" }
  ]
}
```

Transparent:

```text
Bone.type  = COLORPICKER
Bone.value = transparent
```

`transparent` is an explicit allowlisted ColorPicker value. Other CSS named colors remain blocked. Raw CSS gradient strings are not a Bone value.

## Presets

Solid presets: 31, with Japanese / English display names.

Gradient presets: 8.

- Ocean / オーシャン
- Sunset / サンセット
- Forest / フォレスト
- Aurora / オーロラ
- Violet / バイオレット
- Fire / ファイア
- Ice / アイス
- Monochrome / モノクローム

Custom solid and gradient presets can be added with Japanese / English display names.

## Public runtime

- `BoneColorPicker.create()` — #040 standalone / test-page compatibility
- `BoneColorPicker.attachCaller(trigger, bone, options)` — formal Consumer integration
- `detachCaller()` / `openCaller()` / `closeCaller()` / `isCallerOpen()`
- `getCallerValue()` / `setCallerValue()` / `getCallerOutput()` / `getCallerState()` / `repositionCaller()`
- `getInput()`
- `getOptions()`
- `getValue()`
- `getEditingValue()`
- `getColorState()`
- `normalizeColor()`
- `normalizeGradient()`
- `normalizeValue()`
- `gradientToCss()`
- `defaultNamedColors()`
- `getNamedColors()` / `addNamedColor()` / `removeNamedColor()`
- `defaultNamedGradients()`
- `getNamedGradients()` / `addNamedGradient()` / `removeNamedGradient()`
- `localizedName()`
- `setValue()`
- `applyJointInput()`
- `reset()`
- `commit()`
- `buildOutput()`
- `connectOutput()` / `disconnectOutput()`
- `setOutputTargetReady()`
- `clearOutputBlock()`
- `getOutputState()`
- `setOptions()`
- `syncParentStyle()`

## Scope

Included:

- strict HEX6 solid color
- safe two-stop linear gradient
- named solid presets
- named gradient presets
- Japanese / English preset names
- custom solid / gradient preset add

Not included:

- full Palette Manager / Color Library manager
- unlimited multi-stop Gradient Editor
- arbitrary CSS input
- image color extraction
- Theme Designer
- advanced Eyedropper

## Runtime confirmation

Package QA is performed before delivery. Browser Runtime and Completion are not confirmed until the user verifies the component on localhost and performs the completion operation.



## v1.0.6 targeted correction

- ColorPicker Preview / API: gradient value display wraps so the actual-use control is not visually cut off.
- Named solid colors and named gradients in Property are independent accordions.
- Actual picker chips have a visible hover/focus lift, scale, border and glow effect while keeping localized tooltip names.
- Formal connection image normal case is restored to one wide `Source -> #040 ColorPicker -> Target` card with IN and OUT Joint lines; exceptional cases remain separate (5 cards total).

## Actual-use Picker Preview (v1.0.5)

ColorPicker Previewは実際の使用状態を表示する。初期状態ではColorPicker本体だけを表示し、本体をクリックすると内部Picker panelを開く。Picker内に単色31色、透過1種、グラデーション8種を正方形チップで並べ、色名はマウスオーバー/フォーカス時のみ日本語またはEnglishで表示する。カスタム単色/グラデーション追加UIもPicker panel内に持つ。


## v1.0.7 package correction
- Installer/MANIFEST path basis corrected to match the formal package layout.
- MANIFEST entries are relative to the `boneflow` source root; no duplicated `boneflow/boneflow` lookup occurs.
- ColorPicker runtime/UI behavior is unchanged from v1.0.6.

## v1.0.8 reusable consumer API

- `allowedKinds` を追加。`solid` / `transparent` / `gradient` からCallerが許可種別を明示できる。
- 許可外kindは `COLORPICKER_VALUE_KIND_NOT_ALLOWED` で拒否し、Picker UIにも表示しない。
- 既定値は従来どおり3種類すべて許可し、v1.0.7の既存動作は維持する。
- #020 Labelなど既存Propertyが単色HEXのみの場合、`allowedKinds: ["solid"]` で共通ColorPickerを利用できる。


## v1.0.9 single trigger

- Actual-use ColorPickerの入口を1つのbuttonへ統合。現在値Preview / 値テキスト / ▼は同じbutton内に表示する。
- 互換用`getInput()`は`input[type=color]`を返すが、表示・クリック入口には使用せずhidden / tabIndex=-1とする。
- Solid / Transparent / Gradient / カスタム追加 / OUT / Joint契約は変更しない。
- 狭いConsumer幅では値テキストをellipsis表示し、全文は`title` tooltipで確認できる。
- Consumer側でNative color inputや個別toggleを抑止するCSS/JSを積み重ねなくてよい構造へ整理した。


## v1.0.12 compact trigger update
- The clickable entry is one square swatch only.
- Solid / Transparent / GRADIENT_V1 full values are not rendered as inline text.
- Full current value is available from the trigger tooltip (`title`); gradient tooltip format is `GRADIENT_V1 / <angle>° <start> → <end>`.
- The compatibility native `input[type=color]` remains hidden.
- Solid / Transparent / Gradient / custom add / RETURN / Security / Joint contracts are unchanged.


## v1.0.12 explicit tooltip update
- The compact square trigger keeps the value text out of layout.
- Hover or keyboard focus on the square shows an explicit #040 tooltip containing the full current value. The tooltip is anchored above the ColorPicker root/label side so the pointer does not cover it.
- Solid: `#RRGGBB`, Transparent: `transparent`, Gradient: `GRADIENT_V1 / angle° color → color`.
- The internal value / RETURN contract is unchanged.


## v1.0.13 tooltip unification

- The compact swatch remains the only visible trigger.
- Browser-native `title` tooltip is removed from the trigger.
- #040 renders one explicit tooltip only, directly above the clickable swatch.
- The tooltip combines the open action label and the complete current value, e.g. `カラーピッカーを開く / GRADIENT_V1 / 135° #0DCAF0 → #F8F9FA`.
- Solid / Transparent / Gradient / custom preset / RETURN contracts are unchanged.


## v1.0.15 caller overlay boundary

- Consumerは自分自身のProperty UI / trigger要素だけを所有する。#040の内部DOMをConsumerへ埋め込まない。
- `BoneColorPicker.attachCaller(trigger, bone, options)` は#040のPicker Overlayを`document.body`直下へ独立生成する。
- `trigger click -> #040 INPUT -> Overlay selection -> #040 RETURN` を正式Caller経路とする。
- 選択結果は`onReturn(output)`と`bone-colorpicker:return` CustomEventで返す。RETURNは既存`buildOutput()`と同じCOLORPICKER value contractを使用する。
- Consumerは#040内部DOM / class / native input / panel位置をquerySelectorで操作しない。Consumer専用#040 CSSも不要。
- Overlay位置はtrigger要素のdocument座標を基準にする。既定`bottom-start`、明示`top-start`。viewportのスクロール位置による自動上下反転は行わない。
- `setCallerValue()`でCallerの現在値を再同期できる。同期はRETURNを発火しない。
- 従来`create()` APIは#040単体Preview / API互換のため維持するが、他ComponentのProperty統合には`attachCaller()`を使用する。


## v1.0.15 Caller tooltip runtime contract
- Caller-owned trigger remains free of #040 internal DOM.
- #040 owns a detached tooltip under document.body and anchors it above the caller trigger.
- showValueText controls actual hover/focus visibility.
- Smoke Test must exercise hover/focus show-hide; structure-only checks cannot produce ALL PASS.


## v1.0.18 Consumer property baseline
#040 itself demonstrates the formal Consumer path for color-valued Property UI. Background / Parent colors / Effect color are edited through Consumer-owned square triggers attached with `BoneColorPicker.attachCaller()`. Consumer UI does not use #040 internal DOM or Consumer-specific rules from `bone-colorpicker.css`.

- Background: solid / transparent
- Parent background: solid only
- Parent text color: solid only
- Active Effect color: solid only

This is the baseline for later Bone Flow Components instead of native Consumer color pickers or duplicated palette UI.


## DOC Integration v1.0.22
HTML Functional Class: `bf-colorpicker`. Guide: `DOC-0040` / `TOC-0040`. Runtime remains BoneColorPicker v1.0.18. Shared DOC runtime is not modified.


## DOC live palette display v1.0.22
DOC-0040 sections 6 and 7 use real `bf-colorpicker` Functional Class instances as visual swatches. The visible clickable square itself is filled with the current Solid / Transparent / Gradient value. Solid uses the built-in 31 values directly; Gradient mounts the class and applies Runtime `defaultNamedGradients()` structured values via `setValue()`. Per-card PASS text is not rendered; one 31/31 or 8/8 section result verifies mount/value/render. Shared DOC files are unchanged.


## v1.0.18 #118 Picker Panel OPEN/CLOSE
The actual Picker Panel is mounted as `bf-transition`. #040 owns semantic open/closed state and value responsibility; completed #118 Transition owns only the visual ENTER / EXIT. #118 Runtime v1.0.3 and `bf-transition` v1.0.4 are external dependencies and are not copied by this package.


## v1.0.19 Caller Overlay viewport clamp
#040 owns Caller Overlay positioning. If an explicit `bottom-start` / `top-start` placement would extend the Picker Panel past the horizontal viewport edge, #040 clamps the complete Panel to an 8px horizontal viewport margin using document coordinates. Vertical placement semantics, scroll/resize repositioning, RETURN, Close, and #118 Transition behavior are unchanged. Consumers must not query or modify the Overlay DOM/CSS or calculate `left` / `top` themselves.


## v1.0.20 Picker chip tooltip viewport clamp
Picker chip tooltips are #040-owned body overlays rather than pseudo-elements clipped by the Picker Panel's scroll container. The tooltip is positioned from the actual chip bounding box, clamped to an 8px horizontal viewport margin, and moved below the chip when there is insufficient space above. It repositions on viewport scroll/resize and Picker Panel scroll. Consumers must not position or style this tooltip.


## v1.0.21 edge containment correction
- Caller overlay and chip tooltip remain viewport-clamped.
- Chip tooltip is rendered only as a #040-owned body overlay; the legacy clipped chip pseudo-tooltip is removed.
- The dedicated left/right edge test stays inside its test card and must not create document horizontal scrolling.