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

package/src/Breadcrumb/v2/README.md

@@ -0,0 +1,141 @@
+---
+describes: Breadcrumb
+---
+
+Breadcrumbs enable users to quickly see their location within a path of navigation.
+Long breadcrumb text will be automatically truncated, ensuring the list always
+remains on a single line.
+
+**Breadcrumbs are best suited for tablet-sized (~768px) screens and larger.**
+For smaller screens, use a [Link](Link) that returns the user to the previous page or view.
+The example below is implemented with [Responsive](Responsive). Resize the browser window to see
+Breadcrumb become a Link at under 768px.
+
+```js
+---
+type: example
+---
+<Responsive
+  query={{
+    tablet: { minWidth: 768 }
+  }}
+>
+  {(props, matches) => {
+    if (matches.includes('tablet')) {
+      return (
+        <Breadcrumb label="breadcrumb">
+          <Breadcrumb.Link href="#">Student Forecast</Breadcrumb.Link>
+          <Breadcrumb.Link href="#">University of Utah</Breadcrumb.Link>
+          <Breadcrumb.Link href="#">University of Utah Colleges</Breadcrumb.Link>
+          <Breadcrumb.Link>College of Life Sciences</Breadcrumb.Link>
+        </Breadcrumb>
+      )
+    } else {
+      return (
+        <Link
+          href="#"
+          variant="standalone"
+          renderIcon={ChevronLeftInstUIIcon}
+        >
+          <TruncateText>University of Utah Colleges</TruncateText>
+        </Link>
+      )
+    }
+  }}
+</Responsive>
+```
+
+Change the `size` prop to control the font-size of the breadcrumbs (default is `medium`).
+
+```js
+---
+type: example
+---
+<div>
+  <Breadcrumb size="small" label="breadcrumb" margin="none none general.spaceXl">
+    <Breadcrumb.Link href="https://instructure.github.io/instructure-ui/">English 204</Breadcrumb.Link>
+      <Breadcrumb.Link
+        onClick={function () {
+          console.log("This Breadcrumb.Link was clicked!")
+        }}
+      >
+        Exploring John Updike
+      </Breadcrumb.Link>
+    <Breadcrumb.Link href="https://instructure.github.io/instructure-ui/">The Rabbit Novels</Breadcrumb.Link>
+    <Breadcrumb.Link>Rabbit Is Rich</Breadcrumb.Link>
+  </Breadcrumb>
+  <View as="div" width="40rem">
+    <Breadcrumb label="breadcrumb" margin="none none general.spaceXl">
+      <Breadcrumb.Link href="https://instructure.github.io/instructure-ui/">English 204</Breadcrumb.Link>
+        <Breadcrumb.Link
+          onClick={function () {
+            console.log("This Breadcrumb.Link was clicked!")
+          }}
+        >
+          Exploring John Updike
+        </Breadcrumb.Link>
+      <Breadcrumb.Link href="https://instructure.github.io/instructure-ui/">The Rabbit Novels</Breadcrumb.Link>
+      <Breadcrumb.Link>Rabbit Is Rich</Breadcrumb.Link>
+    </Breadcrumb>
+  </View>
+  <Breadcrumb size="large" label="breadcrumb">
+    <Breadcrumb.Link href="https://instructure.github.io/instructure-ui/">English 204</Breadcrumb.Link>
+      <Breadcrumb.Link
+        onClick={function () {
+          console.log("This Breadcrumb.Link was clicked!")
+        }}
+      >
+        Exploring John Updike
+      </Breadcrumb.Link>
+    <Breadcrumb.Link href="https://instructure.github.io/instructure-ui/">The Rabbit Novels</Breadcrumb.Link>
+    <Breadcrumb.Link>Rabbit Is Rich</Breadcrumb.Link>
+  </Breadcrumb>
+</div>
+```
+
+### Icons
+
+You can include icons in `Breadcrumb.Link`:
+
+```js
+---
+type: example
+---
+<Breadcrumb label="Breadcrumb with icons">
+  <Breadcrumb.Link renderIcon={<FolderOpenInstUIIcon />} href="#Breadcrumb">Item Bank</Breadcrumb.Link>
+  <Breadcrumb.Link renderIcon={<Clock4InstUIIcon />} onClick={() => {}}>History</Breadcrumb.Link>
+  <Breadcrumb.Link renderIcon={<PlusInstUIIcon />} iconPlacement="end">New Question</Breadcrumb.Link>
+</Breadcrumb>
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Place Breadcrumb near the top of the page</Figure.Item>
+    <Figure.Item>Show hierarchy, not history</Figure.Item>
+    <Figure.Item>Keep Breadcrumb titles short but descriptive</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Use Breadcrumb if you are taking users through a multi-step process</Figure.Item>
+    <Figure.Item>Use Breadcrumb in mobile layouts: use a Link to the previous page/view instead</Figure.Item>
+  </Figure>
+</Guidelines>
+```
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="a11y" title="Accessibility">
+    <Figure.Item>
+    To indicate the current element within a breadcrumb, the <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current">aria-current</a> attribute is used. In this component, aria-current="page" will automatically be applied to the last element, and we recommend that the current page always be the last element in the breadcrumb. If the last element is not the current page, the isCurrentPage property should be applied to the relevant Breadcrumb.Link to ensure compatibility with screen readers.
+    </Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/Breadcrumb/v2/index.tsx

