@instructure/ui-drawer-layout 11.6.0 → 11.6.1-snapshot-129

package/src/DrawerLayout/v2/DrawerTray/props.ts

@@ -0,0 +1,228 @@
+/*
+ * 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 { PositionMountNode } from '@instructure/ui-position'
+import type { TextDirectionContextConsumerProps } from '@instructure/ui-i18n'
+import type { ComponentStyle, WithStyleProps } from '@instructure/emotion'
+import type {
+  DrawerLayoutTrayTheme,
+  LiveRegion,
+  OtherHTMLAttributes,
+  UIElement
+} from '@instructure/shared-types'
+import type {
+  BaseTransitionStatesType,
+  TransitionType
+} from '@instructure/ui-motion'
+
+type DrawerTrayPlacement = 'start' | 'end'
+
+type DrawerLayoutTrayOwnProps = {
+  label: string
+
+  children?: React.ReactNode | (() => React.ReactNode)
+
+  render?: () => React.ReactNode
+
+  /**
+   * Placement of the `<DrawerLayout.Tray />`
+   */
+  placement?: DrawerTrayPlacement
+
+  /**
+   * If the tray is open or closed.
+   */
+  open?: boolean
+
+  /**
+   * Called when the `<DrawerLayout.Tray />` is opened
+   */
+  onOpen?: (transitionType?: TransitionType) => void
+
+  /**
+   * Called when the `<DrawerLayout.Tray />` is closed
+   */
+  onClose?: (transitionType?: TransitionType) => void
+
+  /**
+   * Should the `<DrawerLayout.Tray />` have a border
+   */
+  border?: boolean
+
+  /**
+   * Should the `<DrawerLayout.Tray />` have a shadow
+   */
+  shadow?: boolean
+
+  /**
+   * Ref function for the `<DrawerLayout.Tray />` content
+   */
+  contentRef?: (element: HTMLDivElement | null) => void
+
+  /**
+   * An element or a function returning an element to use as the mount node
+   * for the `<DrawerLayout.Tray />` when tray is overlaying content
+   */
+  mountNode?: PositionMountNode
+} & PropsPassedToDialog &
+  PropsPassedToTransition &
+  TextDirectionContextConsumerProps
+
+type PropsPassedToDialog = {
+  /**
+   * An element or a function returning an element to focus by default
+   */
+  defaultFocusElement?: UIElement
+
+  /**
+   * An element, function returning an element, or array of elements that will not be hidden from
+   * the screen reader when the `<DrawerLayout.Tray />` is open
+   */
+  liveRegion?: LiveRegion
+
+  /**
+   * Event fired when the underlying FocusRegion is dismissed in overlay mode.
+   * This can happen if:
+   * - `shouldCloseOnDocumentClick` is `true` and the user
+   * clicks outside the `<DrawerLayout.Tray />`
+   * - If `shouldCloseOnEscape` is `true` and the user presses the ESC key.
+   *
+   * This should be used to close the `<DrawerLayout.Tray />` in these cases
+   */
+  onDismiss?: (
+    event: React.UIEvent | React.FocusEvent,
+    documentClick?: boolean
+  ) => void
+
+  shouldContainFocus?: boolean
+
+  shouldReturnFocus?: boolean
+
+  shouldCloseOnDocumentClick?: boolean
+  /**
+   * Should the `<DrawerLayout.Tray />` close when ESC is pressed.
+   * Note that it will only close if it's in the overlay mode (if there is
+   * less space for the content than `DrawerLayout.props.minWidth`)
+   */
+  shouldCloseOnEscape?: boolean
+}
+
+type PropsPassedToTransition = {
+  /**
+   * Callback fired when the `<DrawerLayout.Tray />` transitions in/out
+   */
+  onTransition?: (
+    toState: BaseTransitionStatesType,
+    fromState: BaseTransitionStatesType
+  ) => void
+
+  /**
+   * Callback fired before the `<DrawerLayout.Tray />` transitions in
+   */
+  onEnter?: () => void
+
+  /**
+   * Callback fired as the `<DrawerLayout.Tray />` begins to transition in
+   */
+  onEntering?: () => void
+
+  /**
+   * Callback fired after the `<DrawerLayout.Tray />` finishes transitioning in
+   */
+  onEntered?: (type?: TransitionType) => void
+
+  /**
+   * Callback fired right before the `<DrawerLayout.Tray />` transitions out
+   */
+  onExit?: () => void
+
+  /**
+   * Callback fired as the `<DrawerLayout.Tray />` begins to transition out
+   */
+  onExiting?: () => void
+
+  /**
+   * Callback fired after the `<DrawerLayout.Tray />` finishes transitioning out
+   */
+  onExited?: (type?: TransitionType) => void
+}
+
+type DrawerLayoutTrayState = {
+  transitioning: boolean
+  portalOpen: boolean
+}
+
+type DrawerLayoutTrayStyleProps = {
+  placement: DrawerTrayPlacement
+}
+
+type PropKeys = keyof DrawerLayoutTrayOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type DrawerLayoutTrayProps = DrawerLayoutTrayOwnProps &
+  WithStyleProps<DrawerLayoutTrayTheme, DrawerLayoutTrayStyle> &
+  OtherHTMLAttributes<DrawerLayoutTrayOwnProps>
+
+type DrawerLayoutTrayStyle = ComponentStyle<
+  'drawerTray' | 'drawerTrayWithShadow' | 'drawerTrayContent'
+>
+const allowedProps: AllowedPropKeys = [
+  'label',
+  'children',
+  'render',
+  'placement',
+  'open',
+  'onOpen',
+  'onClose',
+  'border',
+  'shadow',
+  'onTransition',
+  'onEnter',
+  'onEntering',
+  'onEntered',
+  'onExit',
+  'onExiting',
+  'onExited',
+  'contentRef',
+  'mountNode',
+  'defaultFocusElement',
+  'liveRegion',
+  'onDismiss',
+  'shouldContainFocus',
+  'shouldReturnFocus',
+  'shouldCloseOnDocumentClick',
+  'shouldCloseOnEscape',
+  'dir'
+]
+
+export type {
+  DrawerLayoutTrayProps,
+  DrawerLayoutTrayState,
+  DrawerLayoutTrayStyle,
+  DrawerLayoutTrayStyleProps,
+  DrawerTrayPlacement
+}
+export { allowedProps }

