# Bone Flow #040 ColorPicker Specification v1.0

## Status

- Component: #040 ColorPicker
- Version: 1.0.17
- Status: Development
- Development Order: `000-Development-Order_v1.1.1.md`
- Runtime confirmation: user localhost confirmation required
- Completion: not confirmed

## Responsibility

ColorPicker is an Input UI component for selecting and committing either:

1. a solid color as canonical uppercase `#RRGGBB`,
2. explicit `transparent`, or
3. a safe two-stop linear gradient as a structured value.

The component does not accept raw CSS gradient strings as Bone / IN / OUT values. Gradient CSS is generated only for Preview rendering after structural validation.

Named presets are lightweight selection aids, not a full Palette Manager.

## Solid value contract

```text
id    : caller-defined Bone id
type  : COLORPICKER
value : #RRGGBB
```

Valid lowercase HEX6 is normalized to uppercase.

## Transparent value contract

```text
id    : caller-defined Bone id
type  : COLORPICKER
value : transparent
```

Only the exact allowlisted string `transparent` is accepted. Other CSS named colors remain blocked.

## Gradient value contract

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

Formal restrictions:

- `kind` = `gradient`
- `type` = `linear`
- `angle` = number, `0 <= angle < 360`
- exactly two stops
- stop positions are numeric, 0–100, ascending
- stop colors are strict `#RRGGBB`
- raw `linear-gradient(...)` strings are not accepted
- alpha colors, shorthand HEX, CSS named colors, arbitrary CSS and accessor-backed values are not accepted

## Named solid colors

Built-in solid presets: 31.

Bootstrap 5.3-style Theme / base / gray values are used as the initial solid preset values:

- Theme: Primary / Secondary / Success / Danger / Warning / Info / Light / Dark
- Base: Blue / Indigo / Purple / Pink / Red / Orange / Yellow / Green / Teal / Cyan / Black / White / Gray / Gray Dark
- Gray scale: Gray 100 / 200 / 300 / 400 / 500 / 600 / 700 / 800 / 900

Preset display names support Japanese / English. Examples:

- Cyan / シアン
- Gray / グレー
- Red / 赤
- Blue / 青

Custom named solid colors can be added with:

- Japanese display name
- English display name
- HEX6 value

Display names are metadata. A solid Bone / OUT value remains HEX6.

## Named gradients

Eight built-in safe two-color linear-gradient presets are included:

1. Ocean / オーシャン
2. Sunset / サンセット
3. Forest / フォレスト
4. Aurora / オーロラ
5. Violet / バイオレット
6. Fire / ファイア
7. Ice / アイス
8. Monochrome / モノクローム

Custom named gradients can be added with:

- Japanese display name
- English display name
- start HEX6 color
- end HEX6 color
- angle 0–359

This is not a free-form Gradient Editor. The supported gradient responsibility is limited to safe two-stop linear gradients.

## ColorPicker-specific Property

- `disabled`
- `changeCommit`
- `showValueText`
- `namedColors`
- `namedGradients`

## Shared Input UI Property

- Property Japanese / English
- Label visible / text / gap / font size
- Theme: default / dark / light / neon
- Appearance: normal / flat / borderless
- Background: theme / transparent / #RRGGBB
- width / height
- Parent dependency: ON fills actual parent width / height 100% and inherits parent background / text / border / radius / alignment
- Parent Preview settings: width / height / alignment / background / text color / radius
- 9-position placement in standalone mode
- FIT
- input alignment
- #022 Active Border Effect: normal / neon / spin / cross / blink
- effect color / direction / speed

## Dependencies

- #001 Bone Core v1.0.0
- #002 Bone Joint（createDeliveryChannel capability）
- #017 Bone Text
- #020 Bone Label
- #022 Bone Hover Border Effect v1.0.1
- #118 Bone Transition Runtime v1.0.3 / HTML Functional Class `bf-transition` v1.0.4


## Picker Panel OPEN / CLOSE Transition

The ColorPicker continues to own picker-open / picker-closed semantic state, value selection, Caller/RETURN, and the final `hidden` state. The actual Picker Panel element is also a real `bf-transition` host.

- #118 owns visual ENTER / EXIT only.
- #040 calls #118 `enter()` when the Picker Panel opens and #118 `exit()` when it closes.
- #040 uses #118 Runtime defaults for the internal Picker Panel transition; no new ColorPicker Transition Property is added.
- Outside click, Escape, API close, trigger close, and RETURN all close through the same #118 EXIT path.
- A stale EXIT completion cannot hide a Picker Panel that has already reopened.
- #118 remains an external frozen dependency; #040 does not copy or modify #118 Runtime/Class files.

## Security

Untrusted IN / Security Test is independent from the normal Preview.

Accepted:

- strict `#RRGGBB`
- exact `transparent`
- validated `GRADIENT_V1` structured object

Blocked:

