Mixins / foldkit-mixins-ui

FileUpload

namespace · packages/mixins-ui/src/fileUpload.ts:1

export * as FileUpload from './fileUpload.js'

In the guides

Members

FileUpload.accepts

function · packages/mixins-ui/src/fileUpload.ts:283

function accepts(
  tokens: ReadonlyArray<string>,
  file: {
    readonly name: string
    readonly type: string
  },
): boolean

Whether a file is one of the kinds. An empty list takes everything; .ext matches the name's ending, type/* the type's prefix and anything else the type exactly, all case-insensitively. A file with no type matches only an extension.

FileUpload.announce

function · packages/mixins-ui/src/fileUpload.ts:1449

function announce(model: Model, text: string): Model

Has the live region say text, for a step the application caused (a reorder).

FileUpload.configure

function · packages/mixins-ui/src/fileUpload.ts:1327

function configure<const Names extends string = never>(
  config: Presets<FileUploadPreset, Names>,
): {
  readonly view: <Outer>(
    options: FileUploadView<Outer> & PresetOption<Names>,
    h: HtmlBuilder<Outer>,
  ) => Html
  readonly parts: <Outer>(
    options: FileUploadView<Outer> & PresetOption<Names>,
    h: HtmlBuilder<Outer>,
  ) => FileUploadParts
}

The application's own FileUpload: base for every use, presets chosen at a use with preset, and the call over both. mixins concatenate in that order and words merge word by word; any other option given at the call replaces the preset's. parts is bound as view is, for a layout of the application's own.

FileUpload.conflict

function · packages/mixins-ui/src/fileUpload.ts:974

function conflict<Outer>(
  routes: ReadonlyArray<Route<Outer>>,
): Option.Option<Diagnostic>

