@jsvision/files / ChDirDialog

Class: ChDirDialog

Documented in: Chdir Dialog

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

The modal change-directory dialog.

Example

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

const caps = resolveCapabilities().profile; // ambient: reads process.env + process.platform
const app = createApplication({ caps });

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

Extends

• Dialog

Constructors

Constructor

new ChDirDialog(opts): ChDirDialog

Defined in: files/src/dialog/chdir-dialog.ts:117

Parameters

opts

ChDirDialogOptions

Returns

ChDirDialog

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

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/chdir-dialog.ts:109

The button labels, parallel to buttons.

---

buttons

readonly buttons: Button[] = []

Defined in: files/src/dialog/chdir-dialog.ts:107

The button strip (OK/Chdir/Revert/Help).

---

castsShadow

castsShadow: boolean

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

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

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

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/chdir-dialog.ts:97

The current directory, shared with the tree.

---

dirList

readonly dirList: DirList

Defined in: files/src/dialog/chdir-dialog.ts:105

The directory tree.

---

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

---

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/chdir-dialog.ts:95

The filesystem this dialog reads through.

---

grabsFocus

grabsFocus: boolean

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

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

Dialog.grabsFocus

---

history

readonly history: History

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

The recent-path history dropdown beside the path input.

---

i18n

readonly i18n: I18n

Defined in: files/src/dialog/chdir-dialog.ts:111

Translation service used for package-owned dialog text.

---

layout

readonly layout: Readonly<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

---

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

---

path

readonly path: Signal<string>

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

The path field value; it mirrors directory and is what OK validates.

---

pathInput

readonly pathInput: Input

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

The path input.

---

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

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

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

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

---

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

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

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

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

class Panel extends View {
  draw(ctx: DrawContext) {
    ctx.fill(' ', ctx.color('window'));
  }
}

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

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

Dialog.bind

---

chdir()

chdir(): void

Defined in: files/src/dialog/chdir-dialog.ts:208

Descend into the focused tree node (the Chdir button).

Returns

void

---

close()

close(): void

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

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(): Readonly<Rect>

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

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

Returned read-only: this hands out the live layout rect, so a mutable alias would let a subclass move the window a field at a time without requesting a reflow. Copy it ({ ...currentRect() }) if you need a scratch rect.

Returns

Readonly<Rect>

Inherited from

Dialog.currentRect

---

derived()

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

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

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

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

Paint the frame in the dialog role. The inherited window flags remain opt-in, so ordinary dialogs keep their fixed frame while a specialized modeless dialog can expose resize and zoom.

Parameters

ctx

DrawContext

Returns

void

Inherited from

Dialog.draw

---

firstInvalidChild()

protected firstInvalidChild(view): View | null

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

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

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

Dialog.focusSignal

---

handleTerminating()

protected handleTerminating(command, ev): void

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

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

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

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

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

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

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

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

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

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: ui/dist/window/window.d.ts:115

Called by the desktop right after a resize changed layout.rect, before the next reflow. The base window does nothing — flow-laid content reflows on its own. Override it in a subclass whose absolutely-placed children must be repositioned to track the new size (e.g. anchoring a button to the bottom-right corner).

Returns

void

Inherited from

Dialog.onResized

---

remove()

remove(child): void

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

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

---

resetZoom()

resetZoom(): void

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

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

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/chdir-dialog.ts:203

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

Returns

string | null

---

revert()

revert(): void

Defined in: files/src/dialog/chdir-dialog.ts:214

Restore the starting directory (the Revert button).

Returns

void

---

selectByClick()

selectByClick(): void

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

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

---

setLayout()

setLayout(patch): void

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

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

Dialog.setLayout

---

valid()

valid(command): boolean

Defined in: files/src/dialog/chdir-dialog.ts:244

Decide whether the dialog may close. Cancel always closes; OK validates the path field as a readable directory — resolving and closing on success, or raising the error box and staying open.

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

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