What does this PR do?

This is a proposal for a ToggleGroup component to follow on which design work that has been done.

The ToggleGroup is a Box with Buttons within it. The default type is a user can select one option from the group as far as if a user wants more options they pass multiple similar to how Select uses the multiple prop. This component provides the layout of the container which has rounded edges, direction='row', and a right border that is served as a separator since gap='none.

// API
  multiple?: boolean;
  onToggle?: (event: React.ClickEvent + value) => void;
  options?: (
    | string
    | {
        icon?: React.ReactNode | JSX.Element;
        label?: string | React.ReactNode;
        value: string;
      }
  )[];
  value?: string | string[];

base.js
{
  toggleGroup?: {
    button?: {
      pad?: PadType;
      iconOnly?: {
        pad?: PadType;
      };
    };
    container?: BoxProps;
    divider?: {
      color?: ColorType;
    };
  };
};

Rationale for certain naming/behavior decisions

What: ToggleGroup is a specialized group of buttons that supports single and multiple selection/toggling.

Theming approach: Because ToggleGroup is built with buttons, inherit a theme’s button styling as is and minimize the custom overrides that ToggleGroup applies to the buttons. For any overrides, honor the “button” theme mentalities (API, any logic/conditional styling/etc.).

Necessary overrides:

• To match rounding of ToggleGroup container, override border-radius of individual buttons.
• Padding behavior:
  • For theme.button.default (“kind”) themes: the approach is generally for border width to be subtracted from the padding (so people might expect this as they built up their theme styling). In how this component is built, the border is on the container Box, so we should do the subtraction for them.
  • In non “kind” themes, the caller is always responsible for “pad minus border” calculation themselves, so we shouldn’t do any calculation.

Stylistic overrides:

• Base theme has a “brand” color border that comes through for buttons with labels → Remove that so the container border and divider border is the style
• Base theme has different hover behaviors for icon-only (no hover background) and buttons with labels (box-shadow that increases border width) → Since the ToggleGroup buttons don’t have any individual border to begin width, don’t add the “purple” border. The “purple” border would be inconsistent with other controls because we don’t typically add a border onto a component if its default state didn’t have one.
• Should base theme be inheriting the “button” border color for the container?
  • No, will be more prominent than other controls, keep the subtle container border. Caller can always override in their theme if they want otherwise.

What determined the base.js toggleGroup.button.pad?

Icon-only cases are the main use case for the ToggleGroup. In grommet theme, icon-only and labelled buttons have different dimensions. In order to lean towards the 80% case for ToggleGroup use cases and maintain consistency across different combinations of ToggleGroup options, aligning the dimensions for all ToggleGroups to that of base.js icon-only button (48px tall).

Why named “ToggleGroup”?

When viewing Google search trends it was found that toggleGroup was used more across the wider region.
Another downside to using ToggleButtonGroup is how long the word is and in many places in the code base we would need to disable eslint for the imports since the line would be over a amount of characters.
Did button actually have any meaning even though this component was made with a Button this did not necessarily need to be made known to the user.

Why enforce a value once one is selected in single selection?

80% of use cases all have one selected option for a toggleGroup. For our specific need for this component a use case was toggling through either a map list or data view where at least one of those needed to be selected.

Why onToggle?

This handler is called any time a button is clicked, effectively "toggling" an individual button. Initially we had onChange, but this felt in accurate and misaligned with the general Grommet mentality to honor native HTML events. In this case, it's not a change event but just a click event.

Where should the reviewer start?

ToggleGroup.js

What testing has been done on this PR?

storybook. Additional test code for HPE vs Grommet theming:

import React, { useState } from 'react';
import {
  Box,
  Button,
  ToggleGroup,
  Text,
  Grommet,
  Toolbar,
  DataFilters,
  Data,
  DataSearch,
  DataSummary,
} from 'grommet';
import { deepMerge } from 'grommet-icons/utils';
import { hpe } from 'grommet-theme-hpe';
import {
  Bold,
  Italic,
  List,
  MapLocation,
  Table,
  Underline,
} from 'grommet-icons';

const theme = deepMerge(hpe, {
  toggleGroup: {
    button: {
      pad: {
        vertical: 'xsmall',
        horizontal: 'small',
      },
      iconOnly: {
        pad: '9px',
      },
    },
  },
});

const Content = () => {
  const [value, setValue] = useState(['Option 2']);

  return (
    <Box direction="row" align="start" gap="small">
      <ToggleGroup
        options={['Option 1', 'Option 2', 'Option 3']}
        value={value}
        onToggle={(e) => {
          if (e.value.length) setValue(e.value);
        }}
        multiple
      />
      <ToggleGroup
        options={[
          { icon: <Bold />, value: 'b' },
          { icon: <Italic />, label: 'Italic', value: 'i' },
          { icon: <Underline />, value: 'u' },
        ]}
        multiple
      />
      <Button label="Button" primary />
      <Button icon={<Bold />} primary />
    </Box>
  );
};

const Views = () => (
  <ToggleGroup
    options={[
      { icon: <MapLocation />, value: 'b' },
      { icon: <List />, value: 'i' },
      { icon: <Table />, value: 'u' },
    ]}
    defaultValue="b"
  />
);

const ToolbarView = () => (
  <Box>
    <Data data={[]}>
      <Toolbar>
        <DataSearch />
        <DataFilters layer />
        <Views />
        <Box flex />
        <Button label="Actions" />
      </Toolbar>
      <DataSummary />
    </Data>
  </Box>
);

export const Controlled = () => (
  <Box gap="large" overflow="auto">
    <Box gap="large" pad="large">
      <Text>In multiple selection mode, enforce at least one selection.</Text>
      <Content />
      <Grommet theme={theme}>
        <Content />
      </Grommet>
    </Box>
    <Box gap="large" pad="large">
      {/* <Text>In multiple selection mode, enforce at least one selection.</Text> */}
      <ToolbarView />
      <Grommet theme={theme}>
        <ToolbarView />
      </Grommet>
    </Box>
  </Box>
);

export default {
  title: 'Controls/ToggleGroup/Controlled',
};

How should this be manually tested?

storybook

Do Jest tests follow these best practices?

• - Need to add tests
• screen is used for querying.
• The correct query is used. (Refer to this list of queries)
• asFragment() is used for snapshot testing.

Any background context you want to provide?

NEW ToggleGroup component was needed

What are the relevant issues?

closes #grommet/hpe-design-system#3739

Screenshots (if appropriate)

Do the grommet docs need to be updated?

yes

Should this PR be mentioned in the release notes?

yes

Is this change backwards compatible or is it a breaking change?

backwards compatible