Scrawl-canvas v8 - Canvas test 206

Test purpose

There are so, so many things to check here! The following list is not exhaustive:

• The initial display should show a serif font, with line-centered text reading from left to right down the yellow box. Emojis should display (in full color) as expected. Lines will break on spaces; words will not break on soft hyphens. Font size will match the HTML displayed text and the line breaks (should) fall after the same words in both representations.
• The small red dot will follow the mouse cursor over the text, jumping to each text unit's rotation/reflection point. The initial display centers the text units horizontally, with vertical alignment set to 'alphabetic'.
• The demo has been set up to adjust the entity's direction and breakTextOnSpaces attributes to match a font's requirements when that font loads. Check that all fonts do load, and their display matches the HTML display:
• Check that Arabic and Hebrew fonts correctly read right-to-left.
• Check that Thai fonts break lines as expected.
• Check that for Chinese/Japanese fonts, the punctuation does not separate from the previous character across lines.
• Update the breakTextOnSpaces value. For western fonts this will lead to as many letters as possible appearing on each line, with words broken in unexpected places. For Arabic and Devangari fonts, this setting will break the displayed text (though the effect is useful for displaying Arabic fonts vertically).
• For western fonts, check that words will break across lines on hard and soft hyphens when the breakWordOnHyphens attribute is set to true. Soft hyphens should only appear at the end of a line. Check that the hyphen character can be changed programmatically.
• Some fonts will overflow the containing template entity's shape. Check that in these situations the truncate string appears as expected (this will not happen for right-to-left fonts, by design); check also that the truncate character can be changed programmatically.
• Check that letterSpacing and wordSpacing attributes operate as expected. The text should flow as these attributes are adjusted.
• Check that the text adapts as the template entity's dimensions are adjusted. Again, the text should flow (and match the HTML line breaks as closely as possible).
• Check that text flow should see minimal changes as the template entity's scale is adjusted. The font's size should grow/shrink to match the scaling factor.
• Check that when the template entity's rotation (roll attribute) updates, the text moves with the template.
• Updating the textHandleX attribute should see minimal text movement, but the red dot will now settle on each text unit's left or right edge.
• Updating the textHandleY attribute will cause the text to move upwards/downwards to match the attribute's value. Again, the red dot's positioning will match the attribute's value.
• Check that adjusting the lineAdjustment attribute will move the text up/down, but the effect does not leave a significant gap at the top of the template entity's yellow background.
• Check that adjusting the lineSpacing attribute alters the spacing between lines as expected. Setting this attribute to 0 should lead to the display of a single line, not to an error.
• Check the justifyLine attribute:
• The "start" and "end" values should move each line of text to the start/end of the line respectively. For Arabic/Hebrew fonts this will be the right hand side of the template entity's shape; for other fonts, the left hand side.
• The "center" value will center the text (as shown on initial display)
• The "space-between" attribute will show a fully-justified-line effect. Any single orphan words at the end of the text should move to the left/right edge (dependant on the font); double orphan words will have a large gap between them.
• The "space-around" attribute will display a near-full-justified effect; the last line of text will be centered.
• Update the alignment attribute. The text should rotate within the template entity's shape, reflowing to fit within the shape as it rotates.
• Update the textUnitFlow attribute:
• The "row" value should display horizontal text (as initially displayed) with lines running downwards
• The "row-reverse" value will reverse the text lines, with the first line displaying at the bottom and other lines running upwards
• The "column" value should display text as horizontal columns. Each text unit will appear along the column, but rotated 90 degrees around its rotation/reflection point. If the text is not broken on spaces then each letter will appear on its own along the column (change the alignment attribute to show vertical text - for example for Chinese/Japanese fonts)
• The "column-reverse" value reverses the order of the columns.
• Update the localAlignment attribute to adjust each text unit's rotation. Have fun playing with the various rotation attributes to see how they interact.
• Also play with the guideline attribute settings - this will help you see where each text unit is supposed to be in relationship to its line.
• Finally ... update the layoutTemplate attribute. Text should flow within each template's shape.

Known issue: When changing the font, or the layout template, the positioning of the red ball breaks down; however that can be fixed by making a small adjustment to another attribute.

Known issue: letter spacing does not work in Safari browsers.

Touch test: not required.

Annotated code

A special note about fonts

Because fonts load asynchronously, and SC EnhancedLabel entitys currently have a (near-unsolvable) bug where they will measure a font before the font family's various iterations (if specified in CSS @font-family definitions) have downloaded - they only wait for their default font to download, not any additional fonts included (via CSS) in their text string - it makes sense for us to trigger font downloads as soon as possible. And the simplest way to do that is to include text using those fonts in a "hidden" (actually an aria-hidden="true" style="height: 0; overflow: hidden") element in the web page, ahead of the <script> tag that triggers the SC canvas build.

There are, of course, more professional ways for a front-end engineer to manage efficient and timely font downloads ... but this is just a demo and, well, needs must!

Another special note about Chinese and Japanese scripts

As much as we would like to treat every Chinese and Japanese character as its own thing, both writing systems insist that certain punctuation marks cannot be separated from their preceding character over a line break. Browsers know about this, and make sure it happens in normal HTML. SC, however, makes no effort to guess when this should happen.

For this demo, we have manually added word joiner characters - HTML entity ⁠ - immediately before these punctuation marks. A more robust code solution to pre-process canvas text would be required to handle this sort of thing in production environments. Building such a solution into the SC code is not in scope for the project.

An even more special note about Thai scripts

Breaking Thai "words" across lines is a difficult issue - see the W3C Thai Layout Requirements spec for the latest position.

The Thai script is a complex abugida. Spaces are used, but the tendency is to only insert them at natural breath pauses, which means a Thai "word" (as in: a set of characters not separated by spaces) can get exceptionally long.

To break such words across lines, one recommendation is to insert zero-space spaces - HTML entity ​ - in places where this can be done. Browser engines seem to do this internally, but getting that data from the text string doesn't seem possible. For the two Thai fonts above, this has been done manually by copying the raw string into a <p style='width: 10px; font: 16px "Noto Thai Looped Sans"'> element and then counting the characters. Not recommended for production!