@instructure/ui-top-nav-bar 8.30.1-snapshot-15

package/src/TopNavBar/TopNavBarLayout/props.ts

@@ -0,0 +1,209 @@
+/*
+ * 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 PropTypes from 'prop-types'
+
+import {
+  Children as ChildrenPropTypes,
+  element
+} from '@instructure/ui-prop-types'
+
+import type { WithStyleProps } from '@instructure/emotion'
+import type {
+  TopNavBarLayoutTheme,
+  OtherHTMLAttributes,
+  PropValidators
+} from '@instructure/shared-types'
+
+import { TopNavBarActionItems } from '../TopNavBarActionItems'
+import { TopNavBarBrand } from '../TopNavBarBrand'
+import { TopNavBarMenuItems } from '../TopNavBarMenuItems'
+import { TopNavBarUser } from '../TopNavBarUser'
+
+import type { ActionItemsChild } from '../TopNavBarActionItems/props'
+import type { BrandChild } from '../TopNavBarBrand/props'
+import type { MenuItemsChild } from '../TopNavBarMenuItems/props'
+import type { UserChild } from '../TopNavBarUser/props'
+
+import { topNavBarItemTooltipPropType } from '../TopNavBarItem/props'
+
+import { TopNavBarLayout } from './index'
+import type { DesktopLayoutOwnProps } from './DesktopLayout/props'
+import type { SmallViewportLayoutOwnProps } from './SmallViewportLayout/props'
+
+type LayoutChild = React.ComponentElement<TopNavBarLayoutProps, TopNavBarLayout>
+
+type CommonTopNavBarLayoutProps = {
+  /**
+   * Displays the app/product/brand/company/etc. name and/or logo.
+   *
+   * Accepts a `<TopNavBar.Brand>` component.
+   */
+  renderBrand?: BrandChild
+
+  /**
+   * Displays the main navbar items.
+   *
+   * In __desktop__ mode the items are listed on the navbar,
+   * in __smallViewport__ mode the items are accessible under the main "hamburger" menu.
+   *
+   * Accepts a `<TopNavBar.MenuItems>` component.
+   */
+  renderMenuItems?: MenuItemsChild
+
+  /**
+   * Displays the action items, icons, buttons, etc.
+   *
+   * Renders in the top right corner of the navbar in both __desktop__ and __smallViewport__ mode.
+   *
+   * Accepts a `<TopNavBar.ActionItems>` component.
+   */
+  renderActionItems?: ActionItemsChild
+
+  /**
+   * Displays the user menu.
+   *
+   * In __desktop__ mode it renders in the top right corner of the navbar,
+   * in __smallViewport__ mode it is rendered under the main "hamburger" menu, above the menu items.
+   *
+   * Accepts a `<TopNavBar.User>` component.
+   */
+  renderUser?: UserChild
+
+  /**
+   * The 'aria-label' for the underlying `<nav>` element
+   */
+  navLabel?: string
+
+  /**
+   * A function that returns a reference to root HTML element
+   */
+  elementRef?: (el: HTMLElement | null) => void
+}
+
+type TopNavBarLayoutOwnProps = CommonTopNavBarLayoutProps & {
+  /**
+   * Config object for the "desktop" mode:
+   */
+  desktopConfig?: DesktopLayoutOwnProps
+
+  /**
+   * Config object for the "small viewport" mode:
+   */
+  smallViewportConfig: SmallViewportLayoutOwnProps
+}
+
+type CommonPropKeys = keyof CommonTopNavBarLayoutProps
+type PropKeys = keyof TopNavBarLayoutOwnProps
+type DesktopPropKeys = keyof DesktopLayoutOwnProps
+type SmallViewportPropKeys = keyof SmallViewportLayoutOwnProps
+
+type CommonAllowedPropKeys = Readonly<Array<CommonPropKeys>>
+type DesktopAllowedPropKeys = Readonly<Array<DesktopPropKeys>>
+type SmallViewportAllowedPropKeys = Readonly<Array<SmallViewportPropKeys>>
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type TopNavBarLayoutProps = TopNavBarLayoutOwnProps &
+  WithStyleProps<TopNavBarLayoutTheme, null> &
+  OtherHTMLAttributes<TopNavBarLayoutOwnProps>
+
+const commonPropTypes: PropValidators<CommonPropKeys> = {
+  renderBrand: ChildrenPropTypes.oneOf([TopNavBarBrand]),
+  renderMenuItems: ChildrenPropTypes.oneOf([TopNavBarMenuItems]),
+  renderActionItems: ChildrenPropTypes.oneOf([TopNavBarActionItems]),
+  renderUser: ChildrenPropTypes.oneOf([TopNavBarUser]),
+  navLabel: PropTypes.string,
+  elementRef: PropTypes.func
+}
+
+const desktopPropTypes: PropValidators<DesktopPropKeys> = {
+  hideActionsUserSeparator: PropTypes.bool
+}
+
+const smallViewportPropTypes: PropValidators<SmallViewportPropKeys> = {
+  dropdownMenuToggleButtonLabel: PropTypes.string.isRequired,
+  dropdownMenuToggleButtonTooltip: topNavBarItemTooltipPropType,
+  dropdownMenuLabel: PropTypes.string,
+  alternativeTitle: PropTypes.node,
+  renderInPlaceDialogConfig: PropTypes.shape({
+    open: PropTypes.bool.isRequired,
+    onClose: PropTypes.func.isRequired,
+    closeButtonLabel: PropTypes.string.isRequired,
+    content: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+    returnFocusElement: PropTypes.func,
+    shouldContainFocus: PropTypes.bool,
+    shouldCloseOnDocumentClick: PropTypes.bool,
+    shouldCloseOnEscape: PropTypes.bool
+  }),
+  trayMountNode: PropTypes.oneOfType([element, PropTypes.func]),
+  onDropdownMenuToggle: PropTypes.func,
+  onDropdownMenuSelect: PropTypes.func
+}
+
+const propTypes: PropValidators<PropKeys> = {
+  ...commonPropTypes,
+  desktopConfig: PropTypes.shape(desktopPropTypes),
+  smallViewportConfig: PropTypes.shape(smallViewportPropTypes).isRequired
+}
+
+const commonAllowedProps: CommonAllowedPropKeys = [
+  'renderBrand',
+  'renderMenuItems',
+  'renderActionItems',
+  'renderUser',
+  'navLabel',
+  'elementRef'
+]
+
+const desktopAllowedProps: DesktopAllowedPropKeys = ['hideActionsUserSeparator']
+
+const smallViewportAllowedProps: SmallViewportAllowedPropKeys = [
+  'dropdownMenuToggleButtonLabel',
+  'dropdownMenuToggleButtonTooltip',
+  'dropdownMenuLabel',
+  'alternativeTitle',
+  'renderInPlaceDialogConfig',
+  'trayMountNode',
+  'onDropdownMenuToggle',
+  'onDropdownMenuSelect'
+]
+
+const allowedProps: AllowedPropKeys = [
+  ...commonAllowedProps,
+  'desktopConfig',
+  'smallViewportConfig'
+]
+
+export type { LayoutChild, CommonTopNavBarLayoutProps, TopNavBarLayoutProps }
+export {
+  propTypes,
+  allowedProps,
+  commonPropTypes,
+  commonAllowedProps,
+  desktopPropTypes,
+  smallViewportPropTypes,
+  desktopAllowedProps,
+  smallViewportAllowedProps
+}

