feat(ui-img): rework Img

packages/ui-img/package.json

@@ -29,6 +29,7 @@
     "@instructure/shared-types": "workspace:*",
     "@instructure/ui-dom-utils": "workspace:*",
     "@instructure/ui-react-utils": "workspace:*",
+    "@instructure/ui-themes": "workspace:*",
     "@instructure/ui-view": "workspace:*"
   },
   "devDependencies": {
@@ -67,18 +68,18 @@
       "default": "./es/exports/a.js"
     },
     "./v11_7": {
-      "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"
+      "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/a.ts",
-      "types": "./types/exports/a.d.ts",
-      "import": "./es/exports/a.js",
-      "require": "./lib/exports/a.js",
-      "default": "./es/exports/a.js"
+      "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"
     }
   }
 }

packages/ui-img/src/Img/v2/README.md

@@ -0,0 +1,124 @@
+---
+describes: Img
+---
+
+An accessible image component
+
+```js
+---
+type: example
+---
+<Img src={placeholderImage(250, 250)} />
+```
+
+### Margin and display
+
+Use the `margin` prop to add space around `<Img />`. Setting the `display` prop to `block` makes
+the image a block-level element.
+
+```js
+---
+type: example
+---
+<View textAlign="center" as="div">
+  <Img margin="small" alt="A placeholder image" src={placeholderImage(300, 200)} />
+  <Img margin="small" src={placeholderImage(200, 200)} />
+  <Img display="block" margin="small auto" src={placeholderImage(400, 200)} />
+</View>
+```
+
+### Color overlay
+
+The `overlay` prop accepts parameters for `color`, `opacity`, and `blend`.
+
+```js
+---
+type: example
+---
+  <View textAlign="center" as="div">
+    <Img
+      src={placeholderImage(200, 200)}
+      overlay={{color: '#0374B5', opacity: 9, blend: 'overlay'}}
+      alt="A placeholder image"
+      margin="x-small"
+    />
+    <Img
+      src={placeholderImage(200, 200)}
+      overlay={{color: '#0374B5', opacity: 6, blend: 'multiply'}}
+      alt="A placeholder image"
+      margin="x-small"
+    />
+    <Img
+      src={placeholderImage(200, 200)}
+      overlay={{color: '#0374B5', opacity: 3}}
+      alt="A placeholder image"
+      margin="x-small"
+    />
+  </View>
+```
+
+### Cover
+
+When the `constrain` prop is set to `cover` the image fills the _full_ width and height of its
+containing element, while maintaining the aspect ratio of the source image.
+
+```js
+---
+type: example
+---
+<div style={{width: '66%', height: '11rem'}}>
+  <Img src={avatarSquare} constrain="cover" />
+</div>
+```
+
+### Contain
+
+When the `constrain` prop is set to `contain` the image fits within the width and height of its
+containing element, while maintaining the aspect ratio of the source image.
+
+```js
+---
+type: example
+---
+<View as="div" background="primary-inverse" width="200px" height="200px" textAlign="center">
+  <Img src={avatarPortrait} constrain="contain" />
+</View>
+```
+
+### Grayscale and blur filters
+
+Please note: these should only be used for presentational effects.
+
+```js
+---
+type: example
+---
+  <View textAlign="center" as="div">
+    <Img
+      withGrayscale
+      src={avatarSquare}
+      alt="A placeholder image"
+      margin="x-small"
+    />
+    <Img
+      withBlur
+      src={avatarSquare}
+      alt="A placeholder image"
+      margin="x-small"
+    />
+  </View>
+```
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="a11y" title="Accessibility">
+    <Figure.Item>Contextual images must have alternative text that describes the information or function represented by them</Figure.Item>
+    <Figure.Item>Decorative images that do not present important content, are used for layout or non-informative purposes, and do not appear within a link do not need to be presented to screen readers.  Decorative and spacer images should have null alternative text (alt="")</Figure.Item>
+  </Figure>
+</Guidelines>
+```

packages/ui-img/src/Img/v2/index.tsx

@@ -0,0 +1,139 @@
+/*
+ * 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 { withStyle } from '@instructure/emotion'
+
+import generateStyle from './styles'
+
+import { allowedProps } from './props'
+import type { ImgProps } from './props'
+
+/**
+---
+category: components
+---
+**/
+@withStyle(generateStyle)
+class Img extends Component<ImgProps> {
+  static readonly componentId = 'Img'
+
+  static allowedProps = allowedProps
+  static defaultProps = {
+    alt: '',
+    display: 'inline-block',
+    withGrayscale: false,
+    withBlur: false
+  }
+
+  ref: Element | null = null
+
+  handleRef = (el: Element | null) => {
+    const { elementRef } = this.props
+
+    this.ref = el
+
+    if (typeof elementRef === 'function') {
+      elementRef(el)
+    }
+  }
+
+  componentDidMount() {
+    this.props.makeStyles?.()
+  }
+
+  componentDidUpdate() {
+    this.props.makeStyles?.()
+  }
+
+  render() {
+    const {
+      src,
+      alt,
+      margin,
+      display,
+      overlay,
+      withGrayscale,
+      withBlur,
+      constrain,
+      width,
+      height,
+      elementRef,
+      styles,
+      loading,
+      ...props
+    } = this.props
+
+    const a11yProps = {
+      alt: alt || ''
+    }
+
+    const imageProps = {
+      css: styles?.img,
+      src,
+      loading
+    }
+
+    const containerProps = {
+      ...passthroughProps(props),
+      width,
+      height,
+      margin,
+      display,
+      elementRef: this.handleRef
+    }
+
+    if (overlay) {
+      // if a background image is rendered we add the a11y props on the container element
+      const rootProps = {
+        ...containerProps
+      }
+
+      return (
+        <View {...rootProps} as="span" css={styles?.container} data-cid="Img">
+          {/* eslint-disable-next-line jsx-a11y/alt-text*/}
+          {<img {...imageProps} {...a11yProps} />}
+          {overlay && <span css={styles?.overlay} />}
+        </View>
+      )
+    } else {
+      return (
+        <View
+          {...containerProps}
+          {...imageProps}
+          {...a11yProps}
+          as="img"
+          data-cid="Img"
+        />
+      )
+    }
+  }
+}
+
+export default Img
+export { Img }

packages/ui-img/src/Img/v2/props.ts

@@ -0,0 +1,89 @@
+/*
+ * 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 { OtherHTMLAttributes } from '@instructure/shared-types'
+import type {
+  Spacing,
+  WithStyleProps,
+  ComponentStyle
+} from '@instructure/emotion'
+import type { NewComponentTypes } from '@instructure/ui-themes'
+
+type ImgOwnProps = {
+  src: string
+  alt?: string
+  display?: 'inline-block' | 'block'
+  /**
+   * Gets passed down to  the img component. Same as the native HTML img's loading attribute
+   */
+  loading?: 'eager' | 'lazy'
+  /**
+   * 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
+  /**
+   * Valid values for `opacity` are `0` - `10`. Valid values for `blend` are
+   * `normal` (default), `multiply`, `screen`, `overlay`, and `color-burn`.
+   */
+  overlay?: {
+    color: string
+    opacity: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10
+    blend?: 'normal' | 'multiply' | 'screen' | 'overlay' | 'color-burn'
+  }
+  withGrayscale?: boolean
+  withBlur?: boolean
+  constrain?: 'cover' | 'contain'
+  elementRef?: (element: Element | null) => void
+  height?: string | number
+  width?: string | number
+}
+
+type PropKeys = keyof ImgOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type ImgProps = ImgOwnProps &
+  WithStyleProps<NewComponentTypes['Img'], ImgStyle> &
+  OtherHTMLAttributes<ImgOwnProps>
+
+type ImgStyle = ComponentStyle<'overlay' | 'container' | 'img'>
+const allowedProps: AllowedPropKeys = [
+  'src',
+  'alt',
+  'display',
+  'loading',
+  'margin',
+  'overlay',
+  'withGrayscale',
+  'withBlur',
+  'constrain',
+  'elementRef',
+  'height',
+  'width'
+]
+
+export type { ImgProps, ImgStyle }
+export { allowedProps }