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

package/src/Flex/v2/index.tsx

@@ -0,0 +1,157 @@
+/*
+ * 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 { ComponentElement, Children, Component } from 'react'
+
+import {
+  safeCloneElement,
+  passthroughProps,
+  matchComponentTypes,
+  callRenderProp
+} from '@instructure/ui-react-utils'
+import { View } from '@instructure/ui-view/latest'
+import { withStyle } from '@instructure/emotion'
+
+import { Item } from './Item'
+import type { FlexItemProps } from './Item/props'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { FlexProps } from './props'
+
+/**
+---
+category: components
+---
+@module Flex
+**/
+@withStyle(generateStyle)
+class Flex extends Component<FlexProps> {
+  static readonly componentId = 'Flex'
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  static Item = Item
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    as: 'span',
+    direction: 'row',
+    justifyItems: 'start',
+    display: 'flex',
+    withVisualDebug: false,
+    wrap: 'no-wrap',
+    gap: 'none'
+  }
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  renderChildren(children: FlexProps['children']) {
+    // TODO this might fail if children are () => ReactNode
+    return Children.map(children as React.ReactNode, (child) => {
+      if (!child) {
+        return null
+      }
+
+      return matchComponentTypes<ComponentElement<FlexItemProps, Item>>(child, [
+        'Item'
+      ])
+        ? safeCloneElement(child, {
+            // child withVisualDebug prop should override parent
+            withVisualDebug: this.props.withVisualDebug,
+            ...child.props,
+            direction: this.props.direction!.replace(
+              /-reverse/,
+              ''
+            ) as FlexItemProps['direction']
+          })
+        : child
+    })
+  }
+
+  render() {
+    const {
+      as,
+      withVisualDebug,
+      height,
+      display,
+      margin,
+      padding,
+      textAlign,
+      width,
+      styles,
+      gap,
+      wrap
+    } = this.props
+
+    const children = callRenderProp(this.props.children)
+
+    const gapValuesArray = gap?.split(' ')
+    if (gapValuesArray!.length > 1 && wrap === 'no-wrap')
+      console.warn(
+        'The `gap` prop is supplied with an improper `wrap=no-wrap` prop.'
+      )
+    if (children && Children.count(children) > 0) {
+      return (
+        <View
+          {...passthroughProps(this.props)}
+          css={styles?.flex}
+          elementRef={this.handleRef}
+          as={as}
+          display={display}
+          width={width}
+          height={height}
+          margin={margin}
+          padding={padding}
+          textAlign={textAlign}
+          withVisualDebug={withVisualDebug}
+        >
+          {this.renderChildren(children)}
+        </View>
+      )
+    } else {
+      return null
+    }
+  }
+}
+
+export default Flex
+export { Flex, Item as FlexItem }

package/src/Flex/v2/props.ts

@@ -0,0 +1,152 @@
+/*
+ * 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 {
+  AsElementType,
+  FlexTheme,
+  OtherHTMLAttributes,
+  Renderable
+} from '@instructure/shared-types'
+import type {
+  Spacing,
+  WithStyleProps,
+  ComponentStyle
+} from '@instructure/emotion'
+
+type FlexOwnProps = {
+  /**
+   * It's recommended that you use `Flex.Item` for children, but you can also
+   * pass any markup or a function returning markup.
+   *
+   * Note that if you do not use `Flex.Item`, the `withVisualDebug` and
+   * `direction` props will not automatically be set on the children.
+   */
+  children?: Renderable
+
+  /**
+   * the element type to render as
+   */
+  as?: AsElementType
+
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef?: (element: Element | null) => void
+
+  /**
+   * Sets the height of the component's container (optional)
+   */
+  height?: string | number
+
+  /**
+   * Sets the width of the component's container (optional)
+   */
+  width?: string | number
+
+  /**
+   * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`,
+   * `small`, `medium`, `large`, `x-large`, `xx-large`. 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, `gap="small auto large"`.
+   */
+  gap?: Spacing
+
+  /**
+   * Valid values are `0`, `none`, `xxx-small`, `xx-small`, `x-small`,
+   * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via
+   * familiar CSS-like shorthand. For example: `padding="small x-large large"`.
+   */
+  padding?: Spacing
+
+  /**
+   * Sets the CSS display rule for the component's container
+   */
+  display?: 'flex' | 'inline-flex'
+
+  /**
+   * Designates the text alignment
+   */
+  textAlign?: 'start' | 'center' | 'end'
+
+  /**
+   * Sets the flex-direction to row (horizontal) or column (vertical)
+   */
+  direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse'
+
+  /**
+   * Aligns Flex.Items on the vertical axis (horizontal if direction is column)
+   */
+  alignItems?: 'center' | 'start' | 'end' | 'stretch'
+
+  /**
+   * Aligns Flex.Items on the horizontal axis (vertical if direction is column)
+   */
+  justifyItems?: 'center' | 'start' | 'end' | 'space-around' | 'space-between'
+
+  /**
+   * Determines if the Flex.Items should wrap when they exceed their container's width
+   */
+  wrap?: 'wrap' | 'no-wrap' | 'wrap-reverse'
+
+  /**
+   * Activate a dotted outline around the component to make building your
+   * layout easier
+   */
+  withVisualDebug?: boolean
+}
+
+type PropKeys = keyof FlexOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type FlexProps = FlexOwnProps &
+  WithStyleProps<FlexTheme, FlexStyle> &
+  OtherHTMLAttributes<FlexOwnProps>
+
+type FlexStyle = ComponentStyle<'flex'>
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'as',
+  'elementRef',
+  'height',
+  'width',
+  'margin',
+  'padding',
+  'display',
+  'textAlign',
+  'direction',
+  'alignItems',
+  'justifyItems',
+  'wrap',
+  'withVisualDebug'
+]
+
+export type { FlexProps, FlexStyle }
+export { allowedProps }

