@carrier-dpx/air-react-library 0.7.20 → 0.7.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carrier-dpx/air-react-library",
-  "version": "0.7.20",
+  "version": "0.7.22",
   "description": "Air web React component library for Figma Make",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/components/Avatar/Avatar.figma.tsx

@@ -0,0 +1,105 @@
+/**
+ * Figma Code Connect Configuration for Avatar Component
+ * 
+ * Figma URL: https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=6587-47403
+ * 
+ * Figma Properties:
+ * - variant (circle, rounded)
+ * - size (large: 48px, medium: 40px, small: 32px, xsmall: 24px, micro: 20px)
+ * - type (image, letter, icon)
+ * - ✏️ Letter (text property) - layer name "Letter"
+ */
+
+import figma from "@figma/code-connect";
+import Avatar from "./Avatar";
+import Icon from "../Icon";
+
+figma.connect(
+  Avatar,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=6587-47403",
+  {
+    props: {
+      /**
+       * VARIANT MAPPING
+       * Maps Figma's "variant" property to React's "variant" prop
+       * Figma: circle → React: "circular"
+       * Figma: rounded → React: "rounded"
+       */
+      variant: figma.enum("variant", {
+        circle: "circular",
+        rounded: "rounded",
+      }),
+
+      /**
+       * SIZE MAPPING
+       * Maps Figma's "size" property to React's "size" prop
+       * Figma: large (48px), medium (40px), small (32px), xsmall (24px), micro (20px)
+       */
+      size: figma.enum("size", {
+        large: "large",
+        medium: "medium",
+        small: "small",
+        xsmall: "xsmall",
+        micro: "micro",
+      }),
+
+      /**
+       * TYPE MAPPING
+       * Maps Figma's "type" property to determine how Avatar is rendered
+       * - image: uses src prop
+       * - letter: uses children with text from "✏️ Letter"
+       * - icon: uses children with Icon component
+       */
+      type: figma.enum("type", {
+        image: "image",
+        letter: "letter",
+        icon: "icon",
+      }),
+
+      /**
+       * LETTER TEXT
+       * Maps text property "✏️ Letter" from layer "Letter"
+       * Used when type="letter"
+       */
+      letter: figma.string("✏️ Letter"),
+
+      /**
+       * ICON NESTED PROPERTIES
+       * Access Icon's fontSize and SVG through nested properties
+       * Used when type="icon"
+       */
+      icon: figma.nestedProps("Icon", {
+        fontSize: figma.enum("fontSize", {
+          large: "large",
+          medium: "medium",
+          small: "small",
+          xsmall: "xsmall",
+        }),
+        children: figma.instance("SVG"),
+      }),
+    },
+
+    /**
+     * EXAMPLE CODE TEMPLATE
+     * Shows how Avatar should be used based on type
+     */
+    example: ({ variant, size, type, letter, icon }) => {
+      if (type === "icon") {
+        return (
+          <Avatar variant={variant} size={size}>
+            <Icon fontSize={icon.fontSize}>
+              {icon.children}
+            </Icon>
+          </Avatar>
+        );
+      }
+      
+      // Default to letter type (or image if src is provided via sx)
+      return (
+        <Avatar variant={variant} size={size}>
+          {letter}
+        </Avatar>
+      );
+    },
+  }
+);

package/src/components/Avatar/Avatar.tsx

