README

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

Events

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

The following feature flag specifies whether the new editor should be rendered.

F15913-html-editor-alignment

The IHtmlEditorAlignmentSwitch (C#) and D2L.LP.Web.UI.Desktop.Controls.HtmlEditor.IsNewEditorEnabled() (JavaScript) can be used to check the net result of the feature flag for conditional rendering.

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 and lit-analyzer
npm run lint

# eslint only
npm run lint:eslint

# lit-analyzer only
npm run lint:lit

Testing

# lint, unit test and visual-diff 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:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner, and
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)

Usage no npm install needed!

README

HTML Editor

Full HTML Editor

Best Practices

Properties

Events

Methods

HTML Usage Details

Inline Variant

Best Practices

Limited Inline Variant

Best Practices

Integration

Implementing local image pasting

Accessibility

Text Patterns

Installation

Developing, Testing and Contributing

Updating TinyMCE

Running the demos

Linting

Testing

Visual Diff Testing

Versioning & Releasing

Version Changes

Releases

Releasing from Maintenance Branches