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

Rich text editor on a plain `contenteditable` (bold, italic, underline, strike, quote, code,
headings, lists, sub/superscript, indent, text direction, size, font, colors, alignment, links
and clean), plus its compact `variant="comment"` form for threads.

    <.text_editor field={@form[:body]} placeholder="Escreva..." />
    <.text_editor name="note" toolbar={[~w(bold italic underline), ~w(list-ordered list-bullet)]} />
    <.text_editor name="post" filled content_class="h-72" />

    <.text_editor name="comment" variant="comment" on_submit="comment"
      mentions={[%{handle: "juliana-moraes", label: "Juliana Moraes"}]}
      placeholder="Escreva um comentario" />

The HTML is submitted through a hidden input named like the field, and each edit fires a
bubbling `input` event, so `phx-change` runs. The HTML given to the editor is cleaned on the
server by `sanitize/2` (and again in the browser, as is pasted HTML): only formatting tags and
safe links stay. **Sanitize what you store as well.** A value sent by the server replaces the
text; the same value echoed back does not touch it.

`slash` opens a menu of blocks when "/" is typed at the start of a word; `variables` adds the
placeholders of a template (`{cliente}` is drawn as a chip and goes to the server as plain
text); the `:ai` slot is a button at the end of the toolbar (`on_ai` is pushed with the HTML and
the selected text; answer with `insert_html/3`); `footer` draws a bar with a hint and the word
count. In a comment, "@" opens the list of `mentions` (chips sent as `@handle`) and
Ctrl/Cmd+Enter submits (`on_submit`).

Three toolbar buttons are opt-in: `mark` (highlight), `variable` and `image`. `image` asks for
the address and description, or, with `on_image`, pushes the event so the app can upload the
file and answer with `insert_image/4`.

The behaviour lives in the `LedgerUI.TextEditor` hook (`text_editor.js`); the editor needs a
stable `id` (from `field` or `name`).

`text_editor_content/1` shows saved HTML read-only, in the editor's type.

# `comment_editor`

