JSVision

Appearance

@jsvision/files / FileInput

Class: FileInput ​

Defined in: files/src/input/file-input.ts:51

The filename input that mirrors the focused directory entry unless it is itself focused.

Example ​

ts
import { Group, signal } from '@jsvision/ui';
import { FileInput, nodeFileSystem } from '@jsvision/files';
import type { DirEntry } from '@jsvision/files';

const filename = signal('');
const focused = signal<DirEntry | undefined>(undefined);
const field = new FileInput({
  value: filename,          // two-way: reflects and receives the typed name
  focusedEntry: () => focused(),
  wildcard: () => '*.ts',
  sep: nodeFileSystem.sep,
});
field.layout = { position: 'absolute', rect: { x: 0, y: 0, width: 28, height: 1 } };
new Group().add(field);

Extends ​

  • Input

Constructors ​

Constructor ​

new FileInput(opts): FileInput

Defined in: files/src/input/file-input.ts:52

Parameters ​

opts ​

FileInputOptions

Returns ​

FileInput

Overrides ​

Input.constructor

Properties ​

anchor ​

protected anchor: number

Defined in: ui/dist/controls/input.d.ts:72

The fixed end of the selection while extending it with Shift.

Inherited from ​

Input.anchor

bounds ​

bounds: Rect

Defined in: ui/dist/view/view.d.ts:61

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

Inherited from ​

Input.bounds

castsShadow ​

castsShadow: boolean

Defined in: ui/dist/view/view.d.ts:73

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 ​

Input.castsShadow

centered ​

centered: boolean

Defined in: ui/dist/view/view.d.ts:80

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 ​

Input.centered

curPos ​

protected curPos: number

Defined in: ui/dist/controls/input.d.ts:64

The caret index into the value.

Inherited from ​

Input.curPos

dragging ​

protected dragging: boolean

Defined in: ui/dist/controls/input.d.ts:76

True between this field's own mouse-down and its release, so it only extends drags it started.

Inherited from ​

Input.dragging

firstPos ​

protected firstPos: number

Defined in: ui/dist/controls/input.d.ts:66

First visible character index (the horizontal-scroll offset).

Inherited from ​

Input.firstPos

focusable ​

focusable: boolean

Defined in: ui/dist/controls/input.d.ts:56

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.

Inherited from ​

Input.focusable

hasSelection ​

readonly hasSelection: Signal<boolean>

Defined in: ui/dist/controls/input.d.ts:85

Whether the field currently holds a non-empty selection, as a reactive signal. Read it as input.hasSelection(), or bind it (in an effect/computed) to grey a Cut/Copy menu or status item when nothing is selected. It updates on every selection change — select-all, Shift+motion, mouse drag/double-click, and any edit that collapses or deletes the selection.

Inherited from ​

Input.hasSelection

invalid ​

invalid: boolean

Defined in: ui/dist/controls/input.d.ts:78

Set by valid / focus-leave; drives the invalid styling. Read it to react to validity.

Inherited from ​

Input.invalid

lastDownX ​

protected lastDownX: number | null

Defined in: ui/dist/controls/input.d.ts:74

Last mouse-down column, used to detect a double-click; null after any non-click action.

Inherited from ​

Input.lastDownX

layout ​

layout: LayoutProps

Defined in: ui/dist/view/view.d.ts:65

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

Inherited from ​

Input.layout

maxLength ​

protected readonly maxLength: number

Defined in: ui/dist/controls/input.d.ts:60

Length cap on the stored value (Infinity when unbounded).

Inherited from ​

Input.maxLength

postProcess ​

postProcess: boolean

Defined in: ui/dist/view/view.d.ts:90

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

Inherited from ​

Input.postProcess

preProcess ​

preProcess: boolean

Defined in: ui/dist/view/view.d.ts:88

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

Inherited from ​

Input.preProcess

selEnd ​

protected selEnd: number

Defined in: ui/dist/controls/input.d.ts:70

Selection end (exclusive) as a string index. Invariant: selStart ≤ selEnd.

Inherited from ​

Input.selEnd

selStart ​

protected selStart: number

Defined in: ui/dist/controls/input.d.ts:68

Selection start (inclusive) as a string index; selStart === selEnd means no selection.

Inherited from ​

Input.selStart

state ​

readonly state: ViewState

Defined in: ui/dist/view/view.d.ts:63

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

Inherited from ​

Input.state

validator? ​

protected readonly optional validator?: Validator

Defined in: ui/dist/controls/input.d.ts:62

Optional live + blocking validator.

Inherited from ​

Input.validator

value ​

protected readonly value: Signal<string>

Defined in: ui/dist/controls/input.d.ts:58

The two-way bound value signal (source of truth).

Inherited from ​

Input.value

wasFocused ​

protected wasFocused: boolean

Defined in: ui/dist/controls/input.d.ts:87

