Renders the rich text editor.

Give it a form field, or a name and a value:

<.coelho_editor field={@form[:body]} />
<.coelho_editor name="page[intro_doc]" value={@draft["intro_doc"]} />

The second form is for a surface that has no changeset behind it — a JSONB draft whose keys are historical, a field posted straight into phx-change — where building a %Phoenix.HTML.FormField{} to satisfy the component would be building a fiction.

Losing the last keystrokes, and how not to

The editor writes into its hidden input and lets phx-change carry it, which means a phx-debounce can still be holding the last edit when the block leaves the DOM. Nothing arrives, and the writer loses what they typed last. Cancelling a draft, switching a tab, collapsing a section: each of those removes the editor, and each of those is where it bites.

:flush_event closes it. The hook pushes the document on the way out:

<.coelho_editor
  name="page[intro_doc]"
  value={@draft["intro_doc"]}
  flush_event="flush"
  flush_token={@generation}
/>

def handle_event("flush", %{"token" => token, "name" => name, "document" => document}, socket) do
  if token == to_string(socket.assigns.generation) do
    {:noreply, put_draft(socket, name, document)}
  else
    {:noreply, socket}
  end
end

The token comes back as a string. It travels as a DOM attribute, so whatever it was rendered from arrives as text: comparing it to an integer generation is always false, and every flush is dropped by the clause that was meant to catch the stale ones — the data loss :flush_event exists to prevent, failing silently.

The token is yours and the comparison is yours, because only the application knows what a generation is. It matters: cancelling a draft re-renders the editors, and the editors being torn down flush the content from before the cancellation. Without a token that the application bumps when it cancels, the flush puts back exactly what was just thrown away.

What the buttons show

An icon, drawn by Coelho.Icons, with the command's name as its tooltip and its accessible name — so a pointer and a screen reader are told the same thing. The names are English until :labels says otherwise, and a command the library does not draw shows its label as text instead, which is what one an application added does until it is given an icon:

<.coelho_editor
  field={@form[:body]}
  toolbar={~w(bold italic highlight)}
  icons={%{"highlight" => MyApp.Icons.highlight()}}
/>

An icon has to arrive already safe — a ~H sigil, Phoenix.HTML.raw/1, or a {:safe, iodata} — because it is rendered as markup rather than escaped. A plain string is escaped like any other text and shows as tag soup in the button, which is the right way round: markup is what an application states, never what it happens to hold.

An icon is sized by the --coelho-icon custom property, whether it is the library's or the application's — the stylesheet asks for an svg or an img inside the button rather than for a class, so one supplied without .coelho-icon is sized all the same.

What the field says

The link and caption field carries three strings, and they are English until an application says otherwise:

<.coelho_editor
  field={@form[:body]}
  labels={%{"link" => gettext("Link")}}
  field_labels={%{
    "link_label" => gettext("Link address"),
    "link_placeholder" => gettext("https://… then Enter"),
    "link_hint" => gettext("Empty the field to remove the link."),
    "caption_label" => gettext("Caption"),
    "caption_placeholder" => gettext("Describe this attachment")
  }}
/>

:labels names the toolbar's buttons and :field_labels what the field beside them says; they are separate because the first is a command and the second is a sentence. The hint is shown under the field while it is open, and there is no hint at all unless one is given — the gesture it describes, emptying the field to remove the link, is otherwise something a writer has to be told or discover.

Changing either redraws the toolbar, so a language switched mid-session reaches both.

Counting characters

:maxlength renders a counter beside the toolbar and keeps it in step. The count is Coelho.Document.text_length/1 — the text nodes concatenated, which is what the writer typed — and the server renders the first one, so an existing document does not read zero until the hook has started.

The attribute does not stop anyone typing. What it does is show the number and mark the counter with coelho-over past the limit; refusing the document is the schema's job, through limits: [max_text_length: …], and doing it in two places would let the two disagree.

Following a schema change

The container carries phx-update="ignore", so LiveView never patches what ProseMirror owns — which used to mean that a schema changed on a mounted editor was not picked up: the classes, the marks and the node types stayed the ones read at mount, and what the writer saw stopped matching what the page would render.

The hook now watches an exported-schema fingerprint on its own element and rebuilds the view when it moves, keeping the document. The toolbar is redrawn with it. Ids are untouched, so editor_id/1 and insert_node/3 go on working.

Attributes

• field (Phoenix.HTML.FormField) - a form field; give this or :name and :value. Defaults to nil.

• name (:string) - the hidden input's name, without a form field. Defaults to nil.

• value (:any) - the document, without a form field. Defaults to nil.

• id (:string) - defaults to the field's own id, suffixed. Defaults to nil.

• document_schema (Coelho.Schema) - the schema to edit against, Coelho.Schema.default/0 when omitted. Defaults to nil.

• schema_id (:string) - id of a coelho_schema/1 to read the schema from, instead of carrying it. Defaults to nil.

