Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@brightspace-ui/htmleditor

Package Overview
Dependencies
Maintainers
3
Versions
767
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@brightspace-ui/htmleditor

An HTML editor that integrates with Brightspace

  • 2.86.6
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
80
increased by66.67%
Maintainers
3
Weekly downloads
 
Created
Source

HTML Editor

NPM version

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-onlyBooleanWhether or not to restrict image uploads to attachments and prevent saving to course/shared files.
auto-saveBooleanWhether or not to prompt the user when navigating away from the page while the editor has unsaved content.
compactBooleanWhether or not to use compact styles when rendering editor contents.
disabledBooleanWhether the content is read-only.
filesArrayRead-only. An array of FileInfo objects for files added.
file-upload-for-all-usersBooleanWhether or not to enable file uploads to course or shared files.
full-pageBooleanWhether an HTML document or fragment is being authored.
full-page-font-colorString, default: #202122 (ferrite)The body font color. Only applies when full-page is true.
full-page-font-familyString, default: Browser defaultThe body font. Only applies when full-page is true.
full-page-font-sizeString, default: Browser defaultThe body font size. Only applies when full-page is true.
heightString, default: 355pxInitial height of the editor in px, rem, or %.
htmlString, default: empty stringThe HTML being authored.
initializationCompletePromiseRead-only. Fulfilled when the editor has been fully initialized; pending otherwise.
isDirtyBooleanWhether 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.
labelStringLabel for the editor. Required unless labelled-by is specified (see below).
labelled-byStringID of a label to be applied to the editor. This label must not be empty.
label-hiddenBooleanHides the label visually.
max-heightNumber, default: nullMaximum height the HTML editor is allowed to resize to. A null value is equivalent to no limit.
max-lengthNumber, default: nullMaximum 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.
mentionsBooleanWhether or not to enable @mentions.
no-borderBooleanWhether or not to render the border around the editor.
no-filterBooleanWhether or not to disable filtering for the content.
no-inline-vertical-marginsBooleanWhether or not to remove vertical margins around editor content in inline/inline-limited mode.
no-live-validationBooleanWhether or not to disable live validation (on editor blur).
no-spellcheckerBooleanWhether or not to disable spell checking.
paste-local-imagesBooleanWhether or not to enable local image pasting and drag-and-drop. See additional documentation.
requiredBooleanWhether or not the editor is a required field. Enables validation on this criterion when set.
source-editableBooleanWhether or not to enable the source code editor.
toolbar-horizontal-offsetString, default: 0Horizontal offset of the toolbar from the edge of the editor.
typeString, default: fullWhether to render the editor in full, inline, or inline-limited mode.
widthString, default: 100% of bounding containerInitial width of the editor.
word-count-in-footerBooleanWhether or not to display the current word/character counts in the editor footer.

Events

             Event                                                 PropertiesDescription
d2l-htmleditor-blurNoneDispatched when focus is lost from the editor and its toolbar.
d2l-htmleditor-focusNoneDispatched when the editor or its toolbar gains focus.
d2l-htmleditor-image-upload-completeNoneDispatched 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-startNoneDispatched 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-updateNoneDispatched 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:

PatternFormatting
:emoji keywordOpen emoji autocomplete menu
*text*Italic text
**text**Bold text
- textUnordered list
1. textOrdered 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)

FAQs

Package last updated on 06 Nov 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc