@instructure/ui-link 11.6.0 → 11.6.1-snapshot-129

package/src/Link/{index.tsx → v1/index.tsx}

@@ -24,7 +24,7 @@
 
 import { Children, Component } from 'react'
 
-import { View } from '@instructure/ui-view'
+import { View } from '@instructure/ui-view/v11_6'
 import { hasVisibleChildren } from '@instructure/ui-a11y-utils'
 import { isActiveElement, findFocusable } from '@instructure/ui-dom-utils'
 import {
@@ -37,14 +37,14 @@ import {
 import { combineDataCid } from '@instructure/ui-utils'
 import { logWarn as warn } from '@instructure/console'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleLegacy as withStyle } from '@instructure/emotion'
 import generateStyle from './styles'
 import generateComponentTheme from './theme'
 
 import { allowedProps } from './props'
 import type { LinkProps, LinkState, LinkStyleProps } from './props'
 
-import type { ViewOwnProps } from '@instructure/ui-view'
+import type { ViewOwnProps } from '@instructure/ui-view/v11_6'
 
 /**
 ---

package/src/Link/{props.ts → v1/props.ts}

@@ -34,7 +34,7 @@ import type {
   WithStyleProps,
   ComponentStyle
 } from '@instructure/emotion'
-import type { ViewOwnProps } from '@instructure/ui-view'
+import type { ViewOwnProps } from '@instructure/ui-view/v11_6'
 import { Renderable } from '@instructure/shared-types'
 
 type LinkOwnProps = {

package/src/Link/v2/README.md

@@ -0,0 +1,261 @@
+---
+describes: Link
+---
+
+### Where to use Link
+
+`Link` is intended for presenting actions **inline with other content**, such as within headings or sentences. Typically those actions navigate the user to a different view.
+
+```js
+---
+type: example
+---
+<Link href="https://instructure.github.io/instructure-ui/" target="_blank">
+  Link text
+</Link>
+```
+
+### Controlled navigation
+
+Sometimes a simple `Link (<a>)` with an `href` is not enough for navigation and an `onClick` handler is needed. In this case, the recommended approach is the following
+
+```js
+---
+type: example
+---
+<Link
+  variant="standalone"
+  onClick = {(e)=>{
+    e.preventDefault()
+    console.log("do navigation")
+  }}
+  forceButtonRole={false}
+  href="#">Go to places
+</Link>
+```
+
+If neither `href` nor `onClick` is provided, the Link will render as plain text (a `<span>` element) without interactive styling:
+
+```js
+---
+type: example
+---
+<div>
+  <Text>This is a Link with no href or onClick: <Link>I look like plain text</Link></Text>
+</div>
+```
+
+### Size
+
+The `size` prop controls the font size, line height, and icon size, icon gap. Available sizes are `small`, `medium`, and `large`.
+
+```js
+---
+type: example
+---
+<div>
+  <div>
+    <Link renderIcon={<DiamondInstUIIcon />} variant="standalone" href="https://instructure.github.io/instructure-ui/" size="small">
+      Link small
+    </Link>
+  </div>
+  <br />
+  <div>
+    <Link renderIcon={<DiamondInstUIIcon />} variant="standalone" href="https://instructure.github.io/instructure-ui/" size="medium">
+      Link medium
+    </Link>
+  </div>
+  <br />
+  <div>
+    <Link renderIcon={<DiamondInstUIIcon />} variant="standalone" href="https://instructure.github.io/instructure-ui/" size="large">
+      Link large
+    </Link>
+  </div>
+  <br />
+</div>
+```
+
+### Variant
+
+The `variant` prop controls the text decoration and intended use case. Available variants are `inline` (underlined, for use within text) and `standalone` (no underline, for standalone links).
+
+Use the `variant` prop in combination with the `size` prop to control both the appearance and size of the link.
+
+```js
+---
+type: example
+---
+<div>
+  <div>
+    In a line of text you should use the <Link variant="inline" size="medium" renderIcon={<DiamondInstUIIcon />} href="https://instructure.github.io/instructure-ui/">inline</Link> link variant.
+  </div>
+  <br />
+  <div>
+    If the link is standalone (not in a text), use the <code>standalone</code> variant:
+    <Link variant="standalone" size="medium" renderIcon={<DiamondInstUIIcon />} href="https://instructure.github.io/instructure-ui/">standalone</Link>
+  </div>
+</div>
+```
+
+#### Deprecated variant values
+
+**The following variant values are deprecated and will be removed in a future version:**
+
+- `inline-small`
+- `standalone-small`
+
+These deprecated values are still supported for backward compatibility but will trigger console warnings. Please update your code to use the new `variant` + `size` prop combination.
+
+```js
+---
+type: code
+---
+// Deprecated (still works but triggers warning)
+<Link variant="inline-small" href="#">Link</Link>
+<Link variant="standalone-small" href="#">Link</Link>
+
+// Recommended
+<Link variant="inline" size="small" href="#">Link</Link>
+<Link variant="standalone" size="small" href="#">Link</Link>
+```
+
+### Adding margin
+
+Use the `margin` prop to add space to the left or right of the Link. Because
+Link displays `inline`, **top and bottom margin will not work**. If you need
+to add margin to the top or bottom of Link, wrap it inside a `<View />`.
+
+```js
+---
+type: example
+---
+<Text>The quick brown fox <Link href="https://instructure.github.io/instructure-ui/" margin="0 small">jumps</Link> over the lazy dog.</Text>
+```
+
+### Truncating text
+
+Use [TruncateText](TruncateText) to truncate text within Link. Note this will cause Link to display `inline-flex`,
+unless an alternate `display` prop is provided.
+
+```js
+---
+type: example
+---
+<Link
+  onClick={() => console.log('clicked')}
+  renderIcon={<DiamondInstUIIcon />}
+>
+  <TruncateText>{lorem.paragraph()}</TruncateText>
+</Link>
+```
+
+### Using icons
+
+Use the `renderIcon` property to put an [icon](icons) inside a Link. To position the
+icon _after_ the link text, change the `iconPlacement` property to `end`. You can also
+render a Link with just an icon. Don't forget to add text for screen readers, though.
+
+```js
+---
+type: example
+---
+<div>
+  <View as="div" margin="0 0 small">
+    <Link href="https://instructure.design" renderIcon={<DiamondInstUIIcon />}>Icon before text</Link> with the quick brown fox
+  </View>
+  <View as="div" margin="0 0 small">
+    This Link has an icon and displays inline with text. <Link
+      href="https://instructure.design"
+      renderIcon={<DiamondInstUIIcon />}
+      iconPlacement="end"
+    >
+      Icon appears after Link text
+    </Link>. This is more text after the link.
+  </View>
+  <View as="div">
+    This Link consists of only an icon&nbsp;
+    <Link onClick={() => console.log('clicked!')} renderIcon={<DiamondInstUIIcon />}>
+      <ScreenReaderContent>Descriptive text</ScreenReaderContent>
+    </Link>.
+  </View>
+</div>
+```
+
+### Theme overrides
+
+Examples showing how [theme overrides](using-theme-overrides) work for Link:
+
+```js
+---
+type: example
+---
+<div>
+  <InstUISettingsProvider
+    theme={{
+      newTheme: {
+        sharedTokens: {
+          focusOutline: {
+            infoColor: 'pink',
+            width: '0.5rem',
+          }
+        }
+      }
+    }}
+  >
+    <Text>The quick brown fox <Link
+      href="https://instructure.github.io/instructure-ui/"
+      themeOverride={{
+        textColor: 'red',
+        textHoverColor: 'green',
+        fontWeight: 700
+      }}>jumps</Link> over the lazy dog.
+    </Text>
+  </InstUISettingsProvider>
+</div>
+```
+
+```js
+---
+type: example
+---
+<View background="primary-inverse" as="div">
+  <Text color="primary-inverse">The quick brown fox <Link
+    href="https://instructure.github.io/instructure-ui/"
+    color="link"
+    themeOverride={{
+      textColor: 'red',
+      textHoverColor: 'magenta',
+      onColorTextColor: 'orange',
+      onColorTextHoverColor: 'lime',
+      fontWeight: 700
+  }}
+  >jumps</Link> over the lazy dog.</Text>
+  <br />
+  <Text color="primary-inverse">The quick brown fox <Link
+    href="https://instructure.github.io/instructure-ui/"
+    renderIcon={<LogOutInstUIIcon />}
+    color="link-inverse"
+    themeOverride={{
+      textColor: 'red',
+      textHoverColor: 'magenta',
+      onColorTextColor: 'orange',
+      onColorTextHoverColor: 'lime',
+      fontWeight: 700
+  }}
+  >jumps</Link> over the lazy dog.</Text>
+</View>
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="a11y" title="Accessibility">
+    <Figure.Item>Use <code>color="link-inverse"</code> when a Link appears on a dark background to ensure adequate contrast</Figure.Item>
+    <Figure.Item>Links must have a non-empty href attribute to be considered true links and to be accessible to keyboard users</Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/Link/v2/index.tsx

@@ -0,0 +1,321 @@
+/*
+ * 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 { Children, Component } from 'react'
+
+import { View } from '@instructure/ui-view/latest'
+import { hasVisibleChildren } from '@instructure/ui-a11y-utils'
+import { isActiveElement, findFocusable } from '@instructure/ui-dom-utils'
+import {
+  getElementType,
+  getInteraction,
+  matchComponentTypes,
+  passthroughProps
+} from '@instructure/ui-react-utils'
+import { combineDataCid } from '@instructure/ui-utils'
+import { logWarn as warn } from '@instructure/console'
+import { renderIconWithProps } from '@instructure/ui-icons'
+
+import { withStyle } from '@instructure/emotion'
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { LinkProps, LinkState, LinkStyleProps } from './props'
+
+import type { ViewOwnProps } from '@instructure/ui-view/latest'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle)
+class Link extends Component<LinkProps, LinkState> {
+  static readonly componentId = 'Link'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    // Leave interaction default undefined so that `disabled` can also be supplied
+    interaction: undefined,
+    color: 'link',
+    iconPlacement: 'start',
+    forceButtonRole: true
+  } as const
+
+  state = { hasFocus: false }
+
+  get _link() {
+    console.warn(
+      '_link property is deprecated and will be removed in v9, please use ref instead'
+    )
+
+    return this.ref
+  }
+  ref: Element | null = null
+
+  componentDidMount() {
+    this.props.makeStyles?.(this.makeStyleProps())
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.(this.makeStyleProps())
+  }
+
+  makeStyleProps = (): LinkStyleProps & {
+    variant?: LinkProps['variant']
+    size?: LinkProps['size']
+  } => {
+    const { variant: variantProp, size: sizeProp } = this.props
+
+    // Handle deprecated variant values by mapping them to new variant + size props
+    let variant: 'inline' | 'standalone' | undefined = variantProp as any
+    let size = sizeProp
+
+    if (variantProp === 'inline-small' || variantProp === 'standalone-small') {
+      warn(
+        false,
+        `[Link] The variant value "${variantProp}" is deprecated. Use variant="${variantProp.replace(
+          '-small',
+          ''
+        )}" with size="small" instead.`
+      )
+      variant = variantProp.replace('-small', '') as 'inline' | 'standalone'
+      // Only set size from deprecated variant if size prop is not explicitly provided
+      if (!sizeProp) {
+        size = 'small'
+      }
+    } else if (
+      (variantProp === 'inline' || variantProp === 'standalone') &&
+      !sizeProp
+    ) {
+      // When using new variant values without explicit size, default to medium
+      // This maintains the old behavior where 'inline' and 'standalone' were medium-sized
+      size = 'medium'
+    }
+
+    return {
+      containsTruncateText: this.containsTruncateText,
+      hasVisibleChildren: this.hasVisibleChildren,
+      variant,
+      size
+    }
+  }
+
+  handleElementRef = (el: Element | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  handleClick: React.MouseEventHandler<ViewOwnProps> = (event) => {
+    const { onClick } = this.props
+    const { interaction } = this
+
+    if (interaction === 'disabled') {
+      event.preventDefault()
+      event.stopPropagation()
+    } else if (typeof onClick === 'function') {
+      onClick(event)
+    }
+  }
+
+  handleFocus: React.FocusEventHandler<ViewOwnProps> = (event) => {
+    this.setState({ hasFocus: true })
+    if (typeof this.props.onFocus === 'function') {
+      this.props.onFocus(event)
+    }
+  }
+
+  handleBlur: React.FocusEventHandler<ViewOwnProps> = (event) => {
+    this.setState({ hasFocus: false })
+    if (typeof this.props.onBlur === 'function') {
+      this.props.onBlur(event)
+    }
+  }
+
+  get containsTruncateText() {
+    let truncateText = false
+
+    Children.forEach(this.props.children, (child) => {
+      if (child && matchComponentTypes(child, ['TruncateText'])) {
+        truncateText = true
+      }
+    })
+
+    warn(
+      // if display prop is used, warn about icon or TruncateText
+      !truncateText || this.props.display === undefined,
+      '[Link] Using the display property with TruncateText may cause layout issues.'
+    )
+
+    return truncateText
+  }
+
+  get display() {
+    if (this.props.display) {
+      return this.props.display // user-entered display property
+    }
+
+    const { containsTruncateText } = this
+
+    if (this.props.renderIcon) {
+      return containsTruncateText ? 'inline-flex' : 'inline-block'
+    } else {
+      return containsTruncateText ? 'block' : 'auto'
+    }
+  }
+
+  get interaction() {
+    return getInteraction({ props: this.props, interactionTypes: ['disabled'] })
+  }
+
+  get element() {
+    return getElementType(Link, this.props)
+  }
+
+  get focused() {
+    return isActiveElement(this.ref)
+  }
+
+  get focusable() {
+    return findFocusable(this.ref)
+  }
+
+  get hasVisibleChildren() {
+    return hasVisibleChildren(this.props.children)
+  }
+
+  get role() {
+    const { role, forceButtonRole, onClick } = this.props
+
+    if (forceButtonRole) {
+      return onClick && this.element !== 'button' ? 'button' : role
+    }
+
+    return role
+  }
+
+  focus() {
+    this.ref && (this.ref as HTMLElement).focus()
+  }
+
+  renderIcon() {
+    const {
+      display,
+      renderIcon,
+      variant: variantProp,
+      size: sizeProp
+    } = this.props
+
+    warn(
+      // if display prop is used, warn about icon or TruncateText
+      display === undefined,
+      '[Link] Using the display property with an icon may cause layout issues.'
+    )
+
+    // Determine the actual size being used (considering deprecated variants)
+    let size = sizeProp
+    if (variantProp === 'inline-small' || variantProp === 'standalone-small') {
+      size = sizeProp || 'small'
+    } else if (
+      (variantProp === 'inline' || variantProp === 'standalone') &&
+      !sizeProp
+    ) {
+      size = 'medium'
+    }
+
+    // Map Link sizes to icon sizes
+    const linkSizeToIconSize = {
+      small: 'xs',
+      medium: 'sm',
+      large: 'lg'
+    } as const
+
+    const iconSize =
+      linkSizeToIconSize[(size || 'medium') as keyof typeof linkSizeToIconSize]
+
+    return (
+      <span css={this.props.styles?.icon}>
+        {renderIconWithProps(renderIcon, iconSize, undefined)}
+      </span>
+    )
+  }
+
+  render() {
+    const {
+      children,
+      onClick,
+      onMouseEnter,
+      color,
+      href,
+      margin,
+      renderIcon,
+      iconPlacement,
+      ...props
+    } = this.props
+
+    const { interaction } = this
+
+    const isDisabled = interaction === 'disabled'
+
+    const type =
+      this.element === 'button' || this.element === 'input'
+        ? 'button'
+        : undefined
+
+    const tabIndex = this.role === 'button' && !isDisabled ? 0 : undefined
+
+    return (
+      <View
+        {...passthroughProps(props)}
+        elementRef={this.handleElementRef}
+        as={this.element}
+        display={this.display}
+        margin={margin}
+        href={href}
+        onMouseEnter={onMouseEnter}
+        onClick={this.handleClick}
+        onFocus={this.handleFocus}
+        onBlur={this.handleBlur}
+        aria-disabled={isDisabled ? 'true' : undefined}
+        role={this.role}
+        type={type}
+        tabIndex={tabIndex}
+        css={this.props.styles?.link}
+        data-cid={combineDataCid('Link', this.props)}
+      >
+        {renderIcon && iconPlacement === 'start' ? this.renderIcon() : null}
+        {children}
+        {renderIcon && iconPlacement === 'end' ? this.renderIcon() : null}
+      </View>
+    )
+  }
+}
+
+export default Link
+export { Link }