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

package/src/Flex/v2/Item/props.ts

@@ -0,0 +1,146 @@
+/*
+ * 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,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import type {
+  Spacing,
+  WithStyleProps,
+  ComponentStyle
+} from '@instructure/emotion'
+
+type FlexItemOwnProps = {
+  /**
+   * The children to render inside the Item
+   */
+  children?: React.ReactNode
+
+  /**
+   * the element type to render as
+   */
+  as?: AsElementType
+
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef?: (element: Element | null) => void
+
+  /**
+   * 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`, `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
+
+  /**
+   * overrides the parent Flex's alignItems prop, if needed
+   */
+  align?: 'center' | 'start' | 'end' | 'stretch'
+
+  /**
+   * Inherits from the parent Flex component
+   */
+  direction?: 'row' | 'column'
+
+  /**
+   * Designates the text alignment inside the Item
+   */
+  textAlign?: 'start' | 'center' | 'end'
+
+  /**
+   * Handles horizontal overflow
+   */
+  overflowX?: 'auto' | 'hidden' | 'visible'
+
+  /**
+   * Handles vertical overflow
+   */
+  overflowY?: 'auto' | 'hidden' | 'visible'
+
+  /**
+   * Should the FlexItem grow to fill any available space?
+   */
+  shouldGrow?: boolean
+
+  /**
+   * Should the FlexItem shrink (stopping at its `size`)?
+   */
+  shouldShrink?: boolean
+
+  /**
+   * Sets the base size of the FlexItem (width if direction is `row`; height if direction is `column`)
+   */
+  size?: string
+
+  /**
+   * Places dashed lines around the component's borders to help debug your layout
+   */
+  withVisualDebug?: boolean
+  /**
+   * Specifies the order of the `Flex.Item` inside the `Flex` component.
+   *
+   * Utilizes the order flex CSS property.
+   */
+  order?: number
+}
+
+type PropKeys = keyof FlexItemOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type FlexItemProps = FlexItemOwnProps &
+  WithStyleProps<null, FlexItemStyle> &
+  OtherHTMLAttributes<FlexItemOwnProps>
+
+type FlexItemStyle = ComponentStyle<'flexItem'>
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'as',
+  'elementRef',
+  'margin',
+  'padding',
+  'align',
+  'direction',
+  'textAlign',
+  'overflowX',
+  'overflowY',
+  'shouldGrow',
+  'shouldShrink',
+  'size',
+  'withVisualDebug',
+  'order'
+]
+
+export type { FlexItemProps, FlexItemStyle }
+export { allowedProps }

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

