@jsvision/ui / ScrollBar

Class: ScrollBar

Documented in: Scroll Bar

Defined in: ui/src/scroll/scroll-bar.ts:67

A scroll bar: arrows + a page track + a proportional thumb, driven by mouse (see the module docs).

Example

import { ScrollBar, Group, createEventLoop, signal, at } from '@jsvision/ui';
import { resolveCapabilities } from '@jsvision/core';

const caps = resolveCapabilities({ env: {}, platform: 'linux' }).profile;
const pos = signal(0);
const bar = new ScrollBar({ value: pos, min: 0, max: 100, orientation: 'vertical' });

const root = new Group();
root.add(at(bar, 0, 0, 1, 8));
const loop = createEventLoop({ width: 1, height: 8 }, { caps });
loop.mount(root);
pos.set(50); // scroll externally — the thumb re-renders halfway down

Extends

• View

Constructors

Constructor

new ScrollBar(opts): ScrollBar

Defined in: ui/src/scroll/scroll-bar.ts:86

Parameters

opts

ScrollBarOptions

value (two-way signal) + optional min/max/pageStep/arrowStep/orientation.

Returns

ScrollBar

Overrides

View.constructor

Properties

arrowStepVal

protected arrowStepVal: number

Defined in: ui/src/scroll/scroll-bar.ts:78

Arrow-click step (mutable — an owner viewer re-wires it via setRange).

---

bounds

bounds: Rect

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

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:97

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:105

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

---

dragging

protected dragging: boolean = false

Defined in: ui/src/scroll/scroll-bar.ts:81

True while a thumb-drag gesture holds the pointer capture.

---

focusable

focusable: boolean = false

Defined in: ui/src/scroll/scroll-bar.ts:68

Whether this view can receive keyboard focus. Effective focusability also requires the view to be visible and enabled with no hidden/disabled ancestor. Default false; the focus manager drives the state.focused flag.

Overrides

View.focusable

---

grabsFocus

grabsFocus: boolean = true

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

Whether a mouse-down that hits this view moves keyboard focus to it. Default true — the usual click-to-focus. Set false for a control that should act on a click without stealing focus from whatever is focused (e.g. a dialog Cancel button, or a toolbar/stepper button): the click still dispatches, but the previously-focused view keeps focus, so it never fires a focus-leave side effect such as a field's blur-validation. Independent of focusable — a grabsFocus: false view can still be reached by Tab and activated by Space.

Inherited from

View.grabsFocus

---

layout

readonly layout: Readonly<LayoutProps> = {}

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

Layout props for this view (direction, size, padding, absolute placement, …) — read-only.

Change them with setLayout, which is the only writer. The field and every prop on it are closed, so neither view.layout = {…} nor view.layout.rect = {…} compiles, and neither does editing a solved rect a field at a time (view.layout.rect.x = 5). That is deliberate: a wholesale assignment silently drops every prop it omits and never reflows, and an in-place prop write reflows only if you remember to ask.

Read it freely — this is where a view's solved intent lives, and layout.rect is how an absolutely-placed view reports where it was put.

Inherited from

View.layout

---

max

protected max: number

Defined in: ui/src/scroll/scroll-bar.ts:74

Range maximum (mutable — see setRange).

---

min

protected min: number

Defined in: ui/src/scroll/scroll-bar.ts:72

Range minimum (mutable — an owner Scroller/ListView re-limits via setRange).

---

pageStepOpt?

protected optional pageStepOpt?: number

Defined in: ui/src/scroll/scroll-bar.ts:76

Explicit page step, or undefined for the axis-length default (mutable via setRange).

---

postProcess

postProcess: boolean = false

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

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

Inherited from

View.postProcess

---

preProcess

preProcess: boolean = false

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

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

Inherited from

View.preProcess

---

state

readonly state: ViewState

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

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

Writing visible or disabled changes only what the next paint would draw — it does not ask for that paint. Follow such a write with invalidate (or invalidateLayout, which a visibility flip needs, since layout omits hidden views). A development build warns when a write goes unaccounted for.

Inherited from

View.state

---

value

protected readonly value: Signal<number>

Defined in: ui/src/scroll/scroll-bar.ts:70

The two-way bound position (source of truth).

---

vertical

protected readonly vertical: boolean

Defined in: ui/src/scroll/scroll-bar.ts:79

