prosemirror-plugin-inspector

A web component for inspecting the currently selected ProseMirror node.

Table of Contents

• prosemirror-plugin-inspector
  • Table of Contents
  • Installation
  • Usage
    • Styling
  • Documentation
    • Exports
      • InspectorView
      • inspectorPlugin()
      • inspectorPluginKey
      • ProseMirrorInspector
      • findPlaceholder()

Installation

npm i prosemirror-plugin-inspector

Usage

Import the inspectorPlugin() function with all of your other ProseMirror code:

import { EditorState } from "prosemirror-state";
import { EditorView } from "prosemirror-view";
import { inspectorPlugin } from "prosemirror-plugin-inspector";

const schema = new Schema(
  // SchemaSpec goes here
);

new EditorView(document.querySelector("#editor"), {
  state: EditorState.create({
    schema: schema,
    plugins: [
      // load other plugins
      inspectorPlugin({
        // see function documentation for configuration
      }),
    ],
  }),
});

Styling

The html configuration option expects a DocumentFragment that you can fill with <link> or <style> tags. The DocumentFragment will be inserted at the start of the shadow DOM.

To style the inline decorations added by the plugin, use the .placeholder class selector.

Documentation

This module exports a plugin creation function, a PluginView, and a PluginKey for attaching a node inspector to a ProseMirror editor. Additionally, the findPlaceholder() helper function allows for the discovery of decorations placed by file uploads. Type declarations for the exported items are generated from JSDoc annotations in the code.

A quick reference is below; refer to the documentation comments in the code and their corresponding type declarations for a more thorough breakdown.

Exports

InspectorView

The class for creating and updating the inspector.

inspectorPlugin()

A function that returns a plugin you can pass to the editor state. It takes an object with the following properties as an argument:

• class?: The classes for the inspector wrapper
• element?: Where the inspector should be adjacently inserted
• fields: An object with node names as keys and Maps as values; the Map has section names as keys and an array of FieldSpecs as values
• html?: A document fragment containing elements that will style the inspector or provide information about a node; it will be prepended to the inspector's shadow root. The data-path attribute is a string that specifies where to look for a value on the selected node.
  • For example, <h2 data-path="type.name">Node name</h2> will display the value of the node.type.name attribute for all nodes
• toggle(isVisible)?: A function that runs when the visible property of the plugin's state changes; it receives a boolean value indicating whether or not the inspector should be visible
• where?: The InsertPosition indicating where to insert the inspector relative to the element key
• state?: An object representing the initial state of the plugin
  • visible: A boolean value indicating whether or not the inspector is visible
  • decorations: A DecorationSet of placeholders the relevant to the plugin

The fields property is required, but the rest of the properties are optional.

inspectorPluginKey

The key of the plugin created by inspectorPlugin().

ProseMirrorInspector

The class for the custom element that contains the inspector. The custom element uses shadow DOM, and it exposes elements for styling via the part attribute.

findPlaceholder()

Note: As this function is only for specific field types, we should probably remove it. Example field types will probably become a separate package, and this will be moved there.

This function accepts two arguments: an EditorState and a unique id for a Decoration. After searching through the state's decorations, it returns the from position of the first instance of the decoration, and null otherwise.