@ohos-ports/instructure-ui-breadcrumb 11.7.5-beta.0

package/src/Breadcrumb/v1/index.tsx

@@ -0,0 +1,143 @@
+/*
+ * 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 {
+  isValidElement,
+  cloneElement,
+  Children,
+  Component,
+  ReactElement
+} from 'react'
+
+import { View } from '@instructure/ui-view/v11_6'
+
+import { withStyle } from '@instructure/emotion'
+import { IconArrowOpenEndSolid } from '@instructure/ui-icons'
+import { BreadcrumbLink } from './BreadcrumbLink/index.js'
+
+import generateStyle from './styles.js'
+import generateComponentTheme from './theme.js'
+
+import { allowedProps } from './props.js'
+import type { BreadcrumbProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+
+@withStyle(generateStyle, generateComponentTheme)
+class Breadcrumb extends Component<BreadcrumbProps> {
+  static displayName = 'Breadcrumb'
+  static readonly componentId = 'Breadcrumb'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    size: 'medium',
+    children: null
+  }
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    this.ref = el
+  }
+
+  addAriaCurrent = (child: React.ReactNode) => {
+    const updatedChild = cloneElement(
+      child as React.ReactElement<{ 'aria-current'?: string }>,
+      {
+        'aria-current': 'page'
+      }
+    )
+    return updatedChild
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  static Link = BreadcrumbLink
+
+  renderChildren() {
+    const { styles, children } = this.props
+    const numChildren = Children.count(children)
+    const inlineStyle = {
+      maxWidth: `${Math.floor(100 / numChildren)}%`
+    }
+    let isAriaCurrentSet = false
+
+    return Children.map(children, (child, index) => {
+      const isLastElement = index === numChildren - 1
+      if (isValidElement(child)) {
+        const isCurrentPage =
+          (child as ReactElement<any>).props.isCurrentPage || false
+        if (isAriaCurrentSet && isCurrentPage) {
+          console.warn(
+            `Warning: Multiple elements with isCurrentPage=true found. Only one element should be set to current.`
+          )
+        }
+        if (isCurrentPage) {
+          isAriaCurrentSet = true
+        }
+      }
+      return (
+        <li css={styles?.crumb} style={inlineStyle}>
+          {!isAriaCurrentSet &&
+          isLastElement &&
+          (child as React.ReactElement<any>).props.isCurrentPage !== false
+            ? this.addAriaCurrent(child)
+            : child}
+          {index < numChildren - 1 && (
+            <IconArrowOpenEndSolid color="auto" css={styles?.separator} />
+          )}
+        </li>
+      )
+    })
+  }
+
+  render() {
+    const { styles } = this.props
+
+    return (
+      <View
+        role="navigation"
+        as="div"
+        margin={this.props.margin}
+        aria-label={this.props.label}
+        elementRef={this.handleRef}
+        data-cid="Breadcrumb"
+      >
+        <ol css={styles?.breadcrumb}>{this.renderChildren()}</ol>
+      </View>
+    )
+  }
+}
+
+export default Breadcrumb
+export { Breadcrumb, BreadcrumbLink }

package/src/Breadcrumb/v1/props.ts

@@ -0,0 +1,63 @@
+/*
+ * 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 {
+  Spacing,
+  WithStyleProps,
+  ComponentStyle
+} from '@instructure/emotion'
+import type { BreadcrumbTheme } from '@instructure/shared-types'
+
+type BreadcrumbOwnProps = {
+  /**
+   * children of type Breadcrumb.Link
+   */
+  children?: React.ReactNode // TODO: oneOf([BreadcrumbLink])
+  /**
+   * An accessible label for the navigation
+   */
+  label: string
+  /**
+   * Sets the font-size of the breadcrumb text
+   */
+  size?: 'small' | 'medium' | 'large'
+  /**
+   * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`,
+   * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via
+   * familiar CSS-like shorthand. For example: `margin="small auto large"`.
+   */
+  margin?: Spacing
+}
+
+type PropKeys = keyof BreadcrumbOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type BreadcrumbProps = BreadcrumbOwnProps &
+  WithStyleProps<BreadcrumbTheme, BreadcrumbStyle>
+
+type BreadcrumbStyle = ComponentStyle<'breadcrumb' | 'crumb' | 'separator'>
+const allowedProps: AllowedPropKeys = ['children', 'label', 'margin', 'size']
+
+export type { BreadcrumbProps, BreadcrumbStyle }
+export { allowedProps }

package/src/Breadcrumb/v1/styles.ts

