poltrgeist 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +92 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# poltrgeist
|
|
2
|
+
|
|
3
|
+
Funny, non-annoying UI/UX effects for any web page. Buttons explode, elements shy away from your cursor, words go Lovecraftian — but everything stays functional.
|
|
4
|
+
|
|
5
|
+
Zero dependencies. ~19 KB ESM.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install poltrgeist
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Usage
|
|
14
|
+
|
|
15
|
+
### Auto-haunt (scan the DOM automatically)
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
import { poltrgeist } from 'poltrgeist'
|
|
19
|
+
|
|
20
|
+
poltrgeist.haunt({
|
|
21
|
+
probability: 0.15,
|
|
22
|
+
effects: ['explode', 'shy', 'wobble'],
|
|
23
|
+
respectReducedMotion: true,
|
|
24
|
+
})
|
|
25
|
+
|
|
26
|
+
// stop all effects
|
|
27
|
+
poltrgeist.release()
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### Programmatic
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
poltrgeist.apply('#my-button', 'explode')
|
|
34
|
+
poltrgeist.apply(document.querySelectorAll('p'), 'wobble')
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
### Declarative HTML attribute
|
|
38
|
+
|
|
39
|
+
```html
|
|
40
|
+
<button data-poltrgeist="explode shy">Click me</button>
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Effects
|
|
44
|
+
|
|
45
|
+
| Effect | Trigger | Description |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| `explode` | click | Particle burst on click |
|
|
48
|
+
| `shy` | hover | Element drifts away from the cursor |
|
|
49
|
+
| `yeet` | click | Clone flies off-screen; original snaps back |
|
|
50
|
+
| `wobble` | hover | Characters wave individually |
|
|
51
|
+
| `ghost-image` | timer | Faint image drifts in from a screen edge |
|
|
52
|
+
| `heartbeat` | timer | Vignette pulse around the viewport |
|
|
53
|
+
| `cthulhu` | dom-text | Random word temporarily replaced with a Lovecraftian term |
|
|
54
|
+
| `mirror` | dom-text | Random word briefly rendered mirrored |
|
|
55
|
+
|
|
56
|
+
### `ghost-image` — custom images
|
|
57
|
+
|
|
58
|
+
```js
|
|
59
|
+
poltrgeist.haunt({ images: ['/spooky.png', '/ghost.webp'] })
|
|
60
|
+
// or per-apply:
|
|
61
|
+
poltrgeist.apply(document.body, 'ghost-image', { images: ['/spooky.png'] })
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## API
|
|
65
|
+
|
|
66
|
+
### `poltrgeist.haunt(options?)`
|
|
67
|
+
|
|
68
|
+
Scans the DOM and attaches effects based on probability rolls. Automatically re-runs on DOM mutations.
|
|
69
|
+
|
|
70
|
+
| Option | Type | Default | Description |
|
|
71
|
+
|---|---|---|---|
|
|
72
|
+
| `probability` | `number \| Record<EffectName, number>` | `0.15` | Chance (0–1) any eligible element gets an effect |
|
|
73
|
+
| `effects` | `EffectName[]` | all | Allowlist of effects to enable |
|
|
74
|
+
| `images` | `string[]` | — | Custom image URLs for `ghost-image` |
|
|
75
|
+
| `respectReducedMotion` | `boolean` | `true` | Honour `prefers-reduced-motion` |
|
|
76
|
+
| `interval` | `{ min: number; max: number }` | — | Timing range for timer-based effects (ms) |
|
|
77
|
+
|
|
78
|
+
### `poltrgeist.apply(target, effect, opts?)`
|
|
79
|
+
|
|
80
|
+
Attach a single effect to one or more elements.
|
|
81
|
+
|
|
82
|
+
- `target` — `HTMLElement`, `NodeListOf<HTMLElement>`, or a CSS selector string
|
|
83
|
+
- `effect` — an `EffectName`
|
|
84
|
+
- `opts.images` — custom image URLs (for `ghost-image`)
|
|
85
|
+
|
|
86
|
+
### `poltrgeist.release()`
|
|
87
|
+
|
|
88
|
+
Detach all effects and stop all timers.
|
|
89
|
+
|
|
90
|
+
## License
|
|
91
|
+
|
|
92
|
+
MIT
|