Repository navigation
Expand file tree
/
Copy pathllms.txt
More file actions
311 lines (235 loc) · 7.45 KB
/
Copy pathllms.txt
File metadata and controls
311 lines (235 loc) · 7.45 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
# ThanosFx
ThanosFx is a zero-dependency WebGL2 library that burns and reassembles real DOM elements. It captures the element as a texture, renders a full-screen overlay, and animates the element with GPU particles. The underlying DOM is left untouched until the effect finishes.
Use it for delete/recycle transitions, destructive actions, and assemble/reveal moments.
## Requirements
- A browser with WebGL2.
- Client-side JavaScript or TypeScript.
- The target must be an `HTMLElement` attached to the document and visible when the effect starts.
- Wait for images and fonts to load before capturing if they are part of the element.
- The library is DOM-only. It does not render to canvas/WebGL scenes.
## Install
```sh
npm install thanosfx
```
React is optional and only needed for the `thanosfx/react` entry point:
```sh
npm install react
```
## Import
```ts
import { assemble, burn, createEffect, effectNames, playEffect } from "thanosfx";
import type {
AttractorLike,
EffectHandle,
EffectName,
EffectOptions,
RectLike,
} from "thanosfx";
```
## API
### `burn(target, options?)`
Burns the element into dust.
```ts
const handle = burn(card, {
duration: 1700,
attractTo: bin,
attractStrength: 0.9,
attractSwirl: 0.3,
collision: false,
});
```
### `assemble(target, options?)`
Burn played backwards. Dust gathers and the element appears.
```ts
assemble(card, {
duration: 1800,
attractTo: addButton,
removeTarget: false,
});
```
### `playEffect(target, effect, options?)`
Starts an effect by name: `"burn"` or `"assemble"`.
```ts
playEffect(card, "burn", { duration: 1200 });
```
### `createEffect(target, effect, options?)`
Generic form of `playEffect`.
```ts
createEffect(card, "assemble", { removeTarget: false });
```
### `effectNames`
`["burn", "assemble"]`
### `EffectHandle`
Every call returns an `EffectHandle`:
```ts
interface EffectHandle {
readonly promise: Promise<void>;
cancel(): void;
}
```
- `promise` resolves when the effect finishes or is cancelled.
- `cancel()` stops the animation and restores the target.
## Options
```ts
interface EffectOptions {
duration?: number; // milliseconds
removeTarget?: boolean; // burn defaults to true, assemble to false
dpr?: number; // device pixel ratio override
reducedMotion?: "auto" | "allow" | "reduce";
burnMs?: number;
density?: number;
gravity?: number;
bounce?: number;
spread?: number;
life?: number;
friction?: number;
lift?: number;
particleScale?: number;
embers?: boolean;
collision?: boolean;
mode?: "sweep" | "instant";
collideWith?: RectLike[];
attractTo?: AttractorLike | null;
attractStrength?: number; // 0–1
attractSwirl?: number; // negative reverses the curl
}
```
Library defaults:
| Option | Default |
| ------------------ | ----------------------- |
| `duration` | `1700` burn, `1800` assemble |
| `removeTarget` | `true` burn, `false` assemble |
| `dpr` | automatic, capped at 2 |
| `reducedMotion` | `"auto"` |
| `burnMs` | `200` |
| `density` | `0.9` |
| `gravity` | `3200` |
| `bounce` | `0.32` |
| `spread` | `210` |
| `life` | `1` |
| `friction` | `0.66` |
| `lift` | `190` |
| `particleScale` | `1` |
| `embers` | `true` |
| `collision` | `true` |
| `mode` | `"sweep"` |
| `collideWith` | `[]` |
| `attractTo` | `null` |
| `attractStrength` | `0.7` |
| `attractSwirl` | `0.35` |
## Particle modes
### Collision
Dust bounces off the listed elements or rects.
```ts
const cards = [...document.querySelectorAll<HTMLElement>(".task")];
const card = cards[0];
if (!card) throw new Error("Missing task");
await burn(card, {
collision: true,
collideWith: cards.filter((element) => element !== card),
}).promise;
```
### Attract
Dust spirals into an element, rect, or point.
```ts
const bin = document.querySelector<HTMLElement>(".recycle-bin")!;
await burn(card, {
attractTo: bin,
attractStrength: 0.9,
attractSwirl: 0.3,
collision: false,
}).promise;
```
`attractTo` accepts:
- an `Element`
- a `DOMRect`
- `{ left, top, width, height }`
- `[x, y, width, height]`
- `{ x, y }`
- `[x, y]`
### Dissolve
No collision and no attractor. Dust falls and drifts away.
```ts
await burn(card, {
collision: false,
gravity: 450,
spread: 240,
lift: 210,
}).promise;
```
## Recommended cleanup pattern
For delete/recycle flows, keep the element in the layout until the effect finishes:
```ts
const card = document.querySelector<HTMLElement>(".task")!;
const bin = document.querySelector<HTMLElement>(".recycle-bin")!;
const handle = burn(card, {
attractTo: bin,
collision: false,
removeTarget: false,
});
await handle.promise;
card.remove();
```
`removeTarget: false` prevents the library from removing the element before your layout logic runs. If a row should keep its space reserved during the effect, leave it in place and remove it after the promise resolves.
For assemble flows, keep `removeTarget: false` so the element remains visible after the dust gathers.
## React
```tsx
import { useRef } from "react";
import { useThanosFx } from "thanosfx/react";
export function DeleteCard() {
const ref = useRef<HTMLDivElement>(null);
const { play, cancel } = useThanosFx(ref, "burn", {
attractTo: document.querySelector<HTMLElement>(".recycle-bin"),
collision: false,
removeTarget: false,
});
return (
<div ref={ref}>
<button onClick={() => void play()?.promise.then(() => ref.current?.remove())}>
Delete
</button>
<button onClick={cancel}>Cancel</button>
</div>
);
}
```
`useThanosFx(ref, effect, options)` returns:
```ts
{
play(): EffectHandle | null;
cancel(): void;
}
```
The `ThanosFx` component is also available:
```tsx
import { ThanosFx } from "thanosfx/react";
<ThanosFx effect="burn" options={{ duration: 1700 }} autoPlay>
<div className="card">Delete me</div>
</ThanosFx>;
```
## Reduced motion and WebGL2
- `reducedMotion: "auto"` honors `prefers-reduced-motion`.
- `"reduce"` forces the short opacity fallback.
- `"allow"` forces the full particle effect.
- If WebGL2 is unavailable, the effect cannot run. Let the promise reject or fall back to your own fade.
## Troubleshooting
**Nothing happens**
- Check that the target is an `HTMLElement` in the document.
- Check that the target has a non-zero size.
- Check that WebGL2 is available.
- Make sure the element is not `display: none` or `visibility: hidden`.
**Images are missing from the effect**
- Wait for images to decode before starting.
- Cross-origin images can prevent canvas capture. Use same-origin images or data URLs.
- If an optional global `html2canvas` is present, ThanosFx uses it; otherwise it uses an SVG `foreignObject` snapshot.
**The layout jumps**
- Use `removeTarget: false`.
- Keep the element in place until `handle.promise` resolves.
- Remove the element yourself after the effect.
**The target disappears immediately**
- Check the `removeTarget` option.
- Check whether `cancel()` was called.
## Links
- Live demo: https://ehsania.github.io/thanosfx/
- Repository: https://github.com/ehsania/thanosfx
- npm: https://www.npmjs.com/package/thanosfx