Tracks the focus edge so the blocking validator runs only when focus actually leaves the field.

Inherited from ​

Input.wasFocused

Accessors ​

caretPos ​

Get Signature ​

get caretPos(): number

Defined in: ui/dist/controls/input.d.ts:98

The caret index into the value.

Returns ​

number

The current caret position.

Inherited from ​

Input.caretPos

selection ​

Get Signature ​

get selection(): object

Defined in: ui/dist/controls/input.d.ts:93

The current selection range as JS string indices (start ≤ end; empty when start === end).

Returns ​

object

The { start, end } selection bounds.

end ​

end: number

start ​

start: number

Inherited from ​

Input.selection

Methods ​

accelerators() ​

accelerators(): readonly string[]

Defined in: ui/dist/view/view.d.ts:104

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 ​

Input.accelerators

adjustScroll() ​

protected adjustScroll(): void

Defined in: ui/dist/controls/input.d.ts:129

Keep the caret on screen by clamping the horizontal-scroll offset.

Returns ​

void

Inherited from ​

Input.adjustScroll

adjustSelectBlock() ​

protected adjustSelectBlock(): void

Defined in: ui/dist/controls/input.d.ts:187

Order the selection range from the current caret and anchor.

Returns ​

void

Inherited from ​

Input.adjustSelectBlock

applyDelete() ​

protected applyDelete(kind): void

Defined in: ui/dist/controls/input.d.ts:175

Apply a delete gesture, but reject it if the result would fail the live validator. This keeps a masked field from being corrupted — e.g. a delete that would break a picture mask is refused rather than left in an invalid state.

Parameters ​

kind ​

DeleteKind

The delete gesture (backspace / forward / word / selection).

Returns ​

void

Inherited from ​

Input.applyDelete

bind() ​

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

Defined in: ui/dist/view/view.d.ts:192

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 ​

Input.bind

collapseSelection() ​

protected collapseSelection(): void

Defined in: ui/dist/controls/input.d.ts:189

Clear the selection.

Returns ​

void

Inherited from ​

Input.collapseSelection

deleteSelect() ​

protected deleteSelect(): void

Defined in: ui/dist/controls/input.d.ts:185

Remove the selected range and move the caret to its start.

Returns ​

void

Inherited from ​

Input.deleteSelect

derived() ​

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

Defined in: ui/dist/view/view.d.ts:214

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 ​

Input.derived

desiredCaret() ​

desiredCaret(): Point | null

Defined in: ui/dist/controls/input.d.ts:127

The view-local caret cell for the hardware cursor: the focused edit cell, or null when unfocused or scrolled out of view. The event loop translates it to an absolute screen cell.

Returns ​

Point | null

The view-local caret { x, y }, or null.

Inherited from ​

Input.desiredCaret

draw() ​

draw(ctx): void

Defined in: ui/dist/controls/input.d.ts:120

Paint the field: the scrolled value at column 1, the edge arrows, the selection band, and a visible caret, in the focused/normal role. Delegates the pixel math to the render helper.

Parameters ​

ctx ​

DrawContext

The clipped, view-local paint context.

Returns ​

void

Inherited from ​

Input.draw

editState() ​

protected editState(): EditState

Defined in: ui/dist/controls/input.d.ts:165

Snapshot the editable state (value + caret + selection) for the pure delete helpers.

Returns ​

EditState

Inherited from ​

Input.editState

focusSignal() ​

focusSignal(): Signal<void>

Defined in: ui/dist/view/view.d.ts:122

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 ​

Input.focusSignal

getMaxLength() ​

getMaxLength(): number

Defined in: ui/dist/controls/input.d.ts:102

The field's maximum length (Infinity when unbounded), so a companion control can clamp a value to it.

Returns ​

number

Inherited from ​

Input.getMaxLength

getValueSignal() ​

getValueSignal(): Signal<string>

Defined in: ui/dist/controls/input.d.ts:100

The two-way bound text signal, so a companion control can replace the field's text.

Returns ​

Signal<string>

Inherited from ​

Input.getValueSignal

handleKey() ​

protected handleKey(inner): boolean

Defined in: ui/dist/controls/input.d.ts:163

Apply an editing/motion key. Shift + a motion key extends the selection; a plain motion collapses it; an edit (Backspace/Delete/a printable character) deletes any selection first.

Parameters ​

inner ​

KeyEvent

The decoded key event.

Returns ​

boolean

Whether the key was consumed (halts propagation).

Inherited from ​

Input.handleKey

handleMouse() ​

protected handleMouse(inner, ev): void

Defined in: ui/dist/controls/input.d.ts:209

Handle a mouse gesture: clicking an edge arrow scrolls; a plain press positions the caret and begins a drag-selection (capturing the pointer so the drag continues past the field edge); a drag extends the selection; a second press on the same cell is a double-click that selects all; releasing ends the drag.

