[RFC] SplitButton component

[silviuaavram]

Split Button component

Problem description

We need a component that offers the user a list of actionable options. The first option, most used, should be actionable by a button. All the options should be contained in a menu that is shown via a toggle action, provided by a second button.

Proposed solution

The SplitButton should be a widget containing:

1. Main button which, on trigger, executes the first option, the most used.
2. Toggle button which, on toggle, shows/hides a menu with all the options.
3. Vertical Menu that contains the options. Clicking an option should trigger the action associated with that option. Optionally, it should just replace the active option on the main button which will be executed by click.

API Proposal

  /** Shorthand array of props for Menu. */
  items: ShorthandCollection<MenuItemProps>

  /** Index of the item that appears on the button. Default is 0. */
  mainItemIndex: number

  /**
   * Called after user's click.
   *
   * @param {SyntheticEvent} event - React's original SyntheticEvent.
   * @param {object} data - All props.
   */
  onClick?: ComponentEventHandler<ButtonProps>

  /**
   * Called when an item is clicked.
   *
   * @param {SyntheticEvent} event - React's original SyntheticEvent.
   * @param {object} data - All item props.
   */
  onItemClick?: ComponentEventHandler<MenuItemProps>

  /**
   * Called after user's click on the toggle button.
   *
   * @param {SyntheticEvent} event - React's original SyntheticEvent.
   * @param {object} data - All item props.
   */
  onToggle?: ComponentEventHandler<ButtonProps>

  /** The toggle button to display menu of items. */
  toggleButton?: ShorthandValue<ButtonProps>

  /** A split button can be formatted to show different levels of emphasis. */
  primary?: boolean

  /** A split button can be formatted to show different levels of emphasis. */
  secondary?: boolean

The items shorthand will be used to create both the Button and the MenuItem. Both have in common content and icon. Also onClick which is used to execute actions.

SplitButton will accept props such as primary and secondary which will be passed to both buttons. For further individual customisation, shorthands should be used.

If we decide to have shorthand for the main button as well, then we need to manually merge props between this shorthand and the item associated to it.

Other Libraries APIs:

PrimeReact:

• main option is completely separated from other options.
• items have similar shorthand props: label (content), icon, command (onClick).

Accessibility:

• select options via keyboard from the menu. Highlighted option should be maintained in state and keydown for up/down arrows should be added to toggleButton, via behaviors.
• narration of these options.
• expanded/collapsed on the toggle button.

Alternative

Create examples in the docsite that show how to use Button and Menu to create such a widget, without creating an actual component.
Stateful logic may not be trivial if we also want to add kb navigation between the items.

Docsite Examples

• Outlook New Message button, with both content and icons.
  
• Squash and merge similar button. Only content. Selection option just adds it to the button, so the user can click it afterwards (similar to how the Github button works).

- Main option disabled (and the main button implicitly) so user needs to go to the menu in order to perform an action, different from the main one.

[silviuaavram]

progress so far: #1747

will let it as it is before feedback.

[lucivpav]

Can we have something like a replacable?: boolean prop? If true, the menu option will replace the action option of main button.

[layershifter]

Can you please clarify how it's different from usage of two buttons? Are there accessibility concerns? Do you have references to other UI libraries?

---

  <Flex gap="gap.smaller">
    <Button content="Squash and merge" />
    <Button icon={{ name: 'arrow-down' }} iconOnly />
  </Flex>

Then...

---

  <Button.Group>
    <Button content="Squash and merge" />
    <Button icon={{ name: 'arrow-down' }} iconOnly />
  </Button.Group>

And @jurokapsiar is working on MenuButton in #1696:

      <Button.Group>
        <Button content="Squash and merge" />
        <MenuButton
          trigger={<Button icon={{ name: 'arrow-down' }} iconOnly />}
          menu={{
            items,
          }}
          on="click"
        />
      </Button.Group>

[jurokapsiar]

Regarding replacable, that can be up to consumer - if he wants his menu items to replace the main button functionality, he can do that in his click handlers.

Instead of having a list of menu items and picking one of them to be the main item using mainItemIndex, I would propose to have content and icon and a onClick props similar to the button. Menu should be fully defined using the menu prop.

One more thinkg to think about - what should be the DOM structure? My guess is it should render two <button>s, the second should have tabindex -1. We can still show the focus indicator over the whole splitbutton even if only the first is focused.

[miroslavstastny]

OneNote example

Focused by keyboard - focus ring is around the whole thing, background changes only for the first part, Alt+down arrow opens the menu.

Opened menu is start-aligned with the whole button.

[miroslavstastny]

We should also check other libraries to decide whether SplitButton is a separate component or a variation of a Button (that's what Office UI Fabric does)

[silviuaavram]

We decided to get feedback from PM. We can either:

• have separate buttons, with a normal Button and a MenuButton, in which case we can just create some examples in the docsite.
• have Fabric way of doing it, of having a wrapper that accepts key down events, in which case we should probably create a component, since a11y logic may be more complicated.

[levithomason]

Let's move further convo to the open work on this:

#1798