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

package/src/Grid/v2/README.md

@@ -0,0 +1,239 @@
+---
+describes: Grid
+---
+
+### Create a basic column layout
+
+Simply create a `<Grid>` with some `<Grid.Row>` and `Grid.Col` children, and
+the component will evenly distribute its columns.
+
+Note the `visualDebug` prop you can set if you're wondering
+exactly where your Grid columns are.
+
+```js
+---
+type: example
+---
+<div>
+  <Grid visualDebug>
+    <Grid.Row>
+      <Grid.Col>
+        {lorem.paragraph()}
+      </Grid.Col>
+      <Grid.Col>
+        {lorem.paragraph()}
+      </Grid.Col>
+      <Grid.Col>
+        {lorem.paragraph()}
+      </Grid.Col>
+    </Grid.Row>
+  </Grid>
+  <p>
+    {lorem.paragraph()}
+  </p>
+</div>
+```
+
+### Make the Grid stack until a certain breakpoint/screen width
+
+Often you will want to stack your `<Grid.Col>`s until you reach a certain
+screen width. To do this, use the `startAt` prop.
+
+Reduce the screen width and see how the Grid below only displays its
+columns inline after it hits the `large` breakpoint. Note that by
+default, stacked columns have bottom margin for visual separation.
+
+```js
+---
+type: example
+---
+<Grid startAt="large" visualDebug>
+  <Grid.Row>
+    <Grid.Col>
+      {lorem.paragraph()}
+    </Grid.Col>
+    <Grid.Col>
+      {lorem.paragraph()}
+    </Grid.Col>
+  </Grid.Row>
+</Grid>
+```
+
+### Control the width of each column
+
+You can control the width of the `<Grid.Col>` columns for each
+breakpoint with the `width` prop. Please note the following:
+
+- If you don't need complex responsive behavior, you can just set
+  the width property to a single value for all breakpoints after
+  and including the breakpoint set via the `startAt` prop. e.g.
+  `<Grid.Col width={2}>`
+
+- The Grid is made up of **12 columns**. If the columns' total
+  width exceeds 12, the layout will break.
+
+- In addition to accepting any positive, `<=12` numerical values,
+  columns can also accept an `auto` value. This tells the column
+  to expand to the width of its content. (See the final example Grid
+  to see how this can be useful for right-aligning column content.)
+
+- The `startAt` prop setting supersedes any `<Grid.Col>` width props. For
+  example, if you set `width={{small: 2}}` on a column, but the `startAt` prop
+  on your `<Grid>` is set to `medium`, the `width={{small: 2}}` will be ignored.
+
+```js
+---
+type: example
+---
+<Grid visualDebug>
+  <Grid.Row>
+    <Grid.Col width={{small: 4, medium: 6, large: 3, xLarge: 6}}>
+      {lorem.paragraph()}
+    </Grid.Col>
+    <Grid.Col width={{small: 4, medium: 4, large: 3, xLarge: 5}}>
+      {lorem.paragraph()}
+    </Grid.Col>
+    <Grid.Col width={{small: 4, medium: 2, large: 6, xLarge: 1}}>
+      {lorem.paragraph()}
+    </Grid.Col>
+  </Grid.Row>
+</Grid>
+```
+
+### Add space/gutter between columns and rows
+
+By default there is uniform spacing between Grid columns and rows, use the `colSpacing` and
+`rowSpacing` props, which accept `small`, `medium`, and `large` as values, you can change amount of spacing,
+or remove it with `none`.
+
+```js
+---
+type: example
+---
+<Grid colSpacing="large" rowSpacing="small" visualDebug>
+  <Grid.Row>
+    <Grid.Col>
+      {lorem.paragraph()}
+    </Grid.Col>
+    <Grid.Col>
+      {lorem.paragraph()}
+    </Grid.Col>
+    <Grid.Col>
+      {lorem.paragraph()}
+    </Grid.Col>
+  </Grid.Row>
+  <Grid.Row>
+    <Grid.Col>
+      {lorem.paragraph()}
+    </Grid.Col>
+    <Grid.Col>
+      {lorem.paragraph()}
+    </Grid.Col>
+    <Grid.Col>
+      {lorem.paragraph()}
+    </Grid.Col>
+  </Grid.Row>
+</Grid>
+```
+
+Another useful method for spacing out `<Grid.Col>` elements is to use the `hAlign`
+prop together with set widths on the columns. `hAlign` accepts the following
+values: `start`, `center`, `end`, `space-around`, and `space-between`.
+
+#### `hAlign="space-between"`
+
+```js
+---
+type: example
+---
+  <Grid hAlign="space-between" visualDebug>
+    <Grid.Row>
+      <Grid.Col width={2}>
+        {lorem.paragraph()}
+      </Grid.Col>
+      <Grid.Col width={4}>
+        {lorem.paragraph()}
+      </Grid.Col>
+      <Grid.Col width={2}>
+        {lorem.paragraph()}
+      </Grid.Col>
+    </Grid.Row>
+  </Grid>
+```
+
+#### `hAlign="space-around"`
+
+```js
+---
+type: example
+---
+  <Grid hAlign="space-around" visualDebug>
+    <Grid.Row>
+      <Grid.Col width={2}>
+        {lorem.paragraph()}
+      </Grid.Col>
+      <Grid.Col width={4}>
+        {lorem.paragraph()}
+      </Grid.Col>
+      <Grid.Col width={2}>
+        {lorem.paragraph()}
+      </Grid.Col>
+    </Grid.Row>
+  </Grid>
+```
+
+### Vertically align your columns
+
+Align your columns along the vertical axis with the `vAlign` prop. In the example
+below the Grid is set to vertically center its columns.
+
+```js
+---
+type: example
+---
+  <Grid vAlign="middle" visualDebug>
+    <Grid.Row>
+      <Grid.Col>
+        {lorem.paragraph()}
+      </Grid.Col>
+      <Grid.Col>
+        {lorem.paragraph()}
+      </Grid.Col>
+      <Grid.Col>
+        {lorem.paragraph()}
+      </Grid.Col>
+    </Grid.Row>
+  </Grid>
+```
+
+### Putting it all together
+
+Let's use `<Grid>` to create a page header with a heading on the left side
+and some action buttons on the right. In addition, let's say that on small
+screens &#151; like smalls &#151; we want the header to stack the heading and
+the buttons.
+
+Use `startAt="medium"` to make the Grid only affect most tablets and above. To align
+the buttons to the right, add `width="auto"` to their `<Grid.Col>`. This will
+make the column only expand to fit the width of the buttons. Because the
+`<Grid.Col>` containing the heading has no set width, it will expand by default
+to take up all the width it can, pinning the columns containing the buttons
+to the right.
+
+```js
+---
+type: example
+---
+  <Grid startAt="medium" vAlign="middle" colSpacing="none">
+    <Grid.Row>
+      <Grid.Col>
+        <Heading>I am a fairly lengthy heading for the page</Heading>
+      </Grid.Col>
+      <Grid.Col width="auto">
+        <Button>Cancel</Button>
+        &nbsp;
+        <Button color="primary" renderIcon={IconAddSolid}>Widget</Button>
+      </Grid.Col>
+    </Grid.Row>
+  </Grid>
+```

