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

package/src/Avatar/v2/index.tsx

@@ -0,0 +1,175 @@
+/*
+ * 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 { useStyle } from '@instructure/emotion'
+import { useState, useEffect, forwardRef, SyntheticEvent } from 'react'
+
+import { passthroughProps } from '@instructure/ui-react-utils'
+import { renderIconWithProps } from '@instructure/ui-icons'
+import { AvatarProps, avatarSizeToIconSize } from './props'
+
+import generateStyle from './styles'
+
+const ICON_COLOR_MAP = {
+  accent1: 'accentBlueColor',
+  accent2: 'accentGreenColor',
+  accent3: 'accentRedColor',
+  accent4: 'accentOrangeColor',
+  accent5: 'accentGreyColor',
+  accent6: 'accentAshColor',
+  ai: 'onColor'
+} as const
+
+/**
+---
+category: components
+---
+**/
+const Avatar = forwardRef<HTMLDivElement, AvatarProps>(
+  (props: AvatarProps, ref) => {
+    const {
+      size = 'medium',
+      color = 'accent1',
+      hasInverseColor = false,
+      showBorder = 'auto',
+      shape = 'circle',
+      display = 'inline',
+      onImageLoaded = (_event: SyntheticEvent) => {},
+      src,
+      name,
+      renderIcon,
+      alt,
+      themeOverride,
+      margin
+    } = props
+    const [loaded, setLoaded] = useState(false)
+
+    const styles = useStyle({
+      generateStyle,
+      themeOverride,
+      params: {
+        loaded,
+        size,
+        color,
+        hasInverseColor,
+        shape,
+        src,
+        showBorder,
+        display,
+        margin
+      },
+      componentId: 'Avatar',
+      displayName: 'Avatar'
+    })
+
+    useEffect(() => {
+      // in case the image is unset in an update, show icons/initials again
+      if (loaded && !src) {
+        setLoaded(false)
+      }
+      // Image already loaded (common in SSR)
+      //TODO-rework make this work
+      // if (src && !loaded && imgRef.current && imgRef.current.complete) {
+      //   setLoaded(true)
+      //   onImageLoaded?.()
+      // }
+    }, [loaded, src])
+
+    const makeInitialsFromName = () => {
+      if (!name || typeof name !== 'string' || name.trim().length === 0) {
+        return
+      }
+      const currentName = name.trim()
+
+      if (currentName.match(/\s+/)) {
+        const names = currentName.split(/\s+/)
+        return (names[0][0] + names[names.length - 1][0]).toUpperCase()
+      } else {
+        return currentName[0].toUpperCase()
+      }
+    }
+
+    const renderInitials = () => {
+      return <span aria-hidden="true">{makeInitialsFromName()}</span>
+    }
+
+    const renderImage = () => (
+      <img
+        style={{
+          width: '100%',
+          height: '100%',
+          objectFit: 'cover',
+          objectPosition: 'center',
+          ...(loaded ? {} : { display: 'none' })
+        }}
+        src={src}
+        alt={alt ? alt : ''}
+        onLoad={(event: SyntheticEvent) => {
+          setLoaded(true)
+          onImageLoaded(event)
+        }}
+      />
+    )
+
+    const renderContent = () => {
+      //image in avatar - prioritize image over icon
+      if (src) {
+        return (
+          <>
+            {renderImage()}
+            {loaded ? null : renderInitials()}
+          </>
+        )
+      }
+
+      //icon in avatar
+      if (renderIcon) {
+        const iconSize = avatarSizeToIconSize[size]
+        const iconColor = hasInverseColor ? 'onColor' : ICON_COLOR_MAP[color]
+
+        return renderIconWithProps(renderIcon, iconSize, iconColor)
+      }
+
+      //initials in avatar
+      return renderInitials()
+    }
+
+    return (
+      <div
+        {...passthroughProps({ ...props })}
+        ref={ref}
+        aria-label={alt ? alt : undefined}
+        role={alt ? 'img' : undefined}
+        css={styles?.avatar}
+      >
+        {renderContent()}
+      </div>
+    )
+  }
+)
+
+Avatar.displayName = 'Avatar'
+
+export default Avatar
+export { Avatar }

package/src/Avatar/v2/props.ts