@@ -0,0 +1,157 @@
+/*
+ * 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, Children, Component, ReactElement } from 'react'
+
+import { View } from '@instructure/ui-view/latest'
+import { safeCloneElement } from '@instructure/ui-react-utils'
+
+import { withStyleNew } from '@instructure/emotion'
+import { ChevronRightInstUIIcon } from '@instructure/ui-icons'
+import { BreadcrumbLink } from './BreadcrumbLink/index.js'
+
+import generateStyle from './styles.js'
+
+import { allowedProps } from './props.js'
+import type { BreadcrumbProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+
+@withStyleNew(generateStyle)
+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 = safeCloneElement(
+      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, size } = 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
+        }
+      }
+
+      // Clone child (BreadcrumbLink) and pass size prop
+      const childWithSize = isValidElement(child)
+        ? safeCloneElement(child as ReactElement<any>, { size })
+        : child
+
+      // Map Breadcrumb sizes to icon size tokens
+      const breadcrumbSizeToIconSize = {
+        small: 'sm',
+        medium: 'md',
+        large: 'lg'
+      } as const
+
+      const iconSize = breadcrumbSizeToIconSize[size || 'small']
+
+      return (
+        <>
+          <li css={styles?.crumb} style={inlineStyle}>
+            {!isAriaCurrentSet &&
+            isLastElement &&
+            (child as React.ReactElement<any>).props.isCurrentPage !== false
+              ? this.addAriaCurrent(childWithSize)
+              : childWithSize}
+          </li>
+          {index < numChildren - 1 && (
+            <li aria-hidden="true" css={styles?.separator}>
+              <ChevronRightInstUIIcon size={iconSize} color={'mutedColor'} />
+            </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/v2/props.ts

@@ -0,0 +1,64 @@
+/*
+ * 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 { NewComponentTypes } from '@instructure/ui-themes'
+
+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`, and Spacing token values,
+   * see https://instructure.design/layout-spacing. Apply these values via
+   * familiar CSS-like shorthand. For example, `margin="general.spaceMd auto"`.
+   */
+  margin?: Spacing
+}
+
+type PropKeys = keyof BreadcrumbOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type BreadcrumbProps = BreadcrumbOwnProps &
+  WithStyleProps<ReturnType<NewComponentTypes['Breadcrumb']>, BreadcrumbStyle>
+
+type BreadcrumbStyle = ComponentStyle<'breadcrumb' | 'crumb' | 'separator'>
+
+const allowedProps: AllowedPropKeys = ['children', 'label', 'margin', 'size']
+
+export type { BreadcrumbProps, BreadcrumbStyle }
+export { allowedProps }

package/src/Breadcrumb/v2/styles.ts

@@ -0,0 +1,86 @@
+/*
+ * 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 { 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
+ * @return {Object} The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: ReturnType<NewComponentTypes['Breadcrumb']>,
+  props: BreadcrumbProps
+): BreadcrumbStyle => {
+  const { size } = props
+
+  const gapSizeVariants = {
+    small: componentTheme.gapSm,
+    medium: componentTheme.gapMd,
+    large: componentTheme.gapLg
+  }
+
+  return {
+    breadcrumb: {
+      label: 'breadcrumb',
+      margin: 0,
+      padding: 0,
+      listStyleType: 'none',
+      overflow: 'visible',
+      display: 'flex',
+      alignItems: 'center',
+      gap: gapSizeVariants[size!]
+    },
+    crumb: {
+      label: 'breadcrumb__crumb',
+      boxSizing: 'border-box',
+      display: 'flex',
+      alignItems: 'center',
+
+      // prevent text clipping
+      '[data-cid~="TruncateText"]': {
+        overflow: 'visible',
+
+        // prevent extra spacing after the '...'
+        '& [class*="truncateText__spacer"]': {
+          display: 'inline'
+        }
+      }
+    },
+    separator: {
+      label: 'breadcrumb__separator',
+      boxSizing: 'border-box',
+      display: 'inline-flex',
+      alignItems: 'center',
+      flexShrink: 0
+    }
+  }
+}
+
+export default generateStyle

package/src/exports/a.ts

@@ -0,0 +1,27 @@
+/*
+ * 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.
+ */
+export { Breadcrumb, BreadcrumbLink } from '../Breadcrumb/v1/index.js'
+
+export type { BreadcrumbProps } from '../Breadcrumb/v1/props'
+export type { BreadcrumbLinkProps } from '../Breadcrumb/v1/BreadcrumbLink/props'

package/src/exports/b.ts

@@ -0,0 +1,27 @@
+/*
+ * 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.
+ */
+export { Breadcrumb, BreadcrumbLink } from '../Breadcrumb/v2/index.js'
+
+export type { BreadcrumbProps } from '../Breadcrumb/v2/props'
+export type { BreadcrumbLinkProps } from '../Breadcrumb/v2/BreadcrumbLink/props'

package/tsconfig.build.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../tsconfig.build.json",
+  "compilerOptions": {
+    "outDir": "./types",
+    "composite": true,
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../ui-babel-preset/tsconfig.build.json" },
+    { "path": "../ui-themes/tsconfig.build.json" },
+    { "path": "../emotion/tsconfig.build.json" },
+    { "path": "../shared-types/tsconfig.build.json" },
+    { "path": "../ui-icons/tsconfig.build.json" },
+    { "path": "../ui-link/tsconfig.build.json" },
+    { "path": "../ui-react-utils/tsconfig.build.json" },
+    { "path": "../ui-truncate-text/tsconfig.build.json" },
+    { "path": "../ui-tooltip/tsconfig.build.json" },
+    { "path": "../ui-utils/tsconfig.build.json" },
+    { "path": "../ui-view/tsconfig.build.json" },
+    { "path": "../ui-axe-check/tsconfig.build.json" },
+    { "path": "../ui-scripts/tsconfig.build.json" }
+  ]
+}