# #040 ColorPicker Guide

## 1. Overview
ColorPicker is the shared Bone Flow component responsible for color selection. It handles solid colors, transparency, and safe structured two-stop linear gradients. Other UI components should delegate color selection to #040 instead of duplicating native color inputs or custom palettes.

The formal route is UI-040 / DOC-0040 / TOC-0040. The single normal-use HTML Functional Class is `bf-colorpicker`. The Public API remains a separate advanced interface.

## 2. Supported values
- Solid: six-digit `#RRGGBB`, normalized to uppercase.
- Transparent: exact string `transparent`.
- Gradient: safe structured `GRADIENT_V1` with `kind=gradient`, `type=linear`, angle from 0 inclusive to 360 exclusive, and exactly two ordered stops.

Short hex, alpha hex, CSS named colors, raw CSS gradient strings, ASCII-control text, and unsafe accessor-backed objects are rejected.

## 3. HTML Functional Class
Minimum HTML:
```html
<div class="bf-colorpicker" data-value="#0D6EFD"></div>
```

Transparent initial value:
```html
<div class="bf-colorpicker" data-value="transparent"></div>
```

Configured example:
```html
<div
  class="bf-colorpicker"
  data-bone-id="profile-accent"
  data-value="#7C3AED"
  data-label="Accent color"
  data-locale="en"
  data-allowed-kinds="solid,transparent"
  data-theme="dark"
  data-width="280"
  data-height="48"
  data-position="top-left"
  data-transition="fade"
  data-direction="down"
  data-speed="normal"
  data-respect-reduced-motion="true"
  data-show-value-text="true">
</div>
```

`namedColors`, `namedGradients`, and a structured gradient initial value are not encoded as HTML JSON attributes. Use the Property Editor or the `BoneColorPicker` Public API for those structured settings.

## 4. Supported HTML attributes
`data-value`, `data-bone-id`, `data-disabled`, `data-change-commit`, `data-show-value-text`, `data-locale`, `data-allowed-kinds`, `data-label-visible`, `data-label`, `data-label-gap`, `data-label-font-size`, `data-inherit-parent`, `data-width`, `data-height`, `data-position`, `data-fit`, `data-parent-fit`, `data-input-align`, `data-theme`, `data-background-color`, `data-appearance`, `data-active-border-effect`, `data-active-effect-color`, `data-active-effect-direction`, `data-active-effect-speed`, `data-transition`, `data-direction`, `data-speed`, and `data-respect-reduced-motion` map to actual Runtime options. The four transition attributes configure the completed #118 Transition used only for Picker Panel ENTER / EXIT.

## 5. Runtime defaults
`disabled=false`, `changeCommit=true`, `showValueText=true`, `locale=ja`, `allowedKinds=[solid,transparent,gradient]`, 31 built-in named colors, 8 built-in gradients, `labelVisible=true`, `label=ColorPicker`, `labelGap=8`, `labelFontSize=14`, `inheritParent=false`, `width=280`, `height=48`, `position=top-left`, `fit=false`, `parentFit=false`, `inputAlign=auto`, `theme=default`, `backgroundColor=theme`, `appearance=normal`, `activeBorderEffect=normal`, `activeEffectColor=#35F4FF`, `activeEffectDirection=clockwise`, `activeEffectSpeed=normal`.

## 6. Built-in Solid 31 colors
The following is not a text-only list. It mounts 31 real `bf-colorpicker` HTML Functional Class hosts. Each swatch is rendered by the real `BoneColorPicker v1.0.18` Runtime, and the same section reports whether all 31 hosts mounted with the expected values.

[[BF-COLORPICKER-SOLID-PALETTE:en]]

The Runtime contains 31 solid presets: Primary, Secondary, Success, Danger, Warning, Info, Light, Dark, Blue, Indigo, Purple, Pink, Red, Orange, Yellow, Green, Teal, Cyan, Black, White, Gray, Gray Dark, and Gray 100 through Gray 900.

## 7. Built-in Gradient 8 presets
The following mounts eight real `bf-colorpicker` hosts. Gradient values are not pushed into an HTML attribute as CSS strings; after mount, the sample applies the formal `GRADIENT_V1` values returned by `defaultNamedGradients()` through `setValue()`. The section reports mount/value/gradient-render results for all eight presets.

[[BF-COLORPICKER-GRADIENT-PALETTE:en]]

The 8 gradient presets are Ocean, Sunset, Forest, Aurora, Violet, Fire, Ice, and Monochrome. Gradient CSS is generated only from a normalized structured value.

## 8. Property Editor
The Property Editor controls value kind, disabled state, change commit behavior, value text, locale, allowed kinds, label, size, parent inheritance, Position, FIT, Theme, Background, Appearance, Active Effect, Named Color / Gradient, and the #118 settings used for Picker Panel OPEN / CLOSE.