@@ -0,0 +1,66 @@
+/*
+ * 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 { FlexItemProps, FlexItemStyle } 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  {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: null,
+  props: FlexItemProps
+): FlexItemStyle => {
+  const { shouldGrow, shouldShrink, align, size, order } = props
+
+  const alignSelfValues = {
+    start: 'flex-start',
+    end: 'flex-end',
+    center: 'center',
+    stretch: 'stretch'
+  }
+
+  return {
+    flexItem: {
+      label: 'flexItem',
+      boxSizing: 'border-box',
+      minWidth: '0.0625rem',
+      flexBasis: size,
+      ...(order !== undefined ? { order } : {}),
+      // initial value is 1, but we want 0 as our default,
+      // so users can opt in to shrink like they do grow
+      flexShrink: shouldShrink ? 1 : 0,
+      ...(shouldGrow && { flexGrow: 1 }),
+      ...(align && { alignSelf: alignSelfValues[align] })
+    }
+  }
+}
+
+export default generateStyle

package/src/Flex/v2/README.md

@@ -0,0 +1,419 @@
+---
+describes: Flex
+---
+
+The Flex component makes it simple for developers to create multi-column
+layouts with flexbox.
+
+### Layout direction
+
+**Note:** Use the `withVisualDebug` property to see the borders of Flex/Flex.Item while developing!
+
+Flex defaults to a `direction` of `row`, creating a horizontal layout. Change `direction` to
+`column` to stack your Flex.Items.
+
+> **Unless your layout has a specific/finite height, you probably don't need `direction="column"`.** To create a layout of stacked elements, it is simpler to use multiple [View](View) components with `display="block"`.
+
+```js
+---
+type: example
+---
+<div>
+  <Flex withVisualDebug margin="none none large">
+    <Flex.Item>One</Flex.Item>
+    <Flex.Item>Two</Flex.Item>
+    <Flex.Item>Three</Flex.Item>
+    <Flex.Item>Four</Flex.Item>
+  </Flex>
+  <Flex withVisualDebug direction="column" margin="none none large">
+    <Flex.Item>One</Flex.Item>
+    <Flex.Item>Two</Flex.Item>
+    <Flex.Item>Three</Flex.Item>
+    <Flex.Item>Four</Flex.Item>
+  </Flex>
+  <Flex withVisualDebug direction="row-reverse" margin="none none large">
+    <Flex.Item>One</Flex.Item>
+    <Flex.Item>Two</Flex.Item>
+    <Flex.Item>Three</Flex.Item>
+    <Flex.Item>Four</Flex.Item>
+  </Flex>
+  <Flex withVisualDebug direction="column-reverse">
+    <Flex.Item>One</Flex.Item>
+    <Flex.Item>Two</Flex.Item>
+    <Flex.Item>Three</Flex.Item>
+    <Flex.Item>Four</Flex.Item>
+  </Flex>
+</div>
+```
+
+### Gap between Flex.Items
+
+Flex items will have no gap by default. You can set the gap between Flex.Items by using the `gap` property.
+
+```js
+---
+type: example
+---
+<div>
+  <Flex withVisualDebug margin="none none large" gap="small">
+    <Flex.Item>One</Flex.Item>
+    <Flex.Item>Two</Flex.Item>
+    <Flex.Item>Three</Flex.Item>
+    <Flex.Item>Four</Flex.Item>
+  </Flex>
+  <Flex withVisualDebug direction="column" margin="none none large" gap="medium">
+    <Flex.Item>One</Flex.Item>
+    <Flex.Item>Two</Flex.Item>
+    <Flex.Item>Three</Flex.Item>
+    <Flex.Item>Four</Flex.Item>
+  </Flex>
+  <Flex withVisualDebug direction="row-reverse" margin="none none large" gap="medium">
+    <Flex.Item>One</Flex.Item>
+    <Flex.Item>Two</Flex.Item>
+    <Flex.Item>Three</Flex.Item>
+    <Flex.Item>Four</Flex.Item>
+  </Flex>
+  <Flex withVisualDebug direction="column-reverse" gap="small">
+    <Flex.Item>One</Flex.Item>
+    <Flex.Item>Two</Flex.Item>
+    <Flex.Item>Three</Flex.Item>
+    <Flex.Item>Four</Flex.Item>
+  </Flex>
+</div>
+```
+
+You can also set the gap between rows and columns by using the `gap` property. Make sure that the `wrap` property is set to `wrap` or `wrap-reverse`.
+
+```js
+---
+type: example
+---
+<div>
+  <Flex withVisualDebug margin="none none large" gap="small" wrap="wrap">
+    <Flex.Item size='25rem'>One</Flex.Item>
+    <Flex.Item size='25rem'>Two</Flex.Item>
+    <Flex.Item size='25rem'>Three</Flex.Item>
+    <Flex.Item size='25rem'>Four</Flex.Item>
+  </Flex>
+  <Flex withVisualDebug margin="none none large" gap="small large" wrap="wrap">
+    <Flex.Item size='25rem'>One</Flex.Item>
+    <Flex.Item size='25rem'>Two</Flex.Item>
+    <Flex.Item size='25rem'>Three</Flex.Item>
+    <Flex.Item size='25rem'>Four</Flex.Item>
+  </Flex>
+  <Flex withVisualDebug margin="none none large" gap="small" wrap="wrap-reverse">
+    <Flex.Item size='25rem'>One</Flex.Item>
+    <Flex.Item size='25rem'>Two</Flex.Item>
+    <Flex.Item size='25rem'>Three</Flex.Item>
+    <Flex.Item size='25rem'>Four</Flex.Item>
+  </Flex>
+  <Flex withVisualDebug margin="none none large" gap="small large" wrap="wrap-reverse">
+    <Flex.Item size='25rem'>One</Flex.Item>
+    <Flex.Item size='25rem'>Two</Flex.Item>
+    <Flex.Item size='25rem'>Three</Flex.Item>
+    <Flex.Item size='25rem'>Four</Flex.Item>
+  </Flex>
+</div>
+```
+
+### Sizing Flex.Items
+
+By default, Flex.Items **expand to fit their contents**, even if that means overflowing
+their container.
+
+```js
+---
+type: example
+---
+<Flex withVisualDebug>
+  <Flex.Item padding="x-small">
+    Villum dolore eu fugiat nulla pariatur.
+  </Flex.Item>
+  <Flex.Item padding="x-small">
+    Lorem ipsum dolor sit amet, consectetur adipisicing elit.
+  </Flex.Item>
+  <Flex.Item padding="x-small">
+    Duis aute irure.
+  </Flex.Item>
+  <Flex.Item padding="x-small">
+    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  </Flex.Item>
+</Flex>
+```
+
+Adding the `shouldShrink` property forces the Flex.Item to shrink as needed to fit inside its
+container.
+
+```js
+---
+type: example
+---
+<Flex withVisualDebug>
+  <Flex.Item padding="x-small" shouldShrink>
+    Villum dolore eu fugiat nulla pariatur.
+  </Flex.Item>
+  <Flex.Item padding="x-small" shouldShrink>
+    Lorem ipsum dolor sit amet, consectetur adipisicing elit.
+  </Flex.Item>
+  <Flex.Item padding="x-small" shouldShrink>
+    Duis aute irure.
+  </Flex.Item>
+  <Flex.Item padding="x-small" shouldShrink>
+    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  </Flex.Item>
+</Flex>
+```
+
+The `shouldGrow` property forces the Flex.Item to expand to fill in any available space.
+
+```js
+---
+type: example
+---
+<Flex withVisualDebug>
+  <Flex.Item padding="x-small" shouldShrink shouldGrow>
+    I am growing and shrinking!
+  </Flex.Item>
+  <Flex.Item>
+    I am not shrinking or growing.
+  </Flex.Item>
+</Flex>
+```
+
+The `size` property sets the base size (accepts px, em, rem) for the Flex.Item. If the
+`direction` property is `row`, this is the item's **width**. If `direction` is `column`,
+then it is the item's **height**. Flex.Items can grow beyond their `size`, but cannot
+shrink to less than their `size`.
+
+```js
+---
+type: example
+---
+<Flex withVisualDebug>
+  <Flex.Item padding="x-small" size="200px">
+    I am always 200px.
+  </Flex.Item>
+  <Flex.Item padding="x-small" shouldShrink shouldGrow size="200px">
+    I can grow, and shrink down to 200px.
+  </Flex.Item>
+  <Flex.Item padding="x-small" size="25%">
+    I am always 25%.
+  </Flex.Item>
+</Flex>
+```
+
+### Aligning Flex.Items
+
+By default, Flex aligns its Flex.Items along the `center` of the axis. Use the `alignItems`
+property to change this behavior.
+
+`alignItems` can be overridden on individual Flex.Items through Flex.Item's `align` property.
+
+```js
+---
+type: example
+---
+<Flex alignItems="end" withVisualDebug>
+  <Flex.Item>
+    <Avatar name="Sarah Robinson" size="large" src={avatarSquare} />
+  </Flex.Item>
+  <Flex.Item shouldGrow shouldShrink>
+    I should be aligned to the bottom of the Avatar.
+  </Flex.Item>
+  <Flex.Item>
+    Me, too.
+  </Flex.Item>
+  <Flex.Item align="start">
+    I am aligning myself to the top.
+  </Flex.Item>
+</Flex>
+```
+
+### Justifying Flex.Items
+
+Use the `justifyItems` property to change the justification of Flex.Items.
+
+```js
+---
+type: example
+---
+<div>
+  <Flex justifyItems="center" margin="0 0 large" withVisualDebug>
+    <Flex.Item>
+      <Avatar name="Sarah Robinson" size="large" src={avatarSquare} />
+    </Flex.Item>
+    <Flex.Item>
+      We are all centered!
+    </Flex.Item>
+    <Flex.Item>
+      Yeah!
+    </Flex.Item>
+  </Flex>
+
+  <Flex justifyItems="space-between" withVisualDebug margin="0 0 large">
+    <Flex.Item>
+      <Avatar name="Sarah Robinson" size="large" src={avatarSquare} />
+    </Flex.Item>
+    <Flex.Item>
+      Ah, a little more space.
+    </Flex.Item>
+    <Flex.Item>
+      Totally.
+    </Flex.Item>
+  </Flex>
+
+  <Flex justifyItems="end" withVisualDebug>
+    <Flex.Item>
+      <Avatar name="Sarah Robinson" size="large" src={avatarSquare} />
+    </Flex.Item>
+    <Flex.Item>
+      Smooshed again.
+    </Flex.Item>
+    <Flex.Item>
+      Ugh.
+    </Flex.Item>
+  </Flex>
+</div>
+```
+
+### Handling overflow
+
+When `direction` is set to `column`, Flex.Items' `overflowY` property is automagically set
+to `auto` to account for content overflow with a vertical scrollbar. Add padding, so focus rings are not cut off.
+
+> To override this default, simply set `overflowY` on the Flex.Item to either `visible` or `hidden`.
+
+```js
+---
+type: example
+---
+  <Flex
+    withVisualDebug
+    direction="column"
+  >
+    <Flex.Item padding="small">
+      <Heading>Pandas are cute, right?</Heading>
+    </Flex.Item>
+    <Flex.Item>
+      <TextInput name="name" renderLabel="If you dont add padding, the focus ring will be cut off!" />
+    </Flex.Item>
+    <Flex.Item size="150px" padding="small">
+      <Img src={avatarSquare} />
+    </Flex.Item>
+  </Flex>
+```
+
+### A few common layouts
+
+#### Heading and button combination
+
+```js
+---
+type: example
+---
+<Flex>
+  <Flex.Item shouldGrow shouldShrink padding="none medium none none">
+    <Heading>Lorem ipsum dolor sit amet consectetur dolor sit</Heading>
+  </Flex.Item>
+  <Flex.Item>
+    <Button margin="none x-small none none">
+      Cancel
+    </Button>
+    <Button color="success" renderIcon={IconUserSolid}>
+      Add user
+    </Button>
+  </Flex.Item>
+</Flex>
+```
+
+#### Centered content (note the nested Flex components and use of the `wrap` property)
+
+```js
+---
+type: example
+---
+<Flex height="32rem" justifyItems="center" padding="large" withVisualDebug>
+  <Flex.Item shouldShrink shouldGrow textAlign="center">
+
+    <Heading level="h1" margin="0 0 medium">An amazing thing!</Heading>
+
+    <Flex withVisualDebug wrap="wrap" justifyItems="space-around" margin="0 0 medium">
+      <Flex.Item padding="small">
+        <SVGIcon src={iconExample} size="medium" title="Icon Example" />
+        <Text weight="bold" size="large" as="div">We love you!</Text>
+      </Flex.Item>
+      <Flex.Item padding="small">
+        <SVGIcon src={iconExample} size="medium" title="Icon Example" />
+        <Text weight="bold" size="large" as="div">We love you!</Text>
+      </Flex.Item>
+      <Flex.Item padding="small">
+        <SVGIcon src={iconExample} size="medium" title="Icon Example" />
+        <Text weight="bold" size="large" as="div">We love you!</Text>
+      </Flex.Item>
+    </Flex>
+
+    <div>
+      <Button color="primary" size="large">Sign up now!</Button>
+    </div>
+
+  </Flex.Item>
+</Flex>
+```
+
+#### Quick and dirty mobile app layout
+
+```js
+---
+type: example
+---
+
+<Flex height="400px" width="300px" as="div" direction="column" withVisualDebug>
+
+  <Flex.Item padding="small" as="header" textAlign="center">
+    <Heading level="h3">App</Heading>
+  </Flex.Item>
+
+  <Flex.Item shouldGrow shouldShrink padding="small" as="main">
+    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+  </Flex.Item>
+
+  <Flex.Item padding="small" as="footer">
+
+    <Flex withVisualDebug justifyItems="space-between">
+      <Flex.Item>
+        <IconButton
+          renderIcon={IconEmailLine}
+          withBackground={false}
+          withBorder={false}
+          screenReaderLabel="Some app function"
+        />
+      </Flex.Item>
+      <Flex.Item>
+        <IconButton
+          renderIcon={IconPrinterLine}
+          withBackground={false}
+          withBorder={false}
+          screenReaderLabel="Some app function"
+        />
+      </Flex.Item>
+      <Flex.Item>
+        <IconButton
+          renderIcon={IconCalendarDayLine}
+          withBackground={false}
+          withBorder={false}
+          screenReaderLabel="Some app function"
+        />
+      </Flex.Item>
+      <Flex.Item>
+        <IconButton
+          renderIcon={IconSettingsLine}
+          withBackground={false}
+          withBorder={false}
+          screenReaderLabel="Some app function"
+        />
+      </Flex.Item>
+    </Flex>
+
+  </Flex.Item>
+</Flex>
+```