@box/blueprint-web 18.7.1 → 18.9.0

package/dist/lib-esm/avatar/avatar-group/avatar-group.d.ts

@@ -0,0 +1,2 @@
+import { type AvatarGroupProps } from './types';
+export declare const AvatarGroup: import("react").ForwardRefExoticComponent<AvatarGroupProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/lib-esm/avatar/avatar-group/avatar-group.js

@@ -0,0 +1,156 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { bpGray10 } from '@box/blueprint-web-assets/tokens/tokens';
+import clsx from 'clsx';
+import { forwardRef, Children, cloneElement, isValidElement } from 'react';
+import '../../blueprint-configuration-context/blueprint-configuration-context.js';
+import '../../blueprint-configuration-context/consts.js';
+import { useBlueprintConfiguration } from '../../blueprint-configuration-context/useBlueprintConfiguration.js';
+import { Focusable } from '../../focusable/focusable.js';
+import { useTravelTooltip, TravelTooltipBubble } from '../../tooltip/travel-tooltip.js';
+import { composeEventHandlers } from '../../utils/composeEventHandlers.js';
+import { useForkRef } from '../../utils/useForkRef.js';
+import { useUniqueId } from '../../utils/useUniqueId.js';
+import { Avatar } from '../avatar.js';
+import styles from './avatar-group.module.js';
+import { useAvatarGroupHover } from './use-avatar-group-hover.js';
+import { getAvatarGroupVisibility } from './utils.js';
+
+const overflowColor = bpGray10;
+function isAvatarElement(child) {
+  return /*#__PURE__*/isValidElement(child) && child.type === Avatar;
+}
+const AvatarGroup = /*#__PURE__*/forwardRef((props, forwardedRef) => {
+  const {
+    children,
+    className,
+    getTooltipContent,
+    max,
+    overflowLabel,
+    overlap,
+    ringColor,
+    size,
+    style,
+    onMouseLeave,
+    onPointerLeave,
+    onBlur,
+    ...rest
+  } = props;
+  const {
+    componentsWithAnimationEnabled
+  } = useBlueprintConfiguration();
+  const isAnimationEnabled = componentsWithAnimationEnabled.includes('AvatarGroup');
+  const {
+    groupRef: hoverGroupRef,
+    onGroupLeave,
+    onItemEnter
+  } = useAvatarGroupHover(isAnimationEnabled);
+  const {
+    activeTrigger,
+    groupRef: travelGroupRef,
+    hideFocusIfLeavingGroup,
+    hidePointerIfLeavingGroup,
+    label,
+    showForFocus,
+    showForPointer,
+    textRef,
+    tooltipRef
+  } = useTravelTooltip();
+  const ref = useForkRef(useForkRef(hoverGroupRef, travelGroupRef), forwardedRef);
+  const tooltipId = useUniqueId('avatar-group-tooltip');
+  const avatars = Children.toArray(children).filter(isAvatarElement);
+  const {
+    visibleCount,
+    overflowCount
+  } = getAvatarGroupVisibility(avatars.length, max);
+  const visibleAvatars = avatars.slice(0, visibleCount);
+  const hasTooltips = Boolean(getTooltipContent || overflowLabel);
+  const customProperties = {
+    ...(overlap ? {
+      '--avatar-group-overlap': overlap
+    } : {}),
+    ...(ringColor ? {
+      '--avatar-group-ring-color': ringColor
+    } : {})
+  };
+  const leaveFromPointer = event => {
+    if (hidePointerIfLeavingGroup(event)) {
+      onGroupLeave();
+    }
+  };
+  const leaveFromFocus = event => {
+    if (hideFocusIfLeavingGroup(event)) {
+      onGroupLeave();
+    }
+  };
+  const activateItem = (index, trigger, tooltip, show) => {
+    onItemEnter(index);
+    if (tooltip) {
+      show(trigger, tooltip);
+    }
+  };
+  return jsxs("div", {
+    ...rest,
+    ref: ref,
+    className: clsx(styles.avatarGroup, className),
+    "data-bp-animated": isAnimationEnabled ? 'true' : 'false',
+    onBlur: composeEventHandlers(onBlur, leaveFromFocus),
+    onMouseLeave: onMouseLeave,
+    onPointerLeave: composeEventHandlers(onPointerLeave, leaveFromPointer),
+    role: "group",
+    style: overlap || ringColor || style ? {
+      ...customProperties,
+      ...style
+    } : undefined,
+    children: [visibleAvatars.map((child, index) => {
+      const tooltip = getTooltipContent?.(child.props.text, index);
+      return jsx(Focusable, {
+        "aria-describedby": tooltip ? tooltipId : undefined,
+        focusable: Boolean(tooltip),
+        // eslint-disable-next-line react/jsx-no-bind
+        onFocusVisible: event => activateItem(index, event.currentTarget, tooltip, showForFocus),
+        // eslint-disable-next-line react/jsx-no-bind
+        onPointerEnter: event => activateItem(index, event.currentTarget, tooltip, showForPointer),
+        children: jsx("div", {
+          className: styles.item,
+          "data-avatar-group-item": "",
+          children: jsx("div", {
+            className: styles.itemMotion,
+            children: size ? /*#__PURE__*/cloneElement(child, {
+              size
+            }) : child
+          })
+        })
+      }, child.key ?? index);
+    }), overflowCount > 0 && jsx(Focusable, {
+      "aria-describedby": overflowLabel ? tooltipId : undefined,
+      "aria-label": overflowLabel,
+      focusable: Boolean(overflowLabel),
+      // eslint-disable-next-line react/jsx-no-bind
+      onFocusVisible: event => activateItem(visibleAvatars.length, event.currentTarget, overflowLabel, showForFocus),
+      // eslint-disable-next-line react/jsx-no-bind
+      onPointerEnter: event => activateItem(visibleAvatars.length, event.currentTarget, overflowLabel, showForPointer),
+      children: jsx("div", {
+        className: styles.item,
+        "data-avatar-group-item": "",
+        children: jsx("div", {
+          className: styles.itemMotion,
+          children: jsx(Avatar, {
+            color: overflowColor,
+            size: size,
+            text: `+${overflowCount}`
+          })
+        })
+      })
+    }), hasTooltips ? jsx(TravelTooltipBubble, {
+      animated: isAnimationEnabled,
+      id: tooltipId,
+      label: label,
+      show: Boolean(activeTrigger),
+      textRef: textRef,
+      tooltipRef: tooltipRef
+    }) : null]
+  });
+});
+AvatarGroup.displayName = 'AvatarGroup';
+
+export { AvatarGroup };