• toolbar (:list) - commands to show, in order; an empty list hides the toolbar. Any mark the schema declares is a command, as are align_left, align_center, align_right and align_justify where a node declares align, and heading_1 to heading_6 where its :level accepts the number — heading on its own makes the level the schema calls default. A {"insert", node: …, attrs: …, label: …} entry puts a declared inline void node at the cursor, and {"insert", text: …} puts characters there. Every command is filtered against the schema: a button is rendered only where its command can run, and only with a value the attribute's own validator accepts. Defaults to ["bold", "italic", "strike", "code", "link", "heading", "bullet_list", "ordered_list", "blockquote", "caption"].

• labels (:map) - command to label, for a toolbar that has to speak the reader's language. The label is the button's tooltip and its accessible name; anything left out keeps its English. Changing them on a mounted editor redraws the toolbar. Defaults to %{}.

• icons (:map) - command to icon, replacing what Coelho.Icons draws — one of them, or all. Each has to be safe markup already (a ~H sigil, Phoenix.HTML.raw/1, {:safe, iodata}), since it is rendered rather than escaped; a plain string is escaped and shows as tag soup. A command with no icon on either side shows its label as text

  Defaults to %{}.

• field_labels (:map) - what the link and caption field says, for an application with a translator. Keys: "link_label", "link_placeholder", "link_hint", "caption_label", "caption_placeholder", "caption_hint". Anything left out keeps its English

  Defaults to %{}.

• maxlength (:integer) - shows a character counter; does not enforce. Defaults to nil.

• flush_event (:string) - event pushed with the document when the editor leaves the DOM. Defaults to nil.

• flush_token (:any) - sent back with :flush_event, for the application to refuse a stale flush. It travels as a DOM attribute, so it arrives back as a string. Defaults to nil.

• upload (:any) - an %Phoenix.LiveView.UploadConfig{}; enables dropping and pasting files. Defaults to nil.

• debounce (:integer) - phx-debounce in milliseconds for the hidden input the document travels in. Without it every keystroke ships the whole document and the server decodes and validates it again — the cost that matters on a long document beside a live preview. LiveView reads the attribute off the element that emits the event and walks no ancestors, so it cannot be given from the outside: neither :rest, which lands on the root, nor the enclosing form reaches the input.

  Milliseconds and nothing else. LiveView's "blur" waits for a blur event on the element carrying the attribute, and a type="hidden" input never blurs — the change would be held for the life of the page.

  Pair it with :flush_event: a debounce still holding the last edit when the element goes loses it, and that is what the flush is for.

  An upload on the same form is fine. It did not use to be: anything that re-rendered the form while a change was still pending — an upload finishing was enough — patched this field with the server's older copy, and the editor went on holding the newer document while the field posted the older one. The field now follows the editor whenever it is handed a document the editor has already moved past

  Defaults to nil.

• placeholder (:string) - Defaults to nil.

• class (:string) - Defaults to nil.

• Global attributes are accepted.

Renders the schema once, for several editors to share.

Each editor otherwise carries the whole exported schema in a data- attribute of its own — 1.3 KB for the schema that ships, which six editors on a page turn into eight. Render this once and point the editors at it:

<.coelho_schema id="page-schema" document_schema={MyApp.RichText.schema()} />

<.coelho_editor
  name="page[intro_doc]"
  value={@draft["intro_doc"]}
  document_schema={MyApp.RichText.schema()}
  schema_id="page-schema"
/>

Give the editors the same :document_schema. :schema_id says where the exported JSON lives, not which schema it is: the editor still filters its toolbar and stamps its fingerprint from its own :document_schema, and an editor working from one schema while reading another is a mismatch that would show up as buttons quietly doing nothing. The fingerprints are compared in the browser, so the mismatch is an error and not a mystery.

The saving is on the first render. LiveView omits an unchanged dynamic from a diff, so the repetition does not cost anything again on every patch — but it is still eight kilobytes of the page that opens.

Attributes

• id (:string) (required)
• document_schema (Coelho.Schema) - the schema to export, Coelho.Schema.default/0 when omitted. Defaults to nil.

@spec editor_id(Phoenix.HTML.FormField.t() | String.t()) :: String.t()

The DOM id of the editor rendered for a form field.

What insert_node/3 needs to reach one editor rather than all of them.

@spec insert_node(Phoenix.LiveView.Socket.t(), map(), keyword()) ::
  Phoenix.LiveView.Socket.t()

Inserts a node at the editor's selection.

The way anything the server decides on reaches the document: an attachment it has just stored, a mention it has just resolved, an embed it has just fetched. The node is built server side, against the same schema that will validate it on the way back.

socket
|> Coelho.LiveView.insert_node(Coelho.Attachment.to_node(attachment),
     id: editor_id(@form[:body]),
     preview: MyApp.Uploads.url(attachment.key))

Options

• :id — which editor to insert into, as editor_id/1 returns it. push_event/3 reaches the whole page, so without this every editor on it inserts the node, which is only ever right when there is one.
• :preview — for the editor's eyes only: an attachment's URL, which the document does not carry and the renderer resolves again on every render.