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

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@ohos-ports/instructure-ui-breadcrumb",
+  "version": "11.7.5-beta.0",
+  "description": "A breadcrumb component",
+  "author": "Instructure, Inc. Engineering and Product Design",
+  "module": "./es/index.js",
+  "main": "./lib/index.js",
+  "types": "./types/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohos-ports/ohos-ports.git",
+    "directory": "ports/instructure-ui-breadcrumb/11.7.5"
+  },
+  "homepage": "https://instructure.github.io/instructure-ui/",
+  "bugs": "https://github.com/ohos-ports/ohos-ports/issues",
+  "license": "MIT",
+  "dependencies": {
+    "@babel/runtime": "^7.29.7",
+    "@instructure/emotion": "11.7.5",
+    "@instructure/shared-types": "11.7.5",
+    "@instructure/ui-icons": "11.7.5",
+    "@instructure/ui-link": "11.7.5",
+    "@instructure/ui-react-utils": "11.7.5",
+    "@instructure/ui-themes": "11.7.5",
+    "@instructure/ui-tooltip": "11.7.5",
+    "@instructure/ui-truncate-text": "11.7.5",
+    "@instructure/ui-view": "11.7.5",
+    "@instructure/ui-utils": "11.7.5"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "16.3.2",
+    "vitest": "^4.1.9",
+    "@instructure/ui-babel-preset": "11.7.5",
+    "@instructure/ui-scripts": "11.7.5",
+    "@instructure/ui-axe-check": "11.7.5"
+  },
+  "peerDependencies": {
+    "react": ">=18 <=19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./lib/*": "./lib/*",
+    "./es/*": "./es/*",
+    "./types/*": "./types/*",
+    "./package.json": "./package.json",
+    "./src/*": "./src/*",
+    ".": {
+      "src": "./src/exports/a.ts",
+      "types": "./types/exports/a.d.ts",
+      "import": "./es/exports/a.js",
+      "require": "./lib/exports/a.js",
+      "default": "./es/exports/a.js"
+    },
+    "./v11_6": {
+      "src": "./src/exports/a.ts",
+      "types": "./types/exports/a.d.ts",
+      "import": "./es/exports/a.js",
+      "require": "./lib/exports/a.js",
+      "default": "./es/exports/a.js"
+    },
+    "./v11_7": {
+      "src": "./src/exports/b.ts",
+      "types": "./types/exports/b.d.ts",
+      "import": "./es/exports/b.js",
+      "require": "./lib/exports/b.js",
+      "default": "./es/exports/b.js"
+    },
+    "./latest": {
+      "src": "./src/exports/b.ts",
+      "types": "./types/exports/b.d.ts",
+      "import": "./es/exports/b.js",
+      "require": "./lib/exports/b.js",
+      "default": "./es/exports/b.js"
+    }
+  },
+  "scripts": {
+    "lint": "ui-scripts lint",
+    "lint:fix": "ui-scripts lint --fix",
+    "clean": "ui-scripts clean",
+    "build": "ui-scripts build --modules es,cjs",
+    "build:watch": "pnpm run ts:check -- --watch & ui-scripts build --watch",
+    "build:types": "tsc -p tsconfig.build.json",
+    "ts:check": "tsc -p tsconfig.build.json --noEmit --emitDeclarationOnly false",
+    "postinstall": "node scripts/fix-instructure-exports.js"
+  }
+}

