@jsvision/ui / ColorPicker

Class: ColorPicker

Documented in: Color picker

Defined in: ui/src/color/color-picker.ts:191

A one-line color picker: a color chip that opens a swatch (plus an optional hex field) in a dropdown anchored to the field.

Example

import { Group, ColorPicker, signal } from '@jsvision/ui';
import type { Color } from '@jsvision/core';

const g = new Group();
const value = signal<Color>('red');

// A picker with the hex field enabled so custom #rrggbb colors are allowed.
const picker = new ColorPicker({ value, allowCustom: true, onChange: (c) => console.log(c) });
picker.layout = { position: 'absolute', rect: { x: 10, y: 0, width: 20, height: 1 } };
g.add(picker);
// Down / Alt+Down / clicking the ▐↓▌ button opens the swatch; Esc or an outside click cancels.

Extends

• Group

Constructors

Constructor

new ColorPicker(opts): ColorPicker

Defined in: ui/src/color/color-picker.ts:211

Parameters

opts

ColorPickerOptions

The two-way value + optional colors/columns/allowCustom/label/nameFor/ onInput/onChange.

Returns

ColorPicker

Overrides

Group.constructor

Properties

allowCustom

protected readonly allowCustom: boolean

Defined in: ui/src/color/color-picker.ts:200

---

background?

optional background?: keyof Theme

Defined in: ui/src/view/group.ts:64

Optional background theme role filled before children compose, so overlap never leaks cells.

Inherited from

Group.background

---

bounds

bounds: Rect

Defined in: ui/src/view/view.ts:65

Parent-relative integer rect; written by the layout pass — read it in draw/hit-testing.

Inherited from

Group.bounds

---

button

protected readonly button: ColorButton

Defined in: ui/src/color/color-picker.ts:205

---

castsShadow

castsShadow: boolean = false

Defined in: ui/src/view/view.ts:78

