@box/blueprint-web 18.8.0 → 18.9.0

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)]
   });
 });
 

package/dist/lib-esm/components.css

@@ -2542,12 +2542,12 @@
     transition:none;
   }
 }
-.bp_base_badge_module_badgeContainer--cc070{
+.bp_base_badge_module_badgeContainer--44c64{
   display:inline-flex;
   position:relative;
 }
 
-.bp_base_badge_module_badge--cc070{
+.bp_base_badge_module_badge--44c64{
   align-items:center;
   border:var(--border-2) solid var(--border-badge-border);
   border-radius:var(--radius-half);
@@ -2559,37 +2559,37 @@
           user-select:none;
 }
 
-.bp_base_badge_module_smallSizeBadge--cc070{
+.bp_base_badge_module_smallSizeBadge--44c64{
   height:var(--size-2);
   min-width:var(--size-2);
 }
 
-.bp_base_badge_module_mediumSizeBadge--cc070{
+.bp_base_badge_module_mediumSizeBadge--44c64{
   height:var(--size-3);
   min-width:var(--size-3);
 }
 
-.bp_base_badge_module_largeSizeBadge--cc070{
+.bp_base_badge_module_largeSizeBadge--44c64{
   height:var(--size-4);
   min-width:var(--size-4);
 }
 
-.bp_base_badge_module_xlargeSizeBadge--cc070{
+.bp_base_badge_module_xlargeSizeBadge--44c64{
   height:var(--size-5);
   min-width:var(--size-5);
 }
 
-.bp_base_badge_module_xxlargeSizeBadge--cc070{
+.bp_base_badge_module_xxlargeSizeBadge--44c64{
   height:var(--size-6);
   min-width:var(--size-6);
 }
 
-.bp_base_badge_module_iconBadge--cc070{
+.bp_base_badge_module_iconBadge--44c64{
   bottom:-5%;
   right:-5%;
 }
 
-.bp_base_badge_module_interactiveWrapper--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64{
   border:var(--border-2) solid #0000;
   border-radius:50%;
   bottom:calc(-5% - var(--border-2)/2);
@@ -2597,22 +2597,22 @@
   position:absolute;
   right:calc(-5% - var(--border-2)/2);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_smallSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_smallSizeBadge--44c64{
   width:var(--size-2);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_mediumSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_mediumSizeBadge--44c64{
   width:var(--size-3);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_largeSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_largeSizeBadge--44c64{
   width:var(--size-4);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_xlargeSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_xlargeSizeBadge--44c64{
   width:var(--size-5);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_xxlargeSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_xxlargeSizeBadge--44c64{
   width:var(--size-6);
 }
-.bp_base_badge_module_interactiveWrapper--cc070::before{
+.bp_base_badge_module_interactiveWrapper--44c64::before{
   content:"";
   left:calc(var(--size-6)*-1/4);
   min-height:var(--size-6);
@@ -2621,36 +2621,60 @@
   top:calc(var(--size-6)*-1/4);
 }
 
-.bp_base_badge_module_statusBadge--cc070{
+.bp_base_badge_module_statusBadge--44c64{
   bottom:-20%;
   right:-20%;
 }
 
-.bp_base_badge_module_statusBadge--cc070.bp_base_badge_module_largeSizeBadge--cc070{
+.bp_base_badge_module_statusBadge--44c64.bp_base_badge_module_largeSizeBadge--44c64{
   bottom:-22%;
   right:-22%;
 }
 
-.bp_base_badge_module_statusBadge--cc070.bp_base_badge_module_xlargeSizeBadge--cc070{
+.bp_base_badge_module_statusBadge--44c64.bp_base_badge_module_xlargeSizeBadge--44c64{
   bottom:-15%;
   right:-15%;
 }
 
-.bp_base_badge_module_statusBadge--cc070.bp_base_badge_module_xxlargeSizeBadge--cc070{
+.bp_base_badge_module_statusBadge--44c64.bp_base_badge_module_xxlargeSizeBadge--44c64{
   bottom:-4%;
   right:-4%;
 }
 
-.bp_base_badge_module_numericBadge--cc070{
+.bp_base_badge_module_numericBadge--44c64{
+  --bp-badge-enter-x:calc(var(--bp-space-010)*-1);
+  --bp-badge-enter-y:var(--bp-space-010);
   left:60%;
   top:0;
 }
 
-.bp_base_badge_module_numericBadgeSingleDigit--cc070{
+.bp_base_badge_module_numericBadge--44c64[data-bp-animated=true][data-state=playing]{
+  animation-duration:var(--bp-duration-medium);
+  animation-fill-mode:both;
+  animation-name:bp_base_badge_module_bpNumericBadgePopIn--44c64;
+  animation-timing-function:var(--bp-curve-large-on);
+}
+@media (prefers-reduced-motion: reduce){
+  .bp_base_badge_module_numericBadge--44c64[data-bp-animated=true][data-state=playing]{
+    animation:none;
+  }
+}
+
+@keyframes bp_base_badge_module_bpNumericBadgePopIn--44c64{
+  from{
+    opacity:var(--bp-opacity-hidden);
+    transform:translate(var(--bp-badge-enter-x), var(--bp-badge-enter-y)) scale(.5);
+  }
+  to{
+    opacity:var(--bp-opacity-visible);
+    transform:none;
+  }
+}
+.bp_base_badge_module_numericBadgeSingleDigit--44c64{
   padding:1px;
 }
 
-.bp_base_badge_module_numericBadgeMoreDigits--cc070{
+.bp_base_badge_module_numericBadgeMoreDigits--44c64{
   padding:1px 3px;
 }
 .bp_icon_button_module_iconButton--17523[data-bp-animated=true]{

package/dist/lib-esm/index.css

@@ -2542,12 +2542,12 @@
     transition:none;
   }
 }
-.bp_base_badge_module_badgeContainer--cc070{
+.bp_base_badge_module_badgeContainer--44c64{
   display:inline-flex;
   position:relative;
 }
 
-.bp_base_badge_module_badge--cc070{
+.bp_base_badge_module_badge--44c64{
   align-items:center;
   border:var(--border-2) solid var(--border-badge-border);
   border-radius:var(--radius-half);
@@ -2559,37 +2559,37 @@
           user-select:none;
 }
 
-.bp_base_badge_module_smallSizeBadge--cc070{
+.bp_base_badge_module_smallSizeBadge--44c64{
   height:var(--size-2);
   min-width:var(--size-2);
 }
 
-.bp_base_badge_module_mediumSizeBadge--cc070{
+.bp_base_badge_module_mediumSizeBadge--44c64{
   height:var(--size-3);
   min-width:var(--size-3);
 }
 
-.bp_base_badge_module_largeSizeBadge--cc070{
+.bp_base_badge_module_largeSizeBadge--44c64{
   height:var(--size-4);
   min-width:var(--size-4);
 }
 
-.bp_base_badge_module_xlargeSizeBadge--cc070{
+.bp_base_badge_module_xlargeSizeBadge--44c64{
   height:var(--size-5);
   min-width:var(--size-5);
 }
 
-.bp_base_badge_module_xxlargeSizeBadge--cc070{
+.bp_base_badge_module_xxlargeSizeBadge--44c64{
   height:var(--size-6);
   min-width:var(--size-6);
 }
 
-.bp_base_badge_module_iconBadge--cc070{
+.bp_base_badge_module_iconBadge--44c64{
   bottom:-5%;
   right:-5%;
 }
 
-.bp_base_badge_module_interactiveWrapper--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64{
   border:var(--border-2) solid #0000;
   border-radius:50%;
   bottom:calc(-5% - var(--border-2)/2);
@@ -2597,22 +2597,22 @@
   position:absolute;
   right:calc(-5% - var(--border-2)/2);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_smallSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_smallSizeBadge--44c64{
   width:var(--size-2);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_mediumSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_mediumSizeBadge--44c64{
   width:var(--size-3);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_largeSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_largeSizeBadge--44c64{
   width:var(--size-4);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_xlargeSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_xlargeSizeBadge--44c64{
   width:var(--size-5);
 }
-.bp_base_badge_module_interactiveWrapper--cc070.bp_base_badge_module_xxlargeSizeBadge--cc070{
+.bp_base_badge_module_interactiveWrapper--44c64.bp_base_badge_module_xxlargeSizeBadge--44c64{
   width:var(--size-6);
 }
-.bp_base_badge_module_interactiveWrapper--cc070::before{
+.bp_base_badge_module_interactiveWrapper--44c64::before{
   content:"";
   left:calc(var(--size-6)*-1/4);
   min-height:var(--size-6);
@@ -2621,36 +2621,60 @@
   top:calc(var(--size-6)*-1/4);
 }
 
-.bp_base_badge_module_statusBadge--cc070{
+.bp_base_badge_module_statusBadge--44c64{
   bottom:-20%;
   right:-20%;
 }
 
-.bp_base_badge_module_statusBadge--cc070.bp_base_badge_module_largeSizeBadge--cc070{
+.bp_base_badge_module_statusBadge--44c64.bp_base_badge_module_largeSizeBadge--44c64{
   bottom:-22%;
   right:-22%;
 }
 
-.bp_base_badge_module_statusBadge--cc070.bp_base_badge_module_xlargeSizeBadge--cc070{
+.bp_base_badge_module_statusBadge--44c64.bp_base_badge_module_xlargeSizeBadge--44c64{
   bottom:-15%;
   right:-15%;
 }
 
-.bp_base_badge_module_statusBadge--cc070.bp_base_badge_module_xxlargeSizeBadge--cc070{
+.bp_base_badge_module_statusBadge--44c64.bp_base_badge_module_xxlargeSizeBadge--44c64{
   bottom:-4%;
   right:-4%;
 }
 
-.bp_base_badge_module_numericBadge--cc070{
+.bp_base_badge_module_numericBadge--44c64{
+  --bp-badge-enter-x:calc(var(--bp-space-010)*-1);
+  --bp-badge-enter-y:var(--bp-space-010);
   left:60%;
   top:0;
 }
 
-.bp_base_badge_module_numericBadgeSingleDigit--cc070{
+.bp_base_badge_module_numericBadge--44c64[data-bp-animated=true][data-state=playing]{
+  animation-duration:var(--bp-duration-medium);
+  animation-fill-mode:both;
+  animation-name:bp_base_badge_module_bpNumericBadgePopIn--44c64;
+  animation-timing-function:var(--bp-curve-large-on);
+}
+@media (prefers-reduced-motion: reduce){
+  .bp_base_badge_module_numericBadge--44c64[data-bp-animated=true][data-state=playing]{
+    animation:none;
+  }
+}
+
+@keyframes bp_base_badge_module_bpNumericBadgePopIn--44c64{
+  from{
+    opacity:var(--bp-opacity-hidden);
+    transform:translate(var(--bp-badge-enter-x), var(--bp-badge-enter-y)) scale(.5);
+  }
+  to{
+    opacity:var(--bp-opacity-visible);
+    transform:none;
+  }
+}
+.bp_base_badge_module_numericBadgeSingleDigit--44c64{
   padding:1px;
 }
 
-.bp_base_badge_module_numericBadgeMoreDigits--cc070{
+.bp_base_badge_module_numericBadgeMoreDigits--44c64{
   padding:1px 3px;
 }
 .bp_icon_button_module_iconButton--17523[data-bp-animated=true]{

package/dist/lib-esm/utils/use-one-shot-animation.d.ts

@@ -0,0 +1,35 @@
+import { type AnimationEvent } from 'react';
+export type OneShotAnimationState = 'idle' | 'playing';
+/**
+ * Stamp this on the animated node together with `key={animationGeneration}`.
+ * A completion whose stamp does not match the current generation is ignored.
+ */
+export declare const ONE_SHOT_ANIMATION_GENERATION_ATTRIBUTE = "data-bp-animation-generation";
+/**
+ * Replays a CSS animation when `trigger` changes by `Object.is`.
+ *
+ * CSS will not restart while `data-state` stays `'playing'`, so this hook
+ * sets `'playing'` on a trigger change and returns to `'idle'` on
+ * `animationend`.
+ *
+ * Each accepted trigger change bumps `animationGeneration`. When remounting is
+ * safe, key the animated node with that value and set
+ * `data-bp-animation-generation` to the same number so an `animationend` from
+ * the previous node cannot idle the new one.
+ *
+ * If the trigger changes while already playing, the hook goes to `'idle'` first,
+ * then `'playing'` again. Use that path when the node must stay mounted (for
+ * example a text field that should keep focus and input). The idle update is
+ * flushed before paint; a follow-up effect sets `'playing'`.
+ *
+ * A same-value resubmit (for example the same validation error twice) does not
+ * change `trigger` by `Object.is`, so it will not replay. Pass a nonce as
+ * `trigger` when you need another play without a value change.
+ *
+ * A rerender that keeps the same `trigger` after idle does not auto-play.
+ */
+export declare function useOneShotAnimation(trigger: unknown, isEnabled: boolean): {
+    animationState: OneShotAnimationState;
+    animationGeneration: number;
+    onAnimationEnd: (event: AnimationEvent) => void;
+};

package/dist/lib-esm/utils/use-one-shot-animation.js

@@ -0,0 +1,112 @@
+import { useState, useRef, useCallback, useEffect } from 'react';
+import { noop } from './noop.js';
+import { useEnhancedEffect } from './useEnhancedEffect.js';
+
+/**
+ * Stamp this on the animated node together with `key={animationGeneration}`.
+ * A completion whose stamp does not match the current generation is ignored.
+ */
+const ONE_SHOT_ANIMATION_GENERATION_ATTRIBUTE = 'data-bp-animation-generation';
+const animationEndNoop = noop;
+const readStampedAnimationGeneration = event => {
+  const {
+    currentTarget
+  } = event;
+  if (!(currentTarget instanceof Element)) {
+    return null;
+  }
+  const generation = currentTarget.getAttribute(ONE_SHOT_ANIMATION_GENERATION_ATTRIBUTE);
+  if (generation === null) {
+    return null;
+  }
+  return Number(generation);
+};
+/**
+ * Replays a CSS animation when `trigger` changes by `Object.is`.
+ *
+ * CSS will not restart while `data-state` stays `'playing'`, so this hook
+ * sets `'playing'` on a trigger change and returns to `'idle'` on
+ * `animationend`.
+ *
+ * Each accepted trigger change bumps `animationGeneration`. When remounting is
+ * safe, key the animated node with that value and set
+ * `data-bp-animation-generation` to the same number so an `animationend` from
+ * the previous node cannot idle the new one.
+ *
+ * If the trigger changes while already playing, the hook goes to `'idle'` first,
+ * then `'playing'` again. Use that path when the node must stay mounted (for
+ * example a text field that should keep focus and input). The idle update is
+ * flushed before paint; a follow-up effect sets `'playing'`.
+ *
+ * A same-value resubmit (for example the same validation error twice) does not
+ * change `trigger` by `Object.is`, so it will not replay. Pass a nonce as
+ * `trigger` when you need another play without a value change.
+ *
+ * A rerender that keeps the same `trigger` after idle does not auto-play.
+ */
+function useOneShotAnimation(trigger, isEnabled) {
+  const [animationState, setAnimationState] = useState('idle');
+  const [animationGeneration, setAnimationGeneration] = useState(0);
+  const previousTriggerRef = useRef(trigger);
+  const animationGenerationRef = useRef(0);
+  const animationStateRef = useRef(animationState);
+  const restartAfterIdleRef = useRef(false);
+  animationStateRef.current = animationState;
+  const onAnimationEnd = useCallback(event => {
+    if (event.target !== event.currentTarget || animationState !== 'playing') {
+      return;
+    }
+    // This handler was created for a generation that a newer trigger replaced.
+    if (animationGeneration !== animationGenerationRef.current) {
+      return;
+    }
+    const stampedGeneration = readStampedAnimationGeneration(event);
+    // Unstamped callers (no keyed node) keep the previous completion behavior.
+    if (stampedGeneration !== null && stampedGeneration !== animationGenerationRef.current) {
+      return;
+    }
+    setAnimationState('idle');
+  }, [animationGeneration, animationState]);
+  useEnhancedEffect(() => {
+    if (!isEnabled) {
+      previousTriggerRef.current = trigger;
+      restartAfterIdleRef.current = false;
+      setAnimationState('idle');
+      return;
+    }
+    if (Object.is(previousTriggerRef.current, trigger)) {
+      return;
+    }
+    previousTriggerRef.current = trigger;
+    animationGenerationRef.current += 1;
+    setAnimationGeneration(animationGenerationRef.current);
+    if (animationStateRef.current === 'playing') {
+      restartAfterIdleRef.current = true;
+      setAnimationState('idle');
+      return;
+    }
+    restartAfterIdleRef.current = false;
+    setAnimationState('playing');
+  }, [isEnabled, trigger]);
+  useEffect(() => {
+    if (!restartAfterIdleRef.current || animationState !== 'idle') {
+      return;
+    }
+    restartAfterIdleRef.current = false;
+    setAnimationState('playing');
+  }, [animationState]);
+  if (!isEnabled) {
+    return {
+      animationState: 'idle',
+      animationGeneration,
+      onAnimationEnd: animationEndNoop
+    };
+  }
+  return {
+    animationState,
+    animationGeneration,
+    onAnimationEnd
+  };
+}
+
+export { ONE_SHOT_ANIMATION_GENERATION_ATTRIBUTE, useOneShotAnimation };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@box/blueprint-web",
-    "version": "18.8.0",
+    "version": "18.9.0",
     "type": "module",
     "license": "SEE LICENSE IN LICENSE",
     "publishConfig": {
@@ -55,7 +55,7 @@
     "dependencies": {
         "@ariakit/react": "0.4.21",
         "@ariakit/react-core": "0.4.21",
-        "@box/blueprint-web-assets": "^5.13.7",
+        "@box/blueprint-web-assets": "^5.13.8",
         "@internationalized/date": "^3.12.0",
         "@radix-ui/react-accordion": "1.1.2",
         "@radix-ui/react-checkbox": "1.0.4",
@@ -85,7 +85,7 @@
     "devDependencies": {
         "@box/box-test-client": "^3.2.7",
         "@box/playwright-utils": "^2.8.5",
-        "@box/storybook-utils": "^1.4.26",
+        "@box/storybook-utils": "^1.4.27",
         "@figma/code-connect": "1.4.4",
         "@playwright/test": "1.46.1",
         "@types/js-yaml": "^4.0.9",