@@ -0,0 +1,137 @@
+/*
+ * 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 { SyntheticEvent } from 'react'
+
+import type {
+  Spacing,
+  ComponentStyle,
+  ThemeOverrideValue
+} from '@instructure/emotion'
+import type {
+  AsElementType,
+  OtherHTMLAttributes,
+  Renderable
+} from '@instructure/shared-types'
+
+const avatarSizeToIconSize = {
+  'xx-small': 'xs',
+  'x-small': 'xs',
+  small: 'sm',
+  medium: 'md',
+  large: 'lg',
+  'x-large': 'xl',
+  'xx-large': '2xl'
+} as const
+
+type AvatarOwnProps = {
+  /**
+   * The name to display. It will be automatically converted to initials.
+   */
+  name: string
+  /**
+   * URL of the image to display as the background image
+   */
+  src?: string
+  /**
+   * Accessible label
+   */
+  alt?: string
+  size?: keyof typeof avatarSizeToIconSize
+  color?:
+    | 'accent1'
+    | 'accent2'
+    | 'accent3'
+    | 'accent4'
+    | 'accent5'
+    | 'accent6'
+    | 'ai'
+  /**
+   * In inverse color mode the background and text/icon colors are inverted
+   */
+  hasInverseColor?: boolean
+  /**
+   * `auto` only shows a border when there is no source image. This prop can force to always or never show that border.
+   */
+  showBorder?: 'auto' | 'always' | 'never'
+  shape?: 'circle' | 'rectangle'
+  display?: 'inline' | 'block'
+  /**
+   * 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="small auto large"`.
+   */
+  margin?: Spacing
+  /**
+   * Callback fired when the avatar image has loaded.
+   * `event` can be `undefined`, if its already loaded when the page renders
+   * (can happen in SSR)
+   */
+  onImageLoaded?: (event?: SyntheticEvent) => void
+  /**
+   * The element type to render as
+   */
+  as?: AsElementType
+  /**
+   * provides a reference to the underlying html root element
+   */
+  elementRef?: (element: Element | null) => void
+  /**
+   * An icon, or function that returns an icon that gets displayed. If the `src` prop is provided, `src` will have priority.
+   * When using Lucide icons, Avatar will automatically pass the appropriate size and color props based on the Avatar's size and color.
+   */
+  renderIcon?: Renderable
+}
+
+export type AvatarState = {
+  loaded: boolean
+}
+
+type PropKeys = keyof AvatarOwnProps
+
+type AllowedPropKeys = Readonly<Array<PropKeys>>
+
+type AvatarProps = AvatarOwnProps & {
+  themeOverride?: ThemeOverrideValue
+} & OtherHTMLAttributes<AvatarOwnProps>
+
+type AvatarStyle = ComponentStyle<'avatar' | 'image'>
+
+const allowedProps: AllowedPropKeys = [
+  'name',
+  'src',
+  'alt',
+  'size',
+  'color',
+  'hasInverseColor',
+  'shape',
+  'margin',
+  'display',
+  'onImageLoaded',
+  'renderIcon',
+  'showBorder'
+]
+
+export type { AvatarProps, AvatarStyle }
+export { allowedProps, avatarSizeToIconSize }

package/src/Avatar/v2/styles.ts

