# `LedgerUI.Components.Upload`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui/components/upload.ex#L1)

File uploads built on LiveView uploads: the drop panel with each file's progress, errors and
cancel button, and the styled "Choose File" button.

    # mount
    socket |> allow_upload(:photos, accept: ~w(.jpg .png), max_entries: 4)

    <.form for={@form} phx-change="validate" phx-submit="save">
      <.upload upload={@uploads.photos} on_cancel="cancel-upload" columns={2}
        hint="PDF, XML ou CSV · até 10 MB cada" />
    </.form>

    def handle_event("cancel-upload", %{"ref" => ref}, socket),
      do: {:noreply, cancel_upload(socket, :photos, ref)}

`upload/1` renders `live_file_input` itself, so it must sit inside the form that has the
`phx-change` LiveView uploads need. Dropping files on the panel works through `phx-drop-target`;
the `LedgerUI.Upload` hook (`priv/static/ledger_ui/hooks/upload.js`) only paints the `over`
state while files are dragged over it.

The pieces it is made of are public and stateless, for custom layouts and for the design
gallery: `upload_drop/1` (the dashed drop area), `upload_zone/1` (the compact zone with the
kit's variants), `upload_file/1` (a file card), `upload_thumbs/1` and `upload_button/1`.

Deviation from the README: `upload_button/1` is a `<label>` around the file input (as the
README says), so the design's `<button>` is not reproduced byte for byte; `variant` accepts the
design's zone variants too (`solid glow outline soft bordered flat glass dim`).

# `upload`

Renders the drop panel and the list of chosen files.
## Attributes

* `upload` (`Phoenix.LiveView.UploadConfig`) (required)
* `id` (`:string`) - Defaults to `nil`.
* `bordered` (`:boolean`) - Defaults to `false`.
* `filled` (`:boolean`) - Defaults to `false`.
* `columns` (`:integer`) - Defaults to `1`. Must be one of `1`, `2`, `3`, or `4`.
* `variant` (`:string`) - Defaults to `"canvas"`. Must be one of `"canvas"`, `"pond"`, `"solid"`, `"glow"`, `"outline"`, `"soft"`, `"bordered"`, `"flat"`, `"glass"`, or `"dim"`.
* `color` (`:string`) - Defaults to `"primary"`. Must be one of `"neutral"`, `"primary"`, `"secondary"`, `"info"`, `"success"`, `"warning"`, `"error"`, `"mono"`, `"white"`, or `"current"`.
* `shape` (`:string`) - Defaults to `"rounded"`. Must be one of `"rounded"`, `"pill"`, or `"square"`.
* `size` (`:string`) - Defaults to `nil`.Must be one of `nil`, `"md"`, or `"xl"`.
* `layout` (`:string`) - Defaults to `"panel"`. Must be one of `"panel"`, `"circle"`, or `"thumbs"`.
* `hint` (`:string`) - Defaults to `nil`.
* `browse` (`:string`) - Defaults to `nil`.
* `icon_path` (`:string`) - Defaults to `nil`.
* `drop_class` (`:any`) - Defaults to `nil`.
* `on_cancel` (`:any`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `previews` (`:boolean`) - Defaults to `true`.
* `error_texts` (`:map`) - Defaults to `%{too_large: "File is too large", too_many_files: "Too many files", external_client_failure: "Upload failed", not_accepted: "File of invalid type"}`.
* `browse_label` (`:string`) - Defaults to `"Browse"`.
* `drop_label` (`:string`) - Defaults to `"Drag & Drop your files or"`.
* `remove_label` (`:string`) - Defaults to `"Remove"`.
* `uploading_label` (`:string`) - Defaults to `"Uploading"`.
* `complete_label` (`:string`) - Defaults to `"Upload complete"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `label` - Replaces the text of the drop panel.

# `upload_button`

A button that opens the file chooser: a `<label>` with the button classes holding an invisible
file input. With `upload` it renders `live_file_input`; otherwise a plain `<input type="file">`.

    <.upload_button upload={@uploads.avatar}>Choose File</.upload_button>
    <.upload_button name="doc" variant="outline" size="sm">Attach</.upload_button>

## Attributes

* `upload` (`Phoenix.LiveView.UploadConfig`) - Defaults to `nil`.
* `name` (`:string`) - Defaults to `nil`.
* `multiple` (`:boolean`) - Defaults to `false`.
* `accept` (`:string`) - Defaults to `nil`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `color` (`:string`) - Defaults to `"neutral"`. Must be one of `"neutral"`, `"primary"`, `"secondary"`, `"info"`, `"success"`, `"warning"`, `"error"`, `"mono"`, `"white"`, or `"current"`.
* `variant` (`:string`) - Defaults to `"solid"`. Must be one of `"solid"`, `"glow"`, `"outline"`, `"soft"`, `"bordered"`, `"flat"`, `"glass"`, `"ghost"`, or `"dim"`.
* `size` (`:string`) - Defaults to `nil`.Must be one of `nil`, `""`, `"xs"`, `"sm"`, `"md"`, `"lg"`, or `"xl"`.
* `shape` (`:string`) - Defaults to `"rounded"`. Must be one of `"rounded"`, `"pill"`, or `"square"`.
* `icon` (`:boolean`) - Defaults to `false`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)

# `upload_drop`

The dashed drop area: icon, label with the browse link, and a hint.
## Attributes

* `drop_label` (`:string`) - Defaults to `"Drag & Drop your files or"`.
* `browse_label` (`:string`) - Defaults to `"Browse"`.
* `hint` (`:string`) - Defaults to `nil`.
* `over` (`:boolean`) - Draws the drag-over state. Defaults to `false`.
* `error` (`:boolean`) - Defaults to `false`.
* `for` (`:string`) - Id of the file input: the area becomes its `<label>`. Defaults to `nil`.
* `icon_path` (`:string`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `label` - Replaces the text of the area.

# `upload_file`

A file card: badge, name, status, progress bar and the remove (or retry) button.
## Attributes

* `name` (`:string`) (required)
* `ext` (`:string`) - The badge text (`XML`); the extension of `name` by default. Defaults to `nil`.
* `status` (`:string`) - The line under the name. Defaults to `nil`.
* `progress` (`:integer`) - Defaults to `0`.
* `state` (`:string`) - Defaults to `"progress"`. Must be one of `"progress"`, `"done"`, or `"error"`.
* `remove_label` (`:string`) - Defaults to `"Remove"`.
* `retry_label` (`:string`) - On an error: a retry button with this text. Defaults to `nil`.
* `removable` (`:boolean`) - Defaults to `true`.
* `on_remove` (`:any`) - An event name or a `%JS{}` for the remove button. Defaults to `nil`.
* `on_retry` (`:any`) - Defaults to `nil`.
* `ref` (`:string`) - Sent as `phx-value-ref` with the events. Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `preview` - Replaces the extension badge (an image preview).

# `upload_thumbs`

The grid of 64px thumbnails.
## Attributes

* `count` (`:integer`) - Defaults to `3`.
* `columns` (`:integer`) - `--cols` (3 by default in the stylesheet). Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` - Your own tiles instead of `count` placeholders.

# `upload_zone`

The compact drop zone (`lu-upz`) with the kit's variants, colors, shapes and sizes.
## Attributes

* `variant` (`:string`) - Defaults to `"canvas"`. Must be one of `"canvas"`, `"pond"`, `"solid"`, `"glow"`, `"outline"`, `"soft"`, `"bordered"`, `"flat"`, `"glass"`, or `"dim"`.
* `color` (`:string`) - Defaults to `"primary"`. Must be one of `"neutral"`, `"primary"`, `"secondary"`, `"info"`, `"success"`, `"warning"`, `"error"`, `"mono"`, `"white"`, or `"current"`.
* `shape` (`:string`) - Defaults to `"rounded"`. Must be one of `"rounded"`, `"pill"`, or `"square"`.
* `size` (`:string`) - Defaults to `nil`.Must be one of `nil`, `"md"`, or `"xl"`.
* `for` (`:string`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block` (required)

---

*Consult [api-reference.md](api-reference.md) for complete listing*