When true, the renderer paints a drop shadow on the cells just below and to the right of this view, in paint order (a later sibling's shadow falls over an earlier one). Default false. The Desktop sets it per window.

Inherited from

Group.castsShadow

---

centered

centered: boolean = false

Defined in: ui/src/view/view.ts:86

When true, the layout pass recentres this view within its parent after layout — origin = (parent - self) / 2 on both axes. Intended for absolutely-placed views (a modal dialog, a message box) whose size is fixed and whose origin would otherwise be placed by the caller. Default false; Dialog sets it when centered.

Inherited from

Group.centered

---

children

readonly children: View[] = []

Defined in: ui/src/view/group.ts:62

Ordered children; array order is paint order (back-to-front).

Inherited from

Group.children

---

chip

protected readonly chip: ColorChip

Defined in: ui/src/color/color-picker.ts:204

---

colors?

protected readonly optional colors?: readonly Color[]

Defined in: ui/src/color/color-picker.ts:198

---

columns

protected readonly columns: number

Defined in: ui/src/color/color-picker.ts:199

---

focusable

focusable: boolean = true

Defined in: ui/src/color/color-picker.ts:193

The picker itself takes focus (the chip is display-only); Down/Alt+Down opens the dropdown.

Overrides

Group.focusable

---

layout

layout: LayoutProps = {}

Defined in: ui/src/view/view.ts:69

Layout props for this view (direction, size, padding, absolute placement, …).

Inherited from

Group.layout

---

nameFor?

protected readonly optional nameFor?: (c) => string

Defined in: ui/src/color/color-picker.ts:201

Parameters

c

Color

Returns

string

---

onChange?

protected readonly optional onChange?: (c) => void

Defined in: ui/src/color/color-picker.ts:203

Parameters

c

Color

Returns

void

---

onInput?

protected readonly optional onInput?: (c) => void

Defined in: ui/src/color/color-picker.ts:202

Parameters

c

Color

Returns

void

---

postProcess

postProcess: boolean = false

Defined in: ui/src/view/view.ts:98

Take part in the post-process sweep (after the focused view sees the event).

Inherited from

Group.postProcess

---

preProcess

preProcess: boolean = false

Defined in: ui/src/view/view.ts:96

Take part in the pre-process sweep (root→down, before the focused view sees the event).

Inherited from

Group.preProcess

---

state

readonly state: ViewState

Defined in: ui/src/view/view.ts:67

Draw-against flags. The object reference is fixed; individual fields mutate (e.g. focused).

Inherited from

Group.state

---

value

readonly value: Signal<Color>

Defined in: ui/src/color/color-picker.ts:196

Two-way selected color.

Methods

accelerators()

accelerators(): readonly string[]

Defined in: ui/src/view/view.ts:114

The Alt+hotkey accelerator characters (lowercase) this view claims in its focus scope, for duplicate-accelerator detection. The base returns none; accelerator-bearing widgets (Button/Label/CheckGroup/RadioGroup) override it to report their ~X~ hotkey(s).

Returns

readonly string[]

The claimed accelerator chars, or an empty list when the view claims none.

Inherited from

Group.accelerators

---

add()

add(child): void

Defined in: ui/src/view/group.ts:88

Add a child, appending it on top (later in the array draws in front). If this group is already mounted, the child mounts immediately — its scope nested under this group's — and a reflow is scheduled for the new layout; otherwise the child mounts when this group itself mounts.

Parameters

child

View

The view to append.

Returns

void

Inherited from

Group.add

---

addDynamic()

addDynamic(build): void

Defined in: ui/src/view/group.ts:135

Add children reactively from a Show/For accessor, so the set of children updates itself as signals change. When the group is mounted, an effect reads the accessor, mounts any newly produced views, unmounts any that disappeared (firing their onCleanup), and schedules a reflow on change. Pass a factory that builds the combinator inside itself, not an already-built accessor — this lets the group own and dispose the combinator's reactive nodes on unmount.

Parameters

build

DynamicBuilder

A factory that constructs the combinator, e.g. () => Show(cond, then) or () => For(each, key, render).

Returns

void

Example

import { Group, signal, Show } from '@jsvision/ui';

const open = signal(false);
const group = new Group();
group.addDynamic(() => Show(() => open(), () => new Panel())); // Panel appears when `open` is true

Inherited from

Group.addDynamic

---

bind()

bind<T>(reader, apply?, opts?): void

Defined in: ui/src/view/view.ts:228

Bind a reactive value to a redraw. Creates an effect (owned by this view's scope) that reads reader() — subscribing to whatever signals it touches — runs the optional apply(value), then requests a frame: a repaint by default, or a reflow when { relayout: true }. It re-runs automatically whenever those signals change, and is disposed when the view unmounts.

Call it from onMount, not the constructor — the view's scope only exists once mounted, so a pre-mount bind throws rather than silently dropping the binding.

Type Parameters

T

T

Parameters

reader

() => T

Reads the reactive source; the signals it reads become dependencies.

apply?

(v) => void

Optional: apply the read value to the widget (e.g. store it in a field).

opts?

Pass { relayout: true } when the change affects layout, so it reflows instead of just repainting.

relayout?

boolean

Returns

void

Example

import { signal } from '@jsvision/ui';

const count = signal(0);
// `status` is a View whose draw() reads count():
status.onMount(() => {
  status.bind(() => count()); // repaint the status line whenever `count` changes
});

Inherited from

Group.bind

---

derived()

protected derived<T>(fn): () => T

Defined in: ui/src/view/view.ts:261

Create a stable derived accessor owned by this view's scope. The returned () => T keeps the same identity for the life of the view, so it is safe to build in the constructor and hand to child views before this view mounts. The backing computed is created lazily under the view's own scope, so it is always owned and disposed at unmount — unlike a bare computed() in the constructor, which would run before any scope exists, leak, and warn.

Reads behave sensibly across the lifecycle:

• Before mount: evaluates fn() directly (correct current value, nothing persisted). Good for a pre-mount natural-size measure.
• After mount: builds and memoizes a computed(fn) under the view's scope.
• After an unmount→remount: the memo is keyed to the scope it was built under, so a remounted view (which gets a fresh scope) re-derives under the new scope instead of returning the previous mount's disposed, now-frozen computed — keeping a Show/For-remounted widget reactive.

Type Parameters

T

T

Parameters

fn

() => T

The derivation (pure; the signals it reads become the computed's dependencies).

Returns

A stable accessor; call it to read the derived value.

() => T

Inherited from

Group.derived

---

desiredCaret()

desiredCaret(): Point | null

Defined in: ui/src/view/view.ts:192

Where this view wants the hardware text cursor, in view-local cells, or null for no cursor (the default — most views never show one). A focused text input overrides this to place the caret at the edit position; the event loop reads it after each frame, converts it to an absolute cell, and moves the terminal cursor there.

Returns

Point | null

The view-local caret point (0-based, relative to this view's origin), or null.

Inherited from

Group.desiredCaret

---

draw()

draw(ctx): void

Defined in: ui/src/view/group.ts:75

Fill the background role (if set) across the group rect; children are composed by the render root.

Parameters

ctx

DrawContext

Returns

void

Inherited from

Group.draw

---

focusSignal()

focusSignal(): Signal<void>

Defined in: ui/src/view/view.ts:136

Subscribe to this view's focus changes. Reading the returned signal inside a bind/effect re-runs that effect whenever this view gains or loses focus — including from another view (e.g. a Label repainting when the control it labels is focused). The signal notifies on every poke even without a value change. Lazy: the backing signal is created on first call.

Returns

Signal<void>

A signal that ticks whenever this view gains or loses focus.

Example

// Inside a widget's onMount, repaint whenever `other` view's focus changes:
this.onMount(() => this.bind(() => other.focusSignal()()));

Inherited from

Group.focusSignal

---

invalidate()

invalidate(): void

Defined in: ui/src/view/view.ts:197

Request a repaint of this view. A no-op before the view is mounted (the first frame paints everything).

Returns

void

Inherited from

Group.invalidate

---

invalidateLayout()

invalidateLayout(): void

Defined in: ui/src/view/view.ts:202

Request a reflow (re-run layout, then repaint). Use this when a change affects size/position, not just pixels.

Returns

void

Inherited from

Group.invalidateLayout

---

measure()?

optional measure(available): Size2D

Defined in: ui/src/view/view.ts:71

Optional intrinsic-size hook for auto sizing — return the size this view wants for available.

Parameters

available

Size2D

Returns

Size2D

Inherited from

Group.measure

---

onCleanup()

onCleanup(fn): void

Defined in: ui/src/view/view.ts:298

Register a teardown callback that runs once when this view unmounts. Requires a mounted view — so call it from within onMount. Use it to release anything the view acquired (a timer, an external subscription).

Parameters

fn

() => void

The teardown callback.

Returns

void

Inherited from

Group.onCleanup

---

onEvent()

onEvent(ev): void

Defined in: ui/src/color/color-picker.ts:234

Open on Down / Alt+Down while the picker is focused (the chip is display-only; the picker itself takes focus). A mouse-down on the trailing button opens via ColorButton.

Parameters

ev

DispatchEvent

The dispatch envelope.

Returns

void

Overrides

Group.onEvent

---

onMount()

onMount(fn): void

Defined in: ui/src/view/view.ts:283

Register a callback to run once when the view becomes live (after its first layout gives it bounds). This is where to call bind, since the view's reactive scope exists by then. Registering after the view is already live runs the callback immediately.

Parameters

fn

() => void

Post-mount setup.

Returns

void

Inherited from

Group.onMount

---

open()

protected open(ev): void

Defined in: ui/src/color/color-picker.ts:249

Focus the picker, then open the anchored popup hosting a ColorSwatch (+ hex Input) bound to the shared value. The swatch's onChange (commit) fires the picker's onChange and closes the popup (the value is already set). A no-op with no overlay host (headless).

Parameters

ev

DispatchEvent

The dispatch envelope (source of the popup host + focus seam).

Returns

void

---

remove()

remove(child): void

Defined in: ui/src/view/group.ts:104

Remove a child: dispose its scope (recursively disposing its descendants and running their onCleanup), detach it, and schedule a reflow. Removing a non-child (or removing twice) is a safe no-op.

Parameters

child

View

The view to remove.

Returns

void

Inherited from

Group.remove

---

selectByClick()?

optional selectByClick(): void

Defined in: ui/src/view/view.ts:182

Optional "select + raise on click" hook. Left undefined on the base, so a plain view is not a select/raise target. A container that owns z-order (a Window) overrides it to select and raise itself. The hit-test invokes the first ancestor that defines this — before delivering the mouse-down — so a click always raises the window even if the interior also consumes the click.

Returns

void

Inherited from

Group.selectByClick

---

wireHexBind()

protected wireHexBind(hex, hexText): void

Defined in: ui/src/color/color-picker.ts:300

Wire the two-way binding between value and the hex field's text. value → text serializes the color to a normalized #rrggbb; text → value parses a complete valid hex and updates value only when its RGB actually differs. Each direction reads only the other signal, so there is no feedback loop, and the RGB-equality guard keeps a named color (e.g. 'red') from being rewritten to its #aa0000 form when the popup opens.

Parameters

hex

Input

hexText

Signal<string>

Returns

void