@@ -0,0 +1,116 @@
+/*
+ * 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 { BreadcrumbTheme } from '@instructure/shared-types'
+import type { BreadcrumbProps, BreadcrumbStyle } 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: BreadcrumbTheme,
+  props: BreadcrumbProps
+): BreadcrumbStyle => {
+  const { size } = props
+
+  const crumbSizeVariants = {
+    small: {
+      fontSize: componentTheme.smallFontSize,
+      paddingInlineEnd: `calc(${componentTheme.smallSeparatorFontSize} * 2)`,
+      paddingInlineStart: 0
+    },
+    medium: {
+      fontSize: componentTheme.mediumFontSize,
+      paddingInlineEnd: `calc(${componentTheme.mediumSeparatorFontSize} * 2)`,
+      paddingInlineStart: 0
+    },
+    large: {
+      fontSize: componentTheme.largeFontSize,
+      paddingInlineEnd: `calc(${componentTheme.largeSeparatorFontSize} * 2)`,
+      paddingInlineStart: 0
+    }
+  }
+
+  const separatorSizeVariants = {
+    small: {
+      fontSize: componentTheme.smallSeparatorFontSize,
+      insetInlineEnd: `calc(${componentTheme.smallSeparatorFontSize} / 2)`,
+      insetInlineStart: 'auto',
+      marginTop: `calc(-1 * (${componentTheme.smallSeparatorFontSize} / 2))`
+    },
+    medium: {
+      fontSize: componentTheme.mediumSeparatorFontSize,
+      insetInlineEnd: `calc(${componentTheme.mediumSeparatorFontSize} / 2)`,
+      insetInlineStart: 'auto',
+      marginTop: `calc(-1 * (${componentTheme.mediumSeparatorFontSize} / 2))`
+    },
+    large: {
+      fontSize: componentTheme.largeSeparatorFontSize,
+      insetInlineEnd: `calc(${componentTheme.largeSeparatorFontSize} / 2)`,
+      insetInlineStart: 'auto',
+      marginTop: `calc(-1 * (${componentTheme.largeSeparatorFontSize} / 2))`
+    }
+  }
+
+  return {
+    breadcrumb: {
+      label: 'breadcrumb',
+      fontFamily: componentTheme.fontFamily,
+      margin: 0,
+      padding: 0,
+      listStyleType: 'none',
+      overflow: 'visible',
+      display: 'flex',
+      alignItems: 'center'
+    },
+    crumb: {
+      label: 'breadcrumb__crumb',
+      boxSizing: 'border-box',
+      position: 'relative',
+      ...crumbSizeVariants[size!],
+
+      '&:last-child': {
+        paddingInlineEnd: 0
+      }
+    },
+    separator: {
+      label: 'breadcrumb__separator',
+
+      boxSizing: 'border-box',
+      position: 'absolute',
+      top: '50%',
+      color: componentTheme.separatorColor,
+      ...separatorSizeVariants[size!]
+    }
+  }
+}
+
+export default generateStyle

package/src/Breadcrumb/v1/theme.ts

@@ -0,0 +1,55 @@
+/*
+ * 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 { BreadcrumbTheme } from '@instructure/shared-types'
+
+/**
+ * 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): BreadcrumbTheme => {
+  const { colors, typography } = theme
+
+  const componentVariables: BreadcrumbTheme = {
+    fontFamily: typography?.fontFamily,
+    separatorColor: colors?.contrasts?.grey4570,
+
+    smallSeparatorFontSize: '0.5rem',
+    smallFontSize: typography?.fontSizeSmall,
+
+    mediumSeparatorFontSize: '0.75rem',
+    mediumFontSize: typography?.fontSizeMedium,
+
+    largeSeparatorFontSize: '1rem',
+    largeFontSize: typography?.fontSizeLarge
+  }
+
+  return {
+    ...componentVariables
+  }
+}
+
+export default generateComponentTheme

package/src/Breadcrumb/v2/BreadcrumbLink/index.tsx

@@ -0,0 +1,123 @@
+/*
+ * 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 { TruncateText } from '@instructure/ui-truncate-text/latest'
+import { Link } from '@instructure/ui-link/latest'
+import { omitProps } from '@instructure/ui-react-utils'
+import { Tooltip } from '@instructure/ui-tooltip/latest'
+
+import { allowedProps } from './props.js'
+import type { BreadcrumbLinkProps, BreadcrumbLinkState } from './props'
+
+/**
+---
+parent: Breadcrumb
+id: Breadcrumb.Link
+---
+**/
+
+class BreadcrumbLink extends Component<
+  BreadcrumbLinkProps,
+  BreadcrumbLinkState
+> {
+  static displayName = 'BreadcrumbLink'
+  static readonly componentId = 'Breadcrumb.Link'
+
+  static allowedProps = allowedProps
+  static defaultProps = {}
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    this.ref = el
+  }
+  constructor(props: BreadcrumbLinkProps) {
+    super(props)
+
+    this.state = {
+      isTruncated: false
+    }
+  }
+  handleTruncation(isTruncated: boolean) {
+    if (isTruncated !== this.state.isTruncated) {
+      this.setState({ isTruncated })
+    }
+  }
+
+  render() {
+    const {
+      children,
+      href,
+      renderIcon,
+      iconPlacement,
+      onClick,
+      onMouseEnter,
+      isCurrentPage,
+      size
+    } = this.props
+    const { isTruncated } = this.state
+    const props = omitProps(this.props, BreadcrumbLink.allowedProps)
+
+    const isInteractive = onClick || href
+    return (
+      <Tooltip
+        renderTip={children}
+        preventTooltip={!isTruncated}
+        // this wraps the achor/button tag in a span and puts the aria-describedby on that instead of the anchor/button tag
+        // to avoid SRs reading the text twice when there is already an aria-label
+        {...(isInteractive && { as: 'span' })}
+      >
+        <Link
+          {...props}
+          href={href}
+          renderIcon={renderIcon}
+          iconPlacement={iconPlacement}
+          onClick={onClick}
+          onMouseEnter={onMouseEnter}
+          variant="standalone"
+          elementRef={this.handleRef}
+          forceButtonRole={false}
+          size={size}
+          {...(isCurrentPage && { 'aria-current': 'page' })}
+          {...(isTruncated && {
+            ...(typeof children === 'string' && { 'aria-label': children }),
+            ...(!isInteractive && { role: 'text' })
+          })}
+          data-cid="BreadcrumbLink"
+        >
+          <TruncateText
+            onUpdate={(isTruncated) => this.handleTruncation(isTruncated)}
+          >
+            <span aria-hidden={isTruncated}>{children}</span>
+          </TruncateText>
+        </Link>
+      </Tooltip>
+    )
+  }
+}
+
+export default BreadcrumbLink
+export { BreadcrumbLink }

