Support replacing Bard TipTap extensions

[jacksleight]

This PR makes it possible to replace the built-in Bard TipTap nodes/marks with extended versions without causing duplication or errors. It also brings the Bard editor inline with the Bard Augmentor, which already supports node and mark class replacement.

The problems this solves are:

• There’s currently no way to access the built-in extension classes without importing TipTap. And even if you do that you still wouldn't have access to Statamic’s extension classes.
• Statamic.$bard.extend() always appends extensions to the list, even if they’re intended to replace built-in extensions. While TipTap mostly handles this gracefully, it still adds both, which causes duplication and throws errors if the extension has plugins.
• Normally Statamic only adds the extensions that are applicable to the buttons enabled in Bard, however if you’re replacing built-in extensions the replacement always gets added, even if the relevant button isn’t enabled.

The changes are:

• Added Statamic.$bard.tiptap.extensions which exposes the built-in extension classes, so they can easily be extended without importing TipTap.
• Added Statamic.$bard.extendReplace() which will allow you to register callbacks that will return replacement extensions.
• The BardFieldtype component has been updated to apply the replacement extensions, but it only does that if the original extension is in the list.
• To ensure replacement extensions can have the same configuration as default ones a couple of additional variables (languages and levels) are now being passed to the callbacks.
• To ensure the Paragraph extension can be replaced it's being included in the default list.

This shouldn’t cause any BC breaks. Statamic.$bard.extend() still does exactly what it used to.

Sidenote

I’ve tried to do this with zero changes to the existing APIs, but that does mean that the naming is a bit awkward now:

• extend()
• extendReplace()
• buttons()

I wonder if it might be worth changing these to something more consistent and descriptive, like:

• addExtensions()
• replaceExtensions()
• addButtons()
• With extend() and buttons() as aliases for BC

This would be consistent with the equivalent methods in the Bard Augmentor as well.

I’ll leave that decision to you. I can make those changes if you agree.

Testing

Here is a simple example that can be used to test this change. It replaces the Heading extension with a custom version with a tweaked schema.

The heading text should change to red and if you check the list of extensions being passed to the TipTap editor it should only have one instance of a Heading extension (the custom one), or none if the heading buttons aren't enabled.

const{ Heading }=Statamic.$bard.tiptap.extensions;classCustomHeadingextendsHeading{getschema(){return{
...super.schema,toDOM: node=>[`h${node.attrs.level}`,{style: 'color: red',},0],}}}Statamic.booting(()=>{Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);});

[jacksleight]

This is now ready for review, when you have time. Thanks!

[jasonvarga]

Sorry for the delay.

Nice PR! I'm making a few changes though.

Instead of this:

Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);

You'll be able specify the extension by name, and the actual extension will be provided in the callback.

