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

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

@@ -24,11 +24,11 @@
 
 import { Component } from 'react'
 
-import { View } from '@instructure/ui-view'
+import { View } from '@instructure/ui-view/v11_6'
 import { passthroughProps, callRenderProp } from '@instructure/ui-react-utils'
 import { IconAiColoredSolid } from '@instructure/ui-icons'
 
-import { withStyle } from '@instructure/emotion'
+import { withStyleLegacy as withStyle } from '@instructure/emotion'
 
 import generateStyle from './styles'
 import generateComponentTheme from './theme'

package/src/Heading/v2/README.md

@@ -0,0 +1,158 @@
+---
+describes: Heading
+---
+
+Heading is a component for creating typographic headings.
+
+### Variant
+
+Variant covers almost all use cases for headings on pages. Their name reflects the places they meant to be used. It takes care of the style of the heading
+
+```js
+---
+type: embed
+---
+<Alert variant="info">
+  <List margin="0 0 medium">
+    <List.Item>For legacy reasons, each <code>variant</code> has a default <code>level</code> set. This is not the recommended way and will be removed in a later major release. Please always specify the <code>level</code>!</List.Item>
+    <List.Item>When <code>variant</code> is set the <code>as</code> prop is ignored</List.Item>
+    <List.Item>A11Y GUIDELINE: There can be only one <code>h1</code> tag in a page</List.Item>
+    <List.Item>A11Y GUIDELINE: <code>h</code> tags can not skip a level, so for example an <code>h1</code> followed by an <code>h3</code> not allowed</List.Item>
+  </List>
+</Alert>
+```
+
+```js
+---
+type: example
+---
+  <div>
+    <Heading variant="titlePageDesktop" level="h1"> titlePageDesktop </Heading><br/>
+    <Heading variant="titlePageMobile" level="h1"> titlePageMobile </Heading><br/>
+    <Heading variant="titleSection" level="h2"> titleSection </Heading><br/>
+    <Heading variant="titleCardSection" level="h2"> titleCardSection </Heading><br/>
+    <Heading variant="titleModule" level="h2"> titleModule </Heading><br/>
+    <Heading variant="titleCardLarge" level="h3"> titleCardLarge </Heading><br/>
+    <Heading variant="titleCardRegular" level="h3"> titleCardRegular </Heading><br/>
+    <Heading variant="titleCardMini" level="h4"> titleCardMini </Heading><br/>
+    <Heading variant="label" level="h5"> label </Heading><br/>
+    <Heading variant="labelInline" level="h6"> labelInline </Heading><br/>
+  </div>
+```
+
+### AI Heading
+
+Pre-configured and with unique styles, the `ai-headings` are used for standardized, ai-related components.
+
+```js
+---
+type: example
+---
+<div style={{display: 'flex', flexDirection: 'column', gap: '24px'}}>
+  <Heading aiVariant="stacked" level="h2">Nutrition Facts</Heading>
+  <Heading aiVariant="horizontal" level="h3">Nutrition Facts</Heading>
+  <Heading aiVariant="iconOnly" level="h4">Nutrition Facts</Heading>
+</div>
+```
+
+### Heading level
+
+What DOM element is output is determined in the following order:
+
+1. (deprecated) If the variant prop is set, then the value of level prop. If variant is set but level is not, <h1>-<h6> based on the variant prop's value.
+2. The value of the `as` prop
+3. The value of the `level` prop
+4. `<h2>`
+
+The `variant` and `level` props sets its appearance in this order.
+
+```js
+---
+type: example
+---
+<div>
+  <Heading level="h1" as="h3" margin="0 0 x-small">This renders as <code>&lt;h3&gt;</code></Heading>
+</div>
+```
+
+### Heading colors
+
+The default color is `primary`, but it can be set to `secondary`, `primary-on`, `secondary-on` or `inherit` via the `color` prop. Note there is an inverse option available as well: `primary-inverse` or `secondary-inverse` (_see inverse example below_).
+
+```js
+---
+type: example
+---
+<div >
+  <div style={{color: '#0084D1'}}>
+    <Heading color="inherit">I inherit my color via the CSS cascade</Heading>
+  </div>
+  <Heading color="primary">I am primary color (default)</Heading>
+  <Heading color="secondary">I am secondary color</Heading>
+  <View background="primary-inverse" as="div">
+    <Heading color="primary-inverse">I am primary-inverse color</Heading>
+    <Heading color="secondary-inverse">I am secondary-inverse color</Heading>
+  </View>
+  <View background="alert" as="div">
+    <Heading color="primary-on">I am primary-on color</Heading>
+    <Heading color="secondary-on">I am secondary-on color</Heading>
+  </View>
+</div>
+```
+
+### Icons
+
+With the `renderIcon` prop, an icon can be rendered before the text.
+
+```js
+---
+type: example
+---
+<div>
+ <Heading renderIcon={<ShieldUserInstUIIcon/>}>I am heading with icon</Heading>
+</div>
+```
+
+### Heading borders
+
+The default is no borders. However, using the `border` prop, you can
+add either `top` or `bottom` borders to your heading.
+
+```js
+---
+type: example
+---
+<div>
+  <Heading margin="0 0 medium" border="bottom">I have a bottom border</Heading>
+  <Heading border="top">I have a top border</Heading>
+</div>
+```
+
+### Ellipsis text overflow
+
+Use [TruncateText](TruncateText) if you need to constrain your
+Heading to a single line (or certain number of lines).
+
+```js
+---
+type: example
+---
+<Heading level="h2">
+  <TruncateText>{lorem.paragraph()}</TruncateText>
+</Heading>
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="a11y" title="Accessibility">
+    <Figure.Item>Each page should always contain one and only one H1</Figure.Item>
+    <Figure.Item>Headings should be used in logical order</Figure.Item>
+    <Figure.Item>Headings should not be used to format text</Figure.Item>
+  </Figure>
+</Guidelines>
+```

