NoRedInk / noredink-ui / Nri.Ui.Highlighter.V5

Changes from V4:

Highlighter provides a view/model/update to display a view to highlight text and show marks.

Patch changes:

Types


type alias Model marker =
{ id : String
, highlightables : List (Nri.Ui.Highlightable.V3.Highlightable marker)
, marker : Nri.Ui.HighlighterTool.V1.Tool marker
, joinAdjacentInteractiveHighlights : Basics.Bool
, sorter : Sorter marker
, hintingIndices : Maybe ( Basics.Int
, Basics.Int )
, mouseDownIndex : Maybe Basics.Int
, mouseOverIndex : Maybe Basics.Int
, isInitialized : Initialized
, hasChanged : HasChanged
, selectionStartIndex : Maybe Basics.Int
, selectionEndIndex : Maybe Basics.Int
, focusIndex : Maybe Basics.Int
, isHovering : Basics.Bool 
}

Model of a highlighter


type Msg marker
    = Pointer PointerMsg
    | Keyboard KeyboardMsg
    | Focused (Result Browser.Dom.Error ())


type PointerMsg
    = Down Basics.Int
    | Out
    | Over Basics.Int
    | Move (Maybe String) Basics.Int
    | Up (Maybe String)
    | Ignored

Messages used by highlighter when interacting with a mouse or finger.

Init/View/Update

init : { id : String, highlightables : List (Nri.Ui.Highlightable.V3.Highlightable marker), marker : Nri.Ui.HighlighterTool.V1.Tool marker, joinAdjacentInteractiveHighlights : Basics.Bool, sorter : Sorter marker } -> Model marker

Setup initial model

joinAdjacentInteractiveHighlights - When true, and static highlightables are sandwiched by highlighted interactive highlightables of the same type, apply the highlight to the static highlightable as well.

update : Msg marker -> Model marker -> ( Model marker, Platform.Cmd.Cmd (Msg marker), Intent )

Update for highlighter returning additional info about whether there was a change

view : Model marker -> Html.Styled.Html (Msg marker)

static : { config | id : String, highlightables : List (Nri.Ui.Highlightable.V3.Highlightable marker) } -> Html.Styled.Html msg

staticWithTags : { config | id : String, highlightables : List (Nri.Ui.Highlightable.V3.Highlightable marker) } -> Html.Styled.Html msg

viewMarkdown : Model marker -> Html.Styled.Html (Msg marker)

Same as view, but will render strings like "blah" inside of emphasis tags.

WARNING: the version of markdown used here is extremely limited, as the highlighter content needs to be entirely in-line content. Lists & other block-level elements will not render as they usually would!

WARNING: markdown is rendered highlightable by highlightable, so be sure to provide highlightables like ["New York Times"]["New York Times"], NOT like ["New ", "York ", "Times"]["New ", "York ", "Times"]

staticMarkdown : { config | id : String, highlightables : List (Nri.Ui.Highlightable.V3.Highlightable marker) } -> Html.Styled.Html msg

Same as static, but will render strings like "blah" inside of emphasis tags.

WARNING: the version of markdown used here is extremely limited, as the highlighter content needs to be entirely in-line content. Lists & other block-level elements will not render as they usually would!

WARNING: markdown is rendered highlightable by highlightable, so be sure to provide highlightables like ["New York Times"]["New York Times"], NOT like ["New ", "York ", "Times"]["New ", "York ", "Times"]

staticMarkdownWithTags : { config | id : String, highlightables : List (Nri.Ui.Highlightable.V3.Highlightable marker) } -> Html.Styled.Html msg

Same as staticWithTags, but will render strings like "blah" inside of emphasis tags.

WARNING: the version of markdown used here is extremely limited, as the highlighter content needs to be entirely in-line content. Lists & other block-level elements will not render as they usually would!

WARNING: markdown is rendered highlightable by highlightable, so be sure to provide highlightables like ["New York Times"]["New York Times"], NOT like ["New ", "York ", "Times"]["New ", "York ", "Times"]

viewWithOverlappingHighlights : Model marker -> Html.Styled.Html (Msg marker)

Foldable Views

If you want more control over the rendering of the highlightables, you can use these functions inside of a fold to render the highlightables one by one. Use initFoldState to set up the initial state and then each call to viewFoldHighlighter or viewFoldStatic will render a single highlightable along with an update to the state.


type FoldState marker

A type that contains information needed to render individual Highlightables one at a time

initFoldState : Model marker -> FoldState marker

Computes all the mark styles necessary to perform a fold over the Highlightable elements

viewFoldHighlighter : List Css.Style -> FoldState marker -> ( FoldState marker, List (Html.Styled.Html (Msg marker)) )

Render a single Highlightable while also returning an updated state.

A list of extraStyles is also accepted if, for example, you want to apply bold / italic / underline formatting to the generated span.

viewFoldStatic : List Css.Style -> FoldState marker -> ( FoldState marker, List (Html.Styled.Html msg) )

Render a single Highlightable that is NOT interactive while also returning an updated state.

A list of extraStyles is also accepted if, for example, you want to apply bold / italic / underline formatting to the generated span.

Intents


type Intent
    = Intent ({ listenTo : ListenTo, changed : HasChanged })

Possible intents or "external effects" that the Highlighter can request (see perform).

hasChanged : Intent -> HasChanged

Check if the highlighter has changed.


type HasChanged
    = Changed
    | NotChanged

Setters

removeHighlights : Model marker -> Model marker

Getters

clickedHighlightable : Model marker -> Maybe (Nri.Ui.Highlightable.V3.Highlightable marker)

You are not likely to need this helper unless you're working with inline commenting.

hoveredHighlightable : Model marker -> Maybe (Nri.Ui.Highlightable.V3.Highlightable marker)

You are not likely to need this helper unless you're working with inline commenting.

selectShortest : ({ model | highlightables : List (Nri.Ui.Highlightable.V3.Highlightable marker), sorter : Sorter marker } -> Maybe (Nri.Ui.Highlightable.V3.Highlightable marker)) -> { model | highlightables : List (Nri.Ui.Highlightable.V3.Highlightable marker), sorter : Sorter marker } -> Maybe marker

Highlights can overlap. Sometimes, we want to apply a certain behavior (e.g., hover color change) on just the shortest highlight. Use this function to find out which marker applies to the least amount of text.

Note that this is shortest by text length, not shortest by number of highlightables.

You are not likely to need this helper unless you're working with inline commenting.