Statamic.$bard.replaceExtension('heading',({ extension })=>{returnnewCustomHeading({levels: extension.options.levels});// or even justreturnnewCustomHeading(extension.options);});

I'm gonna deprecate $bard.extend() and rename it to $bard.addExtension() like you suggested.
As well as change your extendReplace to replaceExtension.
I'll leave buttons as-is though, because you can add buttons or just manipulate them.

[jacksleight]

Amazing! That new replacement solution is much better!

I just committed one small change I missed in the original PR.

TipTap includes the Doc, Text and Paragraph nodes by default. Statamic is already overriding Doc, and this PR overrides Paragraph, which just leaves Text.

The TipTap editor has a useBuiltInExtensions option that you can set to false if you're overriding those extensions (https://github.com/ueberdosis/tiptap/blob/v1/packages/tiptap/src/Editor.js#L131).

I've set that and added Text to the list, so all the extensions are only added once now.

[jasonvarga]

Awesome, thanks!

[jacksleight]

This PR makes it possible to replace the built-in Bard TipTap nodes/marks with extended versions without causing duplication or errors. It also brings the Bard editor inline with the Bard Augmentor, which already supports node and mark class replacement.

The problems this solves are:

• There’s currently no way to access the built-in extension classes without importing TipTap. And even if you do that you still wouldn't have access to Statamic’s extension classes.
• Statamic.$bard.extend() always appends extensions to the list, even if they’re intended to replace built-in extensions. While TipTap mostly handles this gracefully, it still adds both, which causes duplication and throws errors if the extension has plugins.
• Normally Statamic only adds the extensions that are applicable to the buttons enabled in Bard, however if you’re replacing built-in extensions the replacement always gets added, even if the relevant button isn’t enabled.

The changes are:

• Added Statamic.$bard.tiptap.extensions which exposes the built-in extension classes, so they can easily be extended without importing TipTap.
• Added Statamic.$bard.extendReplace() which will allow you to register callbacks that will return replacement extensions.
• The BardFieldtype component has been updated to apply the replacement extensions, but it only does that if the original extension is in the list.
• To ensure replacement extensions can have the same configuration as default ones a couple of additional variables (languages and levels) are now being passed to the callbacks.
• To ensure the Paragraph extension can be replaced it's being included in the default list.

This shouldn’t cause any BC breaks. Statamic.$bard.extend() still does exactly what it used to.

Sidenote

I’ve tried to do this with zero changes to the existing APIs, but that does mean that the naming is a bit awkward now:

• extend()
• extendReplace()
• buttons()

I wonder if it might be worth changing these to something more consistent and descriptive, like:

• addExtensions()
• replaceExtensions()
• addButtons()
• With extend() and buttons() as aliases for BC

This would be consistent with the equivalent methods in the Bard Augmentor as well.

I’ll leave that decision to you. I can make those changes if you agree.

Testing

Here is a simple example that can be used to test this change. It replaces the Heading extension with a custom version with a tweaked schema.

The heading text should change to red and if you check the list of extensions being passed to the TipTap editor it should only have one instance of a Heading extension (the custom one), or none if the heading buttons aren't enabled.

const{ Heading }=Statamic.$bard.tiptap.extensions;classCustomHeadingextendsHeading{getschema(){return{
...super.schema,toDOM: node=>[`h${node.attrs.level}`,{style: 'color: red',},0],}}}Statamic.booting(()=>{Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);});

[jacksleight]

This is now ready for review, when you have time. Thanks!

[jasonvarga]

Sorry for the delay.

Nice PR! I'm making a few changes though.

Instead of this:

Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);

You'll be able specify the extension by name, and the actual extension will be provided in the callback.

Statamic.$bard.replaceExtension('heading',({ extension })=>{returnnewCustomHeading({levels: extension.options.levels});// or even justreturnnewCustomHeading(extension.options);});

I'm gonna deprecate $bard.extend() and rename it to $bard.addExtension() like you suggested.
As well as change your extendReplace to replaceExtension.
I'll leave buttons as-is though, because you can add buttons or just manipulate them.

[jacksleight]

Amazing! That new replacement solution is much better!

I just committed one small change I missed in the original PR.

TipTap includes the Doc, Text and Paragraph nodes by default. Statamic is already overriding Doc, and this PR overrides Paragraph, which just leaves Text.

The TipTap editor has a useBuiltInExtensions option that you can set to false if you're overriding those extensions (https://github.com/ueberdosis/tiptap/blob/v1/packages/tiptap/src/Editor.js#L131).

I've set that and added Text to the list, so all the extensions are only added once now.

[jasonvarga]

Awesome, thanks!

[jacksleight]

This PR makes it possible to replace the built-in Bard TipTap nodes/marks with extended versions without causing duplication or errors. It also brings the Bard editor inline with the Bard Augmentor, which already supports node and mark class replacement.

The problems this solves are:

• There’s currently no way to access the built-in extension classes without importing TipTap. And even if you do that you still wouldn't have access to Statamic’s extension classes.
• Statamic.$bard.extend() always appends extensions to the list, even if they’re intended to replace built-in extensions. While TipTap mostly handles this gracefully, it still adds both, which causes duplication and throws errors if the extension has plugins.
• Normally Statamic only adds the extensions that are applicable to the buttons enabled in Bard, however if you’re replacing built-in extensions the replacement always gets added, even if the relevant button isn’t enabled.

The changes are:

• Added Statamic.$bard.tiptap.extensions which exposes the built-in extension classes, so they can easily be extended without importing TipTap.
• Added Statamic.$bard.extendReplace() which will allow you to register callbacks that will return replacement extensions.
• The BardFieldtype component has been updated to apply the replacement extensions, but it only does that if the original extension is in the list.
• To ensure replacement extensions can have the same configuration as default ones a couple of additional variables (languages and levels) are now being passed to the callbacks.
• To ensure the Paragraph extension can be replaced it's being included in the default list.

This shouldn’t cause any BC breaks. Statamic.$bard.extend() still does exactly what it used to.

Sidenote

I’ve tried to do this with zero changes to the existing APIs, but that does mean that the naming is a bit awkward now:

• extend()
• extendReplace()
• buttons()

I wonder if it might be worth changing these to something more consistent and descriptive, like:

• addExtensions()
• replaceExtensions()
• addButtons()
• With extend() and buttons() as aliases for BC

This would be consistent with the equivalent methods in the Bard Augmentor as well.

I’ll leave that decision to you. I can make those changes if you agree.

Testing

Here is a simple example that can be used to test this change. It replaces the Heading extension with a custom version with a tweaked schema.

The heading text should change to red and if you check the list of extensions being passed to the TipTap editor it should only have one instance of a Heading extension (the custom one), or none if the heading buttons aren't enabled.

const{ Heading }=Statamic.$bard.tiptap.extensions;classCustomHeadingextendsHeading{getschema(){return{
...super.schema,toDOM: node=>[`h${node.attrs.level}`,{style: 'color: red',},0],}}}Statamic.booting(()=>{Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);});

[jacksleight]

This is now ready for review, when you have time. Thanks!

[jasonvarga]

Sorry for the delay.

Nice PR! I'm making a few changes though.

Instead of this:

Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);