package/src/Grid/v2/index.tsx

@@ -0,0 +1,117 @@
+/*
+ * 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, Component, Children } from 'react'
+
+import {
+  safeCloneElement,
+  matchComponentTypes,
+  omitProps,
+  pickProps
+} from '@instructure/ui-react-utils'
+
+import { GridRow } from '../../GridRow/v2'
+import type { GridRowProps } from '../../GridRow/v2/props'
+import { GridCol } from '../../GridCol/v2'
+
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { GridProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle)
+class Grid extends Component<GridProps> {
+  static readonly componentId = 'Grid'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    colSpacing: 'medium',
+    rowSpacing: 'medium',
+    hAlign: 'start',
+    startAt: 'small',
+    vAlign: 'top',
+    visualDebug: false,
+    children: null
+  }
+
+  static Row = GridRow
+  static Col = GridCol
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    this.ref = el
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  renderChildren() {
+    const { styles, makeStyles, ...props } = this.props
+    const children = Children.toArray(this.props.children)
+
+    return children.map((child, index) => {
+      if (
+        matchComponentTypes<ComponentElement<GridRowProps, GridRow>>(child, [
+          GridRow
+        ])
+      ) {
+        return safeCloneElement(child, {
+          ...pickProps(props, Grid.allowedProps),
+          ...child.props /* child props should override parent */,
+          isLastRow: index + 1 === children.length
+        })
+      } else {
+        return child // PropType validation should handle errors
+      }
+    })
+  }
+
+  render() {
+    const { styles, ...restProps } = this.props
+
+    const props = omitProps(restProps, Grid.allowedProps)
+
+    return (
+      <span {...props} css={styles?.grid} ref={this.handleRef}>
+        {this.renderChildren()}
+      </span>
+    )
+  }
+}
+
+export default Grid
+export { Grid, GridRow, GridCol }

package/src/Grid/v2/props.ts

