@brightspace-ui/htmleditor

HTML Editor

An HTML Editor component used to author rich HTML fragments. It offers three authoring modes for different contexts.

Full HTML Editor

The Full editor surfaces the full range of authoring tools in a traditional WYSIWYG interface.

Best Practices

• Use to clearly communicate rich text editing functionality
• Use when we expect authors will want the full range of authoring tools, and there is sufficient space for a fully-featured experience
• Use on pages where authoring text is one of the primary functions
• Use when it is possible to give the editor sufficient presence and breathing room on the page

• Don’t use when multiple editors appear in close proximity; consider Inline mode instead
• Don’t shrink the Full editor down to fit in tight spaces, such as small sidebars
• Don’t use when rich text formatting is unnecessary or certain formatting options are disallowed

<script type="module">
  import '@brightspace-ui/htmleditor/htmleditor.js';
</script>
<d2l-htmleditor label="Default" html="&lt;p&gt;Hello World!&lt;/p&gt;"></d2l-htmleditor>

Properties

Property	Type	Description
attached-images-only	Boolean	Whether or not to restrict image uploads to attachments and prevent saving to course/shared files.
auto-save	Boolean	Whether or not to prompt the user when navigating away from the page while the editor has unsaved content.
compact	Boolean	Whether or not to use compact styles when rendering editor contents.
disabled	Boolean	Whether the content is read-only.
files	Array	Read-only. An array of FileInfo objects for files added.
file-upload-for-all-users	Boolean	Whether or not to enable file uploads to course or shared files.
full-page	Boolean	Whether an HTML document or fragment is being authored.
full-page-font-color	String, default: #202122 (ferrite)	The body font color. Only applies when full-page is true.
full-page-font-family	String, default: Browser default	The body font. Only applies when full-page is true.
full-page-font-size	String, default: Browser default	The body font size. Only applies when full-page is true.
height	String, default: 355px	Initial height of the editor in px, rem, or %.
html	String, default: empty string	The HTML being authored.
initializationComplete	Promise	Read-only. Fulfilled when the editor has been fully initialized; pending otherwise.
isDirty	Boolean	Whether or not the editor is dirty. If auto-save is enabled, set isDirty to false when triggering workflows where you do not want the autosave prompt.
label	String	Label for the editor. Required unless labelled-by is specified (see below).
labelled-by	String	ID of a label to be applied to the editor. This label must not be empty.
label-hidden	Boolean	Hides the label visually.
max-height	Number, default: null	Maximum height the HTML editor is allowed to resize to. A null value is equivalent to no limit.
max-length	Number, default: null	Maximum length (measured by number of characters) of HTML contents, including HTML control characters. Enables validation on this criterion when set. A null value is equivalent to no limit.
mentions	Boolean	Whether or not to enable @mentions.
no-border	Boolean	Whether or not to render the border around the editor.
no-filter	Boolean	Whether or not to disable filtering for the content.
no-inline-vertical-margins	Boolean	Whether or not to remove vertical margins around editor content in inline/inline-limited mode.
no-live-validation	Boolean	Whether or not to disable live validation (on editor blur).
no-spellchecker	Boolean	Whether or not to disable spell checking.
paste-local-images	Boolean	Whether or not to enable local image pasting and drag-and-drop. See additional documentation.
required	Boolean	Whether or not the editor is a required field. Enables validation on this criterion when set.
source-editable	Boolean	Whether or not to enable the source code editor.
toolbar-horizontal-offset	String, default: 0	Horizontal offset of the toolbar from the edge of the editor.
type	String, default: full	Whether to render the editor in full, inline, or inline-limited mode.
width	String, default: 100% of bounding container	Initial width of the editor.
word-count-in-footer	Boolean	Whether or not to display the current word/character counts in the editor footer.

Events

Event	Properties	Description
d2l-htmleditor-blur	None	Dispatched when focus is lost from the editor and its toolbar.
d2l-htmleditor-focus	None	Dispatched when the editor or its toolbar gains focus.
d2l-htmleditor-image-upload-complete	None	Dispatched when images finish uploading to the editor. If multiple images are being uploaded, the event will only be dispatched once all images are uploaded.
d2l-htmleditor-image-upload-start	None	Dispatched when images start uploading to the editor. If multiple images are being uploaded, the event will only be dispatched for the first image.
d2l-htmleditor-update	None	Dispatched as the internal TinyMCE editor is about to lose focus. The HTML editor internally persists its HTML at this time.

Methods

• clear(): Clears editor contents and undo/redo levels
• focus(): Places focus in the editor
• toggleInlineEditing(editing): Returns a promise. Toggles the inline editor into or out of editing or readonly mode, depending on the specified editing boolean. Promise resolves on completion. Has no effect on the full editor or in fullscreen mode.

HTML Usage Details

Important: user-authored HTML must be trusted or properly sanitized!

HTML fragment:

<script type="module">
  import '@brightspace-ui/htmleditor/htmleditor.js';
</script>
<d2l-htmleditor html="&lt;p&gt;Hello World!&lt;/p&gt;" label="Editor with HTML"></d2l-htmleditor>

HTML document (including head & body):

<script type="module">
  import '@brightspace-ui/htmleditor/htmleditor.js';
</script>
<d2l-htmleditor html="&lt;p&gt;Hello World!&lt;/p&gt;" label="Full Page Editor with HTML" full-page></d2l-htmleditor>

Inline Variant

Used in contexts where reducing visual clutter is important. The Inline editor presents as a standard text field. Focusing on the input field summons a floating toolbar with the most important authoring controls, and a fullscreen button to open the Full editor experience.

Best Practices