You'll be able specify the extension by name, and the actual extension will be provided in the callback.

Statamic.$bard.replaceExtension('heading',({ extension })=>{returnnewCustomHeading({levels: extension.options.levels});// or even justreturnnewCustomHeading(extension.options);});

I'm gonna deprecate $bard.extend() and rename it to $bard.addExtension() like you suggested.
As well as change your extendReplace to replaceExtension.
I'll leave buttons as-is though, because you can add buttons or just manipulate them.

[jacksleight]

Amazing! That new replacement solution is much better!

I just committed one small change I missed in the original PR.

TipTap includes the Doc, Text and Paragraph nodes by default. Statamic is already overriding Doc, and this PR overrides Paragraph, which just leaves Text.

The TipTap editor has a useBuiltInExtensions option that you can set to false if you're overriding those extensions (https://github.com/ueberdosis/tiptap/blob/v1/packages/tiptap/src/Editor.js#L131).

I've set that and added Text to the list, so all the extensions are only added once now.

[jasonvarga]

Awesome, thanks!

[jacksleight]

This PR makes it possible to replace the built-in Bard TipTap nodes/marks with extended versions without causing duplication or errors. It also brings the Bard editor inline with the Bard Augmentor, which already supports node and mark class replacement.

The problems this solves are:

• There’s currently no way to access the built-in extension classes without importing TipTap. And even if you do that you still wouldn't have access to Statamic’s extension classes.
• Statamic.$bard.extend() always appends extensions to the list, even if they’re intended to replace built-in extensions. While TipTap mostly handles this gracefully, it still adds both, which causes duplication and throws errors if the extension has plugins.
• Normally Statamic only adds the extensions that are applicable to the buttons enabled in Bard, however if you’re replacing built-in extensions the replacement always gets added, even if the relevant button isn’t enabled.

The changes are:

• Added Statamic.$bard.tiptap.extensions which exposes the built-in extension classes, so they can easily be extended without importing TipTap.
• Added Statamic.$bard.extendReplace() which will allow you to register callbacks that will return replacement extensions.
• The BardFieldtype component has been updated to apply the replacement extensions, but it only does that if the original extension is in the list.
• To ensure replacement extensions can have the same configuration as default ones a couple of additional variables (languages and levels) are now being passed to the callbacks.
• To ensure the Paragraph extension can be replaced it's being included in the default list.

This shouldn’t cause any BC breaks. Statamic.$bard.extend() still does exactly what it used to.

Sidenote

I’ve tried to do this with zero changes to the existing APIs, but that does mean that the naming is a bit awkward now:

• extend()
• extendReplace()
• buttons()

I wonder if it might be worth changing these to something more consistent and descriptive, like:

• addExtensions()
• replaceExtensions()
• addButtons()
• With extend() and buttons() as aliases for BC

This would be consistent with the equivalent methods in the Bard Augmentor as well.

I’ll leave that decision to you. I can make those changes if you agree.

Testing

Here is a simple example that can be used to test this change. It replaces the Heading extension with a custom version with a tweaked schema.

The heading text should change to red and if you check the list of extensions being passed to the TipTap editor it should only have one instance of a Heading extension (the custom one), or none if the heading buttons aren't enabled.

const{ Heading }=Statamic.$bard.tiptap.extensions;classCustomHeadingextendsHeading{getschema(){return{
...super.schema,toDOM: node=>[`h${node.attrs.level}`,{style: 'color: red',},0],}}}Statamic.booting(()=>{Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);});

[jacksleight]

This is now ready for review, when you have time. Thanks!

[jasonvarga]

Sorry for the delay.

Nice PR! I'm making a few changes though.

Instead of this:

Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);

