@strapi/design-system 1.2.7 → 1.3.0-beta.1

package/src/Select/Select.js

@@ -0,0 +1,318 @@
+import React, { Children, cloneElement, useRef, useState } from 'react';
+import PropTypes from 'prop-types';
+import CarretDown from '@strapi/icons/CarretDown';
+import Cross from '@strapi/icons/Cross';
+import { sizes } from '../themes/sizes';
+import { SelectButton } from './SelectButton';
+import { Field, FieldHint, FieldLabel, FieldError } from '../Field';
+import { Popover } from '../Popover';
+import { Stack } from '../Stack';
+import { Typography } from '../Typography';
+import { Flex } from '../Flex';
+import { Box } from '../Box';
+import { useId } from '../helpers/useId';
+import { SelectList } from './SelectList';
+import { SelectButtonWrapper, IconBox, CaretBox } from './components';
+import { useButtonRef } from './hooks/useButtonRef';
+import { VisuallyHidden } from '../VisuallyHidden';
+import { DownState } from './constants';
+import { escapeSelector } from '../helpers/escapeSelector';
+import { SelectTags } from './SelectTags';
+import styled from 'styled-components';
+
+const MainRow = styled(Flex)`
+  width: 100%;
+`;
+
+export const Select = ({
+  label,
+  labelAction,
+  id,
+  children,
+  customizeContent,
+  placeholder,
+  onChange,
+  value,
+  hint,
+  error,
+  disabled,
+  clearLabel,
+  onClear,
+  onReachEnd,
+  multi,
+  required,
+  selectButtonTitle,
+  size,
+  startIcon,
+  withTags,
+  ...props
+}) => {
+  const generatedId = useId('select', id);
+  const [expanded, setExpanded] = useState(undefined);
+  const buttonRef = useButtonRef(expanded);
+  const containerRef = useRef(null);
+
+  const labelId = `${generatedId}-label`;
+  const contentId = `${generatedId}-content`;
+  const hasStringError = typeof error === 'string';
+  const errorMessageId = hasStringError ? `${generatedId}-error` : undefined;
+  const hintMessageId = hint ? `${generatedId}-hint` : undefined;
+
+  const ariaDescribedBy = errorMessageId || hintMessageId;
+
+  if (withTags && !multi) {
+    throw new Error('The "withTags" props can only be used when the "multi" prop is present');
+  }
+
+  const handleEscape = () => {
+    setExpanded(undefined);
+  };
+
+  const handleClear = () => {
+    if (disabled) return;
+
+    onClear();
+    buttonRef.current.focus();
+  };
+
+  const handleMouseDown = (e) => {
+    e.preventDefault();
+    if (disabled) return;
+    // Check if the right click has been clicked
+    // "which" check is for webkit
+    if (e.nativeEvent.which === 3 || e.nativeEvent.button === 2) {
+      return;
+    }
+
+    setExpanded(DownState.Mouse);
+  };
+
+  const handleSelectItem = (newValue, closeMenu = true) => {
+    if (multi) {
+      onChange(value.includes(newValue) ? value.filter((x) => x !== newValue) : [...value, newValue]);
+    } else {
+      onChange(newValue);
+      if (closeMenu) setExpanded(undefined);
+    }
+  };
+
+  const handleSelectGroupItem = (newValue) => {
+    onChange(
+      value.includes(newValue[0])
+        ? value.filter(function (e) {
+            return this.indexOf(e) < 0;
+          }, newValue)
+        : [...value, ...newValue],
+    );
+  };
+
+  let selectOptionLabel;
+  let tags = [];
+
+  const cloneOption = (node, isChild) => {
+    const optionId = `${generatedId}-option-${node.props.value}`;
+
+    const selected = multi ? value.includes(node.props.value) : node.props.value === value;
+
+    if (selected) {
+      if (withTags) {
+        tags.push({ label: node.props.children, value: node.props.value });
+      } else {
+        selectOptionLabel = node.props.children;
+      }
+    }
+
+    return cloneElement(node, {
+      id: escapeSelector(optionId),
+      onClick: () => handleSelectItem(node.props.value),
+      selected,
+      multi,
+      isChild,
+    });
+  };
+
+  const childrenClone = Children.toArray(children).map((node) => {
+    if (node.type.displayName === 'OptGroup') {
+      const optionId = `${generatedId}-option-${node.props.label}`;
+
+      const selected = node.props.children.every((child) => value.includes(child.props.value));
+      const indeterminate = !selected && node.props.children.some((child) => value.includes(child.props.value));
+
+      return cloneElement(node, {
+        id: escapeSelector(optionId),
+        onClick: () => handleSelectGroupItem(node.props.children.map((child) => child.props.value)),
+        selected,
+        indeterminate,
+        multi,
+        children: Children.toArray(node.props.children).map((node) => cloneOption(node, true)),
+        value: node.props.label,
+      });
+    } else {
+      return cloneOption(node);
+    }
+  });
+
+  return (
+    <Field hint={hint} error={error} id={generatedId}>
+      <Stack spacing={label || hint || hasStringError ? 1 : 0}>
+        {label && (
+          <FieldLabel required={required} as="span" id={labelId} action={labelAction}>
+            {label}
+          </FieldLabel>
+        )}
+
+        <SelectButtonWrapper size={size} hasError={Boolean(error)} disabled={disabled} ref={containerRef}>
+          <SelectButton
+            ref={buttonRef}
+            labelledBy={`${labelId} ${contentId}`}
+            aria-describedby={ariaDescribedBy}
+            expanded={Boolean(expanded)}
+            onTrigger={setExpanded}
+            id={generatedId}
+            hasError={Boolean(error)}
+            disabled={disabled}
+            onMouseDown={handleMouseDown}
+            {...props}
+          />
+
+          <MainRow justifyContent="space-between">
+            <Flex>
+              {startIcon && (
+                <Box paddingLeft={3} aria-hidden={true}>
+                  {startIcon}
+                </Box>
+              )}
+
+              {withTags && <SelectTags tags={tags} onRemoveTag={handleSelectItem} disabled={disabled} />}
+
+              <Box paddingLeft={4} paddingRight={4}>
+                {withTags ? (
+                  <>
+                    {!value || value.length === 0 ? (
+                      <Typography ellipsis id={contentId} textColor={'neutral600'}>
+                        {placeholder}
+                      </Typography>
+                    ) : null}
+                    <VisuallyHidden as="span" id={contentId}>
+                      {customizeContent ? customizeContent(value) : selectOptionLabel || placeholder}
+                      {value.join(', ')}
+                    </VisuallyHidden>
+                  </>
+                ) : (
+                  <Typography ellipsis id={contentId} textColor={value ? 'neutral800' : 'neutral600'}>
+                    {customizeContent ? customizeContent(value) : selectOptionLabel || placeholder}
+                    {multi && <VisuallyHidden as="span">{value.join(', ')}</VisuallyHidden>}
+                  </Typography>
+                )}
+              </Box>
+            </Flex>
+
+            <Flex>
+              {((multi && value && value.length) || (!multi && value)) && onClear && (
+                <IconBox
+                  as="button"
+                  type="button"
+                  onClick={handleClear}
+                  aria-label={clearLabel}
+                  aria-disabled={disabled}
+                  title={clearLabel}
+                >
+                  <Cross />
+                </IconBox>
+              )}
+
+              <CaretBox
+                paddingLeft={3}
+                aria-hidden
+                as="button"
+                type="button"
+                onMouseDown={handleMouseDown}
+                tabIndex={-1}
+                disabled={disabled}
+                title={selectButtonTitle}
+              >
+                <CarretDown />
+              </CaretBox>
+            </Flex>
+          </MainRow>
+        </SelectButtonWrapper>
+
+        <FieldHint />
+        <FieldError />
+      </Stack>
+
+      {expanded && (
+        <Popover
+          source={containerRef}
+          spacing={4}
+          fullWidth
+          intersectionId={`select-list-intersection-${generatedId}`}
+          onReachEnd={onReachEnd}
+        >
+          <SelectList
+            selectId={generatedId}
+            labelledBy={label ? labelId : undefined}
+            onEscape={handleEscape}
+            expanded={expanded}
+            onSelectItem={(value, isGroup) => (isGroup ? handleSelectGroupItem(value) : handleSelectItem(value, false))}
+            multi={multi}
+          >
+            {childrenClone}
+          </SelectList>
+        </Popover>
+      )}
+    </Field>
+  );
+};
+
+Select.defaultProps = {
+  'aria-label': undefined,
+  children: [],
+  clearLabel: 'Clear',
+  customizeContent: undefined,
+  disabled: false,
+  id: undefined,
+  label: undefined,
+  labelAction: undefined,
+  multi: false,
+  onChange: () => {},
+  onClear: undefined,
+  onReachEnd: undefined,
+  value: undefined,
+  hint: undefined,
+  error: undefined,
+  placeholder: 'Select...',
+  required: false,
+  selectButtonTitle: 'Carret Down Button',
+  size: 'M',
+  startIcon: undefined,
+  withTags: false,
+};
+
+Select.propTypes = {
+  'aria-label': PropTypes.string,
+  children: PropTypes.oneOfType([PropTypes.arrayOf(PropTypes.node), PropTypes.node]),
+  clearLabel: PropTypes.string,
+  customizeContent: PropTypes.func,
+  disabled: PropTypes.bool,
+  error: PropTypes.oneOfType([PropTypes.string, PropTypes.bool]),
+  hint: PropTypes.oneOfType([PropTypes.string, PropTypes.node, PropTypes.arrayOf(PropTypes.node)]),
+  id: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
+  label: PropTypes.string,
+  labelAction: PropTypes.element,
+  multi: PropTypes.bool,
+  onChange: PropTypes.func,
+  onClear: PropTypes.func,
+  onReachEnd: PropTypes.func,
+  placeholder: PropTypes.string,
+  required: PropTypes.bool,
+  selectButtonTitle: PropTypes.string,
+  size: PropTypes.oneOf(Object.keys(sizes.input)),
+  startIcon: PropTypes.element,
+  value: PropTypes.oneOfType([
+    PropTypes.arrayOf(PropTypes.oneOfType([PropTypes.string, PropTypes.number])),
+    PropTypes.string,
+    PropTypes.number,
+  ]),
+  withTags: PropTypes.bool,
+};

