packages/core/src/lib/transitions/fade.ts
This is the source snapshot used to build these API details. View this revision on GitHub.
1 import type { PibblVisibilityTransitionOptions } from '../hooks/use-visibility-transition.js';
2 import type { embers } from './embers.js';
3 import { opacity } from '../../filters/native.js';
4 import type { PibblFilter } from '../style/filter-types.js';
5
6 declare const effectBrand: unique symbol;
7 /**
8 * Immutable, inert visual definition; mounted state belongs to its controller.
9 *
10 * @see {@link fade}
11 * @see {@link PibblVisibilityTransitionOptions}
12 * @see {@link embers}
13 */
14 export interface PibblTransitionEffect { readonly [effectBrand]: true }
15 export interface TransitionFrame {
16 readonly active: boolean;
17 readonly elapsed: number;
18 readonly progressAt: (elapsed: number) => number;
19 }
20 export type TransitionSampler = (progress: number, phase: 'enter' | 'exit', frame: TransitionFrame) => readonly PibblFilter[];
21 const definitions = new WeakMap<PibblTransitionEffect, { sample: TransitionSampler; tail: number; create?: () => TransitionRuntime }>();
22 /**
23 * A uniform fade of the receiving primitive and all of its descendants together.
24 *
25 * @returns A fade effect to use with a visibility transition. See {@link PibblTransitionEffect}.
26 *
27 * @see {@link PibblTransitionEffect}
28 */
29 export function fade(): PibblTransitionEffect {
30 return defineTransitionEffect(progress => progress === 1 ? [] : [opacity({ amount: progress })]);
31 }
32 export function transitionEffectSampler(definition: PibblTransitionEffect): TransitionSampler {
33 const record = definitions.get(definition);
34 if (!record) throw new TypeError('Expected a Pibbl transition effect definition.');
35 return record.sample;
36 }
37
38 /** @internal Shared registration for first-party definitions. */
39 export function defineTransitionEffect(sample: TransitionSampler, tail = 0, create?: () => TransitionRuntime): PibblTransitionEffect {
40 const definition = Object.freeze({}) as PibblTransitionEffect;
41 definitions.set(definition, { sample, tail, create });
42 return definition;
43 }
44
45 export function transitionEffectTail(definition: PibblTransitionEffect): number {
46 transitionEffectSampler(definition);
47 return definitions.get(definition)!.tail;
48 }
49
50 /** Private controller-owned state for effects that simulate during Advance. */
51 export interface TransitionRuntime {
52 readonly sample: TransitionSampler;
53 advance?(elapsed: number, progressAt: (time: number) => number): void;
54 reset?(): void;
55 dispose?(): void;
56 }
57 export function createTransitionRuntime(effect: PibblTransitionEffect): TransitionRuntime {
58 const sample = transitionEffectSampler(effect);
59 return definitions.get(effect)!.create?.() ?? { sample };
60 }
61 Documentation version
Section titled “Documentation version”Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.