@cleartrip/ct-design-floating-wrapper 1.11.0 → 5.27.0-SNAPSHOT-native-main.14

package/src/FloatingWrapper.native.tsx

@@ -0,0 +1,46 @@
+import Animated from 'react-native-reanimated';
+import { GestureDetector } from 'react-native-gesture-handler';
+import { makeStyles } from '@cleartrip/ct-design-style-manager';
+
+import { useDraggable } from './hooks/useDraggable.native';
+import type { IFloatingWrapperProps } from './type';
+
+const staticStyles = makeStyles(() => ({
+  root: {
+    position: 'absolute',
+    top: 0,
+    left: 0,
+    zIndex: 100,
+  },
+  hidden: {
+    display: 'none',
+  },
+}));
+
+/**
+ * Native counterpart of the web `FloatingWrapper`. Renders a draggable,
+ * edge-snapping overlay. There is no `position: fixed` in React Native, so the
+ * widget is `position: absolute` and must be mounted inside a full-screen parent
+ * (or the design-system `Portal`) for a true overlay. The app root must also be
+ * wrapped in `GestureHandlerRootView`.
+ */
+const FloatingWrapper = (props: IFloatingWrapperProps) => {
+  const { children, show = true } = props;
+  const { gesture, animatedStyle, onLayout } = useDraggable(props);
+
+  // Stay mounted while hidden (via `display: none`) so the dragged coordinates
+  // are retained and the widget re-opens where the user last left it.
+  return (
+    <GestureDetector gesture={gesture}>
+      <Animated.View
+        onLayout={onLayout}
+        pointerEvents={show ? 'auto' : 'none'}
+        style={[staticStyles.root, animatedStyle, !show && staticStyles.hidden]}
+      >
+        {children}
+      </Animated.View>
+    </GestureDetector>
+  );
+};
+
+export default FloatingWrapper;

package/src/FloatingWrapper.tsx

@@ -0,0 +1,54 @@
+import { type CSSProperties } from 'react';
+import { makeStyles, useWebMergeStyles } from '@cleartrip/ct-design-style-manager';
+
+import { useDraggable } from './hooks/useDraggable';
+import type { IFloatingWrapperProps } from './type';
+
+const staticStyles = makeStyles(() => ({
+  root: {
+    position: 'fixed',
+    top: 0,
+    left: 0,
+    willChange: 'transform',
+    touchAction: 'none',
+    userSelect: 'none',
+    WebkitUserSelect: 'none',
+    WebkitTapHighlightColor: 'transparent',
+    zIndex: 100,
+  },
+}));
+
+const FloatingWrapper = (props: IFloatingWrapperProps) => {
+  const { children, disabled = false, show = true } = props;
+
+  const { bind, position, isReady, canAnimate } = useDraggable(props);
+
+  const rootClassName = useWebMergeStyles([staticStyles.root], []);
+
+  /**
+   * Resting style only. The drag path (cursor / transition / transform) is
+   * written straight to the element by `useDraggable` to avoid re-renders.
+   */
+  const dynamicStyle: CSSProperties = {
+    transform: `translate(${position.x}px, ${position.y}px)`,
+    cursor: disabled ? 'default' : 'grab',
+    // Skip the transition for the very first placement so the widget shows
+    // up at its resting corner instead of sliding in from `(0,0)`.
+    transition: canAnimate ? 'transform 200ms ease-out' : 'none',
+    // Keep it hidden until measured/positioned to avoid a `(0,0)` flash.
+    visibility: isReady ? undefined : 'hidden',
+    // Hide via CSS (instead of unmounting) so the dragged coordinates are
+    // retained and the widget re-opens where the user last left it.
+    display: show ? undefined : 'none',
+    // Disable interaction while hidden so it can't be clicked.
+    pointerEvents: show ? undefined : 'none',
+  };
+
+  return (
+    <div {...bind} className={rootClassName} style={dynamicStyle}>
+      {children}
+    </div>
+  );
+};
+
+export default FloatingWrapper;

package/src/hooks/useDraggable.native.ts

