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

package/src/Tooltip/{props.ts → v1/props.ts}

@@ -35,7 +35,7 @@ import type {
   PositionMountNode
 } from '@instructure/ui-position'
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
-import type { PopoverOwnProps } from '@instructure/ui-popover'
+import type { PopoverOwnProps } from '@instructure/ui-popover/v11_6'
 import type { WithDeterministicIdProps } from '@instructure/ui-react-utils'
 import { Renderable } from '@instructure/shared-types'
 

package/src/Tooltip/v2/README.md

@@ -0,0 +1,142 @@
+---
+describes: Tooltip
+---
+
+Tooltips are small text-only contextual overlays that are triggered by hover/focus. Use anywhere additional explanation might be needed but space is limited on the triggering element.
+
+> ### What about 'focusable' elements?
+>
+> Content provided to the `renderTip` prop **should not contain any focusable elements**. If you'd like to do
+> that you should use the [Popover](Popover) component and handle focus management yourself or
+> consider using a [Modal](Modal) or a [Tray](Tray) as those will work better on smaller screens.
+
+#### Uncontrolled Tooltips
+
+```js
+---
+type: example
+---
+<div>
+  <p>
+    <Tooltip
+      renderTip="Hello. I'm a tool tip"
+      as={Button}
+      onShowContent={() => console.log('showing')}
+      onHideContent={() => console.log('hidden')}
+    >
+      Hover or focus me
+    </Tooltip>
+  </p>
+  <p>
+    <Tooltip
+      color="primary-inverse"
+      renderTip="Hello. I'm a tool tip"
+      placement="bottom"
+      offsetX="5px"
+    >
+      <TextInput
+        display="inline-block"
+        renderLabel="Enter some text"
+      />
+    </Tooltip>
+  </p>
+  <p>
+    <Tooltip
+      renderTip="Hello. I'm a tool tip"
+      placement="start"
+      on={['click', 'hover', 'focus']}
+    >
+      <IconButton
+        renderIcon={<InfoInstUIIcon color="baseColor"/>}
+        withBackground={false}
+        withBorder={false}
+        screenReaderLabel="Toggle Tooltip"
+      />
+    </Tooltip>
+  </p>
+</div>
+```
+
+#### Controlled Tooltips
+
+```js
+---
+type: example
+---
+const Example = () => {
+  const [isShowingContent, setIsShowingContent] = useState(false)
+
+  return (
+    <>
+      <p>
+        <Tooltip
+          renderTip="Hello. I'm a tool tip"
+          isShowingContent={isShowingContent}
+          onShowContent={(e) => {
+            console.log('expecting to show tooltip')
+          }}
+          onHideContent={(e) => {
+            console.log('expecting to hide tooltip')
+          }}
+        >
+          <Link href="#">This link has a tooltip</Link>
+        </Tooltip>
+      </p>
+      <Checkbox
+        label="show tooltip?"
+        variant="toggle"
+        value="toggled"
+        onChange={(event) => {
+          setIsShowingContent(event.target.checked)
+        }}
+      />
+    </>
+  )
+}
+
+render(<Example />)
+```
+
+### Custom elements as renderTrigger
+
+Popover and Tooltip attach mouse and focus event listeners to their render trigger components via props. These need to be propagated to the component for the listeners to work:
+
+```js
+---
+type: example
+---
+const MyComponent = forwardRef((props, ref) => {
+  return (
+    <View background="primary" padding='space12' {...props} ref={ref}>
+      My custom component
+    </View>
+  )
+})
+
+;<Tooltip renderTip="Tooltip text to display">
+  <MyComponent />
+</Tooltip>
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Use on icons with no labels</Figure.Item>
+    <Figure.Item>Use on condensed dates</Figure.Item>
+    <Figure.Item>Use on table content if items are getting truncated</Figure.Item>
+    <Figure.Item>Use to provide more specific data (ie. user hovers over a chart element, Tooltip shows precise info)</Figure.Item>
+    <Figure.Item>Try to stay within 50 characters</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Repeat the exact information contained on the triggering element</Figure.Item>
+    <Figure.Item>Contain links or focusable items</Figure.Item>
+    <Figure.Item>Use icons inside Tooltips</Figure.Item>
+    <Figure.Item>Use in place of a <Link href="/#Popover">Popover</Link> or <Link href="/#Menu">Menu</Link></Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/Tooltip/v2/index.tsx

@@ -0,0 +1,191 @@
+/*
+ * 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 { Component, ReactNode } from 'react'
+
+import {
+  getElementType,
+  omitProps,
+  ensureSingleChild,
+  passthroughProps,
+  callRenderProp,
+  withDeterministicId
+} from '@instructure/ui-react-utils'
+import { Popover } from '@instructure/ui-popover/latest'
+import type { PopoverProps } from '@instructure/ui-popover/latest'
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import type { TooltipProps, TooltipState } from './props'
+import { allowedProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+@withDeterministicId()
+@withStyle(generateStyle)
+class Tooltip extends Component<TooltipProps, TooltipState> {
+  static readonly componentId = 'Tooltip'
+
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    defaultIsShowingContent: false,
+    color: 'primary',
+    placement: 'top',
+    constrain: 'window',
+    offsetX: 0,
+    offsetY: 0,
+    preventTooltip: false
+  } as const
+
+  private readonly _id: string
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    this.ref = el
+    if (typeof this.props.elementRef === 'function') {
+      this.props.elementRef(el)
+    }
+  }
+
+  constructor(props: TooltipProps) {
+    super(props)
+
+    this._id = props.deterministicId!()
+
+    this.state = { hasFocus: false }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  handleFocus: PopoverProps['onFocus'] = () => {
+    this.setState({ hasFocus: true })
+  }
+
+  handleBlur: PopoverProps['onBlur'] = () => {
+    this.setState({ hasFocus: false })
+  }
+
+  renderTrigger() {
+    const { children, as } = this.props as TooltipProps
+    const { hasFocus } = this.state
+
+    const triggerProps = {
+      'aria-describedby': this._id
+    }
+
+    if (as) {
+      const Trigger = getElementType(Tooltip, this.props)
+      const props = omitProps(this.props, Tooltip.allowedProps)
+      return (
+        <Trigger {...props} {...triggerProps}>
+          {
+            children as ReactNode /*TODO check if it can be TooltipRenderChildren, this might cause a crash*/
+          }
+        </Trigger>
+      )
+    } else if (typeof children === 'function') {
+      return children({
+        focused: hasFocus,
+        getTriggerProps: (props) => ({
+          ...triggerProps,
+          ...props
+        })
+      })
+    } else {
+      return ensureSingleChild(children, triggerProps)
+    }
+  }
+
+  render() {
+    const {
+      renderTip,
+      isShowingContent,
+      defaultIsShowingContent,
+      on,
+      color,
+      placement,
+      mountNode,
+      constrain,
+      offsetX,
+      offsetY,
+      positionTarget,
+      onShowContent,
+      onHideContent,
+      preventTooltip,
+      styles,
+      ...rest
+    } = this.props
+
+    return (
+      <Popover
+        {...passthroughProps(rest)}
+        isShowingContent={!preventTooltip && isShowingContent}
+        defaultIsShowingContent={!preventTooltip && defaultIsShowingContent}
+        on={on}
+        shouldRenderOffscreen
+        shouldReturnFocus={false}
+        placement={placement}
+        color={color === 'primary' ? 'primary-inverse' : 'primary'}
+        mountNode={mountNode}
+        constrain={constrain}
+        shadow="resting"
+        offsetX={offsetX}
+        offsetY={offsetY}
+        positionTarget={positionTarget}
+        renderTrigger={() => this.renderTrigger()}
+        onShowContent={onShowContent}
+        onHideContent={onHideContent}
+        onFocus={this.handleFocus}
+        onBlur={this.handleBlur}
+        elementRef={this.handleRef}
+        shouldCloseOnDocumentClick={false}
+        shouldCloseOnEscape
+        shouldSetAriaExpanded={false}
+        data-cid="Tooltip"
+      >
+        {!preventTooltip ? (
+          <span id={this._id} css={styles?.tooltip} role="tooltip">
+            {/* TODO: figure out how to add a ref to this */}
+            {callRenderProp(renderTip)}
+          </span>
+        ) : null}
+      </Popover>
+    )
+  }
+}
+
+export default Tooltip
+export { Tooltip }

package/src/Tooltip/v2/props.ts

@@ -0,0 +1,223 @@
+/*
+ * 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 React from 'react'
+
+import type {
+  AsElementType,
+  TooltipTheme,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import type {
+  PlacementPropValues,
+  PositionConstraint,
+  PositionMountNode
+} from '@instructure/ui-position'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type { PopoverOwnProps } from '@instructure/ui-popover/latest'
+import type { WithDeterministicIdProps } from '@instructure/ui-react-utils'
+import { Renderable } from '@instructure/shared-types'
+
+type TooltipRenderChildrenArgs = {
+  focused: boolean
+  getTriggerProps: <TriggerProps extends Record<string, any>>(
+    props: TriggerProps
+  ) => { 'aria-describedby': string } & TriggerProps
+}
+
+type TooltipRenderChildren = (
+  args: TooltipRenderChildrenArgs
+) => React.ReactNode
+
+type TooltipOwnProps = {
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef?: (element: Element | null) => void
+  /**
+   * A ReactNode or a function that returns a ReactNode with the following params:
+   *
+   * @param {Boolean} focused - Is the Tooltip trigger focused?
+   * @param {Function} getTriggerProps - Props to be spread onto the trigger element
+   */
+  children: React.ReactNode | TooltipRenderChildren
+
+  /**
+   * The content to render in the tooltip
+   */
+  renderTip: Renderable
+
+  /**
+   * Whether or not the tooltip content is shown, when controlled
+   */
+  isShowingContent?: boolean
+
+  /**
+   * Whether or not to show the content by default, when uncontrolled
+   */
+  defaultIsShowingContent?: boolean
+
+  /**
+   * the element type to render as (assumes a single child if 'as' is undefined)
+   */
+  as?: AsElementType
+
+  /**
+   * The action that causes the Content to display (`click`, `hover`, `focus`)
+   */
+  on?: ('click' | 'hover' | 'focus') | ('click' | 'hover' | 'focus')[]
+
+  /**
+   * The color of the tooltip content
+   */
+  color?: 'primary' | 'primary-inverse'
+
+  /**
+   * Specifies where the Tooltip will be placed in relation to the target element.
+   * Ex. placement="bottom" will render the Tooltip below the triggering element
+   * (Note: if there is not room, it will position opposite. Ex. "top" will
+   * automatically switch to "bottom")
+   */
+  placement?: PlacementPropValues
+
+  /**
+   * An element or a function returning an element to use as the mount node
+   * for the `<Tooltip />` (defaults to `document.body`)
+   */
+  mountNode?: PositionMountNode
+
+  /**
+   * The parent in which to constrain the tooltip.
+   * One of: 'window', 'scroll-parent', 'parent', 'none', an element,
+   * or a function returning an element
+   */
+  constrain?: PositionConstraint
+
+  /**
+   * The horizontal offset for the positioned content
+   */
+  offsetX?: string | number
+
+  /**
+   * The vertical offset for the positioned content
+   */
+  offsetY?: string | number
+
+  /**
+   * Target element for positioning the Tooltip (if it differs from children/trigger)
+   */
+  positionTarget?: PositionMountNode
+
+  /**
+   * Callback fired when content is shown. When controlled, this callback is
+   * fired when the tooltip expects to be shown
+   */
+  onShowContent?: (event: React.UIEvent | React.FocusEvent) => void
+
+  /**
+   * Callback fired when content is hidden. When controlled, this callback is
+   * fired when the tooltip expects to be hidden
+   */
+  onHideContent?: (
+    event: React.UIEvent | React.FocusEvent,
+    args: { documentClick: boolean }
+  ) => void
+
+  /**
+   * If true, it won't display the tooltip. This is useful in cases when tooltip is conditionally needed
+   * but in an uncontrolled way
+   */
+  preventTooltip?: boolean
+}
+
+type PropKeys = keyof TooltipOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+// passes through props for Popover, except the ones set manually
+type PropsPassableToPopover = Omit<
+  PopoverOwnProps,
+  | 'isShowingContent'
+  | 'defaultIsShowingContent'
+  | 'on'
+  | 'shouldRenderOffscreen'
+  | 'shouldReturnFocus'
+  | 'placement'
+  | 'color'
+  | 'children'
+  | 'mountNode'
+  | 'constrain'
+  | 'shadow'
+  | 'offsetX'
+  | 'offsetY'
+  | 'positionTarget'
+  | 'renderTrigger'
+  | 'onShowContent'
+  | 'onHideContent'
+  | 'onFocus'
+  | 'onBlur'
+  | 'elementRef'
+  | 'preventTooltip'
+>
+
+type TooltipProps = PropsPassableToPopover &
+  TooltipOwnProps &
+  WithStyleProps<TooltipTheme, TooltipStyle> &
+  // the OtherHTMLAttributes might be passed to the trigger or Popover
+  OtherHTMLAttributes<TooltipOwnProps> &
+  WithDeterministicIdProps
+
+type TooltipStyle = ComponentStyle<'tooltip'>
+
+type TooltipState = {
+  hasFocus: boolean
+}
+const allowedProps: AllowedPropKeys = [
+  'elementRef',
+  'children',
+  'renderTip',
+  'isShowingContent',
+  'defaultIsShowingContent',
+  'as',
+  'on',
+  'color',
+  'placement',
+  'mountNode',
+  'constrain',
+  'offsetX',
+  'offsetY',
+  'positionTarget',
+  'onShowContent',
+  'onHideContent',
+  'preventTooltip'
+]
+
+export type {
+  TooltipProps,
+  TooltipState,
+  TooltipStyle,
+  TooltipRenderChildren,
+  TooltipRenderChildrenArgs
+}
+export { allowedProps }

package/src/Tooltip/v2/styles.ts

@@ -0,0 +1,52 @@
+/*
+ * 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 { NewComponentTypes } from '@instructure/ui-themes'
+import type { TooltipStyle } from './props'
+
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param  {Object} componentTheme The theme variable object.
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: NewComponentTypes['Tooltip']
+): TooltipStyle => {
+  return {
+    tooltip: {
+      label: 'tooltip',
+      fontFamily: componentTheme.fontFamily,
+      fontWeight: componentTheme.fontWeight,
+      boxSizing: 'border-box',
+      display: 'block',
+      fontSize: componentTheme.fontSize,
+      padding: componentTheme.padding
+    }
+  }
+}
+
+export default generateStyle

package/src/exports/a.ts

@@ -0,0 +1,28 @@
+/*
+ * 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.
+ */
+export { Tooltip } from '../Tooltip/v1'
+export type {
+  TooltipProps,
+  TooltipRenderChildrenArgs
+} from '../Tooltip/v1/props'

package/src/exports/b.ts

@@ -0,0 +1,28 @@
+/*
+ * 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.
+ */
+export { Tooltip } from '../Tooltip/v2'
+export type {
+  TooltipProps,
+  TooltipRenderChildrenArgs
+} from '../Tooltip/v2/props'