Same as `text_editor/1` (same attributes and slots), under the name the design vitrine uses.
## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `name` (`:string`) - Defaults to `nil`.
* `value` (`:string`) - Defaults to `nil`.
* `field` (`Phoenix.HTML.FormField`) - Defaults to `nil`.
* `label` (`:string`) - Defaults to `nil`.
* `help` (`:string`) - Defaults to `nil`.
* `errors` (`:list`) - Defaults to `[]`.
* `placeholder` (`:string`) - Defaults to `nil`.
* `toolbar` (`:list`) - Defaults to `[["bold", "italic", "underline", "strike"], ["blockquote", "code-block"], ["header-1", "header-2"], ["list-ordered", "list-bullet"], ["script-sub", "script-super"], ["indent-minus1", "indent-plus1"], ["direction-rtl"], ["size"], ["header"], ["color", "background"], ["font"], ["align"], ["clean"]]`.
* `filled` (`:boolean`) - Defaults to `false`.
* `content_class` (`:any`) - Defaults to `nil`.
* `link_label` (`:string`) - Defaults to `"Enter link:"`.
* `tool_labels` (`:map`) - Defaults to `%{}`.
* `on_image` (`:string`) - Defaults to `nil`.
* `images` (`:boolean`) - Defaults to `false`.
* `image_label` (`:string`) - Defaults to `"Image URL:"`.
* `image_alt_label` (`:string`) - Defaults to `"Description"`.
* `image_save_label` (`:string`) - Defaults to `"Insert"`.
* `save_label` (`:string`) - Defaults to `"Save"`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `on_change` (`:string`) - Defaults to `nil`.
* `debounce` (`:integer`) - Defaults to `300`.
* `target` (`:any`) - Defaults to `nil`.
* `variant` (`:string`) - Defaults to `"comment"`. Must be one of `"default"`, or `"comment"`.
* `slash` (`:boolean`) - Defaults to `false`.
* `slash_items` (`:list`) - Defaults to `[%{label: "Text", key: "paragraph", hint: "Plain paragraph", icon: "¶"}, %{label: "Heading 1", key: "h1", hint: "Big section title", icon: "H1"}, %{label: "Heading 2", key: "h2", hint: "Medium section title", icon: "H2"}, %{label: "Bulleted list", key: "bullet", hint: "A simple list", icon: "•"}, %{label: "Numbered list", key: "ordered", hint: "A list with order", icon: "1."}, %{label: "Quote", key: "quote", hint: "Highlight a passage", icon: "❝"}, %{label: "Code block", key: "code", hint: "Monospaced text", icon: "</>"}, %{label: "Divider", key: "divider", hint: "A horizontal rule", icon: "—"}]`.
* `on_slash` (`:string`) - Defaults to `nil`.
* `slash_title` (`:string`) - Defaults to `"Insert"`.
* `variables` (`:list`) - Defaults to `[]`.
* `variable_label` (`:string`) - Defaults to `"Variable"`.
* `variable_title` (`:string`) - Defaults to `"Insert variable"`.
* `mentions` (`:list`) - Defaults to `[]`.
* `mention_title` (`:string`) - Defaults to `"Mention someone"`.
* `mention_button` (`:boolean`) - Defaults to `true`.
* `mention_label` (`:string`) - Defaults to `"Mention"`.
* `on_ai` (`:string`) - Defaults to `nil`.
* `on_submit` (`:string`) - Defaults to `nil`.
* `submit_label` (`:string`) - Defaults to `"Comment"`.
* `submit_key` (`:any`) - Defaults to `"Ctrl ↵"`.
* `submit_hint` (`:string`) - Text after the shortcut ("to send"). Defaults to `nil`.
* `bar` (`:boolean`) - Defaults to `true`.
* `clear_on_submit` (`:boolean`) - Defaults to `true`.
* `footer` (`:boolean`) - Defaults to `false`.
* `hint` (`:string`) - Defaults to `nil`.
* `words_label` (`:string`) - Defaults to `"words"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `actions` - The buttons of a comment's bar, before the submit button (attach...).
* `ai` - The content of a button at the end of the toolbar that asks the assistant.
* `attachments` - What a comment carries (files as chips), between the text and the bar.

# `insert_html`

Pushes `html` (sanitized) to be inserted at the caret of the editor `id`, replacing the
selection. Answer to `on_ai`, `on_slash` and similar events.

# `insert_image`

Inserts an `<img>` at the caret of the editor `id` (answer to `on_image`). `src` must be
`http(s)` or a path of your own host.

# `rich_text_editor`

Same as `text_editor/1` (same attributes and slots), under the name the design vitrine uses.
## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `name` (`:string`) - Defaults to `nil`.
* `value` (`:string`) - Defaults to `nil`.
* `field` (`Phoenix.HTML.FormField`) - Defaults to `nil`.
* `label` (`:string`) - Defaults to `nil`.
* `help` (`:string`) - Defaults to `nil`.
* `errors` (`:list`) - Defaults to `[]`.
* `placeholder` (`:string`) - Defaults to `nil`.
* `toolbar` (`:list`) - Defaults to `[["bold", "italic", "underline", "strike"], ["blockquote", "code-block"], ["header-1", "header-2"], ["list-ordered", "list-bullet"], ["script-sub", "script-super"], ["indent-minus1", "indent-plus1"], ["direction-rtl"], ["size"], ["header"], ["color", "background"], ["font"], ["align"], ["clean"]]`.
* `filled` (`:boolean`) - Defaults to `false`.
* `content_class` (`:any`) - Defaults to `nil`.
* `link_label` (`:string`) - Defaults to `"Enter link:"`.
* `tool_labels` (`:map`) - Defaults to `%{}`.
* `on_image` (`:string`) - Defaults to `nil`.
* `images` (`:boolean`) - Defaults to `false`.
* `image_label` (`:string`) - Defaults to `"Image URL:"`.
* `image_alt_label` (`:string`) - Defaults to `"Description"`.
* `image_save_label` (`:string`) - Defaults to `"Insert"`.
* `save_label` (`:string`) - Defaults to `"Save"`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `on_change` (`:string`) - Defaults to `nil`.
* `debounce` (`:integer`) - Defaults to `300`.
* `target` (`:any`) - Defaults to `nil`.
* `variant` (`:string`) - Defaults to `"default"`. Must be one of `"default"`, or `"comment"`.
* `slash` (`:boolean`) - Defaults to `false`.
* `slash_items` (`:list`) - Defaults to `[%{label: "Text", key: "paragraph", hint: "Plain paragraph", icon: "¶"}, %{label: "Heading 1", key: "h1", hint: "Big section title", icon: "H1"}, %{label: "Heading 2", key: "h2", hint: "Medium section title", icon: "H2"}, %{label: "Bulleted list", key: "bullet", hint: "A simple list", icon: "•"}, %{label: "Numbered list", key: "ordered", hint: "A list with order", icon: "1."}, %{label: "Quote", key: "quote", hint: "Highlight a passage", icon: "❝"}, %{label: "Code block", key: "code", hint: "Monospaced text", icon: "</>"}, %{label: "Divider", key: "divider", hint: "A horizontal rule", icon: "—"}]`.
* `on_slash` (`:string`) - Defaults to `nil`.
* `slash_title` (`:string`) - Defaults to `"Insert"`.
* `variables` (`:list`) - Defaults to `[]`.
* `variable_label` (`:string`) - Defaults to `"Variable"`.
* `variable_title` (`:string`) - Defaults to `"Insert variable"`.
* `mentions` (`:list`) - Defaults to `[]`.
* `mention_title` (`:string`) - Defaults to `"Mention someone"`.
* `mention_button` (`:boolean`) - Defaults to `true`.
* `mention_label` (`:string`) - Defaults to `"Mention"`.
* `on_ai` (`:string`) - Defaults to `nil`.
* `on_submit` (`:string`) - Defaults to `nil`.
* `submit_label` (`:string`) - Defaults to `"Comment"`.
* `submit_key` (`:any`) - Defaults to `"Ctrl ↵"`.
* `submit_hint` (`:string`) - Text after the shortcut ("to send"). Defaults to `nil`.
* `bar` (`:boolean`) - Defaults to `true`.
* `clear_on_submit` (`:boolean`) - Defaults to `true`.
* `footer` (`:boolean`) - Defaults to `false`.
* `hint` (`:string`) - Defaults to `nil`.
* `words_label` (`:string`) - Defaults to `"words"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `actions` - The buttons of a comment's bar, before the submit button (attach...).
* `ai` - The content of a button at the end of the toolbar that asks the assistant.
* `attachments` - What a comment carries (files as chips), between the text and the bar.