package/dist/lib-esm/avatar/avatar-group/avatar-group.module.js

@@ -0,0 +1,4 @@
+import '../../index.css';
+var styles = {"avatarGroup":"bp_avatar_group_module_avatarGroup--c775b","item":"bp_avatar_group_module_item--c775b","itemMotion":"bp_avatar_group_module_itemMotion--c775b"};
+
+export { styles as default };

package/dist/lib-esm/avatar/avatar-group/types.d.ts

@@ -0,0 +1,27 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import { type AvatarSize } from '../types';
+export interface AvatarGroupProps extends Omit<ComponentPropsWithoutRef<'div'>, 'role'> {
+    /**
+     * Avatar children to display. Compose with `<Avatar>` nodes — the group clones
+     * them to apply `size` and the overlap/ring treatment.
+     */
+    children?: ReactNode;
+    /** Maximum number of avatars shown before an overflow `+N` avatar is rendered. */
+    max?: number;
+    /** Size passed through to each Avatar, including the overflow avatar. */
+    size?: AvatarSize;
+    /**
+     * Overlap distance between adjacent avatars as a CSS length.
+     * @default `--bp-space-020` (8px).
+     */
+    overlap?: string;
+    /**
+     * Ring colour around each avatar as a CSS color.
+     * @default `--bp-gray-white`.
+     */
+    ringColor?: string;
+    /** Accessible label for the overflow avatar. */
+    overflowLabel?: string;
+    /** Tooltip label for a visible avatar. Omit to skip tooltips. */
+    getTooltipContent?(text: string | undefined, index: number): string | undefined;
+}

package/dist/lib-esm/avatar/avatar-group/use-avatar-group-hover.d.ts

@@ -0,0 +1,6 @@
+export declare function applyAvatarGroupHover(items: HTMLElement[], activeIndex: number | null): void;
+export declare function useAvatarGroupHover(enabled: boolean): {
+    groupRef: import("react").RefObject<HTMLDivElement>;
+    onGroupLeave: () => void;
+    onItemEnter: (index: number) => void;
+};

package/dist/lib-esm/avatar/avatar-group/use-avatar-group-hover.js