- shorthand HEX
- alpha HEX
- CSS named colors
- raw CSS `linear-gradient(...)` strings
- malformed objects
- unsafe accessor-backed packet / nested values
- ASCII-control-character-containing values

A blocked value does not replace the previous accepted Security Sandbox value or the normal Preview value.

## Joint / OUT

`#002 Bone Joint` is used for formal connection evaluation and OUT Delivery Channel.
The test page includes six explicit connection cases: normal IN, normal OUT, IN Target Field missing, OUT Target Field missing, IN type mismatch, OUT type mismatch.

Output includes:

- componentId
- componentName
- version
- type
- source
- value
- valueKind = `solid`, `transparent`, or `gradient`
- colorFormat = `HEX6`, `TRANSPARENT`, or `GRADIENT_V1`
- Bone `{ id, type: COLORPICKER, value }`
- validation

## WAIT / BLOCKED

WAIT and BLOCKED are tested on a dedicated Delivery Sandbox.
WAIT queues output while Target is not ready and releases it after READY in FIFO order.
BLOCKED keeps the connection while stopping delivery.

## QA

Smoke Test and Validation do not auto-run. Initial state is `NOT RUN`.
Normal Preview, Security Sandbox, QA sandbox and Delivery sandbox are separate.
JSON and Markdown Runtime Report exports are available from the test page.

Package-side QA does not count as user localhost Browser Runtime confirmation.

## Completion

Completion remains unavailable until actual Smoke + Validation ALL PASS and required WAIT / BLOCKED visual confirmations are complete. User localhost confirmation is required before Completed / Specification Frozen.

## Change history


### v1.0.6

- Property named solid / named gradient sections changed to accordions.
- Actual-use Preview gradient value is readable without ellipsis-only clipping.
- Picker chip hover/focus effect strengthened.
- Formal connection normal case restored to combined IN / OUT card; total connection cards are 5.

### v1.0.5

- Rebuilt ColorPicker Preview as an actual-use picker: closed component first, internal picker panel on click.
- Moved preset swatches into the ColorPicker runtime panel instead of always-visible Preview rows.
- Added explicit `transparent` value, checkerboard swatch, Security acceptance, commit / OUT / Joint / WAIT-compatible value contract.
- Picker panel includes 31 solid presets, Transparent, 8 gradients, localized hover names and custom solid / gradient add controls.

### v1.0.4

- Added square solid-color and gradient chips inside ColorPicker Preview.
- Preview chips show only color surfaces by default; localized color names appear on mouseover/focus tooltip.
- Clicking a Preview chip selects and commits that preset to the normal ColorPicker Preview.
- Custom named colors and gradients are added to the Preview chip rows as well.

### v1.0.3

- Added safe two-stop linear-gradient value support.
- Added 8 built-in gradient presets.
- Added custom gradient preset creation with Japanese / English names, start / end colors and angle.
- Added Japanese / English display names to all 31 built-in solid presets.
- Custom named solid colors now support Japanese / English display names.
- Raw CSS gradient strings remain blocked; gradient OUT uses a structured value.

### v1.0.2

- Expanded built-in named solid colors to 31 Bootstrap 5.3-style Theme / Base / Gray values.
- Parent Preview and parent dependency behavior rechecked.


## 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 UI contract

- Actual-use selection trigger MUST be one interactive button.
- The trigger contains a value preview swatch, an optional value text and a non-interactive caret.
- The compatibility native solid input remains available through `getInput()` but MUST be hidden and removed from tab order.
- Overflowing value text MUST use ellipsis visually and expose the complete value through a tooltip (`title`).
- Solid / Transparent / GRADIENT_V1, named presets, custom add, commit, OUT, Security and WAIT/BLOCKED contracts are unchanged.


## 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 MUST be anchored above the ColorPicker root/label side, not directly under the pointer.
- 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 #040-first Consumer color-property correction
- #040 Runtime CSS no longer ships Consumer-owned `.bf-caller-color-trigger` / swatch styling. Consumer trigger styling belongs to the Consumer page/component.
- The #040 formal test-page Property Editor now consumes its own public `attachCaller()` contract for Background, Parent Background, Parent Text Color and Active Effect Color instead of native Consumer `input[type=color]`.
- Background uses `allowedKinds: ["solid", "transparent"]`; Parent Background / Parent Text / Effect Color use `allowedKinds: ["solid"]`.
- Actual RETURN updates the Property value and Preview; Smoke/Validation include observable caller-open, available-kind and RETURN-result checks.
- Validation V19 is no longer an unconditional `true`; initial NOT RUN state is captured from the real QA UI before execution.
- #040 public Caller API/value contract remains unchanged.


## 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 integration
- Picker Panel OPEN/CLOSE now uses completed #118 Transition v1.0.12 assets (Runtime 1.0.3 / `bf-transition` 1.0.4).
- Color/value/Caller/RETURN contracts are unchanged.


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