package/src/TopNavBar/TopNavBarLayout/theme.ts

@@ -0,0 +1,47 @@
+/*
+ * 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 { Theme } from '@instructure/ui-themes'
+import type { TopNavBarLayoutTheme } from '@instructure/shared-types'
+
+import desktopTheme from './DesktopLayout/theme'
+import smallViewportTheme from './SmallViewportLayout/theme'
+
+/**
+ * Generates the theme object for the component from the theme and provided additional information
+ * @param  {Object} theme The actual theme object.
+ * @return {Object} The final theme object with the overrides and component variables
+ */
+const generateComponentTheme = (theme: Theme): TopNavBarLayoutTheme => {
+  const componentVariables: TopNavBarLayoutTheme = {
+    ...desktopTheme(theme),
+    ...smallViewportTheme(theme)
+  }
+
+  return {
+    ...componentVariables
+  }
+}
+
+export default generateComponentTheme

package/src/TopNavBar/TopNavBarLocator.ts

@@ -0,0 +1,31 @@
+/*
+ * 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 { locator } from '@instructure/ui-test-locator'
+
+import { TopNavBar } from './index'
+
+// @ts-expect-error ts-migrate(2339) FIXME: Property 'selector' does not exist on type 'typeof... Remove this comment to see the full error message
+export const TopNavBarLocator = locator(TopNavBar.selector, {
+  /* custom component query methods go here */
+})

