base

plane-src/packages/ui/src/avatar/avatar-group.tsx

@@ -0,0 +1,97 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import React from "react";
+// ui
+import { Tooltip } from "@plane/propel/tooltip";
+// helpers
+import { cn } from "../utils";
+// types
+import type { TAvatarSize } from "./helper";
+import { getSizeInfo, isAValidNumber } from "./helper";
+
+type Props = {
+  /**
+   * The children of the avatar group.
+   * These should ideally should be `Avatar` components
+   */
+  children: React.ReactNode;
+  /**
+   * The maximum number of avatars to display.
+   * If the number of children exceeds this value, the additional avatars will be replaced by a count of the remaining avatars.
+   * @default 2
+   */
+  max?: number;
+  /**
+   * Whether to show the tooltip or not
+   * @default true
+   */
+  showTooltip?: boolean;
+  /**
+   * The size of the avatars
+   * Possible values: "sm", "md", "base", "lg"
+   * @default "md"
+   */
+  size?: TAvatarSize;
+};
+
+export function AvatarGroup(props: Props) {
+  const { children, max = 2, showTooltip = true, size = "md" } = props;
+
+  // calculate total length of avatars inside the group
+  const totalAvatars = React.Children.toArray(children).length;
+
+  // if avatars are equal to max + 1, then we need to show the last avatar as well, if avatars are more than max + 1, then we need to show the count of the remaining avatars
+  const maxAvatarsToRender = totalAvatars <= max + 1 ? max + 1 : max;
+
+  // slice the children to the maximum number of avatars
+  const avatars = React.Children.toArray(children).slice(0, maxAvatarsToRender);
+
+  // assign the necessary props from the AvatarGroup component to the Avatar components
+  const avatarsWithUpdatedProps = avatars.map((avatar) => {
+    const updatedProps: Partial<Props> = {
+      showTooltip,
+      size,
+    };
+
+    return React.cloneElement(avatar as React.ReactElement, updatedProps);
+  });
+
+  // get size details based on the size prop
+  const sizeInfo = getSizeInfo(size);
+
+  return (
+    <div className={cn("flex", sizeInfo.spacing)}>
+      {avatarsWithUpdatedProps.map((avatar, index) => (
+        <div key={index} className="rounded-full border border-subtle-1">
+          {avatar}
+        </div>
+      ))}
+      {maxAvatarsToRender < totalAvatars && (
+        <Tooltip tooltipContent={`${totalAvatars} total`} disabled={!showTooltip}>
+          <div
+            className={cn(
+              "grid place-items-center rounded-full border border-subtle-1 bg-accent-subtle text-9 text-accent-primary",
+              {
+                [sizeInfo.avatarSize]: !isAValidNumber(size),
+              }
+            )}
+            style={
+              isAValidNumber(size)
+                ? {
+                    width: `${size}px`,
+                    height: `${size}px`,
+                  }
+                : {}
+            }
+          >
+            +{totalAvatars - max}
+          </div>
+        </Tooltip>
+      )}
+    </div>
+  );
+}

plane-src/packages/ui/src/avatar/avatar.stories.tsx

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import type { Meta, StoryObj } from "@storybook/react";
+import { Avatar } from "./avatar";
+
+const meta: Meta<typeof Avatar> = {
+  title: "Avatar",
+  component: Avatar,
+};
+
+export default meta;
+type Story = StoryObj<typeof Avatar>;
+
+export const Default: Story = {
+  args: { name: "John Doe" },
+};
+
+export const Large: Story = {
+  args: { name: "John Doe" },
+};

plane-src/packages/ui/src/avatar/avatar.tsx

