Component · Inputs

File Picker

A host-driven file/directory browser with breadcrumbs, multi-select, path entry, and optional preview — no filesystem I/O in TermRock.

Kind: widget
Input: interactive
Canvas: 120×40

Live preview

Ghostty· TermRock —file-picker/unixloading poster…

Loading terminal poster…

○ loading posterNo input — rendered state only

File Picker · exact mounted Rust story

01 · Purpose

What it is for

A host-driven file/directory browser with breadcrumbs, multi-select, path entry, and optional preview — no filesystem I/O in TermRock.

Best fit: Inputs · input · widget

02 · Behavior

What the mounted story proves

01
FilePicker
Representative 120×40 terminal state.
02
Passive paint
No keyboard or pointer action is claimed by this representative story.
03
Evidence stays explicit
3 covered · 8 partial · 5 missing axes.

03 · Implement

Install, then start from exact code

Install

cargo add termrock --git https://github.com/tailrocks/termrock.git --rev 5283c2acf9154d0cfcd37b1ffe821c00faf90ea2

Add TermRock once. Keep domain effects in the host application.

Minimal implementation

Exact Rust setup used by file-picker/unix.

Open to load code.

04 · Adapt

Variants and composition

Variants

Use the preview Variant menu when alternate registered stories exist. Each selection mounts a fresh configuration.

Composition

Inputs · input · widget

05 · Reference

API, tokens, accessibility

API

FilePickerOpen source ↗

Tokens

DesignSystemInspect exact story code for roles and capability projection.

Accessibility

Input contract mountedNo input claim in the representative story.

Contract

Evidence in progress3/23 axes covered

06 · Go deeper

Advanced guidance

Authored implementation guidance

Purpose. Reusable open/save browser for files and directories. Built from PathInput, CollectionState list focus, Selection multi-check, and optional OverlayStack dialogs. TermRock never calls the filesystem.

Ownership

Concern	Owner
List / preview I/O, cancel, permissions	Host
Entry projection (kind, hidden, size, mtime labels)	Host
Hidden filter, name filter, sort, multi, crumbs	FilePicker
Path field typing	Embedded PathInput
Modal place / dismiss	OverlayStack helpers

Host loop

Listing and preview requests use independent generation sequences. With preview enabled, highlighting any entry—including directories—emits PreviewRequested with a fresh preview generation. Starting any directory listing invalidates outstanding preview work, so a late result from the prior selection or directory cannot replace the current preview.

Modes

OpenFile / SaveFile — files selectable; dirs navigate
OpenDirectory — dirs selectable
OpenAny — both

Presentation

presentation_for_bounds / auto paint: narrow terminals prefer Fullscreen and drop the preview column. Overlay id: FILE_PICKER_OVERLAY_ID.

Composing picker chrome

All picker chrome is enabled by default. Hosts embedding the FilePicker inside an existing header, search row, body, and footer can hide only the rows they already render:

These options keep the FilePicker's list/preview layout and input behavior. They only remove the matching title count, breadcrumb, path, status, or footer row. The picker title remains visible when show_count(false) is used.

Hosts that render a custom preview shell can use FilePickerState::preview() to borrow the latest accepted FilePreview without duplicating picker state. The getter is read-only; asynchronous hosts still apply results through apply_preview(generation, preview) so stale results remain rejected.

Ownership boundary

TermRock owns reusable terminal rendering and interaction state. The host owns domain data, policy, persistence, authorization, and side effects.

Evidence status

3 covered, 8 partial, and 5 missing contract axes. Missing evidence is not a behavior claim.

Field Row

A density-aware composed field row with shared label columns, semantic selection chrome, masked and unset values, markers, and annotations.

Form

A responsive form layout with stable focus, validation, and hit geometry.