@@ -0,0 +1,111 @@
+import { forwardRef } from "react";
+
+import MuiAvatar, { AvatarProps as MuiAvatarProps } from "@mui/material/Avatar";
+import { blueGrey } from "@mui/material/colors";
+import { CSSObject, styled } from "@mui/material/styles";
+
+import { styleTokens } from "../theme/constants/styleTokens";
+import { getDisplayStringForAvatar } from "../utils/DataDisplayUtils";
+import { getSxStyles } from "../utils/styles";
+
+export interface AvatarProps extends MuiAvatarProps {
+  variant?: "circular" | "rounded";
+  /**
+   * Size of the Avatar
+   * - large: 48px
+   * - medium: 40px
+   * - small: 32px
+   * - xsmall: 24px
+   * - micro: 20px
+   */
+  size?: "large" | "medium" | "small" | "xsmall" | "micro";
+}
+
+/** The Avatar component represents a unique user or entity through a custom image, initials or icon.
+ *
+ * // Default import
+ * import Avatar from '@carrier-dpx/air-react-library/Avatar'
+ *
+ * // Named import
+ * import { Avatar } from '@carrier-dpx/air-react-library'
+ */
+
+const MuiAvatarStyled = styled(MuiAvatar)({
+  "&.MuiAvatar-rounded": {
+    borderRadius: styleTokens.borderRadius.large,
+  },
+});
+
+const Avatar = forwardRef<HTMLDivElement, AvatarProps>(
+  ({ children, sx, size = "medium", ...rest }, ref) => {
+    const getSize = () => {
+      switch (size) {
+        case "large":
+          return "48px";
+        case "medium":
+          return "40px";
+        case "small":
+          return "32px";
+        case "xsmall":
+          return "24px";
+        case "micro":
+          return "20px";
+        default:
+          return "40px";
+      }
+    };
+
+    const getFontSize = () => {
+      switch (size) {
+        case "large":
+          return "18px";
+        case "medium":
+          return "16px";
+        case "small":
+          return "14px";
+        case "xsmall":
+          return "12px";
+        case "micro":
+          return "10px";
+        default:
+          return "16px";
+      }
+    };
+
+    const avatarSize = getSize();
+    const isLargeVariant = size === "large";
+
+    return (
+      <MuiAvatarStyled
+        sx={(theme) => {
+          const resolvedSx = (getSxStyles(theme, sx) ?? {}) as CSSObject;
+          
+          return {
+            backgroundColor: blueGrey[500],
+            cursor: "default",
+            fontSize: getFontSize(),
+            fontWeight: 600,
+            width: avatarSize,
+            height: avatarSize,
+            ...(isLargeVariant && {
+              "& .MuiSvgIcon-root": {
+                fontSize: "24px",
+              },
+            }),
+            ...resolvedSx,
+          } as CSSObject;
+        }}
+        {...rest}
+        ref={ref}
+      >
+        {typeof children === "string"
+          ? getDisplayStringForAvatar(children)
+          : children}
+      </MuiAvatarStyled>
+    );
+  }
+);
+
+Avatar.displayName = "Avatar";
+
+export default Avatar;

package/src/components/Avatar/AvatarGroup.figma.tsx

@@ -0,0 +1,60 @@
+/**
+ * Figma Code Connect Configuration for AvatarGroup Component
+ * 
+ * Figma URL: https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=15889-77636
+ * 
+ * Figma Properties:
+ * - spacing (small, medium)
+ * - size (large: 48px, medium: 40px, small: 32px, xsmall: 24px)
+ */
+
+import figma from "@figma/code-connect";
+import AvatarGroup from "./AvatarGroup";
+import Avatar from "./Avatar";
+
+figma.connect(
+  AvatarGroup,
+  "https://www.figma.com/design/vkoHdM6rchIhH9IWetZeP0/Air--Components?node-id=15889-77636",
+  {
+    props: {
+      /**
+       * SPACING MAPPING
+       * Maps Figma's "spacing" property to React's "spacing" prop
+       * Figma: small, medium
+       */
+      spacing: figma.enum("spacing", {
+        small: "small",
+        medium: "medium",
+      }),
+
+      /**
+       * SIZE MAPPING
+       * Maps Figma's "size" property - size is applied to Avatar children, not the group
+       * Figma: large (48px), medium (40px), small (32px), xsmall (24px)
+       */
+      size: figma.enum("size", {
+        large: "large",
+        medium: "medium",
+        small: "small",
+        xsmall: "xsmall",
+      }),
+
+      /**
+       * CHILDREN
+       * Maps Avatar instances within the AvatarGroup
+       */
+      children: figma.children("Avatar"),
+    },
+
+    /**
+     * EXAMPLE CODE TEMPLATE
+     * Shows how AvatarGroup should be used with Avatar children
+     * Note: size prop is passed to individual Avatar components, not the group
+     */
+    example: ({ spacing, size, children }) => (
+      <AvatarGroup spacing={spacing}>
+        {children}
+      </AvatarGroup>
+    ),
+  }
+);

