@atlaskit/icon
Version:
An icon is a symbol representing a command, device, directory, or common action.
53 lines (52 loc) • 2.88 kB
TypeScript
import { type Ref } from 'react';
import type { AnimatedIconRef } from '../types';
/**
* One step of a motion timeline: `phase` is returned by the hook for `durationMs`.
*/
export type MotionStep<P extends string> = {
phase: P;
durationMs: number;
};
export type AnimatedIconPlaybackOptions = {
/**
* When `true`, a motion started by a trigger plays its whole timeline even if the trigger goes inactive
* part way (for example the pointer leaves). The trigger's `reset()` is then called once the timeline ends.
* Defaults to `false`: the motion is cancelled immediately.
*/
nonInterruptible?: boolean;
};
/**
* Shared playback control for animated icons: "play once, guarded, interruptible".
*
* - `reanimate()` on the ref starts a motion. It is ignored while one is already playing.
* - When an `AnimatedIconTrigger` above becomes active, the icon plays once, then tells the trigger it is done.
* The trigger clears once every icon it started is done, so icons of different durations all play through.
* - When the trigger goes inactive mid-motion, the motion is cancelled immediately, unless the icon passes
* `{ nonInterruptible: true }`, in which case the whole timeline plays and the trigger is told at the end.
*
* A motion is a timeline of steps that run back to back. The hook returns the name of the current step's
* phase, or `undefined` when idle, and the icon maps each phase to styles. The second value, `lastPhase`, is the
* phase that was active when the motion finished or was interrupted (`undefined` before the first motion), for
* the rare icon that must keep part of a phase's styles after going idle. Most icons only need `[phase]`. A hold is just a step whose
* phase the icon styles the same as the one before it.
*
* ```ts
* const TIMELINE = [
* { phase: 'shade', durationMs: 700 },
* { phase: 'hold', durationMs: 100 },
* { phase: 'redraw', durationMs: 600 },
* ] as const;
* ```
*
* When the user prefers reduced motion nothing plays: the phase stays `undefined`, so icons never need their own
* reduced motion CSS. The trigger is still told the icon is done straight away so it doesn't stay active.
*
* Call this once per icon. A second call with the same ref overwrites `reanimate()` and starts a second timer;
* model overlapping effects as phases of one timeline instead.
*
* `timeline` must be a module-level constant. A new array on every render would change `play`, re-run the
* trigger effect and cancel the motion.
*
* To write a new animated icon: define the glyph, the timeline, and a style for each phase.
*/
export declare const useAnimatedIconPlayback: <P extends string>(ref: Ref<AnimatedIconRef> | undefined, timeline: readonly MotionStep<P>[], { nonInterruptible }?: AnimatedIconPlaybackOptions) => readonly [phase: P | undefined, lastPhase: P | undefined];