@@ -0,0 +1,191 @@
+import { useCallback, useEffect } from 'react';
+import { Dimensions, LayoutChangeEvent } from 'react-native';
+import { Gesture, GestureType } from 'react-native-gesture-handler';
+import { AnimatedStyle, Easing, runOnJS, useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated';
+
+import { IBounds, IFloatingWrapperProps, IPosition, InitialCorner } from '../type';
+
+const DEFAULT_EDGE_OFFSET = 8;
+const SNAP_DURATION = 200;
+
+const clampJS = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);
+
+const isExplicitBounds = (bounds: IFloatingWrapperProps['bounds']): bounds is IBounds =>
+  typeof bounds === 'object' && bounds !== null && 'top' in bounds;
+
+/**
+ * React Native drag/position engine behind `FloatingWrapper`. Mirrors the web
+ * `useDraggable`: tracks an `{ x, y }` translation, keeps the element inside its
+ * `bounds`, and (optionally) snaps to the nearest horizontal edge on release.
+ *
+ * The web build writes transforms straight to the DOM node; here the gesture math
+ * runs on the UI thread via Reanimated shared values, so React never re-renders
+ * during a drag.
+ */
+export const useDraggable = (
+  props: IFloatingWrapperProps,
+): { gesture: GestureType; animatedStyle: AnimatedStyle; onLayout: (event: LayoutChangeEvent) => void } => {
+  const {
+    bounds = 'viewport',
+    edgeOffset = DEFAULT_EDGE_OFFSET,
+    initialPosition = InitialCorner.BOTTOM_RIGHT,
+    snapToEdge = true,
+    disabled = false,
+    onTap,
+  } = props;
+
+  const tx = useSharedValue(0);
+  const ty = useSharedValue(0);
+  const startX = useSharedValue(0);
+  const startY = useSharedValue(0);
+  const width = useSharedValue(0);
+  const height = useSharedValue(0);
+  const ready = useSharedValue(false);
+
+  // Bounds + config mirrored into shared values so the pan worklet can read
+  // them on the UI thread without hopping back to JS.
+  const boundLeft = useSharedValue(0);
+  const boundTop = useSharedValue(0);
+  const boundRight = useSharedValue(0);
+  const boundBottom = useSharedValue(0);
+  const edge = useSharedValue(edgeOffset);
+  const snap = useSharedValue(snapToEdge);
+
+  const readRect = useCallback((): IBounds => {
+    if (isExplicitBounds(bounds)) {
+      return bounds;
+    }
+    // NOTE: element-ref bounds need an async measureInWindow pass; until that
+    // is wired up we fall back to the full viewport.
+    const { width: vw, height: vh } = Dimensions.get('window');
+    return { top: 0, left: 0, right: vw, bottom: vh };
+  }, [bounds]);
+
+  const syncBounds = useCallback(() => {
+    const rect = readRect();
+    boundLeft.value = rect.left;
+    boundTop.value = rect.top;
+    boundRight.value = rect.right;
+    boundBottom.value = rect.bottom;
+  }, [readRect, boundLeft, boundTop, boundRight, boundBottom]);
+
+  useEffect(() => {
+    edge.value = edgeOffset;
+    snap.value = snapToEdge;
+  }, [edgeOffset, snapToEdge, edge, snap]);
+
+  useEffect(() => {
+    syncBounds();
+    const subscription = Dimensions.addEventListener('change', syncBounds);
+    return () => subscription.remove();
+  }, [syncBounds]);
+
+  const onLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      const { width: w, height: h } = event.nativeEvent.layout;
+      // A hidden widget (`display: none` while `show` is false) measures 0x0.
+      // Keep the last real size so limits don't collapse to a zero-size box.
+      if (w === 0 && h === 0) {
+        return;
+      }
+
+      const firstMeasure = width.value === 0 && height.value === 0;
+      width.value = w;
+      height.value = h;
+
+      if (!firstMeasure) {
+        return;
+      }
+
+      const rect = readRect();
+      const minX = rect.left + edgeOffset;
+      const minY = rect.top + edgeOffset;
+      const maxX = Math.max(minX, rect.right - w - edgeOffset);
+      const maxY = Math.max(minY, rect.bottom - h - edgeOffset);
+
+      let resting: IPosition;
+      if (typeof initialPosition !== 'string') {
+        resting = {
+          x: clampJS(initialPosition.x, minX, maxX),
+          y: clampJS(initialPosition.y, minY, maxY),
+        };
+      } else {
+        switch (initialPosition) {
+          case InitialCorner.TOP_LEFT:
+            resting = { x: minX, y: minY };
+            break;
+          case InitialCorner.TOP_RIGHT:
+            resting = { x: maxX, y: minY };
+            break;
+          case InitialCorner.BOTTOM_LEFT:
+            resting = { x: minX, y: maxY };
+            break;
+          case InitialCorner.BOTTOM_RIGHT:
+          default:
+            resting = { x: maxX, y: maxY };
+        }
+      }
+
+      tx.value = resting.x;
+      ty.value = resting.y;
+      ready.value = true;
+    },
+    [readRect, edgeOffset, initialPosition, width, height, tx, ty, ready],
+  );
+
+  const panGesture = Gesture.Pan()
+    .enabled(!disabled)
+    .onStart(() => {
+      'worklet';
+      startX.value = tx.value;
+      startY.value = ty.value;
+    })
+    .onUpdate((gestureEvent) => {
+      'worklet';
+      const minX = boundLeft.value + edge.value;
+      const minY = boundTop.value + edge.value;
+      const maxX = Math.max(minX, boundRight.value - width.value - edge.value);
+      const maxY = Math.max(minY, boundBottom.value - height.value - edge.value);
+      tx.value = Math.min(Math.max(startX.value + gestureEvent.translationX, minX), maxX);
+      ty.value = Math.min(Math.max(startY.value + gestureEvent.translationY, minY), maxY);
+    })
+    .onEnd(() => {
+      'worklet';
+      const minX = boundLeft.value + edge.value;
+      const maxX = Math.max(minX, boundRight.value - width.value - edge.value);
+      let targetX = tx.value;
+
+      if (snap.value) {
+        const center = tx.value + width.value / 2;
+        const boxCenter = (boundLeft.value + boundRight.value) / 2;
+        targetX = center < boxCenter ? minX : maxX;
+      }
+
+      tx.value = withTiming(targetX, {
+        duration: SNAP_DURATION,
+        easing: Easing.out(Easing.ease),
+      });
+      ty.value = withTiming(ty.value, {
+        duration: SNAP_DURATION,
+        easing: Easing.out(Easing.ease),
+      });
+    });
+
+  const tapGesture = Gesture.Tap().onEnd((_event, success) => {
+    'worklet';
+    if (success && onTap) {
+      runOnJS(onTap)();
+    }
+  });
+
+  const gesture = Gesture.Race(panGesture, tapGesture);
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    transform: [{ translateX: tx.value }, { translateY: ty.value }],
+    // Keep it hidden until measured/positioned to avoid a `(0,0)` flash.
+    opacity: ready.value ? 1 : 0,
+  }));
+
+  // @ts-ignore
+  return { gesture, animatedStyle, onLayout };
+};

