README

Draft.js conductor

📝✨ Little Draft.js helpers to make rich text editors just work. Built for Draftail.

Features

Infinite list nesting
Idempotent copy-paste between editors
Editor state data conversion helpers

Infinite list nesting

By default, Draft.js only provides support for 5 list levels for bulleted and numbered lists. While this is often more than enough, some editors need to go further.

Instead of manually writing and maintaining the list nesting styles, use those little helpers:

import { getListNestingStyles, blockDepthStyleFn } from "draftjs-conductor";

<style>
  {getListNestingStyles(6)}
</style>
<Editor blockStyleFn={blockDepthStyleFn} />

getListNestingStyles will generate the necessary CSS for your editor’s lists. blockDepthStyleFn will then apply classes to blocks based on their depth, so the styles take effect. Voilà!

If your editor’s maximum list nesting depth never changes, pre-render the styles as a fragment for better performance:

const listNestingStyles = <style>{getListNestingStyles(6)}</style>;

You can also leverage React.memo to speed up re-renders even if max was to change:

const NestingStyles = React.memo(ListNestingStyles);

<style>
  <NestingStyles max={max} />
</style>;

Relevant Draft.js issues:

Idempotent copy-paste between editors

The default Draft.js copy-paste handlers lose a lot of the formatting when copy-pasting between Draft.js editors. While this might be ok for some use cases, sites with multiple editors on the same page need them to reliably support copy-paste.

Relevant Draft.js issues:

All of those problems can be fixed with this library, which overrides the copy and cut events to transfer more of the editor’s content, and introduces a function to use with the Draft.js handlePastedText to retrieve the pasted content.

This will paste all copied content, even if the target editor might not support it. To ensure only supported content is retained, use filters like draftjs-filters.

Note: IE11 isn’t supported, as it doesn't support storing HTML in the clipboard, and we also use the Element.closest API.

With draft.js 0.11 and above

Here’s how to use the copy/cut override, and the paste handler:

import {
  onDraftEditorCopy,
  onDraftEditorCut,
  handleDraftEditorPastedText,
} from "draftjs-conductor";

class MyEditor extends Component {
  constructor(props: Props) {
    super(props);

    this.state = {
      editorState: EditorState.createEmpty(),
    };

    this.onChange = this.onChange.bind(this);
    this.handlePastedText = this.handlePastedText.bind(this);
  }

  onChange(nextState: EditorState) {
    this.setState({ editorState: nextState });
  }

  handlePastedText(text: string, html: ?string, editorState: EditorState) {
    let newState = handleDraftEditorPastedText(html, editorState);

    if (newState) {
      this.onChange(newState);
      return true;
    }

    return false;
  }

  render() {
    const { editorState } = this.state;

    return (
      <Editor
        editorState={editorState}
        onChange={this.onChange}
        onCopy={onDraftEditorCopy}
        onCut={onDraftEditorCut}
        handlePastedText={this.handlePastedText}
      />
    );
  }
}

The copy/cut event handlers will ensure the clipboard contains a full representation of the Draft.js content state on copy/cut, while handleDraftEditorPastedText retrieves Draft.js content state from the clipboard. Voilà! This also changes the HTML clipboard content to be more semantic, with less styles copied to other word processors/editors.

You can also use getDraftEditorPastedContent method and set new EditorState by yourself. It is useful when you need to do some transformation with content (for example filtering unsupported styles), before past it in the state.

With draft.js 0.10

The above code relies on the onCopy and onCut event handlers, only available from Draft.js v0.11.0 onwards. For Draft.js v0.10.5, use registerCopySource instead, providing a ref to the editor:

import {
  registerCopySource,
  handleDraftEditorPastedText,
} from "draftjs-conductor";

class MyEditor extends Component {
  componentDidMount() {
    this.copySource = registerCopySource(this.editorRef);
  }

  componentWillUnmount() {
    if (this.copySource) {
      this.copySource.unregister();
    }
  }

  render() {
    const { editorState } = this.state;

    return (
      <Editor
        ref={(ref) => {
          this.editorRef = ref;
        }}
        editorState={editorState}
        onChange={this.onChange}
        handlePastedText={this.handlePastedText}
      />
    );
  }
}

With draft-js-plugins

The setup is slightly different with draft-js-plugins (and React hooks) – we need to use the provided getEditorRef method:

// reference to the editor
const editor = useRef<Editor>(null);

// register code for copying
useEffect(() => {
  let unregisterCopySource: undefined | unregisterObject = undefined;
  if (editor.current !== null) {
    unregisterCopySource = registerCopySource(
      editor.current.getEditorRef() as any,
    );
  }
  return () => {
    unregisterCopySource?.unregister();
  };
});

See #115 for further details.

Editor state data conversion helpers

Draft.js has its own data conversion helpers, convertFromRaw and convertToRaw, which work really well, but aren’t providing that good of an API when initialising or persisting the content of an editor.

We provide two helper methods to simplify the initialisation and serialisation of content. createEditorStateFromRaw combines EditorState.createWithContent, EditorState.createEmpty and convertFromRaw as a single method:

import { createEditorStateFromRaw } from "draftjs-conductor";

// Initialise with `null` if there’s no preexisting state.
const editorState = createEditorStateFromRaw(null);
// Initialise with the raw content state otherwise
const editorState = createEditorStateFromRaw({ entityMap: {}, blocks: [] });
// Optionally use a decorator, like with Draft.js APIs.
const editorState = createEditorStateFromRaw(null, decorator);

To save content, serialiseEditorStateToRaw combines convertToRaw with checks for empty content – so empty content is saved as null, rather than a single text block with empty text as would be the case otherwise.

import { serialiseEditorStateToRaw } from "draftjs-conductor";

// Content will be `null` if there’s no textual content, or RawDraftContentState otherwise.
const content = serialiseEditorStateToRaw(editorState);

Contributing

See anything you like in here? Anything missing? We welcome all support, whether on bug reports, feature requests, code, design, reviews, tests, documentation, and more. Please have a look at our contribution guidelines.

Credits

View the full list of contributors. MIT licensed. Website content available as CC0. Image credit: FirefoxEmoji.

Usage no npm install needed!