0.1.5 · Local selection and upload presentation

Import LocalFilePicker, UploadQueue and UploadDialog from rom-ui/files. These components do not create a transport, persist bytes or complete an attachment.

Local selection

Supply authority and onselect(files) to LocalFilePicker. The callback receives browser File objects. Duplicate filenames remain separate selections. The component does not turn filenames into storage paths or Resource IDs.

The picker uses a native file input. Default limits are 20 files and 10 MiB per file. Set maxFiles, maxBytes and accept for metadata preflight. MIME and extension hints do not establish file-content validity or permission. The host must enforce server limits, authorization and content checks.

The picker clears its native input after selection. This permits selecting the same file again. Canceled or empty selection does not replace host state. Rejected selections do not invoke the callback.

Set preferFileSystemAccess to opt into showOpenFilePicker when it is available in a secure context. The component calls it directly from the user's button action. Unsupported environments retain the native input path. Resolved handles use the same metadata preflight. The component does not retain filesystem handles or request persistent access. Cancellation preserves host selection. Late results from a replaced authority or destroyed lifetime cannot invoke onselect.

The API documentation describes its limited availability and user-activation requirement. Qualification uses mocked enhanced-API outcomes in both engines and real native chooser fallback. It does not establish native File System Access support in WebKit.

Queue ownership

Supply readonly UploadItem values with unique host-owned IDs. Filenames can repeat. The host supplies each stage: selected, uploading, processing, failed, unknown, confirmed or canceled. A confirmed stage requires an attachment kind and exact ID. Supply it only after ROM confirms completion.

Byte progress remains separate from verification and attachment completion. A 100% bar still reports uploading when that is the supplied stage. Failed items can expose onretry(id). Unknown outcomes expose onrecover(id) instead. The host must reconcile or replay its original operation, preserving its receipt and command identity. Cancellation is a request through oncancel(id); the widget does not infer that a remote operation was canceled.

UploadDialog composes the picker and queue inside the shared Dialog. Bind open to control visibility. Use its actions snippet for additional host controls. A new authority closes and recreates the dialog subtree. The host must also replace private queue and selection data when authority changes.

Optional Uppy selection

Install @uppy/core@6.2.0 and @uppy/svelte@6.0.0 separately with pnpm. Import UppySelection from rom-ui/files/uppy. The base file controls do not import this optional entry. Supply authority and onselect(files). The adapter uses Uppy's Svelte headless hook for keyboard selection and drag/drop. Each authority lifetime owns a fresh Uppy engine. Duplicate filenames receive distinct engine file IDs. The adapter destroys the engine and discards queued selection callbacks when that lifetime ends. The host must also replace its private selection data when authority changes.

Use maxFiles, maxBytes and allowedFileTypes to configure restrictions for an authority lifetime. Create a new authority lifetime when changing those restrictions. The optional onready(engine) setup callback can return a cleanup function for host subscriptions or transport integration. The adapter does not enable automatic uploads. Uppy completion does not establish ROM attachment confirmation.

The official Svelte integration describes the headless hooks.

File picker composition

Import FilePicker and the FileQuery types from rom-ui/files. Bind open and supply an authority token. The host's load(request) returns authorized, disclosed metadata. FilePicker does not implement authorization or fetch through another client. Use the existing ROM session/query boundary in the real adapter.

Requests contain an opaque folder identity, search text, cursor and AbortSignal. Ready pages contain entries and breadcrumbs. A page can provide an opaque next cursor for host pagination. Denied pages expose no choices. Failed or obsolete requests do not retain selectable results.

The component copies metadata and limits each page to 100 unique identities and 32 breadcrumbs. Unsigned sizes use bigint and retain exact values. Names and MIME text do not become storage paths or URLs. The optional preview(entry) snippet permits host-owned presentation without automatic remote preview fetching.

Explicit Select returns the exact file kind and ID. It does not upload, attach or mutate a Resource. Authority replacement closes the dialog and disposes its query lifetime. The English gallery includes both a labeled fixture provider and the authorized ROM attachment catalog.

ROM integration

The gallery keeps simulated queue states separate from real ROM uploads. Native and Uppy selection use Studio's attachment lifecycle and existing session/recovery contracts. Real-host Chromium and WebKit journeys verify committed attachments, exact downloads, cross-visitor denial, and recovery after reload. The File System Access enhancement retains the native chooser fallback.