Methods

accelerators()

accelerators(): readonly string[]

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

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

View.accelerators

---

arrowStep()

arrowStep(): number

Defined in: ui/src/scroll/scroll-bar.ts:184

The effective arrow-click step; the wheel steps 3× this.

Returns

number

---

axisLen()

protected axisLen(): number

Defined in: ui/src/scroll/scroll-bar.ts:150

The drawn/measured long-axis length in cells (height when vertical, else width).

Returns

number

---

bind()

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

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

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 { View, signal, type DrawContext } from '@jsvision/ui';

const count = signal(0);

class StatusLine extends View {
  draw(ctx: DrawContext): void {
    ctx.text(0, 0, `${count()} pending`, ctx.color('statusBar'));
  }
}

const status = new StatusLine();
// In onMount, not the constructor: bind() needs the view's scope, which only exists once mounted.
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:359

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:239

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/scroll/scroll-bar.ts:194

Paint the bar: an arrow at each end in the scrollBarControls role, a ▒ track (or a full ▓ fill when disabled) in scrollBarPage, and the thumb in scrollBarControls at its current cell.

Parameters

ctx

DrawContext

The clipped, view-local paint context.

Returns

void

Overrides

View.draw

---

focusSignal()

focusSignal(): Signal<void>

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

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

import { View, Button, type DrawContext } from '@jsvision/ui';

// A caption that highlights while the control it labels holds focus.
class Caption extends View {
  constructor(
    private readonly text: string,
    private readonly target: View,
  ) {
    super();
    // Reading the target's focus signal inside bind() ties this view's repaint to the target's
    // focus flips — a view can observe focus it does not own.
    this.onMount(() => this.bind(() => this.target.focusSignal()()));
  }

  draw(ctx: DrawContext): void {
    ctx.text(0, 0, this.text, ctx.color(this.target.state.focused ? 'labelSelected' : 'label'));
  }
}

const ok = new Button('~O~K');
const caption = new Caption('Confirm:', ok);

Inherited from

View.focusSignal

---

getPos()

protected getPos(len): number

Defined in: ui/src/scroll/scroll-bar.ts:171

The thumb cell along the axis, in [1, getSize()-2] — the position mapped proportionally from value within [min, max] and pinned between the two end arrows.

Parameters

len

number

The long-axis length in cells.

Returns

number

The 0-based thumb index.

---

getSize()

protected getSize(len): number

Defined in: ui/src/scroll/scroll-bar.ts:155

The effective bar length, never below 3 (an arrow at each end plus at least one track/thumb cell).

Parameters

len

number

Returns

number

---

handleDown()

protected handleDown(ev, mark): void

Defined in: ui/src/scroll/scroll-bar.ts:249

Mouse-down: on the thumb ⇒ start a captured drag; on an end arrow ⇒ step once; on the track ⇒ jump the thumb to the clicked position and enter the same captured drag, so the pointer keeps driving it.

Parameters

ev

DispatchEvent

mark

number

Returns

void

---

handleDrag()

protected handleDrag(ev, mark): void

Defined in: ui/src/scroll/scroll-bar.ts:267

Captured drag: map the axis position back to a proportional value.

Parameters

ev

DispatchEvent

mark

number

Returns

void

---

handleUp()

protected handleUp(ev): void

Defined in: ui/src/scroll/scroll-bar.ts:282

Mouse-up: end a drag + release the capture.

Parameters

ev

DispatchEvent

Returns

void

---

invalidate()

invalidate(): void

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

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:250

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

---

jumpTo()

protected jumpTo(mark, s): void

Defined in: ui/src/scroll/scroll-bar.ts:274

Map an axis position mark to a proportional value, clamped between the two end arrows.

Parameters

mark

number

s

number

Returns

void

---

measure()?

optional measure(available): Size2D

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

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:396

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/scroll/scroll-bar.ts:224

Route mouse gestures (the bar owns no keys). Arrow/page click steps once; a thumb click captures the pointer and maps subsequent moves to value; wheel steps 3·arrowStep.

Parameters

ev

DispatchEvent

The dispatch envelope (carries local + the setCapture/releaseCapture seams).

Returns

void

Overrides

View.onEvent

---

onMount()

onMount(fn): void

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

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

---

pageStep()

pageStep(): number

Defined in: ui/src/scroll/scroll-bar.ts:179