package/src/Flex/v2/styles.ts

@@ -0,0 +1,112 @@
+/*
+ * 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 { getShorthandPropValue, makeThemeVars } from '@instructure/emotion'
+import type { NewComponentTypes, SharedTokens } from '@instructure/ui-themes'
+import type { FlexProps, FlexStyle } from './props'
+
+/**
+ * ---
+ * 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  {string} props.justifyItems
+ * @param  {string} props.direction
+ * @param  {string} props.alignItems
+ * @param  {string} props.wrap
+ * @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['Flex'],
+  props: FlexProps,
+  sharedTokens: SharedTokens
+): FlexStyle => {
+  const { justifyItems, wrap, direction, gap } = props
+
+  // align-items css prop
+  // When flex direction is row, 'center' is the most useful default because it
+  // vertically aligns Items. For column direction, though, we want 'stretch'.
+  const alignItems =
+    props.alignItems ||
+    (direction === 'column' || direction === 'column-reverse'
+      ? 'stretch'
+      : 'center')
+  const alignItemsValues = {
+    center: 'center',
+    start: 'flex-start',
+    end: 'flex-end',
+    stretch: 'stretch'
+  }
+
+  // justify-content css prop
+  const justifyItemsValues = {
+    start: 'flex-start',
+    end: 'flex-end',
+    center: 'center',
+    'space-around': 'space-around',
+    'space-between': 'space-between'
+  }
+
+  // wrap css prop
+  const wrapValues = {
+    wrap: 'wrap',
+    'wrap-reverse': 'wrap-reverse',
+    'no-wrap': undefined
+  }
+
+  // flex-direction css props
+  const flexDirectionValues = {
+    column: 'column',
+    'column-reverse': 'column-reverse',
+    row: 'row',
+    'row-reverse': 'row-reverse'
+  }
+
+  // gap css prop
+  const gapValues = makeThemeVars('gap', {
+    ...sharedTokens.spacing,
+    ...sharedTokens.legacy.spacing
+  })
+  const getGapValue = (gap: FlexProps['gap'], values: Record<string, string>) =>
+    getShorthandPropValue('Flex', values, gap, 'gap')
+
+  return {
+    flex: {
+      label: 'flex',
+      fontFamily: componentTheme.fontFamily,
+      boxSizing: 'border-box',
+      alignItems: alignItemsValues[alignItems],
+      justifyContent: justifyItemsValues[justifyItems!],
+      flexWrap: wrapValues[wrap!],
+      flexDirection: flexDirectionValues[direction!],
+      gap: getGapValue(gap!, gapValues)
+    }
+  }
+}
+
+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 { Flex, FlexItem } from '../Flex/v1'
+
+export type { FlexProps } from '../Flex/v1/props'
+export type { FlexItemProps } from '../Flex/v1/Item/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 { Flex, FlexItem } from '../Flex/v2'
+
+export type { FlexProps } from '../Flex/v2/props'
+export type { FlexItemProps } from '../Flex/v2/Item/props'