You'll be able specify the extension by name, and the actual extension will be provided in the callback.

Statamic.$bard.replaceExtension('heading',({ extension })=>{returnnewCustomHeading({levels: extension.options.levels});// or even justreturnnewCustomHeading(extension.options);});

I'm gonna deprecate $bard.extend() and rename it to $bard.addExtension() like you suggested.
As well as change your extendReplace to replaceExtension.
I'll leave buttons as-is though, because you can add buttons or just manipulate them.

[jacksleight]

Amazing! That new replacement solution is much better!

I just committed one small change I missed in the original PR.

TipTap includes the Doc, Text and Paragraph nodes by default. Statamic is already overriding Doc, and this PR overrides Paragraph, which just leaves Text.

The TipTap editor has a useBuiltInExtensions option that you can set to false if you're overriding those extensions (https://github.com/ueberdosis/tiptap/blob/v1/packages/tiptap/src/Editor.js#L131).

I've set that and added Text to the list, so all the extensions are only added once now.

[jasonvarga]

Awesome, thanks!

[jacksleight]

This PR makes it possible to replace the built-in Bard TipTap nodes/marks with extended versions without causing duplication or errors. It also brings the Bard editor inline with the Bard Augmentor, which already supports node and mark class replacement.

The problems this solves are:

• There’s currently no way to access the built-in extension classes without importing TipTap. And even if you do that you still wouldn't have access to Statamic’s extension classes.
• Statamic.$bard.extend() always appends extensions to the list, even if they’re intended to replace built-in extensions. While TipTap mostly handles this gracefully, it still adds both, which causes duplication and throws errors if the extension has plugins.
• Normally Statamic only adds the extensions that are applicable to the buttons enabled in Bard, however if you’re replacing built-in extensions the replacement always gets added, even if the relevant button isn’t enabled.

The changes are:

• Added Statamic.$bard.tiptap.extensions which exposes the built-in extension classes, so they can easily be extended without importing TipTap.
• Added Statamic.$bard.extendReplace() which will allow you to register callbacks that will return replacement extensions.
• The BardFieldtype component has been updated to apply the replacement extensions, but it only does that if the original extension is in the list.
• To ensure replacement extensions can have the same configuration as default ones a couple of additional variables (languages and levels) are now being passed to the callbacks.
• To ensure the Paragraph extension can be replaced it's being included in the default list.

This shouldn’t cause any BC breaks. Statamic.$bard.extend() still does exactly what it used to.

Sidenote

I’ve tried to do this with zero changes to the existing APIs, but that does mean that the naming is a bit awkward now:

• extend()
• extendReplace()
• buttons()

I wonder if it might be worth changing these to something more consistent and descriptive, like:

• addExtensions()
• replaceExtensions()
• addButtons()
• With extend() and buttons() as aliases for BC

This would be consistent with the equivalent methods in the Bard Augmentor as well.

I’ll leave that decision to you. I can make those changes if you agree.

Testing

Here is a simple example that can be used to test this change. It replaces the Heading extension with a custom version with a tweaked schema.

The heading text should change to red and if you check the list of extensions being passed to the TipTap editor it should only have one instance of a Heading extension (the custom one), or none if the heading buttons aren't enabled.

const{ Heading }=Statamic.$bard.tiptap.extensions;classCustomHeadingextendsHeading{getschema(){return{
...super.schema,toDOM: node=>[`h${node.attrs.level}`,{style: 'color: red',},0],}}}Statamic.booting(()=>{Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);});

[jacksleight]

This is now ready for review, when you have time. Thanks!

[jasonvarga]

Sorry for the delay.

Nice PR! I'm making a few changes though.

Instead of this:

Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);

