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

package/lib/Avatar/v2/styles.js

@@ -0,0 +1,172 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _emotion = require("@instructure/emotion");
+/*
+ * 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.
+ */
+
+/**
+ * ---
+ * 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, params, sharedTokens) => {
+  const loaded = params.loaded,
+    size = params.size,
+    color = params.color,
+    hasInverseColor = params.hasInverseColor,
+    shape = params.shape,
+    showBorder = params.showBorder,
+    display = params.display,
+    margin = params.margin;
+  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: (0, _emotion.calcSpacingFromShorthand)(margin, {
+        ...sharedTokens.spacing,
+        ...sharedTokens.legacy.spacing
+      })
+    },
+    image: {
+      label: 'avatar__image',
+      width: '100%',
+      height: '100%',
+      objectFit: 'cover',
+      objectPosition: 'center',
+      ...(loaded ? {} : {
+        display: 'none'
+      })
+    }
+  };
+};
+var _default = exports.default = generateStyle;

package/lib/{index.js → exports/a.js}

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 Object.defineProperty(exports, "Avatar", {
   enumerable: true,
   get: function () {
-    return _Avatar.Avatar;
+    return _v.Avatar;
   }
 });
-var _Avatar = require("./Avatar");
+var _v = require("../Avatar/v1");

package/lib/exports/b.js

@@ -0,0 +1,12 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "Avatar", {
+  enumerable: true,
+  get: function () {
+    return _v.Avatar;
+  }
+});
+var _v = require("../Avatar/v2");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-avatar",
-  "version": "11.6.0",
+  "version": "11.6.1-snapshot-129",
   "description": "An image or letters that represents a user.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -15,20 +15,20 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.27.6",
-    "@instructure/ui-icons": "11.6.0",
-    "@instructure/emotion": "11.6.0",
-    "@instructure/shared-types": "11.6.0",
-    "@instructure/ui-react-utils": "11.6.0",
-    "@instructure/ui-view": "11.6.0"
+    "@instructure/emotion": "11.6.1-snapshot-129",
+    "@instructure/ui-icons": "11.6.1-snapshot-129",
+    "@instructure/ui-view": "11.6.1-snapshot-129",
+    "@instructure/shared-types": "11.6.1-snapshot-129",
+    "@instructure/ui-react-utils": "11.6.1-snapshot-129"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "15.0.7",
     "vitest": "^3.2.2",
-    "@instructure/ui-axe-check": "11.6.0",
-    "@instructure/ui-babel-preset": "11.6.0",
-    "@instructure/ui-themes": "11.6.0",
-    "@instructure/ui-color-utils": "11.6.0"
+    "@instructure/ui-axe-check": "11.6.1-snapshot-129",
+    "@instructure/ui-babel-preset": "11.6.1-snapshot-129",
+    "@instructure/ui-color-utils": "11.6.1-snapshot-129",
+    "@instructure/ui-themes": "11.6.1-snapshot-129"
   },
   "peerDependencies": {
     "react": ">=18 <=19"
@@ -38,17 +38,39 @@
   },
   "sideEffects": false,
   "exports": {
-    ".": {
-      "types": "./types/index.d.ts",
-      "import": "./es/index.js",
-      "require": "./lib/index.js",
-      "default": "./es/index.js"
-    },
     "./lib/*": "./lib/*",
     "./es/*": "./es/*",
     "./types/*": "./types/*",
     "./package.json": "./package.json",
-    "./src/*": "./src/*"
+    "./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",

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

@@ -22,7 +22,7 @@
  * SOFTWARE.
  */
 