package/src/TopNavBar/TopNavBarMenuItems/TopNavBarMenuItemsLocator.ts

@@ -0,0 +1,56 @@
+/*
+ * 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 { locator } from '@instructure/ui-test-locator'
+
+/* eslint-disable no-restricted-imports */
+// @ts-expect-error bypass no type definition found error
+import { TruncateListLocator } from '@instructure/ui-truncate-list/es/TruncateList/TruncateListLocator'
+/* eslint-enable no-restricted-imports */
+
+import { TopNavBarItemLocator } from '../TopNavBarItem/TopNavBarItemLocator'
+
+import { TopNavBarMenuItems } from './index'
+
+// @ts-expect-error ts-migrate(2339) FIXME: Property 'selector' does not exist on type 'typeof... Remove this comment to see the full error message
+export const TopNavBarMenuItemsLocator = locator(TopNavBarMenuItems.selector, {
+  findAllMenuItems: (...args: any[]) => {
+    return TopNavBarItemLocator.findAll(...args)
+  },
+  findTruncateList: (...args: any[]) => {
+    return TruncateListLocator.find(...args)
+  },
+  findTruncateListTriggerItem: async (...args: any[]) => {
+    const truncateList = await TruncateListLocator.find(...args)
+
+    if (truncateList) {
+      return TopNavBarItemLocator.find(
+        '[id^=TopNavBarMenuItems-hiddenMenuItemsMenuTrigger_]',
+        ...args
+      )
+    } else {
+      return truncateList
+    }
+  }
+})

package/src/TopNavBar/TopNavBarMenuItems/index.tsx