@@ -0,0 +1,111 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+// ui
+import { Tooltip } from "@plane/propel/tooltip";
+// helpers
+import { cn } from "../utils";
+import type { TAvatarSize } from "./helper";
+import { getBorderRadius, getSizeInfo, isAValidNumber } from "./helper";
+
+type Props = {
+  /**
+   * The name of the avatar which will be displayed on the tooltip
+   */
+  name?: string;
+  /**
+   * The background color if the avatar image fails to load
+   */
+  fallbackBackgroundColor?: string;
+  /**
+   * The text to display if the avatar image fails to load
+   */
+  fallbackText?: string;
+  /**
+   * The text color if the avatar image fails to load
+   */
+  fallbackTextColor?: string;
+  /**
+   * Whether to show the tooltip or not
+   * @default true
+   */
+  showTooltip?: boolean;
+  /**
+   * The size of the avatars
+   * Possible values: "sm", "md", "base", "lg"
+   * @default "md"
+   */
+  size?: TAvatarSize;
+  /**
+   * The shape of the avatar
+   * Possible values: "circle", "square"
+   * @default "circle"
+   */
+  shape?: "circle" | "square";
+  /**
+   * The source of the avatar image
+   */
+  src?: string;
+  /**
+   * The custom CSS class name to apply to the component
+   */
+  className?: string;
+};
+
+export function Avatar(props: Props) {
+  const {
+    name,
+    fallbackBackgroundColor,
+    fallbackText,
+    fallbackTextColor,
+    showTooltip = true,
+    size = "md",
+    shape = "circle",
+    src,
+    className = "",
+  } = props;
+
+  // get size details based on the size prop
+  const sizeInfo = getSizeInfo(size);
+
+  return (
+    <Tooltip tooltipContent={fallbackText ?? name ?? "?"} disabled={!showTooltip}>
+      <div
+        className={cn("grid place-items-center overflow-hidden", getBorderRadius(shape), {
+          [sizeInfo.avatarSize]: !isAValidNumber(size),
+        })}
+        style={
+          isAValidNumber(size)
+            ? {
+                height: `${size}px`,
+                width: `${size}px`,
+              }
+            : {}
+        }
+        tabIndex={-1}
+      >
+        {src ? (
+          <img src={src} className={cn("h-full w-full", getBorderRadius(shape), className)} alt={name} />
+        ) : (
+          <div
+            className={cn(
+              sizeInfo.fontSize,
+              "grid h-full w-full place-items-center",
+              getBorderRadius(shape),
+              className
+            )}
+            style={{
+              backgroundColor: fallbackBackgroundColor ?? "#028375",
+              color: fallbackTextColor ?? "#ffffff",
+            }}
+          >
+            {name?.[0]?.toUpperCase() ?? fallbackText ?? "?"}
+          </div>
+        )}
+      </div>
+    </Tooltip>
+  );
+}

plane-src/packages/ui/src/avatar/helper.tsx

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+export type TAvatarSize = "sm" | "md" | "base" | "lg" | number;
+
+/**
+ * Get the size details based on the size prop
+ * @param size The size of the avatar
+ * @returns The size details
+ */
+export const getSizeInfo = (size: TAvatarSize) => {
+  switch (size) {
+    case "sm":
+      return {
+        avatarSize: "h-4 w-4",
+        fontSize: "text-11",
+        spacing: "-space-x-1",
+      };
+    case "md":
+      return {
+        avatarSize: "h-5 w-5",
+        fontSize: "text-11",
+        spacing: "-space-x-1",
+      };
+    case "base":
+      return {
+        avatarSize: "h-6 w-6",
+        fontSize: "text-13",
+        spacing: "-space-x-1.5",
+      };
+    case "lg":
+      return {
+        avatarSize: "h-7 w-7",
+        fontSize: "text-13",
+        spacing: "-space-x-1.5",
+      };
+    default:
+      return {
+        avatarSize: "h-5 w-5",
+        fontSize: "text-11",
+        spacing: "-space-x-1",
+      };
+  }
+};
+
+/**
+ * Get the border radius based on the shape prop
+ * @param shape The shape of the avatar
+ * @returns The border radius
+ */
+export const getBorderRadius = (shape: "circle" | "square") => {
+  switch (shape) {
+    case "circle":
+      return "rounded-full";
+    case "square":
+      return "rounded-sm";
+    default:
+      return "rounded-full";
+  }
+};
+
+/**
+ * Check if the value is a valid number
+ * @param value The value to check
+ * @returns Whether the value is a valid number or not
+ */
+export const isAValidNumber = (value: unknown) => typeof value === "number" && !isNaN(value);

plane-src/packages/ui/src/avatar/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+export * from "./avatar-group";
+export * from "./avatar";