JSVision

Appearance

@jsvision/files / FileDialog

Class: FileDialog ​

Documented in: File dialog

Defined in: files/src/dialog/file-dialog.ts:81

The modal open/save file dialog.

Example ​

ts
import { createApplication, Commands } from '@jsvision/ui';
import { resolveCapabilities } from '@jsvision/core';
import { FileDialog, errorBox, nodeFileSystem } from '@jsvision/files';

const caps = resolveCapabilities({ env: process.env, platform: process.platform }).profile;
const app = createApplication({ caps });

const dlg = new FileDialog({
  fs: nodeFileSystem,
  showError: (msg) => void errorBox(app, msg),
});
app.desktop.addWindow(dlg);
const command = await app.loop.execView<string>(dlg);
const path = command === Commands.ok ? dlg.result() : null;
app.desktop.removeWindow(dlg);

Extends ​

  • Dialog

Constructors ​

Constructor ​

new FileDialog(opts): FileDialog

Defined in: files/src/dialog/file-dialog.ts:110

Parameters ​

opts ​

FileDialogOptions

Returns ​

FileDialog

Overrides ​

Dialog.constructor

Properties ​

acceleratorScope ​

acceleratorScope: boolean

Defined in: ui/dist/dialog/dialog.d.ts:68

Roots the dialog's accelerator scope — its mount-time duplicate check stops at nested scopes.

Inherited from ​

Dialog.acceleratorScope

active ​

readonly active: Signal<boolean>

Defined in: ui/dist/window/window.d.ts:76

true when this is the active (top-most, focused) window, false when it sits behind another. The desktop keeps it in sync as windows are raised, added, and removed; the frame chrome reads it to switch between the active and inactive look. A standalone window defaults to true.

Inherited from ​

Dialog.active

background? ​

optional background?: keyof Theme

Defined in: ui/dist/view/group.d.ts:60

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

Inherited from ​

Dialog.background

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 ​

Dialog.bounds

buttonLabels ​

readonly buttonLabels: string[] = []

Defined in: files/src/dialog/file-dialog.ts:103

The button labels, parallel to buttons.

buttons ​

readonly buttons: Button[] = []

Defined in: files/src/dialog/file-dialog.ts:101

The button strip (open- or save-mode set).

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 ​

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

Dialog.centered

children ​

readonly children: View[]

Defined in: ui/dist/view/group.d.ts:58

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

Inherited from ​

Dialog.children

closable ​

closable: boolean

Defined in: ui/dist/window/window.d.ts:86

Whether the window can be closed (shows the close box).

Inherited from ​

Dialog.closable

directory ​

readonly directory: Signal<string>

Defined in: files/src/dialog/file-dialog.ts:85

The current directory, shared with the listing and info pane.

dragging ​

readonly dragging: Signal<boolean>

Defined in: ui/dist/window/window.d.ts:70

true while the window is being dragged (moved or resized), false otherwise. The desktop flips it around a gesture; bind to it if you want to react to drag start/end. A standalone window (never added to a desktop) stays false.

Inherited from ​

Dialog.dragging

fileInfoPane ​

readonly fileInfoPane: FileInfoPane

Defined in: files/src/dialog/file-dialog.ts:97

The read-out info pane below the listing.

fileInput ​

readonly fileInput: FileInput

Defined in: files/src/dialog/file-dialog.ts:93

The filename input.

fileList ​

readonly fileList: FileList

Defined in: files/src/dialog/file-dialog.ts:91

The two-column file listing.

filename ​

readonly filename: Signal<string>

Defined in: files/src/dialog/file-dialog.ts:89

The filename field value, shared with fileInput.

focusable ​

focusable: boolean

Defined in: ui/dist/window/window.d.ts:60

A window is a focus target so raising it (and resolving the active window) works.

Inherited from ​

Dialog.focusable

fs ​

readonly fs: FileSystem

Defined in: files/src/dialog/file-dialog.ts:83

The filesystem this dialog reads and writes through.

history ​

readonly history: History

Defined in: files/src/dialog/file-dialog.ts:95

The recent-path history dropdown beside the filename input.

layout ​

layout: LayoutProps

Defined in: ui/dist/window/window.d.ts:62