Color properties owned by other components must use the #040 Caller instead of substituting a native color picker.

## 9. #118 Transition
#040 uses the completed **#118 Transition v1.0.12 / Runtime v1.0.3** only for the Picker Panel visual **ENTER / EXIT during OPEN / CLOSE**. Color validation, the 31 solids, Transparent, gradients, chip selection, Caller, and RETURN remain #040 responsibilities.

#040 owns the semantic `open / closed / hidden` state and the final `hidden` state. #118 owns only the visual interpolation of the Picker Panel. CLOSE caused by outside click, Escape, or RETURN uses the same #118 EXIT path.

### Where #118 is used and the responsibility boundary
The actual Picker Panel is a real `bf-transition` host. #040 owns semantic open/closed state and the final hidden state; #118 owns visual ENTER / EXIT only. `openPicker` / `closePicker`, Caller trigger close, outside click, Escape, and RETURN use the same #118 path. #040 exposes the formal #118 visual settings for the Picker Panel: Transition (23), Direction (4), Speed (3), and Respect Reduced Motion (boolean). The same values can be supplied on `bf-colorpicker` with `data-transition`, `data-direction`, `data-speed`, and `data-respect-reduced-motion`. The three relation fields remain internal to #040.

### Configure #118 through `bf-colorpicker`
When #040 is used through its HTML Functional Class, put the four #118 visual settings directly on the `bf-colorpicker` host. The consumer does not create a separate #118 element.

```html
<div
  id="profile-color"
  class="bf-colorpicker"
  data-value="#0D6EFD"
  data-transition="slide-fade"
  data-direction="left"
  data-speed="fast"
  data-respect-reduced-motion="true">
</div>
```

The #040 Runtime creates the internal relation fields and mounts the real Picker Panel as `bf-transition`. After changing these values in Property Editor, press **Apply Property** to update the real #118 Picker Panel instance.

### `data-transition` — all 23 formal values from #118 v1.0.12
The following list comes from the completed #118 Transition v1.0.12 / Runtime v1.0.3 `BoneTransition.TRANSITIONS` contract. **Use the code value at the left in `data-transition`.** Every formal value includes its name, behavior, Direction usage, and intended use.