The mixins:key-conflict that drawing the input with routes would throw, or none: the application's routes against Enter and Space (the dialog's), Backspace and Delete (the last file's), and each other.

FileUpload.counts

function · packages/mixins-ui/src/fileUpload.ts:1459

function counts(model: Model): {
  readonly held: number
  readonly queued: number
  readonly uploading: number
  readonly done: number
  readonly failed: number
  readonly bytes: number
}

What the entries are doing, and how many bytes they hold.

FileUpload.displayUrl

function · packages/mixins-ui/src/fileUpload.ts:1484

function displayUrl(entry: Entry): Option.Option<string>

The address an img can show: the preview of a local file, or a stored image's own.

FileUpload.Entry

const · packages/mixins-ui/src/fileUpload.ts:75

const Entry: Schema.Struct<{
  readonly id: Schema.String
  readonly name: Schema.String
  readonly size: Schema.Number
  readonly type: Schema.String
  readonly source: TaggedUnion<{
    readonly Local: { readonly file: Schema.instanceOf<File, File> }
    readonly Stored: { readonly url: Schema.String }
  }>
  readonly preview: Schema.OptionFromNullOr<Schema.String>
  readonly attempts: Schema.Number
  readonly status: TaggedUnion<{
    readonly Held: {}
    readonly Queued: {}
    readonly Uploading: {
      readonly attempt: Schema.Number
      readonly lane: Schema.Number
      readonly loaded: Schema.Number
      readonly total: Schema.Number
    }
    readonly Done: { readonly url: Schema.OptionFromNullOr<Schema.String> }
    readonly Failed: {
      readonly reason: Schema.String
      readonly retryable: Schema.Boolean
    }
  }>
}>

FileUpload.FileUploadItem

interface · packages/mixins-ui/src/fileUpload.ts:981

interface FileUploadItem {
  readonly entry: Entry
  readonly item: (children: ReadonlyArray<Html>) => Html
  readonly preview: Option.Option<Html>
  readonly name: Html
  readonly meta: Html
  readonly state: Option.Option<Html>
  readonly progress: Option.Option<Html>
  readonly actions: Option.Option<Html>
  readonly grip: Option.Option<Html>
}

What one entry draws, unassembled, for a layout of the application's own (a table row, a card).

FileUpload.FileUploadParts

interface · packages/mixins-ui/src/fileUpload.ts:997

interface FileUploadParts {
  readonly root: (children: ReadonlyArray<Html>) => Html
  readonly input: Html
  readonly picker: Option.Option<Html>
  readonly description: Option.Option<Html>
  readonly constraints: Option.Option<Html>
  readonly errors: Option.Option<Html>
  readonly status: Html
  readonly summary: Option.Option<Html>
  readonly list: (items: ReadonlyArray<Html>) => Html
  readonly items: ReadonlyArray<FileUploadItem>
}

The drawings view assembles, each alone.

FileUpload.FileUploadPattern

const · packages/mixins-ui/src/fileUpload.ts:783

const FileUploadPattern: A11y.Pattern<{
  readonly input: {
    readonly capability: Capability.Capability<
      'Interactive',
      readonly [Capability.Capability<'Base', readonly []>]
    >
    readonly events: readonly [Event.EventToken<'change'>]
    readonly attributes: readonly [Attr.AttrToken<'aria-invalid'>]
    readonly obligations: readonly [
      A11y.Obligation<'activation'>,
      A11y.Obligation<'focus-strategy'>,
      A11y.Obligation<'name'>,
    ]
  }
  readonly picker: {
    readonly capability: Capability.Capability<
      'Container',
      readonly [
        Capability.Capability<
          'Interactive',
          readonly [Capability.Capability<'Base', readonly []>]
        >,
      ]
    >
  }
  readonly remove: {
    readonly capability: Capability.Capability<
      'Interactive',
      readonly [Capability.Capability<'Base', readonly []>]
    >
    readonly events: readonly [Event.EventToken<'click'>]
    readonly attributes: readonly [Attr.AttrToken<'aria-label'>]
  }
}>

The input is a native file input and the picker its label; a removable row needs a named control.

FileUpload.FileUploadPreset

type · packages/mixins-ui/src/fileUpload.ts:1315

type FileUploadPreset = Pick<
  FileUploadView<never>,
  'style' | 'words' | 'picture' | 'itemActions' | 'progress'
> & {
  readonly mixins?: MixinList<never>
}

What a FileUpload is given once: its look, its words and the drawings it is handed, none of which holds a Message or reads the Model. sort reads the Model each draw and routes hold Messages, so both stay at the call.

FileUpload.FileUploadSlots

const · packages/mixins-ui/src/fileUpload.ts:729

const FileUploadSlots: Slots.Contract<{ readonly root: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>; readonly input: Slot.UnnamedSlot<Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>, readonly [Event.EventToken<"change">, Event.EventToken<"keydown">], readonly [Attr.AttrToken<"aria-invalid">, Attr.AttrToken<"aria-describedby">, Attr.AttrToken<"disabled">], readonly Slot.RequirementName[], boolean>; readonly picker: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>; readonly prompt: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>; readonly browse: Slot.UnnamedSlot<Capability.Capability<"Container", readonly [Capability.Capability<"Interactive", readonly [Capability.Capability<"Base", readonly []>]>]>, readonly Slot.EventName[], readonly Slot.AttributeName[], readonly Slot.RequirementName[], boolean>; readonly constraints: Slot.UnnamedSlot<Ca …;

The anatomy. The input is a native file input drawn first, a transparent pixel rather than hidden, and the picker is its label, always its next sibling, so the browser opens the dialog for a press on the picker and for Enter or Space on the input, and the picker rings when the input has keyboard focus. The picker also owns the drag events and data-dragging. A recipe's layout only restyles it.

FileUpload.FileUploadView

interface · packages/mixins-ui/src/fileUpload.ts:871

interface FileUploadView<Outer> {
  readonly model: Model
  readonly onMessage: (message: Message) => NoInfer<Outer>
  readonly label: string
  readonly name?: string | undefined
  readonly required?: boolean | undefined
  readonly disabled?: boolean | undefined
  readonly readOnly?: boolean | undefined
  readonly invalid?: boolean | undefined
  readonly description?: string | undefined
  readonly picture?: ((url: Option.Option<string>) => Html) | undefined
  readonly itemActions?: ((entry: Entry) => ReadonlyArray<Html>) | undefined
  readonly progress?: Progress | undefined
  readonly routes?: ReadonlyArray<Route<NoInfer<Outer>>> | undefined
  readonly sort?:
    | {
        readonly input: unknown
        readonly mixin: MixinValue<Outer>
      }
    | undefined
  readonly words?: Partial<FileUploadWords> | undefined
  readonly style?: NamedStyle<typeof FileUploadSlots> | undefined
  readonly mixins?: MixinList<Outer> | undefined
}

FileUpload.FileUploadWords

interface · packages/mixins-ui/src/fileUpload.ts:803

interface FileUploadWords {
  readonly prompt: string
  readonly list: string
  readonly remove: string
  readonly cancel: string
  readonly retry: string
  readonly clear: string
  readonly grip: string
  readonly uploading: string
  readonly constraints: string
  readonly constraintsCount: string
  readonly constraintsSize: string
  readonly summary: string
  readonly held: string
  readonly queued: string
  readonly done: string
  readonly failedReason: string
  readonly added: string
  readonly refused: string
  readonly removed: string
  readonly cleared: string
  readonly uploaded: string
  readonly failedNotice: string
  readonly refusedKind: string
  readonly refusedTooLarge: string
  readonly refusedTooMany: string
  readonly refusedDuplicate: string
  readonly refusedNotFiles: string
}

Every word the field draws, with {name}, {count}, {max}, {size} and {reason} standing for what a sentence is about. Text, never functions: a view input holds no nested function.

FileUpload.ids

function · packages/mixins-ui/src/fileUpload.ts:1425

function ids(model: Model): ReadonlyArray<string>

The entries' ids in drawn order, for a sort Behavior's items.

FileUpload.init

function · packages/mixins-ui/src/fileUpload.ts:223

function init(options: InitOptions): Model

Throws, naming the option, for what no field can honour.

FileUpload.InitialFile

interface · packages/mixins-ui/src/fileUpload.ts:189

interface InitialFile {
  readonly id: string
  readonly name: string
  readonly size: number
  readonly type: string
  readonly url: string
}

FileUpload.InitOptions

interface · packages/mixins-ui/src/fileUpload.ts:198

interface InitOptions {
  readonly id: string
  readonly multiple?: boolean | undefined
  readonly accept?: ReadonlyArray<string> | undefined
  readonly maxSize?: number | undefined
  readonly maxFiles?: number | undefined
  readonly previews?: boolean | undefined
  readonly lanes?: number | undefined
  readonly initial?: ReadonlyArray<InitialFile> | undefined
}

FileUpload.Job

const · packages/mixins-ui/src/fileUpload.ts:1344

const Job: Schema.Struct<{
  readonly id: Schema.String
  readonly attempt: Schema.Number
  readonly file: Schema.instanceOf<File, File>
}>

The send a lane is running: what the application's transport is given.

FileUpload.jobIn

function · packages/mixins-ui/src/fileUpload.ts:1355

function jobIn(model: Model, lane: number): Option.Option<Job>

What lane lane is sending now.

FileUpload.lane

function · packages/mixins-ui/src/fileUpload.ts:1394

function lane<Parent, ParentMessage, Services = never>(
  options: LaneOptions<Parent, ParentMessage, Services> & {
    readonly lane: number
  },
): {
  modelToDependencies: (parent: Parent) => {
    job: Option.Option<{
      readonly id: string
      readonly attempt: number
      readonly file: File
    }>
  }
  dependenciesToStream: ({
    job,
  }: {
    readonly job: Option.Option<Job>
  }) => Stream.Stream<ParentMessage, never, Services>
}

The callbacks of one lane's Subscription entry, for entry(FileUpload.laneFields, FileUpload.lane({ lane: 0, … })). One entry per lane keeps an upload from restarting when another finishes; lanes makes them all.

FileUpload.laneFields

const · packages/mixins-ui/src/fileUpload.ts:1352

const laneFields = { job }

The dependencies of a lane's Subscription entry: its job, none while the lane is free.

FileUpload.LaneOptions

interface · packages/mixins-ui/src/fileUpload.ts:1378

interface LaneOptions<Parent, ParentMessage, Services> {
  readonly model: (parent: Parent) => Model
  readonly send: (job: Job) => Stream.Stream<ParentMessage, never, Services>
}

FileUpload.lanes

function · packages/mixins-ui/src/fileUpload.ts:1410

function lanes<Parent, ParentMessage, Services = never>(
  options: LaneOptions<Parent, ParentMessage, Services> & {
    readonly count: number
  },
): {
  readonly [x: string]: Subscription.EntryWithoutKeepAlive<
    Parent,
    ParentMessage,
    {
      readonly job: Option.Option<{
        readonly id: string
        readonly attempt: number
        readonly file: File
      }>
    },
    Services
  > &
    SubscriptionBrand
}

Every lane's Subscription entry for count lanes, so an application cannot wire fewer entries than init({ lanes }) asked for. Take the count from the one constant that feeds both.

FileUpload.Message

const · packages/mixins-ui/src/fileUpload.ts:136

const Message: MessageUnion<{
  readonly Offered: {
    readonly files: Schema.$Array<Schema.instanceOf<File, File>>
    readonly by: Schema.Literals<readonly ['pick', 'drop', 'paste']>
  }
  readonly DragEntered: {}
  readonly DragLeft: {}
  readonly Removed: { readonly id: Schema.String }
  readonly RemovedLast: {}
  readonly Cleared: {}
  readonly DismissedRefusals: {}
  readonly Retried: { readonly id: Schema.String }
  readonly Previewed: {
    readonly previews: Schema.$Array<
      Schema.Struct<{ readonly id: Schema.String; readonly url: Schema.String }>
    >
  }
  readonly Progressed: {
    readonly id: Schema.String
    readonly attempt: Schema.Number
    readonly loaded: Schema.Number
    readonly total: Schema.Number
  }
  readonly Succeeded: {
    readonly id: Schema.String
    readonly attempt: Schema.Number
    readonly url: Schema.OptionFromNullOr<Schema.String>
  }
  readonly Failed: {
    readonly id: Schema.String
    readonly attempt: Schema.Number
    readonly reason: Schema.String
    readonly retryable: Schema.Boolean
  }
  readonly CompletedSync: {}
  readonly CompletedFocus: {}
  readonly CompletedRevoke: {}
}>

FileUpload.Model

const · packages/mixins-ui/src/fileUpload.ts:114

const Model: Schema.Struct<{ readonly id: Schema.String; readonly multiple: Schema.Boolean; readonly accept: Schema.$Array<Schema.String>; readonly maxSize: Schema.OptionFromNullOr<Schema.Number>; readonly maxFiles: Schema.OptionFromNullOr<Schema.Number>; readonly previews: Schema.Boolean; readonly lanes: Schema.Number; readonly entries: Schema.$Array<Schema.Struct<{ readonly id: Schema.String; readonly name: Schema.String; readonly size: Schema.Number; readonly type: Schema.String; readonly source: TaggedUnion<{ readonly Local: { readonly file: Schema.instanceOf<File, File>; }; readonly Stored: { readonly url: Schema.String; }; }>; readonly preview: Schema.OptionFromNullOr<Schema.String>; readonly attempts: Schema.Number; readonly status: TaggedUnion<{ readonly Held: {}; readonly Queued: {}; readonly Uploading: { readonly attempt: Schema.Number; readonly lane: Schema.Number; readonly loaded: Schema.Number; readonly total: Schema.Number; }; readonly Done: { readonly url: Schema.OptionFromNullOr<Schema.String>; }; readonly Failed: { readonly reason: Schema.String; readonly retryable: Schema.Boolean; }; }>; }>>; readonly minted: Schema.Number; readonly dragging: Schema.Boolean; readonly refusals: Schema.$Array<TaggedUnion<{ readonly Kind: { readonly name: Schema.String; }; readonly TooLarge: { readonly name: Schema.String; readonly size: Schema.Number; readonly max: Schema.Number; }; readonly TooMany: { readonly max: Schema.Number; }; readonly Duplicate: { readonly name: Schema.String; }; r …;

FileUpload.Notice

const · packages/mixins-ui/src/fileUpload.ts:102

const Notice: TaggedUnion<{
  readonly Added: { readonly count: Schema.Number }
  readonly Refused: { readonly count: Schema.Number }
  readonly Removed: { readonly name: Schema.String }
  readonly Cleared: { readonly count: Schema.Number }
  readonly Uploaded: { readonly name: Schema.String }
  readonly Failed: {
    readonly name: Schema.String
    readonly reason: Schema.String
  }
  readonly Said: { readonly text: Schema.String }
}>

What the live region says; one sentence per change, never a percentage.

FileUpload.ordered

function · packages/mixins-ui/src/fileUpload.ts:1431

function ordered(model: Model, order: ReadonlyArray<string>): Model

The entries in the order of order (pass Reorder.apply(FileUpload.ids(model), move)); an id it lacks keeps its place at the end. The same Model when the order is unchanged.

FileUpload.OutMessage

const · packages/mixins-ui/src/fileUpload.ts:177

const OutMessage: MessageUnion<{
  readonly Picked: {
    readonly added: Schema.$Array<Schema.String>
    readonly replaced: Schema.$Array<Schema.String>
    readonly refused: Schema.$Array<
      TaggedUnion<{
        readonly Kind: { readonly name: Schema.String }
        readonly TooLarge: {
          readonly name: Schema.String
          readonly size: Schema.Number
          readonly max: Schema.Number
        }
        readonly TooMany: { readonly max: Schema.Number }
        readonly Duplicate: { readonly name: Schema.String }
        readonly NotFiles: {}
      }>
    >
  }
  readonly Removed: { readonly ids: Schema.$Array<Schema.String> }
}>

FileUpload.parts

function · packages/mixins-ui/src/fileUpload.ts:1014

function parts<Outer>(
  options: FileUploadView<Outer>,
  h: HtmlBuilder<Outer>,
): FileUploadParts

Draws the field's pieces apart; view is parts in order, so there is one drawing.

FileUpload.Refusal

const · packages/mixins-ui/src/fileUpload.ts:89

const Refusal: TaggedUnion<{
  readonly Kind: { readonly name: Schema.String }
  readonly TooLarge: {
    readonly name: Schema.String
    readonly size: Schema.Number
    readonly max: Schema.Number
  }
  readonly TooMany: { readonly max: Schema.Number }
  readonly Duplicate: { readonly name: Schema.String }
  readonly NotFiles: {}
}>

Why a file was not listed.

FileUpload.released

function · packages/mixins-ui/src/fileUpload.ts:1538

function released(model: Model): Return<Model, Message>

Lets go of every preview: call it from the Message that drops the widget (a route change, a dialog closing). Nothing revokes on unmount, so without it the object URLs live until the document unloads.

FileUpload.removeId

function · packages/mixins-ui/src/fileUpload.ts:311

function removeId(id: string, entryId: string): string

The id of an entry's remove button, which takes the focus when its neighbour leaves.

FileUpload.Route

type · packages/mixins-ui/src/fileUpload.ts:869

type Route<Outer> = Behaviors.Keys.Route<Model, Outer>

FileUpload.settled

function · packages/mixins-ui/src/fileUpload.ts:1501

function settled(model: Model): Model

The Model as a draft or a server may keep it: uploaded files become stored ones, every other local file goes, and what only a live page holds (dragging, refusals, the notice, object URLs) is cleared.

FileUpload.sizeText

function · packages/mixins-ui/src/fileUpload.ts:299

function sizeText(bytes: number): string

1536 as 1.5 kB, 1234567 as 1.2 MB: decimal units, one decimal from a kilobyte up.

FileUpload.Source

const · packages/mixins-ui/src/fileUpload.ts:51

const Source: TaggedUnion<{
  readonly Local: { readonly file: Schema.instanceOf<File, File> }
  readonly Stored: { readonly url: Schema.String }
}>

Where an entry's bytes are.

FileUpload.Status

const · packages/mixins-ui/src/fileUpload.ts:60

const Status: TaggedUnion<{
  readonly Held: {}
  readonly Queued: {}
  readonly Uploading: {
    readonly attempt: Schema.Number
    readonly lane: Schema.Number
    readonly loaded: Schema.Number
    readonly total: Schema.Number
  }
  readonly Done: { readonly url: Schema.OptionFromNullOr<Schema.String> }
  readonly Failed: {
    readonly reason: Schema.String
    readonly retryable: Schema.Boolean
  }
}>

An entry's place in the send. attempt counts sends of the entry; a Message of another attempt is stale.

FileUpload.update

function · packages/mixins-ui/src/fileUpload.ts:590

function update(model: Model, message: Message): Step

The field after message; the same Model when nothing changes.

FileUpload.view

function · packages/mixins-ui/src/fileUpload.ts:1275

function view<Outer>(
  options: FileUploadView<Outer>,
  h: HtmlBuilder<Outer>,
): Html

The field: input, picker, description and constraints, errors, status, summary and list, in that order.

FileUpload.without

function · packages/mixins-ui/src/fileUpload.ts:1453

function without(
  model: Model,
  removed: ReadonlyArray<string>,
): Return<Model, Message>

Removes entries the application chose to drop; focus stays where it is.

FileUpload.words

const · packages/mixins-ui/src/fileUpload.ts:839

const words = {
  prompt,
  list,
  remove,
  cancel,
  retry,
  clear,
  grip,
  uploading,
  constraints,
  constraintsCount,
  constraintsSize,
  summary,
  held,
  queued,
  done,
  failedReason,
  added,
  refused,
  removed,
  cleared,
  uploaded,
  failedNotice,
  refusedKind,
  refusedTooLarge,
  refusedTooMany,
  refusedDuplicate,
  refusedNotFiles,
}

The defaults, in English.