` / `` ancestors, in the markdown and HTML modes they count delimiters. A stray popup is cosmetic β nothing is ever written to the document except by accepting a row. One case worth knowing about `#` specifically. In markdown a heading is `#` followed by a **space** β `# Notes` is a heading, `#notes` is a paragraph containing a tag, and the editor's hybrid preview agrees with MDEx on this. But a lone `#` on an otherwise empty line is a valid (empty) heading, so with `min_chars: 0` that single keystroke both renders as a heading and opens the tag popup. It resolves itself on the next character: a letter makes it a tag, a space makes it a heading. Set `min_chars: 1` if you would rather the popup never appear in that ambiguous moment, or `boundary: :not_line_start` to keep the popup off the first column entirely β then `#` opens a heading and `#tag` mid-line opens the popup, with no keystroke where both are live. ### Hashtag styling Configuring a `#` trigger also tells Leaf that `#` means "tag" in this editor, so hashtags render as tinted, slightly-italic tokens in the visual and hybrid surfaces instead of reading as ordinary prose. It is purely a decoration β the markdown stays `#tag` and serialization is unchanged. An editor with no `#` trigger gets no hashtag styling, so a document that uses `#` for issue numbers is left alone. ### Interaction β/β move (wrapping), Enter and Tab accept, Escape dismisses. While the popup is open Enter neither inserts a newline, nor continues a list, nor submits the surrounding form. Clicking a row does not steal focus from the editor. The popup is portaled to ``, anchored to the caret, flips above it when there is no room below, and never opens mid-IME-composition. ### Testing a trigger The popup lives entirely on the client, so a LiveView test drives the server half directly: render_hook(view, "suggest", %{"trigger" => "#", "query" => "eli", "seq" => 1}) assert_receive {:leaf_suggest, %{trigger: "#", query: "eli", seq: 1}} Popup DOM carries stable hooks for browser-level tests: the popup is `##{editor_id}-suggest`, rows are `[data-leaf-suggest-index]` and carry `data-leaf-suggest-value` and `data-leaf-suggest-kind` (`"result"` / `"create"`). ## Custom component tags (`preserve_tags`) > #### Read this before putting component tags through the editor {: .warning} > > Markdown holding custom tags β ``, ` β¦ ` β > **must** declare them in `preserve_tags`. Without it the visual and > hybrid surfaces flatten each one into loose paragraphs on the first > keystroke, and autosave writes that back over the original. Leaf logs > a warning (see below) the first time it sees an undeclared PascalCase > tag, but the declaration is what actually protects the content. <.leaf_editor id="post-content-editor" content={@content} preserve_tags={["Hero", "Showcase", "Note", "Audio", "EntityForm"]} /> A declared tag is pulled out before the markdown parser runs, rendered as an **atomic block** β non-editable, so nothing inside it can be corrupted in place β and restored verbatim on the way back out, so the source round-trips byte for byte. The block reads as a *preview of the component*, not as its source. Known attribute names map to typographic roles and are typeset in the editor's own prose voice: | Role | Attribute names | | --- | --- | | Eyebrow | `kicker`, `eyebrow`, `overline`, `badge`, `category` | | Title | `title`, `heading`, `headline`, `name`, and `label` with no link | | Supporting text | `subtitle`, `subheading`, `tagline`, `description`, `summary`, `caption`, `blurb`, `text`, `body`, `alt` | | Banner | `image`, `img`, `poster`, `thumbnail`, `cover`, `background`, `avatar`, `photo`, `banner`, and an image-shaped `src` | | Call to action | `label`/`cta`/`button` next to `href`/`url`/`link`/`to` | Children render as formatted text, so bold and links inside `β¦ ` are visible while you write. Anything with no role falls through to a small, faint source line β for those there is nothing better to say. A tag with nothing to show collapses to its nameplate. This is a convention, not a contract: Leaf has never seen your ``, so getting it wrong costs nothing beyond an attribute landing on the source line. The scale stays close to prose on purpose β a placeholder that reads like a document, not an imitation of the published component. **Double-click** a block to edit its raw source in place; β/Ctrl+Enter or the Save button commits, Escape cancels. When `preserve_tags` is missing a tag that the content uses, Leaf emits a one-off `Logger.warning` naming it. Disable with: config :leaf, warn_unpreserved_tags: false ## Security Note The deny-list regex sanitization in this component is a UX layer only. Consumers must still validate and allow-list content at the persistence boundary. ## Denying features `deny` removes affordances entirely β the markup is never rendered, and the matching client paths refuse to act, so it is one rule rather than a default a stray click can talk its way past. | Atom | Effect | | --- | --- | | `:links` | No link button; ``/`[β¦](β¦)` stripped from content | | `:images` | No image button; ` `/`` stripped from content | | `:video` | No video button | | `:visual_mode` | No visual tab, in any switcher | | `:hybrid_mode` | No hybrid tab, in any switcher | | `:markdown_mode` | No markdown tab, in any switcher | | `:html_mode` | No HTML tab, in any switcher | A host whose documents are built from custom component tags typically wants the markdown surface only β the visual surfaces cannot edit an atomic block's source anyway: <.leaf_editor id="content-editor" mode={:markdown} deny={[:visual_mode, :hybrid_mode]} β¦ /> Denying the mode the host also passed as `mode` falls back to the first allowed mode in `:hybrid`, `:visual`, `:markdown`, `:html` order. Denying *every* mode raises β it is always a mistake. When only one mode survives the switcher is hidden rather than rendered as a single dead tab. ## Commands from Parent Use `send_update/2`: send_update(Leaf, id: "my-editor", action: :insert_image, url: "https://...", alt: "description") send_update(Leaf, id: "my-editor", action: :set_content, content: "# Hello") send_update(Leaf, id: "my-editor", action: :set_mode, mode: :visual) send_update(Leaf, id: "my-editor", action: :flush, ref: "save-42") send_update(Leaf, id: "my-editor", action: :mark_saved) `:set_content` re-baselines the dirty snapshot by default β replacing the content programmatically is not a user edit, so an untouched editor still reads clean and `protect_navigation` does not prompt. Pass `mark_saved: false` to keep the old baseline (i.e. treat the new content as unsaved work). ## JS Setup Add to your app.js: import "../../../deps/leaf/priv/static/assets/leaf.js" let Hooks = { Leaf: window.LeafHooks.Leaf, // ... your other hooks } ### Checking the bundle is present and current Leaf does not bundle its own JS into the host β an editor whose hook never attaches renders, looks ordinary and does nothing at all. Two things guard against losing an afternoon to that: - If the hook has not attached shortly after paint, the editor logs a console error naming the likely causes. It stays on its loading shimmer rather than pretending to be an editor. - `window.LeafHooks.version` reports the version of the loaded bundle. Compare it against `Leaf.js_version/0` (which equals the `:leaf` application version) to catch a **vendored** copy that stayed behind after `mix deps.update leaf`: if Leaf.js_version() != vendored_version_from_somewhere do Logger.warning("Vendored leaf.js is stale") end The client does the same check itself whenever the server-rendered `data-leaf-js-version` disagrees with the loaded bundle, and warns. ## Gettext (optional) To enable translations, configure a gettext backend: config :leaf, :gettext_backend, MyApp.Gettext Otherwise, English strings are used as-is. Leaf ships its own catalog template at `priv/gettext/leaf.pot` β a host's `mix gettext.extract` cannot see msgids living in a dependency's source, so copy it in and merge instead of extracting: cp deps/leaf/priv/gettext/leaf.pot priv/gettext/leaf.pot mix gettext.merge priv/gettext Then translate `priv/gettext/
/LC_MESSAGES/leaf.po`. Lookups try the `"leaf"` domain first and fall back to the `"default"` domain, so hosts that would rather keep every string in `default.po` can append the msgids there and skip the extra domain. # `js_version` ```elixir @spec js_version() :: String.t() ``` The version of the JS bundle this library ships, as a string. Equals the `:leaf` application version. Hosts that **vendor** `priv/static/assets/leaf.js` into their own asset pipeline (rather than importing it from `deps/`) can compare this against `window.LeafHooks.version` to catch a copy that stayed behind after `mix deps.update leaf` β the editor renders identically either way, so a stale bundle is otherwise silent. # `leaf_editor` Renders a Leaf editor as a function component. This is a convenience wrapper around the `Leaf` LiveComponent. Import it in your view helpers: import Leaf, only: [leaf_editor: 1] Then use it in your templates: <.leaf_editor id="my-editor" content={@content} /> All attributes are passed through to the underlying LiveComponent. ## Attributes * `id` (`:string`) (required) * `content` (`:string`) - Defaults to `""`. * `mode` (`:atom`) - Defaults to `:hybrid`. Must be one of `:visual`, `:hybrid`, `:markdown`, or `:html`. * `preset` (`:atom`) - Defaults to `:advanced`. Must be one of `:advanced`, or `:simple`. * `toolbar` (`:list`) - Defaults to `[]`. * `deny` (`:list`) - Features to remove entirely: `:links`, `:images`, `:video`, `:visual_mode`, `:hybrid_mode`, `:markdown_mode`, `:html_mode`. Denied modes lose their tab in every switcher and refuse a `:set_mode` command. Denying all four modes raises. Defaults to `[]`. * `placeholder` (`:string`) - Defaults to `"Write something..."`. * `readonly` (`:boolean`) - Defaults to `false`. * `height` (`:string`) - Defaults to `"480px"`. * `min_height` (`:string`) - Defaults to `nil`. * `max_height` (`:string`) - Defaults to `nil`. * `debounce` (`:integer`) - Defaults to `400`. * `flush_on_blur` (`:boolean`) - Defaults to `true`. * `emit_events` (`:boolean`) - Defaults to `false`. * `toolbar_extra` (`:list`) - Host-defined toolbar buttons. Each entry is a map (atom or string keys): - `:id` β required; echoed back as `{:leaf_toolbar_action, %{id: id}}` - `:label` β text shown on the button - `:title` β tooltip / aria-label - `:icon` β **rendered as raw markup** so an inline `