# `Ascii.Phoenix.Components`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/phoenix/components.ex#L2)

Function components for drawing pieces in Phoenix, without JavaScript.

`ascii/1` draws one frame, frame 0 by default: upstream's own rule is
that frame 0 is a good still, and it is all a reader who prefers reduced
motion sees, and what a dead view or an email gets. To play a piece, see
`Ascii.Phoenix.player/1`.

    <Ascii.Phoenix.Components.ascii piece="donut" />
    <Ascii.Phoenix.Components.ascii piece="night-coast" label="a lighthouse at night" />
    <Ascii.Phoenix.Components.ascii piece="elixir" mono class="logo" />
    <Ascii.Phoenix.Components.ascii piece="big-text" ink={["#ff5f6d", "#ffc371"]} />

`frame/1` draws a frame you already have, from an `Ascii.Player` your
LiveView subscribes to, say.

Only available when `phoenix_live_view` is a dependency.

# `ascii`

One frame of a piece as a `<pre>`.

A text piece is its text, in the page's own colour, or in spans of an
`ink`, and of colours for its `parts`. A coloured piece is its text in
spans of its palette, over its `ground`; `mono` draws it in one ink
instead. The `<pre>` is `role="img"`, labelled with `label`, or with
what the piece tells of its options (`Ascii.describe/1`): a gauge's
reading, a boot log's steps, else the piece's name and note.

## Attributes

* `piece` (`:any`) (required) - a slug or a module.
* `t` (`:float`) - the time to draw, in seconds. Defaults to `0.0`.
* `options` (`:map`) - the piece's options, checked against its defaults. Defaults to `%{}`.
* `mono` (`:boolean`) - draw a coloured piece in one ink. Defaults to `false`.
* `ink` (`:any`) - the colour of a piece in one ink: `"#rrggbb"`, or a list for a gradient. Defaults to `nil`.
* `gradient` (`:any`) - `:horizontal`, `:vertical` or `:diagonal`. Defaults to `nil`.
* `parts` (`:any`) - colours for its parts (see `Ascii.Parts`): a map, or `true` for its own. Defaults to `nil`.
* `paper` (`:boolean`) - dark ink on a light page. Defaults to `false`.
* `now` (`:any`) - a DateTime for pieces that read the clock. Defaults to `nil`.
* `label` (`:string`) - what the picture shows; by default the piece tells it (`Ascii.describe/1`). Defaults to `nil`.
* Global attributes are accepted.

# `frame`

A frame you already have as a `<pre>`, drawn as `ascii/1` draws one: for
frames from an `Ascii.Player` your LiveView subscribes to, or from
`Ascii.frame/3`. Each row is an element of its own, so as the frame
changes LiveView sends only the rows that did.

    <Ascii.Phoenix.Components.frame frame={@frame} label="the Elixir logo" />

## Attributes

* `frame` (`Ascii.Frame`) (required)
* `label` (`:string`) - what the picture shows. Defaults to `"ascii art"`.
* Global attributes are accepted.

---

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