rupertlssmith / rte-toolkit-patch / RichText.Annotation

This module contains common constants and functions used to annotate nodes. Annotations can be added to elements and text to keep track of position when doing a complex transform like a lift or join, as well as add flags to a node that you can use to effect behavior, like if something is selectable.

newElement =
    element |> Element.withAnnotations (Set.singleton selection)

Annotations

selection : String

Represents that a node is currently selected. This annotation is transient, e.g. it should be cleared before a transform or command is complete. This annotation is also used when rendering to annotate a selected node for decorators.

selectable : String

Represents that a node can be selected. This annotation is not transient.

lift : String

Represents that a node should be lifted. This annotation is transient, e.g. it should be cleared before a transform or command is complete.

Helpers

add : String -> RichText.Node.Node -> RichText.Node.Node

Adds the given annotation to the node.

add Annotation.selectable (Block horizontal_rule)
--> Returns (Block horizontal_rule) with the selectable annotation added

addAtPath : String -> RichText.Model.Node.Path -> RichText.Model.Node.Block -> Result String RichText.Model.Node.Block

Adds an annotation to the node at the given path. Returns an error if no node exists at that path.

Annotation.addAtPath "myAnnotation" path root

addToBlock : String -> RichText.Model.Node.Block -> RichText.Model.Node.Block

Helper which adds the given annotation to a block node.

addToInline : String -> RichText.Model.Node.Inline -> RichText.Model.Node.Inline

Helper which adds the given annotation to an inline node.

fromNode : RichText.Node.Node -> Set String

Helper method to extract annotations from a node.

fromNode node
--> Set ["__selectable__"]

clear : String -> RichText.Model.Node.Block -> RichText.Model.Node.Block

Removes the given annotation from this node and its children.

clear Annotation.lift root
--> Returns `root` but with all the lift annotations removed.

remove : String -> RichText.Node.Node -> RichText.Node.Node

Removes the given annotation from the node if it exists.

remove Annotation.selectable (Block horizontal_rule)
--> Returns (Block horizontal_rule) with the selectable annotation removed

removeAtPath : String -> RichText.Model.Node.Path -> RichText.Model.Node.Block -> Result String RichText.Model.Node.Block

Removes the given annotation from the node at the given path. Returns an error if no node exists at that path.

Annotation.removeAtPath "myAnnotation" path root

removeFromBlock : String -> RichText.Model.Node.Block -> RichText.Model.Node.Block

Helper which removes the given annotation from a block node.

removeFromInline : String -> RichText.Model.Node.Inline -> RichText.Model.Node.Inline

Helper which removes the given annotation from an inline node.

Selection

These methods are for marking selection, which is useful for keeping track of a user's selection when defining your own transforms.

annotateSelection : RichText.Model.Selection.Selection -> RichText.Model.Node.Block -> RichText.Model.Node.Block

Adds the selection annotation to the paths in the selection if they exist. This is useful when defining your own transforms to keep track of which nodes are selected.

markedRoot =
    annotateSelection normalizedSelection (State.root editorState)

selectionFromAnnotations : RichText.Model.Node.Block -> Basics.Int -> Basics.Int -> Maybe RichText.Model.Selection.Selection

Derives the selection from selection annotations.

selectionFromAnnotations root 0 0
--> Just { anchorNode=[0], anchorOffset=0, focusNode=[1,2], focusOffset=0 }

clearSelectionAnnotations : RichText.Model.Node.Block -> RichText.Model.Node.Block

Clears the selection annotation from the editor node. The selection annotation should be transient, so it's important to clear the annotation once you're finished with it.

clearSelectionAnnotations root
--> Returns root but with the selection annotation removed

isSelectable : RichText.Node.Node -> Basics.Bool

True if a node has the selectable annotation or is Text, false otherwise.

isSelectable (Inline textNode)
--> True

Lift

doLift : RichText.Model.Node.Block -> RichText.Model.Node.Block

Lifts nodes that are marked with the lift annotation if possible. Note that if there are multiple levels of lift annotations, you may have to call this function multiple times.

markedRoot : Block
markedRoot =
    addLiftMarkToBlocksInSelection normalizedSelection root

liftedRoot : Block
liftedRoot =
    doLift markedRoot