@cruxgarden/plasma-ui 0.2.4 → 0.3.0
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/CHANGELOG.md +104 -0
- package/README.md +82 -7
- package/dist/Plasma.d.ts +31 -6
- package/dist/PlasmaProvider.d.ts +77 -12
- package/dist/index.d.ts +12 -3
- package/dist/index.js +325 -155
- package/dist/renderer.d.ts +30 -2
- package/package.json +7 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,109 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
### Every look the material adds is now a control
|
|
6
|
+
|
|
7
|
+
Six things gave the plasma a look of its own and only two could be turned off,
|
|
8
|
+
so "plain glass, nothing but the lens" was not reachable. Each is a prop now,
|
|
9
|
+
every one defaulting to exactly the old behaviour.
|
|
10
|
+
|
|
11
|
+
- **Added:** `shimmer` - the slow iridescent sheen drifting across the body of
|
|
12
|
+
each surface. This is the rainbow that stayed no matter how far `rim` came
|
|
13
|
+
down; it had no uniform at all.
|
|
14
|
+
- **Added:** `glow` - the halo of color the plasma casts on the background
|
|
15
|
+
around it. Keyed to the height field, not to elevation, which is why it was
|
|
16
|
+
still there at `elevation={0}` where the drop shadow genuinely is off.
|
|
17
|
+
- **Added:** `wash` - how much of its own cast the material puts on what you
|
|
18
|
+
see through it. `0` passes the background straight through.
|
|
19
|
+
- **Added:** `grain` - the film grain over the background.
|
|
20
|
+
- **Added:** `backgroundBlur` (0-40 px) - blurs the background itself, where
|
|
21
|
+
`frost` blurs only what a frosted surface sees. Eight extra passes above 0,
|
|
22
|
+
and none at 0. Contributed as a patch by Tigrana.
|
|
23
|
+
- **Added:** an **Aqua** tab in the playground: all six off, refraction up. The
|
|
24
|
+
README carries the same recipe under "Clear as water".
|
|
25
|
+
|
|
26
|
+
### Composability
|
|
27
|
+
|
|
28
|
+
- **Added:** `<PlasmaCanvas>` and `canvas={false}` on the provider, so the
|
|
29
|
+
canvas element can be placed and styled by the consumer. The renderer still
|
|
30
|
+
draws the whole viewport - this moves the element, not the field.
|
|
31
|
+
- **Added:** `group` on `<Plasma>`. Two independent sets of panels on one page
|
|
32
|
+
no longer snap onto each other. Snapping only; surfaces still fuse wherever
|
|
33
|
+
they overlap.
|
|
34
|
+
- **Added:** `usePlasmaRuntime()` and `usePlasmaDefaults()`. The context is two
|
|
35
|
+
contexts now, and the runtime half is stable, so a component that only wants
|
|
36
|
+
`pulse` is no longer re-rendered by every styling change. `usePlasma()`
|
|
37
|
+
returns both together and is unchanged.
|
|
38
|
+
- **Changed:** `as` is properly polymorphic. `<Plasma as="a" href>` and
|
|
39
|
+
`<Plasma as={Link} to>` typecheck; `PlasmaProps` on its own still means the
|
|
40
|
+
div form.
|
|
41
|
+
- **Changed:** `maxSurfaces` is live. It recompiles the shaders rather than
|
|
42
|
+
being fixed at mount, and the renderer warns once when it has to drop
|
|
43
|
+
surfaces instead of silently not drawing them.
|
|
44
|
+
- **Changed:** `bounds` takes `RefObject<HTMLElement | null>`, which is what
|
|
45
|
+
`useRef<T>(null)` produces under @types/react 19, where it did not compile.
|
|
46
|
+
- **Changed:** `PlasmaRenderer`, `makeShaders` and the renderer types are
|
|
47
|
+
marked `@internal` - still exported as an escape hatch, but outside semver.
|
|
48
|
+
|
|
49
|
+
### React
|
|
50
|
+
|
|
51
|
+
- **Fixed:** refs were written during render (`settingsRef`, `joinCb`,
|
|
52
|
+
`plasmaRef`). They update in a layout effect now.
|
|
53
|
+
- **Fixed:** a surface's options reached the renderer one paint late, because
|
|
54
|
+
the update ran in a passive effect while the CSS it accompanies commits with
|
|
55
|
+
layout. Registration also read those options through a closure its own dep
|
|
56
|
+
list could leave stale for a frame; it reads a ref instead.
|
|
57
|
+
- **Fixed:** `useLayoutEffect` warned during server rendering. Both components
|
|
58
|
+
use an isomorphic variant, and join state reads through
|
|
59
|
+
`useSyncExternalStore` with a server snapshot - SSR is clean, and tested.
|
|
60
|
+
- **Fixed:** interaction handlers were new identities on every render, which
|
|
61
|
+
broke memoization for `as={MemoizedComponent}`.
|
|
62
|
+
- **Added:** development-only warnings for a `<Plasma>` outside a provider, a
|
|
63
|
+
provider with no canvas, and a `style` setting `transform`, `translate` or
|
|
64
|
+
`scale` on a positioned surface - the three failures that were silent. They
|
|
65
|
+
drop out of a production build.
|
|
66
|
+
|
|
67
|
+
### Gate
|
|
68
|
+
|
|
69
|
+
- `npm run verify` also runs `typecheck:app` (the site, the examples and a
|
|
70
|
+
compile-only API suite, none of which were typechecked before) and
|
|
71
|
+
`format:check`. CI adds `typecheck:react19`, since the peer range is
|
|
72
|
+
`react >=18` while the dev types pin 18.
|
|
73
|
+
- Prettier no longer claims `src`, `tests` or CSS, whose dense style is
|
|
74
|
+
deliberate; `npm run format` used to hand a 690-line diff to anyone who ran it.
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
Follow-ups to the context-loss work in 0.2.4, which fixed the frame loop but
|
|
78
|
+
left the paths around it holding objects from the dead context.
|
|
79
|
+
|
|
80
|
+
- **Fixed:** a `background` image was gone for good after a context restore.
|
|
81
|
+
`initGL()` re-ran `configure()`, but `loadBackground()` early-returns on an
|
|
82
|
+
unchanged source, so `imgTex` kept its handle from the dead context while
|
|
83
|
+
`uHasImg` still said 1 — every frame then threw INVALID_OPERATION on
|
|
84
|
+
`bindTexture`. The background state is reset before the reconfigure, so the
|
|
85
|
+
source is genuinely reloaded.
|
|
86
|
+
- **Fixed:** a restore that landed during a `freezeOnScroll` fling left the
|
|
87
|
+
canvas blank. `applyResize()` refuses to allocate while frozen, so the eight
|
|
88
|
+
targets got no storage and the multi-target framebuffer no attachments, and
|
|
89
|
+
the loop restarted into a freeze that was meant to hold it. A restore now
|
|
90
|
+
ends the freeze and reallocates.
|
|
91
|
+
- **Fixed:** `destroy()` leaked the background texture — created in
|
|
92
|
+
`loadBackground()`, so never in the owned set — and a full-size texture went
|
|
93
|
+
with every teardown, including each StrictMode remount.
|
|
94
|
+
- **Fixed:** a background image whose load landed after `destroy()` allocated
|
|
95
|
+
an orphan texture on the still-live shared context.
|
|
96
|
+
- **Fixed:** compiled shaders were never deleted. `deleteProgram()` does not
|
|
97
|
+
free a shader that was not flagged, so ten shader objects stranded per
|
|
98
|
+
`initGL()` — once per remount and once per context restore.
|
|
99
|
+
- **Changed:** the provider's `configure()` effect derives its dependencies
|
|
100
|
+
from the settings object rather than a hand-written list, so a new setting is
|
|
101
|
+
live the moment it is added instead of silently freezing at its mount value.
|
|
102
|
+
- **Added:** a fake WebGL2 + DOM harness (`tests/webgl-harness.mjs`) and seven
|
|
103
|
+
renderer lifecycle tests. It accounts for every GL object created and fails
|
|
104
|
+
on any use of one from a dead context or already deleted — the two mistakes
|
|
105
|
+
that are invisible in a browser until the field goes black.
|
|
106
|
+
|
|
3
107
|
## 0.2.4
|
|
4
108
|
|
|
5
109
|
- **Fixed:** the field stopped rendering after a window resize and never came
|
package/README.md
CHANGED
|
@@ -6,13 +6,14 @@ Liquid panels for React, rendered in WebGL on canvas, inspired by Apple's Liquid
|
|
|
6
6
|
|
|
7
7
|
[Playground and Docs](https://cruxgarden.github.io/plasma-ui/) · [Workspace example](https://cruxgarden.github.io/plasma-ui/examples/workspace/)
|
|
8
8
|
|
|
9
|
-
**Status: 0.
|
|
9
|
+
**Status: 0.3.0.** Core is stable and tested, but the API may change.
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
npm install @cruxgarden/plasma-ui
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
Zero dependencies, except for React.
|
|
15
|
+
Zero dependencies, except for React. Best on desktop: the effect is GPU-heavy
|
|
16
|
+
and does not run well on mobile.
|
|
16
17
|
|
|
17
18
|
```tsx
|
|
18
19
|
import { PlasmaProvider, Plasma } from "@cruxgarden/plasma-ui";
|
|
@@ -58,12 +59,19 @@ export function App() {
|
|
|
58
59
|
| `rimWidth` | `number` | `1` | How far the rim reaches in from the edge |
|
|
59
60
|
| `highlight` | `number` | `1` | Pointer-facing highlight; `0` turns it off |
|
|
60
61
|
| `edgeLine` | `number` | `1` | Thin line along the outline; `0` turns it off |
|
|
62
|
+
| `shimmer` | `number` | `1` | The slow iridescent sheen that drifts across the body of each surface; `0` turns it off |
|
|
63
|
+
| `glow` | `number` | `1` | The halo of color the plasma casts on the background around it - the soft light that is still there at `elevation={0}`; `0` turns it off |
|
|
64
|
+
| `wash` | `number` | `1` | How much of its own cast the material puts on what you see through it; `0` passes the background straight through |
|
|
65
|
+
| `grain` | `number` | `1` | Film grain over the background (never over the surfaces); `0` turns it off |
|
|
66
|
+
| `backgroundBlur` | `number` | `0` | Blur the background itself, in CSS px (0-40). Unlike `frost`, which blurs only what a frosted surface sees, this softens the whole field |
|
|
61
67
|
| `pointerDrop` | `boolean` | `true` | Liquid drop that follows the pointer |
|
|
62
68
|
| `ambientDrops` | `boolean` | `false` | Decorative orbiting drops |
|
|
63
69
|
| `grid`, `magnet` | `number` | `24`, `40` | Snap grid size and edge latch distance |
|
|
64
70
|
| `quality` | `number` | `1.25` | Maximum canvas pixel ratio |
|
|
65
|
-
| `
|
|
71
|
+
| `freezeOnScroll` | `boolean` | `false` | Touch devices only: pin the last drawn frame to the page through a fling and resume when the scrolling stops |
|
|
72
|
+
| `maxSurfaces` | `number` | `16` | Visible surface budget, compiled into the shaders; changing it rebuilds them, and higher costs GPU time |
|
|
66
73
|
| `zIndex` | `number` | `-1` | Canvas stacking order |
|
|
74
|
+
| `canvas` | `boolean` | `true` | `false`: render [`<PlasmaCanvas />`](#plasmacanvas) yourself to choose where the element sits and how it is styled |
|
|
67
75
|
|
|
68
76
|
## `<Plasma>`
|
|
69
77
|
|
|
@@ -71,7 +79,7 @@ Accepts all HTML attributes, plus the following:
|
|
|
71
79
|
|
|
72
80
|
| Prop | Type | Default | Description |
|
|
73
81
|
| --------------------------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
74
|
-
| `as` | `ElementType` | `"div"` | Element to render
|
|
82
|
+
| `as` | `ElementType` | `"div"` | Element or component to render. Its props typecheck through: `as="a"` takes `href`, `as={Link}` takes `to` |
|
|
75
83
|
| `radius` | `number` | provider | Corner radius (px) for this surface |
|
|
76
84
|
| `lean` | `number \| false` | `10` | Lean toward the pointer while standalone |
|
|
77
85
|
| `tint`, `opacity`, `frost`, `elevation` | `string`, `number` | provider | Color, translucency, and shadow depth for this surface; joined surfaces with different values blend into each other |
|
|
@@ -80,15 +88,74 @@ Accepts all HTML attributes, plus the following:
|
|
|
80
88
|
| `draggable` | `boolean` | `false` | Move freely, snap on release; arrow keys move one grid step |
|
|
81
89
|
| `snap` | `boolean` | `true` | Latch to neighbor edges, otherwise the grid |
|
|
82
90
|
| `bounds` | `RefObject<HTMLElement>` | viewport | Drag area and grid origin |
|
|
91
|
+
| `group` | `string` | | Snap only against surfaces in the same group; surfaces with no group form one group of their own |
|
|
83
92
|
| `offset` / `defaultOffset` | `{ x, y }` | | Controlled or initial offset; changes spring into place |
|
|
84
93
|
| `onDragStart`, `onDragEnd(offset)` | | | Drag lifecycle; `onDragEnd` gets the settled offset |
|
|
85
94
|
| `onJoinChange(joined)` | | | Fires when the surface fuses with or separates from a neighbor |
|
|
86
95
|
|
|
96
|
+
Everything else you pass goes to the rendered element. `PlasmaProps<C>` is the
|
|
97
|
+
full prop type for `<Plasma as={C}>`; `PlasmaOwnProps` is just the table above,
|
|
98
|
+
if you need to wrap `Plasma` in a component of your own.
|
|
99
|
+
|
|
87
100
|
Drag ignores presses on buttons, links, inputs, and anything marked `data-plasma-nodrag`.
|
|
88
101
|
|
|
89
|
-
##
|
|
102
|
+
## Hooks
|
|
103
|
+
|
|
104
|
+
| Hook | Returns |
|
|
105
|
+
| --------------------- | ----------------------------------------------------------------------------- |
|
|
106
|
+
| `usePlasmaRuntime()` | `renderer`, `supported`, `reducedMotion`, `pulse(x, y, strength?)`, `bump(energy)` |
|
|
107
|
+
| `usePlasmaDefaults()` | `tint`, `opacity`, `frost`, `radius`, `grid`, `magnet`, `spring` |
|
|
108
|
+
| `usePlasma()` | both of the above, in one object |
|
|
109
|
+
|
|
110
|
+
`usePlasmaRuntime()` is the one to reach for when you only need `pulse`: its
|
|
111
|
+
value is stable, so a component reading it is not re-rendered every time a
|
|
112
|
+
styling prop on the provider changes. `usePlasma()` is the convenient one and
|
|
113
|
+
re-renders on any change.
|
|
114
|
+
|
|
115
|
+
## `<PlasmaCanvas>`
|
|
116
|
+
|
|
117
|
+
The provider renders the canvas itself unless you pass `canvas={false}`, in
|
|
118
|
+
which case render `<PlasmaCanvas />` wherever you want the element to live:
|
|
119
|
+
|
|
120
|
+
```tsx
|
|
121
|
+
<PlasmaProvider canvas={false}>
|
|
122
|
+
<div className="page-backdrop" />
|
|
123
|
+
<PlasmaCanvas zIndex={0} className="field" />
|
|
124
|
+
<main>...</main>
|
|
125
|
+
</PlasmaProvider>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
It takes `className`, `style` and `zIndex`. Note that this places and styles
|
|
129
|
+
the **element**; the renderer still draws the whole viewport. Confining the
|
|
130
|
+
field to a container is [roadmap](#roadmap) work, not something this prop does.
|
|
131
|
+
|
|
132
|
+
## Clear as water
|
|
133
|
+
|
|
134
|
+
Six things give the material a look of its own, and each is a separate
|
|
135
|
+
control, so "plain glass, nothing but the lens" is a configuration rather than
|
|
136
|
+
a fork:
|
|
90
137
|
|
|
91
|
-
|
|
138
|
+
```tsx
|
|
139
|
+
<PlasmaProvider
|
|
140
|
+
rim={0} // the iridescent edge
|
|
141
|
+
highlight={0} // the specular that follows the pointer
|
|
142
|
+
shimmer={0} // the sheen drifting across the body
|
|
143
|
+
glow={0} // the halo cast on the background - visible even at elevation 0
|
|
144
|
+
wash={0} // the material's own tint on what you see through it
|
|
145
|
+
grain={0} // film grain on the background
|
|
146
|
+
edgeLine={0.35} // a hairline is usually still wanted: it is what reads as an edge
|
|
147
|
+
refraction={1.5}
|
|
148
|
+
dispersion={1.6}
|
|
149
|
+
/>
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The **Aqua** tab in the [playground](https://cruxgarden.github.io/plasma-ui/)
|
|
153
|
+
is exactly this, with all six sliders live next to it.
|
|
154
|
+
|
|
155
|
+
Two of these answer questions that come up often: the faint rainbow that never
|
|
156
|
+
went away no matter how far `rim` came down is `shimmer`, and the soft light
|
|
157
|
+
still hugging a panel at `elevation={0}` is `glow` - it is cast by the plasma,
|
|
158
|
+
not by the shadow, which really is off at `0`.
|
|
92
159
|
|
|
93
160
|
## Custom moods
|
|
94
161
|
|
|
@@ -133,7 +200,7 @@ NOTE: `flow` ripples the outline, so leave it at `0` whenever flush edges should
|
|
|
133
200
|
|
|
134
201
|
- Use Plasma for container components: panels, docks, cards, dialogs. Components should be nested inside.
|
|
135
202
|
- Place surfaces together or further apart than the Blend distance. Smaller gaps render as liquid bridging them.
|
|
136
|
-
- Up to `maxSurfaces` (default 16) draw at once; offscreen panels are skipped first. Two render passes loop over every slot per pixel, so set this value only as high as you need.
|
|
203
|
+
- Up to `maxSurfaces` (default 16) draw at once; offscreen panels are skipped first, and the library warns in the console when it has to drop any. Two render passes loop over every slot per pixel, so set this value only as high as you need. Changing it recompiles the shaders, so change it when the layout changes, not per frame.
|
|
137
204
|
- Lean and Pulse use the CSS `translate` and `scale` properties, and Drag uses `transform`. Avoid setting these properties on `Plasma` elements yourself.
|
|
138
205
|
- `prefers-reduced-motion` disables Lean, Pulse, the pointer Drop, and Spring.
|
|
139
206
|
|
|
@@ -153,6 +220,14 @@ Contributions welcome for any of these - see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
153
220
|
|
|
154
221
|
Chrome, Edge, Firefox, and Safari 16.4+ (WebGL2). In non-supported browsers, `Plasma` renders as a CSS frosted panel and all layout, drag, and snap behavior still works.
|
|
155
222
|
|
|
223
|
+
**Use it on the desktop.** Every pass is full-viewport, so the cost scales with
|
|
224
|
+
the canvas, and phones pay it at a device pixel ratio the effect does not need.
|
|
225
|
+
It runs on mobile - resolution drops past a pixel budget, and `freezeOnScroll`
|
|
226
|
+
pins the last frame through a fling - but it is not where this belongs.
|
|
227
|
+
|
|
228
|
+
Server rendering works: surfaces come out as the CSS fallback with no layout
|
|
229
|
+
effect warnings, and the canvas takes over on hydration.
|
|
230
|
+
|
|
156
231
|
## Development
|
|
157
232
|
|
|
158
233
|
```bash
|
package/dist/Plasma.d.ts
CHANGED
|
@@ -3,9 +3,8 @@ export interface Offset {
|
|
|
3
3
|
x: number;
|
|
4
4
|
y: number;
|
|
5
5
|
}
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
as?: React.ElementType;
|
|
6
|
+
/** The props Plasma itself understands. Everything else goes to the rendered element. */
|
|
7
|
+
export interface PlasmaOwnProps {
|
|
9
8
|
/** Corner radius in px. Defaults to the provider's radius. */
|
|
10
9
|
radius?: number;
|
|
11
10
|
/** How far (px) the surface leans toward the pointer while standalone. 0 or false disables. Default 10. */
|
|
@@ -26,8 +25,19 @@ export interface PlasmaProps extends Omit<React.HTMLAttributes<HTMLElement>, "on
|
|
|
26
25
|
draggable?: boolean;
|
|
27
26
|
/** Snap on release (edges latch to neighbors, otherwise the grid). Default true. */
|
|
28
27
|
snap?: boolean;
|
|
29
|
-
/**
|
|
30
|
-
|
|
28
|
+
/**
|
|
29
|
+
* Only snap against surfaces carrying the same group. Two independent sets
|
|
30
|
+
* of panels on one page stop latching onto each other. Surfaces with no
|
|
31
|
+
* group form one group of their own. Scopes snapping only - surfaces still
|
|
32
|
+
* fuse visually wherever they overlap.
|
|
33
|
+
*/
|
|
34
|
+
group?: string;
|
|
35
|
+
/**
|
|
36
|
+
* Keep dragging inside this element. Defaults to the viewport. Also sets the
|
|
37
|
+
* grid origin. The `| null` matters: under @types/react 19 `useRef<T>(null)`
|
|
38
|
+
* is a `RefObject<T | null>`, which a bare `RefObject<HTMLElement>` rejects.
|
|
39
|
+
*/
|
|
40
|
+
bounds?: React.RefObject<HTMLElement | null>;
|
|
31
41
|
/** Controlled offset from the element's layout position. Changes spring into place. */
|
|
32
42
|
offset?: Offset;
|
|
33
43
|
/** Starting offset when uncontrolled. */
|
|
@@ -38,4 +48,19 @@ export interface PlasmaProps extends Omit<React.HTMLAttributes<HTMLElement>, "on
|
|
|
38
48
|
/** Fires when the surface fuses with or separates from a neighbor. */
|
|
39
49
|
onJoinChange?: (joined: boolean) => void;
|
|
40
50
|
}
|
|
41
|
-
|
|
51
|
+
/**
|
|
52
|
+
* Props for `<Plasma as={C}>`: Plasma's own, plus everything `C` accepts.
|
|
53
|
+
* `PlasmaProps` on its own still means the div form, as it always did.
|
|
54
|
+
*/
|
|
55
|
+
export type PlasmaProps<C extends React.ElementType = "div"> = PlasmaOwnProps & {
|
|
56
|
+
/** Element or component to render. Default "div". */
|
|
57
|
+
as?: C;
|
|
58
|
+
ref?: React.Ref<HTMLElement>;
|
|
59
|
+
} & Omit<React.ComponentPropsWithoutRef<C>, keyof PlasmaOwnProps | "as" | "ref">;
|
|
60
|
+
/**
|
|
61
|
+
* A plasma surface. The DOM stays ordinary HTML; the canvas only draws.
|
|
62
|
+
*
|
|
63
|
+
* The cast is what makes `as` polymorphic: `<Plasma as="a" href=...>` and
|
|
64
|
+
* `<Plasma as={Link} to=...>` typecheck, which a plain forwardRef cannot express.
|
|
65
|
+
*/
|
|
66
|
+
export declare const Plasma: <C extends React.ElementType = "div">(props: PlasmaProps<C>) => React.ReactElement | null;
|
package/dist/PlasmaProvider.d.ts
CHANGED
|
@@ -23,6 +23,25 @@ export interface PlasmaProviderProps {
|
|
|
23
23
|
highlight?: number;
|
|
24
24
|
/** Strength of the thin line along the outline. 0 turns it off. Default 1. */
|
|
25
25
|
edgeLine?: number;
|
|
26
|
+
/**
|
|
27
|
+
* The slow iridescent sheen that drifts across the body of each surface.
|
|
28
|
+
* 0 turns it off. Default 1. Set it to 0 along with `rim`, `highlight`,
|
|
29
|
+
* `edgeLine`, `glow` and `wash` for plain water - see "Clear as water" in
|
|
30
|
+
* the README.
|
|
31
|
+
*/
|
|
32
|
+
shimmer?: number;
|
|
33
|
+
/** Colored bloom the plasma casts onto the background around it. 0 turns it off. Default 1. */
|
|
34
|
+
glow?: number;
|
|
35
|
+
/**
|
|
36
|
+
* How much of its own cast the material puts on what you see through it -
|
|
37
|
+
* a slight desaturation and lift. 0 passes the background through
|
|
38
|
+
* untouched. Default 1.
|
|
39
|
+
*/
|
|
40
|
+
wash?: number;
|
|
41
|
+
/** Film grain over the background (never over the surfaces). 0 turns it off. Default 1. */
|
|
42
|
+
grain?: number;
|
|
43
|
+
/** Blur the background itself, in CSS px, 0-40. Softens the whole field, unlike `frost`, which blurs only what a frosted surface sees. Default 0. */
|
|
44
|
+
backgroundBlur?: number;
|
|
26
45
|
/** How thick the material feels: 0 is watery and bouncy, 1 is slow like syrup. Also scales drag and snap springs. Default 0.5. */
|
|
27
46
|
viscosity?: number;
|
|
28
47
|
/** How far the plasma trails and stretches behind moving panels. 0 turns it off. Default 1. */
|
|
@@ -60,27 +79,73 @@ export interface PlasmaProviderProps {
|
|
|
60
79
|
* if any, to scroll with the page.
|
|
61
80
|
*/
|
|
62
81
|
freezeOnScroll?: boolean;
|
|
63
|
-
/** Maximum visible plasma surfaces
|
|
82
|
+
/** Maximum visible plasma surfaces at once. Raising it costs GPU time; changing it rebuilds the shaders. Default 16. */
|
|
64
83
|
maxSurfaces?: number;
|
|
65
|
-
/** z-index of the
|
|
84
|
+
/** z-index of the canvas this provider renders. Default -1 (behind content). Ignored when `canvas` is false. */
|
|
66
85
|
zIndex?: number;
|
|
86
|
+
/**
|
|
87
|
+
* Whether the provider renders the canvas itself. Set false and place a
|
|
88
|
+
* `<PlasmaCanvas />` anywhere in the tree to control where the element
|
|
89
|
+
* lives and how it is styled. Default true.
|
|
90
|
+
*/
|
|
91
|
+
canvas?: boolean;
|
|
67
92
|
}
|
|
68
|
-
|
|
93
|
+
/**
|
|
94
|
+
* The parts of the context that exist for the provider's lifetime. This value
|
|
95
|
+
* is stable: it changes once when the renderer is created and then only if
|
|
96
|
+
* the reduced-motion preference does, so `usePlasmaRuntime()` consumers are
|
|
97
|
+
* not re-rendered by every styling change.
|
|
98
|
+
*/
|
|
99
|
+
export interface PlasmaRuntime {
|
|
69
100
|
renderer: PlasmaRenderer | null;
|
|
70
|
-
/**
|
|
101
|
+
/** False when WebGL2 is unavailable; <Plasma> falls back to a CSS frosted panel. */
|
|
102
|
+
supported: boolean;
|
|
103
|
+
reducedMotion: boolean;
|
|
104
|
+
pulse: (x: number, y: number, strength?: number) => void;
|
|
105
|
+
bump: (energy: number) => void;
|
|
106
|
+
}
|
|
107
|
+
/** The provider-level values a surface falls back to, and the layout settings. */
|
|
108
|
+
export interface PlasmaDefaults {
|
|
71
109
|
tint: string;
|
|
72
110
|
opacity: number;
|
|
73
111
|
frost: number;
|
|
74
|
-
/** Provider-level default corner radius. */
|
|
75
112
|
radius: number;
|
|
76
|
-
/** False when WebGL2 is unavailable; <Plasma> falls back to a CSS frosted panel. */
|
|
77
|
-
supported: boolean;
|
|
78
113
|
grid: number;
|
|
79
114
|
magnet: number;
|
|
80
115
|
spring: Mood["spring"];
|
|
81
|
-
reducedMotion: boolean;
|
|
82
|
-
pulse: (x: number, y: number, strength?: number) => void;
|
|
83
|
-
bump: (energy: number) => void;
|
|
84
116
|
}
|
|
85
|
-
|
|
86
|
-
export
|
|
117
|
+
/** Everything `usePlasma()` returns: the runtime and the defaults together. */
|
|
118
|
+
export interface PlasmaContextValue extends PlasmaRuntime, PlasmaDefaults {
|
|
119
|
+
}
|
|
120
|
+
/** Renderer, support flag and commands. Stable - use this when you only need `pulse`. */
|
|
121
|
+
export declare const usePlasmaRuntime: () => PlasmaRuntime;
|
|
122
|
+
/** Provider-level tint, opacity, frost, radius, grid, magnet and spring. */
|
|
123
|
+
export declare const usePlasmaDefaults: () => PlasmaDefaults;
|
|
124
|
+
/** Everything at once. Re-renders on any provider change; prefer the narrower hooks. */
|
|
125
|
+
export declare function usePlasma(): PlasmaContextValue;
|
|
126
|
+
/** True in every build except a production one. */
|
|
127
|
+
export declare const DEV: boolean;
|
|
128
|
+
/**
|
|
129
|
+
* useLayoutEffect on the client, useEffect on the server - React warns about
|
|
130
|
+
* the former during SSR, and none of this work means anything there anyway.
|
|
131
|
+
*/
|
|
132
|
+
export declare const useIsoLayoutEffect: typeof React.useLayoutEffect;
|
|
133
|
+
/** Keeps a ref pointing at the newest value without writing to it during render. */
|
|
134
|
+
export declare function useLatest<T>(value: T): React.MutableRefObject<T>;
|
|
135
|
+
export interface PlasmaCanvasProps {
|
|
136
|
+
className?: string;
|
|
137
|
+
style?: React.CSSProperties;
|
|
138
|
+
/** z-index of the canvas. Default -1 (behind content). */
|
|
139
|
+
zIndex?: number;
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* The canvas the plasma is drawn on. The provider renders one by default;
|
|
143
|
+
* render this yourself (with `canvas={false}` on the provider) to choose
|
|
144
|
+
* where the element sits in the DOM and how it is styled.
|
|
145
|
+
*
|
|
146
|
+
* The drawn region is still the whole viewport - this controls the element,
|
|
147
|
+
* not the area the renderer covers. Clipping the field to a container is not
|
|
148
|
+
* supported yet.
|
|
149
|
+
*/
|
|
150
|
+
export declare function PlasmaCanvas({ className, style, zIndex }: PlasmaCanvasProps): React.JSX.Element;
|
|
151
|
+
export declare function PlasmaProvider({ children, mood, theme, blend, refraction, dispersion, rim, smoothness, background, radius, tint, opacity, frost, elevation, viscosity, stretch, flow, rimColor, rimWidth, highlight, edgeLine, shimmer, glow, wash, grain, backgroundBlur, pointerDrop, ambientDrops, grid, magnet, quality, maxSurfaces, zIndex, freezeOnScroll, canvas, }: PlasmaProviderProps): React.JSX.Element;
|
package/dist/index.d.ts
CHANGED
|
@@ -1,11 +1,20 @@
|
|
|
1
|
-
export { PlasmaProvider, usePlasma } from "./PlasmaProvider";
|
|
2
|
-
export type { PlasmaProviderProps, PlasmaContextValue } from "./PlasmaProvider";
|
|
1
|
+
export { PlasmaProvider, PlasmaCanvas, usePlasma, usePlasmaRuntime, usePlasmaDefaults } from "./PlasmaProvider";
|
|
2
|
+
export type { PlasmaProviderProps, PlasmaCanvasProps, PlasmaContextValue, PlasmaRuntime, PlasmaDefaults } from "./PlasmaProvider";
|
|
3
3
|
export { Plasma } from "./Plasma";
|
|
4
|
-
export type { PlasmaProps, Offset } from "./Plasma";
|
|
4
|
+
export type { PlasmaProps, PlasmaOwnProps, Offset } from "./Plasma";
|
|
5
5
|
export { moods, resolveMood } from "./moods";
|
|
6
6
|
export type { Mood, MoodName } from "./moods";
|
|
7
7
|
export { snapBox, boxGap } from "./snap";
|
|
8
8
|
export type { Box, SnapOptions } from "./snap";
|
|
9
|
+
/**
|
|
10
|
+
* The rendering engine. Exported as an escape hatch - `usePlasmaRuntime()`
|
|
11
|
+
* hands you the live instance - but it is internal: its shape tracks whatever
|
|
12
|
+
* the shaders need and can change in any release, including a patch. Nothing
|
|
13
|
+
* below this line is covered by the package's semver promise.
|
|
14
|
+
* @internal
|
|
15
|
+
*/
|
|
9
16
|
export { PlasmaRenderer } from "./renderer";
|
|
17
|
+
/** @internal */
|
|
10
18
|
export { makeShaders, DEFAULT_MAX_SHAPES } from "./shaders";
|
|
19
|
+
/** @internal */
|
|
11
20
|
export type { BackgroundSource, JoinedSides, RendererSettings, ShapeHandle, ShapeOptions } from "./renderer";
|