Parameters ​

inner ​

MouseEvent

The decoded mouse event.

ev ​

DispatchEvent

The dispatch envelope (local cell + the pointer-capture seam).

Returns ​

void

Inherited from ​

Input.handleMouse

insertPrintable() ​

protected insertPrintable(inner): boolean

Defined in: ui/dist/controls/input.d.ts:183

Insert a printable character: delete any selection first, then insert at the caret, respecting the length cap and the validator. Always collapses the selection afterwards.

Parameters ​

inner ​

KeyEvent

The decoded key event.

Returns ​

boolean

Whether the key was consumed.

Inherited from ​

Input.insertPrintable

invalidate() ​

invalidate(): void

Defined in: ui/dist/view/view.d.ts:167

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

Returns ​

void

Inherited from ​

Input.invalidate

invalidateLayout() ​

invalidateLayout(): void

Defined in: ui/dist/view/view.d.ts:169

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

Returns ​

void

Inherited from ​

Input.invalidateLayout

measure()? ​

optional measure(available): Size2D

Defined in: ui/dist/view/view.d.ts:67

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

Parameters ​

available ​

Size2D

Returns ​

Size2D

Inherited from ​

Input.measure

onCleanup() ​

onCleanup(fn): void

Defined in: ui/dist/view/view.d.ts:230

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 ​

Input.onCleanup

onEvent() ​

onEvent(ev): void

Defined in: ui/dist/controls/input.d.ts:137

Route a key (edit / move / select) or a mouse gesture (position / drag-select / scroll). Tab and Enter are deliberately not consumed — they pass through to focus traversal and the dialog's default button.

Parameters ​

ev ​

DispatchEvent

The dispatch envelope (carries local during real mouse dispatch).

Returns ​

void

Inherited from ​

Input.onEvent

onMount() ​

onMount(fn): void

Defined in: ui/dist/view/view.d.ts:222

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 ​

Input.onMount

pasteText() ​

protected pasteText(text): void

Defined in: ui/dist/controls/input.d.ts:155

Insert pasted text: replace any current selection, then insert each code point through the validator and the length cap (invalid or over-cap characters are dropped individually).

Parameters ​

text ​

string

The pasted text (untrusted; its size is already bounded upstream).

Returns ​

void

Inherited from ​

Input.pasteText

posFromMouse() ​

protected posFromMouse(localX): number

Defined in: ui/dist/controls/input.d.ts:211

Map a view-local mouse column to a value index.

Parameters ​

localX ​

number

Returns ​

number

Inherited from ​

Input.posFromMouse

refreshHasSelection() ​

protected refreshHasSelection(): void

Defined in: ui/dist/controls/input.d.ts:191

Push the current selection-presence into hasSelection so an app can react to selection changes.

Returns ​

void

Inherited from ​

Input.refreshHasSelection

runClipboard() ​

protected runClipboard(action, ev): void

Defined in: ui/dist/controls/input.d.ts:148

Run a clipboard action. Copy and cut write the current selection to the clipboard (which mirrors it to both the OS clipboard and the app-local buffer); an empty selection is a no-op, and cut then deletes the selection. Paste inserts the app-local buffer at the caret — replacing any selection — through the validator and length cap; an empty buffer is a no-op. The terminal's own paste gesture still arrives separately as a paste event handled by pasteText.

Parameters ​

action ​

ClipboardAction

The clipboard action.

ev ​

DispatchEvent

The dispatch envelope (carries setClipboard / readClipboard).

Returns ​

void

Inherited from ​

Input.runClipboard

selectAll() ​

selectAll(enable?): void

Defined in: ui/dist/controls/input.d.ts:197

Select the entire value (or, with enable === false, clear the selection) and move the caret to the end. Public so a companion control can select-all before replacing the text. Defaults to select-all.

Parameters ​

enable? ​

boolean

Returns ​

void

Inherited from ​

Input.selectAll

selectByClick()? ​

optional selectByClick(): void

Defined in: ui/dist/view/view.d.ts:156

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 ​

Input.selectByClick

setValue() ​

protected setValue(next): void

Defined in: ui/dist/controls/input.d.ts:199

Write the bound value (two-way).

Parameters ​

next ​

string

Returns ​

void

Inherited from ​

Input.setValue

valid() ​

valid(): boolean

Defined in: ui/dist/controls/input.d.ts:113

Run the blocking validator over the current value, update invalid, and return the result. Call it to validate on demand. With no validator, always valid.

Returns ​

boolean

Whether the current value passes the blocking validator.

Inherited from ​

Input.valid

writeEditState() ​

protected writeEditState(s): void

Defined in: ui/dist/controls/input.d.ts:167

Commit an EditState: write value + caret + selection back onto this field.

Parameters ​

s ​

EditState

Returns ​

void

Inherited from ​

Input.writeEditState