Absolute placement — the desktop writes layout.rect; padding: 1 insets content past the border.

Inherited from ​

Dialog.layout

listBar ​

readonly listBar: ScrollBar

Defined in: files/src/dialog/file-dialog.ts:99

The listing's horizontal scroll bar (owned by the dialog, placed under the list).

minHeight ​

minHeight: number

Defined in: ui/dist/window/window.d.ts:92

Inherited from ​

Dialog.minHeight

minWidth ​

minWidth: number

Defined in: ui/dist/window/window.d.ts:91

The smallest size a resize gesture will shrink the window to. Raise these in a subclass whose content assumes a fixed minimum (e.g. a dialog whose child rects need at least 49×19).

Inherited from ​

Dialog.minWidth

movable ​

movable: boolean

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

Whether the title bar can be dragged to move the window.

Inherited from ​

Dialog.movable

number? ​

optional number?: number

Defined in: ui/dist/window/window.d.ts:78

An accelerator number 1–9 shown in the frame (Alt+N activates the window); undefined = none.

Inherited from ​

Dialog.number

postProcess ​

postProcess: boolean

Defined in: ui/dist/dialog/dialog.d.ts:66

Caught after the focused chain so the hosted buttons' command events are seen dialog-wide.

Inherited from ​

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

Dialog.preProcess

resizable ​

resizable: boolean

Defined in: ui/dist/window/window.d.ts:82

Whether the window can be resized via the corner grips.

Inherited from ​

Dialog.resizable

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 ​

Dialog.state

title ​

readonly title: Signal<string>

Defined in: ui/dist/window/window.d.ts:64

The window title, centered in the top border. Set it to repaint the frame.

Inherited from ​

Dialog.title

wildcard ​

readonly wildcard: Signal<string>

Defined in: files/src/dialog/file-dialog.ts:87

The active file wildcard.

zoomable ​

zoomable: boolean

Defined in: ui/dist/window/window.d.ts:84

Whether the window can be maximized/restored (shows the zoom box).

Inherited from ​

Dialog.zoomable

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 ​

Dialog.accelerators

add() ​

add(child): void

Defined in: ui/dist/view/group.d.ts:77

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 ​

Dialog.add

addDynamic() ​

addDynamic(build): void

Defined in: ui/dist/view/group.d.ts:103

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 ​

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

Dialog.addDynamic

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 ​

Dialog.bind

clear() ​

clear(): void

Defined in: files/src/dialog/file-dialog.ts:215

Empty the filename field (save-mode Clear).

Returns ​

void

close() ​

close(): void

Defined in: ui/dist/window/window.d.ts:144

Close the window, removing it from the desktop (which disposes its scope). No-op if not closable.

Returns ​

void

Inherited from ​

Dialog.close

commitPlacement() ​

commitPlacement(): void

Defined in: ui/dist/window/window.d.ts:123

Freeze the current on-screen position into layout.rect and stop auto-centering, if this window is still centered. The desktop calls this at the start of a move/resize gesture: a centered window's real position lives in bounds (computed each reflow) rather than in layout.rect (which stays at the origin), so a gesture that read layout.rect would snap it to the top-left. After this runs once, the window behaves as a normally-placed window. No-op if not centered.

Returns ​

void

Inherited from ​

Dialog.commitPlacement

currentRect() ​

protected currentRect(): Rect

Defined in: ui/dist/window/window.d.ts:125

The window's current WM rect (the layout rect, or a degenerate fallback before placement).

Returns ​

Rect

Inherited from ​

Dialog.currentRect

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 ​

Dialog.derived

desiredCaret() ​

desiredCaret(): Point | null

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

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 ​

Dialog.desiredCaret

draw() ​

draw(ctx): void

Defined in: ui/dist/dialog/dialog.d.ts:86

Paint the frame in the dialog role — close box, no zoom box. A modal dialog always draws active.

Parameters ​

ctx ​

DrawContext

Returns ​

void

Inherited from ​

Dialog.draw

firstInvalidChild() ​

protected firstInvalidChild(view): View | null

Defined in: ui/dist/dialog/dialog.d.ts:97

Depth-first: the first descendant control whose zero-arg valid() returns false, or null.

Parameters ​

view ​

View

Returns ​

View | null

Inherited from ​

