@jayf0x/fluidity-js 0.1.6 β†’ 0.2.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.
Files changed (4) hide show
  1. package/README.md +65 -42
  2. package/dist/globals.d.ts +4 -0
  3. package/dist/index.js +1410 -515
  4. package/package.json +4 -1
package/README.md CHANGED
@@ -1,52 +1,42 @@
1
- # fluidity-js
2
-
3
- **WebGL fluid simulation for React β€” interactive text and image effects powered by Navier-Stokes.**
1
+ # fluidity-js - πŸ”₯Upgrade your UXπŸ”₯
4
2
 
5
3
  [![npm](https://img.shields.io/npm/v/@jayf0x/fluidity-js)](https://www.npmjs.com/package/@jayf0x/fluidity-js)
6
4
  [![license](https://img.shields.io/npm/l/@jayf0x/fluidity-js)](./LICENSE)
7
5
  [![size](https://img.shields.io/bundlephobia/minzip/@jayf0x/fluidity-js)](https://bundlephobia.com/package/@jayf0x/fluidity-js)
8
6
 
9
- <a href="https://jayf0x.github.io/fluidity">
10
- <p align="center" title='Try if you can make this effect.'>
11
- <img align="center" src="assets/preview.png" alt="preview" height="300px"/>
12
- </p>
13
-
7
+ <a href="https://jayf0x.github.io/fluidity">
14
8
  <p align="center">
15
- <strong>
16
- Live demo β†’
17
- </strong>
9
+ <img src="assets/preview.gif" alt="preview" height="300px"/>
18
10
  </p>
11
+ <p align="center"><strong>Live demo β†’</strong></p>
19
12
  </a>
20
13
 
21
- ---
22
-
23
- ## Install
24
-
25
14
  ```bash
26
- npm i @jayf0x/fluidity-js
15
+ bun add @jayf0x/fluidity-js
16
+ # or: npm install / yarn add / pnpm add
27
17
  ```
28
18
 
29
- Requires React β‰₯ 17 and WebGL (WebGL2 recommended; WebGL1 supported as fallback).
19
+ > **WebGPU-first** πŸ”₯ β€” falls back automatically to WebGL2 / WebGL1.
30
20
 
31
21
  ---
32
22
 
33
- ## Usage
23
+ ## React examples
34
24
 
35
- ### FluidText
25
+ **Hero text that moves with your cursor:**
36
26
 
37
27
  ```tsx
38
28
  import { FluidText } from '@jayf0x/fluidity-js';
39
29
 
40
30
  export function Hero() {
41
31
  return (
42
- <div style={{ width: '100%', height: 300 }}>
43
- <FluidText text="hello" fontSize={120} color="#ffffff" />
32
+ <div style={{ width: '100%', height: 400 }}>
33
+ <FluidText text="Hello World" fontSize={140} color="#ffffff" />
44
34
  </div>
45
35
  );
46
36
  }
47
37
  ```
48
38
 
49
- ### FluidImage
39
+ **Full-bleed image cover β€” one line to make it alive:**
50
40
 
51
41
  ```tsx
52
42
  import { FluidImage } from '@jayf0x/fluidity-js';
@@ -60,11 +50,18 @@ export function Cover() {
60
50
  }
61
51
  ```
62
52
 
63
- ### Ref API
53
+ **Go further β€” presets, algorithms, live config:**
64
54
 
65
55
  ```tsx
66
- import { useRef } from 'react';
56
+ <FluidText text="Wicked" preset="neon" algorithm="glass" />
57
+ <FluidImage src="/poster.jpg" algorithm="ripple" config={{ curl: 0.4, splatRadius: 0.008 }} />
58
+ <FluidText text="Chill" preset="calm" quality={{ dpr: 1, sim: 0.75 }} />
59
+ ```
60
+
61
+ **Trigger effects programmatically:**
67
62
 
63
+ ```tsx
64
+ import { useRef } from 'react';
68
65
  import { FluidText } from '@jayf0x/fluidity-js';
69
66
 
70
67
  export function Interactive() {
@@ -72,19 +69,18 @@ export function Interactive() {
72
69
 
73
70
  return (
74
71
  <>
75
- <div style={{ width: '100%', height: 300 }}>
76
- <FluidText ref={fluid} text="fluid" fontSize={120} color="#fff" />
72
+ <div style={{ width: '100%', height: 400 }}>
73
+ <FluidText ref={fluid} text="Touch me" fontSize={120} color="#fff" />
77
74
  </div>
75
+ <button onClick={() => fluid.current?.splat(200, 200, 8, -4)}>Splat</button>
76
+ <button onClick={() => fluid.current?.updateConfig({ curl: 0.5 })}>Swirl</button>
78
77
  <button onClick={() => fluid.current?.reset()}>Reset</button>
79
- <button onClick={() => fluid.current?.updateConfig({ curl: 0.3 })}>Swirl</button>
80
78
  </>
81
79
  );
82
80
  }
83
81
  ```
84
82
 
85
- `FluidHandle` is a global type β€” no import needed.
86
-
87
- More examples β†’ [`demo/src/examples/`](./demo/src/examples/)
83
+ Official examples β†’ [`demo/src/examples/`](./demo/src/examples/)
88
84
 
89
85
  ---
90
86
 
@@ -110,18 +106,20 @@ More examples β†’ [`demo/src/examples/`](./demo/src/examples/)
110
106
 
111
107
  ### Shared props
112
108
 
113
- | Prop | Type | Default |
114
- | ----------------- | ---------------------- | ------------ |
115
- | `config` | `Partial<FluidConfig>` | β€” |
116
- | `preset` | `PresetKey` | β€” |
117
- | `algorithm` | `FluidAlgorithm` | `'standard'` |
118
- | `backgroundColor` | `string` | `'#0a0a0a'` |
119
- | `backgroundSrc` | `string` | β€” |
120
- | `backgroundSize` | `string \| number` | `'cover'` |
121
- | `isMouseEnabled` | `boolean` | `true` |
122
- | `isWorkerEnabled` | `boolean` | `true` |
123
- | `className` | `string` | β€” |
124
- | `style` | `CSSProperties` | β€” |
109
+ | Prop | Type | Default |
110
+ | ----------------- | ---------------------- | ---------------------- |
111
+ | `config` | `Partial<FluidConfig>` | β€” |
112
+ | `preset` | `PresetKey` | β€” |
113
+ | `algorithm` | `FluidAlgorithm` | `'standard'` |
114
+ | `quality` | `FluidQuality` | `{ dpr: 1, sim: 0.5 }` |
115
+ | `backgroundColor` | `string` | `'#0a0a0a'` |
116
+ | `backgroundSrc` | `string` | β€” |
117
+ | `backgroundSize` | `string \| number` | `'cover'` |
118
+ | `isMouseEnabled` | `boolean` | `true` |
119
+ | `isWorkerEnabled` | `boolean` | `true` |
120
+ | `useWebGPU` | `boolean` | `true` |
121
+ | `className` | `string` | β€” |
122
+ | `style` | `CSSProperties` | β€” |
125
123
 
126
124
  ---
127
125
 
@@ -142,6 +140,31 @@ More examples β†’ [`demo/src/examples/`](./demo/src/examples/)
142
140
 
143
141
  ---
144
142
 
143
+ ## Quality
144
+
145
+ `quality` controls rendering resolution on two independent axes. Both props are reactive β€” you can adjust them at runtime.
146
+
147
+ | Field | Range | Default | Description |
148
+ | ----- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
149
+ | `dpr` | 0.1 – 1 | `1` | Canvas backing resolution as a fraction of `devicePixelRatio`. `0.5` on a Retina screen renders at 1Γ— instead of 2Γ—, saving ~75% fill rate. |
150
+ | `sim` | 0.1 – 1 | `0.5` | Simulation FBO size as a fraction of canvas size. Lower = cheaper GPU, less fluid detail. |
151
+
152
+ ```tsx
153
+ <FluidText text="hello" quality={{ dpr: 0.75, sim: 0.25 }} />
154
+ ```
155
+
156
+ `dpr` and `sim` are independent β€” you can run a sharp canvas at a coarser simulation:
157
+
158
+ ```tsx
159
+ // Sharp display, cheap simulation
160
+ <FluidImage src="/hero.jpg" quality={{ dpr: 1, sim: 0.2 }} />
161
+
162
+ // Lower display res, full simulation quality
163
+ <FluidImage src="/hero.jpg" quality={{ dpr: 0.5, sim: 1 }} />
164
+ ```
165
+
166
+ ---
167
+
145
168
  ## FluidConfig
146
169
 
147
170
  | Key | Default | Description |
package/dist/globals.d.ts CHANGED
@@ -40,7 +40,9 @@ interface FluidHandle {
40
40
  }
41
41
 
42
42
  interface FluidBaseProps {
43
+ /** Will apply to canvas container */
43
44
  className?: string;
45
+ /** Will apply to canvas container */
44
46
  style?: React.CSSProperties;
45
47
  config?: Partial<FluidConfig>;
46
48
  isMouseEnabled?: boolean;
@@ -51,6 +53,8 @@ interface FluidBaseProps {
51
53
  backgroundColor?: string;
52
54
  backgroundSrc?: string;
53
55
  backgroundSize?: string | number;
56
+ /** enabled greater performance, but not every browser supports it */
57
+ useWebGPU?: boolean;
54
58
  }
55
59
 
56
60
  interface FluidTextProps extends FluidBaseProps {