The effective page step (the configured pageStep, else the axis length − 1).

Returns

number

---

partCode()

protected partCode(mark, pos, s): number

Defined in: ui/src/scroll/scroll-bar.ts:297

Classify a clicked cell into a part code (start/end arrow, page-back/-forward, or the thumb). Vertical parts add 4 so the same code space distinguishes the two orientations.

Parameters

mark

number

The along-axis click cell.

pos

number

The current thumb cell.

s

number

The last cell index (getSize()-1).

Returns

number

---

put()

protected put(ctx, i, char, style): void

Defined in: ui/src/scroll/scroll-bar.ts:213

Write one glyph at axis index i (col 0 / row 0 on the cross axis).

Parameters

ctx

DrawContext

i

number

char

string

style

Style

Returns

void

---

readValue()

protected readValue(): number

Defined in: ui/src/scroll/scroll-bar.ts:160

The current position clamped into [min,max] (a stray owner write can't index out of range).

Returns

number

---

scrollStep()

protected scrollStep(part): number

Defined in: ui/src/scroll/scroll-bar.ts:308

The signed step for a part code: bit 1 selects page vs arrow step, bit 0 selects forward vs back.

Parameters

part

number

Returns

number

---

selectByClick()?

optional selectByClick(): void

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

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

---

setLayout()

setLayout(patch): void

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

Change some of this view's layout props and request a reflow — the only way to write layout. Props the patch does not name are kept, and the reflow happens for you.

The merge is shallow, deliberately: size and rect are replaced whole rather than merged field-by-field. That is what makes a variant swap correct — going from {kind:'fixed',cells:1} to {kind:'fr',weight:1} must not leave a stale cells behind. The cost is that per-side padding cannot be patched one side at a time; pass the whole padding value.

Two behaviours worth knowing:

• An explicit undefined resets that prop to its layout default. setLayout({ size: undefined }) makes the view auto-sized again, and setLayout({ position: 'flow' }) puts an absolutely-placed view back in the flow (its now-unused rect is simply ignored).
• Do not call it in a constructor of a class that subclasses may extend. A base constructor body runs before a subclass's override readonly layout = {…} field initializer, and that initializer installs a fresh object, so the call would be erased. Call it after construction, or from onMount.

Reflowing an unmounted view is a no-op, so calling it before mount is safe.

Parameters

patch

Partial<LayoutProps>

The layout props to change; anything omitted is preserved.

Returns

void

Example

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

const panel = new Group();
panel.setLayout({ direction: 'col', padding: 1 });
// Later — `direction` and `padding` survive; once `panel` is mounted this also reflows:
panel.setLayout({ size: { kind: 'fr', weight: 1 } });

Inherited from

View.setLayout

---

setRange()

setRange(min, max, pageStep?, arrowStep?): void

Defined in: ui/src/scroll/scroll-bar.ts:129

Re-limit the bar at runtime — an owning Scroller/ListView calls this when its viewport or content extent changes. The bound value is not written here; it is clamped into the new range on read, so a shrunk range never over-scrolls or throws.

A call that actually changes the range repaints the bar, so a range that moves while the position stays put still reaches the screen — a list whose items arrive asynchronously, or a filter that narrows the item count with the offset still at the top. A call that changes nothing repaints nothing, which is what makes it safe for an owner to re-limit from inside its own draw().

Parameters

min

number

New range minimum.

max

number

New range maximum (raised to min if smaller).

pageStep?

number

New page step, or undefined to keep the axis-length default.

arrowStep?

number

New arrow step, or undefined to keep the current one. A multi-column list wires this to its row count so an arrow-click jumps a whole column; a single-column owner leaves it at 1.

Returns

void

Example

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

const top = signal(0);
// A list whose rows arrive asynchronously: the bar mounts disabled, because nothing overflows yet.
const bar = new ScrollBar({ value: top, min: 0, max: 0 });

// When they land it goes live on its own — `top` is still 0, so the value bind never fires.
const loadRows = async (): Promise<string[]> => ['alpha', 'beta', 'gamma'];
void loadRows().then((rows) => bar.setRange(0, Math.max(0, rows.length - 2)));

---

setValue()

protected setValue(next): void

Defined in: ui/src/scroll/scroll-bar.ts:314

Write the bound position, clamped to [min,max].

Parameters

next

number

Returns

void