@instructure/ui-side-nav-bar 11.6.0 → 11.6.1-snapshot-129

package/src/SideNavBar/v2/README.md

@@ -0,0 +1,108 @@
+---
+describes: SideNavBar
+---
+
+A top-level `SideNavBar` component.
+
+```js
+---
+type: example
+---
+  const Example = () => {
+    const [minimized, setMinimized] = React.useState(false)
+
+    return (
+      <div style={{height: '47rem', width: '10rem'}}>
+        <SideNavBar
+          label="Main navigation"
+          toggleLabel={{
+            expandedLabel: 'Minimize SideNavBar',
+            minimizedLabel: 'Expand SideNavBar'
+          }}
+          onMinimized={(_e, isMinimized) => setMinimized(isMinimized)}
+        >
+          <SideNavBar.Item
+            icon={<GlobeInstUIIcon size={minimized ? "small" : "medium"}/>}
+            label={<ScreenReaderContent>Home</ScreenReaderContent>}
+            href="#"
+            themeOverride={{
+              contentPadding: '1em 0.375rem 1em 0.375rem'
+            }}
+          />
+          <SideNavBar.Item
+            icon={<Avatar name="Ziggy Marley" size="x-small" src={avatarSquare} showBorder="always"/>}
+            label="Account"
+            onClick={() => { this.loadSubNav('account') }}
+          />
+          <SideNavBar.Item
+            icon={<ShieldUserInstUIIcon />}
+            label="Admin"
+            href="#"
+          />
+          <SideNavBar.Item selected
+            icon={<LayoutDashboardInstUIIcon />}
+            label="Dashboard"
+            href="#"
+          />
+          <SideNavBar.Item
+            icon={<BookTextInstUIIcon />}
+            label="Courses"
+            href="#"
+          />
+          <SideNavBar.Item
+            icon={<CalendarDaysInstUIIcon />}
+            label="Calendar"
+            href="#"
+          />
+          <SideNavBar.Item
+            icon={
+              <Badge count={99}
+                formatOutput={function (formattedCount) {
+                  return (
+                    <AccessibleContent alt={`You have ${formattedCount} unread messages.`}>
+                      {formattedCount}
+                    </AccessibleContent>
+                  )
+                }}
+              >
+                <InboxInstUIIcon />
+              </Badge>
+            }
+            label="Inbox"
+            href="#"
+          />
+          <SideNavBar.Item
+            icon={<Clock4InstUIIcon />}
+            label="History"
+            href="#"
+          />
+          <SideNavBar.Item
+            icon={<HelpCircleInstUIIcon />}
+            label="Help"
+            href="#"
+          />
+        </SideNavBar>
+      </div>
+    )
+  }
+
+render(<Example />)
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Use for top-level SideNavBar</Figure.Item>
+    <Figure.Item>Remember that SideNavBar can be themed by the institution</Figure.Item>
+    <Figure.Item>When using an <Link href="/#Avatar">Avatar</Link> in the SideNavBar it should have the <code>showBorder="always"</code> prop</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Add LTI links to the main area</Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/SideNavBar/v2/SideNavBarItem/index.tsx

@@ -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 { Component } from 'react'
+
+import { omitProps, getElementType } from '@instructure/ui-react-utils'
+import { Tooltip } from '@instructure/ui-tooltip/latest'
+import { hasVisibleChildren } from '@instructure/ui-a11y-utils'
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+import type { SideNavBarItemProps } from './props'
+import { allowedProps } from './props'
+
+/**
+---
+parent: SideNavBar
+id: SideNavBar.Item
+---
+**/
+@withStyle(generateStyle, 'SideNavBarItem')
+class SideNavBarItem extends Component<SideNavBarItemProps> {
+  static readonly componentId = 'SideNavBar.Item'
+
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    as: 'a',
+    selected: false,
+    minimized: false
+  } as const
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    const { elementRef } = this.props
+    this.ref = el
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.({ minimized: this.props.minimized })
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.({ minimized: this.props.minimized })
+  }
+
+  renderLink(addRef: boolean) {
+    const ElementType = getElementType(SideNavBarItem, this.props)
+
+    const { href, onClick, icon, label } = this.props
+
+    const props = omitProps(this.props, SideNavBarItem.allowedProps)
+
+    return (
+      <ElementType
+        {...props}
+        href={href}
+        onClick={onClick}
+        ref={addRef ? this.handleRef : undefined}
+        css={this.props.styles?.navigationItem}
+        aria-label={this.props.minimized ? (label as string) : undefined}
+        data-cid="SideNavBarItem"
+      >
+        <div css={this.props.styles?.icon}>{icon}</div>
+        {!this.props.minimized ? (
+          <div css={this.props.styles?.label}>{label}</div>
+        ) : null}
+      </ElementType>
+    )
+  }
+
+  render() {
+    const { minimized, label } = this.props
+    const hasTooltip: boolean = minimized! && hasVisibleChildren(label)
+    const link = this.renderLink(!hasTooltip)
+    return hasTooltip ? (
+      <Tooltip renderTip={label} placement="end" elementRef={this.handleRef}>
+        {link}
+      </Tooltip>
+    ) : (
+      link
+    )
+  }
+}
+
+export default SideNavBarItem
+export { SideNavBarItem }

package/src/SideNavBar/v2/SideNavBarItem/props.ts

@@ -0,0 +1,89 @@
+/*
+ * 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,
+  SideNavBarItemTheme,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+
+type SideNavBarItemOwnProps = {
+  /**
+   * The reference to the underlying HTML element
+   */
+  elementRef?: (el: Element | null) => void
+  /**
+   * The visual to display (ex. an Image, Logo, Avatar, or Icon)
+   */
+  icon: React.ReactNode
+  /**
+   * The text to display  for the SideNavBar Link
+   */
+  label: React.ReactNode
+  /**
+   * The element type to render as (will default to `<a>` if href is provided)
+   */
+  as?: AsElementType
+  /**
+   * If the SideNavBarItem goes to a new page, pass an href
+   */
+  href?: string
+  /**
+   * If the SideNavBarItem does not go to a new page pass an onClick
+   */
+  onClick?: (event: React.MouseEvent) => void
+  /**
+   * Denotes which SideNavBarItem is currently selected
+   */
+  selected?: boolean
+  /**
+   * When minimized is set to true, the `<SideNavBar />` shows icons only while the text becomes a tooltip. When it is set to false, the `<SideNavBar />` shows text in addition to the icons
+   */
+  minimized?: boolean
+}
+
+type PropKeys = keyof SideNavBarItemOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type SideNavBarItemProps = SideNavBarItemOwnProps &
+  WithStyleProps<SideNavBarItemTheme, SideNavBarItemStyle> &
+  OtherHTMLAttributes<SideNavBarItemOwnProps>
+
+type SideNavBarItemStyle = ComponentStyle<'navigationItem' | 'icon' | 'label'>
+const allowedProps: AllowedPropKeys = [
+  'elementRef',
+  'icon',
+  'label',
+  'as',
+  'href',
+  'onClick',
+  'selected',
+  'minimized'
+]
+
+export type { SideNavBarItemProps, SideNavBarItemStyle }
+export { allowedProps }

package/src/SideNavBar/v2/SideNavBarItem/styles.ts

@@ -0,0 +1,111 @@
+/*
+ * 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 { SideNavBarItemProps, SideNavBarItemStyle } 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 theme token object
+ * @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['SideNavBarItem'],
+  props: SideNavBarItemProps
+): SideNavBarItemStyle => {
+  const { selected } = props
+
+  return {
+    navigationItem: {
+      borderRadius: componentTheme.borderRadius,
+      label: 'navigationItem',
+      fontFamily: componentTheme.fontFamily,
+      fontWeight: componentTheme.fontWeight,
+      display: 'block',
+      width: '100%',
+      textAlign: 'center',
+      padding: componentTheme.contentPadding,
+      cursor: 'pointer',
+      border: 'none',
+      boxSizing: 'border-box',
+      textDecoration: componentTheme.linkTextDecoration,
+      overflowWrap: 'break-word',
+      wordWrap: 'break-word',
+      hyphens: 'auto',
+      ...(selected
+        ? {
+            backgroundColor: componentTheme.selectedBackgroundColor,
+            color: componentTheme.selectedFontColor,
+            '&:active, &:hover': {
+              backgroundColor: componentTheme.selectedBackgroundColor,
+              color: componentTheme.selectedFontColor,
+              textDecoration: componentTheme.linkTextDecoration
+            },
+            '&:focus': {
+              backgroundColor: componentTheme.selectedBackgroundColor,
+              boxShadow: `${componentTheme.selectedOuterFocusOutlineColor}, ${componentTheme.selectedInnerFocusOutlineColor}`,
+              outline: 'none'
+            }
+          }
+        : {
+            backgroundColor: componentTheme.backgroundColor,
+            color: componentTheme.fontColor,
+            '&:active': {
+              backgroundColor: componentTheme.hoverBackgroundColor
+            },
+            '&:hover': {
+              transition: 'background-color .3s',
+              backgroundColor: componentTheme.hoverBackgroundColor,
+              color: componentTheme.fontColor,
+              textDecoration: componentTheme.linkTextDecoration
+            },
+            '&:focus': {
+              backgroundColor: componentTheme.hoverBackgroundColor,
+              boxShadow: `inset 0 0 0 0.125rem ${componentTheme.outerFocusOutlineColor}, inset 0 0 0 0.25rem ${componentTheme.innerFocusOutlineColor}`,
+              outline: 'none'
+            }
+          })
+    },
+    icon: {
+      label: 'navigationItem__icon',
+      height: componentTheme.iconWrapperHeight,
+      display: 'flex',
+      alignItems: 'center',
+      justifyContent: 'center'
+    },
+    label: {
+      label: 'navigationItem__label',
+      fontSize: componentTheme.fontSize,
+      lineHeight: componentTheme.lineHeight
+    }
+  }
+}
+
+export default generateStyle

package/src/SideNavBar/v2/index.tsx

@@ -0,0 +1,162 @@
+/*
+ * 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, Children, ReactElement, isValidElement } from 'react'
+
+import { omitProps, safeCloneElement } from '@instructure/ui-react-utils'
+import {
+  PanelLeftCloseInstUIIcon,
+  PanelLeftOpenInstUIIcon,
+  renderIconWithProps
+} from '@instructure/ui-icons'
+import { ScreenReaderContent } from '@instructure/ui-a11y-content'
+import { withStyle } from '@instructure/emotion'
+
+import { SideNavBarItem } from './SideNavBarItem'
+
+import generateStyle from './styles'
+import type { SideNavBarProps, SideNavBarState } from './props'
+import { allowedProps } from './props'
+
+const navMinimized = ({ minimized }: { minimized: boolean }) => ({
+  minimized: !minimized
+})
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle)
+class SideNavBar extends Component<SideNavBarProps, SideNavBarState> {
+  static readonly componentId = 'SideNavBar'
+
+  static allowedProps = allowedProps
+
+  static defaultProps = {
+    children: null,
+    defaultMinimized: false,
+    // TODO we should investigate later if it used or not
+    onClick: function (_e: React.MouseEvent) {}
+  }
+
+  static Item = SideNavBarItem
+
+  ref: Element | null = null
+
+  constructor(props: SideNavBarProps) {
+    super(props)
+
+    this.state = {
+      minimized: this.isControlled(props)
+        ? !!props.minimized
+        : !!props.defaultMinimized
+    }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.({ minimized: this.minimized })
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.({ minimized: this.minimized })
+  }
+
+  get minimized() {
+    if (this.isControlled()) {
+      return !!this.props.minimized
+    }
+    return !!this.state.minimized
+  }
+
+  isControlled(props = this.props) {
+    return typeof props.minimized === 'boolean'
+  }
+
+  handleNavToggle = (event: React.SyntheticEvent) => {
+    if (!this.isControlled()) {
+      this.setState(navMinimized)
+    }
+    if (typeof this.props.onMinimized === 'function') {
+      this.props.onMinimized(event, !this.minimized)
+    }
+  }
+
+  renderChildren() {
+    return Children.map(this.props.children, (child) => {
+      if (!isValidElement(child)) return null
+      const navItem = safeCloneElement(child as ReactElement, {
+        minimized: this.state.minimized
+      })
+      return <li css={this.props.styles?.list}>{navItem}</li>
+    })
+  }
+
+  renderIcon() {
+    const icon = this.minimized
+      ? PanelLeftOpenInstUIIcon
+      : PanelLeftCloseInstUIIcon
+    const iconColor = this.props.selected
+      ? 'sideNavActiveColor'
+      : 'sideNavColor'
+
+    return renderIconWithProps(icon, 'lg', iconColor as any) //TODO-rework remove after merging into v12
+  }
+
+  toggleMessage() {
+    return this.state.minimized
+      ? this.props.toggleLabel.minimizedLabel
+      : this.props.toggleLabel.expandedLabel
+  }
+
+  render() {
+    const { label } = this.props
+
+    const props = omitProps(this.props, SideNavBar.allowedProps, ['minimized'])
+
+    return (
+      <nav
+        {...props}
+        css={this.props.styles?.navigation}
+        data-cid="SideNavBar"
+        aria-label={label}
+        ref={(element) => {
+          this.ref = element
+        }}
+      >
+        <ul css={this.props.styles?.content}>{this.renderChildren()}</ul>
+        <SideNavBarItem
+          aria-expanded={!this.minimized}
+          onClick={this.handleNavToggle}
+          icon={this.renderIcon()}
+          label={
+            <ScreenReaderContent>{this.toggleMessage()}</ScreenReaderContent>
+          }
+        ></SideNavBarItem>
+      </nav>
+    )
+  }
+}
+
+export default SideNavBar
+export { SideNavBar, SideNavBarItem }

package/src/SideNavBar/v2/props.ts

@@ -0,0 +1,94 @@
+/*
+ * 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 {
+  SideNavBarTheme,
+  OtherHTMLAttributes
+} from '@instructure/shared-types'
+import type { WithStyleProps, ComponentStyle } from '@instructure/emotion'
+
+type SideNavBarOwnProps = {
+  /**
+   * When minimized is set to true, the `<SideNavBar />` shows icons only while the text becomes a tooltip. When it is set to false, the `<SideNavBar />` shows text in addition to the icons
+   */
+  minimized?: boolean
+  /**
+   * Whether the `<SideNavBar />` is initially minimized (uncontrolled)
+   */
+  defaultMinimized?: boolean
+  onMinimized?: (event: React.SyntheticEvent, minimized: boolean) => void
+  /**
+   * Screen reader label for the main SideNavBar
+   */
+  label: string
+  /**
+   * Screen reader label for the toggle button expanded/minimized state
+   */
+  toggleLabel: {
+    expandedLabel?: string
+    minimizedLabel?: string
+  }
+  /**
+   * If the `<SideNavBar.Item>` goes to a new page, pass an href
+   */
+  href?: string
+  /**
+   * If the `<SideNavBar.Item>` does not go to a new page pass an onClick
+   */
+  onClick?: (event: React.MouseEvent) => void
+  /**
+   * children of type SideNavBar.Item
+   */
+  children?: React.ReactNode
+}
+
+type SideNavBarState = {
+  minimized: boolean
+}
+
+type PropKeys = keyof SideNavBarOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type SideNavBarProps = SideNavBarOwnProps &
+  WithStyleProps<SideNavBarTheme, SideNavBarStyle> &
+  OtherHTMLAttributes<SideNavBarOwnProps>
+
+type SideNavBarStyle = ComponentStyle<
+  'navigation' | 'list' | 'content' | 'toggleIcon'
+>
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'minimized',
+  'defaultMinimized',
+  'onMinimized',
+  'label',
+  'toggleLabel',
+  'href',
+  'onClick'
+]
+
+export type { SideNavBarProps, SideNavBarState, SideNavBarStyle }
+export { allowedProps }