@instructure/ui-options 11.6.0 → 11.6.1-snapshot-129

package/src/Options/v2/Item/styles.ts

@@ -0,0 +1,205 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { matchComponentTypes } from '@instructure/ui-react-utils'
+
+import type { NewComponentTypes } from '@instructure/ui-themes'
+import type { OptionsItemProps, OptionsItemStyle } from './props'
+import { ReactNode } from 'react'
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} componentTheme The theme variable object.
+ * @param  {Object} props the props of the component, the style is applied to
+ * @param  {Object} state the state of the component, the style is applied to
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: NewComponentTypes['OptionsItem'],
+  props: OptionsItemProps
+): OptionsItemStyle => {
+  const {
+    variant,
+    children,
+    renderBeforeLabel: hasContentBeforeLabel,
+    renderAfterLabel: hasContentAfterLabel,
+    beforeLabelContentVAlign,
+    afterLabelContentVAlign
+  } = props
+  // TODO if children are () => ReactNode this wont match anything
+  const containsList = matchComponentTypes(children as ReactNode, ['Options'])
+
+  // used for label and description too
+  const variantVariants = {
+    highlighted: {
+      background: componentTheme.highlightedBackground,
+      color: componentTheme.highlightedLabelColor
+    },
+    selected: {
+      background: componentTheme.selectedBackground,
+      color: componentTheme.selectedLabelColor
+    },
+    disabled: { cursor: 'not-allowed', opacity: 0.68 },
+    'highlighted-disabled': {
+      background: componentTheme.highlightedBackground,
+      color: componentTheme.highlightedLabelColor,
+      cursor: 'not-allowed'
+    },
+    'selected-highlighted': {
+      background: componentTheme.selectedHighlightedBackground,
+      color: componentTheme.highlightedLabelColor
+    },
+    default: {
+      transition: 'background 200ms'
+    }
+  }
+
+  const getContentVAlign = (type: 'before' | 'after') => {
+    const vAlign =
+      type === 'before' ? beforeLabelContentVAlign : afterLabelContentVAlign
+
+    const vOffset =
+      type === 'before'
+        ? componentTheme.beforeLabelContentVOffset
+        : componentTheme.afterLabelContentVOffset
+
+    return {
+      start: {
+        alignItems: 'flex-start',
+        paddingBlockStart: vOffset
+      },
+      center: {
+        alignItems: 'center',
+        paddingBlockStart: vOffset,
+        paddingBlockEnd: vOffset
+      },
+      end: {
+        alignItems: 'flex-end',
+        paddingBlockEnd: vOffset
+      }
+    }[vAlign!]
+  }
+
+  const linkStyles = { textDecoration: 'none', color: 'currentColor' }
+
+  return {
+    item: {
+      label: 'optionItem',
+      background: componentTheme.background,
+      color: componentTheme.color,
+      cursor: 'pointer',
+      display: 'block',
+      fontSize: componentTheme.fontSize,
+      fontFamily: componentTheme.fontFamily,
+      fontWeight: props.isSelected
+        ? componentTheme.fontWeightSelected
+        : componentTheme.fontWeight,
+      lineHeight: componentTheme.lineHeight,
+      outline: 'none',
+      position: 'relative',
+      userSelect: 'none',
+      ...variantVariants[variant!],
+      ...(containsList && { cursor: 'default' }),
+
+      // for nested items
+      '[class*=-optionItem] &': {
+        // except if it has icon before
+        ...(!hasContentBeforeLabel && {
+          '[class$=-optionItem__container]': {
+            paddingInlineStart: componentTheme.nestedPadding
+          },
+          '[class$=-optionItem__content--before]': {
+            insetInlineStart: componentTheme.nestedPadding
+          }
+        })
+      }
+    },
+    container: {
+      label: 'optionItem__container',
+      display: 'block',
+      outline: 'none',
+      padding: `${componentTheme.paddingVertical} ${componentTheme.paddingHorizontal}`,
+      ...(containsList && { padding: '0' }),
+      ...(hasContentBeforeLabel && {
+        paddingInlineEnd: componentTheme.iconPadding,
+        paddingInlineStart: `calc(${componentTheme.iconPadding} * 2 + 1em)`
+      }),
+      ...(hasContentAfterLabel && {
+        paddingInlineEnd: `calc(${componentTheme.iconPadding} * 2 + 1em)`,
+        paddingInlineStart: componentTheme.iconPadding
+      }),
+      ...(hasContentBeforeLabel &&
+        hasContentAfterLabel && {
+          paddingInlineEnd: `calc(${componentTheme.iconPadding} * 2 + 1em)`,
+          paddingInlineStart: `calc(${componentTheme.iconPadding} * 2 + 1em)`
+        }),
+
+      // NOTE: needs separate groups for `:is()` and `:-webkit-any()` because of css selector group validation (see https://www.w3.org/TR/selectors-3/#grouping)
+      '&:is(a)': {
+        '&, &:link, &:visited, &:active, &:hover, &:focus': linkStyles
+      },
+      '&:-webkit-any(a)': {
+        '&, &:link, &:visited, &:active, &:hover, &:focus': linkStyles
+      }
+    },
+    content: {
+      label: 'optionItem__content',
+      display: 'flex',
+      height: '100%',
+      boxSizing: 'border-box',
+      pointerEvents: 'none',
+      position: 'absolute',
+      top: '0'
+    },
+    contentBefore: {
+      label: 'optionItem__content--before',
+      insetInlineEnd: 'auto',
+      insetInlineStart: componentTheme.iconPadding,
+      ...getContentVAlign('before')
+    },
+    contentAfter: {
+      label: 'optionItem__content--after',
+      insetInlineEnd: componentTheme.iconPadding,
+      insetInlineStart: 'auto',
+      ...getContentVAlign('after')
+    },
+    description: {
+      label: 'optionItem__description',
+      display: 'block',
+      paddingBlockStart: componentTheme.descriptionPaddingStart,
+      fontWeight: componentTheme.descriptionFontWeight,
+      fontSize: componentTheme.descriptionFontSize,
+      lineHeight: componentTheme.descriptionLineHeight,
+      color: componentTheme.descriptionColor,
+
+      ...variantVariants[variant!],
+      background: 'none' // needed to clear variant background
+    }
+  }
+}
+
+export default generateStyle