- `fade` — **Fade In / Fade Out / フェードイン / フェードアウト** — Interpolates visibility using opacity only. Direction: not used. Use: General visibility changes. ENTER: From transparent to visible. EXIT: From visible to transparent.
- `slide` — **Slide In / Slide Out / スライドイン / スライドアウト** — Moves the target in or out from the selected direction. Direction: used (`up / down / left / right`). Use: Menus and panels. ENTER: From the selected direction to rest. EXIT: From rest toward the selected direction.
- `slide-fade` — **Slide + Fade / スライド + フェード** — Combines translation and opacity. Direction: used (`up / down / left / right`). Use: Lightweight panel changes. ENTER: Moves in while fading in. EXIT: Moves out while fading out.
- `scale` — **Scale In / Scale Out / スケールイン / スケールアウト** — Interpolates state using scale. Direction: not used. Use: Cards and popups. ENTER: From smaller to normal size. EXIT: From normal to smaller size.
- `scale-fade` — **Scale + Fade / スケール + フェード** — Combines scale and opacity. Direction: not used. Use: Dialogs and auxiliary UI. ENTER: Scales up while fading in. EXIT: Scales down while fading out.
- `zoom` — **Zoom In / Zoom Out / ズームイン / ズームアウト** — A stronger depth-like scale transition. Direction: not used. Use: Emphasized changes. ENTER: Zooms forward from a small image. EXIT: Zooms away to a small image.
- `zoom-fade` — **Zoom + Fade / ズーム + フェード** — Combines zoom and opacity. Direction: not used. Use: Modals and focal elements. ENTER: Zooms in while appearing. EXIT: Zooms out while disappearing.
- `dissolve` — **Dissolve / ディゾルブ** — Softly dissolves with opacity and blur. Direction: not used. Use: Content replacement. ENTER: From blurred transparent to clear. EXIT: Blurs while fading away.
- `wipe` — **Wipe In / Wipe Out / ワイプイン / ワイプアウト** — Reveals or hides the surface from a direction. Direction: used (`up / down / left / right`). Use: Section changes. ENTER: Opens the clipping region. EXIT: Closes the clipping region.
- `reveal` — **Reveal / Conceal / リビール / コンシール** — A softer directional reveal/conceal. Direction: used (`up / down / left / right`). Use: Detail regions. ENTER: Gradually reveals directionally. EXIT: Gradually conceals directionally.
- `expand` — **Expand / Collapse / 展開 / 折り畳み** — Expands or collapses along an axis. Direction: used (`up / down / left / right`). Use: Accordions and details. ENTER: Expands from a compressed state. EXIT: Collapses along the axis.
- `drop` — **Drop Down / Pull Up / ドロップダウン / プルアップ** — Drops down or pulls back up. Direction: not used. Use: Menus. ENTER: Drops from above into place. EXIT: Pulls upward and disappears.
- `pop` — **Pop In / Pop Out / ポップイン / ポップアウト** — Scale transition with a brief overshoot. Direction: not used. Use: Notices and lightweight popups. ENTER: Pops in with a small overshoot. EXIT: Briefly expands then shrinks out.
- `flip-x` — **Flip X In / Out / X軸フリップ** — Transitions with X-axis 3D rotation. Direction: not used. Use: Card changes. ENTER: Rotates on X axis into view. EXIT: Rotates out on X axis.
- `flip-y` — **Flip Y In / Out / Y軸フリップ** — Transitions with Y-axis 3D rotation. Direction: not used. Use: Card changes. ENTER: Rotates on Y axis into view. EXIT: Rotates out on Y axis.
- `curtain-horizontal` — **Curtain Horizontal / 左右カーテン開閉** — Opens/closes horizontally like curtains. Direction: not used. Use: Large region changes. ENTER: Opens from center to both sides. EXIT: Closes from sides to center.
- `curtain-vertical` — **Curtain Vertical / 上下カーテン開閉** — Opens/closes vertically like curtains. Direction: not used. Use: Large region changes. ENTER: Opens vertically from center. EXIT: Closes vertically to center.
- `shutter-horizontal` — **Shutter Horizontal / 横シャッター** — Directional horizontal shutter transition. Direction: used (`up / down / left / right`). Use: Panels and images. ENTER: Opens horizontally. EXIT: Closes horizontally.
- `shutter-vertical` — **Shutter Vertical / 縦シャッター** — Directional vertical shutter transition. Direction: used (`up / down / left / right`). Use: Panels and images. ENTER: Opens vertically. EXIT: Closes vertically.
- `fold` — **Fold / Unfold / フォールド / アンフォールド** — Folds or unfolds around an edge. Direction: used (`up / down / left / right`). Use: Side panels. ENTER: Unfolds from an edge. EXIT: Folds toward an edge.
- `rise` — **Rise / Sink / 浮上 / 沈下** — Rises from below and sinks downward. Direction: not used. Use: Cards and notices. ENTER: Rises from below into view. EXIT: Sinks down while disappearing.
- `teleport-up` — **Teleport Up / 上昇ワープ（ルーラ風）** — Narrows, stretches and accelerates upward; ENTER reverses the motion. Direction: not used. Use: Teleport-like exits, screen departure, special menu storage. ENTER: Returns from a thin image above to the normal position. EXIT: Accelerates upward, narrows, stretches vertically and vanishes.
- `iris` — **Iris Open / Close / アイリス開閉** — Opens or closes a circular aperture. Direction: not used. Use: Focus changes. ENTER: Expands from a small center circle. EXIT: Contracts to a small center circle.

