@shazmoghaddam/orbs 0.0.0-stage → 1.8.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/LICENSE +21 -0
- package/README.md +339 -2
- package/orb.d.ts +157 -0
- package/orb.js +1172 -0
- package/orb.min.js +44 -0
- package/package.json +70 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Shaz Moghaddam, https://shazmoghaddam.github.io, https://linkedin.com/in/shazmoghaddam, London.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,340 @@
|
|
|
1
|
-
|
|
1
|
+

|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
# Orbs
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@shazmoghaddam/orbs)
|
|
6
|
+
[](https://github.com/ShazMoghaddam/orbs/actions/workflows/ci.yml)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+

|
|
9
|
+

|
|
10
|
+
[](https://www.jsdelivr.com/package/gh/ShazMoghaddam/orbs)
|
|
11
|
+
[](https://github.com/ShazMoghaddam/orbs)
|
|
12
|
+
|
|
13
|
+
Twenty-one morphing dot-formation animations for the web. Use them for loaders, AI "listening", "thinking" and "speaking" states, success and error badges, ambient desk displays, or one memorable moment in a hero.
|
|
14
|
+
|
|
15
|
+
One file, about 11 KB gzipped, no dependencies, no build step.
|
|
16
|
+
|
|
17
|
+
**[Open the Studio](https://shazmoghaddam.github.io/orbs/#studio)** to design an orb, copy its code, or export it as a video, GIF or image · See one in a real page in the Contact section of [shazmoghaddam.github.io](https://shazmoghaddam.github.io)
|
|
18
|
+
|
|
19
|
+

|
|
20
|
+
|
|
21
|
+
## Quick start
|
|
22
|
+
|
|
23
|
+
Add a canvas, size it with CSS, then load the script.
|
|
24
|
+
|
|
25
|
+
```html
|
|
26
|
+
<canvas data-orb="torus" style="width:200px; height:200px; color:#FF4400" aria-hidden="true"></canvas>
|
|
27
|
+
|
|
28
|
+
<script src="https://cdn.jsdelivr.net/gh/ShazMoghaddam/orbs@1.8.0/orb.min.js" defer></script>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Every `<canvas data-orb>` on the page starts automatically. The dots use the canvas's CSS `color`, so you theme an orb the same way you theme text.
|
|
32
|
+
|
|
33
|
+
You can also download `orb.min.js` and host it yourself.
|
|
34
|
+
|
|
35
|
+
### With npm
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
npm install @shazmoghaddam/orbs
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
```js
|
|
42
|
+
import Orb from '@shazmoghaddam/orbs';
|
|
43
|
+
|
|
44
|
+
const orb = new Orb(canvas, { state: 'thinking', style: 'lines', glow: true });
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
TypeScript types are included, so your editor suggests every option, shape and state. Importing on a server (Next.js, Nuxt and the like) is safe; create the orb in the browser.
|
|
48
|
+
|
|
49
|
+
### React
|
|
50
|
+
|
|
51
|
+
```jsx
|
|
52
|
+
import { useEffect, useRef } from 'react';
|
|
53
|
+
import Orb from '@shazmoghaddam/orbs';
|
|
54
|
+
|
|
55
|
+
export function StatusOrb({ state = 'idle' }) {
|
|
56
|
+
const canvas = useRef(null);
|
|
57
|
+
const orb = useRef(null);
|
|
58
|
+
useEffect(() => {
|
|
59
|
+
orb.current = new Orb(canvas.current, { state });
|
|
60
|
+
return () => orb.current.destroy();
|
|
61
|
+
}, []);
|
|
62
|
+
useEffect(() => { orb.current?.state(state); }, [state]);
|
|
63
|
+
return <canvas ref={canvas} style={{ width: 200, height: 200, color: '#FF7A45' }} aria-hidden="true" />;
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### Vue
|
|
68
|
+
|
|
69
|
+
```vue
|
|
70
|
+
<script setup>
|
|
71
|
+
import { ref, watch, onMounted, onBeforeUnmount } from 'vue';
|
|
72
|
+
import Orb from '@shazmoghaddam/orbs';
|
|
73
|
+
|
|
74
|
+
const props = defineProps({ state: { type: String, default: 'idle' } });
|
|
75
|
+
const canvas = ref(null);
|
|
76
|
+
let orb;
|
|
77
|
+
onMounted(() => { orb = new Orb(canvas.value, { state: props.state }); });
|
|
78
|
+
watch(() => props.state, (s) => orb?.state(s));
|
|
79
|
+
onBeforeUnmount(() => orb?.destroy());
|
|
80
|
+
</script>
|
|
81
|
+
|
|
82
|
+
<template>
|
|
83
|
+
<canvas ref="canvas" style="width: 200px; height: 200px; color: #FF7A45" aria-hidden="true" />
|
|
84
|
+
</template>
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
The [Studio](https://shazmoghaddam.github.io/orbs/#studio) writes these for you, with your settings filled in.
|
|
88
|
+
|
|
89
|
+
## Shapes
|
|
90
|
+
|
|
91
|
+
| Shape | What it looks like |
|
|
92
|
+
| --- | --- |
|
|
93
|
+
| `sphere` | Evenly spread dots on a slowly turning globe |
|
|
94
|
+
| `wave` | A liquid surface that swells, with brighter crests |
|
|
95
|
+
| `spikes` | Every dot becomes a spine, rippling like an audio visualiser |
|
|
96
|
+
| `constellation` | Star nodes linked to their nearest neighbours, twinkling |
|
|
97
|
+
| `torus` | A donut seen almost face-on, its surface rolling inside out |
|
|
98
|
+
| `helix` | A double helix with rungs |
|
|
99
|
+
| `galaxy` | Three spiral arms around a bright core, gently swaying |
|
|
100
|
+
| `ticks` | A dashed loader ring with a pulse chasing round it |
|
|
101
|
+
| `cube` | A wireframe cube built from dots |
|
|
102
|
+
| `layers` | Four tall, slanted diamonds overlapping like stacked sheets, lit in a wave and rocking gently |
|
|
103
|
+
| `clusters` | Four k-means style clusters breathing, linked to their centroids |
|
|
104
|
+
| `ripple` | Rings spreading out from the centre and fading, for listening |
|
|
105
|
+
| `bars` | Columns of dots rising and falling, for speaking |
|
|
106
|
+
| `atom` | A small nucleus with three orbits, each carrying a bright electron |
|
|
107
|
+
| `infinity` | A figure of eight with a bright pulse running round it |
|
|
108
|
+
| `vortex` | Three arms spiralling inwards and down a funnel, for thinking |
|
|
109
|
+
| `blob` | A sphere whose surface wobbles slowly, like a drop of liquid |
|
|
110
|
+
| `iris` | An eye that faces you: radial fibres, a breathing pupil, a glance and a blink, for listening |
|
|
111
|
+
| `orbit` | Four large, soft dots circling on their own tilted paths, for calm, ambient moments |
|
|
112
|
+
| `check` | A success badge: a dotted ring with a tick inside |
|
|
113
|
+
| `cross` | An error badge: the same ring with an X inside |
|
|
114
|
+
|
|
115
|
+
Any shape can morph into any other. Dots leave in a top-to-bottom cascade, and lines and dashes fade in and out with the morph.
|
|
116
|
+
|
|
117
|
+
`check` and `cross` are status badges, so they are left out of the default cycle. Morph to them yourself, or list them in `data-shapes`. Flat shapes (`layers`, `bars`, `infinity`, `iris`, `check` and `cross`) turn to face the viewer instead of spinning, so they always read clearly. `atom` is busy at loader size, so use it at about 120 px or larger.
|
|
118
|
+
|
|
119
|
+
## Options
|
|
120
|
+
|
|
121
|
+
Set options as `data-` attributes, or pass them to the constructor.
|
|
122
|
+
|
|
123
|
+
| Attribute | JS option | Default | What it does |
|
|
124
|
+
| --- | --- | --- | --- |
|
|
125
|
+
| `data-orb` | `shape` | `sphere` | Starting shape |
|
|
126
|
+
| `data-shapes` | `shapes` | all except `check` and `cross` | Comma list of shapes to cycle through |
|
|
127
|
+
| `data-points` | `points` | `180`, or `320` with lines | Number of dots. Use 60 to 100 for small loaders |
|
|
128
|
+
| `data-dot` | `dot` | `1.2` | Dot radius in CSS pixels |
|
|
129
|
+
| `data-speed` | `speed` | `0.35` | Rotation speed in radians per second |
|
|
130
|
+
| `data-cycle` | `cycle` | `0` | Milliseconds between automatic morphs. `0` turns it off |
|
|
131
|
+
| `data-hover="morph"` | `hover: 'morph'` | off | Morph to the next shape on hover or tap |
|
|
132
|
+
| `data-click="morph"` | `click: 'morph'` | off | Morph to the next shape only on click or tap. Wrap the canvas in a `<button>` so keyboard users can use it too |
|
|
133
|
+
| `data-theme-morph` | `themeMorph: true` | off | Morph when `<body>`'s `data-theme` or `class` changes |
|
|
134
|
+
| `data-style` | `style` | `dots` | `lines` draws the shape as glowing vertical slices. See [Lines style](#lines-style) |
|
|
135
|
+
| `data-line` | `line` | auto | Line thickness in CSS pixels, for slices and connecting lines |
|
|
136
|
+
| `data-glow` | `glow` | off | A soft glow behind the shape. On its own it uses 8 px; a number sets the size |
|
|
137
|
+
| `data-audio` | `audio` | off | CSS selector of an `<audio>` or `<video>` to react to once it plays. See [React to sound](#react-to-sound) |
|
|
138
|
+
| `data-audio-amount` | `audioAmount` | `1` | How strongly it reacts to sound |
|
|
139
|
+
| `data-tilt` | `tilt` | `0` | Extra tilt in degrees, added to each shape's own angle |
|
|
140
|
+
| `data-state` | `state` | none | A named state, such as `thinking`. See [Named states](#named-states). Change the attribute later to switch |
|
|
141
|
+
| `data-follow` | `follow: true` | off | Lean towards the pointer |
|
|
142
|
+
| `data-scroll-tilt` | `scrollTilt: true` | off | Tilt as the orb scrolls through the page |
|
|
143
|
+
| `data-reflect` | `reflect` | off | A faded mirror image underneath. On its own it uses 0.35; a number from 0 to 1 sets its strength |
|
|
144
|
+
|
|
145
|
+
## Lines style
|
|
146
|
+
|
|
147
|
+
Any shape can be drawn as glowing vertical slices instead of dots, inspired by the scan-line look in music videos. Solid shapes like `sphere`, `wave` and `torus` become sliced silhouettes, `bars` becomes a waveform, and `check`, `cross` and `infinity` keep their clean outlines.
|
|
148
|
+
|
|
149
|
+
```html
|
|
150
|
+
<canvas data-orb="bars" data-style="lines" data-glow data-reflect
|
|
151
|
+
style="width:320px;height:320px;color:#6FD8F2" aria-hidden="true"></canvas>
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
`data-glow` and `data-reflect` work with dots too. Lines look best from about 120 px up, and on dark backgrounds with a bright colour. `constellation`, `clusters` and `orbit` are sparse, so they suit dots better. See [`examples/lines.html`](examples/lines.html).
|
|
155
|
+
|
|
156
|
+
## Desk display
|
|
157
|
+
|
|
158
|
+
Turn a spare iPad, tablet or monitor into an ambient orb. Design one in the [Studio](https://shazmoghaddam.github.io/orbs/#studio), then copy its display link from **Get the code**, or write one yourself:
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
https://shazmoghaddam.github.io/orbs/display.html?shape=orbit&color=FF7A45&glow=8
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
It takes the same settings as the Studio's share links. Tap once for full screen. The display keeps the screen awake where the browser allows it, hides the cursor when idle, and drifts a few pixels each minute so nothing burns in. Add `&sound=mic` and it reacts to music in the room after that first tap; the sound is analysed on the device and never recorded or sent. On an iPad, use **Share → Add to Home Screen** to open it without browser bars.
|
|
165
|
+
|
|
166
|
+
## React to sound
|
|
167
|
+
|
|
168
|
+
An orb can move with music, a voice or a microphone. `bars` follows the actual frequencies, bass in the middle and treble at the edges. Other shapes pulse with the volume and push out on the beat, and flat marks like `check` only pulse, so they stay readable.
|
|
169
|
+
|
|
170
|
+
With an audio or video player on the page, no JavaScript is needed:
|
|
171
|
+
|
|
172
|
+
```html
|
|
173
|
+
<audio id="player" src="track.mp3" controls></audio>
|
|
174
|
+
<canvas data-orb="bars" data-style="lines" data-glow data-audio="#player" aria-hidden="true"></canvas>
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Or from JavaScript, call `listen` from a click, since browsers only start audio after a user gesture:
|
|
178
|
+
|
|
179
|
+
```js
|
|
180
|
+
button.addEventListener('click', () => orb.listen('mic')); // a microphone, a MediaStream,
|
|
181
|
+
orb.listen(videoElement); // an <audio> or <video>,
|
|
182
|
+
orb.listen(myAudioNode); // or any Web Audio node
|
|
183
|
+
orb.unlisten(); // stop reacting
|
|
184
|
+
|
|
185
|
+
orb.audio.level; // 0 to 1, while listening
|
|
186
|
+
orb.audio.bands; // 16 values from bass to treble, 0 to 1
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
- **Microphone:** sound is analysed in the browser and never played back, recorded or sent anywhere. The browser asks for permission, and it needs HTTPS (or localhost).
|
|
190
|
+
- **Audio from another site:** a file served from a different domain needs CORS headers and `crossorigin="anonymous"` on the element. Without them the browser silences it once Orbs is connected, which is a browser rule rather than something Orbs can work around. Pages opened straight from disk (`file://`) count as another site too, so test audio files through a local server, for example `python3 -m http.server`.
|
|
191
|
+
- **Web Audio nodes:** use `Orb.audioContext()` to create them, so they share the orb's audio context.
|
|
192
|
+
- Shapes can define their own `audio(i, data, A, p, out)` hook, as `bars` does.
|
|
193
|
+
|
|
194
|
+
See [`examples/audio.html`](examples/audio.html), which has a built-in demo beat, a microphone button and a file picker.
|
|
195
|
+
|
|
196
|
+
## JavaScript API
|
|
197
|
+
|
|
198
|
+
```js
|
|
199
|
+
const orb = new Orb(canvas, { shape: 'wave', points: 90 });
|
|
200
|
+
|
|
201
|
+
orb.morph('ticks'); // go to a specific shape
|
|
202
|
+
orb.next(); // go to the next shape in `shapes`
|
|
203
|
+
orb.state('thinking'); // a named state: shape and pace together
|
|
204
|
+
orb.set({ style: 'lines', glow: 10, speed: 0.6 }); // change settings while it runs
|
|
205
|
+
orb.destroy(); // stop and remove listeners
|
|
206
|
+
|
|
207
|
+
canvas.addEventListener('orb:morph', e => console.log(e.detail.shape)); // after every morph
|
|
208
|
+
|
|
209
|
+
Orb.shapes; // every registered shape
|
|
210
|
+
Orb.init(root); // start any <canvas data-orb> added after the page loaded
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
`set` takes any option from the table above except the shape list for hover and click, and changes it without restarting the orb. Changing `points` rebuilds the shape in place. `Orb.init` is handy in React, Vue or anything else that adds canvases later; it skips canvases that are already running.
|
|
214
|
+
|
|
215
|
+
## Named states
|
|
216
|
+
|
|
217
|
+
Most orbs show what something is doing, so Orbs has names for that. A state picks a shape and a pace, and morphing one orb between states reads better than swapping spinners.
|
|
218
|
+
|
|
219
|
+
| State | Shape | Feels |
|
|
220
|
+
| --- | --- | --- |
|
|
221
|
+
| `idle` | `orbit` | calm, unhurried |
|
|
222
|
+
| `listening` | `iris` | attentive |
|
|
223
|
+
| `thinking` | `vortex` | computational |
|
|
224
|
+
| `working` | `ticks` | busy |
|
|
225
|
+
| `speaking` | `bars` | voice |
|
|
226
|
+
| `active` | `blob` | responsive |
|
|
227
|
+
| `loading` | `infinity` | patient |
|
|
228
|
+
| `success` | `check` | done |
|
|
229
|
+
| `error` | `cross` | something went wrong |
|
|
230
|
+
|
|
231
|
+
```js
|
|
232
|
+
orb.state('listening');
|
|
233
|
+
orb.state('thinking');
|
|
234
|
+
orb.state('success');
|
|
235
|
+
|
|
236
|
+
canvas.addEventListener('orb:state', e => console.log(e.detail.state));
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
Or with no JavaScript at all: `<canvas data-orb data-state="thinking">`. Change the attribute later and the orb follows, which is all React or Vue needs:
|
|
240
|
+
|
|
241
|
+
```jsx
|
|
242
|
+
<canvas data-orb data-state={busy ? 'thinking' : 'idle'} />
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
Add or change states with `Orb.states.reviewing = { shape: 'helix', speed: 0.6 }`. A state stops any cycling, since it says exactly what the orb should show. See [`examples/loader.html`](examples/loader.html).
|
|
246
|
+
|
|
247
|
+
## Cursor and scroll
|
|
248
|
+
|
|
249
|
+
`data-follow` makes an orb lean gently towards the pointer, and `data-scroll-tilt` tilts it as it moves through the page. Both ease in rather than snap, sit on top of the shape's own motion, and turn off when the visitor has reduced motion on.
|
|
250
|
+
|
|
251
|
+
```html
|
|
252
|
+
<canvas data-orb="torus" data-follow data-scroll-tilt aria-hidden="true"></canvas>
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
## Custom shapes
|
|
256
|
+
|
|
257
|
+
`Orb.define` registers a new shape. `build(n)` must return `n` points inside the unit sphere. Everything else is optional.
|
|
258
|
+
|
|
259
|
+
```js
|
|
260
|
+
Orb.define('ring2', {
|
|
261
|
+
build(n) {
|
|
262
|
+
const pts = [];
|
|
263
|
+
for (let i = 0; i < n; i++) {
|
|
264
|
+
const a = (i / n) * Math.PI * 2;
|
|
265
|
+
pts.push([Math.cos(a) * 0.8, (i % 2 ? 0.1 : -0.1), Math.sin(a) * 0.8]);
|
|
266
|
+
}
|
|
267
|
+
return { pts };
|
|
268
|
+
},
|
|
269
|
+
tilt: 1.2, // camera tilt in radians
|
|
270
|
+
spin: 0.5, // rotation multiplier
|
|
271
|
+
face: false, // true turns the orb to face the viewer instead of spinning
|
|
272
|
+
inCycle: true, // false leaves the shape out of the default cycle
|
|
273
|
+
lineGap: 0.45, // lines style: the widest gap (in radii) still joined into one line
|
|
274
|
+
bigDots: false, // true makes size a percentage of the orb's radius, for large soft dots
|
|
275
|
+
size: 1, // dot size multiplier, number or function(i, data, t, p)
|
|
276
|
+
alpha: 1, // opacity multiplier, number or function(i, data, t, p)
|
|
277
|
+
dash: (i, data, t, p) => 0, // above 0, draws a radial stroke of that length instead of a dot
|
|
278
|
+
audio(i, data, A, p, out) {}, // optional: react to sound. A.bands (16) and A.level are 0 to 1
|
|
279
|
+
deform(i, data, t, p, out) { // live motion: write a moved copy of p into out
|
|
280
|
+
out[0] = p[0]; out[1] = p[1] + Math.sin(t + i) * 0.05; out[2] = p[2];
|
|
281
|
+
}
|
|
282
|
+
});
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
To draw lines between points, return `edges: [[i, j], ...]` from `build` and set `edgeAlpha` on the shape.
|
|
286
|
+
|
|
287
|
+
## Turning a letter into an orb
|
|
288
|
+
|
|
289
|
+
Keep the real letter in the HTML and lay the canvas over it. Search engines and screen readers still read the word, and if the script fails the letter simply shows. See [`examples/letter.html`](examples/letter.html).
|
|
290
|
+
|
|
291
|
+
```html
|
|
292
|
+
<h1>Hell<span class="orb-letter">o<canvas data-orb="sphere" aria-hidden="true"></canvas></span></h1>
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
```css
|
|
296
|
+
.orb-letter { position: relative; display: inline-block; }
|
|
297
|
+
.orb-letter canvas { position: absolute; left: 50%; top: 62%; width: .72em; height: .72em; transform: translate(-50%, -50%); }
|
|
298
|
+
.orb-letter.orb-ready { color: transparent; } /* added by the script once the orb is running */
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
The `top` and `width` values depend on your typeface, so nudge them until the orb sits on the letter's x-height.
|
|
302
|
+
|
|
303
|
+
## Accessibility and performance
|
|
304
|
+
|
|
305
|
+
- When the visitor has reduced motion turned on, each orb shows a still frame, morphs happen instantly, and orbs don't react to sound.
|
|
306
|
+
- Orbs only animate while they are on screen and the tab is visible.
|
|
307
|
+
- Canvases render at device pixel ratio (capped at 2) and resize with their container.
|
|
308
|
+
- The lines style costs a little more than dots. Glow and reflection each copy the finished frame, so they are off unless you ask for them. Glow is blurred at quarter size to keep it cheap, and browsers without canvas filters simply skip it.
|
|
309
|
+
- Orbs are decorative. Add `aria-hidden="true"` to the canvas and put any status text next to it, as the loader example does.
|
|
310
|
+
|
|
311
|
+
## Browser support
|
|
312
|
+
|
|
313
|
+
Any current browser with canvas, `requestAnimationFrame` and `ResizeObserver`. Older browsers fall back to window resize events.
|
|
314
|
+
|
|
315
|
+
## Building from source
|
|
316
|
+
|
|
317
|
+
`orb.min.js` is generated from `orb.js` with terser. After changing `orb.js`:
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
npm install
|
|
321
|
+
npm run check # rebuilds orb.min.js, runs the tests and checks the size budget
|
|
322
|
+
npm run serve # then open http://localhost:4173/
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
CI runs the same check on every pull request.
|
|
326
|
+
|
|
327
|
+
If Orbs is useful to you, a star on the repo helps other developers find it.
|
|
328
|
+
|
|
329
|
+
## Contributing
|
|
330
|
+
|
|
331
|
+
Bug reports, new shapes and Studio ideas are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md), and report security problems privately as [SECURITY.md](SECURITY.md) explains.
|
|
332
|
+
|
|
333
|
+
## Licence
|
|
334
|
+
|
|
335
|
+
[MIT](LICENSE). Use it in anything, commercial included. A link back is appreciated but not required.
|
|
336
|
+
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
Created by **Shaz Moghaddam** · London\
|
|
340
|
+
[Website](https://shazmoghaddam.github.io/) · [LinkedIn](https://www.linkedin.com/in/shazmoghaddam/)
|
package/orb.d.ts
ADDED
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
// Type definitions for Orbs 1.8
|
|
2
|
+
// https://github.com/ShazMoghaddam/orbs · Shaz Moghaddam · MIT
|
|
3
|
+
|
|
4
|
+
declare namespace Orb {
|
|
5
|
+
/** The built-in shapes. Custom shapes added with Orb.define work too. */
|
|
6
|
+
type ShapeName =
|
|
7
|
+
| 'sphere' | 'wave' | 'spikes' | 'constellation' | 'torus' | 'helix' | 'galaxy' | 'ticks'
|
|
8
|
+
| 'cube' | 'layers' | 'clusters' | 'ripple' | 'bars' | 'atom' | 'infinity' | 'vortex'
|
|
9
|
+
| 'blob' | 'iris' | 'orbit' | 'check' | 'cross';
|
|
10
|
+
|
|
11
|
+
/** The built-in named states. Add your own to Orb.states. */
|
|
12
|
+
type StateName =
|
|
13
|
+
| 'idle' | 'listening' | 'thinking' | 'working' | 'speaking'
|
|
14
|
+
| 'active' | 'loading' | 'success' | 'error';
|
|
15
|
+
|
|
16
|
+
type Vec3 = [number, number, number];
|
|
17
|
+
/** A number, or a function of (dot index, shape data, seconds, position). */
|
|
18
|
+
type PerDot = number | ((i: number, data: any, t: number, p: Vec3) => number);
|
|
19
|
+
|
|
20
|
+
interface Options {
|
|
21
|
+
/** First shape. Defaults to the first shape in `shapes`. */
|
|
22
|
+
shape?: ShapeName | (string & {});
|
|
23
|
+
/** A named state, which picks the shape and pace. */
|
|
24
|
+
state?: StateName | (string & {});
|
|
25
|
+
/** Shapes to cycle through, as an array or a comma-separated string. Defaults to all except check and cross. */
|
|
26
|
+
shapes?: Array<ShapeName | (string & {})> | string;
|
|
27
|
+
/** Number of dots. Default 180, or 320 with the lines style. */
|
|
28
|
+
points?: number;
|
|
29
|
+
/** Base rotation in radians per second. Default 0.35. */
|
|
30
|
+
speed?: number;
|
|
31
|
+
/** Dot radius in CSS pixels. Default 1.2. */
|
|
32
|
+
dot?: number;
|
|
33
|
+
/** Milliseconds between automatic morphs; 0 turns cycling off. Default 0. */
|
|
34
|
+
cycle?: number;
|
|
35
|
+
/** 'dots' (default) or 'lines', which draws glowing vertical slices. */
|
|
36
|
+
style?: 'dots' | 'lines';
|
|
37
|
+
/** Line thickness in CSS pixels for slices and connecting lines; 0 is automatic. */
|
|
38
|
+
line?: number;
|
|
39
|
+
/** A soft glow behind the shape: true for 8 px, or a size in pixels. */
|
|
40
|
+
glow?: boolean | number;
|
|
41
|
+
/** A faded mirror image underneath: true for 0.35, or a strength from 0 to 1. */
|
|
42
|
+
reflect?: boolean | number;
|
|
43
|
+
/** Extra tilt in degrees, added to each shape's own angle. */
|
|
44
|
+
tilt?: number;
|
|
45
|
+
/** Lean gently towards the pointer. */
|
|
46
|
+
follow?: boolean;
|
|
47
|
+
/** Tilt as the orb scrolls through the page. */
|
|
48
|
+
scrollTilt?: boolean;
|
|
49
|
+
/** 'morph' changes shape on hover or tap. */
|
|
50
|
+
hover?: 'morph';
|
|
51
|
+
/** 'morph' changes shape on click or tap only. */
|
|
52
|
+
click?: 'morph';
|
|
53
|
+
/** Morph when <body>'s data-theme or class changes. */
|
|
54
|
+
themeMorph?: boolean;
|
|
55
|
+
/** An <audio> or <video> (or a selector for one) to react to once it plays. */
|
|
56
|
+
audio?: HTMLMediaElement | string;
|
|
57
|
+
/** How strongly the orb reacts to sound. Default 1. */
|
|
58
|
+
audioAmount?: number;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Settings that can change on a running orb with orb.set(). */
|
|
62
|
+
type Settings = Omit<Options, 'hover' | 'click' | 'themeMorph' | 'audio'>;
|
|
63
|
+
|
|
64
|
+
interface Audio {
|
|
65
|
+
/** Overall loudness, 0 to 1. */
|
|
66
|
+
level: number;
|
|
67
|
+
/** Sixteen values from bass to treble, each 0 to 1. */
|
|
68
|
+
bands: Float32Array;
|
|
69
|
+
/** Set when listening to a microphone. */
|
|
70
|
+
stream?: MediaStream;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
interface Shape {
|
|
74
|
+
/** Return n points inside the unit sphere, plus any data the other hooks need. */
|
|
75
|
+
build(n: number): { pts: Vec3[]; edges?: Array<[number, number]>; [key: string]: any };
|
|
76
|
+
/** Camera tilt in radians. */
|
|
77
|
+
tilt?: number;
|
|
78
|
+
/** Rotation multiplier. */
|
|
79
|
+
spin?: number;
|
|
80
|
+
/** Live motion: write a moved copy of p into out. */
|
|
81
|
+
deform?(i: number, data: any, t: number, p: Vec3, out: Vec3): void;
|
|
82
|
+
/** Greater than 0 draws a radial stroke of that length instead of a dot. */
|
|
83
|
+
dash?(i: number, data: any, t: number, p: Vec3): number;
|
|
84
|
+
/** React to sound: write a moved copy of p into out. */
|
|
85
|
+
audio?(i: number, data: any, A: Audio, p: Vec3, out: Vec3): void;
|
|
86
|
+
size?: PerDot;
|
|
87
|
+
alpha?: PerDot;
|
|
88
|
+
edgeAlpha?: PerDot;
|
|
89
|
+
/** Turn to face the viewer instead of spinning, for flat marks. */
|
|
90
|
+
face?: boolean;
|
|
91
|
+
/** false leaves the shape out of the default cycle. */
|
|
92
|
+
inCycle?: boolean;
|
|
93
|
+
/** Lines style: the widest gap, in radii, still joined into one line. Default 0.45. */
|
|
94
|
+
lineGap?: number;
|
|
95
|
+
/** Size dots as a percentage of the orb's radius instead of pixels. */
|
|
96
|
+
bigDots?: boolean;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
interface State {
|
|
100
|
+
shape: ShapeName | (string & {});
|
|
101
|
+
speed?: number;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** Detail of the 'orb:morph' event. */
|
|
105
|
+
interface MorphDetail { shape: string }
|
|
106
|
+
/** Detail of the 'orb:state' event. */
|
|
107
|
+
interface StateDetail { state: string; shape: string }
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
declare class Orb {
|
|
111
|
+
constructor(canvas: HTMLCanvasElement, options?: Orb.Options);
|
|
112
|
+
|
|
113
|
+
/** The current shape. */
|
|
114
|
+
readonly shape: string;
|
|
115
|
+
/** The current named state, if one was set. */
|
|
116
|
+
readonly stateName?: string;
|
|
117
|
+
/** Sound analysis while listening, otherwise null. */
|
|
118
|
+
readonly audio: Orb.Audio | null;
|
|
119
|
+
|
|
120
|
+
/** Morph to a shape. */
|
|
121
|
+
morph(shape: Orb.ShapeName | (string & {})): this;
|
|
122
|
+
/** Morph to the next shape in the cycle. */
|
|
123
|
+
next(): this;
|
|
124
|
+
/** Switch to a named state: its shape and pace together. */
|
|
125
|
+
state(name: Orb.StateName | (string & {})): this;
|
|
126
|
+
/** Change settings while the orb runs. */
|
|
127
|
+
set(settings: Orb.Settings): this;
|
|
128
|
+
/** React to sound: an <audio> or <video>, a MediaStream, any Web Audio node, or 'mic'. Call it from a click. */
|
|
129
|
+
listen(source: HTMLMediaElement | MediaStream | AudioNode | 'mic'): Promise<this>;
|
|
130
|
+
/** Stop reacting to sound. A microphone this orb opened is closed. */
|
|
131
|
+
unlisten(): this;
|
|
132
|
+
/** Re-read the canvas's CSS colour, after changing it from script. */
|
|
133
|
+
refreshColor(): void;
|
|
134
|
+
/** Stop the orb and remove its listeners. */
|
|
135
|
+
destroy(): void;
|
|
136
|
+
|
|
137
|
+
/** Every registered shape. */
|
|
138
|
+
static shapes: Record<string, Orb.Shape>;
|
|
139
|
+
/** Every named state. Add your own: Orb.states.reviewing = { shape: 'helix', speed: 0.6 }. */
|
|
140
|
+
static states: Record<string, Orb.State>;
|
|
141
|
+
/** Register a custom shape. */
|
|
142
|
+
static define(name: string, shape: Orb.Shape): void;
|
|
143
|
+
/** Start any <canvas data-orb> inside root (default: the whole page) that isn't running yet. */
|
|
144
|
+
static init(root?: ParentNode): void;
|
|
145
|
+
/** The shared Web Audio context, for building your own audio nodes. */
|
|
146
|
+
static audioContext(): AudioContext | null;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
declare global {
|
|
150
|
+
interface Window { Orb: typeof Orb }
|
|
151
|
+
interface HTMLElementEventMap {
|
|
152
|
+
'orb:morph': CustomEvent<Orb.MorphDetail>;
|
|
153
|
+
'orb:state': CustomEvent<Orb.StateDetail>;
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
export = Orb;
|