@atlaskit/motion
Version:
A set of utilities to apply motion in your application.
91 lines (90 loc) • 4.28 kB
TypeScript
/**
* @jsxRuntime classic
* @jsx jsx
*/
import { type ForwardRefExoticComponent, type ReactElement, type RefAttributes } from 'react';
import type { XCSSProp } from '@compiled/react';
import { type XCSSAllProperties, type XCSSAllPseudos } from '@atlaskit/css';
import { type MotionIconography } from '@atlaskit/tokens/css-type-schema';
import { type Transition } from './types';
export interface IconMotionProps {
/**
* The icon to render. When the icon changes (a different icon component, or a different `key`),
* the previous icon plays `exitingAnimation`, then the new icon plays `enteringAnimation`.
*
* Passing nothing (`isOpen && <Icon />`) removes the icon, so it plays `exitingAnimation`, and
* passing an icon again plays `enteringAnimation`.
*
* Pass the icon element itself. A swap is detected from the element's type and `key`, so a
* wrapper component that renders different icons internally won't trigger an animation.
*
* Inside an `IconButton`, return `IconMotion` from the `icon` render function and spread the
* props the button passes onto the icon, so its colour and size still apply. The button also passes
* a `motionOvershoot` that matches its `spacing`, which is for `IconMotion` and not the icon:
* `icon={({ motionOvershoot, ...iconProps }) => <IconMotion overshoot={motionOvershoot}>{isOpen ? <UpIcon {...iconProps} /> : <DownIcon {...iconProps} />}</IconMotion>}`
*/
children: ReactElement | false | null | undefined;
/**
* Motion token played by an icon as it appears.
*/
enteringAnimation?: MotionIconography;
/**
* Motion token played by an icon as it disappears.
*/
exitingAnimation?: MotionIconography;
/**
* When `true`, the initial icon plays `enteringAnimation` on first render.
* By default the initial icon is shown without animating.
*/
shouldAppear?: boolean;
/**
* Called when an icon has finished entering or exiting.
*/
onFinish?: (state: Transition) => void;
/**
* A `testId` prop is provided for specified elements,
* which is a unique string that appears as a data attribute `data-testid` in the rendered code,
* serving as a hook for automated tests.
*/
testId?: string;
/**
* How far past its own box the icon travels, and how far the clip around the icon extends, as a
* CSS length. Use a space token, such as `token('space.100')`.
*
* This only applies to the `cycle` motion tokens (`motion.iconography.enter.cycle.*` and
* `motion.iconography.exit.cycle.*`), which slide the icon out of its box. Other motions ignore it.
* The icon is always clipped to its box, so `overshoot` is how far the clip is widened to match the
* space around the icon, such as the padding of the button it sits in.
*/
overshoot?: string;
/**
* When `true`, the icon being replaced finishes exiting before the new icon enters. When `false`,
* the new icon enters while the old icon exits, with the two overlaid in the same spot.
*/
shouldExitThenEnter?: boolean;
}
/**
* Props of `IconMotionBase` that the public `IconMotion` does not expose. Effects such as
* `IconMotion.Rotate` use them to style the root element without wrapping it in another element.
*/
export interface IconMotionBaseProps extends IconMotionProps {
xcss?: XCSSProp<XCSSAllProperties, XCSSAllPseudos>;
}
/**
* What `IconMotion` exposes through its `ref`.
*/
export interface IconMotionHandle {
/**
* Plays the exit and enter animations of the current icon again, by swapping in a fresh copy of
* it. It follows `shouldExitThenEnter`: the icon exits and then enters again when it is `true`, and the
* two copies overlay when it is `false`. It does nothing visible when no icon is rendered.
*/
reanimate: () => void;
}
/**
* Animates an icon when it is swapped for a different one, using the `motion.iconography` tokens.
* The icon being replaced plays `exitingAnimation`, and once it has finished the new icon plays
* `enteringAnimation`.
*/
declare const IconMotionBase: ForwardRefExoticComponent<IconMotionBaseProps & RefAttributes<IconMotionHandle>>;
export default IconMotionBase;