Box UI Elements

The DraftJSEditor component provides a Draft.js editor interface within box-ui-elements.

State Management

This component is uncontrolled regarding its editorState. It does not own or manage the editor state internally. Instead, you must manage the EditorState in your own application logic and pass it to the component.

Handling Changes

Whenever the content within the <Editor /> changes, the component triggers its onChange method, passing the new EditorState as an argument. You should use this callback to update your local state.

Using Decorators

Because the component does not own the EditorState, you cannot configure Draft.js decorators via the DraftJSEditor component itself. You must apply any decorators (for features like mentions or custom formatting) at the point where you define and manage the EditorState in your application.

// Conceptual usage pattern:
// 1. Manage EditorState in your parent component
// 2. Pass state to DraftJSEditor
// 3. Update state via onChange

<DraftJSEditor 
  editorState={this.state.editorState} 
  onChange={(nextEditorState) => this.setState({ editorState: nextEditorState })} 
/>

The Portal component is used to render children into a DOM node outside of the current component's hierarchy. This is specifically useful for UI elements that need to break out of parent containers, such as modals, notifications, popovers, and flyouts.

Key behaviors to note:

• Logic only: Portal only manages the mounting and unmounting logic to the outside DOM; it does not provide any built-in styles, event handlers, or behaviors. You must implement these in your parent component.
• Context: React context is preserved and passed from the Portal parent to the children components.
• Props: Any props passed to Portal (such as className) are applied directly to the inner-wrapper div that contains the children.

import { Portal } from 'box-ui-elements';

const MyPortalExample = ({ isOpen }) => {
    if (!isOpen) return null;
    return (
        <Portal className='modal-wrapper'>
            <div className='modal'>...
            </div>
        </Portal>
    );
}

The <Menu> component provides an ARIA-compliant menu implementation, handling keyboard navigation, focus management, and appropriate ARIA attributes according to the WAI-ARIA Menu standard.

To build a menu, you can use several sub-components:

• <MenuItem>: A standard menu item.
• <MenuSeparator />: A visual divider between items.
• <MenuSectionHeader>: A header for grouping menu items.
• <MenuLinkItem>: Required for wrapping anchor tags (<a> or <Link>) to ensure correct ARIA behavior for links within a menu.
• <SelectMenuLinkItem>: Used for items that represent a selectable state, typically rendered with a checkmark.
• <SubmenuItem>: Used to nest a <Menu> inside another menu to create submenus.

const { 
  MenuItem, 
  MenuSeparator, 
  MenuLinkItem, 
  MenuSectionHeader 
} = require('box-ui-elements/es/components/menu');

<Menu>
  <MenuItem>View Profile</MenuItem>
  <MenuItem showRadar>Help</MenuItem>
  <MenuSeparator />
  <MenuSectionHeader>Menu Section</MenuSectionHeader>
  <MenuLinkItem>
    <Link href="/#">Awesome Link</Link>
  </MenuLinkItem>
</Menu>;

Rich text styling in this component is handled via two mechanisms:

Entities

Entities annotate a range of text with metadata. In DraftJSMentionSelector, mentions are implemented as entities.

1. Create an entity using contentState.createEntity().
2. Use Modifier.replaceText(...) to replace the partial text (e.g., @se) with the full entity-ified text (e.g., @Sebastian Motraghi) to generate a new ContentState.
3. The mention entity includes an id in its metadata.

Decorators

Decorators scan text to determine which ranges should be rendered with special UI.

• The mentionDecorator is applied when creating the initial EditorState.
• The mentionStrategy identifies ranges that have an Entity annotated as type: 'MENTION'.
• Important Implementation Rule: When creating custom components for decorators, do not set text from a prop. The decorator sets the children prop with the actual text content. Your component must use { props.children } to ensure the rendered UI matches the internal state.

Correct Pattern:

// Do this
<MyDecoratorComponent>{ props.children }</MyDecoratorComponent>

// Do NOT do this
<MyDecoratorComponent text={ props.text } />