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

package/src/View/v2/index.tsx

@@ -0,0 +1,240 @@
+/*
+ * 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, ComponentType } from 'react'
+
+import { getCSSStyleDeclaration } from '@instructure/ui-dom-utils'
+import { textDirectionContextConsumer } from '@instructure/ui-i18n'
+import { logError as error } from '@instructure/console'
+import {
+  getElementType,
+  omitProps,
+  pickProps,
+  passthroughProps
+} from '@instructure/ui-react-utils'
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { ViewProps } from './props'
+
+/**
+---
+category: components
+---
+@module View
+**/
+@textDirectionContextConsumer()
+@withStyle(generateStyle)
+class View extends Component<ViewProps> {
+  static componentId = 'View'
+  static allowedProps = allowedProps
+  static defaultProps = {
+    display: 'auto',
+    overflowX: 'visible',
+    overflowY: 'visible',
+    withVisualDebug: false,
+    borderColor: 'primary',
+    position: 'static',
+    focusPosition: 'offset',
+    focusColor: 'info',
+    shouldAnimateFocus: true,
+    overscrollBehavior: 'auto'
+  } as const
+
+  // TODO: Remove this code once all components are using passthroughProps in place
+  // of omitProps and have removed this function
+
+  // omitViewProps needs to be called on the composed View component so that the
+  // View.allowedProps in the method matches the View.allowedProps that will be called in
+  // the consumers. Otherwise the discrepancy could cause unexpected props being
+  // allowed through.
+
+  // Removes View's own props from the given object. Automatically excludes the
+  // following props: 'theme', 'children', 'className', 'style', 'styles',
+  // 'makeStyles', 'themeOverride'
+  // @param props the object to process
+  // @param Component The component whose props are processed.
+  // Only needed for debug logging in non-production builds.
+  static omitViewProps = (
+    props: Record<string, any>,
+    Component: ComponentType<any>
+  ) => {
+    // We don't want the theming and styling props to pass
+    // (these are added and handled by the `@withStyle` decorator)
+    const propsToOmit = [
+      ...View.allowedProps,
+      'styles',
+      'makeStyles',
+      'themeOverride'
+    ]
+
+    let shouldLogError = true
+    try {
+      shouldLogError =
+        process.env.NODE_ENV !== 'production' ||
+        process.env.GITHUB_PULL_REQUEST_PREVIEW === 'true'
+    } catch (e) {
+      if (e instanceof ReferenceError) {
+        // if process is not available a ReferenceError is thrown
+        shouldLogError = false
+      } else {
+        throw e
+      }
+    }
+
+    if (shouldLogError) {
+      Object.keys(pickProps(props, propsToOmit)).forEach((prop) => {
+        error(false, `[${Component.name}] prop '${prop}' is not allowed.`)
+      })
+    }
+    return omitProps(props, propsToOmit)
+  }
+
+  private spanMarginVerified: boolean
+  get _element() {
+    console.warn(
+      '_element property is deprecated and will be removed in v9, please use ref instead'
+    )
+
+    return this.ref
+  }
+
+  constructor(props: ViewProps) {
+    super(props)
+    this.spanMarginVerified = false
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+
+    // Not calling getCSSStyleDeclaration can save hundreds of ms in tests and production
+    if (process.env.NODE_ENV === 'development' && !this.spanMarginVerified) {
+      // We have to verify margins in the first 'componentDidUpdate',
+      // because that is when all styles are calculated,
+      // but we only want to check once, using a flag
+      this.spanMarginVerified = true
+
+      error(
+        !(function verifySpanMargin(element, margin) {
+          if (!element) {
+            return
+          }
+
+          const display = getCSSStyleDeclaration(element)?.display
+
+          if (display !== 'inline') {
+            return
+          }
+
+          const marginValues = margin ? margin.split(' ') : null
+          let verticalMargin = false
+
+          // either top or bottom margin are set
+          if (margin) {
+            if (
+              marginValues &&
+              marginValues[0] &&
+              marginValues[0] !== 'none' &&
+              marginValues[0] !== '0'
+            ) {
+              verticalMargin = true
+            }
+            if (
+              marginValues &&
+              marginValues[2] &&
+              marginValues[2] !== 'none' &&
+              marginValues[2] !== '0'
+            ) {
+              verticalMargin = true
+            }
+          }
+
+          return verticalMargin
+        })(this.ref, this.props.margin),
+        `[View] display style is set to 'inline' and will allow for horizontal margins only.`
+      )
+    }
+  }
+
+  ref: Element | null = null
+
+  handleElementRef = (el: HTMLElement | null) => {
+    if (typeof this.props.elementRef === 'function') {
+      this.props.elementRef(el)
+    }
+    this.ref = el
+  }
+
+  render() {
+    const {
+      children,
+      textAlign,
+      background,
+      display,
+      withVisualDebug,
+      width,
+      height,
+      minWidth,
+      minHeight,
+      maxWidth,
+      maxHeight,
+      overflowX,
+      overflowY,
+      stacking,
+      shadow,
+      position,
+      focusPosition,
+      focusColor,
+      shouldAnimateFocus,
+      borderColor,
+      className,
+      overscrollBehavior,
+      styles,
+      makeStyles,
+      ...props
+    } = this.props
+
+    const ElementType = getElementType(View, this.props)
+
+    return (
+      <ElementType
+        {...passthroughProps(props)}
+        className={className}
+        css={[styles?.view, styles?.inlineStyles]}
+        ref={this.handleElementRef}
+      >
+        {children}
+      </ElementType>
+    )
+  }
+}
+
+export default View
+export { View }