@@ -0,0 +1,61 @@
+import { useRef, useCallback } from 'react';
+
+// Transitions.dev avatar hover. Lift is negative so the active item rises.
+const LIFT = -4;
+const SCALE = 1.05;
+// TODO(ewang): confirm duration — 200/140 has no --bp-duration-* pair (medium=150, long=300)
+const DUR_IN = '200ms';
+const DUR_OUT = '140ms';
+// TODO(ewang): confirm curve — Transitions.dev 0.22,1,0.36,1 vs --bp-curve-large-on
+const EASE_IN = 'cubic-bezier(0.22, 1, 0.36, 1)';
+// Leave is a plain ease-out — no spring overshoot.
+const EASE_OUT = 'cubic-bezier(0.4, 0, 0.2, 1)';
+function applyAvatarGroupHover(items, activeIndex) {
+  const isLeaving = activeIndex === null;
+  const ease = isLeaving ? EASE_OUT : EASE_IN;
+  const duration = isLeaving ? DUR_OUT : DUR_IN;
+  items.forEach(item => {
+    item.style.transitionDuration = duration;
+    item.style.transitionTimingFunction = ease;
+  });
+  items.forEach((item, index) => {
+    if (activeIndex === null) {
+      item.style.setProperty('--shift', '0px');
+      item.style.setProperty('--scale-active', '1');
+      item.style.zIndex = '';
+      return;
+    }
+    const isActive = index === activeIndex;
+    item.style.setProperty('--shift', isActive ? `${LIFT}px` : '0px');
+    item.style.setProperty('--scale-active', isActive ? String(SCALE) : '1');
+    item.style.zIndex = isActive ? '3' : '';
+  });
+}
+function useAvatarGroupHover(enabled) {
+  const groupRef = useRef(null);
+  const getItems = useCallback(() => {
+    if (!groupRef.current) {
+      return [];
+    }
+    return [...groupRef.current.querySelectorAll('[data-avatar-group-item]')];
+  }, []);
+  const onItemEnter = useCallback(index => {
+    if (!enabled) {
+      return;
+    }
+    applyAvatarGroupHover(getItems(), index);
+  }, [enabled, getItems]);
+  const onGroupLeave = useCallback(() => {
+    if (!enabled) {
+      return;
+    }
+    applyAvatarGroupHover(getItems(), null);
+  }, [enabled, getItems]);
+  return {
+    groupRef,
+    onGroupLeave,
+    onItemEnter
+  };
+}
+
+export { applyAvatarGroupHover, useAvatarGroupHover };

package/dist/lib-esm/avatar/avatar-group/utils.d.ts

@@ -0,0 +1,5 @@
+export type AvatarGroupVisibility = {
+    visibleCount: number;
+    overflowCount: number;
+};
+export declare function getAvatarGroupVisibility(totalCount: number, max?: number): AvatarGroupVisibility;

package/dist/lib-esm/avatar/avatar-group/utils.js

@@ -0,0 +1,31 @@
+/**
+ * Splits a group of avatars into the number shown and the leftover overflow count
+ * rendered as a `+N` avatar.
+ *
+ * `max` is the visible count before overflow. When omitted, every avatar is shown.
+ */
+function getVisibleCountForMax(totalCount, max) {
+  if (max === Number.POSITIVE_INFINITY) {
+    return totalCount;
+  }
+  if (!Number.isFinite(max)) {
+    return 0;
+  }
+  const normalizedMax = Math.max(0, Math.trunc(max));
+  return Math.min(totalCount, normalizedMax);
+}
+function getAvatarGroupVisibility(totalCount, max) {
+  if (max === undefined) {
+    return {
+      visibleCount: totalCount,
+      overflowCount: 0
+    };
+  }
+  const visibleCount = getVisibleCountForMax(totalCount, max);
+  return {
+    visibleCount,
+    overflowCount: totalCount - visibleCount
+  };
+}
+
+export { getAvatarGroupVisibility };

package/dist/lib-esm/avatar/avatar.module.js

@@ -1,4 +1,4 @@
 import '../index.css';
-var styles = {"avatar":"bp_avatar_module_avatar--ed504","text":"bp_avatar_module_text--ed504","xsmall":"bp_avatar_module_xsmall--ed504","length-1":"bp_avatar_module_length-1--ed504","length-2":"bp_avatar_module_length-2--ed504","small":"bp_avatar_module_small--ed504","medium":"bp_avatar_module_medium--ed504","large":"bp_avatar_module_large--ed504","length-3":"bp_avatar_module_length-3--ed504","length-4":"bp_avatar_module_length-4--ed504","xlarge":"bp_avatar_module_xlarge--ed504","xxlarge":"bp_avatar_module_xxlarge--ed504","badge":"bp_avatar_module_badge--ed504","image":"bp_avatar_module_image--ed504","loading":"bp_avatar_module_loading--ed504","anonymousAvatar":"bp_avatar_module_anonymousAvatar--ed504","iconContainer":"bp_avatar_module_iconContainer--ed504"};
+var styles = {"avatar":"bp_avatar_module_avatar--42c50","text":"bp_avatar_module_text--42c50","xsmall":"bp_avatar_module_xsmall--42c50","length-1":"bp_avatar_module_length-1--42c50","length-2":"bp_avatar_module_length-2--42c50","small":"bp_avatar_module_small--42c50","medium":"bp_avatar_module_medium--42c50","large":"bp_avatar_module_large--42c50","length-3":"bp_avatar_module_length-3--42c50","length-4":"bp_avatar_module_length-4--42c50","xlarge":"bp_avatar_module_xlarge--42c50","xxlarge":"bp_avatar_module_xxlarge--42c50","badge":"bp_avatar_module_badge--42c50","image":"bp_avatar_module_image--42c50","loading":"bp_avatar_module_loading--42c50","anonymousAvatar":"bp_avatar_module_anonymousAvatar--42c50","iconContainer":"bp_avatar_module_iconContainer--42c50"};
 
 export { styles as default };