-import { useStyle } from '@instructure/emotion'
+import { useStyleLegacy as useStyle } from '@instructure/emotion'
 import {
   useState,
   SyntheticEvent,
@@ -32,7 +32,7 @@ import {
   useRef
 } from 'react'
 
-import { View } from '@instructure/ui-view'
+import { View } from '@instructure/ui-view/v11_6'
 import { callRenderProp, passthroughProps } from '@instructure/ui-react-utils'
 import type { AvatarProps } from './props'
 

package/src/Avatar/v2/README.md

@@ -0,0 +1,277 @@
+---
+describes: Avatar
+---
+
+The avatar component can be used to display a user's avatar. When an image src is not supplied the user's initials will display.
+
+Instead of the initials, an SVG icon can be displayed with the `renderIcon` property. **Note: If both `src` and `renderIcon` are provided, the image (`src`) takes priority.**
+
+The avatar can be `circle` _(default)_ or `rectangle`. The component uses flexbox layout and can be displayed as `inline` _(default)_ or `block` using the `display` prop.
+
+```js
+---
+type: example
+readonly: true
+---
+
+<div>
+  <View display="block" padding="small medium" background="primary">
+    <Avatar name="Arthur C. Clarke" />
+    <Avatar name="James Arias" color="accent2" />
+    <Avatar name="Charles Kimball" color="accent3" />
+    <Avatar name="Melissa Reed" color="accent4" />
+    <Avatar name="Heather Wheeler" color="accent5" />
+    <Avatar name="David Herbert" color="accent6" />
+    <Avatar name="Isaac Asimov" color="accent1" />
+  </View>
+  <View display="block" padding="small medium" background="primary">
+    <Avatar name="Arthur C. Clarke" hasInverseColor />
+    <Avatar name="James Arias" color="accent2" hasInverseColor />
+    <Avatar name="Charles Kimball" color="accent3" hasInverseColor />
+    <Avatar name="Melissa Reed" color="accent4" hasInverseColor />
+    <Avatar name="Heather Wheeler" color="accent5" hasInverseColor />
+    <Avatar name="David Herbert" color="accent6" hasInverseColor />
+    <Avatar name="Isaac Asimov" color="accent1" hasInverseColor />
+  </View>
+</div>
+```
+
+### AI Avatar
+
+There is a need for special, `ai avatars`. These have a specific look. You can achieve it the following way
+
+```js
+---
+type: example
+readonly: true
+---
+<View display="block" padding="small medium" background="primary">
+  <Avatar size="xx-small" color="ai" name="AI Assistant" renderIcon={IconAiSolid} />
+  <Avatar size="x-small" color="ai" name="AI Assistant" renderIcon={IconAiSolid} />
+  <Avatar size="small" color="ai" name="AI Assistant" renderIcon={IconAiSolid} />
+  <Avatar size="medium" color="ai" name="AI Assistant" renderIcon={IconAiSolid} />
+  <Avatar size="large" color="ai" name="AI Assistant" renderIcon={IconAiSolid} />
+  <Avatar size="x-large" color="ai" name="AI Assistant" renderIcon={IconAiSolid} />
+  <Avatar size="xx-large" color="ai" name="AI Assistant" renderIcon={IconAiSolid} />
+</View>
+```
+
+### Using Lucide Icons
+
+Lucide icons in Avatar are automatically sized and colored according to the Avatar's `size` and `color` props, so manual adjustments are not needed on the icon itself.
+
+```js
+---
+type: example
+---
+<div>
+  <View display="block" padding="small medium">
+    <Avatar name="User Avatar" size="xx-small" renderIcon={UserInstUIIcon} />
+    <Avatar name="User Avatar" size="x-small" renderIcon={UserInstUIIcon} />
+    <Avatar name="User Avatar" size="small" renderIcon={UserInstUIIcon} />
+    <Avatar name="User Avatar" size="medium" renderIcon={UserInstUIIcon} />
+    <Avatar name="User Avatar" size="large" renderIcon={UserInstUIIcon} />
+    <Avatar name="User Avatar" size="x-large" renderIcon={UserInstUIIcon} />
+    <Avatar name="User Avatar" size="xx-large" renderIcon={UserInstUIIcon} />
+  </View>
+  <View display="block" padding="small medium">
+    <Avatar name="Profile" size="small" color="accent2" renderIcon={<CircleUserInstUIIcon />} />
+    <Avatar name="Group" size="medium" color="accent3" renderIcon={<UsersInstUIIcon />} />
+    <Avatar name="Settings" size="large" color="accent4" renderIcon={<SettingsInstUIIcon />} />
+  </View>
+  <View display="block" padding="small medium">
+    <Avatar name="Profile" size="large" color="accent4" renderIcon={()=><CircleUserInstUIIcon />} />
+    <Avatar name="Group" size="x-large" color="accent5" renderIcon={()=><UsersInstUIIcon />} />
+    <Avatar name="Settings" size="xx-large" color="accent6" renderIcon={()=><SettingsInstUIIcon />} />
+  </View>
+</div>
+```
+
+### Size
+
+The `size` prop allows you to select from `xx-small`, `x-small`, `small`, `medium` _(default)_, `large`, `x-large`, and `xx-large`. Each size has predefined dimensions and typography scales.
+
+```js
+---
+type: example
+---
+<div>
+  <View display="block" padding="small medium">
+    <Avatar name="Arthur C. Clarke" size="xx-small" />
+    <Avatar name="James Arias" size="x-small" />
+    <Avatar name="Charles Kimball" size="small" />
+    <Avatar name="Melissa Reed" size="medium" />
+    <Avatar name="Heather Wheeler" size="large" />
+    <Avatar name="David Herbert" size="x-large" />
+    <Avatar name="Isaac Asimov" size="xx-large" />
+  </View>
+  <View display="block" padding="small medium" background="primary">
+    <Avatar name="Arthur C. Clarke" size="xx-small" src={avatarSquare} />
+    <Avatar name="James Arias" size="x-small" src={avatarSquare} />
+    <Avatar name="Charles Kimball" size="small" src={avatarSquare} />
+    <Avatar name="Melissa Reed" size="medium" src={avatarSquare} />
+    <Avatar name="Heather Wheeler" size="large" src={avatarSquare} />
+    <Avatar name="David Herbert" size="x-large" src={avatarSquare} />
+    <Avatar name="Isaac Asimov" size="xx-large" src={avatarSquare} />
+  </View>
+  <View display="block" padding="small medium">
+    <Avatar name="Arthur C. Clarke" renderIcon={UsersInstUIIcon} size="xx-small" />
+    <Avatar name="James Arias" renderIcon={UsersInstUIIcon} size="x-small" />
+    <Avatar name="Charles Kimball" renderIcon={UsersInstUIIcon} size="small" />
+    <Avatar name="Melissa Reed" renderIcon={UsersInstUIIcon} size="medium" />
+    <Avatar name="Heather Wheeler" renderIcon={UsersInstUIIcon} size="large" />
+    <Avatar name="David Herbert" renderIcon={UsersInstUIIcon} size="x-large" />
+    <Avatar name="Isaac Asimov" renderIcon={UsersInstUIIcon} size="xx-large" />
+  </View>
+</div>
+```
+
+### Colors
+
+The color of the initials and icons can be set with the `color` prop, and it allows you to select from `accent1` _(default)_, `accent2`, `accent3`, `accent4`, `accent5`, `accent6`, and `ai` _(for AI avatars with gradient background)_.
+
+```js
+---
+type: example
+---
+<div>
+  <View display="block" padding="small medium">
+    <Avatar name="Arthur C. Clarke" />
+    <Avatar name="James Arias" color="accent2" />
+    <Avatar name="Charles Kimball" color="accent3" />
+    <Avatar name="Melissa Reed" color="accent4" />
+    <Avatar name="Heather Wheeler" color="accent5" />
+    <Avatar name="David Herbert" color="accent6" />
+    <Avatar name="Isaac Asimov" color="accent1" />
+  </View>
+  <View display="block" padding="small medium">
+    <Avatar renderIcon={UsersInstUIIcon} name="Arthur C. Clarke" />
+    <Avatar renderIcon={UsersInstUIIcon} name="James Arias" color="accent2" />
+    <Avatar renderIcon={UsersInstUIIcon} name="Charles Kimball" color="accent3" />
+    <Avatar renderIcon={UsersInstUIIcon} name="Melissa Reed" color="accent4" />
+    <Avatar renderIcon={UsersInstUIIcon} name="Heather Wheeler" color="accent5" />
+    <Avatar renderIcon={UsersInstUIIcon} name="David Herbert" color="accent6" />
+    <Avatar renderIcon={UsersInstUIIcon} name="Isaac Asimov" color="accent1" />
+  </View>
+</div>
+```
+
+The `hasInverseColor` prop inverts the background color and the text/icon color.
+
+Inverted Avatars have **no border**.
+
+```js
+---
+type: example
+---
+<div>
+  <View display="block" padding="small medium" background="primary">
+    <Avatar name="Arthur C. Clarke" hasInverseColor />
+    <Avatar name="James Arias" color="accent2" hasInverseColor />
+    <Avatar name="Charles Kimball" color="accent3" hasInverseColor />
+    <Avatar name="Melissa Reed" color="accent4" hasInverseColor />
+    <Avatar name="Heather Wheeler" color="accent5" hasInverseColor />
+    <Avatar name="David Herbert" color="accent6" hasInverseColor />
+    <Avatar name="Isaac Asimov" color="accent1" hasInverseColor />
+  </View>
+  <View display="block" padding="small medium" background="primary">
+    <Avatar renderIcon={UsersInstUIIcon} name="Arthur C. Clarke" hasInverseColor />
+    <Avatar renderIcon={UsersInstUIIcon} name="James Arias" color="accent2" hasInverseColor />
+    <Avatar renderIcon={UsersInstUIIcon} name="Charles Kimball" color="accent3" hasInverseColor />
+    <Avatar renderIcon={UsersInstUIIcon} name="Melissa Reed" color="accent4" hasInverseColor />
+    <Avatar renderIcon={UsersInstUIIcon} name="Heather Wheeler" color="accent5" hasInverseColor />
+    <Avatar renderIcon={UsersInstUIIcon} name="David Herbert" color="accent6" hasInverseColor />
+    <Avatar renderIcon={UsersInstUIIcon} name="Isaac Asimov" color="accent1" hasInverseColor />
+  </View>
+</div>
+```
+
+In case you need more control over the color, feel free to use the `themeOverride` prop, and override the default theme variables.
+
+```js
+---
+type: example
+---
+<div>
+  <Avatar name="Isaac Asimov" renderIcon={UsersInstUIIcon} themeOverride={{ accent1TextColor: '#efb410' }} />
+  <Avatar name="Heather Wheeler" color="accent5" themeOverride={{ accent5TextColor: 'magenta' }} />
+  <Avatar name="Charles Kimball" renderIcon={UsersInstUIIcon} hasInverseColor themeOverride={{ textOnColor: 'lightblue', backgroundColor: 'black' }} />
+  <Avatar name="David Herbert" hasInverseColor color="accent5" themeOverride={{ accent5BackgroundColor: '#efb410' }} />
+</div>
+```
+
+### Display
+
+The `display` prop controls whether the avatar is displayed as `inline` _(default)_ or `block`. This affects the CSS display property and layout behavior.
+
+```js
+---
+type: example
+---
+<div>
+  <Text>Inline avatars: </Text>
+  <Avatar name="John Doe" size="small" display="inline" />
+  <Avatar name="Jane Smith" size="small" display="inline" />
+  <Text> are displayed inline with text.</Text>
+
+  <div style={{ marginTop: '1rem' }}>
+    <Text>Block avatars:</Text>
+    <Avatar name="John Doe" size="small" display="block" />
+    <Avatar name="Jane Smith" size="small" display="block" />
+    <Text>stack vertically.</Text>
+  </div>
+</div>
+```
+
+### Border
+
+By default only avatars without an image have borders but you can force it to `always` or `never` show with the `showBorder` prop however you should only use it rarely in very specific occasions (e.g. displaying an avatar in the [SideNavBar](/#SideNavBar))
+
+```js
+---
+type: example
+---
+<div>
+  <Avatar name="Sarah Robinson" src={avatarSquare} showBorder="always" />
+  <Avatar name="Sarah Robinson" renderIcon={UsersInstUIIcon} showBorder="never" />
+</div>
+```
+
+### Priority and Behavior
+
+When both `src` and `renderIcon` props are provided, the **image (`src`) takes priority** and will be displayed instead of the icon. The icon will only be shown as a fallback while the image is loading or if the image fails to load.
+
+```js
+---
+type: example
+---
+<div>
+  <Avatar
+    name="John Doe"
+    src={avatarSquare}
+    renderIcon={UsersInstUIIcon}
+  />
+  <Text>Image takes priority over icon</Text>
+</div>
+```
+
+### Accessibility
+
+Avatars use the `aria-hidden="true"` property and therefore are hidden from screenreaders. Make sure if you are using them stand-alone it's accompanied with [ScreenReaderContent](ScreenReaderContent).
+
+### Guidelines
+
+```js
+---
+type: embed
+---
+<Guidelines>
+  <Figure recommendation="yes" title="Do">
+    <Figure.Item>Ensure the appropriate size is being used for its placement (in a table, stand-alone, etc…)</Figure.Item>
+    <Figure.Item>Use circle variant in Canvas</Figure.Item>
+  </Figure>
+  <Figure recommendation="no" title="Don't">
+    <Figure.Item>Use inline in sentence</Figure.Item>
+  </Figure>
+</Guidelines>
+```