feat(ui-flex): add order prop to Flex.Item

INSTUI-4663

Author: ToMESSKa

cypress/component/FlexItem.cy.tsx

@@ -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 { Flex } from '@instructure/ui'
+
+describe('<Flex.Item/>', () => {
+  it('visually reorders items when order prop is set', () => {
+    cy.mount(
+      <Flex data-testid="flex-container-default">
+        <Flex.Item data-testid="item-1-default">FOO</Flex.Item>
+        <Flex.Item data-testid="item-2-default">BOO</Flex.Item>
+      </Flex>
+    )
+
+    cy.get('[data-testid="flex-container-default"]').then(($container) => {
+      const firstItem = $container.find('[data-testid="item-1-default"]')[0]
+      const secondItem = $container.find('[data-testid="item-2-default"]')[0]
+      const firstRect = firstItem.getBoundingClientRect()
+      const secondRect = secondItem.getBoundingClientRect()
+
+      expect(firstRect.left).to.be.lessThan(secondRect.left)
+    })
+
+    // set order prop
+    cy.mount(
+      <Flex data-testid="flex-container-ordered">
+        <Flex.Item order={2} data-testid="item-1-ordered">
+          FOO
+        </Flex.Item>
+        <Flex.Item order={1} data-testid="item-2-ordered">
+          BOO
+        </Flex.Item>
+      </Flex>
+    )
+
+    cy.get('[data-testid="flex-container-ordered"]').then(($container) => {
+      const firstItem = $container.find('[data-testid="item-1-ordered"]')[0]
+      const secondItem = $container.find('[data-testid="item-2-ordered"]')[0]
+      const firstRect = firstItem.getBoundingClientRect()
+      const secondRect = secondItem.getBoundingClientRect()
+
+      expect(secondRect.left).to.be.lessThan(firstRect.left)
+    })
+  })
+})

packages/ui-flex/src/Flex/Item/__tests__/FlexItem.test.tsx

@@ -22,7 +22,7 @@
  * SOFTWARE.
  */
 
-import { render, waitFor } from '@testing-library/react'
+import { render, waitFor, screen } from '@testing-library/react'
 import { vi } from 'vitest'
 
 import '@testing-library/jest-dom'
@@ -57,4 +57,18 @@ describe('<Item />', () => {
 
     expect(axeCheck).toBe(true)
   })
+
+  describe('order prop', () => {
+    it('should apply `order` CSS when passed', () => {
+      render(<Item order={2}>Item with order</Item>)
+      const item = screen.getByText('Item with order')
+      expect(item).toHaveStyle('order: 2')
+    })
+
+    it('should not apply `order` CSS when prop is undefined', () => {
+      render(<Item>Item without order</Item>)
+      const item = screen.getByText('Item without order')
+      expect(item).not.toHaveStyle({ order: expect.anything() })
+    })
+  })
 })

packages/ui-flex/src/Flex/Item/props.ts

@@ -110,6 +110,14 @@ type FlexItemOwnProps = {
    * 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.
+   *
+   * Items with the same order revert to source order.
+   *
+   * Utilizes the order flex CSS property. Default order CSS value is 0.
+   */
+  order?: string | number
 }
 
 type PropKeys = keyof FlexItemOwnProps
@@ -136,7 +144,8 @@ const propTypes: PropValidators<PropKeys> = {
   shouldGrow: PropTypes.bool,
   shouldShrink: PropTypes.bool,
   size: PropTypes.string,
-  withVisualDebug: PropTypes.bool
+  withVisualDebug: PropTypes.bool,
+  order: PropTypes.oneOfType([PropTypes.string, PropTypes.number])
 }
 
 const allowedProps: AllowedPropKeys = [
@@ -153,7 +162,8 @@ const allowedProps: AllowedPropKeys = [
   'shouldGrow',
   'shouldShrink',
   'size',
-  'withVisualDebug'
+  'withVisualDebug',
+  'order'
 ]
 
 export type { FlexItemProps, FlexItemStyle }

packages/ui-flex/src/Flex/Item/styles.ts

@@ -38,7 +38,7 @@ const generateStyle = (
   _componentTheme: null,
   props: FlexItemProps
 ): FlexItemStyle => {
-  const { shouldGrow, shouldShrink, align, size } = props
+  const { shouldGrow, shouldShrink, align, size, order } = props
 
   const alignSelfValues = {
     start: 'flex-start',
@@ -53,6 +53,7 @@ const generateStyle = (
       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,