@work-rjkashyap/unified-ui 0.3.3 → 0.3.5

package/dist/components/avatar.d.ts

@@ -0,0 +1,198 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+
+declare const avatarVariants: (props?: ({
+    size?: "xs" | "sm" | "md" | "lg" | "xl" | null | undefined;
+    shape?: "circle" | "square" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type AvatarStatus = "online" | "offline" | "busy" | "away";
+type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
+type AvatarShape = "circle" | "square";
+interface AvatarProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "color">, VariantProps<typeof avatarVariants> {
+    /**
+     * Image source URL for the avatar.
+     * When provided, the component renders an `<img>` element.
+     * If the image fails to load, it falls back to initials or icon.
+     */
+    src?: string | null;
+    /**
+     * Alt text for the avatar image.
+     * Required for accessibility when `src` is provided.
+     * Also used as tooltip/title text.
+     */
+    alt?: string;
+    /**
+     * Full name of the user. Used to:
+     * 1. Generate initials for the fallback display
+     * 2. Provide alt text if `alt` is not explicitly set
+     *
+     * Initials are derived from the first letter of the first and last
+     * name segments (e.g. "Jane Doe" → "JD", "Alice" → "A").
+     */
+    name?: string;
+    /**
+     * Size of the avatar.
+     * @default "md"
+     */
+    size?: AvatarSize;
+    /**
+     * Shape of the avatar.
+     * @default "circle"
+     */
+    shape?: AvatarShape;
+    /**
+     * Status indicator displayed as a colored dot on the avatar.
+     * Position is automatically adjusted based on the avatar size.
+     */
+    status?: AvatarStatus;
+    /**
+     * Custom accessible label for the status indicator.
+     * Overrides the default label derived from the status value.
+     */
+    statusLabel?: string;
+    /**
+     * Custom fallback icon to display when no `src` or `name` is provided.
+     * Defaults to a generic user silhouette SVG.
+     */
+    fallbackIcon?: ReactNode;
+    /**
+     * Custom background color class for the fallback state.
+     * Useful for generating unique colors per user.
+     *
+     * @example "bg-indigo-100 text-indigo-700"
+     */
+    fallbackClassName?: string;
+    /** Additional CSS classes to merge on the root element. */
+    className?: string;
+    /** Content to render inside the avatar (overrides all fallback logic). */
+    children?: ReactNode;
+}
+/**
+ * Avatar — displays a user's profile image, initials, or a fallback icon.
+ *
+ * Built on the design system's token layer with CVA for variant composition.
+ * All colors, radii, spacing, and transitions come from CSS custom properties
+ * defined in design-system.css.
+ *
+ * The component automatically handles image loading and gracefully falls
+ * back to initials (derived from `name`) or a default user icon.
+ *
+ * Accessibility:
+ *   - Images include `alt` text (falls back to `name` if not provided)
+ *   - Fallback initials container has `role="img"` and `aria-label`
+ *   - Status dot has `role="status"` and descriptive `aria-label`
+ *
+ * @example
+ * ```tsx
+ * // With image
+ * <Avatar src="/photo.jpg" alt="Jane Doe" />
+ *
+ * // Initials fallback
+ * <Avatar name="Jane Doe" />
+ * <Avatar name="Jane Doe" size="lg" />
+ *
+ * // With status indicator
+ * <Avatar src="/photo.jpg" alt="Jane" status="online" />
+ * <Avatar name="Bob" status="busy" />
+ * <Avatar name="Charlie" status="away" size="sm" />
+ *
+ * // Square shape (for orgs/apps)
+ * <Avatar src="/logo.png" alt="Acme Inc" shape="square" />
+ *
+ * // All sizes
+ * <Avatar name="A" size="xs" />
+ * <Avatar name="A" size="sm" />
+ * <Avatar name="A" size="md" />
+ * <Avatar name="A" size="lg" />
+ * <Avatar name="A" size="xl" />
+ *
+ * // Custom fallback styling
+ * <Avatar name="Jane" fallbackClassName="bg-indigo-100 text-indigo-700" />
+ *
+ * // Custom fallback icon
+ * <Avatar fallbackIcon={<BotIcon className="size-[60%]" />} />
+ *
+ * // Custom children (overrides all fallback logic)
+ * <Avatar>
+ *   <span>🎉</span>
+ * </Avatar>
+ * ```
+ */
+declare const Avatar: react.ForwardRefExoticComponent<AvatarProps & react.RefAttributes<HTMLSpanElement>>;
+interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Maximum number of avatars to display before showing the "+N" overflow.
+     * Set to `0` or `Infinity` to disable truncation.
+     * @default 5
+     */
+    max?: number;
+    /**
+     * Size applied to all child avatars and the overflow indicator.
+     * Overrides the `size` prop on individual Avatar children.
+     * @default "md"
+     */
+    size?: AvatarSize;
+    /**
+     * Shape applied to all child avatars and the overflow indicator.
+     * Overrides the `shape` prop on individual Avatar children.
+     * @default "circle"
+     */
+    shape?: AvatarShape;
+    /**
+     * Spacing between overlapping avatars (as a negative margin).
+     * @default "default" — uses size-appropriate overlap
+     */
+    spacing?: "tight" | "default" | "loose";
+    /** Content — should be Avatar components. */
+    children?: ReactNode;
+    /** Additional CSS classes to merge on the wrapper. */
+    className?: string;
+}
+/**
+ * AvatarGroup — stacks multiple avatars with overlap and "+N" overflow.
+ *
+ * Renders child Avatar components in a horizontal stack with negative
+ * margins for overlap. When the number of children exceeds `max`, the
+ * excess avatars are hidden and a "+N" overflow indicator is shown.
+ *
+ * The group enforces consistent `size` and `shape` across all children
+ * by cloning them with the group's props.
+ *
+ * @example
+ * ```tsx
+ * // Basic group
+ * <AvatarGroup>
+ *   <Avatar src="/a.jpg" alt="Alice" />
+ *   <Avatar src="/b.jpg" alt="Bob" />
+ *   <Avatar name="Charlie" />
+ * </AvatarGroup>
+ *
+ * // With max and overflow
+ * <AvatarGroup max={3}>
+ *   <Avatar name="Alice" />
+ *   <Avatar name="Bob" />
+ *   <Avatar name="Charlie" />
+ *   <Avatar name="Diana" />
+ *   <Avatar name="Eve" />
+ * </AvatarGroup>
+ * // Renders: [Alice] [Bob] [Charlie] [+2]
+ *
+ * // Custom size and spacing
+ * <AvatarGroup size="lg" spacing="tight">
+ *   <Avatar name="A" />
+ *   <Avatar name="B" />
+ *   <Avatar name="C" />
+ * </AvatarGroup>
+ *
+ * // Square group (for org logos)
+ * <AvatarGroup shape="square" size="sm">
+ *   <Avatar src="/logo1.png" alt="Org 1" />
+ *   <Avatar src="/logo2.png" alt="Org 2" />
+ * </AvatarGroup>
+ * ```
+ */
+declare const AvatarGroup: react.ForwardRefExoticComponent<AvatarGroupProps & react.RefAttributes<HTMLDivElement>>;
+
+export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarShape, type AvatarSize, type AvatarStatus, avatarVariants };

package/dist/components/avatar.mjs

@@ -0,0 +1,329 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "../utils/cn";
+import { cva } from "class-variance-authority";
+import {
+  Children,
+  cloneElement,
+  forwardRef,
+  isValidElement,
+  useEffect,
+  useState
+} from "react";
+const avatarVariants = cva(
+  // Base styles — shared across all variants and sizes
+  [
+    // Layout
+    "relative inline-flex items-center justify-center shrink-0",
+    // Typography for fallback initials
+    "font-medium leading-none select-none",
+    // Default colors for fallback state
+    "bg-muted text-muted-foreground"
+  ],
+  {
+    variants: {
+      // -----------------------------------------------------------------
+      // Size Variants
+      // -----------------------------------------------------------------
+      size: {
+        /**
+         * Extra small — 24px. Inline metadata, compact lists.
+         */
+        xs: "size-6 text-[10px]",
+        /**
+         * Small — 32px. Table rows, compact cards.
+         */
+        sm: "size-8 text-xs",
+        /**
+         * Medium — 40px. Default, cards, comments.
+         */
+        md: "size-10 text-sm",
+        /**
+         * Large — 48px. Profile headers, featured content.
+         */
+        lg: "size-12 text-base",
+        /**
+         * Extra large — 64px. Profile pages, hero sections.
+         */
+        xl: "size-16 text-lg"
+      },
+      // -----------------------------------------------------------------
+      // Shape Variants
+      // -----------------------------------------------------------------
+      shape: {
+        /**
+         * Circle — default, standard avatar shape.
+         */
+        circle: "rounded-full",
+        /**
+         * Square — rounded rectangle, for app icons or org logos.
+         */
+        square: "rounded-md"
+      }
+    },
+    defaultVariants: {
+      size: "md",
+      shape: "circle"
+    }
+  }
+);
+const statusColorMap = {
+  online: "bg-success",
+  offline: "bg-muted-foreground",
+  busy: "bg-danger",
+  away: "bg-warning"
+};
+const statusLabelMap = {
+  online: "Online",
+  offline: "Offline",
+  busy: "Busy",
+  away: "Away"
+};
+const statusSizeMap = {
+  xs: "size-1.5",
+  sm: "size-2",
+  md: "size-2.5",
+  lg: "size-3",
+  xl: "size-3.5"
+};
+const statusPositionMap = {
+  xs: "bottom-0 right-0",
+  sm: "bottom-0 right-0",
+  md: "bottom-0.5 right-0.5",
+  lg: "bottom-0.5 right-0.5",
+  xl: "bottom-1 right-1"
+};
+function getInitials(name) {
+  const parts = name.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) return "";
+  if (parts.length === 1) return parts[0][0].toUpperCase();
+  return (parts[0][0] + parts[parts.length - 1][0]).toUpperCase();
+}
+function DefaultFallbackIcon({ className }) {
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      className: cn("size-8 translate-y-px text-current opacity-70", className),
+      xmlns: "http://www.w3.org/2000/svg",
+      viewBox: "0 0 24 24",
+      fill: "currentColor",
+      "aria-hidden": "true",
+      children: [
+        /* @__PURE__ */ jsx("circle", { cx: "12", cy: "7", r: "4" }),
+        /* @__PURE__ */ jsx("path", { d: "M12 14c-4.42 0-8 2.24-8 5v5h16v-5c0-2.76-3.58-5-8-5z" })
+      ]
+    }
+  );
+}
+function StatusDot({
+  status,
+  size,
+  label,
+  shape
+}) {
+  const resolvedLabel = label ?? statusLabelMap[status];
+  return /* @__PURE__ */ jsx(
+    "span",
+    {
+      className: cn(
+        "absolute block",
+        "rounded-full",
+        "ring-2 ring-background",
+        statusSizeMap[size],
+        statusColorMap[status],
+        // Position based on shape — circle uses corner, square uses edge
+        shape === "circle" ? statusPositionMap[size] : "bottom-0 right-0"
+      ),
+      role: "status",
+      "aria-label": resolvedLabel
+    }
+  );
+}
+function useImageLoadStatus(src) {
+  const [status, setStatus] = useState(
+    () => src ? "loading" : "error"
+  );
+  useEffect(() => {
+    if (!src) {
+      setStatus("error");
+      return;
+    }
+    setStatus("loading");
+    const img = new Image();
+    const handleLoad = () => setStatus("loaded");
+    const handleError = () => setStatus("error");
+    img.addEventListener("load", handleLoad);
+    img.addEventListener("error", handleError);
+    img.src = src;
+    if (img.complete) {
+      setStatus("loaded");
+    }
+    return () => {
+      img.removeEventListener("load", handleLoad);
+      img.removeEventListener("error", handleError);
+    };
+  }, [src]);
+  return status;
+}
+const Avatar = forwardRef(function Avatar2({
+  src,
+  alt,
+  name,
+  size = "md",
+  shape = "circle",
+  status,
+  statusLabel,
+  fallbackIcon,
+  fallbackClassName,
+  className,
+  children,
+  ...rest
+}, ref) {
+  const imageStatus = useImageLoadStatus(src);
+  const showImage = imageStatus === "loaded" && src;
+  const initials = name ? getInitials(name) : "";
+  const resolvedAlt = alt ?? name ?? "Avatar";
+  const imgEl = showImage ? /* @__PURE__ */ jsx(
+    "img",
+    {
+      src,
+      alt: resolvedAlt,
+      className: "size-full object-cover",
+      draggable: false
+    }
+  ) : null;
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      ref,
+      className: cn(
+        avatarVariants({ size, shape }),
+        !showImage && fallbackClassName,
+        className
+      ),
+      "data-ds": "",
+      "data-ds-component": "avatar",
+      "data-ds-size": size,
+      "data-ds-shape": shape,
+      ...rest,
+      children: [
+        /* @__PURE__ */ jsx("span", { className: "absolute inset-0 overflow-hidden rounded-[inherit] flex items-center justify-center", children: children ? children : showImage ? (
+          /* Priority 2: Loaded image */
+          imgEl
+        ) : initials ? (
+          /* Priority 3: Initials from name */
+          /* @__PURE__ */ jsx("span", { role: "img", "aria-label": resolvedAlt, children: initials })
+        ) : (
+          /* Priority 4: Fallback icon */
+          /* @__PURE__ */ jsx("span", { role: "img", "aria-label": resolvedAlt, children: fallbackIcon ?? /* @__PURE__ */ jsx(DefaultFallbackIcon, {}) })
+        ) }),
+        status && /* @__PURE__ */ jsx(
+          StatusDot,
+          {
+            status,
+            size,
+            label: statusLabel,
+            shape
+          }
+        )
+      ]
+    }
+  );
+});
+Avatar.displayName = "Avatar";
+const overlapMap = {
+  xs: { tight: "-ml-3", default: "-ml-2.5", loose: "-ml-1.5" },
+  sm: { tight: "-ml-4", default: "-ml-3", loose: "-ml-2" },
+  md: { tight: "-ml-5", default: "-ml-4", loose: "-ml-3" },
+  lg: { tight: "-ml-6", default: "-ml-5", loose: "-ml-3.5" },
+  xl: { tight: "-ml-8", default: "-ml-6", loose: "-ml-4" }
+};
+const AvatarGroup = forwardRef(
+  function AvatarGroup2({
+    max = 5,
+    size = "md",
+    shape = "circle",
+    spacing = "default",
+    className,
+    children,
+    ...rest
+  }, ref) {
+    const childArray = Children.toArray(children).filter(isValidElement);
+    const totalCount = childArray.length;
+    const overflowCount = max > 0 && totalCount > max ? totalCount - max : 0;
+    const visibleChildren = overflowCount > 0 ? childArray.slice(0, max) : childArray;
+    const overlapClass = overlapMap[size][spacing];
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref,
+        className: cn("inline-flex items-center", className),
+        role: "group",
+        "aria-label": `Group of ${totalCount} avatars`,
+        "data-ds": "",
+        "data-ds-component": "avatar-group",
+        ...rest,
+        children: [
+          visibleChildren.map((child, index) => {
+            if (!isValidElement(child)) return child;
+            return /* @__PURE__ */ jsx(
+              "span",
+              {
+                className: cn(
+                  index > 0 && overlapClass,
+                  // Ensure proper stacking order (first avatar on top)
+                  // z-index is set via CSS var so hover:z-50! (Tailwind) can override it
+                  "relative inline-flex cursor-pointer transition-transform duration-150 ease-out",
+                  "z-(--ag-z)",
+                  "hover:z-50! hover:scale-110"
+                ),
+                style: { "--ag-z": totalCount - index },
+                children: cloneElement(child, {
+                  size,
+                  shape,
+                  className: cn(
+                    child.props?.className,
+                    "ring-2 ring-background"
+                  )
+                })
+              },
+              child.props?.alt ?? child.props?.name ?? index
+            );
+          }),
+          overflowCount > 0 && /* @__PURE__ */ jsx(
+            "span",
+            {
+              className: cn(overlapClass, "relative inline-flex z-(--ag-z)"),
+              style: { "--ag-z": 0 },
+              children: /* @__PURE__ */ jsxs(
+                "span",
+                {
+                  className: cn(
+                    avatarVariants({ size, shape }),
+                    "ring-2 ring-background",
+                    "bg-muted text-muted-foreground",
+                    "font-semibold"
+                  ),
+                  role: "img",
+                  "aria-label": `${overflowCount} more`,
+                  "data-ds": "",
+                  "data-ds-component": "avatar-overflow",
+                  children: [
+                    "+",
+                    overflowCount
+                  ]
+                }
+              )
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+AvatarGroup.displayName = "AvatarGroup";
+export {
+  Avatar,
+  AvatarGroup,
+  avatarVariants
+};