package/src/DrawerLayout/v2/DrawerTray/styles.ts

@@ -0,0 +1,106 @@
+/*
+ * 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, SharedTokens } from '@instructure/ui-themes'
+import type {
+  DrawerLayoutTrayProps,
+  DrawerLayoutTrayStyleProps,
+  DrawerLayoutTrayStyle
+} 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} sharedTokens Shared token object that stores common values for the theme.
+ * @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['DrawerLayoutTray'],
+  props: DrawerLayoutTrayProps,
+  _sharedTokens: SharedTokens,
+  state: DrawerLayoutTrayStyleProps
+): DrawerLayoutTrayStyle => {
+  const { border } = props
+  const { placement } = state
+
+  const borderPlacementStyle = {
+    start: { borderRightWidth: componentTheme.borderWidth },
+    end: { borderLeftWidth: componentTheme.borderWidth }
+  }
+
+  const borderStyles = border
+    ? {
+        borderWidth: 0,
+        borderColor: componentTheme.borderColor,
+        borderStyle: componentTheme.borderStyle,
+        boxSizing: 'border-box',
+        ...borderPlacementStyle[placement]
+      }
+    : {
+        boxSizing: 'content-box'
+      }
+
+  const placementStyleMap = {
+    start: { left: 0 },
+    end: { right: 0 }
+  }
+
+  const trayStyle = {
+    position: 'absolute',
+    backgroundColor: componentTheme.background,
+    zIndex: componentTheme.zIndex,
+    overflowY: componentTheme.overflowY,
+    overflowX: componentTheme.overflowX,
+    ...borderStyles,
+    top: 0,
+    bottom: 0,
+    ...placementStyleMap[placement]
+  }
+
+  return {
+    drawerTray: {
+      label: 'drawerTray',
+      ...trayStyle
+    },
+    drawerTrayWithShadow: {
+      label: 'drawerTray--with-shadow',
+      ...trayStyle,
+      boxShadow: componentTheme.boxShadow,
+      border: 0
+    },
+    drawerTrayContent: {
+      label: 'drawerTray__content',
+      overflowY: componentTheme.contentOverflowY,
+      height: '100%',
+      boxSizing: 'content-box'
+    }
+  }
+}
+
+export default generateStyle

package/src/DrawerLayout/v2/README.md

@@ -0,0 +1,231 @@
+---
+describes: DrawerLayout
+---
+
+The `<DrawerLayout />` component creates a layout consisting of both `<DrawerLayout.Tray />` and `<DrawerLayout.Content />`.
+The tray can be placed at the `start` or `end` position. When there is sufficient space available,
+the tray is positioned alongside the content. As the screen gets smaller, the `<DrawerTray />` can
+be configured to overlay the `<DrawerLayout.Content />`
+
+The `minWidth` prop specifies a breakpoint. When the `<DrawerLayout.Content />` resizes such that the width is
+less than the designated `minWidth`, the tray overlays the content
+
+```js
+---
+type: example
+---
+  const Example = () => {
+    const [open, setOpen] = useState(false)
+    const [trayIsOverlayed, setTrayIsOverlayed] = useState(false)
+
+    const handleOverlayTrayChange = (trayIsOverlayed) => {
+      setTrayIsOverlayed(trayIsOverlayed)
+    }
+
+    const handleTrayDismiss = () => {
+      setOpen(false)
+    }
+
+    return (
+      <View height="25rem" as="div" background="primary" position="relative">
+        {trayIsOverlayed && open && <Mask onClick={handleTrayDismiss} />}
+        <DrawerLayout onOverlayTrayChange={handleOverlayTrayChange}>
+          <DrawerLayout.Tray
+            id="DrawerLayoutTrayExample1"
+            open={open}
+            placement="start"
+            label="Drawer Tray Start Example"
+            onDismiss={handleTrayDismiss}
+          >
+            <View
+              as="div"
+              maxWidth="16rem"
+              textAlign="center"
+              margin="large auto"
+              padding="small"
+            >
+              <CloseButton
+                placement="end"
+                offset="small"
+                onClick={handleTrayDismiss}
+                screenReaderLabel="Close"
+              />
+              <Avatar name="foo bar" margin="0 0 small 0" />
+              <Text as="div" size="x-small">
+                Hello from start tray with a small amount of placeholder content
+              </Text>
+            </View>
+          </DrawerLayout.Tray>
+          <DrawerLayout.Content label="Drawer content example">
+            <View as="div" height="100%" background="primary">
+              <View as="div" padding="x-large" background="primary">
+                <Heading border="bottom">A simple drawer layout</Heading>
+                <Grid startAt="medium" vAlign="middle" colSpacing="none">
+                  <Grid.Row>
+                    <Grid.Col>
+                      <Button
+                        margin="small 0"
+                        size="small"
+                        onClick={() => {
+                          setOpen(true)
+                        }}
+                        aria-haspopup={trayIsOverlayed ? 'dialog' : 'region'}
+                        aria-controls="DrawerLayoutTrayExample1"
+                      >
+                        Expand tray
+                      </Button>
+                    </Grid.Col>
+                  </Grid.Row>
+                </Grid>
+                <Text size="x-small">
+                  <p>{lorem.paragraph()}</p>
+                </Text>
+                <Text size="x-small">
+                  <p>{lorem.paragraph()}</p>
+                </Text>
+              </View>
+            </View>
+          </DrawerLayout.Content>
+        </DrawerLayout>
+      </View>
+    )
+  }
+
+  render(<Example />)
+```
+
+Multiple `<DrawerLayout />` components can be nested in order to place trays on both sides
+
+```js
+---
+type: example
+---
+  const Example = () => {
+    const [endOpen, setEndOpen] = useState(false)
+    const [startOpen, setStartOpen] = useState(false)
+
+    return (
+      <View height="40rem" display="block" background="primary">
+        <DrawerLayout>
+          <DrawerLayout.Tray
+            open={endOpen}
+            placement="end"
+            label="Drawer Tray End Example"
+            onDismiss={() => {
+              setEndOpen(false)
+            }}
+          >
+            <View
+              as="div"
+              maxWidth="48rem"
+              textAlign="center"
+              margin="large auto"
+              padding="large"
+              background="primary"
+            >
+              <CloseButton
+                placement="end"
+                offset="small"
+                onClick={() => {
+                  setEndOpen(false)
+                }}
+                screenReaderLabel="Close"
+              />
+              <Text as="div" size="x-small">
+                Hello from end tray with a good amount of content as well
+              </Text>
+            </View>
+          </DrawerLayout.Tray>
+          <DrawerLayout.Content label="Drawer content example containing another layout">
+            <DrawerLayout>
+              <DrawerLayout.Tray
+                label="Layout Tray Start Example"
+                open={startOpen}
+                placement="start"
+                onDismiss={() => {
+                  setStartOpen(false)
+                }}
+              >
+                <View
+                  as="div"
+                  maxWidth="16rem"
+                  textAlign="center"
+                  margin="large auto"
+                  padding="small"
+                >
+                  <CloseButton
+                    placement="end"
+                    offset="small"
+                    onClick={() => {
+                      setStartOpen(false)
+                    }}
+                    screenReaderLabel="Close"
+                  />
+                  <Avatar name="foo bar" margin="0 0 small 0" />
+                  <Text as="div" size="x-small">
+                    Hello from start tray with a small amount of placeholder
+                    content
+                  </Text>
+                </View>
+              </DrawerLayout.Tray>
+              <DrawerLayout.Content label="Drawer content example containing a responsive ">
+                <View as="div" background="primary" height='100%'>
+                  <View as="div" padding="x-large"      background="primary">
+                    <Heading border="bottom">A nested drawer layout</Heading>
+                    <Grid startAt="medium" vAlign="middle" colSpacing="none">
+                      <Grid.Row>
+                        <Grid.Col>
+                          <Button
+                            margin="small 0"
+                            size="small"
+                            onClick={() => {
+                              setStartOpen(true)
+                            }}
+                            aria-haspopup="dialog"
+                          >
+                            Expand start tray
+                          </Button>
+                        </Grid.Col>
+                        <Grid.Col width="auto">
+                          <Button
+                            margin="small 0"
+                            size="small"
+                            onClick={() => {
+                              setEndOpen(true)
+                            }}
+                            aria-haspopup="dialog"
+                          >
+                            Expand end tray
+                          </Button>
+                        </Grid.Col>
+                      </Grid.Row>
+                      <Grid.Row colSpacing="medium">
+                        <Grid.Col>
+                          <Img role="img" src={placeholderImage(250, 250)} />
+                        </Grid.Col>
+                        <Grid.Col>
+                          <Img role="img" src={placeholderImage(250, 250)} />
+                        </Grid.Col>
+                        <Grid.Col>
+                          <Img role="img" src={placeholderImage(250, 250)} />
+                        </Grid.Col>
+                      </Grid.Row>
+                    </Grid>
+                    <Text size="x-small">
+                      <p>{lorem.paragraph()}</p>
+                    </Text>
+                    <Text size="x-small">
+                      <p>{lorem.paragraph()}</p>
+                    </Text>
+                  </View>
+                </View>
+              </DrawerLayout.Content>
+            </DrawerLayout>
+          </DrawerLayout.Content>
+        </DrawerLayout>
+      </View>
+    )
+  }
+
+  render(<Example />)
+```

package/src/DrawerLayout/v2/__fixtures__/DrawerLayout.fixture.tsx

@@ -0,0 +1,75 @@
+/*
+ * 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 { DrawerLayout } from '../index'
+import type { DrawerLayoutProps } from '../props'
+import type { DrawerLayoutTrayProps } from '../DrawerTray/props'
+
+type DrawerLayoutFixtureProps = {
+  layoutWidth?: string | number
+  trayWidth?: string | number
+  placement?: DrawerLayoutTrayProps['placement']
+  open?: DrawerLayoutTrayProps['open']
+  onOverlayTrayChange?: DrawerLayoutProps['onOverlayTrayChange']
+}
+
+export default class DrawerLayoutFixture extends Component<DrawerLayoutFixtureProps> {
+  static defaultProps = {
+    layoutWidth: '600px',
+    trayWidth: '200px',
+    open: false,
+    placement: 'start',
+    onOverlayTrayChange: () => {}
+  }
+
+  render() {
+    const { layoutWidth, trayWidth, open, placement, onOverlayTrayChange } =
+      this.props
+
+    return (
+      <div style={{ width: layoutWidth }}>
+        <DrawerLayout
+          minWidth="500px"
+          onOverlayTrayChange={onOverlayTrayChange}
+        >
+          <DrawerLayout.Tray
+            open={open}
+            placement={placement}
+            label="Test DrawerTray"
+          >
+            <div style={{ width: trayWidth }}>Hello from tray</div>
+          </DrawerLayout.Tray>
+          <DrawerLayout.Content label="Test DrawerContent">
+            <div>
+              Hello from content
+              <button>Expand</button>
+            </div>
+          </DrawerLayout.Content>
+        </DrawerLayout>
+      </div>
+    )
+  }
+}

package/src/DrawerLayout/{index.tsx → v2/index.tsx}

@@ -67,7 +67,7 @@ category: components
 ---
 **/
 @withDeterministicId()
-@withStyle(generateStyle, null)
+@withStyle(generateStyle)
 @textDirectionContextConsumer()
 class DrawerLayout extends Component<DrawerLayoutProps, DrawerLayoutState> {
   static readonly componentId = 'DrawerLayout'