JSVision

Appearance

@jsvision/ui / Button

Class: Button ​

Documented in: Button

Defined in: ui/src/controls/button.ts:50

A focusable command button.

Example ​

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

const buttons = new Group();

// A default button that emits a command (handled elsewhere, e.g. by a Dialog or the app).
const ok = new Button('~O~K', { command: 'ok', default: true });
ok.layout = { position: 'absolute', rect: { x: 1, y: 0, width: 10, height: 2 } };
buttons.add(ok);

// A plain button that runs a callback directly.
const count = signal(0);
const add = new Button('~A~dd', { onClick: () => count.set(count() + 1) });
add.layout = { position: 'absolute', rect: { x: 12, y: 0, width: 11, height: 2 } };
buttons.add(add);

Extends ​

Constructors ​

Constructor ​

new Button(text, opts?): Button

Defined in: ui/src/controls/button.ts:75

Parameters ​

text ​

string

The label, optionally marking its hotkey with ~X~ (e.g. '~O~K').

opts? ​

ButtonOptions = {}

command / onClick / default / disabled (see ButtonOptions).

Returns ​

Button

Overrides ​

View.constructor

Properties ​

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 ​

View.bounds

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 ​

View.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 ​

View.centered

clickHandler? ​

protected readonly optional clickHandler?: () => void

Defined in: ui/src/controls/button.ts:63

Click callback fired on activation, if any.

Returns ​

void

command? ​

protected readonly optional command?: string

Defined in: ui/src/controls/button.ts:61

Command emitted on activation, if any.

disabledOpt ​

protected readonly disabledOpt: boolean | (() => boolean)

Defined in: ui/src/controls/button.ts:67

The disabled flag or reactive getter.

focusable ​

focusable: boolean = true

Defined in: ui/src/controls/button.ts:52

Space activates the button while it is focused.

Overrides ​

View.focusable

isDefault ​

protected readonly isDefault: boolean

Defined in: ui/src/controls/button.ts:65

Whether this is the dialog default (also activates on unconsumed Enter).

layout ​

layout: LayoutProps = {}

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

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

Inherited from ​

View.layout

parsed ​

protected readonly parsed: ParsedLabel

Defined in: ui/src/controls/button.ts:59

Parsed hotkey (letter + column) for Alt+hotkey matching.

postProcess ​

postProcess: boolean = true

Defined in: ui/src/controls/button.ts:54

Caught after the focused chain so Alt+hotkey and a default button's Enter are seen dialog-wide.

Overrides ​

View.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 ​

View.preProcess

pressed ​

protected pressed: boolean = false

Defined in: ui/src/controls/button.ts:69

Visual pressed state (mouse-down inside the face, before release).

raw ​

protected readonly raw: string

Defined in: ui/src/controls/button.ts:57

The original tilde-marked label.

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 ​

View.state

Methods ​

accelerators() ​

accelerators(): readonly string[]

Defined in: ui/src/controls/button.ts:99

The button's ~X~ Alt-hotkey char (lowercase), for duplicate-accelerator detection; none if unmarked.

Returns ​

readonly string[]

Overrides ​

View.accelerators

activate() ​

protected activate(ev): void

Defined in: ui/src/controls/button.ts:228

Emit the command (if any) and fire onClick. Only ever called for an enabled button.

Parameters ​

ev ​

DispatchEvent

Returns ​

void

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 ​

ts
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 ​

View.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 ​

View.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 ​

View.desiredCaret

draw() ​

draw(ctx): void

Defined in: ui/src/controls/button.ts:114

Paint the centered label on a raised face with a block-glyph drop shadow down the right column and across the bottom row. A pressed button shifts its face right one cell and hides the shadow.

Parameters ​

ctx ​

DrawContext

The clipped, view-local paint context.

Returns ​

void

Overrides ​

View.draw

drawTitle() ​

protected drawTitle(ctx, row, s, indent, face, accent): void

Defined in: ui/src/controls/button.ts:165

Draw the label centered on row, with the hotkey run accented. There are no [ ] brackets in this rendering.

Parameters ​

ctx ​

DrawContext

The clipped, view-local paint context.

row ​

number

The title row (view-local y).

s ​

number

The last column index (width - 1).

indent ​

number

Left indent — 1 normally, 2 when pressed (the face shifts right).

face ​

Style

The resolved face style for non-hotkey glyphs.

accent ​

Style

The resolved accent style for the hotkey glyph.

Returns ​

void

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 ​

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

Inherited from ​

View.focusSignal

inFace() ​

protected inFace(local): boolean

Defined in: ui/src/controls/button.ts:222

Whether a view-local point lies in the clickable face. Column 0 (the shadow-adjacent edge) is inert, and the last column and last row (the drop shadow) are excluded too.

Parameters ​

local ​

Point | undefined

Returns ​

boolean

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 ​

View.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 ​

View.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 ​

View.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 ​

View.onCleanup

onEvent() ​

onEvent(ev): void

Defined in: ui/src/controls/button.ts:187

Handle activation: a click (press then release inside the face), Space while focused, this button's Alt+hotkey, and (for a default button) an unconsumed Enter. A disabled button is completely inert.

Parameters ​

ev ​

DispatchEvent

The dispatch envelope (carries emit/local during real dispatch).

Returns ​

void

Overrides ​

View.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 ​

View.onMount

resolveDisabled() ​

protected resolveDisabled(): boolean

Defined in: ui/src/controls/button.ts:104

Resolve the disabled flag (evaluating the getter if it is reactive).

Returns ​

boolean

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 ​

View.selectByClick