### Direction / Speed / Reduced Motion values
- `data-direction="up"` = Up
- `data-direction="down"` = Down
- `data-direction="left"` = Left
- `data-direction="right"` = Right
- `data-speed="slow"` = Slow
- `data-speed="normal"` = Normal (#040 default)
- `data-speed="fast"` = Fast
- `data-respect-reduced-motion="true"` = respect the OS reduced-motion preference (#040 default)
- `data-respect-reduced-motion="false"` = use the selected Transition regardless of that preference

When a Transition is marked as not using Direction, the direction value may remain configured but is not used by the #118 motion plan.
### Property Editor mapping
The **Picker OPEN / CLOSE - #118 Transition** group exposes four settings:

- **Transition**: one of the 23 formal Transition values.
- **Direction**: Up / Down / Left / Right. Formal values are `up / down / left / right`.
- **Speed**: Slow / Normal / Fast. Formal values are `slow / normal / fast`.
- **Respect Reduced Motion**: ON / OFF. HTML values are `true / false`.

After changing these settings, press **Apply Property**. The actual Picker Panel `bf-transition` instance receives the new values. The relation fields `data-transition-ui-no`, `data-target-ui-no`, and `data-target-part` are generated internally by #040 and are not consumer settings.

## 10. Position
Supported values are `top-left`, `top-center`, `top-right`, `middle-left`, `center`, `middle-right`, `bottom-left`, `bottom-center`, and `bottom-right`.

## 11. Caller / RETURN
A consumer owns only its color trigger. #040 owns the picker overlay and RETURN flow.

```html
<button id="effect-color" type="button" aria-label="Effect color"></button>
<script>
const trigger = document.getElementById("effect-color");
BoneColorPicker.attachCaller(
  trigger,
  { id: "effect-color-picker", type: "COLORPICKER", value: "#35F4FF" },
  {
    locale: "en",
    allowedKinds: ["solid"],
    onReturn(output) {
      trigger.dataset.value = output.value;
    }
  }
);
</script>
```

Consumers must not query or manipulate #040 internal overlay, chip, native input, or panel DOM.

## 12. allowedKinds
Use `solid` for text/effect/shadow/glow colors, `solid,transparent` for backgrounds when transparency is valid, and add `gradient` only for properties that formally accept gradients.


## 13. Security
Untrusted input is inspected through own data-property descriptors without executing getters. Valid `#RRGGBB`, `transparent`, and safe `GRADIENT_V1` values are accepted. Invalid or unsafe values are blocked and the previously committed value is preserved.

## 14. Joint / WAIT / FIFO / BLOCKED
#040 uses #002 Bone Joint createDeliveryChannel capability for delivery and accepts compatible later Joint versions. WAIT keeps the connection while queuing output, READY resumes FIFO delivery, and BLOCKED keeps the connection while preventing delivery.

## 15. Smoke / Validation / Completion
Smoke and Validation remain NOT RUN until explicitly executed. Completion requires passing Runtime QA plus the required WAIT/BLOCK visual confirmation. User-localhost confirmation is required before Completed / Specification Frozen status.

## 16. Cumulative Regression usage
Use the **Cumulative Regression** action in the #040 header to open `bone-development-order.html`. #040 is evaluated through four rows:

- `#040 BoneColorPicker bundle`: verifies the real `BoneColorPicker v1.0.18`, `BoneColorPickerFunctionalClass`, DOC-0040, and the frozen #118 dependency. It also verifies that `#html-functional-class-live.bf-colorpicker` is actually mounted, `BoneColorPickerFunctionalClass.getInstance()` returns the real Runtime instance, and the real Picker Panel is mounted as a `bf-transition` host.
- `#040 Smoke Test`: opens a fresh same-origin #040 iframe, requires exactly one `#run-smoke` button, clicks the real button, and waits for the page's actual result.
- `#040 Validation`: requires exactly one `#run-validation` button, clicks it, and waits for the actual Validation result.
- `#040 Runtime 1.0.18`: verifies the Runtime version from the iframe.

### HTML Class settings checked by Cumulative Regression
Regression does not define Transition settings itself. Configure the real #040 test host with `bf-colorpicker` attributes, then Regression verifies the mounted result.

```html
<div
  id="html-functional-class-live"
  class="bf-colorpicker"
  data-value="#0D6EFD"
  data-transition="slide-fade"
  data-direction="left"
  data-speed="fast"
  data-respect-reduced-motion="true">
</div>
```

The bundle gate follows this host through the real BoneColorPicker instance, the real Picker Panel, and the mounted `bf-transition` instance.

The regression gate checks the actual HTML Functional Class path, not only the class-name string:

```text
<div id="html-functional-class-live" class="bf-colorpicker" ...>
  -> BoneColorPickerFunctionalClass mount
  -> real BoneColorPicker instance
  -> real Picker Panel .bf-transition
  -> BoneTransitionFunctionalClass mount
```

If the Functional Class host is not mounted, the Runtime instance is missing, or the Picker Panel is not a real `bf-transition` host, the #040 bundle row fails. Any failing #040 row forces the overall #000 result to fail. Cumulative Regression is a test route, not a #040 dependency relationship.

## 17. Public API
The Public API remains separate from `bf-colorpicker`: `defaults`, `defaultNamedColors`, `defaultNamedGradients`, normalization/validation methods, create/destroy/value/preset methods, Joint output methods, Caller methods, picker open/close methods, and `syncParentStyle`.

## 18. Troubleshooting
If `bf-colorpicker` cannot mount, verify BoneColorPicker v1.0.18 and its existing dependencies are loaded first. If DOC-0040 cannot open, verify the shared DOC loader/guide assets and the installed DOC/TOC registry merge. Do not replace the shared guide with a component-specific modal.

## 19. Version / Status
Runtime: BoneColorPicker v1.0.24. DOC Integration: v1.0.32 Candidate / HTML Functional Class bridge: v1.0.28. Not Completed / not Specification Frozen before user-localhost confirmation.


## 20. Dependency boundary
#040 depends on #001 Core, #002 Joint, #017 Text, #020 Label, #022 Hover Border Effect, and completed #118 Transition Runtime v1.0.3 / `bf-transition` v1.0.4. #040 does not copy or modify #118 assets.


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