Proposal: Clean up core APIs

Change add* to register*

I had some really nice feedback tonight from some of the old folks who used to work at Meta on DraftJS. They mentioned that the current pattern of addListener, addTransform etc was confusing – as it’s assumed to be just “adding” something. They expected there to be an opposite API of removeListener and removeTransform.

They mentioned that we could do what other popular libraries do, and create an observe or use a register prefix, which infers that you’re creating something that has a return signature. This would mean the following changes:

• addListener -> registerListener
• addNodeTransform -> registerNodeTransform

This should hopefully make it clear that these APIs return the removal variants of themselves.

Let’s break out command listeners

They’re not really listeners, and never have been. Listeners don’t expect the function to return anything, but command listeners do – and they also have priorities! So let’s come up with a better naming for both the listening part and the dispatching part! My current thinking is:

• addListener('command', function, priority) -> registerCommandHandler(function, priority)
• execCommand(commandType, payload) -> dispatchCommand(commandType, payload)

Let’s remove root listeners

I really don’t feel they push folks down the path of success. They encourage adding listeners to the contenteditable, but really they should probably be delegating events to the document and, where possible, leveraging commands instead.

[trueadm]

I like Amy’s idea around the register prefix instead of create. What do others think?

[trueadm]

@thegreatercurve We should keep textcontent listeners, purely because it avoids the user from having to use update listeners too much (they fire much more frequently than textcontent listeners do).

We used to have explicit listeners, i.e. registerUpdateListener etc, the reason we moved away from them was to make it feel more web like. However, I’m not really seeing any real benefits from that right now, so you’re probably right!