package/src/Options/v2/Item/theme.ts

@@ -0,0 +1,79 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import type { Theme, ThemeSpecificStyle } from '@instructure/ui-themes'
+import { OptionsItemTheme } from '@instructure/shared-types'
+
+/**
+ * Generates the theme object for the component from the theme and provided additional information
+ * @param  {Object} theme The actual theme object.
+ * @return {Object} The final theme object with the overrides and component variables
+ */
+const generateComponentTheme = (theme: Theme): OptionsItemTheme => {
+  const { colors, typography, spacing, key: themeName } = theme
+
+  const themeSpecificStyle: ThemeSpecificStyle<OptionsItemTheme> = {
+    canvas: {
+      color: theme['ic-brand-font-color-dark'],
+      highlightedBackground: theme['ic-brand-primary']
+    }
+  }
+
+  const componentVariables: OptionsItemTheme = {
+    fontSize: typography?.fontSizeMedium,
+    fontFamily: typography?.fontFamily,
+    fontWeight: typography?.fontWeightNormal,
+    lineHeight: typography?.lineHeightCondensed,
+    fontWeightSelected: typography?.fontWeightNormal,
+
+    color: colors?.contrasts?.grey125125,
+    background: colors?.contrasts?.white1010,
+    highlightedLabelColor: colors?.contrasts?.white1010,
+    highlightedBackground: colors?.contrasts?.blue4570,
+    selectedLabelColor: colors?.contrasts?.white1010,
+    selectedBackground: colors?.contrasts?.grey4570,
+    selectedHighlightedBackground: colors?.contrasts?.blue5782,
+
+    padding: `${spacing?.xSmall} ${spacing?.small}`,
+    iconPadding: spacing?.small,
+    nestedPadding: spacing?.small,
+
+    beforeLabelContentVOffset: '0.625rem',
+    afterLabelContentVOffset: '0.625rem',
+
+    descriptionFontSize: typography.fontSizeSmall,
+    descriptionFontWeight: typography.fontWeightNormal,
+    descriptionLineHeight: typography.lineHeight,
+    descriptionPaddingStart: '0.25em',
+    descriptionColor: colors?.contrasts?.grey5782
+  }
+
+  return {
+    ...componentVariables,
+    ...themeSpecificStyle[themeName]
+  }
+}
+
+export { generateComponentTheme as optionsItemThemeGenerator }
+export default generateComponentTheme