package/dist/lib-esm/avatar/index.d.ts

@@ -1,2 +1,4 @@
 export { Avatar } from './avatar';
+export { AvatarGroup } from './avatar-group/avatar-group';
+export { type AvatarGroupProps } from './avatar-group/types';
 export { type AvatarProps } from './types';

package/dist/lib-esm/badge/base-badge.d.ts

@@ -1,3 +1,4 @@
+import { type AnimationEventHandler } from 'react';
 import { type BadgeProps } from './types';
 export type BaseBadgeProps = Omit<BadgeProps, 'children'> & {
     /** The color of the badge background. */
@@ -5,5 +6,9 @@ export type BaseBadgeProps = Omit<BadgeProps, 'children'> & {
     className?: string;
     /** The child element to display in the badge: string for NumericBadge and svg for IconBadge). */
     children?: React.ReactElement;
+    'data-bp-animated'?: 'true' | 'false';
+    'data-bp-animation-generation'?: number;
+    'data-state'?: 'idle' | 'playing';
+    onAnimationEnd?: AnimationEventHandler<HTMLDivElement>;
 };
-export declare const BaseBadge: ({ backgroundColor, className, children, size, offset }: BaseBadgeProps) => import("react/jsx-runtime").JSX.Element;
+export declare const BaseBadge: ({ backgroundColor, className, children, size, offset, "data-bp-animated": dataBpAnimated, "data-bp-animation-generation": dataBpAnimationGeneration, "data-state": dataState, onAnimationEnd, }: BaseBadgeProps) => import("react/jsx-runtime").JSX.Element;

package/dist/lib-esm/badge/base-badge.js

@@ -8,11 +8,19 @@ const BaseBadge = ({
   className,
   children,
   size,
-  offset
+  offset,
+  'data-bp-animated': dataBpAnimated,
+  'data-bp-animation-generation': dataBpAnimationGeneration,
+  'data-state': dataState,
+  onAnimationEnd
 }) => {
   const offsetStyle = mapValues(offset, value => Number.isInteger(value) ? `${value}px` : `0`);
   return jsx("div", {
     className: clsx(className, styles.badge, styles[`${size}SizeBadge`]),
+    "data-bp-animated": dataBpAnimated,
+    "data-bp-animation-generation": dataBpAnimationGeneration,
+    "data-state": dataState,
+    onAnimationEnd: onAnimationEnd,
     style: {
       backgroundColor,
       ...offsetStyle

package/dist/lib-esm/badge/base-badge.module.js

@@ -1,4 +1,4 @@
 import '../index.css';
-var styles = {"badgeContainer":"bp_base_badge_module_badgeContainer--cc070","badge":"bp_base_badge_module_badge--cc070","smallSizeBadge":"bp_base_badge_module_smallSizeBadge--cc070","mediumSizeBadge":"bp_base_badge_module_mediumSizeBadge--cc070","largeSizeBadge":"bp_base_badge_module_largeSizeBadge--cc070","xlargeSizeBadge":"bp_base_badge_module_xlargeSizeBadge--cc070","xxlargeSizeBadge":"bp_base_badge_module_xxlargeSizeBadge--cc070","iconBadge":"bp_base_badge_module_iconBadge--cc070","interactiveWrapper":"bp_base_badge_module_interactiveWrapper--cc070","statusBadge":"bp_base_badge_module_statusBadge--cc070","numericBadge":"bp_base_badge_module_numericBadge--cc070","numericBadgeSingleDigit":"bp_base_badge_module_numericBadgeSingleDigit--cc070","numericBadgeMoreDigits":"bp_base_badge_module_numericBadgeMoreDigits--cc070"};
+var styles = {"badgeContainer":"bp_base_badge_module_badgeContainer--44c64","badge":"bp_base_badge_module_badge--44c64","smallSizeBadge":"bp_base_badge_module_smallSizeBadge--44c64","mediumSizeBadge":"bp_base_badge_module_mediumSizeBadge--44c64","largeSizeBadge":"bp_base_badge_module_largeSizeBadge--44c64","xlargeSizeBadge":"bp_base_badge_module_xlargeSizeBadge--44c64","xxlargeSizeBadge":"bp_base_badge_module_xxlargeSizeBadge--44c64","iconBadge":"bp_base_badge_module_iconBadge--44c64","interactiveWrapper":"bp_base_badge_module_interactiveWrapper--44c64","statusBadge":"bp_base_badge_module_statusBadge--44c64","numericBadge":"bp_base_badge_module_numericBadge--44c64","bpNumericBadgePopIn":"bp_base_badge_module_bpNumericBadgePopIn--44c64","numericBadgeSingleDigit":"bp_base_badge_module_numericBadgeSingleDigit--44c64","numericBadgeMoreDigits":"bp_base_badge_module_numericBadgeMoreDigits--44c64"};
 
 export { styles as default };

package/dist/lib-esm/badge/numeric-badge.js

@@ -1,8 +1,12 @@
 import { jsxs, jsx } from 'react/jsx-runtime';
 import { WatermelonRed110 } from '@box/blueprint-web-assets/tokens/tokens';
 import clsx from 'clsx';
-import { forwardRef, Children, cloneElement } from 'react';
+import { forwardRef, useState, useCallback, Children, cloneElement } from 'react';
+import '../blueprint-configuration-context/blueprint-configuration-context.js';
+import '../blueprint-configuration-context/consts.js';
+import { useBlueprintConfiguration } from '../blueprint-configuration-context/useBlueprintConfiguration.js';
 import { Text } from '../text/text.js';
+import { useOneShotAnimation, ONE_SHOT_ANIMATION_GENERATION_ATTRIBUTE } from '../utils/use-one-shot-animation.js';
 import { useUniqueId } from '../utils/useUniqueId.js';
 import { BaseBadge } from './base-badge.js';
 import styles from './base-badge.module.js';
@@ -14,6 +18,32 @@ const NumericBadge = /*#__PURE__*/forwardRef((props, forwardedRef) => {
     offset,
     render
   } = props;
+  const {
+    componentsWithAnimationEnabled
+  } = useBlueprintConfiguration();
+  const isAnimationEnabled = componentsWithAnimationEnabled.includes('NumericBadge');
+  const {
+    animationState,
+    animationGeneration,
+    onAnimationEnd
+  } = useOneShotAnimation(value, isAnimationEnabled);
+  // First paint must play enter: the hook's initial trigger is idle and does not
+  // auto-play on mount. Flip to entered on animationend so idle does not loop.
+  const [hasEntered, setHasEntered] = useState(false);
+  const handleAnimationEnd = useCallback(event => {
+    if (event.target !== event.currentTarget) {
+      return;
+    }
+    // A completion from the previous keyed node must not finish this generation.
+    if (event.currentTarget.getAttribute(ONE_SHOT_ANIMATION_GENERATION_ATTRIBUTE) !== String(animationGeneration)) {
+      return;
+    }
+    if (!hasEntered) {
+      setHasEntered(true);
+    }
+    onAnimationEnd(event);
+  }, [animationGeneration, hasEntered, onAnimationEnd]);
+  const animationDataState = isAnimationEnabled && (!hasEntered || animationState === 'playing') ? 'playing' : 'idle';
   const valueId = useUniqueId('numeric-badge-value');
   // In the case of a deeply nested child (e.g., the child is wrapped by a tooltip), the render prop must be passed instead of children to correctly apply aria-describedby.
   let badgeChild;
@@ -36,7 +66,11 @@ const NumericBadge = /*#__PURE__*/forwardRef((props, forwardedRef) => {
         [styles.numericBadgeMoreDigits]: value.length > 1,
         [styles.numericBadgeSingleDigit]: value.length === 1
       }),
+      "data-bp-animated": isAnimationEnabled ? 'true' : 'false',
+      "data-bp-animation-generation": animationGeneration,
+      "data-state": animationDataState,
       offset: offset,
+      onAnimationEnd: handleAnimationEnd,
       size: "medium",
       children: jsx(Text, {
         as: "span",
@@ -45,7 +79,7 @@ const NumericBadge = /*#__PURE__*/forwardRef((props, forwardedRef) => {
         variant: "labelBold",
         children: value
       })
-    })]
+    }, animationGeneration)]
   });
 });