You'll be able specify the extension by name, and the actual extension will be provided in the callback.

Statamic.$bard.replaceExtension('heading',({ extension })=>{returnnewCustomHeading({levels: extension.options.levels});// or even justreturnnewCustomHeading(extension.options);});

I'm gonna deprecate $bard.extend() and rename it to $bard.addExtension() like you suggested.
As well as change your extendReplace to replaceExtension.
I'll leave buttons as-is though, because you can add buttons or just manipulate them.

[jacksleight]

Amazing! That new replacement solution is much better!

I just committed one small change I missed in the original PR.

TipTap includes the Doc, Text and Paragraph nodes by default. Statamic is already overriding Doc, and this PR overrides Paragraph, which just leaves Text.

The TipTap editor has a useBuiltInExtensions option that you can set to false if you're overriding those extensions (https://github.com/ueberdosis/tiptap/blob/v1/packages/tiptap/src/Editor.js#L131).

I've set that and added Text to the list, so all the extensions are only added once now.

[jasonvarga]

Awesome, thanks!

[jacksleight]

This PR makes it possible to replace the built-in Bard TipTap nodes/marks with extended versions without causing duplication or errors. It also brings the Bard editor inline with the Bard Augmentor, which already supports node and mark class replacement.

The problems this solves are:

• There’s currently no way to access the built-in extension classes without importing TipTap. And even if you do that you still wouldn't have access to Statamic’s extension classes.
• Statamic.$bard.extend() always appends extensions to the list, even if they’re intended to replace built-in extensions. While TipTap mostly handles this gracefully, it still adds both, which causes duplication and throws errors if the extension has plugins.
• Normally Statamic only adds the extensions that are applicable to the buttons enabled in Bard, however if you’re replacing built-in extensions the replacement always gets added, even if the relevant button isn’t enabled.

The changes are:

• Added Statamic.$bard.tiptap.extensions which exposes the built-in extension classes, so they can easily be extended without importing TipTap.
• Added Statamic.$bard.extendReplace() which will allow you to register callbacks that will return replacement extensions.
• The BardFieldtype component has been updated to apply the replacement extensions, but it only does that if the original extension is in the list.
• To ensure replacement extensions can have the same configuration as default ones a couple of additional variables (languages and levels) are now being passed to the callbacks.
• To ensure the Paragraph extension can be replaced it's being included in the default list.

This shouldn’t cause any BC breaks. Statamic.$bard.extend() still does exactly what it used to.

Sidenote

I’ve tried to do this with zero changes to the existing APIs, but that does mean that the naming is a bit awkward now:

• extend()
• extendReplace()
• buttons()

I wonder if it might be worth changing these to something more consistent and descriptive, like:

• addExtensions()
• replaceExtensions()
• addButtons()
• With extend() and buttons() as aliases for BC

This would be consistent with the equivalent methods in the Bard Augmentor as well.

I’ll leave that decision to you. I can make those changes if you agree.

Testing

Here is a simple example that can be used to test this change. It replaces the Heading extension with a custom version with a tweaked schema.

The heading text should change to red and if you check the list of extensions being passed to the TipTap editor it should only have one instance of a Heading extension (the custom one), or none if the heading buttons aren't enabled.

const{ Heading }=Statamic.$bard.tiptap.extensions;classCustomHeadingextendsHeading{getschema(){return{
...super.schema,toDOM: node=>[`h${node.attrs.level}`,{style: 'color: red',},0],}}}Statamic.booting(()=>{Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);});

[jacksleight]

This is now ready for review, when you have time. Thanks!

[jasonvarga]

Sorry for the delay.

Nice PR! I'm making a few changes though.

Instead of this:

Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);

You'll be able specify the extension by name, and the actual extension will be provided in the callback.