package/src/Options/v2/README.md

@@ -0,0 +1,409 @@
+---
+describes: Options
+---
+
+`Options` is a view-only component for creating option lists and menus, like those used in [Select](Select) and [Menu](Menu). It should only be used if an existing component doesn't offer the level of customization needed.
+
+The `variant` prop of `Option.Item` provides several visual treatments. Use the `highlighted` variant to indicate that an option is being hovered, focused, or otherwise interacted with and the `selected` variant to indicate the selected option.
+
+```js
+---
+type: example
+---
+<View display="block" width="300px">
+  <Options>
+    <Options.Item onClick={() => console.log('clicked!')}>
+      Default option
+    </Options.Item>
+    <Options.Item variant="highlighted">
+      Highlighted option
+    </Options.Item>
+    <Options.Item variant="selected">
+      Selected option
+    </Options.Item>
+    <Options.Item variant="disabled">
+      Disabled option
+    </Options.Item>
+    <Options.Item variant="highlighted-disabled">
+      Highlighted disabled option
+    </Options.Item>
+  </Options>
+</View>
+```
+
+`Options` components can be nested to create sub menus. Icons may be added to any `Options.Item` before or after its text content using `renderBeforeLabel` and `renderAfterLabel` respectively.
+
+> `Options` and `Options.Item` receive default roles of `list` and `listitem` respectively, but the most applicable roles should be used. These will commonly be `listbox`/`option` or `menu`/`menuitem`.
+
+```js
+---
+type: example
+---
+<View display="block" width="300px">
+  <Options role="menu" as="ul">
+    <Options.Item role="menuitem">
+      Option one
+    </Options.Item>
+    <Options.Item role="menuitem" variant="highlighted">
+      Option two
+    </Options.Item>
+    <Options.Item role="menuitem" renderAfterLabel={IconArrowOpenEndSolid}>
+      Flyout menu option
+    </Options.Item>
+    <Options.Separator as="li" />
+    <Options role="menu" as="ul" renderLabel={'Sub menu'}>
+      <Options.Item role="menuitem">
+        Sub option one
+      </Options.Item>
+      <Options.Item role="menuitem">
+        Sub option two
+      </Options.Item>
+    </Options>
+    <Options.Separator />
+    <Options role="menu" as="ul" renderLabel={'Radio group'}>
+      <Options.Item
+        role="menuitemradio"
+        aria-checked="true"
+        renderBeforeLabel={IconCheckSolid}
+      >
+        Radio option one
+      </Options.Item>
+      <Options.Item
+        role="menuitemradio"
+        aria-checked="false"
+        renderBeforeLabel={
+          <IconCheckLine style={{opacity: 0}} />
+        }
+      >
+        Radio option two
+      </Options.Item>
+    </Options>
+    <Options.Separator />
+    <Options.Item role="menuitem">
+      Option three
+    </Options.Item>
+  </Options>
+</View>
+```
+
+`Options` does not manage any state or react to any user interaction. The consuming component or app should listen for events on items and update the `variant` props accordingly via its own state.
+
+```js
+---
+type: example
+---
+const Example = ({ options }) => {
+  const [highlighted, setHighlighted] = useState(-1)
+  const [selected, setSelected] = useState(-1)
+
+  const handleKeyDown = (event) => {
+    let index = highlighted
+
+    if (event.keyCode === 40 && highlighted < options.length - 1) {
+      // down arrow
+      event.preventDefault()
+      index = highlighted + 1
+    } else if (event.keyCode === 38 && highlighted > 0) {
+      // up arrow
+      event.preventDefault()
+      index = highlighted - 1
+    } else if (event.keyCode === 13 && highlighted > -1) {
+      // enter
+      setSelected(index)
+    }
+
+    setHighlighted(index)
+  }
+
+  const handleFocus = (index) => {
+    setHighlighted(index)
+  }
+
+  const handleMouseOver = (index) => {
+    setHighlighted(index)
+  }
+
+  const handleClick = (index) => {
+    setSelected(index)
+  }
+
+  return (
+    <View display="block" width="300px" shadow="above">
+      <Options
+        onKeyDown={handleKeyDown}
+        onMouseOut={() => setHighlighted(-1)}
+        tabIndex="0"
+      >
+        {options.map((option, index) => {
+          let variant = 'default'
+          if (highlighted === index) {
+            variant = 'highlighted'
+          } else if (selected === index) {
+            variant = 'selected'
+          }
+
+          return (
+            <Options.Item
+              key={option}
+              variant={variant}
+              tabIndex="-1"
+              onMouseOver={(e) => handleMouseOver(index)}
+              onFocus={() => handleFocus(index)}
+              onClick={() => handleClick(index)}
+            >
+              {option}
+            </Options.Item>
+          )
+        })}
+      </Options>
+    </View>
+  )
+}
+
+render(
+  <Example
+    options={[
+      'Option one',
+      'Option two',
+      'Option three',
+      'Option four',
+      'Option five'
+    ]}
+  />
+)
+```
+
+You can recolor the text and the background of the items for their `default`, `highlighted` and `selected` variants.
+
+By default, the icons in the `Option.Item` have the same color as the text. If you want to set the color of the icon separately, pass a function to the `renderBeforeLabel` or `renderAfterLabel` prop. This function will have a `props` parameter, so you can access the properties of that `Option.Item` (e.g. the current `variant`). The available props are: `[ variant, as, role, children ]`.
+
+```js
+---
+type: example
+---
+const Example = ({ options }) => {
+  const [highlighted, setHighlighted] = useState(-1)
+  const [selected, setSelected] = useState(-1)
+
+  const handleKeyDown = (event) => {
+    let index = highlighted
+
+    if (event.keyCode === 40 && highlighted < options.length - 1) {
+      // down arrow
+      event.preventDefault()
+      index = highlighted + 1
+    } else if (event.keyCode === 38 && highlighted > 0) {
+      // up arrow
+      event.preventDefault()
+      index = highlighted - 1
+    } else if (event.keyCode === 13 && highlighted > -1) {
+      // enter
+      setSelected(index)
+    }
+
+    setHighlighted(index)
+  }
+
+  const handleFocus = (event, index) => {
+    setHighlighted(index)
+  }
+
+  const handleMouseOver = (event, index) => {
+    setHighlighted(index)
+  }
+
+  const handleClick = (event, index) => {
+    setSelected(index)
+  }
+
+  return (
+    <View display="block" width="300px" shadow="above">
+      <Options
+        onKeyDown={handleKeyDown}
+        onMouseOut={() => setHighlighted(-1)}
+        tabIndex="0"
+      >
+        {options.map((option, index) => {
+          let variant = 'default'
+          if (highlighted === index) {
+            variant = 'highlighted'
+          } else if (selected === index) {
+            variant = 'selected'
+          }
+
+          return (
+            <Options.Item
+              key={option.label}
+              variant={variant}
+              tabIndex="-1"
+              onMouseOver={(e) => handleMouseOver(e, index)}
+              onFocus={(e) => handleFocus(e, index)}
+              onClick={(e) => handleClick(e, index)}
+              {...option.extraProps}
+            >
+              {option.label}
+            </Options.Item>
+          )
+        })}
+      </Options>
+    </View>
+  )
+}
+
+render(
+  <Example
+    options={[
+      {
+        label: 'Default item',
+        extraProps: {
+          renderBeforeLabel: IconCheckSolid
+        }
+      },
+      {
+        label: 'Text is green',
+        extraProps: {
+          renderBeforeLabel: IconCheckSolid,
+          themeOverride: { color: '#0B874B' }
+        }
+      },
+      {
+        label: 'Highlighted text is black',
+        extraProps: {
+          renderBeforeLabel: IconCheckSolid,
+          themeOverride: { highlightedLabelColor: '#2D3B45' }
+        }
+      },
+      {
+        label: 'Highlighted background is purple',
+        extraProps: {
+          renderBeforeLabel: IconCheckSolid,
+          themeOverride: { highlightedBackground: '#BF32A4' }
+        }
+      },
+      {
+        label: 'Only the icon is red',
+        extraProps: {
+          renderBeforeLabel: (props) => {
+            return (
+              <IconCheckSolid
+                {...(props.variant === 'default' && { color: 'warning' })}
+              />
+            )
+          }
+        }
+      }
+    ]}
+  />
+)
+```
+
+Additional/secondary text can be added via the `description` prop, and the ARIA role of it can be set with the `descriptionRole` prop.
+
+For longer, multi-line options the problem of the vertical alignment comes up. The content of the `renderBeforeLabel` and `renderAfterLabel` props are vertically centered by default. This can be changed with the `beforeLabelContentVAlign` and `afterLabelContentVAlign` props.
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [highlighted, setHighlighted] = useState(-1)
+
+  const handleMouseOver = (index) => {
+    setHighlighted(index)
+  }
+
+  return (
+    <View display="block" width="300px">
+      <Options onMouseOut={() => setHighlighted(-1)}>
+        <Options.Item
+          onMouseOver={() => handleMouseOver(1)}
+          variant={highlighted === 1 ? 'highlighted' : 'default'}
+          description="Curabitur fringilla, urna ut efficitur molestie, nibh lacus tincidunt elit, ut tempor ipsum nunc sit amet massa."
+          renderBeforeLabel={IconCheckSolid}
+          renderAfterLabel={IconArrowOpenEndSolid}
+          beforeLabelContentVAlign="start"
+          afterLabelContentVAlign="start"
+        >
+          Option one
+        </Options.Item>
+        <Options.Item
+          onMouseOver={() => handleMouseOver(2)}
+          variant={highlighted === 2 ? 'highlighted' : 'default'}
+          description="Curabitur fringilla, urna ut efficitur molestie, nibh lacus tincidunt elit, ut tempor ipsum nunc sit amet massa."
+          renderBeforeLabel={IconCheckSolid}
+          renderAfterLabel={IconArrowOpenEndSolid}
+          beforeLabelContentVAlign="center"
+          afterLabelContentVAlign="center"
+        >
+          Option two
+        </Options.Item>
+        <Options.Item
+          onMouseOver={() => handleMouseOver(3)}
+          variant={highlighted === 3 ? 'highlighted' : 'default'}
+          description="Curabitur fringilla, urna ut efficitur molestie, nibh lacus tincidunt elit, ut tempor ipsum nunc sit amet massa."
+          renderBeforeLabel={IconCheckSolid}
+          renderAfterLabel={IconArrowOpenEndSolid}
+          beforeLabelContentVAlign="end"
+          afterLabelContentVAlign="end"
+        >
+          Option three
+        </Options.Item>
+      </Options>
+    </View>
+  )
+}
+
+render(<Example />)
+```
+
+Providing a `href` prop will render the option as `<a>` link element.
+
+**WARNING!** Since `Options` is a view-only component, you have to make sure it is accessible, and if set the variant to disabled, disable the links as well!
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [highlighted, setHighlighted] = useState(-1)
+
+  const handleMouseOver = (index) => {
+    setHighlighted(index)
+  }
+
+  return (
+    <View display="block" width="300px">
+      <Options onMouseOut={() => setHighlighted(-1)}>
+        <Options.Item
+          onMouseOver={() => handleMouseOver(1)}
+          variant={highlighted === 1 ? 'highlighted' : 'default'}
+          href="/"
+        >
+          Link one
+        </Options.Item>
+        <Options.Item
+          onMouseOver={() => handleMouseOver(2)}
+          variant={highlighted === 2 ? 'highlighted' : 'default'}
+          href="/"
+        >
+          Link two
+        </Options.Item>
+        <Options.Item
+          onMouseOver={() => handleMouseOver(3)}
+          variant={highlighted === 3 ? 'highlighted' : 'default'}
+          variant="disabled"
+          aria-disabled="true"
+          onClick={(e) => {
+            e.preventDefault()
+          }}
+          href="/"
+        >
+          Link three
+        </Options.Item>
+      </Options>
+    </View>
+  )
+}
+
+render(<Example />)
+```