Commands: Highlight & Links

Commands for the highlight mark, the highlighter tool and hyperlinks.

import { toggleHighlight, setHighlight, setLink, removeLink } from "@stesura/core/commands";

Highlighting

toggleHighlight

Toggle the highlight on the selection. It is removed only when the existing highlight has the same color; a different color is replaced.

toggleHighlight(color: string): Command

setHighlight / enableHighlight

setHighlight applies the highlight mark in color to the selection.

enableHighlight arms the highlighter instead: the cursor becomes a marker, and later selections are highlighted in color until disableHighlight. "transparent" arms an eraser that removes highlights. Returns false without a color. Pass view so the cursor can change.

setHighlight(color: string): Command
enableHighlight(color?: string): Command

unsetHighlight / disableHighlight

unsetHighlight removes the highlight mark from the selection. disableHighlight disarms the highlighter and restores the cursor.

unsetHighlight: Command
disableHighlight: Command

Available Colors

Highlights use Word’s highlight palette, HIGHLIGHT_COLORS from @stesura/core/constants. Pasted HTML is only parsed as a highlight when its background matches one of these.

Links

Links are created in two steps: setPendingLink records the target range, and setLink applies the URL to it.

setLink

Link the pending selection to url and clear the pending state, in one transaction. The URL is sanitized with safeNormalizeUrl, and any code mark over the range is removed. Returns false when no link is pending or the URL is unsafe.

setLink(url: string): Command

setLinkUrl

Same behavior as setLink: it links the pending selection, so editing an existing link also goes through setPendingLink first.

setLinkUrl(url: string): Command

removeLink

Remove the link from the selection, or the whole link under a bare cursor.

removeLink: Command

setPendingLink

Enter the pending-link state that opens the link editor. With a bare cursor it selects the link under it, or else the surrounding word. The URL of an existing link is kept in the plugin state as existingUrl. Refused in code blocks and on non-text selections.

setPendingLink: Command

cancelPendingLink

Clear the pending-link state without creating a link. Returns false when nothing is pending.

cancelPendingLink: Command

Link Workflow

1. User selects text
2. setPendingLink is called (Mod-k, or in editor-react the toolbar Link button or the context menu)
3. The pendingLinkPlugin adds a visual decoration to the selection
4. editor-react opens its floating link form while the pending state is set
5. User enters a URL
6. setLinkUrl(url) (or setLink(url)) creates the link mark
7. Or cancelPendingLink to abort

Next Steps

• Commands: Tables: table manipulation
• Commands: Sections & Track Changes: page layout and revision tracking