Statamic.$bard.replaceExtension('heading',({ extension })=>{returnnewCustomHeading({levels: extension.options.levels});// or even justreturnnewCustomHeading(extension.options);});

I'm gonna deprecate $bard.extend() and rename it to $bard.addExtension() like you suggested.
As well as change your extendReplace to replaceExtension.
I'll leave buttons as-is though, because you can add buttons or just manipulate them.

[jacksleight]

Amazing! That new replacement solution is much better!

I just committed one small change I missed in the original PR.

TipTap includes the Doc, Text and Paragraph nodes by default. Statamic is already overriding Doc, and this PR overrides Paragraph, which just leaves Text.

The TipTap editor has a useBuiltInExtensions option that you can set to false if you're overriding those extensions (https://github.com/ueberdosis/tiptap/blob/v1/packages/tiptap/src/Editor.js#L131).

I've set that and added Text to the list, so all the extensions are only added once now.

[jasonvarga]

Awesome, thanks!

[jacksleight]

This PR makes it possible to replace the built-in Bard TipTap nodes/marks with extended versions without causing duplication or errors. It also brings the Bard editor inline with the Bard Augmentor, which already supports node and mark class replacement.

The problems this solves are:

• There’s currently no way to access the built-in extension classes without importing TipTap. And even if you do that you still wouldn't have access to Statamic’s extension classes.
• Statamic.$bard.extend() always appends extensions to the list, even if they’re intended to replace built-in extensions. While TipTap mostly handles this gracefully, it still adds both, which causes duplication and throws errors if the extension has plugins.
• Normally Statamic only adds the extensions that are applicable to the buttons enabled in Bard, however if you’re replacing built-in extensions the replacement always gets added, even if the relevant button isn’t enabled.

The changes are:

• Added Statamic.$bard.tiptap.extensions which exposes the built-in extension classes, so they can easily be extended without importing TipTap.
• Added Statamic.$bard.extendReplace() which will allow you to register callbacks that will return replacement extensions.
• The BardFieldtype component has been updated to apply the replacement extensions, but it only does that if the original extension is in the list.
• To ensure replacement extensions can have the same configuration as default ones a couple of additional variables (languages and levels) are now being passed to the callbacks.
• To ensure the Paragraph extension can be replaced it's being included in the default list.

This shouldn’t cause any BC breaks. Statamic.$bard.extend() still does exactly what it used to.

Sidenote

I’ve tried to do this with zero changes to the existing APIs, but that does mean that the naming is a bit awkward now:

• extend()
• extendReplace()
• buttons()

I wonder if it might be worth changing these to something more consistent and descriptive, like:

• addExtensions()
• replaceExtensions()
• addButtons()
• With extend() and buttons() as aliases for BC

This would be consistent with the equivalent methods in the Bard Augmentor as well.

I’ll leave that decision to you. I can make those changes if you agree.

Testing

Here is a simple example that can be used to test this change. It replaces the Heading extension with a custom version with a tweaked schema.

The heading text should change to red and if you check the list of extensions being passed to the TipTap editor it should only have one instance of a Heading extension (the custom one), or none if the heading buttons aren't enabled.

const{ Heading }=Statamic.$bard.tiptap.extensions;classCustomHeadingextendsHeading{getschema(){return{
...super.schema,toDOM: node=>[`h${node.attrs.level}`,{style: 'color: red',},0],}}}Statamic.booting(()=>{Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);});

[jacksleight]

This is now ready for review, when you have time. Thanks!

[jasonvarga]

Sorry for the delay.

Nice PR! I'm making a few changes though.

Instead of this:

Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);

You'll be able specify the extension by name, and the actual extension will be provided in the callback.