• Use where clutter is a concern, such as pages with multiple rich text fields
• Use where rich text fields appear in cramped spaces, such as sidebars

• Don’t use the Inline editor when you have a large space to fill
• Don’t use the Inline editor in places where formatting options are limited, since users can still access the Full editor with the fullscreen button
• Don’t use the Inline editor where rich text authoring is an primary function of the page, since the Full editor provides more affordances for advanced functionality

<script type="module">
  import '@brightspace-ui/htmleditor/htmleditor.js';
</script>
<d2l-htmleditor type="inline" label="Inline" height="150px" width="400px"></d2l-htmleditor>

Limited Inline Variant

Reserved for special use-cases where only basic formatting and insertion options are desired.

Best Practices

• Use in contexts such as Activity Feed, where formatting options should be limited

• Don’t use the Limited Inline editor in contexts that should offer the full range of formatting options

<script type="module">
  import '@brightspace-ui/htmleditor/htmleditor.js';
</script>
<d2l-htmleditor type="inline-limited" label="Inline Limited" height="150px" width="400px"></d2l-htmleditor>

Integration

Implementing local image pasting

Your application or component will need additional implementation work to support local image pasting. When the paste-local-images attribute is specified on the editor, copying/pasting or dragging/dropping images into the editor will prompt the editor to push those images to a temporary location on blur and then expose those files via the editor's files property. It's expected that your application or component will provide its own workflow to save those files somewhere more permanent.

Accessibility

The Brightspace editor has comprehensive screen reader and keyboard navigation support. You can move through toolbar items with the Arrow keys; use Tab and Shift + Tab to quickly switch between the toolbars and content area.

• Use the Tab key to switch focus down to the content area, and Shift + Tab to shift back up to the toolbar
  • If a context toolbar is visible, it will be positioned between the main toolbar and content area
• Use the Arrow keys to move between toolbar items
• Use the Control + Arrow keys (⌘ + Arrow keys on Mac) to move between toolbar groups
• Use the Return to select and toggle toolbar items, or open dropdown menus

Text Patterns

The following can be entered in the text editing area for quick formatting:

Pattern	Formatting
:emoji keyword	Open emoji autocomplete menu
*text*	Italic text
**text**	Bold text
- text	Unordered list
1. text	Ordered list

Installation

To install from NPM:

npm install @brightspace-ui/htmleditor

Developing, Testing and Contributing

After cloning the repo, run npm install to install dependencies, npm run build to generate imports required to consume tinyMCE from the CDN.

Updating TinyMCE

When a new version of TinyMCE has been published to the CDN, update the version export in tinymce-lib-version.js, then run npm run build to re-generate the exports for the new version. This is also done automatically on publish. Do not alter the generated imports yourself.

Running the demos

To start an es-dev-server that hosts the demo page and tests:

npm start

Linting

# eslint, stylelint, and langs
npm run lint

# eslint only
npm run lint:eslint

Testing

# lint and unit test
npm test

# lint only
npm run lint

# unit tests only
npm run test:headless

# debug or run a subset of local unit tests
# then navigate to `http://localhost:9876/debug.html`
npm run test:headless:watch

Visual Diff Testing

This repo uses the @brightspace-ui/visual-diff utility to compare current snapshots against a set of golden snapshots stored in source control.

The golden snapshots in source control must be updated by the visual-diff GitHub Action. If a pull request results in visual differences, a draft pull request with the new goldens will automatically be opened against its branch.

To run the tests locally to help troubleshoot or develop new tests, first install these dependencies:

npm install @brightspace-ui/visual-diff@X mocha@Y puppeteer@Z  --no-save

Replace X, Y and Z with the current versions the action is using.

Then run the tests:

# run visual-diff tests
npx mocha './test/**/*.visual-diff.js' -t 40000
# subset of visual-diff tests:
npx mocha './test/**/*.visual-diff.js' -t 40000 -g some-pattern
# update visual-diff goldens
npx mocha './test/**/*.visual-diff.js' -t 40000 --golden

Versioning & Releasing

TL;DR: Commits prefixed with fix: and feat: will trigger patch and minor releases when merged to main. Read on for more details...

The sematic-release GitHub Action is called from the release.yml GitHub Action workflow to handle version changes and releasing.

Version Changes

All version changes should obey semantic versioning rules:

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards compatible manner, and
3. PATCH version when you make backwards compatible bug fixes.

The next version number will be determined from the commit messages since the previous release. Our semantic-release configuration uses the Angular convention when analyzing commits:

• Commits which are prefixed with fix: or perf: will trigger a patch release. Example: fix: validate input before using
• Commits which are prefixed with feat: will trigger a minor release. Example: feat: add toggle() method
• To trigger a MAJOR release, include BREAKING CHANGE: with a space or two newlines in the footer of the commit message
• Other suggested prefixes which will NOT trigger a release: build:, ci:, docs:, style:, refactor: and test:. Example: docs: adding README for new component

To revert a change, add the revert: prefix to the original commit message. This will cause the reverted change to be omitted from the release notes. Example: revert: fix: validate input before using.

Releases

When a release is triggered, it will:

• Update the version in package.json
• Tag the commit
• Create a GitHub release (including release notes)
• Deploy a new package to NPM

Releasing from Maintenance Branches

Occasionally you'll want to backport a feature or bug fix to an older release. semantic-release refers to these as maintenance branches.

Maintenance branch names should be of the form: +([0-9])?(.{+([0-9]),x}).x.

Regular expressions are complicated, but this essentially means branch names should look like:

• 1.15.x for patch releases on top of the 1.15 release (after version 1.16 exists)
• 2.x for feature releases on top of the 2 release (after version 3 exists)