@@ -0,0 +1,275 @@
+/*
+ * 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.
+ */
+
+/** @jsx jsx */
+import React, { Component } from 'react'
+
+import {
+  omitProps,
+  safeCloneElement,
+  withDeterministicId
+} from '@instructure/ui-react-utils'
+import { warn, error } from '@instructure/console'
+import { testable } from '@instructure/ui-testable'
+
+import { withStyle, jsx } from '@instructure/emotion'
+
+import { Drilldown } from '@instructure/ui-drilldown'
+import { TruncateList } from '@instructure/ui-truncate-list'
+
+import { TopNavBarContext } from '../TopNavBarContext'
+import { TopNavBarItem } from '../TopNavBarItem'
+import type { ItemChild } from '../TopNavBarItem/props'
+
+import {
+  mapItemsForDrilldown,
+  renderMappedItemDrilldownSubpages,
+  renderMappedItemsAsDrilldownOptions
+} from '../utils/mapItemsForDrilldown'
+import type { RenderOptionContent } from '../utils/mapItemsForDrilldown'
+
+import generateStyle from './styles'
+import generateComponentTheme from './theme'
+
+import { propTypes, allowedProps } from './props'
+import type { TopNavBarMenuItemsProps, TopNavBarMenuItemsState } from './props'
+
+/**
+---
+parent: TopNavBar
+id: TopNavBar.MenuItems
+---
+@module TopNavBarMenuItems
+@tsProps
+**/
+@withDeterministicId()
+@withStyle(generateStyle, generateComponentTheme)
+@testable()
+class TopNavBarMenuItems extends Component<
+  TopNavBarMenuItemsProps,
+  TopNavBarMenuItemsState
+> {
+  static readonly componentId = 'TopNavBar.MenuItems'
+
+  static propTypes = propTypes
+  static allowedProps = allowedProps
+  static defaultProps = {}
+
+  declare context: React.ContextType<typeof TopNavBarContext>
+  static contextType = TopNavBarContext
+
+  private readonly _hiddenMenuItemsMenuTriggerId: string
+  private readonly _hiddenItemsMenuId: string
+
+  ref: HTMLUListElement | Element | null = null
+
+  handleRef = (el: HTMLUListElement | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  constructor(props: TopNavBarMenuItemsProps) {
+    super(props)
+
+    this._hiddenMenuItemsMenuTriggerId = props.deterministicId!(
+      'TopNavBarMenuItems-hiddenMenuItemsMenuTrigger'
+    )
+    this._hiddenItemsMenuId = props.deterministicId!(
+      'TopNavBarSmallViewportLayout-drilldown'
+    )
+
+    this.state = {
+      key: 0,
+      visibleItemsCount: undefined
+    }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate(prevProps: TopNavBarMenuItemsProps) {
+    this.props.makeStyles?.()
+
+    if (
+      React.Children.count(prevProps.children) !== this.childrenArray.length
+    ) {
+      this.setState({ key: this.state.key + 1 })
+    }
+  }
+
+  get childrenArray() {
+    return React.Children.toArray(this.props.children) as ItemChild[]
+  }
+
+  renderOptionContent: RenderOptionContent = (children, itemProps) => {
+    const { styles } = this.props
+
+    return (
+      <span
+        css={
+          itemProps?.status === 'active'
+            ? styles?.submenuOptionActive
+            : styles?.submenuOption
+        }
+      >
+        {children}
+      </span>
+    )
+  }
+
+  renderHiddenItemsMenu(hiddenItems: ItemChild[]) {
+    const { renderHiddenItemsMenuTriggerLabel, currentPageId } = this.props
+
+    if (!hiddenItems.length) {
+      return <span></span>
+    }
+
+    const mappedItems = mapItemsForDrilldown(hiddenItems, {
+      renderOptionContent: this.renderOptionContent,
+      currentPageId
+    })
+    const subPages = renderMappedItemDrilldownSubpages(mappedItems)
+    const options = renderMappedItemsAsDrilldownOptions(mappedItems)
+
+    const hasActiveChild = hiddenItems.find(
+      (child) => child.props.status === 'active'
+    )
+
+    return (
+      <TopNavBarItem
+        id={this._hiddenMenuItemsMenuTriggerId}
+        status={hasActiveChild ? 'active' : 'default'}
+        renderSubmenu={
+          <Drilldown rootPageId={this._hiddenItemsMenuId}>
+            {[
+              <Drilldown.Page
+                id={this._hiddenItemsMenuId}
+                key={this._hiddenItemsMenuId}
+              >
+                {options}
+              </Drilldown.Page>,
+              ...subPages
+            ]}
+          </Drilldown>
+        }
+      >
+        {renderHiddenItemsMenuTriggerLabel(hiddenItems.length)}
+      </TopNavBarItem>
+    )
+  }
+
+  renderChildren() {
+    const { currentPageId } = this.props
+
+    return this.childrenArray.map((child) => {
+      if (!child) {
+        return
+      }
+
+      const { id, status, variant, renderSubmenu, renderAvatar } = child.props
+      const isCurrentPage = currentPageId === id
+
+      if (renderAvatar) {
+        error(
+          false,
+          `Items in <TopNavBar.MenuItems> are not allowed to have avatars, but item with id: "${id}" has \`renderAvatar\` prop.`
+        )
+        return null
+      }
+
+      if (!isCurrentPage) {
+        return child
+      } else {
+        if (variant !== 'default') {
+          warn(
+            false,
+            `Only \`variant="default"\` items can be set to current/active, but the item with id "${id}" is "${variant}" variant.`
+          )
+
+          return child
+        }
+
+        if (status === 'disabled') {
+          warn(
+            false,
+            `Disabled items can not be set to current/active, but the item with id "${id}" is disabled.`
+          )
+
+          return child
+        }
+
+        return safeCloneElement(child, {
+          status: 'active',
+          // if it has submenu, the root item cannot be current,
+          // just a link inside the submenu
+          'aria-current': renderSubmenu ? undefined : 'page'
+        })
+      }
+    })
+  }
+
+  render() {
+    const { listLabel, styles } = this.props
+
+    if (!this.childrenArray.length) {
+      return null
+    }
+
+    if (this.context.layout === 'smallViewport') {
+      // in smallViewport mode it is rendered as a Drilldown
+      return null
+    }
+
+    return (
+      <TruncateList
+        {...omitProps(this.props, allowedProps)}
+        key={this.state.key} // rerender if child count changes
+        elementRef={this.handleRef}
+        css={styles?.topNavBarMenuItems}
+        visibleItemsCount={this.state.visibleItemsCount}
+        onUpdate={({ visibleItemsCount }) => {
+          this.setState({ visibleItemsCount })
+        }}
+        renderHiddenItemMenu={(hiddenChildren) =>
+          this.renderHiddenItemsMenu(hiddenChildren as ItemChild[])
+        }
+        {...(styles?.itemSpacing && {
+          itemSpacing: styles.itemSpacing
+        })}
+        aria-label={listLabel}
+      >
+        {this.renderChildren()}
+      </TruncateList>
+    )
+  }
+}
+
+export { TopNavBarMenuItems }
+export default TopNavBarMenuItems