# `Ascii.Pieces.Dissolve`
[🔗](https://github.com/houllette/ascii_art/blob/main/lib/ascii/pieces/dissolve.ex#L1)

Words that crumble to dust and condense into the next.

A word in smooth stroked capitals crumbles letter by letter, its dust
sinking out of each letter, while the next word's dust gathers onto its
strokes. Give it your own words: a greeting in many languages, the
stages of a job, a rotating tagline.

## Options

Give them to `Ascii.new/2` as `options:`, and new ones while it plays
with `Ascii.put_options/2` (or a Phoenix player's `options`): it starts
afresh with the new words.

  * `words` - the words, in turn, each held 1.6 seconds and then
    dissolving into the next over 2.6, the last into the first. A list,
    or comma-separated text (`"build,ship,rest"`, as from a form). In
    capitals whatever their case: the font has `A` to `Z`, `0` to `9`,
    `.`, `,`, `!`, `?`, `'`, `-` and the space, and draws `?` for any other
    character. The letters shrink to fit the longest word in the width.
    Empty words are dropped; with none left it says "hello". Default
    `["hello", "hola", "ciao", "salut"]`.

The frame is always 64 by 13.

## Colours

It has no parts to colour one by one: in one ink, or a gradient, with
`:ink` and `:gradient` (see `Ascii.Ink`). Its dust is in lighter
shades than its strokes, so one ink still reads as solid letters and
their dust.

## Keys and clicks

It takes none: it is words to read, and `Ascii.handle_event/2` ignores
every event. A Phoenix player given `interactive` and `notify` still
tells your LiveView where it was clicked.

## Screen readers

`Ascii.describe/1` reads the words, in turn: "dissolve: build, ship,
rest"; past six, "and N more". With no words but blanks it gives the
piece's name and note.

## Example

```elixir
words = Ascii.new!("dissolve", options: %{words: ["build", "ship", "rest"]}, ink: "#7fdbca")
{frame, _words} = Ascii.frame(words, 0.0)
{frame.cols, frame.rows}
#=> {64, 13}

Ascii.describe(words)
#=> "dissolve: build, ship, rest"
```

```heex
<Ascii.Phoenix.live_player id="hello" piece="dissolve" options={%{words: @greetings}} ink="#7fdbca" />
```

Ported from `src/pieces/dissolve.ts` in bas3line/ascii (MIT).

---

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