file

Provides typed browser download resources and modern file selection.

Download resources use gossamer/blob for Blob construction and object-URL lifetime. Render the returned URL and filename on a normal Lustre or Redraw anchor; Glendix intentionally does not synthesize or programmatically click a hidden anchor.

File selection uses Plinth’s File System Access API bindings. Browsers without showOpenFilePicker return PickerUnsupported; Glendix does not emulate the capability with a hidden input. Applications that need a fallback can render a visible file input with accepted_types and handle that input in their UI layer.

Application document parsing, persistence, extension policy, and filename normalization remain outside this module.

Types

Download

opaque </>

Represents a declarative browser download and its object-URL resource.

pub opaque type Download

DownloadError

</>

Represents invalid metadata supplied while creating a download.

pub type DownloadError {
  DownloadFilenameWasEmpty
  DownloadMimeTypeWasInvalid(mime_type: String)
}

Constructors

```
DownloadFilenameWasEmpty
```
The suggested filename is empty after surrounding whitespace is removed.
```
DownloadMimeTypeWasInvalid(mime_type: String)
```
The MIME type is empty or does not contain a concrete type/subtype.

Picker

opaque </>

Configures metadata validation for a selected browser file.

pub opaque type Picker

PickerCapability

</>

Represents availability of the modern browser file picker.

pub type PickerCapability {
  ModernPickerAvailable
  ModernPickerUnavailable
}

Constructors

```
ModernPickerAvailable
```
showOpenFilePicker is callable in the current browser.
```
ModernPickerUnavailable
```
The current runtime does not expose showOpenFilePicker.

PickerConfigurationError

</>

Represents invalid picker configuration.

pub type PickerConfigurationError {
  MaximumSizeWasNotPositive(maximum_size_bytes: Int)
  AcceptedTypeWasInvalid(accepted_type: String)
}

Constructors

```
MaximumSizeWasNotPositive(maximum_size_bytes: Int)
```
The maximum permitted file size must be greater than zero.
```
AcceptedTypeWasInvalid(accepted_type: String)
```
An accepted type was neither a MIME type/range nor a file extension.

PickerError

</>

Represents a modern file-picker or selected-file failure.

pub type PickerError {
  PickerUnsupported
  SelectionCancelled
  SelectionFailed(reason: String)
  SelectedFileCouldNotBeOpened(name: String, reason: String)
  SelectedFileWasEmpty(name: String)
  SelectedFileWasTooLarge(
    name: String,
    size_bytes: Int,
    maximum_size_bytes: Int,
  )
  SelectedFileTypeWasNotAccepted(
    name: String,
    mime_type: String,
    accepted_types: List(String),
  )
  SelectedFileCouldNotBeRead(name: String, reason: String)
}

Constructors

```
PickerUnsupported
```
The current runtime does not support the modern file picker.
```
SelectionCancelled
```
The user cancelled selection or the browser returned no selected handle.
```
SelectionFailed(reason: String)
```
The picker failed for a reason other than user cancellation.

SelectedFileCouldNotBeOpened(name: String, reason: String)

The selected handle could not be opened as a browser file.

```
SelectedFileWasEmpty(name: String)
```
The selected file contains no bytes.

SelectedFileWasTooLarge(
  name: String,
  size_bytes: Int,
  maximum_size_bytes: Int,
)

The selected file is larger than the configured maximum.

SelectedFileTypeWasNotAccepted(
  name: String,
  mime_type: String,
  accepted_types: List(String),
)

The selected file does not match any configured MIME type or extension.

SelectedFileCouldNotBeRead(name: String, reason: String)

The browser rejected reading the selected file’s bytes.

SelectedFile

opaque </>

Represents a browser-selected file whose bytes passed configured checks.

pub opaque type SelectedFile

Values

accepted_types

</>

pub fn accepted_types(
  configuration configuration: Picker,
) -> List(String)

Returns accepted MIME types/extensions in stable first-seen order.

The result can be passed to Lustre or Redraw’s accept attribute for a visible declarative fallback input.

download

</>

pub fn download(
  from bytes: BitArray,
  named filename: String,
  with_mime_type mime_type: String,
) -> Result(Download, DownloadError)

Creates a MIME-typed Blob and object URL for a declarative download link.

The filename is preserved exactly. Glendix only rejects an empty filename; application-specific normalization and extension policy remain the caller’s responsibility. Release the resource with release when its anchor is removed or replaced.

download_filename

</>

pub fn download_filename(resource resource: Download) -> String

Returns the filename to use on a declarative anchor’s download attribute.

download_mime_type

</>

pub fn download_mime_type(resource resource: Download) -> String

Returns the validated MIME type associated with the download.

download_url

</>

pub fn download_url(resource resource: Download) -> String

Returns the object URL to use on a declarative anchor’s href attribute.

pick

</>

pub fn pick(
  using configuration: Picker,
) -> promise.Promise(Result(SelectedFile, PickerError))

Opens the modern picker and reads one validated file.

Plinth’s current API does not expose picker options and the browser call is single-select by default. If a browser nevertheless returns multiple handles, the first handle in browser order is used.

picker

</>

pub fn picker(
  accepting accepted_types: List(String),
  maximum_size_bytes maximum_size_bytes: Int,
) -> Result(Picker, PickerConfigurationError)

Creates picker validation configuration.

Accepted values may be exact MIME types (application/json), MIME wildcards (image/*), or dot-prefixed extensions (.ic). An empty list accepts any type. Duplicate values are removed while preserving first-seen order.

picker_capability

</>

pub fn picker_capability() -> PickerCapability

Reports whether the modern picker is available in the current runtime.

release

</>

pub fn release(resource resource: Download) -> Nil

Revokes a download’s object URL.

The underlying Gossamer operation follows URL.revokeObjectURL: releasing the same resource more than once is a safe no-op at the browser boundary.

selected_bytes

</>

pub fn selected_bytes(file file: SelectedFile) -> BitArray

Returns the selected file bytes.

selected_mime_type

</>

pub fn selected_mime_type(file file: SelectedFile) -> String

Returns the selected browser MIME type, which may be empty.

selected_name

</>

pub fn selected_name(file file: SelectedFile) -> String

Returns the selected browser filename.

selected_size_bytes

</>

pub fn selected_size_bytes(file file: SelectedFile) -> Int

Returns the selected file size in bytes.