package/src/Breadcrumb/v2/BreadcrumbLink/props.ts

@@ -0,0 +1,101 @@
+/*
+ * 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 {
+  PickPropsWithExceptions,
+  OtherHTMLAttributes,
+  Renderable
+} from '@instructure/shared-types'
+import type { ViewOwnProps } from '@instructure/ui-view/latest'
+import type { LinkProps } from '@instructure/ui-link/latest'
+
+type BreadcrumbLinkOwnProps = {
+  /**
+   * Content to render as the crumb, generally should be text.
+   */
+  children: React.ReactNode
+  /**
+   * Link the crumb should direct to; if an href is provided, the crumb will render as a link
+   */
+  href?: string
+  /**
+   * If the Breadcrumb.Link has an onClick prop (and no href), it will render as a button
+   */
+  onClick?: (event: React.MouseEvent<ViewOwnProps, MouseEvent>) => void
+  /**
+   * Fires when the Link is hovered
+   */
+  onMouseEnter?: (event: React.MouseEvent<ViewOwnProps, MouseEvent>) => void
+  /**
+   * Sets the font-size of the breadcrumb text
+   */
+  size?: 'small' | 'medium' | 'large'
+  /**
+   * Add an icon to the Breadcrumb.Link
+   */
+  renderIcon?: Renderable
+  /**
+   * Place the icon before or after the text in the Breadcrumb.Link
+   */
+  iconPlacement?: 'start' | 'end'
+  /**
+   * Whether the page this breadcrumb points to is the current one. If true, it sets aria-current="page".
+   * If this prop is not set to true on any breadcrumb element, the one recieving the aria-current="page" will always be the last element, unless the last element's isCurrentPage prop is explicity set to false.
+   */
+  isCurrentPage?: boolean
+}
+
+type PropKeys = keyof BreadcrumbLinkOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type BreadcrumbLinkProps = PickPropsWithExceptions<
+  LinkProps,
+  | 'children'
+  | 'href'
+  | 'onClick'
+  | 'renderIcon'
+  | 'iconPlacement'
+  | 'elementRef'
+> &
+  BreadcrumbLinkOwnProps &
+  OtherHTMLAttributes<BreadcrumbLinkOwnProps & LinkProps>
+const allowedProps: AllowedPropKeys = [
+  'children',
+  'href',
+  'iconPlacement',
+  'onClick',
+  'onMouseEnter',
+  'renderIcon',
+  'size',
+  'isCurrentPage'
+]
+
+type BreadcrumbLinkState = {
+  isTruncated: boolean
+}
+
+export type { BreadcrumbLinkProps, BreadcrumbLinkState }
+export { allowedProps }