package/src/components/Avatar/AvatarGroup.tsx

@@ -0,0 +1,45 @@
+import { forwardRef } from "react";
+
+import MuiAvatarGroup, {
+  AvatarGroupProps as MuiAvatarGroupProps,
+} from "@mui/material/AvatarGroup";
+import { styled } from "@mui/material/styles";
+
+export interface AvatarGroupProps extends MuiAvatarGroupProps {
+  variant?: "circular";
+}
+
+/** The AvatarGroup component represents a set of unique users or entities through custom images, initials or icons.
+ *
+ * // Default import
+ * import AvatarGroup from '@carrier-dpx/air-react-library/Avatar'
+ *
+ * // Named import
+ * import { AvatarGroup } from '@carrier-dpx/air-react-library'
+ */
+
+const MuiAvatarGroupStyled = styled(MuiAvatarGroup)<AvatarGroupProps>(
+  ({ spacing, theme }) => ({
+    ...(spacing === "small" && {
+      ".MuiAvatarGroup-avatar": {
+        marginLeft: "-12px !important",
+        ":last-child": {
+          marginLeft: "0px!important",
+        },
+      },
+    }),
+    "& .MuiAvatarGroup-avatar": {
+      fontWeight: 600,
+      fontSize: "16px",
+      border: `2px solid ${theme.palette.base?.background.paper}`,
+    },
+  })
+);
+
+const AvatarGroup = forwardRef<unknown, AvatarGroupProps>((props, ref) => {
+  return <MuiAvatarGroupStyled {...props} ref={ref} />;
+});
+
+AvatarGroup.displayName = "AvatarGroup";
+
+export default AvatarGroup;

package/src/components/Avatar/index.ts

@@ -0,0 +1,9 @@
+// Avatar component family exports
+export { default } from "./Avatar";
+export { default as Avatar } from "./Avatar";
+export * from "./Avatar";
+export type { AvatarProps } from "./Avatar";
+
+export { default as AvatarGroup } from "./AvatarGroup";
+export * from "./AvatarGroup";
+export type { AvatarGroupProps } from "./AvatarGroup";

package/src/components/utils/DataDisplayUtils.ts

@@ -0,0 +1,24 @@
+/**
+ * Get display string for Avatar component
+ * Formats a string (name, initials, etc.) for display in Avatar
+ */
+export const getDisplayStringForAvatar = (input: string): string => {
+  if (!input) return "";
+  
+  // If it's already initials (2-3 characters), return as-is
+  if (input.length <= 3 && input.split(" ").length === 1) {
+    return input.toUpperCase();
+  }
+  
+  // Extract initials from name
+  const words = input.trim().split(/\s+/);
+  if (words.length >= 2) {
+    // First letter of first word + first letter of last word
+    return (words[0][0] + words[words.length - 1][0]).toUpperCase();
+  } else if (words.length === 1 && words[0].length > 0) {
+    // Single word - take first 2 characters
+    return words[0].substring(0, 2).toUpperCase();
+  }
+  
+  return input.toUpperCase();
+};

package/src/index.ts

@@ -28,6 +28,8 @@ export { default as Toolbar } from "./components/Toolbar";
 export type { ToolbarProps } from "./components/Toolbar";
 export { default as IconButton } from "./components/IconButton";
 export type { IconButtonProps } from "./components/IconButton";
+export { default as Avatar, AvatarGroup } from "./components/Avatar";
+export type { AvatarProps, AvatarGroupProps } from "./components/Avatar";
 export * from "./components/theme";
 
 // Demo Icons - exported from main index to avoid deep-path imports