UNPKG

@atlaskit/icon

Version:

An icon is a symbol representing a command, device, directory, or common action.

53 lines (52 loc) • 2.88 kB
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];