package/src/Heading/v2/index.tsx

@@ -0,0 +1,291 @@
+/*
+ * 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 { View } from '@instructure/ui-view/latest'
+import { passthroughProps } from '@instructure/ui-react-utils'
+import { StarsInstUIIcon, renderIconWithProps } from '@instructure/ui-icons'
+
+import { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { HeadingProps } from './props'
+import { AsElementType } from '@instructure/shared-types'
+
+const variantLevels: Record<
+  NonNullable<HeadingProps['variant']>,
+  'h1' | 'h2' | 'h3' | 'h4' | 'h5'
+> = {
+  titlePageDesktop: 'h1',
+  titlePageMobile: 'h1',
+  titleSection: 'h2',
+  titleCardSection: 'h2',
+  titleModule: 'h3',
+  titleCardLarge: 'h4',
+  titleCardRegular: 'h4',
+  titleCardMini: 'h4',
+  label: 'h5',
+  labelInline: 'h5'
+}
+
+const variantToIconSize: Record<
+  NonNullable<HeadingProps['variant']>,
+  'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+> = {
+  titlePageDesktop: '2xl',
+  titlePageMobile: 'xl',
+  titleSection: 'xl',
+  titleCardSection: 'xl',
+  titleModule: 'xl',
+  titleCardLarge: 'xl',
+  titleCardRegular: 'lg',
+  titleCardMini: 'md',
+  label: 'md',
+  labelInline: 'md'
+}
+
+const levelToIconSize: Record<
+  Exclude<HeadingProps['level'], 'reset' | undefined>,
+  'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+> = {
+  h1: '2xl',
+  h2: 'xl',
+  h3: 'xl',
+  h4: 'lg',
+  h5: 'md',
+  h6: 'md'
+}
+
+const variantToAIHorizontalIconSize: Record<
+  NonNullable<HeadingProps['variant']>,
+  'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+> = {
+  titlePageDesktop: '2xl',
+  titlePageMobile: 'xl',
+  titleSection: 'xl',
+  titleCardSection: 'xl',
+  titleModule: 'md',
+  titleCardLarge: 'md',
+  titleCardRegular: 'md',
+  titleCardMini: 'xs',
+  label: 'xs',
+  labelInline: 'xs'
+}
+
+const levelToAIHorizontalIconSize: Record<
+  Exclude<HeadingProps['level'], 'reset' | undefined>,
+  'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+> = {
+  h1: '2xl',
+  h2: 'lg',
+  h3: 'md',
+  h4: 'sm',
+  h5: 'xs',
+  h6: 'xs'
+}
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle)
+class Heading extends Component<HeadingProps> {
+  static readonly componentId = 'Heading'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    children: null,
+    border: 'none',
+    color: 'primary'
+  } as const
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  checkProps() {
+    const { variant, as } = this.props
+    if (variant) {
+      if (as) {
+        console.warn("[Heading]: Don't use 'as' with 'variant' ")
+      }
+    }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+    this.checkProps()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+    this.checkProps()
+  }
+
+  getIconSize(forAIHorizontal = false) {
+    const { variant, level, as } = this.props
+
+    if (variant) {
+      return forAIHorizontal
+        ? variantToAIHorizontalIconSize[variant]
+        : variantToIconSize[variant]
+    }
+    if (level && level !== 'reset') {
+      return forAIHorizontal
+        ? levelToAIHorizontalIconSize[level]
+        : levelToIconSize[level]
+    }
+    if (
+      as &&
+      typeof as === 'string' &&
+      ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(as)
+    ) {
+      const asLevel = as as Exclude<HeadingProps['level'], 'reset' | undefined>
+      return forAIHorizontal
+        ? levelToAIHorizontalIconSize[asLevel]
+        : levelToIconSize[asLevel]
+    }
+    return 'md'
+  }
+
+  renderContent() {
+    const { children, renderIcon, aiVariant } = this.props
+
+    if (renderIcon && !aiVariant) {
+      return (
+        <span css={[this.props.styles?.withIcon]} aria-hidden="true">
+          {renderIconWithProps(renderIcon, this.getIconSize(), 'inherit')}
+          {children}
+        </span>
+      )
+    }
+    if (aiVariant === 'stacked') {
+      return (
+        <span css={[this.props.styles?.withIcon]} aria-hidden="true">
+          <span css={this.props.styles?.igniteAIStacked}>
+            <StarsInstUIIcon color="ai" size="sm" />
+            <span css={this.props.styles?.igniteAI}>IgniteAI</span>
+          </span>
+          {children}
+        </span>
+      )
+    }
+    if (aiVariant === 'horizontal') {
+      return (
+        <span css={this.props.styles?.withIcon} aria-hidden="true">
+          <span css={this.props.styles?.igniteAIHorizontal}>
+            <StarsInstUIIcon color="ai" size={this.getIconSize(true)} />
+            <span css={this.props.styles?.igniteAI}>IgniteAI</span>
+          </span>
+          {children}
+        </span>
+      )
+    }
+    if (aiVariant === 'iconOnly') {
+      return (
+        <span css={this.props.styles?.withIcon} aria-hidden="true">
+          <StarsInstUIIcon color="ai" size={this.getIconSize(true)} />
+          {children}
+        </span>
+      )
+    }
+    return children
+  }
+
+  //overriding default screen reader functionality is needed to read spans in h tags correctly
+  getAriaLabel() {
+    const { aiVariant, children, renderIcon } = this.props
+    if (aiVariant === 'stacked' || aiVariant === 'horizontal') {
+      return `IgniteAI, ${children}`
+    }
+    if (aiVariant === 'iconOnly' || renderIcon) {
+      return `${children}`
+    }
+    return undefined
+  }
+
+  render() {
+    const {
+      border,
+      children,
+      color,
+      level,
+      margin,
+      elementRef,
+      makeStyles,
+      variant,
+      ...props
+    } = this.props
+
+    let ElementType: AsElementType = 'h2'
+    if (variant) {
+      // TODO deprecated, remove. `variant` should not set DOM level
+      if (level) {
+        if (level === 'reset') {
+          ElementType = 'span'
+        } else {
+          ElementType = level
+        }
+      } else {
+        ElementType = variantLevels[variant]
+      }
+    } else if (props.as) {
+      ElementType = props.as
+    } else if (level) {
+      if (level === 'reset') {
+        ElementType = 'span'
+      } else {
+        ElementType = level
+      }
+    }
+    return (
+      <View
+        aria-label={this.getAriaLabel()}
+        {...passthroughProps(props)}
+        css={this.props.styles?.heading}
+        as={ElementType}
+        elementRef={this.handleRef}
+        margin={margin}
+        data-cid="Heading"
+      >
+        {this.renderContent()}
+      </View>
+    )
+  }
+}
+
+export default Heading
+export { Heading }

package/src/Heading/v2/props.ts

@@ -0,0 +1,133 @@
+/*
+ * 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 {
+  AsElementType,
+  HeadingTheme,
+  OtherHTMLAttributes,
+  Renderable
+} from '@instructure/shared-types'
+import type {
+  Spacing,
+  WithStyleProps,
+  ComponentStyle
+} from '@instructure/emotion'
+
+type HeadingLevel<U extends keyof React.JSX.IntrinsicElements> = U
+
+type HeadingOwnProps = {
+  /**
+   * transforms heading into an `ai` variant
+   */
+  aiVariant?: 'stacked' | 'horizontal' | 'iconOnly'
+  /**
+   * The text content of the Heading
+   */
+  children?: React.ReactNode // TODO: childrenOrValue or is it even needed?
+  /**
+   * Add a top- or bottom-border to the Heading
+   */
+  border?: 'none' | 'top' | 'bottom'
+  /**
+   * The font color to render, NOTE: `ai` color is deprecated. Use the `aiVariant` prop instead
+   */
+  color?:
+    | 'primary'
+    | 'secondary'
+    | 'primary-inverse'
+    | 'secondary-inverse'
+    | 'inherit'
+    | 'primary-on'
+    | 'secondary-on'
+    | 'ai'
+  /**
+   * The level of the heading in the DOM: h1 is largest; h6 is smallest.
+   */
+  level?: HeadingLevel<'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'> | 'reset'
+  /**
+   * What DOM element is output is determined in the following order:
+   * 1. (deprecated) If `variant` is set, then use the `level` prop, if that's
+   * not set use `<h1>`-`<h6>` based on the `variant` prop's value
+   * 2. The value of the `as` prop
+   * 3. The value of the `level` prop
+   * 4. `<h2>`
+   */
+  as?: AsElementType
+  /**
+   * 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
+  /**
+   * Provides a ref to the underlying HTML element
+   */
+  elementRef?: (element: Element | null) => void
+  /**
+   * An icon, or function that returns an icon that gets displayed before the text.
+   */
+  renderIcon?: Renderable
+  /**
+   * Sets appearance of the heading. Will also set its heading level, if not
+   * specified by the `level` prop (deprecated, not recommended!)
+   */
+  variant?:
+    | 'titlePageDesktop'
+    | 'titlePageMobile'
+    | 'titleSection'
+    | 'titleCardSection'
+    | 'titleModule'
+    | 'titleCardLarge'
+    | 'titleCardRegular'
+    | 'titleCardMini'
+    | 'label'
+    | 'labelInline'
+}
+
+type PropKeys = keyof HeadingOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type HeadingProps = HeadingOwnProps &
+  WithStyleProps<HeadingTheme, HeadingStyle> &
+  OtherHTMLAttributes<HeadingOwnProps>
+
+type HeadingStyle = ComponentStyle<
+  'heading' | 'igniteAI' | 'igniteAIStacked' | 'igniteAIHorizontal' | 'withIcon'
+>
+const allowedProps: AllowedPropKeys = [
+  'aiVariant',
+  'border',
+  'children',
+  'color',
+  'level',
+  'as',
+  'margin',
+  'elementRef',
+  'variant'
+]
+
+export type { HeadingProps, HeadingStyle }
+export { allowedProps }