Statamic.$bard.replaceExtension('heading',({ extension })=>{returnnewCustomHeading({levels: extension.options.levels});// or even justreturnnewCustomHeading(extension.options);});

I'm gonna deprecate $bard.extend() and rename it to $bard.addExtension() like you suggested.
As well as change your extendReplace to replaceExtension.
I'll leave buttons as-is though, because you can add buttons or just manipulate them.

[jacksleight]

Amazing! That new replacement solution is much better!

I just committed one small change I missed in the original PR.

TipTap includes the Doc, Text and Paragraph nodes by default. Statamic is already overriding Doc, and this PR overrides Paragraph, which just leaves Text.

The TipTap editor has a useBuiltInExtensions option that you can set to false if you're overriding those extensions (https://github.com/ueberdosis/tiptap/blob/v1/packages/tiptap/src/Editor.js#L131).

I've set that and added Text to the list, so all the extensions are only added once now.

[jasonvarga]

Awesome, thanks!

[jacksleight]

This PR makes it possible to replace the built-in Bard TipTap nodes/marks with extended versions without causing duplication or errors. It also brings the Bard editor inline with the Bard Augmentor, which already supports node and mark class replacement.

The problems this solves are:

• There’s currently no way to access the built-in extension classes without importing TipTap. And even if you do that you still wouldn't have access to Statamic’s extension classes.
• Statamic.$bard.extend() always appends extensions to the list, even if they’re intended to replace built-in extensions. While TipTap mostly handles this gracefully, it still adds both, which causes duplication and throws errors if the extension has plugins.
• Normally Statamic only adds the extensions that are applicable to the buttons enabled in Bard, however if you’re replacing built-in extensions the replacement always gets added, even if the relevant button isn’t enabled.

The changes are:

• Added Statamic.$bard.tiptap.extensions which exposes the built-in extension classes, so they can easily be extended without importing TipTap.
• Added Statamic.$bard.extendReplace() which will allow you to register callbacks that will return replacement extensions.
• The BardFieldtype component has been updated to apply the replacement extensions, but it only does that if the original extension is in the list.
• To ensure replacement extensions can have the same configuration as default ones a couple of additional variables (languages and levels) are now being passed to the callbacks.
• To ensure the Paragraph extension can be replaced it's being included in the default list.

This shouldn’t cause any BC breaks. Statamic.$bard.extend() still does exactly what it used to.

Sidenote

I’ve tried to do this with zero changes to the existing APIs, but that does mean that the naming is a bit awkward now:

• extend()
• extendReplace()
• buttons()

I wonder if it might be worth changing these to something more consistent and descriptive, like:

• addExtensions()
• replaceExtensions()
• addButtons()
• With extend() and buttons() as aliases for BC

This would be consistent with the equivalent methods in the Bard Augmentor as well.

I’ll leave that decision to you. I can make those changes if you agree.

Testing

Here is a simple example that can be used to test this change. It replaces the Heading extension with a custom version with a tweaked schema.

The heading text should change to red and if you check the list of extensions being passed to the TipTap editor it should only have one instance of a Heading extension (the custom one), or none if the heading buttons aren't enabled.

const{ Heading }=Statamic.$bard.tiptap.extensions;classCustomHeadingextendsHeading{getschema(){return{
...super.schema,toDOM: node=>[`h${node.attrs.level}`,{style: 'color: red',},0],}}}Statamic.booting(()=>{Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);});

[jacksleight]

This is now ready for review, when you have time. Thanks!

[jasonvarga]

Sorry for the delay.

Nice PR! I'm making a few changes though.

Instead of this:

Statamic.$bard.extendReplace(({ levels })=>[[Heading,newCustomHeading({ levels })],]);

You'll be able specify the extension by name, and the actual extension will be provided in the callback.

Statamic.$bard.replaceExtension('heading',({ extension })=>{returnnewCustomHeading({levels: extension.options.levels});// or even justreturnnewCustomHeading(extension.options);});

I'm gonna deprecate $bard.extend() and rename it to $bard.addExtension() like you suggested.
As well as change your extendReplace to replaceExtension.
I'll leave buttons as-is though, because you can add buttons or just manipulate them.

[jacksleight]

Amazing! That new replacement solution is much better!

I just committed one small change I missed in the original PR.

TipTap includes the Doc, Text and Paragraph nodes by default. Statamic is already overriding Doc, and this PR overrides Paragraph, which just leaves Text.

The TipTap editor has a useBuiltInExtensions option that you can set to false if you're overriding those extensions (https://github.com/ueberdosis/tiptap/blob/v1/packages/tiptap/src/Editor.js#L131).

I've set that and added Text to the list, so all the extensions are only added once now.

[jasonvarga]

Awesome, thanks!