package/src/View/v2/props.ts

@@ -0,0 +1,278 @@
+/*
+ * 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 { Cursor } from '@instructure/shared-types'
+import type {
+  AsElementType,
+  OtherHTMLAttributes,
+  ViewTheme
+} from '@instructure/shared-types'
+import type {
+  WithStyleProps,
+  Spacing,
+  BorderWidth,
+  BorderRadii,
+  Shadow,
+  Stacking,
+  ComponentStyle,
+  StyleObject
+} from '@instructure/emotion'
+
+type BorderColor =
+  | string
+  | 'transparent'
+  | 'primary'
+  | 'secondary'
+  | 'brand'
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'alert'
+  | 'danger'
+
+type ViewOwnProps = {
+  /**
+   * The element to render as the component root, `span` by default
+   */
+  as?: AsElementType
+  /**
+   * provides a reference to the underlying html element
+   */
+  elementRef?: (element: HTMLElement | null) => void
+  /**
+   * By default the display prop is 'auto', meaning it takes on the
+   * display rules of the html element it's rendered as (see `as` prop).
+   */
+  display?:
+    | 'auto'
+    | 'inline'
+    | 'block'
+    | 'inline-block'
+    | 'flex'
+    | 'inline-flex'
+    | 'contents'
+    // these are global CSS values
+    | 'inherit' // inherit the parent's display value
+    | 'initial' // reset the property back to the spec default
+    | 'revert' // reset to user agent stylesheet
+    | 'revert-layer'
+    | 'unset' // same as initial
+  overflowX?: 'auto' | 'hidden' | 'visible'
+  overflowY?: 'auto' | 'hidden' | 'visible'
+  height?: string | number
+  width?: string | number
+  maxHeight?: string | number
+  maxWidth?: string | number
+  minHeight?: string | number
+  minWidth?: string | number
+  /**
+   * The children to render inside the <View />
+   */
+  children?: React.ReactNode
+  /**
+   * Designates the text alignment within the `<View />`
+   */
+  textAlign?: 'start' | 'center' | 'end'
+  /**
+   * Sets the color of the View border.
+   * Accepts a color string value (e.g., "#FFFFFF", "red") or one of the predefined theme color options.
+   */
+  borderColor?: BorderColor
+  /**
+   * Designates the background style of the `<View />`
+   */
+  background?:
+    | 'transparent'
+    | 'primary'
+    | 'secondary'
+    | 'primary-inverse'
+    | 'brand'
+    | 'info'
+    | 'alert'
+    | 'success'
+    | 'danger'
+    | 'warning'
+  /**
+   * Specify a value for the CSS position property. Use `relative` if `focusable` will be true.
+   */
+  position?: 'static' | 'absolute' | 'relative' | 'sticky' | 'fixed'
+  /**
+   * The `left` CSS property in left-to-right interfaces. Will not do anything if `position === "static"`.
+   */
+  insetInlineStart?: string
+  /**
+   * The `right` CSS property in left-to-right interfaces. Will not do anything if `position === "static"`.
+   */
+  insetInlineEnd?: string
+  /**
+   * The `top` CSS property. Will not do anything if `position === "static"`.
+   */
+  insetBlockStart?: string
+  /**
+   * The `bottom` CSS property. Will not do anything if `position === "static"`.
+   */
+  insetBlockEnd?: string
+  /**
+   * Manually control if the `View` should display a focus outline.
+   *
+   * When left `undefined` (which is the default) the focus outline will display
+   * automatically if the `View` is focusable and receives focus.
+   */
+  withFocusOutline?: boolean
+  /**
+   * Determines whether the focus outline displays offset or inset from the focused View
+   */
+  focusPosition?: 'offset' | 'inset'
+  /**
+   * Determines the color of the focus outline
+   */
+  focusColor?: 'info' | 'inverse' | 'success' | 'danger'
+  /**
+   * Determines if the focus ring should animate when it appears
+   */
+  shouldAnimateFocus?: boolean
+  /**
+   * Activate a dotted outline around the component to make building your
+   * layout easier
+   */
+  withVisualDebug?: boolean
+
+  dir?: 'ltr' | 'rtl'
+  /**
+   * Valid values are `0`, `none`, `auto`, and Spacing token values,
+   * see https://instructure.design/layout-spacing. Apply these values via
+   * familiar CSS-like shorthand. For example, `margin="small auto large"`.
+   */
+  margin?: Spacing
+  /**
+   * Valid values are `0`, `none`, `auto`, and Spacing token values,
+   * see https://instructure.design/layout-spacing. Apply these values via
+   * familiar CSS-like shorthand. For example, `padding="small auto large"`.
+   */
+  padding?: Spacing
+  /**
+   * Accepts the familiar CSS shorthand to designate border widths corresponding
+   * to edges
+   */
+  borderWidth?: BorderWidth
+  /**
+   * Accepts `small`, `medium`, `large`, `circle`, and `pill`. Border radius can be
+   * assigned to individual corners in CSS shorthand style (e.g., `"medium large none pill"`).
+   * Also accepts valid CSS length values like `1rem` or `12px`
+   */
+  borderRadius?: BorderRadii
+  /**
+   * Controls the shadow depth for the `<View />`
+   */
+  shadow?: Shadow
+
+  /**
+   * Controls the z-index depth for the `<View />`
+   */
+  stacking?: Stacking
+  /**
+   * Specify a mouse cursor to use when hovering over the `<View />`
+   */
+  cursor?: Cursor
+  /**
+   * Sets what a browser does when reaching the boundary of a scrolling area.
+   * Valid values are `auto`, `contain`, `none`.
+   */
+  overscrollBehavior?: 'auto' | 'contain' | 'none'
+  /**
+   * DEPRECATED, this prop does nothing. Use the focusOutlineOffset theme
+   * variable
+   *
+   * Sets the radius of the focus border ring.
+   *
+   * For offset type, the given value is increased by the difference between the focus ring' offset and the focus ring's width.
+   *
+   * For inset type, the given value is decreased by the sum of the focus ring' offset and the focus ring's width.
+   */
+  focusRingBorderRadius?: string
+  /**
+   * Display the focus ring when any of the descendants is focused.
+   * (uses the [:focus-within](https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within)
+   * CSS selector)
+   */
+  focusWithin?: boolean
+}
+
+type PropKeys = keyof ViewOwnProps
+
+type ViewProps = ViewOwnProps &
+  WithStyleProps<ViewTheme, ViewStyle> &
+  OtherHTMLAttributes<ViewOwnProps>
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type ViewStyle = ComponentStyle<'view'> & {
+  inlineStyles: StyleObject
+}
+
+// This variable will be attached as static property on the `View` component
+// so we don't rely on the `PropTypes` validators for our internal logic.
+// This means on prod builds the consuming applications can safely delete propTypes.
+const allowedProps: AllowedPropKeys = [
+  'as',
+  'background',
+  'borderColor',
+  'borderRadius',
+  'borderWidth',
+  'children',
+  'cursor',
+  'dir',
+  'display',
+  'elementRef',
+  'focusColor',
+  'focusPosition',
+  'height',
+  'insetBlockEnd',
+  'insetBlockStart',
+  'insetInlineEnd',
+  'insetInlineStart',
+  'margin',
+  'maxHeight',
+  'maxWidth',
+  'minHeight',
+  'minWidth',
+  'overflowX',
+  'overflowY',
+  'overscrollBehavior',
+  'padding',
+  'position',
+  'shadow',
+  'shouldAnimateFocus',
+  'stacking',
+  'textAlign',
+  'width',
+  'withFocusOutline',
+  'withVisualDebug',
+  'focusRingBorderRadius',
+  'focusWithin'
+]
+
+export { allowedProps }
+export type { ViewProps, ViewOwnProps, ViewStyle, BorderColor }