package/src/Select/Select.stories.mdx

@@ -0,0 +1,362 @@
+<!--- Select.stories.mdx --->
+
+import { useState } from 'react';
+import { Meta, Story, Canvas } from '@storybook/addon-docs';
+import { ArgsTable } from '@storybook/addon-docs';
+import Earth from '@strapi/icons/Earth';
+import Plus from '@strapi/icons/Plus';
+import { Select } from './Select';
+import { Option } from './Option';
+import { Stack } from '../Stack';
+import { Typography } from '../Typography';
+import { MultiSelectNested } from './MultiSelectNested.js';
+
+<Meta title="Design System/Components/Select" component={Select} />
+
+# Select
+
+Selects are fields that displays to users a list of options via a PopOver component. They allow users to make a single or multiple selections from this list. The selected option(s) of a Select need(s) to be stored whether it's single or a multi. Selects are part of forms.
+
+[View source](https://github.com/strapi/design-system/tree/main/packages/strapi-design-system/src/Select)
+
+**Best practices**
+
+- A select is part of a form.
+- Prefer the usage of Menu component if the user needs to make a single choice.
+- Try to have a sort logic in the popover of the menu.
+- In a multi select component, the "0 currently selected" text, can be changed but it will never have a placeholder style.
+- Use sentence case into a Select and straight-to-the-point sentences.
+- An option should be written on a single line.
+
+## Imports
+
+```js
+import { Select, Option } from '@strapi/design-system/Select';
+```
+
+or
+
+```js
+import { MultiSelectNested } from '@strapi/design-system/Select';
+```
+
+## Usage
+
+A Select allow users to make a selection from a list.
+
+### Default Select
+
+The default Select.
+
+<Canvas>
+  <Story name="base">
+    {() => {
+      const [value, setValue] = useState();
+      const [error, toggleError] = useState();
+      const [disabled, toggleDisabled] = useState();
+      return (
+        <Stack spacing={11}>
+          <Typography variant="beta">Current value is {value}</Typography>
+          <Select
+            id="select1"
+            label="Choose your meal"
+            labelAction={<Earth />}
+            required
+            placeholder="Your example"
+            hint="Description line"
+            onClear={() => setValue(undefined)}
+            clearLabel="Clear the meal"
+            error={error}
+            value={value}
+            onChange={setValue}
+            disabled={disabled}
+            startIcon={<Plus />}
+            selectButtonTitle="Carret Down Button"
+          >
+            <Option
+              value={'pizza'}
+              startIcon={<div style={{ height: '6px', borderRadius: '50%', width: '6px', background: 'red' }} />}
+            >
+              Pizza
+            </Option>
+            <Option value={'hamburger'}>Hamburger</Option>
+            <Option value={'bagel'}>Bagel</Option>
+          </Select>
+          <button onClick={() => toggleError((s) => (s ? undefined : 'An error occured'))}>
+            <Typography>Show the error state</Typography>
+          </button>
+          <button onClick={() => toggleDisabled((s) => !s)}>
+            <Typography>Show the disabled state</Typography>
+          </button>
+        </Stack>
+      );
+    }}
+  </Story>
+</Canvas>
+
+### Without label
+
+The default Select.
+
+<Canvas>
+  <Story name="withoutLabel">
+    {() => {
+      const [value, setValue] = useState();
+      const [error, toggleError] = useState();
+      const [disabled, toggleDisabled] = useState();
+      return (
+        <Stack spacing={11}>
+          <Typography variant="beta">Current value is {value}</Typography>
+          <Select
+            id="select1"
+            aria-label="Choose your meal"
+            placeholder="Your example"
+            hint="Description line"
+            onClear={() => setValue(undefined)}
+            clearLabel="Clear the meal"
+            error={error}
+            value={value}
+            onChange={setValue}
+            disabled={disabled}
+            startIcon={<Plus />}
+            selectButtonTitle="Carret Down Button"
+          >
+            <Option
+              value={'pizza'}
+              startIcon={<div style={{ height: '6px', borderRadius: '50%', width: '6px', background: 'red' }} />}
+            >
+              Pizza
+            </Option>
+            <Option value={'hamburger'}>Hamburger</Option>
+            <Option value={'bagel'}>Bagel</Option>
+          </Select>
+          <button onClick={() => toggleError((s) => (s ? undefined : 'An error occured'))}>
+            <Typography>Show the error state</Typography>
+          </button>
+          <button onClick={() => toggleDisabled((s) => !s)}>
+            <Typography>Show the disabled state</Typography>
+          </button>
+        </Stack>
+      );
+    }}
+  </Story>
+</Canvas>
+
+### Select multi
+
+A multi Select allow users to make multiple selections from a list.
+
+In a multi select component, the "0 currently selected" text, can be changed but it will never have a placeholder style.
+
+<Canvas>
+  <Story name="multi">
+    {() => {
+      const [values, setValues] = useState([]);
+      const [error, toggleError] = useState();
+      const [disabled, toggleDisabled] = useState();
+      return (
+        <Stack spacing={11}>
+          <Typography as="h2" variant="beta">
+            Current value is {values.join(', ')}
+          </Typography>
+          <Select
+            id="select1"
+            label="Choose your meal"
+            placeholder="Your example"
+            onClear={() => setValues([])}
+            hint="Description line"
+            clearLabel="Clear the meal"
+            selectButtonTitle="Carret Down Button"
+            error={error}
+            value={values}
+            onChange={setValues}
+            disabled={disabled}
+            customizeContent={(values) => `${values.length} currently selected`}
+            multi
+          >
+            <Option value={'pizza'}>Pizza</Option>
+            <Option value={'hamburger'}>Hamburger</Option>
+            <Option value={'bagel'}>Bagel</Option>
+          </Select>
+          <button onClick={() => toggleError((s) => (s ? undefined : 'An error occured'))}>
+            <Typography>Show the error state</Typography>
+          </button>
+          <button onClick={() => toggleDisabled((s) => !s)}>
+            <Typography>Show the disabled state</Typography>
+          </button>
+        </Stack>
+      );
+    }}
+  </Story>
+</Canvas>
+
+### Select multi with tags
+
+A multi Select allow users to visually select multiple options from a list. Prefer using a Select with multi tags when the selected values need to be visible in the input.
+
+<Canvas>
+  <Story name="multi-withTags">
+    {() => {
+      const [values, setValues] = useState([]);
+      const [error, toggleError] = useState();
+      const [disabled, toggleDisabled] = useState();
+      return (
+        <Stack spacing={11}>
+          <Typography variant="beta">Current value is {values.join(', ')}</Typography>
+          <Select
+            id="select1"
+            label="Choose your meal"
+            placeholder="Your example"
+            onClear={() => setValues([])}
+            hint="Description line"
+            clearLabel="Clear the meal"
+            error={error}
+            value={values}
+            onChange={setValues}
+            disabled={disabled}
+            customizeContent={(values) => `${values.length} currently selected`}
+            selectButtonTitle="Carret Down Button"
+            multi
+            withTags
+          >
+            <Option value={'pizza'}>Pizza</Option>
+            <Option value={'hamburger'}>Hamburger</Option>
+            <Option value={'bagel'}>Bagel</Option>
+            {Array(20)
+              .fill(null)
+              .map((_, i) => (
+                <Option key={i} value={`${i}`}>
+                  Another option
+                </Option>
+              ))}
+          </Select>
+          <button onClick={() => toggleError((s) => (s ? undefined : 'An error occured'))}>
+            <Typography>Show the error state</Typography>
+          </button>
+          <button onClick={() => toggleDisabled((s) => !s)}>
+            <Typography>Show the disabled state</Typography>
+          </button>
+        </Stack>
+      );
+    }}
+  </Story>
+</Canvas>
+
+### Select size S
+
+Select should be scaled down if they aimed to be placed in a smaller portions of a page.
+
+<Canvas>
+  <Story name="size-S">
+    {() => {
+      const [values, setValues] = useState([]);
+      return (
+        <Stack spacing={11}>
+          <Select
+            id="select1"
+            label="Choose your meal"
+            placeholder="Your example"
+            onClear={() => setValues([])}
+            hint="Description line"
+            clearLabel="Clear the meal"
+            error={undefined}
+            size="S"
+            value={values}
+            onChange={setValues}
+            disabled={false}
+            customizeContent={(values) => `${values.length} currently selected`}
+            selectButtonTitle="Carret Down Button"
+          >
+            <Option value={'pizza'}>Pizza</Option>
+            <Option value={'hamburger'}>Hamburger</Option>
+            <Option value={'bagel'}>Bagel</Option>
+          </Select>
+        </Stack>
+      );
+    }}
+  </Story>
+</Canvas>
+
+### Select multi nested
+
+A multi nested Select allow users to make multiple selections from a list.
+
+In a multi select component, the "0 currently selected" text, can be changed but it will never have a placeholder style.
+
+<Canvas>
+  <Story name="multi-nested">
+    {() => {
+      const [error, toggleError] = useState();
+      const [disabled, toggleDisabled] = useState();
+      const options = [
+        {
+          label: 'Pizza',
+          children: [
+            {
+              label: 'Peperroni',
+              value: 'peperroni',
+            },
+            {
+              label: 'Marguerita',
+              value: 'marguerita',
+            },
+          ],
+        },
+        {
+          label: 'Hamburger',
+          value: 'hamburger',
+        },
+        {
+          label: 'Bagel',
+          value: 'bagel',
+        },
+        {
+          label: 'Pasta',
+          children: [
+            {
+              label: 'Tartuffo',
+              value: 'tartuffo',
+            },
+            {
+              label: 'Carbonara',
+              value: 'carbonara',
+            },
+          ],
+        },
+      ];
+      const [values, setValues] = useState([]);
+      return (
+        <Stack spacing={11}>
+          <Typography variant="beta">Current value is {values.join(', ')}</Typography>
+          <MultiSelectNested
+            id="select1"
+            label="Choose your meal"
+            placeholder="Your example"
+            onClear={() => setValues([])}
+            hint="Description line"
+            clearLabel="Clear the meal"
+            error={error}
+            disabled={disabled}
+            customizeContent={(values) => `${values.length} currently selected`}
+            onChange={setValues}
+            value={values}
+            options={options}
+          />
+          <button onClick={() => toggleError((s) => (s ? undefined : 'An error occured'))}>
+            <Typography>Show the error state</Typography>
+          </button>
+          <button onClick={() => toggleDisabled((s) => !s)}>
+            <Typography>Show the disabled state</Typography>
+          </button>
+        </Stack>
+      );
+    }}
+  </Story>
+</Canvas>
+
+## Props
+
+The Select component composes Field so you can pass all Field props, and React.InputHTMLAttributes.
+The Option component wraps all its children in the (Box)[https://design-system-git-main-strapijs.vercel.app/?path=/docs/design-system-technical-components-box--base] component, so you can pass all Box props to change its style.
+
+<ArgsTable of={Select} />