feat(ui): fixed toolbar group customization

[ruslan-amboss]

What

This PR introduces a comprehensive customization system for toolbar groups in the Lexical Rich Text Editor. It allows developers to override not just the order, but virtually any aspect of toolbar components (such as format, align, indent) through the FixedToolbarFeature configuration. Customizable properties include order, icons, group type, and more.

Why

Previously, toolbar group configurations were hardcoded in their respective components with no way to modify them without changing the source code. This made it difficult for developers to:

1. Reorder toolbar components to match specific UX requirements
2. Replace icons with custom ones to maintain design consistency
3. Transform dropdown groups into button groups or vice versa
4. Apply other customizations needed for specific projects

This enhancement provides full flexibility for tailoring the rich text editor interface while maintaining a clean and maintainable codebase.

How

The implementation consists of three key parts:

1. Enhanced the FixedToolbarFeature API:

   • Added a new customGroups property to FixedToolbarFeatureProps that accepts a record mapping group keys to partial ToolbarGroup objects
   • These partial objects can override any property of the default toolbar group configuration

2. Leveraged existing deep merge utility:

   • Used Payload's existing deepMerge utility to properly combine default configurations with custom overrides
   • This ensures that only specified properties are overridden while preserving all other default behaviors

3. Applied customizations in the sanitization process:

   • Updated the sanitizeClientFeatures function to identify and apply custom group configurations
   • Applied deep merging before the sorting process to ensure proper ordering with customized configurations
   • Maintained backward compatibility for users who don't need customization

Usage Example

import { FixedToolbarFeature } from '@payloadcms/richtext-lexical'
import { CustomIcon } from './icons/CustomIcon'

{
  name: 'content',
  type: 'richText',
  admin: {
    features: [
      // Other features...
      FixedToolbarFeature({
        customGroups: {
            'text': {
              order: 10,
              ChildComponent: CustomIcon,
            },
            'format': {
              order: 15,
            },
            'add': {
              type: 'buttons',
              order: 20,
            },
        }
      })
    ]
  }
}

Demo

fixed-toolbar-customization.mov

[GermanJablo]

ToolbarGroup is designed to be used on the client. To pass it as a property to FixedToolbarFeature, we could accept only the serializable subset of properties.
This would mean excluding isEnabled and items from ToolbarDropdownGroup. Theoretically, some subproperties of items could also be retained with a bit more complexity in the types.

Your example in the PR description/video works because you only used properties from that subset of serializable properties. Also, while it's probably not a problem since they're usually static icons, I would add to the tsdoc that ChildComponent must be a server component.

[ruslan-amboss]

Thanks for clarifying! That makes sense regarding the need for serialization.

[GermanJablo]

This type makes your example not work

text: {
  order: 10,
  ChildComponent: SwapIcon, // Object literal may only specify known properties, and 'ChildComponent' does not exist in type 'Partial<Omit<ToolbarGroup, "isEnabled" | "items">>'.
},

Additionally, if the item contains type: "button", it should not allow ChildComponent or maxActiveItems

// this should give a ts error
hello: {
  key: 'hello',
  order: 1,
  type: 'buttons',
  maxActiveItems: 1,
},

[ruslan-amboss]

Got the idea! Pushed the updated types, which pass your examples

type CustomDropdownGroup = Partial<Omit<ToolbarDropdownGroup, 'isEnabled' | 'items'>>
type CustomButtonsGroup = Partial<
  Omit<ToolbarButtonsGroup, 'ChildComponent' | 'isEnabled' | 'items' | 'maxActiveItems'>
>
type CustomGroup = CustomButtonsGroup | CustomDropdownGroup
export type CustomGroups = Record<string, CustomGroup>

[GermanJablo]

Thank you!

[github-actions]

🚀 This is included in version v3.38.0