@instructure/ui-options 8.14.1-snapshot.7 → 8.15.1-snapshot.2

package/src/Options/Item/index.tsx

@@ -58,9 +58,9 @@ class Item extends Component<OptionsItemProps> {
     as: 'span',
     variant: 'default',
     role: 'listitem',
-    renderBeforeLabel: null,
-    renderAfterLabel: null,
-    children: null
+    descriptionRole: 'note',
+    beforeLabelContentVAlign: 'center',
+    afterLabelContentVAlign: 'center'
   } as const
 
   ref: Element | null = null
@@ -104,6 +104,8 @@ class Item extends Component<OptionsItemProps> {
       as,
       role,
       styles,
+      description,
+      descriptionRole,
       renderBeforeLabel,
       renderAfterLabel,
       children
@@ -112,6 +114,9 @@ class Item extends Component<OptionsItemProps> {
     const ElementType = getElementType(Item, this.props, () => as!)
     const passthroughProps = omitProps(this.props, Item.allowedProps)
 
+    const childrenContent = callRenderProp(children)
+    const descriptionContent = callRenderProp(description)
+
     return (
       <ElementType
         role="none"
@@ -122,7 +127,12 @@ class Item extends Component<OptionsItemProps> {
         }}
       >
         <span {...passthroughProps} css={styles?.container} role={role}>
-          {children}
+          {childrenContent}
+          {descriptionContent && (
+            <span css={styles?.description} role={descriptionRole}>
+              {descriptionContent}
+            </span>
+          )}
         </span>
         {renderBeforeLabel &&
           this.renderContent(renderBeforeLabel, styles?.contentBefore)}

package/src/Options/Item/props.ts

@@ -44,7 +44,7 @@ type ItemProps = {
    */
   variant?: 'default' | 'highlighted' | 'selected' | 'disabled'
   /**
-   * The aria role of the element
+   * The ARIA role of the element
    */
   role?: string
 }
@@ -60,7 +60,22 @@ type OptionsItemOwnProps = ItemProps & {
    * (if you pass a function, it has the `props` as its parameter)
    */
   renderAfterLabel?: React.ReactNode | ((props: ItemProps) => React.ReactNode)
-  children?: React.ReactNode | (() => React.ReactNode)
+  /**
+   * Sets the vAlign of renderBeforeLabel content
+   */
+  beforeLabelContentVAlign?: 'start' | 'center' | 'end'
+  /**
+   * Sets the vAlign of renderAfterLabel content
+   */
+  afterLabelContentVAlign?: 'start' | 'center' | 'end'
+  /**
+   * Additional "secondary" description text
+   */
+  description?: React.ReactNode | (() => React.ReactNode)
+  /**
+   * The ARIA role of the description element
+   */
+  descriptionRole?: string
 }
 
 type PropKeys = keyof OptionsItemOwnProps
@@ -72,7 +87,12 @@ type OptionsItemProps = OptionsItemOwnProps &
   OtherHTMLAttributes<OptionsItemOwnProps>
 
 type OptionsItemStyle = ComponentStyle<
-  'item' | 'container' | 'content' | 'contentBefore' | 'contentAfter'
+  | 'item'
+  | 'container'
+  | 'content'
+  | 'contentBefore'
+  | 'contentAfter'
+  | 'description'
 >
 
 const propTypes: PropValidators<PropKeys> = {
@@ -81,6 +101,10 @@ const propTypes: PropValidators<PropKeys> = {
   role: PropTypes.string,
   renderBeforeLabel: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
   renderAfterLabel: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  beforeLabelContentVAlign: PropTypes.oneOf(['start', 'center', 'end']),
+  afterLabelContentVAlign: PropTypes.oneOf(['start', 'center', 'end']),
+  description: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+  descriptionRole: PropTypes.string,
   children: PropTypes.oneOfType([PropTypes.node, PropTypes.func])
 }
 
@@ -90,6 +114,10 @@ const allowedProps: AllowedPropKeys = [
   'role',
   'renderBeforeLabel',
   'renderAfterLabel',
+  'beforeLabelContentVAlign',
+  'afterLabelContentVAlign',
+  'description',
+  'descriptionRole',
   'children'
 ]
 

package/src/Options/Item/styles.ts

@@ -45,11 +45,14 @@ const generateStyle = (
     variant,
     children,
     renderBeforeLabel: hasContentBeforeLabel,
-    renderAfterLabel: hasContentAfterLabel
+    renderAfterLabel: hasContentAfterLabel,
+    beforeLabelContentVAlign,
+    afterLabelContentVAlign
   } = props
 
   const containsList = matchComponentTypes(children, ['Options'])
 
+  // used for label and description too
   const variantVariants = {
     highlighted: {
       background: componentTheme.highlightedBackground,
@@ -63,6 +66,34 @@ const generateStyle = (
     default: {}
   }
 
+  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 transition = 'background 200ms'
+
   return {
     item: {
       label: 'optionItem',
@@ -76,7 +107,7 @@ const generateStyle = (
       lineHeight: componentTheme.lineHeight,
       outline: 'none',
       position: 'relative',
-      transition: 'background 200ms',
+      transition,
       userSelect: 'none',
       ...variantVariants[variant!],
       ...(containsList && { cursor: 'default' }),
@@ -115,9 +146,9 @@ const generateStyle = (
     },
     content: {
       label: 'optionItem__content',
-      alignItems: 'center',
       display: 'flex',
       height: '100%',
+      boxSizing: 'border-box',
       pointerEvents: 'none',
       position: 'absolute',
       top: '0'
@@ -125,12 +156,27 @@ const generateStyle = (
     contentBefore: {
       label: 'optionItem__content--before',
       insetInlineEnd: 'auto',
-      insetInlineStart: componentTheme.iconPadding
+      insetInlineStart: componentTheme.iconPadding,
+      ...getContentVAlign('before')
     },
     contentAfter: {
       label: 'optionItem__content--after',
       insetInlineEnd: componentTheme.iconPadding,
-      insetInlineStart: 'auto'
+      insetInlineStart: 'auto',
+      ...getContentVAlign('after')
+    },
+    description: {
+      label: 'optionItem__description',
+      display: 'block',
+      transition,
+      paddingBlockStart: componentTheme.descriptionPaddingStart,
+      fontWeight: componentTheme.descriptionFontWeight,
+      fontSize: componentTheme.descriptionFontSize,
+      lineHeight: componentTheme.descriptionLineHeight,
+      color: componentTheme.descriptionColor,
+
+      ...variantVariants[variant!],
+      background: 'none' // needed to clear variant background
     }
   }
 }

package/src/Options/Item/theme.ts

@@ -55,7 +55,16 @@ const generateComponentTheme = (theme: Theme): OptionsItemTheme => {
 
     padding: `${spacing?.xSmall} ${spacing?.small}`,
     iconPadding: spacing?.small,
-    nestedPadding: spacing?.medium
+    nestedPadding: spacing?.medium,
+
+    beforeLabelContentVOffset: '0.625rem',
+    afterLabelContentVOffset: '0.625rem',
+
+    descriptionFontSize: typography.fontSizeSmall,
+    descriptionFontWeight: typography.fontWeightNormal,
+    descriptionLineHeight: typography.lineHeight,
+    descriptionPaddingStart: '0.25em',
+    descriptionColor: colors.textDark
   }
 
   return {

package/src/Options/README.md

@@ -130,7 +130,11 @@ class Example extends React.Component {
         width="300px"
         shadow="above"
       >
-        <Options onKeyDown={this.handleKeyDown} tabIndex="0">
+        <Options
+          onKeyDown={this.handleKeyDown}
+          onMouseOut={(e) => this.setState({ highlighted: -1 })}
+          tabIndex="0"
+        >
           {this.props.options.map((option, index) => {
             let variant = 'default'
             if (this.state.highlighted === index) {
@@ -225,7 +229,11 @@ class Example extends React.Component {
         width="300px"
         shadow="above"
       >
-        <Options onKeyDown={this.handleKeyDown} tabIndex="0">
+        <Options
+          onKeyDown={this.handleKeyDown}
+          onMouseOut={(e) => this.setState({ highlighted: -1 })}
+          tabIndex="0"
+        >
           {this.props.options.map((option, index) => {
             let variant = 'default'
             if (this.state.highlighted === index) {
@@ -296,3 +304,71 @@ render(
   ]} />
 )
 ```
+
+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
+---
+render: false
+example: true
+---
+class Example extends React.Component {
+  constructor(props) {
+    super(props)
+
+    this.state = {
+      highlighted: -1
+    }
+  }
+
+  handleMouseOver = (index) => {
+    this.setState({ highlighted: index })
+  }
+
+  render() {
+    return (
+      <View display="block" width="300px">
+        <Options onMouseOut={(e) => this.setState({ highlighted: -1 })}>
+          <Options.Item
+            onMouseOver={(e) => this.handleMouseOver(1)}
+            variant={this.state.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={(e) => this.handleMouseOver(2)}
+            variant={this.state.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={(e) => this.handleMouseOver(3)}
+            variant={this.state.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 />)
+```

package/src/Options/index.tsx

@@ -23,7 +23,7 @@
  */
 
 /** @jsx jsx */
-import { Component, Children, ReactElement } from 'react'
+import React, { Component, Children } from 'react'
 
 import {
   omitProps,
@@ -42,10 +42,18 @@ import generateStyles from './styles'
 import generateComponentTheme from './theme'
 
 import { Item } from './Item'
+import type { OptionsItemProps } from './Item/props'
 import { Separator } from './Separator'
+import type { OptionsSeparatorProps } from './Separator/props'
+
 import type { OptionsProps } from './props'
 import { allowedProps, propTypes } from './props'
 
+type ItemChild = React.ComponentElement<OptionsItemProps, Item>
+type SeparatorChild = React.ComponentElement<OptionsSeparatorProps, Separator>
+type OptionsChild = React.ComponentElement<OptionsProps, Options>
+type OptionsChildren = (ItemChild | SeparatorChild | OptionsChild)[]
+
 /**
 ---
 category: components
@@ -109,11 +117,11 @@ class Options extends Component<OptionsProps> {
     )
   }
 
-  renderSubList(children: React.ReactNode) {
+  renderSubList(subOptions: OptionsChild) {
     const { styles } = this.props
     return (
       <Item as={this.childAs} role="presentation" css={styles?.label}>
-        {children}
+        {subOptions}
       </Item>
     )
   }
@@ -121,12 +129,12 @@ class Options extends Component<OptionsProps> {
   renderChildren() {
     const { children } = this.props
 
-    return Children.map(children, (child) => {
-      if (matchComponentTypes(child, ['Options'])) {
+    return Children.map(children as OptionsChildren, (child) => {
+      if (matchComponentTypes<OptionsChild>(child, ['Options'])) {
         return this.renderSubList(child)
       }
       if (matchComponentTypes(child, ['Item', 'Separator'])) {
-        return safeCloneElement(child as ReactElement, { as: this.childAs })
+        return safeCloneElement(child, { as: this.childAs })
       }
       return undefined
     })