@@ -0,0 +1,62 @@
+/*
+ * 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 { GridTheme, OtherHTMLAttributes } from '@instructure/shared-types'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+import type { GridBreakpoints } from '../../utils/v1/GridTypes'
+
+type GridOwnProps = {
+  /**
+   * One of: `Grid.Row`, `ScreenReaderContent`
+   */
+  children?: React.ReactNode // TODO: oneOf([GridRow, ScreenReaderContent])
+  colSpacing?: 'none' | 'small' | 'medium' | 'large'
+  rowSpacing?: 'none' | 'small' | 'medium' | 'large'
+  hAlign?: 'start' | 'center' | 'end' | 'space-around' | 'space-between'
+  vAlign?: 'top' | 'middle' | 'bottom' | 'stretch'
+  startAt?: GridBreakpoints
+  visualDebug?: boolean
+}
+
+type PropKeys = keyof GridOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type GridProps = GridOwnProps &
+  WithStyleProps<GridTheme, GridStyle> &
+  OtherHTMLAttributes<GridOwnProps>
+
+type GridStyle = ComponentStyle<'grid'>
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'colSpacing',
+  'rowSpacing',
+  'hAlign',
+  'vAlign',
+  'startAt',
+  'visualDebug'
+]
+
+export type { GridProps, GridStyle }
+export { allowedProps }

package/src/Grid/v2/styles.ts

@@ -0,0 +1,70 @@
+/*
+ * 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 { GridBreakpoints } from '../../utils/v1/GridTypes'
+import type { GridProps, GridStyle } 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: NewComponentTypes['Grid'],
+  props: GridProps
+): GridStyle => {
+  const { startAt, visualDebug } = props
+
+  const getStartAtVariants = (breakpoint: GridBreakpoints) =>
+    !!startAt && startAt === breakpoint ? { boxSizing: 'border-box' } : {}
+
+  return {
+    grid: {
+      label: 'grid',
+      display: 'block',
+
+      ...getStartAtVariants('small'),
+
+      [`@media screen and (min-width: ${componentTheme.mediumMin})`]: {
+        ...getStartAtVariants('medium')
+      },
+      [`@media screen and (min-width: ${componentTheme.largeMin})`]: {
+        ...getStartAtVariants('large')
+      },
+      [`@media screen and (min-width: ${componentTheme.xLargeMin})`]: {
+        ...getStartAtVariants('x-large')
+      },
+
+      ...(visualDebug && { outline: '0.0625rem dashed red' })
+    }
+  }
+}
+
+export default generateStyle

package/src/GridCol/{index.tsx → v1/index.tsx}

@@ -26,7 +26,7 @@ import { Component } from 'react'
 
 import { omitProps } from '@instructure/ui-react-utils'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleLegacy as withStyle } from '@instructure/emotion'
 import { logWarn as warn } from '@instructure/console'
 
 import generateStyle from './styles'

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

@@ -24,7 +24,7 @@
 
 import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
 import type { GridTheme, OtherHTMLAttributes } from '@instructure/shared-types'
-import type { GridBreakpoints } from '../GridTypes'
+import type { GridBreakpoints } from '../../utils/v1/GridTypes'
 
 type ColWidths = 'auto' | number
 

package/src/GridCol/{styles.ts → v1/styles.ts}

@@ -23,7 +23,7 @@
  */
 
 import type { GridTheme } from '@instructure/shared-types'
-import type { GridBreakpoints } from '../GridTypes'
+import type { GridBreakpoints } from '../../utils/v1/GridTypes'
 import type { GridColProps, GridColStyle } from './props'
 
 type BreakPoints = NonNullable<GridBreakpoints>

package/src/GridCol/v2/index.tsx

@@ -0,0 +1,113 @@
+/*
+ * 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 } from 'react'
+
+import { omitProps } from '@instructure/ui-react-utils'
+
+import { withStyle } from '@instructure/emotion'
+import { logWarn as warn } from '@instructure/console'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { GridColProps } from './props'
+
+/**
+---
+parent: Grid
+id: Grid.Col
+---
+**/
+@withStyle(generateStyle)
+class GridCol extends Component<GridColProps> {
+  static readonly componentId = 'Grid.Col'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    textAlign: 'inherit',
+    children: null,
+    isLastCol: false,
+    isLastRow: false
+  }
+
+  ref: HTMLSpanElement | null = null
+
+  handleRef = (el: HTMLSpanElement | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  widthCheck() {
+    const { width } = this.props
+    let shouldWarn = false
+    if (width) {
+      if (typeof width === 'number' && width <= 0) {
+        shouldWarn = true
+      }
+
+      if (typeof width === 'object') {
+        Object.keys(width).forEach((breakpoint) => {
+          //@ts-expect-error Ts doesn't understand Object.keys properly
+          if (typeof width[breakpoint] === 'number' && width[breakpoint] <= 0) {
+            shouldWarn = true
+          }
+        })
+      }
+    }
+    if (shouldWarn) {
+      warn(false, 'Col width must be positive!')
+    }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+    this.widthCheck()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+    this.widthCheck()
+  }
+
+  render() {
+    const { children, styles } = this.props
+
+    const props = omitProps(this.props, GridCol.allowedProps)
+
+    return (
+      <span {...props} ref={this.handleRef} css={styles?.gridCol}>
+        {children}
+      </span>
+    )
+  }
+}
+
+export default GridCol
+export { GridCol }