Feature Request: Decoration API

[Ragnar-Oock]

Description

It's reported at several locations in the doc (for example on the linting example experiment page ) that Tiptap has no API to interact with prosemirror's decoration with extension, requiring the use of prosemirror plugins.

Is there any plan for adding one in tiptap v2 ?

Suggestion

maybe it could look like this ?

addDecorations?: (this: {
      name: string
      options: Options
      storage: Storage
      parent: ParentConfig<ExtensionConfig<Options, Storage>>['addDecorations']
    }) => Decoration[]

Use Case

There is plenty of extensions (official or not) that uses decorations to work (InvisibleCharacters and Placeholder are official examples), unfortunately they require using prosemirror plugins to add those decorations.

Type

New feature

[nperez0111]

Really appreciate your thoughts on this, we have been considering an API quite similar to what you've described we just haven't gotten around to the details of it yet. But it is on our list for a v3.

I am interested in collecting use cases for the decoration api, so it would be particularly helpful to know what you might be trying to use the decoration api for?

[Ragnar-Oock]

I used it to visually preserve the selection when opening the modal of a link widget and I might use it to display formatting hints for user generated content, highlighting in red chars after a certain number in the first paragraph of a document for example. Kind of like the linting example/experiment shown on the doc.

[bdbch]

Yep - I've been thinking about official Decoration support in Tiptap directly. My idea was to have something like this on an extension level:

// This creates decorations for all nodes inside a document
// showing their node type names
addDecorations({ editor }) {
  const decorations = []
  const { doc } = editor.state

  doc.descendants((node, pos) => {
    const name = node.type.name
    const $pos = doc.resolve(pos)
    const after = $pos.after($pos.depth)

    decorations.push(Decoration.widget(after, () => {
      const el = document.createElement('span')
      el.innerText = name
      el.classList.add('node-name-widget')
      return el
    }))
  })

  return decorations
}

The returned decorations could be collected by the ExtensionManager and passed to a DecorationManager / decoration prosemirror plugin which handles the PM state & DecorationSet creation.

[Ragnar-Oock]

Having the DecorationSet passed as a parameter might be interesting in the case the extension creator wants to filter out existing decorations. Thought that could be done by storing an instance of it in the extension's storage but I think that might lead to additional boilerplate and could make this (already complex) API harder to understand for new users of the library.

For example, his is how I handled the decorations in the extension I made to visually preserve the selection when focus leaves the editor :

new Plugin({
	key: new PluginKey('fakeSelection'),
	state: {
		init(_, { doc }) {
			return DecorationSet.create(doc, []);
		},
		apply(transaction, decorations) {
			const { from, to } = transaction.selection;
			const shouldShowSelection = transaction.getMeta(showSelectionMetaName) as boolean | undefined;

			// add a decoration in the document to show where the selection is (only works with one selection)
			if (shouldShowSelection === true && to !== from) {
				return decorations.add(transaction.doc, [
					Decoration.inline(from, to, { class: 'selection' })
				]);
			}
			// remove any decoration that might have been set
			if (shouldShowSelection === false) {
				return decorations.remove(decorations.find());
			}

			// basically do nothing
			return decorations.map(transaction.mapping, transaction.doc);
		}
	},
	props: {
		decorations(state): DecorationSource | null | undefined {
			return this.getState(state);
		}
	}
})

I don't know how you want to handle the decoration set creation in the tiptap core, but recreating a new one from the addDecorations call for every transaction might take a toll on performance, especially if there's a lot of decorations to apply (for extensions like InvisibleCharacters for example)

[bdbch]

The DecorationSet creation is still done in a Prosemirror Plugin. We can handle the creation on init still. I think the only thing that could become complicated is the creation of new Tiptap Decoration classes on each transaction right now.

I'll get back to it later this week to see if I can find a solution where we can keep track of decorations to not update them every transaction.

[bdbch]

I started working on the Decoration API last night (see #5437)

I added a new addDecorations option to extensions which can return an array of decorations.

Decorations can be created like this:

WidgetDecoration.create({
  pos: 0,
  toDOM: () => {
    const el = document.createElement('div')
    el.innerHTML = '<p>I am a widget decoration acting as a document header</p>'
    return el
  },
})

NodeDecoration.create({
  pos: pos,
  to: pos + node.size,
  attributes: {
    style: 'background-color: red;'
  }
})

// marks the first 10 characters of a document red
InlineDecoration.create({
  pos: 0,
  to: 10,
  attributes: {
    style: 'color: red;'
  }
})

---

could look like this:

addDecorations() {
  return [
    WidgetDecoration.create({
      pos: 0,
      toDOM: () => {
        const el = document.createElement('div')
        el.innerHTML = '<p>I am a widget decoration acting as a document header</p>'
        return el
      },
    }),
    NodeDecoration.create({
      pos: pos,
      to: pos + node.size,
      attributes: {
        style: 'background-color: red;'
      }
    }),
    InlineDecoration.create({
      pos: 0,
      to: 10,
      attributes: {
        style: 'color: red;'
      }
    }),
  ]
}

These decoration creations run on document changes (by checking if a transaction had document relevant changes).