@zendeskgarden/react-dropdowns 9.0.0-next.0 → 9.0.0-next.10

package/README.md

@@ -1,6 +1,9 @@
-# @zendeskgarden/react-dropdowns [![npm version](https://flat.badgen.net/npm/v/@zendeskgarden/react-dropdowns)](https://www.npmjs.com/package/@zendeskgarden/react-dropdowns)
+# @zendeskgarden/react-dropdowns [![npm version][npm version badge]][npm version link]
 
-This package includes components relating to dropdowns in the
+[npm version badge]: https://flat.badgen.net/npm/v/@zendeskgarden/react-dropdowns
+[npm version link]: https://www.npmjs.com/package/@zendeskgarden/react-dropdowns
+
+This package includes components related to dropdowns in the
 [Garden Design System](https://zendeskgarden.github.io/).
 
 ## Installation
@@ -12,85 +15,86 @@ npm install @zendeskgarden/react-dropdowns
 npm install react react-dom styled-components @zendeskgarden/react-theming
 ```
 
-## Basic Example
+## Usage
+
+### Combobox
 
 ```jsx
 import { ThemeProvider } from '@zendeskgarden/react-theming';
-import { Dropdown, Menu, Item, Trigger } from '@zendeskgarden/react-dropdowns';
+import { Field, Label, Combobox, Option } from '@zendeskgarden/react-dropdowns';
 
 /**
  * Place a `ThemeProvider` at the root of your React application
  */
 <ThemeProvider>
-  <Dropdown onSelect={value => console.log(`Selected: ${value}`)}>
-    <Trigger>
-      <button>This triggers a menu</button>
-    </Trigger>
-    <Menu placement="end" hasArrow>
-      <Item value="option-1">Option 1</Item>
-      <Item value="option-2">Option 2</Item>
-      <Item value="option-3">Option 3</Item>
-    </Menu>
-  </Dropdown>
+  <Field>
+    <Field.Label>Label</Field.Label>
+    <Combobox>
+      <Option value="One" />
+      <Option value="Two" />
+      <Option value="Three" />
+    </Combobox>
+  </Field>
 </ThemeProvider>;
 ```
 
-For all components within the `react-dropdowns` package, the menu layouts and
-implementations are interchangeable.
-
-Whether you're making a `Select`, `Autocomplete`, or a traditional `Menu` the `<Menu>` implementation
-will adapted to its consumer.
-
-## Usage
-
-### Overview
-
-The `react-dropdowns` package abstracts the common concepts of `Menus`, `Selects`, and `Autocompletes`
-into a common API. This includes consistent visuals, common keyboard interaction, and a fully accessible
-experience for sighted and non-sighted users.
-
-The customizations available within this can be broken into two groups: _placement / positioning_
-and _dropdown state_
-
-### Placement / Positioning
-
-Internally, the `<Dropdown>` component uses [PopperJS](https://popper.js.org/popper-documentation.html)
-for its positioning calculations.
-
-The `<Menu>` component accepts all customizations regarding placement, boundaries, overflows,
-etc. via the `popperModifiers` prop.
+Beyond this basic example, Garden's `Combobox` offers a comprehensive set of
+WAI-ARIA compliant combobox features. Key capabilities include:
+
+- **Controllable**: The `Combobox` functions in both [uncontrolled and
+  controlled](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components)
+  modes. Controlled mode enables aspects, such as input value, selection value(s),
+  listbox expansion, and current option active index, to share and adapt to the
+  surrounding UI.
+- **Autocomplete-able**: Denotes the `Combobox` with [list
+  autocomplete](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/).
+  Filtering implementation is left to the API consumer.
+- **Selectable**: The `Combobox` API ensures the selection of one or more
+  listbox option values, while also supporting the W3C [no autocomplete
+  example](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-none/)
+  for use cases like search.
+- **Multi-selectable**: This feature enables the `Combobox` to provide WAI-ARIA
+  [multi-select
+  listbox](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-rearrangeable/#ex2_label)
+  functionality with option-as-tag value rendering.
+- **Non-editable**: The `Combobox` supports [select-only
+  mode](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/),
+  where the user cannot modify the `<input>`.
+- **Filterable**: The `Combobox` offers various filtering methods for listbox
+  options. Details of the filtering implementation are left to the API consumer.
+- **Markup-able**: The `Combobox` can convert input value text to rich HTML
+  markup on blur in single-selection mode.
+- **Decorate-able**: The `Combobox` allows adding start and end media (SVG icons).
+  Certain features will replace end media with Garden's standard dropdown chevron
+  treatment.
+- **Group-able**: The `Combobox` API utilizes fully accessible `<OptGroup>`
+  components for grouping, similar to the corresponding HTML element.
+- **Compactible**: Like other form elements, the `Combobox` supports compact
+  sizing.
+- **Field-able**: The `Combobox` builds on Garden’s Field API context to
+  establish accessible relationships with corresponding Label, Hint, and Message
+  components.
+- **Validate-able**: The `Combobox` provides validation styling and
+  accessibility comparable to other Garden form components.
+- **RTL theme-able**: Functionality displays and operates correctly for
+  left-to-right and right-to-left layouts.
+
+### Menu
 
 ```jsx
-/** Customize default overflow settings to position against the `viewport` */
-<Menu popperModifiers={{ preventOverflow: { boundariesElement: 'viewport' } }}>
-  <Item value="item-1">Item 1</Item>
-  <Item value="item-2">Item 2</Item>
-  <Item value="item-3">Item 3</Item>
-</Menu>
-```
-
-### Dropdown State
-
-We use the [Downshift](https://github.com/downshift-js/downshift) render-prop library to
-handle our keyboard and accessibility logic.
-
-The following states can be controlled directly from the `<Dropdown>` component:
-
-- **isOpen** Whether the dropdown is currently open
-- **highlightedIndex** Which index is currently highlighted
-- **inputValue** The value of the input when it's used as an `Autocomplete`
-- **selectedItem** The currently selected item
-- **selectedItems** The currently selected items
-
-All other customizations may be provided directly to the Downshift provider
-via the `downshiftProps` prop.
-
-Downshift provides several advanced customization features that can be very helpful when
-customizing this component. The [stateReducer](https://github.com/downshift-js/downshift#statereducer)
-pattern is a common customization strategy.
+import { ThemeProvider } from '@zendeskgarden/react-theming';
+import { Menu, Item } from '@zendeskgarden/react-dropdowns';
 
-### Server Side Rendering
+/**
+ * Place a `ThemeProvider` at the root of your React application
+ */
+<ThemeProvider>
+  <Menu button="Choose an item">
+    <Item value="item-01" label="One" />
+    <Item value="item-02" label="Two" />
+    <Item value="item-03" label="Three" />
+  </Menu>
+</ThemeProvider>;
+```
 
-If you are using server side rendering you may need to [configure specific Downshift settings](https://github.com/downshift-js/downshift#resetidcounter).
-This package re-exports the Downshift `resetIdCounter` utility. It allows resetting the internal id
-counter which is used to generate unique ids for Downshift.
+Visit [storybook](https://zendeskgarden.github.io/react-components) for live examples.

package/dist/esm/context/useComboboxContext.js

@@ -0,0 +1,18 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+import { createContext, useContext } from 'react';
+
+const ComboboxContext = createContext(undefined);
+const useComboboxContext = () => {
+  const context = useContext(ComboboxContext);
+  if (!context) {
+    throw new Error('Error: this component must be rendered within a <Combobox>.');
+  }
+  return context;
+};
+
+export { ComboboxContext, useComboboxContext as default };

package/dist/esm/context/useFieldContext.js

@@ -0,0 +1,18 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+import { createContext, useContext } from 'react';
+
+const FieldContext = createContext(undefined);
+const useFieldContext = () => {
+  const context = useContext(FieldContext);
+  if (!context) {
+    throw new Error('Error: this component must be rendered within a <Field>.');
+  }
+  return context;
+};
+
+export { FieldContext, useFieldContext as default };

package/dist/esm/context/useItemContext.js

@@ -0,0 +1,18 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+import { createContext, useContext } from 'react';
+
+const ItemContext = createContext(undefined);
+const useItemContext = () => {
+  const context = useContext(ItemContext);
+  if (!context) {
+    throw new Error('Error: this component must be rendered within an <Item>.');
+  }
+  return context;
+};
+
+export { ItemContext, useItemContext as default };

package/dist/esm/context/useItemGroupContext.js

@@ -0,0 +1,14 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+import { createContext, useContext } from 'react';
+
+const ItemGroupContext = createContext({});
+const useItemGroupContext = () => {
+  return useContext(ItemGroupContext);
+};
+
+export { ItemGroupContext, useItemGroupContext as default };

package/dist/esm/context/useMenuContext.js

@@ -0,0 +1,18 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+import { createContext, useContext } from 'react';
+
+const MenuContext = createContext(undefined);
+const useMenuContext = () => {
+  const context = useContext(MenuContext);
+  if (!context) {
+    throw new Error('Error: this component must be rendered within a <Menu>.');
+  }
+  return context;
+};
+
+export { MenuContext, useMenuContext as default };

package/dist/esm/context/useOptionContext.js

@@ -0,0 +1,18 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+import { createContext, useContext } from 'react';
+
+const OptionContext = createContext(undefined);
+const useOptionContext = () => {
+  const context = useContext(OptionContext);
+  if (!context) {
+    throw new Error('Error: this component must be rendered within an <Option>.');
+  }
+  return context;
+};
+
+export { OptionContext, useOptionContext as default };

package/dist/esm/elements/combobox/Combobox.js

@@ -0,0 +1,330 @@
+/**
+* Copyright Zendesk, Inc.
+*
+* Use of this source code is governed under the Apache License, Version 2.0
+* found at http://www.apache.org/licenses/LICENSE-2.0.
+*/
+import React__default, { forwardRef, useState, useMemo, useRef, useContext, useEffect } from 'react';
+import PropTypes from 'prop-types';
+import { ThemeContext } from 'styled-components';
+import { useCombobox } from '@zendeskgarden/container-combobox';
+import { DEFAULT_THEME, useWindow, useText } from '@zendeskgarden/react-theming';
+import { VALIDATION } from '@zendeskgarden/react-forms';
+import SvgChevronDownStroke from '../../node_modules/@zendeskgarden/svg-icons/src/16/chevron-down-stroke.svg.js';
+import { ComboboxContext } from '../../context/useComboboxContext.js';
+import useFieldContext from '../../context/useFieldContext.js';
+import { StyledCombobox } from '../../views/combobox/StyledCombobox.js';
+import { StyledContainer } from '../../views/combobox/StyledContainer.js';
+import '../../views/combobox/StyledField.js';
+import '../../views/combobox/StyledFloatingListbox.js';
+import '../../views/combobox/StyledHint.js';
+import { StyledInput } from '../../views/combobox/StyledInput.js';
+import { StyledInputGroup } from '../../views/combobox/StyledInputGroup.js';
+import { StyledInputIcon } from '../../views/combobox/StyledInputIcon.js';
+import '../../views/combobox/StyledLabel.js';
+import '../../views/combobox/StyledListbox.js';
+import '../../views/combobox/StyledListboxSeparator.js';
+import '../../views/combobox/StyledMessage.js';
+import '../../views/combobox/StyledOptGroup.js';
+import '../../views/combobox/StyledOption.js';
+import '../../views/combobox/StyledOptionContent.js';
+import '../../views/combobox/StyledOptionIcon.js';
+import '../../views/combobox/StyledOptionMeta.js';
+import '../../views/combobox/StyledOptionTypeIcon.js';
+import '../../views/combobox/StyledTag.js';
+import { StyledTagsButton } from '../../views/combobox/StyledTagsButton.js';
+import { StyledTrigger } from '../../views/combobox/StyledTrigger.js';
+import { StyledValue } from '../../views/combobox/StyledValue.js';
+import '../../views/menu/StyledMenu.js';
+import '../../views/menu/StyledFloatingMenu.js';
+import '../../views/menu/StyledItem.js';
+import '../../views/menu/StyledItemContent.js';
+import '../../views/menu/StyledItemGroup.js';
+import '../../views/menu/StyledItemIcon.js';
+import '../../views/menu/StyledItemMeta.js';
+import '../../views/menu/StyledItemTypeIcon.js';
+import '../../views/menu/StyledButton.js';
+import '../../views/menu/StyledSeparator.js';
+import { Listbox } from './Listbox.js';
+import { TagGroup } from './TagGroup.js';
+import { toOptions } from './utils.js';
+
+const MAX_TAGS = 4;
+const Combobox = forwardRef((_ref, ref) => {
+  let {
+    children,
+    activeIndex,
+    defaultActiveIndex,
+    defaultExpanded,
+    endIcon,
+    focusInset,
+    inputProps: _inputProps,
+    inputValue: _inputValue,
+    isAutocomplete,
+    isBare,
+    isCompact,
+    isDisabled,
+    isEditable,
+    isExpanded: _isExpanded,
+    isMultiselectable,
+    listboxAppendToNode,
+    listboxAriaLabel,
+    listboxMaxHeight,
+    listboxMinHeight,
+    listboxZIndex,
+    maxHeight,
+    maxTags = MAX_TAGS,
+    onChange,
+    placeholder,
+    renderExpandTags,
+    renderValue,
+    selectionValue,
+    startIcon,
+    validation,
+    ...props
+  } = _ref;
+  const {
+    hasHint,
+    hasMessage,
+    labelProps,
+    setLabelProps,
+    hintProps,
+    setHintProps,
+    messageProps,
+    setMessageProps
+  } = useFieldContext();
+  const [isInputHidden, setIsInputHidden] = useState(true);
+  const [isLabelHovered, setIsLabelHovered] = useState(false);
+  const [isTagGroupExpanded, setIsTagGroupExpanded] = useState(false);
+  const [optionTagProps, setOptionTagProps] = useState({});
+  const options = useMemo(() => {
+    const tagProps = {};
+    const retVal = toOptions(children, tagProps);
+    if (isMultiselectable) {
+      setOptionTagProps(value => ({
+        ...value,
+        ...tagProps
+      }));
+    }
+    return retVal;
+  }, [children, isMultiselectable]);
+  const triggerRef = useRef(null);
+  const inputRef = useRef(null);
+  const listboxRef = useRef(null);
+  const theme = useContext(ThemeContext) || DEFAULT_THEME;
+  const environment = useWindow(theme);
+  const {
+    activeValue,
+    inputValue,
+    isExpanded,
+    getTriggerProps,
+    getHintProps,
+    getInputProps,
+    getLabelProps,
+    getListboxProps,
+    getMessageProps,
+    getOptionProps,
+    getOptGroupProps,
+    getTagProps,
+    removeSelection,
+    selection
+  } = useCombobox({
+    idPrefix: props.id,
+    triggerRef,
+    inputRef,
+    listboxRef,
+    options,
+    environment,
+    hasHint,
+    hasMessage,
+    isAutocomplete,
+    isEditable,
+    isMultiselectable,
+    disabled: isDisabled,
+    inputValue: _inputValue,
+    selectionValue,
+    isExpanded: _isExpanded,
+    defaultExpanded,
+    activeIndex,
+    defaultActiveIndex,
+    onChange
+  });
+  const contextValue = useMemo(() => ({
+    activeValue,
+    getOptionProps,
+    getOptGroupProps,
+    getTagProps,
+    isCompact,
+    removeSelection
+  }), [activeValue, getOptionProps, getOptGroupProps, getTagProps, isCompact, removeSelection]);
+  const hasChevron = useMemo(() => !isBare && (isAutocomplete || !isEditable), [isAutocomplete, isBare, isEditable]);
+  const expandTags = useText(Combobox, {
+    renderExpandTags
+  }, 'renderExpandTags', '+ {{value}} more', isMultiselectable || false);
+  const _listboxAriaLabel = useText(Combobox, {
+    listboxAriaLabel
+  }, 'listboxAriaLabel', 'Options');
+  const triggerProps = {
+    isAutocomplete,
+    isBare,
+    isCompact,
+    isEditable,
+    isLabelHovered,
+    isMultiselectable,
+    maxHeight,
+    focusInset,
+    validation,
+    ...getTriggerProps({
+      onFocus: () => {
+        if (!isDisabled) {
+          if (isEditable) {
+            setIsInputHidden(false);
+          }
+          if (isMultiselectable) {
+            setIsTagGroupExpanded(true);
+          }
+        }
+      },
+      onBlur: event => {
+        if (event.relatedTarget === null || !triggerRef.current?.contains(event.relatedTarget)) {
+          if (isEditable) {
+            setIsInputHidden(true);
+          }
+          if (isMultiselectable) {
+            setIsTagGroupExpanded(false);
+          }
+        }
+      }
+    })
+  };
+  const inputProps = {
+    'aria-invalid': validation === 'error' || validation === 'warning',
+    hidden: isInputHidden,
+    isBare,
+    isCompact,
+    isEditable,
+    isMultiselectable,
+    placeholder,
+    ...getInputProps({
+      ..._inputProps
+    })
+  };
+  const listboxProps = getListboxProps({
+    'aria-label': _listboxAriaLabel
+  });
+  useEffect(() => {
+    if (!labelProps) {
+      const _labelProps = getLabelProps({
+        onMouseEnter: () => setIsLabelHovered(true),
+        onMouseLeave: () => setIsLabelHovered(false)
+      });
+      setLabelProps(_labelProps);
+    }
+    return () => labelProps && setLabelProps(undefined);
+  }, [getLabelProps, labelProps, setLabelProps]);
+  useEffect(() => {
+    if (!hintProps) {
+      const _hintProps = getHintProps();
+      setHintProps(_hintProps);
+    }
+    return () => hintProps && setHintProps(undefined);
+  }, [getHintProps, hintProps, setHintProps]);
+  useEffect(() => {
+    if (!messageProps) {
+      const _messageProps = getMessageProps();
+      setMessageProps(_messageProps);
+    }
+    return () => messageProps && setMessageProps(undefined);
+  }, [getMessageProps, messageProps, setMessageProps]);
+  return React__default.createElement(ComboboxContext.Provider, {
+    value: contextValue
+  }, React__default.createElement(StyledCombobox, Object.assign({
+    isCompact: isCompact,
+    tabIndex: -1
+  }, props, {
+    ref: ref
+  }), React__default.createElement(StyledTrigger, triggerProps, React__default.createElement(StyledContainer, null, startIcon && React__default.createElement(StyledInputIcon, {
+    $isLabelHovered: isLabelHovered,
+    $isCompact: isCompact
+  }, startIcon), React__default.createElement(StyledInputGroup, null, isMultiselectable && Array.isArray(selection) && React__default.createElement(TagGroup, {
+    isDisabled: isDisabled,
+    isExpanded: isTagGroupExpanded,
+    maxTags: maxTags,
+    optionTagProps: optionTagProps,
+    selection: selection
+  }, selection.length > maxTags && React__default.createElement(StyledTagsButton, {
+    disabled: isDisabled,
+    hidden: isTagGroupExpanded,
+    isCompact: isCompact,
+    tabIndex: -1,
+    type: "button"
+  }, (() => {
+    const value = selection.length - maxTags;
+    return renderExpandTags ? renderExpandTags(value) : expandTags?.replace('{{value}}', value.toString());
+  })())), React__default.createElement(StyledValue, {
+    hidden: !isInputHidden,
+    isAutocomplete: isAutocomplete,
+    isBare: isBare,
+    isCompact: isCompact,
+    isDisabled: isDisabled,
+    isEditable: isEditable,
+    isMultiselectable: isMultiselectable,
+    isPlaceholder: !(inputValue || renderValue)
+  }, renderValue ? renderValue({
+    selection,
+    inputValue
+  }) : inputValue || placeholder), React__default.createElement(StyledInput, inputProps)), (hasChevron || endIcon) && React__default.createElement(StyledInputIcon, {
+    $isCompact: isCompact,
+    $isEnd: true,
+    $isLabelHovered: isLabelHovered,
+    $isRotated: hasChevron && isExpanded
+  }, hasChevron ? React__default.createElement(SvgChevronDownStroke, null) : endIcon))), React__default.createElement(Listbox, Object.assign({
+    appendToNode: listboxAppendToNode,
+    isCompact: isCompact,
+    isExpanded: isExpanded,
+    maxHeight: listboxMaxHeight,
+    minHeight: listboxMinHeight,
+    triggerRef: triggerRef,
+    zIndex: listboxZIndex
+  }, listboxProps), children)));
+});
+Combobox.displayName = 'Combobox';
+Combobox.propTypes = {
+  activeIndex: PropTypes.number,
+  defaultActiveIndex: PropTypes.number,
+  defaultExpanded: PropTypes.bool,
+  endIcon: PropTypes.any,
+  focusInset: PropTypes.bool,
+  id: PropTypes.string,
+  inputProps: PropTypes.object,
+  inputValue: PropTypes.string,
+  isAutocomplete: PropTypes.bool,
+  isBare: PropTypes.bool,
+  isCompact: PropTypes.bool,
+  isDisabled: PropTypes.bool,
+  isEditable: PropTypes.bool,
+  isExpanded: PropTypes.bool,
+  isMultiselectable: PropTypes.bool,
+  listboxAppendToNode: PropTypes.any,
+  listboxAriaLabel: PropTypes.string,
+  listboxMaxHeight: PropTypes.string,
+  listboxMinHeight: PropTypes.string,
+  listboxZIndex: PropTypes.number,
+  maxHeight: PropTypes.string,
+  maxTags: PropTypes.number,
+  onChange: PropTypes.func,
+  placeholder: PropTypes.string,
+  renderExpandTags: PropTypes.func,
+  renderValue: PropTypes.func,
+  selectionValue: PropTypes.any,
+  startIcon: PropTypes.any,
+  validation: PropTypes.oneOf(VALIDATION)
+};
+Combobox.defaultProps = {
+  isEditable: true,
+  listboxMaxHeight: '400px',
+  listboxZIndex: 1000,
+  maxTags: MAX_TAGS
+};
+
+export { Combobox };