packages/core/src/lib/transitions/common.ts
This is the source snapshot used to build these API details. View this revision on GitHub.
1 import { blur, opacity } from '../../filters/native.js';
2 import { defineTransitionEffect, type PibblTransitionEffect } from './fade.js';
3 import { captureTransition, finite, regionSnapshot, seededNoise, type CaptureFrame, type TransitionRegion } from './capture.js';
4
5 /**
6 * Direction and displacement controls for a sliding visibility transition.
7 *
8 * @see {@link slide}
9 */
10 export interface PibblSlideOptions {
11 /**
12 * Horizontal coordinate or displacement in the containing coordinate system. See
13 * {@link PibblSlideOptions}.
14 */
15 readonly x?: number;
16 /**
17 * Vertical coordinate or displacement in the containing coordinate system. See
18 * {@link PibblSlideOptions}.
19 */
20 readonly y?: number;
21 }
22 /**
23 * Scale controls for a zooming visibility transition.
24 *
25 * @see {@link zoom}
26 */
27 export interface PibblZoomOptions {
28 /** Origin of the transform or geometric query. See {@link PibblZoomOptions}. */
29 readonly origin: Readonly<{
30 /**
31 * Horizontal coordinate or displacement in the containing coordinate system. See
32 * {@link PibblZoomOptions}.
33 */
34 x: number;
35 /**
36 * Vertical coordinate or displacement in the containing coordinate system. See
37 * {@link PibblZoomOptions}.
38 */
39 y: number;
40 }>;
41 /** Starting endpoint or value. See {@link PibblZoomOptions}. */
42 readonly from?: number;
43 }
44 /**
45 * Direction and clipping controls for a wiping visibility transition.
46 *
47 * @see {@link wipe}
48 */
49 export interface PibblWipeOptions {
50 /** Logical region over which the effect is evaluated. See {@link TransitionRegion}. */
51 readonly region: TransitionRegion;
52 /** Direction in which this operation proceeds. See {@link PibblWipeOptions}. */
53 readonly direction?: 'left' | 'right' | 'top' | 'bottom';
54 }
55 /**
56 * Blur controls for a visibility reveal transition.
57 *
58 * @see {@link blurReveal}
59 */
60 export interface PibblBlurRevealOptions {
61 /**
62 * Radius in the coordinate system of this geometry or effect. See {@link PibblBlurRevealOptions}.
63 */
64 readonly radius?: number;
65 }
66 /**
67 * Noise and threshold controls for a dissolving visibility transition.
68 *
69 * @see {@link dissolve}
70 */
71 export interface PibblDissolveOptions {
72 /** Logical region over which the effect is evaluated. See {@link TransitionRegion}. */
73 readonly region: TransitionRegion;
74 /** Size of the dissolve noise cells. See {@link PibblDissolveOptions}. */
75 readonly cellSize?: number;
76 /**
77 * Seed used for deterministic sampling or simulation initialization. See
78 * {@link PibblDissolveOptions}.
79 */
80 readonly seed?: number;
81 }
82 const captured = (draw: (frame: CaptureFrame, progress: number) => void) => defineTransitionEffect(q => q === 1 ? [] : q === 0 ? [opacity({ amount: 0 })] : [captureTransition(frame => draw(frame, q))]);
83 /**
84 * Translate from an offset while fading; exit follows the same path backward.
85 *
86 * @param options - Slide direction and displacement settings; defaults apply when omitted. See
87 * {@link PibblSlideOptions} .
88 * @returns A slide transition effect. See {@link PibblTransitionEffect}.
89 *
90 * @see {@link PibblSlideOptions}
91 * @see {@link PibblTransitionEffect}
92 */
93 export function slide(options: PibblSlideOptions = {}): PibblTransitionEffect {
94 const x = finite(options.x ?? 0, 'x'), y = finite(options.y ?? 24, 'y');
95 return captured(({ context, drawSource }, q) => { context.translate(x * (1 - q), y * (1 - q)); context.globalAlpha = q; drawSource(); });
96 }
97 /**
98 * Scale around an explicit local origin while fading.
99 *
100 * @param options - Zoom scale and origin settings. See {@link PibblZoomOptions}.
101 * @returns A zoom transition effect. See {@link PibblTransitionEffect}.
102 *
103 * @see {@link PibblZoomOptions}
104 * @see {@link PibblTransitionEffect}
105 */
106 export function zoom(options: PibblZoomOptions): PibblTransitionEffect {
107 const x = finite(options.origin.x, 'origin.x'), y = finite(options.origin.y, 'origin.y'), from = finite(options.from ?? .8, 'from', 0);
108 return captured(({ context: c, drawSource }, q) => { const scale = from + (1 - from) * q; c.translate(x, y); c.scale(scale, scale); c.translate(-x, -y); c.globalAlpha = q; drawSource(); });
109 }
110 /**
111 * Reveal from one side of an explicit local region.
112 *
113 * @param options - Wipe direction and shape settings. See {@link PibblWipeOptions}.
114 * @returns A wipe transition effect. See {@link PibblTransitionEffect}.
115 *
116 * @see {@link PibblWipeOptions}
117 * @see {@link PibblTransitionEffect}
118 */
119 export function wipe(options: PibblWipeOptions): PibblTransitionEffect {
120 const r = regionSnapshot(options.region), direction = options.direction ?? 'left';
121 if (!['left', 'right', 'top', 'bottom'].includes(direction)) throw new TypeError('Unknown wipe direction.');
122 return captured(({ context: c, drawSource }, q) => {
123 const vertical = direction === 'top' || direction === 'bottom';
124 const width = vertical ? r.width : r.width * q, height = vertical ? r.height * q : r.height;
125 c.beginPath(); c.rect(r.x + (direction === 'right' ? r.width - width : 0), r.y + (direction === 'bottom' ? r.height - height : 0), width, height); c.clip(); drawSource();
126 });
127 }
128 /**
129 * Resolve from a soft transparent image into crisp content using native filters.
130 *
131 * @param options - Blur settings; defaults apply when omitted. See {@link PibblBlurRevealOptions}.
132 * @returns A blur-reveal transition effect. See {@link PibblTransitionEffect}.
133 *
134 * @see {@link PibblBlurRevealOptions}
135 * @see {@link PibblTransitionEffect}
136 */
137 export function blurReveal(options: PibblBlurRevealOptions = {}): PibblTransitionEffect {
138 const radius = finite(options.radius ?? 16, 'radius', 0);
139 return defineTransitionEffect(q => q === 1 ? [] : [blur({ radius: radius * (1 - q) }), opacity({ amount: q })]);
140 }
141 /**
142 * A deterministic scattered reveal. Cell size is a minimum; the grid is capped at 128×128.
143 *
144 * @param options - Dissolve sampling and appearance settings. See {@link PibblDissolveOptions}.
145 * @returns A dissolve transition effect. See {@link PibblTransitionEffect}.
146 *
147 * @see {@link PibblDissolveOptions}
148 * @see {@link PibblTransitionEffect}
149 */
150 export function dissolve(options: PibblDissolveOptions): PibblTransitionEffect {
151 const r = regionSnapshot(options.region), size = finite(options.cellSize ?? 5, 'cellSize', 1), noise = seededNoise(finite(options.seed ?? 0, 'seed'));
152 const columns = Math.min(128, Math.ceil(r.width / size)), rows = Math.min(128, Math.ceil(r.height / size));
153 return captured(({ context: c, drawSource }, q) => {
154 c.beginPath();
155 for (let row = 0; row < rows; row++) for (let col = 0; col < columns; col++) if (noise(row * columns + col) < q) c.rect(r.x + col * r.width / columns, r.y + row * r.height / rows, r.width / columns, r.height / rows);
156 c.clip(); drawSource();
157 });
158 }
159 Documentation version
Section titled “Documentation version”Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.