package/scripts/fix-instructure-exports.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * Postinstall fix for Node.js >= 22 (strict exports resolution).
+ *
+ * Problem: @instructure/* packages publish wildcard "folder passthrough"
+ * exports such as:
+ *     "./lib/*": "./lib/*"
+ * and consumers require *directory* subpaths, e.g.
+ *     require("@instructure/ui-svg-images/lib/SVGIcon")
+ * Older Node.js versions resolved such targets to <dir>/index.js with a
+ * deprecation warning (DEP0155-style behaviour); modern Node.js (>= v22,
+ * strict in v26) refuses to resolve exports targets to directories, so the
+ * module graph fails with MODULE_NOT_FOUND / ERR_PACKAGE_PATH_NOT_EXPORTED.
+ *
+ * Fix: for every installed package whose exports contain a passthrough
+ * wildcard (key === value, e.g. "./lib/*"), add explicit mappings
+ *     "./lib/<dir>": "./lib/<dir>/index.js"
+ * for every directory under that base that contains an index file. Exact
+ * string matches always win over wildcard patterns in Node's exports
+ * algorithm, so this restores the legacy directory resolution without
+ * touching any other behaviour.
+ *
+ * Run automatically via the package "postinstall" script.
+ */
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const INDEX_FILES = ['index.js', 'index.cjs', 'index.mjs']
+
+// Collect [relativeDir] pairs for every directory under `baseDir`
+// (recursively) that contains an index file.
+function collectIndexDirs (baseDir, rel = '') {
+  const out = []
+  let entries
+  try {
+    entries = fs.readdirSync(baseDir, { withFileTypes: true })
+  } catch (e) {
+    return out
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const relPath = rel ? `${rel}/${entry.name}` : entry.name
+    const dir = path.join(baseDir, entry.name)
+    for (const idx of INDEX_FILES) {
+      if (fs.existsSync(path.join(dir, idx))) {
+        out.push(relPath)
+        break
+      }
+    }
+    out.push(...collectIndexDirs(dir, relPath))
+  }
+  return out
+}
+
+function patchExports (pkgDir) {
+  const pkgJsonPath = path.join(pkgDir, 'package.json')
+  let pkg
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
+  } catch (e) {
+    return false
+  }
+  if (!pkg.exports || typeof pkg.exports !== 'object') return false
+
+  let changed = false
+  for (const [key, value] of Object.entries(pkg.exports)) {
+    if (typeof value !== 'string') continue
+    // Only handle passthrough wildcards like "./lib/*": "./lib/*"
+    const m = key.match(/^\.\/([^*]+)\*$/)
+    if (!m || value !== key) continue
+    const base = m[1] // e.g. "lib/"
+    const baseDir = path.join(pkgDir, base)
+    for (const rel of collectIndexDirs(baseDir)) {
+      const sub = `./${base}${rel}`
+      if (!(sub in pkg.exports)) {
+        pkg.exports[sub] = `${sub}/index.js`
+        changed = true
+      }
+    }
+  }
+  if (changed) {
+    fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + '\n')
+  }
+  return changed
+}
+
+// Find the nearest node_modules directory by walking up from `startDir`.
+// When this package is installed as a dependency, the consumer's
+// node_modules is an ancestor of __dirname (e.g.
+// <root>/node_modules/@ohos-ports/instructure-ui-breadcrumb/scripts),
+// so we walk up until we find it.
+function findNodeModules (startDir) {
+  let dir = startDir
+  while (true) {
+    const candidate = path.join(dir, 'node_modules')
+    try {
+      if (fs.statSync(candidate).isDirectory()) return candidate
+    } catch (e) {
+      // not found, keep walking up
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+function main () {
+  const nm = findNodeModules(__dirname)
+  if (!nm) {
+    console.log('[fix-instructure-exports] no node_modules, skipping')
+    return
+  }
+  let patched = 0
+  const visit = (dir) => {
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch (e) {
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const full = path.join(dir, entry.name)
+      if (entry.name.startsWith('@')) {
+        visit(full)
+      } else if (fs.existsSync(path.join(full, 'package.json'))) {
+        if (patchExports(full)) patched++
+      }
+    }
+  }
+  visit(nm)
+  console.log(`[fix-instructure-exports] patched ${patched} package(s)`)
+}
+
+main()

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

@@ -0,0 +1,122 @@
+/*
+ * 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/v11_6'
+import { Link } from '@instructure/ui-link/v11_6'
+import { omitProps } from '@instructure/ui-react-utils'
+import { Tooltip } from '@instructure/ui-tooltip/v11_6'
+
+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
+    } = 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}
+          isWithinText={false}
+          elementRef={this.handleRef}
+          forceButtonRole={false}
+          {...(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/v1/BreadcrumbLink/props.ts

@@ -0,0 +1,102 @@
+/*
+ * 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/v11_6'
+import type { LinkProps } from '@instructure/ui-link/v11_6'
+
+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'
+  | 'isWithinText'
+  | '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 }

package/src/Breadcrumb/v1/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="#"
+          isWithinText={false}
+          renderIcon={IconArrowOpenStartLine}
+        >
+          <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 medium">
+    <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 medium">
+      <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={<IconBankLine size="small" />} href="#Breadcrumb">Item Bank</Breadcrumb.Link>
+  <Breadcrumb.Link renderIcon={<IconClockLine size="small" />} onClick={() => {}}>History</Breadcrumb.Link>
+  <Breadcrumb.Link renderIcon={IconPlusLine} 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>
+```