# `sanitize`

```elixir
@spec sanitize(term(), keyword()) :: String.t()
```

Cleans the HTML of an editor: only formatting tags stay (`p div br span b strong i em u s strike
del sub sup blockquote pre code h1-h4 ul ol li a hr mark`, plus `img` with `images: true`).

Attributes are dropped except `href` of a link (`http(s)`, `mailto:`, `tel:`, a path or `#`),
`src`/`alt`/`width`/`height` of an image (`http(s)` or a path of your own host, never `data:`,
`javascript:` or `//host`; `alt` up to 300 characters, sizes 1 to 4000), `dir` and a `style`
limited to a few typographic properties. Everything else is dropped, text is escaped.

    iex> LedgerUI.Components.TextEditor.sanitize(~S|<p onclick="x()">Hi <b>you</b><script>bad()</script></p>|)
    "<p>Hi <b>you</b>bad()</p>"

# `text_editor`

Renders a rich text editor.
## Attributes

* `id` (`:string`) - Defaults to `nil`.
* `name` (`:string`) - Defaults to `nil`.
* `value` (`:string`) - Defaults to `nil`.
* `field` (`Phoenix.HTML.FormField`) - Defaults to `nil`.
* `label` (`:string`) - Defaults to `nil`.
* `help` (`:string`) - Defaults to `nil`.
* `errors` (`:list`) - Defaults to `[]`.
* `placeholder` (`:string`) - Defaults to `nil`.
* `toolbar` (`:list`) - Defaults to `[["bold", "italic", "underline", "strike"], ["blockquote", "code-block"], ["header-1", "header-2"], ["list-ordered", "list-bullet"], ["script-sub", "script-super"], ["indent-minus1", "indent-plus1"], ["direction-rtl"], ["size"], ["header"], ["color", "background"], ["font"], ["align"], ["clean"]]`.
* `filled` (`:boolean`) - Defaults to `false`.
* `content_class` (`:any`) - Defaults to `nil`.
* `link_label` (`:string`) - Defaults to `"Enter link:"`.
* `tool_labels` (`:map`) - Defaults to `%{}`.
* `on_image` (`:string`) - Defaults to `nil`.
* `images` (`:boolean`) - Defaults to `false`.
* `image_label` (`:string`) - Defaults to `"Image URL:"`.
* `image_alt_label` (`:string`) - Defaults to `"Description"`.
* `image_save_label` (`:string`) - Defaults to `"Insert"`.
* `save_label` (`:string`) - Defaults to `"Save"`.
* `disabled` (`:boolean`) - Defaults to `false`.
* `on_change` (`:string`) - Defaults to `nil`.
* `debounce` (`:integer`) - Defaults to `300`.
* `target` (`:any`) - Defaults to `nil`.
* `variant` (`:string`) - Defaults to `"default"`. Must be one of `"default"`, or `"comment"`.
* `slash` (`:boolean`) - Defaults to `false`.
* `slash_items` (`:list`) - Defaults to `[%{label: "Text", key: "paragraph", hint: "Plain paragraph", icon: "¶"}, %{label: "Heading 1", key: "h1", hint: "Big section title", icon: "H1"}, %{label: "Heading 2", key: "h2", hint: "Medium section title", icon: "H2"}, %{label: "Bulleted list", key: "bullet", hint: "A simple list", icon: "•"}, %{label: "Numbered list", key: "ordered", hint: "A list with order", icon: "1."}, %{label: "Quote", key: "quote", hint: "Highlight a passage", icon: "❝"}, %{label: "Code block", key: "code", hint: "Monospaced text", icon: "</>"}, %{label: "Divider", key: "divider", hint: "A horizontal rule", icon: "—"}]`.
* `on_slash` (`:string`) - Defaults to `nil`.
* `slash_title` (`:string`) - Defaults to `"Insert"`.
* `variables` (`:list`) - Defaults to `[]`.
* `variable_label` (`:string`) - Defaults to `"Variable"`.
* `variable_title` (`:string`) - Defaults to `"Insert variable"`.
* `mentions` (`:list`) - Defaults to `[]`.
* `mention_title` (`:string`) - Defaults to `"Mention someone"`.
* `mention_button` (`:boolean`) - Defaults to `true`.
* `mention_label` (`:string`) - Defaults to `"Mention"`.
* `on_ai` (`:string`) - Defaults to `nil`.
* `on_submit` (`:string`) - Defaults to `nil`.
* `submit_label` (`:string`) - Defaults to `"Comment"`.
* `submit_key` (`:any`) - Defaults to `"Ctrl ↵"`.
* `submit_hint` (`:string`) - Text after the shortcut ("to send"). Defaults to `nil`.
* `bar` (`:boolean`) - Defaults to `true`.
* `clear_on_submit` (`:boolean`) - Defaults to `true`.
* `footer` (`:boolean`) - Defaults to `false`.
* `hint` (`:string`) - Defaults to `nil`.
* `words_label` (`:string`) - Defaults to `"words"`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `actions` - The buttons of a comment's bar, before the submit button (attach...).
* `ai` - The content of a button at the end of the toolbar that asks the assistant.
* `attachments` - What a comment carries (files as chips), between the text and the bar.

# `text_editor_content`

Shows saved rich text, read-only, in the editor's type. `value` is escaped unless it is already
marked safe (`{:safe, html}` / `Phoenix.HTML.raw/1`): pass safe HTML only after `sanitize/2`.
The inner block wins.

## Attributes

* `value` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `inner_block`

---

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