@box/blueprint-web 18.7.1 → 18.9.0

package/dist/lib-esm/tooltip/travel-tooltip.js

@@ -0,0 +1,100 @@
+import { jsx } from 'react/jsx-runtime';
+import { useRef, useState, useLayoutEffect } from 'react';
+import styles from './travel-tooltip.module.js';
+
+const arm = (trigger, nextLabel) => ({
+  element: trigger,
+  label: nextLabel ?? trigger.dataset.tooltip ?? ''
+});
+const leftTheGroup = event => {
+  const next = event.relatedTarget;
+  return !(next instanceof Node && event.currentTarget.contains(next));
+};
+function useTravelTooltip() {
+  const groupRef = useRef(null);
+  const tooltipRef = useRef(null);
+  const textRef = useRef(null);
+  const [hovered, setHovered] = useState(null);
+  const [focused, setFocused] = useState(null);
+  const [leader, setLeader] = useState('pointer');
+  // Latest modality leads. The other keeps the bubble open after that one leaves the group.
+  const leading = leader === 'pointer' ? hovered : focused;
+  const trailing = leader === 'pointer' ? focused : hovered;
+  const active = leading ?? trailing;
+  const activeTrigger = active?.element ?? null;
+  const label = active?.label ?? '';
+  useLayoutEffect(() => {
+    const group = groupRef.current;
+    const tooltip = tooltipRef.current;
+    const text = textRef.current;
+    if (!activeTrigger || !group || !tooltip || !text) {
+      return;
+    }
+    const groupBox = group.getBoundingClientRect();
+    const triggerBox = activeTrigger.getBoundingClientRect();
+    const computed = getComputedStyle(tooltip);
+    const pad = Number.parseFloat(computed.paddingLeft) + Number.parseFloat(computed.paddingRight);
+    const width = Math.ceil(text.scrollWidth + pad);
+    const x = triggerBox.left - groupBox.left + triggerBox.width / 2 - width / 2;
+    tooltip.style.setProperty('--travel-tooltip-x', `${x}px`);
+    tooltip.style.width = `${width}px`;
+  }, [activeTrigger, label]);
+  const showForPointer = (trigger, nextLabel) => {
+    setHovered(arm(trigger, nextLabel));
+    setLeader('pointer');
+  };
+  const showForFocus = (trigger, nextLabel) => {
+    setFocused(arm(trigger, nextLabel));
+    setLeader('focus');
+  };
+  const hidePointerIfLeavingGroup = event => {
+    if (!leftTheGroup(event)) {
+      return false;
+    }
+    setHovered(null);
+    return true;
+  };
+  const hideFocusIfLeavingGroup = event => {
+    if (!leftTheGroup(event)) {
+      return false;
+    }
+    setFocused(null);
+    return true;
+  };
+  return {
+    activeTrigger,
+    groupRef,
+    hideFocusIfLeavingGroup,
+    hidePointerIfLeavingGroup,
+    label,
+    showForFocus,
+    showForPointer,
+    textRef,
+    tooltipRef
+  };
+}
+function TravelTooltipBubble({
+  animated,
+  id,
+  label,
+  show,
+  textRef,
+  tooltipRef
+}) {
+  return jsx("span", {
+    ref: tooltipRef,
+    "aria-hidden": show ? 'false' : 'true',
+    className: styles.tooltip,
+    "data-bp-animated": animated ? 'true' : 'false',
+    "data-show": show ? 'true' : 'false',
+    id: id,
+    role: "tooltip",
+    children: jsx("span", {
+      ref: textRef,
+      className: styles.text,
+      children: label
+    })
+  });
+}
+
+export { TravelTooltipBubble, useTravelTooltip };

package/dist/lib-esm/tooltip/travel-tooltip.module.js

@@ -0,0 +1,4 @@
+import '../index.css';
+var styles = {"tooltip":"bp_travel_tooltip_module_tooltip--37a55","text":"bp_travel_tooltip_module_text--37a55"};
+
+export { styles as default };

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.7.1",
+    "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.6",
+        "@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.25",
+        "@box/storybook-utils": "^1.4.27",
         "@figma/code-connect": "1.4.4",
         "@playwright/test": "1.46.1",
         "@types/js-yaml": "^4.0.9",