<markdown-toolbar> element

Markdown formatting buttons for text inputs.

This is a FlaskBB maintained fork of github/markdown-toolbar-element, forked at upstream v2.2.3. See Relationship to upstream.

Installation

$ npm install --save @flaskbb/markdown-toolbar-element

Usage

import '@flaskbb/markdown-toolbar-element'

<markdown-toolbar for="textarea_id">
  <md-bold>bold</md-bold>
  <md-header>header</md-header>
  <md-italic>italic</md-italic>
  <md-quote>quote</md-quote>
  <md-code>code</md-code>
  <md-link>link</md-link>
  <md-image>image</md-image>
  <md-unordered-list>unordered-list</md-unordered-list>
  <md-ordered-list>ordered-list</md-ordered-list>
  <md-task-list>task-list</md-task-list>
  <md-mention>mention</md-mention>
  <md-ref>ref</md-ref>
  <button data-md-button>Custom button</button>
</markdown-toolbar>
<textarea id="textarea_id"></textarea>

<markdown-toolbar> comes with focus management as advised in WAI-ARIA Authoring Practices 1.1: Toolbar Design Pattern. The md-* buttons that ship with this package are automatically managed. Add a data-md-button attribute to any custom toolbar items to enroll them into focus management.

Custom buttons

There are two ways to add a button for markup this package does not ship with.

<md-custom> - configured from markup

<md-custom> covers the common case of wrapping the selection in fixed text, without writing any JavaScript:

<markdown-toolbar for="textarea_id">
  <md-custom data-md-prefix="||" data-md-placeholder="spoiler">spoiler</md-custom>
  <md-custom data-md-prefix="[[" data-md-suffix="]]">wiki link</md-custom>
  <md-custom data-md-insert="[TOC]">table of contents</md-custom>
</markdown-toolbar>

| Attribute | Effect | | --------------------- | ----------------------------------------------------------------------------------------------- | | data-md-prefix | Text inserted before the selection. | | data-md-suffix | Text inserted after the selection. Defaults to data-md-prefix; set it to "" for no suffix. | | data-md-insert | Insert this text as its own block instead of wrapping the selection. Overrides prefix/suffix. | | data-md-placeholder | Inserted between prefix and suffix, and selected, when the button is clicked with no selection. |

Clicking a wrapping button a second time on text it already wrapped removes the markup again, the same way <md-bold> does. All four attributes are observed, so changing them at runtime takes effect on the next click.

MarkdownButtonElement subclasses - anything else

Multi-line aware buttons, buttons that open a dialog, or anything else the attributes above cannot express, subclass MarkdownButtonElement:

import {MarkdownButtonElement} from '@flaskbb/markdown-toolbar-element'

class MyPluginCalloutElement extends MarkdownButtonElement {
  connectedCallback() {
    super.connectedCallback()
    this.markdownStyle = {prefix: '> ', multiline: true, surroundWithNewlines: true}
  }
}

customElements.define('myplugin-callout', MyPluginCalloutElement)

The class is also available as window.MarkdownButtonElement for scripts that are loaded with a plain <script> tag rather than bundled.

The contract for a subclass:

• Assign this.markdownStyle before the element can be clicked. Doing it in connectedCallback() is the right place; attributes are already readable there. A button with no style assigned does nothing when clicked.
• Call super.connectedCallback(). It sets role="button" and marks the element as part of the toolbar's keyboard navigation set. If you cannot call it, put data-md-toolbar-button on the element in markup instead.
• Pick a tag name prefixed with your plugin or application name. customElements.define throws if a name is registered twice, so md-* and bare names like spoiler-button are collision risks.

markdownStyle accepts the Style type, which is exported for TypeScript consumers:

| Field | Type | Effect | | ---------------------- | --------- | -------------------------------------------------------------------------- | | prefix | string | Text inserted before the selection. | | suffix | string | Text inserted after the selection. | | blockPrefix | string | Replaces prefix when the selection spans multiple lines. | | blockSuffix | string | Replaces suffix when the selection spans multiple lines. | | multiline | boolean | Apply prefix/suffix to each selected line instead of the block. | | surroundWithNewlines | boolean | Pad the result with blank lines so it forms its own block. | | trimFirst | boolean | Move leading/trailing whitespace out of the wrapped text. | | prefixSpace | boolean | Insert a space before prefix when the preceding character is not blank. | | replaceNext | string | Substring of suffix that gets selected after inserting, e.g. url. | | scanFor | string | Regex; if the selection matches, it is put into replaceNext's place. | | orderedList | boolean | Renumber the selected lines as an ordered list. | | unorderedList | boolean | Prefix the selected lines as an unordered list. | | placeholder | string | Inserted and selected when the button is used with an empty selection. | | insert | string | Insert this text as its own block, ignoring every field above. |

A custom element whose definition never loaded (a plugin script that failed to fetch, for example) is skipped by the toolbar's keyboard navigation instead of becoming a dead stop between the other buttons.

Relationship to upstream

This is a hard fork, and adapted to the own needs of FlaskBB.

Changes against upstream v2.2.3:

• MarkdownButtonElement, MarkdownToolbarElement, MarkdownCustomButtonElement and the Style type are exported, and MarkdownButtonElement is exposed on window.
• MarkdownButtonElement gained a markdownStyle accessor, so subclasses outside this package can configure themselves. Upstream keeps the styles in a module-private WeakMap with no way in.
• Added the <md-custom> element.
• Added the placeholder and insert style fields.
• MarkdownButtonElement.connectedCallback() marks the element with data-md-toolbar-button, which enrolls it into focus management. The built-in md-* elements now call super.connectedCallback(), so they also get role="button" - upstream never set it on them, a pre-existing accessibility gap fixed here.
• Keyboard navigation skips undefined custom elements.
• Package renamed, TypeScript and CI updated.

Browser support

Browsers without native custom element support require a polyfill.

• Chrome
• Firefox
• Safari
• Microsoft Edge

Development

npm install
npm test

License

Distributed under the MIT license. See LICENSE for details. Originally written by GitHub, Inc.; the fork is maintained by the FlaskBB team.