@@ -0,0 +1,194 @@
+/*
+ * 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 { calcSpacingFromShorthand } from '@instructure/emotion'
+import type { NewComponentTypes, SharedTokens } from '@instructure/ui-themes'
+import { AvatarProps, AvatarStyle } from './props'
+
+type StyleParams = {
+  loaded: boolean
+  size: AvatarProps['size']
+  color: AvatarProps['color']
+  hasInverseColor: AvatarProps['hasInverseColor']
+  shape: AvatarProps['shape']
+  src: AvatarProps['src']
+  showBorder: AvatarProps['showBorder']
+  display: AvatarProps['display']
+  margin: AvatarProps['margin']
+}
+/**
+ * ---
+ * private: true
+ * ---
+ * Generates the style object from the theme and provided additional information
+ * @param componentTheme The theme variable object.
+ * @param params Additional parameters to customize the style.
+ * @param sharedTokens Shared token object that stores common values for the theme.
+ * @return The final style object, which will be used in the component
+ */
+const generateStyle = (
+  componentTheme: NewComponentTypes['Avatar'],
+  params: StyleParams,
+  sharedTokens: SharedTokens
+): AvatarStyle => {
+  const {
+    loaded,
+    size,
+    color,
+    hasInverseColor,
+    shape,
+    showBorder,
+    display,
+    margin
+  } = params
+
+  const sizeStyles = {
+    'xx-small': {
+      fontSize: componentTheme.fontSize2xs,
+      borderWidth: componentTheme.borderWidthSm,
+      width: componentTheme.size2xs,
+      height: componentTheme.size2xs
+    },
+    'x-small': {
+      fontSize: componentTheme.fontSizeXs,
+      borderWidth: componentTheme.borderWidthSm,
+      width: componentTheme.sizeXs,
+      height: componentTheme.sizeXs
+    },
+    small: {
+      fontSize: componentTheme.fontSizeSm,
+      borderWidth: componentTheme.borderWidthSm,
+      width: componentTheme.sizeSm,
+      height: componentTheme.sizeSm
+    },
+    medium: {
+      fontSize: componentTheme.fontSizeMd,
+      borderWidth: componentTheme.borderWidthMd,
+      width: componentTheme.sizeMd,
+      height: componentTheme.sizeMd
+    },
+    large: {
+      fontSize: componentTheme.fontSizeLg,
+      borderWidth: componentTheme.borderWidthMd,
+      width: componentTheme.sizeLg,
+      height: componentTheme.sizeLg
+    },
+    'x-large': {
+      fontSize: componentTheme.fontSizeXl,
+      borderWidth: componentTheme.borderWidthMd,
+      width: componentTheme.sizeXl,
+      height: componentTheme.sizeXl
+    },
+    'xx-large': {
+      fontSize: componentTheme.fontSize2xl,
+      borderWidth: componentTheme.borderWidthMd,
+      width: componentTheme.size2xl,
+      height: componentTheme.size2xl
+    }
+  }
+
+  const colorVariants = {
+    accent1: {
+      text: componentTheme.blueTextColor,
+      background: componentTheme.blueBackgroundColor
+    },
+    accent2: {
+      text: componentTheme.greenTextColor,
+      background: componentTheme.greenBackgroundColor
+    },
+    accent3: {
+      text: componentTheme.redTextColor,
+      background: componentTheme.redBackgroundColor
+    },
+    accent4: {
+      text: componentTheme.orangeTextColor,
+      background: componentTheme.orangeBackgroundColor
+    },
+    accent5: {
+      text: componentTheme.greyTextColor,
+      background: componentTheme.greyBackgroundColor
+    },
+    accent6: {
+      text: componentTheme.ashTextColor,
+      background: componentTheme.ashBackgroundColor
+    },
+    ai: {
+      text: componentTheme.textOnColor,
+      background: `linear-gradient(135deg, ${componentTheme.aiTopGradientColor} 0%, ${componentTheme.aiBottomGradientColor} 100%)`
+    }
+  }
+
+  const getBorder = () => {
+    if (showBorder === 'never') {
+      return 'none'
+    }
+    if (showBorder === 'always') {
+      return 'solid'
+    }
+    //if none of the above, so auto
+    if (hasInverseColor || color === 'ai') {
+      return 'none'
+    }
+    return 'solid'
+  }
+
+  return {
+    avatar: {
+      label: 'avatar',
+      boxSizing: 'border-box',
+      border: getBorder(),
+      borderRadius: shape === 'circle' ? '50%' : 0,
+      ...sizeStyles[size!],
+      background:
+        hasInverseColor || color === 'ai'
+          ? colorVariants[color!].background
+          : componentTheme.backgroundColor,
+      display: display === 'inline' ? 'inline-flex' : 'flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      verticalAlign: 'middle',
+      color: hasInverseColor
+        ? componentTheme.textOnColor
+        : colorVariants[color!].text,
+      borderColor: componentTheme.borderColor,
+      fontWeight: componentTheme.fontWeight,
+      overflow: 'hidden',
+      // TODO handle the merging on tokens inside the util
+      margin: calcSpacingFromShorthand(margin, {
+        ...sharedTokens.spacing,
+        ...sharedTokens.legacy.spacing
+      })
+    },
+    image: {
+      label: 'avatar__image',
+      width: '100%',
+      height: '100%',
+      objectFit: 'cover',
+      objectPosition: 'center',
+      ...(loaded ? {} : { display: 'none' })
+    }
+  }
+}
+
+export default generateStyle

package/src/exports/a.ts

@@ -0,0 +1,25 @@
+/*
+ * 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 { Avatar } from '../Avatar/v1'
+export type { AvatarProps } from '../Avatar/v1/props'

package/src/exports/b.ts

@@ -0,0 +1,25 @@
+/*
+ * 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 { Avatar } from '../Avatar/v2'
+export type { AvatarProps } from '../Avatar/v2/props'