Custom Bard buttons can be added conditionally

[morhi]

When adding custom buttons to bard using

Statamic.$bard.buttons( (button) => { ... } );

the buttons will be available in any bard instance, without the possibility to disable them in the blueprint editor. This PR adds the option to enable or disable custom buttons from addons or the project for each fieldtype config.

Blueprint Editor:

Bard Instance:

Javascript Usage:

Statamic.$bard.buttons((buttons, selectedButtons) => {
    return [
        {
            name: 'world',
            text: 'Beatiful World',
            command: 'beautifulWorld
            args: { world: 'beautiful' },
            icon: 'check',
            component: BeautifulWorldButton,
        },
    ];
});

// or

Statamic.$bard.buttons((buttons, selectedButtons) => {
    if (!selectedButtons || selectedButtons.include('world')) {
        buttons.push({
            name: 'world',
            text: 'Beatiful World',
            command: 'beautifulWorld
            args: { world: 'beautiful' },
            icon: 'check',
            component: BeautifulWorldButton,
        });
    }
});

Closes #2340

[jasonvarga]

What's the purpose of the new selectedButtons argument being passed into the callback? It's being filtered out immediately anyway.

[morhi]

What's the purpose of the new selectedButtons argument being passed into the callback? It's being filtered out immediately anyway.

This is more like backwards-compatibility issue. The Statamic.$bard.buttons is called from two places: 1) In the blueprint editor, where you can define which buttons should be available for this bard field 2) In the entry publish form, where the field is actually used.

So in case 1 all buttons should be shown. In case 2 only the selected buttons from 1) should be shown. However, this is not a problem, as long as you return an array of buttons that should be added, because they will be filtered out automatically according to their availability state. But there is the possibility to directly manipulate the buttons reference without returning a value, which makes the button always appear in case 2), if you don't manipulate the buttons conditionally.

When you look at https://statamic.dev/extending/bard#buttons the reference manipulation is one of the examples.

Maybe I can fix this, so it is not necessary to do this extra check.

[jasonvarga]

Thanks for this PR, and sorry for the delay on it.

The way you had it was a breaking change. If you didn't have the button configured in the buttons array in the blueprint, it would no longer be visible in the toolbar.

What I've done is introduce a button function that developers can use to wrap their buttons in.

When we use the callback in the fieldtype, it'll filter itself out if it's not configured in the buttons array.
When we use the callback in the blueprint builder, it'll always show it.

Statamic.$bard.buttons((buttons, button) => {
    return button({ name: 'bold' });
    // or multiple...
    return [
      button({ name: 'bold' }),
      button({ name: 'italic' }),
    ];
});

People using the existing way, where you return an object or an array of objects, it'll continue to add the button to all fields. If they want to start making it conditional, they can just wrap their object in button().

I also removed the css change, it was a bit buggy in the regular fieldtype. Feel free to open a separate issue or PR for that.