NoRedInk / noredink-ui / Nri.Ui.Block.V6

Changes from V5:

- Remove `wordWithId` and `blankWithId` as we no longer are trying to point to words or blanks with the question box.
- Remove the `fullHeightBlank` attribute option - we can always infer this from the contents
- Set a maximum blank width of ~60 characters as blanks won't line break
- Remove `labelState` as we are shifting reposibility to consumers to animate labels via `labelCss`

Patch changes

- Add renderReadAloud
- Add border styles `dashed` and`underline`
- Correctly display a transparent background for underline blanks
- Add `skipLabelAnimation`, so balloon animation can be skipped

view : List (Attribute msg) -> Accessibility.Styled.Html msg

Create a block element.

Note that it is important that a series of Block elements be wrapped in a container with "whitespace; pre" set. This will ensure that line breaks only happen at whitespace, and not directly before an emphasis block in situations where it would look strange (like if the block started with a comma).

p
    [ css [ Css.whitespace Css.pre ] ]
    [ Block.view [ Block.plaintext "Hello, world!" ] ]

renderReadAloud : List (Attribute msg) -> String

Render a block to a ReadAloud friendly string.


type Attribute msg

Content

plaintext : String -> Attribute msg

Provide the main content of the block as a plain-text string. You can also use content for more complex cases, including a blank appearing within an emphasis.


type Content msg

content : List (Content msg) -> Attribute msg

Use content for more complex block views, for instance when a blank appears within an emphasis block. Prefer to use plaintext when possible for better readability.

Block.view
    [ Block.emphasize
    , Block.content (Block.phrase "Hello, " ++  Block.blank { characterWidth = 8 } :: Block.phrase "!" ) ]
    ]

phrase : String -> List (Content msg)

Add any arbitrary string as part of block content.

space : Content msg

Convenience helper to insert a space into block content.

Putting spaces in phrase is fine as well, but you might find this more useful around the edges of blank.

bold : List (Content msg) -> Content msg

Wraps a group of content in a strong tag

italic : List (Content msg) -> Content msg

Wraps a group of content in a em tag

blank : { widthInChars : Basics.Int } -> Content msg

Insert a blank into block content specify a number of characters to set the width.

For simple blanks, you can call view with no content or plaintext specified, however if you need to control the width of the blank or put a blank inside of other emphasized content you need to use this function.

The widthInChars will be multipled by 0.5em, which will roughly appear to be the same size as a string with that many characters.

For example, the following two blocks should be approximately the same width.

phrase "Hello" blank { widthInChars = 5 }

Content customization

emphasize : Attribute msg

Mark content as emphasized.

Labels & positioning

label : String -> Attribute msg

Add a label above content. This label supports markdown syntax for bold and italics

labelId : String -> Attribute msg

labelContentId : String -> String


type alias LabelPosition =
{ totalHeight : Basics.Float
, arrowHeight : Basics.Float
, zIndex : Basics.Int
, xOffset : Basics.Float 
}

Use getLabelPositions to construct this value.

getLabelPositions : Dict String { label : Browser.Dom.Element, labelContent : Browser.Dom.Element } -> Dict String LabelPosition

Determine where to position labels in order to dynamically avoid overlapping content.

- First, we add ids to block with labels with `Block.labelId`.
- Say we added `Block.labelId "example-id"`, then we will use `Browser.Dom.getElement "example-id"` and `Browser.Dom.getElement (Block.labelContentId "example-id")` to construct a record in the shape { label : Dom.Element, labelContent : Dom.Element }. We store this record in a dictionary keyed by ids (e.g., "example-id") with measurements for all other labels.

getLabelPositions will return a dictionary of values (keyed by label ids) whose values can be passed directly to labelPosition for positioning.

labelPosition : Maybe LabelPosition -> Attribute msg

Use getLabelPositions to calculate what these values should be.

labelCss : List Css.Style -> Attribute msg

Use to set a block's label's CSS

Visual customization

yellow : Attribute msg

cyan : Attribute msg

magenta : Attribute msg

green : Attribute msg

blue : Attribute msg

purple : Attribute msg

brown : Attribute msg

insertLineBreakOpportunities : Basics.Bool -> Attribute msg

Insert the HTML "line break opportunity" element if the content is a space (Only makes a difference on Chrome. Firefox and Safari treat this element like a .)

dashed : Attribute msg

Sets the border style to be dashed

underline : Attribute msg

Sets the border style to be underlined

skipLabelAnimation : Attribute msg