Dialog.firstInvalidChild

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 ​

Dialog.focusSignal

handleTerminating() ​

protected handleTerminating(command, ev): void

Defined in: ui/dist/dialog/dialog.d.ts:107

Apply a terminating command: cancel bypasses; ok/yes/no run the valid() gate first.

Parameters ​

command ​

string

ev ​

DispatchEvent

Returns ​

void

Inherited from ​

Dialog.handleTerminating

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 ​

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

Dialog.invalidateLayout

isZoomed() ​

isZoomed(): boolean

Defined in: ui/dist/window/window.d.ts:127

Whether the window is currently zoomed (maximized).

Returns ​

boolean

Inherited from ​

Dialog.isZoomed

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 ​

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

Dialog.onCleanup

onDesktopResize() ​

onDesktopResize(size): void

Defined in: ui/dist/window/window.d.ts:142

Re-fit to a resized desktop: a zoomed window re-maximizes to the new desktop size, and its saved restore rect is clamped so a later un-zoom still lands on-screen. A non-zoomed window is left where it is (a window may overflow the desktop edge).

Parameters ​

size ​

Size2D

The new desktop content size.

Returns ​

void

Inherited from ​

Dialog.onDesktopResize

onEvent() ​

onEvent(ev): void

Defined in: ui/dist/dialog/dialog.d.ts:105

Route events: catch a terminating command → valid() gate → close; and (when modal) route the frame close-box + Esc to the cancel path. Everything else delegates to Window (raise/move for a modeless dialog).

Parameters ​

ev ​

DispatchEvent

The dispatch envelope.

Returns ​

void

Inherited from ​

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

Dialog.onMount

onResized() ​

onResized(): void

Defined in: files/src/dialog/file-dialog.ts:197

Reflow the children to track the frame when the dialog is drag-resized.

Returns ​

void

Overrides ​

Dialog.onResized

remove() ​

remove(child): void

Defined in: ui/dist/view/group.d.ts:85

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 ​

Dialog.remove

replace() ​

replace(): void

Defined in: files/src/dialog/file-dialog.ts:209

Load the focused entry's name into the field (save-mode Replace).

Returns ​

void

resetZoom() ​

resetZoom(): void

Defined in: ui/dist/window/window.d.ts:129

Forget the zoom state without restoring the rect (used by cascade/tile, which place the window).

Returns ​

void

Inherited from ​

Dialog.resetZoom

resolveCancel() ​

protected resolveCancel(ev): void

Defined in: ui/dist/dialog/dialog.d.ts:109

Resolve the modal to cancel (bypasses valid()), for the frame close-box and Esc.

Parameters ​

ev ​

DispatchEvent

Returns ​

void

Inherited from ​

Dialog.resolveCancel

result() ​

result(): string | null

Defined in: files/src/dialog/file-dialog.ts:204

The resolved absolute path, or null while unresolved / on cancel.

Returns ​

string | null

selectByClick() ​

selectByClick(): void

Defined in: ui/dist/window/window.d.ts:155

Select and raise the window on a mouse-down. The hit-test calls this before the event descends into the window's interior, so the window comes to the front even when an interior child ends up consuming the click. It first records whether the window was already active (so onEvent can make the first click on an inactive window only raise it, not act on a frame button). A standalone window (no desktop) is a safe no-op; re-selecting the already-active window just re-raises it harmlessly.

Returns ​

void

Inherited from ​

Dialog.selectByClick

valid() ​

valid(command): boolean

Defined in: files/src/dialog/file-dialog.ts:266

Decide whether the dialog may close for a terminating command. Cancel always closes; OK runs the filename state machine (wildcard re-filters, a directory descends, a valid file resolves, an invalid entry raises the error box). Other commands defer to the base dialog.

Parameters ​

command ​

string

The command trying to close the dialog.

Returns ​

boolean

true to close, false to stay open.

Overrides ​

Dialog.valid

zoom() ​

zoom(): void

Defined in: ui/dist/window/window.d.ts:134

Toggle maximized ↔ restored. Maximizing saves the current rect and fills the desktop; restoring re-applies the exact saved rect. No-op if the window is not zoomable or has no desktop parent.

Returns ​

void

Inherited from ​

Dialog.zoom