package/src/hooks/useDraggable.ts

@@ -0,0 +1,295 @@
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useSwipeable } from 'react-swipeable';
+
+import {
+  IBounds,
+  IFloatingWrapperProps,
+  IPosition,
+  IUseDraggableResult,
+  TBoundsInput,
+  TInitialCorner,
+  InitialCorner,
+} from '../type';
+
+const DEFAULT_EDGE_OFFSET = 8;
+const SNAP_TRANSITION = 'transform 200ms ease-out';
+
+const clamp = (value: number, min: number, max: number) => {
+  return Math.min(Math.max(value, min), max);
+};
+
+const isExplicitBounds = (bounds: TBoundsInput): bounds is IBounds => {
+  return typeof bounds === 'object' && bounds !== null && 'top' in bounds;
+};
+
+const isCorner = (position: IPosition | TInitialCorner): position is TInitialCorner => typeof position === 'string';
+
+const getViewportRect = (): IBounds => ({
+  top: 0,
+  left: 0,
+  right: typeof window === 'undefined' ? 0 : window.innerWidth,
+  bottom: typeof window === 'undefined' ? 0 : window.innerHeight,
+});
+
+const resolveBounds = (bounds: TBoundsInput | undefined): IBounds => {
+  if (!bounds || bounds === 'viewport') return getViewportRect();
+  if (isExplicitBounds(bounds)) return bounds;
+
+  const element = bounds.current;
+  if (!element) return getViewportRect();
+
+  const rect = element.getBoundingClientRect();
+  return {
+    top: rect.top,
+    left: rect.left,
+    right: rect.right,
+    bottom: rect.bottom,
+  };
+};
+
+interface ILimits {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+
+/**
+ * Drag/position engine behind `FloatingWidget`. Tracks an `{ x, y }` translation,
+ * keeps the element inside its `bounds`, and (optionally) snaps to the nearest
+ * horizontal edge when a drag ends.
+ */
+export const useDraggable = (props: IFloatingWrapperProps): IUseDraggableResult => {
+  const {
+    bounds = 'viewport',
+    edgeOffset = DEFAULT_EDGE_OFFSET,
+    initialPosition = InitialCorner.BOTTOM_RIGHT,
+    snapToEdge = true,
+    disabled = false,
+    show = true,
+    onTap,
+  } = props;
+
+  /**
+   * State for the position of the draggable element
+   */
+  const [position, setPosition] = useState<IPosition>({ x: 0, y: 0 });
+
+  /**
+   * Becomes `true` once the element has been measured and positioned. Used to
+   * keep it hidden until then so there's no `(0,0)` flash.
+   */
+  const [isReady, setIsReady] = useState(false);
+
+  /**
+   * Enabled one frame after the first placement so the initial position is
+   * applied without a transition (no slide-in), while subsequent moves (drag
+   * snap / resize re-clamp) still animate.
+   */
+  const [canAnimate, setCanAnimate] = useState(false);
+
+  /**
+   * Refs for the draggable element
+   */
+  const elementRef = useRef<HTMLElement | null>(null);
+  /**
+   * Refs for the size of the draggable element
+   */
+  const sizeRef = useRef({ width: 0, height: 0 });
+  /**
+   * Refs for the position of the draggable element
+   */
+  const positionRef = useRef(position);
+  /**
+   * Refs for the start position of the draggable element
+   */
+  const dragStartRef = useRef<IPosition>({ x: 0, y: 0 });
+  /**
+   * Refs for the initialized state of the draggable element
+   */
+  const isInitializedRef = useRef(false);
+  /**
+   * Last viewport width, used to tell an orientation change apart from a
+   * height-only resize.
+   */
+  const viewportWidthRef = useRef(0);
+
+  // Mirror the latest props/state into refs so the mount-only effect and the
+  // swipe handlers always read fresh values without re-subscribing.
+  positionRef.current = position;
+  const propsRef = useRef(props);
+  propsRef.current = { ...props, bounds, edgeOffset, initialPosition, snapToEdge, show };
+
+  const getLimits = (): ILimits => {
+    const rect = resolveBounds(propsRef.current.bounds);
+    const { width, height } = sizeRef.current;
+    const pad = propsRef.current.edgeOffset ?? DEFAULT_EDGE_OFFSET;
+    const minX = rect.left + pad;
+    const minY = rect.top + pad;
+    const maxX = Math.max(minX, rect.right - width - pad);
+    const maxY = Math.max(minY, rect.bottom - height - pad);
+    return { minX, minY, maxX, maxY };
+  };
+
+  const clampToLimits = (next: IPosition): IPosition => {
+    const { minX, minY, maxX, maxY } = getLimits();
+    return {
+      x: clamp(next.x, minX, maxX),
+      y: clamp(next.y, minY, maxY),
+    };
+  };
+
+  const snapToNearestEdge = (next: IPosition): IPosition => {
+    const clamped = clampToLimits(next);
+    if (!propsRef.current.snapToEdge) return clamped;
+
+    const rect = resolveBounds(propsRef.current.bounds);
+    const { minX, maxX } = getLimits();
+    const center = clamped.x + sizeRef.current.width / 2;
+    const boxCenter = (rect.left + rect.right) / 2;
+    return { ...clamped, x: center < boxCenter ? minX : maxX };
+  };
+
+  const resolveInitialPosition = (): IPosition => {
+    const { minX, minY, maxX, maxY } = getLimits();
+    const initial = propsRef.current.initialPosition ?? InitialCorner.BOTTOM_RIGHT;
+
+    if (!isCorner(initial)) return clampToLimits(initial);
+
+    switch (initial) {
+      case InitialCorner.TOP_LEFT:
+        return { x: minX, y: minY };
+      case InitialCorner.TOP_RIGHT:
+        return { x: maxX, y: minY };
+      case InitialCorner.BOTTOM_LEFT:
+        return { x: minX, y: maxY };
+      case InitialCorner.BOTTOM_RIGHT:
+      default:
+        return { x: maxX, y: maxY };
+    }
+  };
+
+  const applyTransform = (pos: IPosition) => {
+    const element = elementRef.current;
+    if (element) {
+      element.style.transform = `translate(${pos.x}px, ${pos.y}px)`;
+    }
+  };
+
+  const applyDragState = (dragging: boolean) => {
+    const element = elementRef.current;
+    if (!element) return;
+    element.style.cursor = disabled ? 'default' : dragging ? 'grabbing' : 'grab';
+    // Follow the finger 1:1 while dragging; animate the snap on release.
+    element.style.transition = dragging ? 'none' : SNAP_TRANSITION;
+  };
+
+  // Keep latest closures available to the mount-only effect below.
+  const clampRef = useRef(clampToLimits);
+  clampRef.current = clampToLimits;
+  const initRef = useRef(resolveInitialPosition);
+  initRef.current = resolveInitialPosition;
+
+  useLayoutEffect(() => {
+    const element = elementRef.current;
+    if (!element) return undefined;
+
+    const measure = () => {
+      const rect = element.getBoundingClientRect();
+      // A hidden widget (`display: none` while `show` is false) measures
+      // 0x0. Storing that would size every limit for a zero-width box and
+      // clamp the coordinates to the wrong corner, so keep the last real size.
+      if (rect.width === 0 && rect.height === 0) return;
+      sizeRef.current = { width: rect.width, height: rect.height };
+    };
+
+    // Leave the coordinates alone while hidden: the viewport is usually
+    // mid-resize (soft keyboard opening in a webview) and clamping against it
+    // would move the widget for the next time it's shown.
+    const reclamp = () => {
+      if (!propsRef.current.show) return;
+      setPosition((prev) => clampRef.current(prev));
+    };
+
+    measure();
+
+    if (!isInitializedRef.current) {
+      isInitializedRef.current = true;
+      setPosition(initRef.current());
+      setIsReady(true);
+    } else {
+      reclamp();
+    }
+
+    const resizeObserver = new ResizeObserver(() => {
+      measure();
+      reclamp();
+    });
+    resizeObserver?.observe(element);
+
+    viewportWidthRef.current = window?.innerWidth ?? 360;
+
+    const onWindowResize = () => {
+      if (window.innerWidth === viewportWidthRef.current) return;
+      viewportWidthRef.current = window?.innerWidth ?? 360;
+      measure();
+      reclamp();
+    };
+
+    window.addEventListener('resize', onWindowResize);
+
+    return () => {
+      resizeObserver?.disconnect();
+      window.removeEventListener('resize', onWindowResize);
+    };
+  }, []);
+
+  // Once the resting position is painted, enable the transition on the next
+  // frame so future moves animate but the initial placement does not.
+  useEffect(() => {
+    if (!isReady || canAnimate) return undefined;
+    const id = requestAnimationFrame(() => setCanAnimate(true));
+    return () => cancelAnimationFrame(id);
+  }, [isReady, canAnimate]);
+
+  const handlers = useSwipeable({
+    onSwipeStart: () => {
+      if (disabled) return;
+      dragStartRef.current = positionRef.current;
+      applyDragState(true);
+    },
+    onSwiping: (eventData) => {
+      if (disabled) return;
+      const start = dragStartRef.current;
+      const next = clampToLimits({
+        x: start.x + eventData.deltaX,
+        y: start.y + eventData.deltaY,
+      });
+      positionRef.current = next;
+      applyTransform(next);
+    },
+    onSwiped: () => {
+      if (disabled) return;
+      applyDragState(false);
+      const resting = snapToNearestEdge(positionRef.current);
+      positionRef.current = resting;
+      setPosition(resting);
+    },
+    onTap: () => {
+      onTap?.();
+    },
+    trackMouse: true,
+    trackTouch: true,
+    preventScrollOnSwipe: true,
+  });
+
+  const bind: IUseDraggableResult['bind'] = {
+    ...handlers,
+    ref: (element: HTMLElement | null) => {
+      handlers.ref(element);
+      elementRef.current = element;
+    },
+  };
+
+  return { bind, position, isReady, canAnimate };
+};

package/src/index.native.ts

@@ -0,0 +1,3 @@
+export { default as FloatingWrapper } from './FloatingWrapper';
+export { useDraggable } from './hooks/useDraggable';
+export * from './type';

package/src/index.ts

@@ -0,0 +1,3 @@
+export { default as FloatingWrapper } from './FloatingWrapper';
+export { useDraggable } from './hooks/useDraggable';
+export * from './type';

package/src/style.ts

@@ -0,0 +1,18 @@
+import { CSSProperties } from 'react';
+import { Theme } from '@cleartrip/ct-design-theme';
+
+export const getFloatingWidgetStyle = (theme: Theme): Record<string, CSSProperties> => {
+  return {
+    root: {
+      position: 'fixed',
+      top: 0,
+      left: 0,
+      willChange: 'transform',
+      touchAction: 'none',
+      userSelect: 'none',
+      WebkitUserSelect: 'none',
+      WebkitTapHighlightColor: 'transparent',
+      zIndex: 100,
+    },
+  };
+};

package/src/type.ts

@@ -0,0 +1,86 @@
+import type { ReactNode, RefObject } from 'react';
+
+/**
+ * A rectangular region expressed in viewport (fixed) coordinates
+ */
+export interface IBounds {
+  top: number;
+  left: number;
+  right: number;
+  bottom: number;
+}
+
+/**
+ * The "viewbox" the consumer can constrain the floating widget to.
+ *  - `"viewport"` (default): the full browser window.
+ *  - `IBounds`: an explicit rectangle in viewport coordinates.
+ *  - a ref to an element: the element's live bounding box is used as the box.
+ */
+export type TBoundsInput = 'viewport' | IBounds | RefObject<HTMLElement | null>;
+
+export interface IPosition {
+  x: number;
+  y: number;
+}
+
+export enum InitialCorner {
+  TOP_LEFT = 'top-left',
+  TOP_RIGHT = 'top-right',
+  BOTTOM_LEFT = 'bottom-left',
+  BOTTOM_RIGHT = 'bottom-right',
+}
+
+export type TInitialCorner = `${InitialCorner}`;
+
+export interface IFloatingWrapperProps {
+  /** The widget that should be made floating / draggable. */
+  children: ReactNode;
+  /**
+   * Region the widget is allowed to be placed within.
+   * Defaults to the full viewport.
+   */
+  bounds?: TBoundsInput;
+  /** Gap (px) kept between the widget and the edges of `bounds`. Default `8`. */
+  edgeOffset?: number;
+  /**
+   * Where the widget rests initially - either an absolute `{ x, y }` (relative
+   * to `bounds`'s coordinate space) or a corner keyword. Default `"bottom-right"`.
+   */
+  initialPosition?: IPosition | TInitialCorner;
+  /**
+   * Snap to the nearest left/right edge after a drag ends, like iOS
+   * AssistiveTouch. Default `true`.
+   */
+  snapToEdge?: boolean;
+  /** When `true` the widget cannot be dragged. Default `false`. */
+  disabled?: boolean;
+  /**
+   * Controls the widget's visibility. When toggled back to `true` the widget
+   * reappears at its last dragged position (the component stays mounted, so
+   * its coordinates are preserved). Default `true`.
+   */
+  show?: boolean;
+  /** Fired on tap / click (a touch that stayed under the drag threshold). */
+  onTap?: () => void;
+}
+
+export interface IUseDraggableResult {
+  /** Props to spread on the floating element (ref + pointer handlers). */
+  bind: {
+    ref: (element: HTMLElement | null) => void;
+    onMouseDown?: (event: React.MouseEvent) => void;
+  };
+  /** Current translation applied to the element. */
+  position: IPosition;
+  /**
+   * `false` until the widget has been measured and placed at its initial
+   * position. Use it to keep the widget hidden so there's no `(0,0)` flash.
+   */
+  isReady: boolean;
+  /**
+   * `false` for the first painted frame and `true` afterwards. Use it to gate
+   * the CSS transition so the initial placement is instant (no slide-in from
+   * `(0,0)`), while later moves (drag snap / resize) still animate.
+   */
+  canAnimate: boolean;
+}