@link-foundation/ui-sound 0.0.0-stage → 0.1.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 +24 -0
- package/README.md +202 -2
- package/package.json +51 -4
- package/src/audio-session.js +82 -0
- package/src/bind.js +77 -0
- package/src/comfort.js +34 -0
- package/src/document.js +149 -0
- package/src/graph.js +217 -0
- package/src/index.d.ts +196 -0
- package/src/index.js +17 -0
- package/src/player.js +214 -0
- package/src/runtime.js +124 -0
- package/src/settings.js +215 -0
- package/src/theme.js +308 -0
- package/themes/immortality.lino +867 -0
- package/themes/quiet.lino +101 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
This is free and unencumbered software released into the public domain.
|
|
2
|
+
|
|
3
|
+
Anyone is free to copy, modify, publish, use, compile, sell, or
|
|
4
|
+
distribute this software, either in source code form or as a compiled
|
|
5
|
+
binary, for any purpose, commercial or non-commercial, and by any
|
|
6
|
+
means.
|
|
7
|
+
|
|
8
|
+
In jurisdictions that recognize copyright laws, the author or authors
|
|
9
|
+
of this software dedicate any and all copyright interest in the
|
|
10
|
+
software to the public domain. We make this dedication for the benefit
|
|
11
|
+
of the public at large and to the detriment of our heirs and
|
|
12
|
+
successors. We intend this dedication to be an overt act of
|
|
13
|
+
relinquishment in perpetuity of all present and future rights to this
|
|
14
|
+
software under copyright law.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
19
|
+
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
20
|
+
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
21
|
+
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
22
|
+
OTHER DEALINGS IN THE SOFTWARE.
|
|
23
|
+
|
|
24
|
+
For more information, please refer to <https://unlicense.org>
|
package/README.md
CHANGED
|
@@ -1,3 +1,203 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @link-foundation/ui-sound
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Opt-in UI sound synthesized with Web Audio from Links Notation themes.
|
|
4
|
+
No audio files, network requests or import-time browser effects.
|
|
5
|
+
|
|
6
|
+
```js
|
|
7
|
+
import {
|
|
8
|
+
readSoundTheme,
|
|
9
|
+
createSoundPlayer,
|
|
10
|
+
bindSoundConfig,
|
|
11
|
+
bindSound,
|
|
12
|
+
} from '@link-foundation/ui-sound';
|
|
13
|
+
import { createConfig, persistUserLayer } from '@link-foundation/ui-config';
|
|
14
|
+
import { parse } from '@link-foundation/ui-core';
|
|
15
|
+
|
|
16
|
+
// Load this bundled text using your host's file loader or fetch:
|
|
17
|
+
// @link-foundation/ui-sound/themes/quiet.lino
|
|
18
|
+
const { theme, diagnostics } = readSoundTheme(themeText);
|
|
19
|
+
if (!theme) throw new Error(diagnostics.map((d) => d.message).join('\n'));
|
|
20
|
+
const config = createConfig({ document: parse('settings: box') });
|
|
21
|
+
const persistence = persistUserLayer(config, localStorage);
|
|
22
|
+
const settings = bindSoundConfig(config);
|
|
23
|
+
const player = createSoundPlayer({ theme, config: settings });
|
|
24
|
+
const binding = bindSound(player);
|
|
25
|
+
// Pass binding.onAction to ui-dom mountDocument or #33 mountBehavior.
|
|
26
|
+
// Enable only in response to the viewer's explicit choice:
|
|
27
|
+
settings.set('sound.enabled', true);
|
|
28
|
+
player.setVolume(0.3);
|
|
29
|
+
// Audio initializes lazily when the page has user activation.
|
|
30
|
+
player.play('click', { x: 0.5 });
|
|
31
|
+
player.cue('open');
|
|
32
|
+
const unsubscribe = player.onCue(({ event, pan }) => drawResonance(event, pan));
|
|
33
|
+
player.mute(); // persists sound.enabled = false
|
|
34
|
+
player.mute(false); // persists sound.enabled = true
|
|
35
|
+
// On unmount:
|
|
36
|
+
unsubscribe();
|
|
37
|
+
binding.dispose();
|
|
38
|
+
await player.dispose();
|
|
39
|
+
persistence.stop();
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
`createSoundPlayer` accepts `{theme, config, now, random, createContext,
|
|
43
|
+
gestureTarget, document, hasBeenActive, maxVolume, reducedMotion,
|
|
44
|
+
reducedMotionEvents, onDiagnostic}`. Only theme is required. The
|
|
45
|
+
optional config has `get`, `set`, `subscribe` as provided by
|
|
46
|
+
`bindSoundConfig`. Without it, volume/mute live in memory and sound starts
|
|
47
|
+
off. `mute(false)` enables it. `now` returns milliseconds; `random` returns
|
|
48
|
+
[0,1). Inject these and `createContext` for deterministic tests. Browser
|
|
49
|
+
failures reach `onDiagnostic`; it defaults to no logging. The player exposes
|
|
50
|
+
read-only `enabled` and `volume`. `play` returns the selected voice names
|
|
51
|
+
or an empty array when silent. `cue` is its public event-name alias.
|
|
52
|
+
|
|
53
|
+
A theme has named voices (oscillator/noise graphs, envelopes, optional
|
|
54
|
+
filters/FM/delays/repeats), event modes `random`, `cycle`, `layer`, per-event
|
|
55
|
+
throttling, a shelf/compressor/reverb bus, and per-voice provenance.
|
|
56
|
+
[The specification](../../docs/spec/sound.md) defines all fields and bounds.
|
|
57
|
+
`createSoundBus(context, settings, random)` and
|
|
58
|
+
`playVoice(context, voice, output, options)` also accept an offline or fake
|
|
59
|
+
BaseAudioContext directly. `playVoice` returns the scheduled end time.
|
|
60
|
+
|
|
61
|
+
Bundled themes are `quiet` (five soft voices) and `immortality` (all 26
|
|
62
|
+
patches, including noise, FM and stereo parts). The port is from
|
|
63
|
+
[konard/immortality at 16a6172](https://github.com/konard/immortality/tree/16a6172c38fc120133485f805c49d980b9850bc4)
|
|
64
|
+
under the Unlicense. Every source record retains the original character,
|
|
65
|
+
source label and reference URL from SOUNDS in settings.ts. Those references
|
|
66
|
+
identify inspiration, not downloaded assets; only synthesized code is
|
|
67
|
+
ported. The quiet theme is original CC0-1.0 work. Reproduce the port with
|
|
68
|
+
[the experiment script](../../experiments/issue-74/port.mjs).
|
|
69
|
+
|
|
70
|
+
`bindSound` maps #33 `press` to `click`, `open` to `open`, etc. It accepts
|
|
71
|
+
a LiNo `sound-map` override and optional interpreter `machines`. Pass its
|
|
72
|
+
`onAction` callback to the existing renderer; it deduplicates multiple
|
|
73
|
+
actions per native event. Machine subscriptions map accepted transition
|
|
74
|
+
events. Bind each interaction through one route. Call `dispose` on both
|
|
75
|
+
binding and player when unmounting.
|
|
76
|
+
|
|
77
|
+
Sound is off by default and audio never starts before a user gesture.
|
|
78
|
+
Respect the viewer's choice: include `SOUND_SETTINGS_LINO` comfort fields
|
|
79
|
+
in your settings schema (`soundSettingsSchema()` returns the standalone
|
|
80
|
+
schema; merge fields into the host schema without a second schema header).
|
|
81
|
+
Use ui-settings preset/shared-look/randomize functions before updating the
|
|
82
|
+
config user layer. `SOUND_COMFORT_KEYS` exports the explicit key list.
|
|
83
|
+
Never copy sound preferences from another viewer's raw config patch.
|
|
84
|
+
Persist the user layer to keep volume on reload. Only motion-linked intro
|
|
85
|
+
and scan cues respect reduced motion; all other sounds follow the viewer's
|
|
86
|
+
sound preference. Keep visual/text/ARIA equivalents for all information,
|
|
87
|
+
and make mute and volume available through accessible host controls.
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
node --test packages/ui-sound/tests/*.test.js
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Live controls and preview
|
|
94
|
+
|
|
95
|
+
`player.configure(values)` updates settings in memory without creating or
|
|
96
|
+
replacing the AudioContext. Fields are `volume` (0–1), `tone` (high-shelf dB,
|
|
97
|
+
−40–40), `frequency` (1–24000 Hz), `reverb` (0–1), `room` (0.3–4 seconds),
|
|
98
|
+
`pitchSpread` (0–100 cents), `stereo`, `width` (0–1), `hoverGap` (0–500 ms),
|
|
99
|
+
`mode` (`random`, `cycle`, `layer`, or `null` to use event modes), and `enabled`.
|
|
100
|
+
Pass `maxVolume: 2` at player construction and schema generation to opt into
|
|
101
|
+
200% volume; the default maximum is 1. `setVolume` and `mute` persist through
|
|
102
|
+
config; `configure` is transient. Config changes apply generated settings live.
|
|
103
|
+
|
|
104
|
+
```js
|
|
105
|
+
player.configure({
|
|
106
|
+
frequency: 3200,
|
|
107
|
+
tone: -7, // warm; neutral 0, bright +5
|
|
108
|
+
reverb: 0.5,
|
|
109
|
+
room: 2,
|
|
110
|
+
pitchSpread: 15,
|
|
111
|
+
stereo: true,
|
|
112
|
+
width: 0.6,
|
|
113
|
+
events: {
|
|
114
|
+
activate: {
|
|
115
|
+
voices: ['tick', 'tap'],
|
|
116
|
+
mode: 'cycle',
|
|
117
|
+
level: 2,
|
|
118
|
+
throttle: 70,
|
|
119
|
+
},
|
|
120
|
+
},
|
|
121
|
+
});
|
|
122
|
+
player.preview('tick');
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
An event update replaces each supplied property, preserves omitted properties,
|
|
126
|
+
and leaves other events unchanged. Runtime lists contain zero to four known
|
|
127
|
+
voices; an empty list is silent. Invalid lists/modes throw at configuration.
|
|
128
|
+
Random selection excludes the last played voice for the same event. Layering
|
|
129
|
+
retains 1/√n headroom before the event level (0–2, default 1).
|
|
130
|
+
|
|
131
|
+
Each play shares one uniform detune within ±pitchSpread and a uniform level
|
|
132
|
+
variation up to ±10%, scaled by min(1, spread/15). Spread zero gives exactly
|
|
133
|
+
zero added detune and unity level. Defaults are 15 cents, stereo on, width 0.6.
|
|
134
|
+
Pointer pan is multiplied by width before part pan is added and clamped;
|
|
135
|
+
stereo off removes pointer pan while retaining part pan.
|
|
136
|
+
|
|
137
|
+
The bus exposes `shelf`, `wet`, `convolver` and `configure` in addition to
|
|
138
|
+
`input`, `master`, `disconnect`. Volume, shelf gain/frequency and send changes
|
|
139
|
+
use a 20 ms time constant. The wet route exists at initial reverb zero; changing
|
|
140
|
+
room replaces the impulse buffer in place. Noise uses a weakly held two-second
|
|
141
|
+
buffer per context/sample rate, looped from an independent random offset.
|
|
142
|
+
Envelopes stay exactly zero before delayed/repeated scheduled starts.
|
|
143
|
+
|
|
144
|
+
`preview(voiceName, {x})` bypasses event mapping, throttle and reduced-motion
|
|
145
|
+
event suppression; it still respects activation, enabled, volume, stereo,
|
|
146
|
+
humanization and the bus. Unknown voices are silent. The page visibility
|
|
147
|
+
listener suspends hidden audio; the next eligible visible play resumes it.
|
|
148
|
+
`hasBeenActive` defaults to `navigator.userActivation.hasBeenActive`. A lazily
|
|
149
|
+
created player can play immediately after sticky activation; pre-activation
|
|
150
|
+
plays never create audio or queue sounds. A captured gesture also unlocks a
|
|
151
|
+
subsequent enable-and-play in that same handler. Failed initialization retries
|
|
152
|
+
on a new gesture and reports through the existing opt-in diagnostics.
|
|
153
|
+
`reducedMotionEvents` (also configurable at runtime) defaults to `['intro', 'scan']`.
|
|
154
|
+
|
|
155
|
+
## Generated settings
|
|
156
|
+
|
|
157
|
+
`generateSoundSettings(theme, events, {slots: 4, maxVolume: 1})` returns a
|
|
158
|
+
nested LiNo fragment without a schema header. Append it to a host schema, or
|
|
159
|
+
use `createSoundSettingsSchema` for a standalone schema. Event entries are
|
|
160
|
+
names or `{name, label}` objects. `slots` is 1–4. The voice name `none` is
|
|
161
|
+
reserved in generated settings. Choice values remain voice names, with labels
|
|
162
|
+
from `source.character` (falling back to the name). `option-labels` metadata
|
|
163
|
+
is rendered by the standard settings panel. Global keys are `sound.enabled`,
|
|
164
|
+
`sound.volume`, `sound.mode`, `sound.tone`, `sound.reverb`, `sound.room`,
|
|
165
|
+
`sound.pitchSpread`, `sound.stereo`, `sound.width`, `sound.hoverGap`.
|
|
166
|
+
Tone choices are warm/neutral/bright; programmatic tone uses dB.
|
|
167
|
+
|
|
168
|
+
Event keys are `sound.events.EVENT.voice1` through `voice4` and
|
|
169
|
+
`sound.events.EVENT.level`. Slot n+1 is visible when n is not `none`;
|
|
170
|
+
playback stops reading slots at the first `none`. Room is visible only when
|
|
171
|
+
reverb is positive; width only while stereo is on. Every generated field is
|
|
172
|
+
comfort metadata, so presets, shared looks and randomization preserve it.
|
|
173
|
+
`SOUND_COMFORT_KEYS` lists the global keys; use `schema.fields` to enumerate
|
|
174
|
+
all generated event keys. The existing two-field `SOUND_SETTINGS_LINO` and
|
|
175
|
+
`soundSettingsSchema()` remain available for basic mute/volume consumers.
|
|
176
|
+
|
|
177
|
+
Pass `{schema}` to `bindSoundConfig(config, {schema})` to bind all generated
|
|
178
|
+
fields. The player subscribes to these fields, including consumer-only events.
|
|
179
|
+
The settings panel's `mountPreview` hook can call `player.preview(values[field.key])`
|
|
180
|
+
for fields marked `preview sound-voice`. See the complete, runnable
|
|
181
|
+
[settings example](examples/README.md), including accessible ▶ buttons.
|
|
182
|
+
|
|
183
|
+
## Plain document interaction binding
|
|
184
|
+
|
|
185
|
+
`bindSoundToDocument(player, {root: document, cueEvent: 'sound-cue', now})`
|
|
186
|
+
installs one set of capture listeners and returns `{dispose}`. `root` may also
|
|
187
|
+
be an element. Use this route once for controls outside ui-dom action binding.
|
|
188
|
+
|
|
189
|
+
- Mouse hover cues once on entry to an interactive control, throttled by the
|
|
190
|
+
player's live hover gap (default 80 ms). Touch and pen do not hover.
|
|
191
|
+
- Clicks cue `toggle` for checkboxes/pressed buttons, `select` for radios/tabs,
|
|
192
|
+
and `activate` for other buttons/links. An ancestor `data-sound="NAME"`
|
|
193
|
+
overrides classification; an empty value silences it.
|
|
194
|
+
- Summary clicks defer to the details `toggle` event, which cues `open`/`close`.
|
|
195
|
+
- Range input cues `select` every 70 ms; text input/textarea cues `type` every
|
|
196
|
+
30 ms; select/colour changes cue `select`.
|
|
197
|
+
- Pointer movement within `data-sound-scan` cues `scan` every 90 ms.
|
|
198
|
+
- Disabled, aria-disabled and inert controls are silent.
|
|
199
|
+
|
|
200
|
+
Components can dispatch `new CustomEvent('sound-cue', {detail: 'notify'})` on
|
|
201
|
+
window, or use `detail: {event: 'notify', x: 0.5}`. Set `cueEvent` to your
|
|
202
|
+
channel name (empty disables it). The binder uses injectable milliseconds
|
|
203
|
+
and removes all document/window listeners on disposal.
|
package/package.json
CHANGED
|
@@ -1,6 +1,53 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@link-foundation/ui-sound",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Opt-in synthesized UI sounds with LiNo themes and viewer-owned comfort settings",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": {
|
|
8
|
+
"types": "./src/index.d.ts",
|
|
9
|
+
"default": "./src/index.js"
|
|
10
|
+
},
|
|
11
|
+
"./themes/*": "./themes/*"
|
|
12
|
+
},
|
|
13
|
+
"types": "./src/index.d.ts",
|
|
14
|
+
"files": [
|
|
15
|
+
"src/",
|
|
16
|
+
"themes/",
|
|
17
|
+
"README.md",
|
|
18
|
+
"LICENSE"
|
|
19
|
+
],
|
|
20
|
+
"keywords": [
|
|
21
|
+
"ui",
|
|
22
|
+
"links-notation",
|
|
23
|
+
"sound",
|
|
24
|
+
"web-audio"
|
|
25
|
+
],
|
|
26
|
+
"license": "Unlicense",
|
|
27
|
+
"repository": {
|
|
28
|
+
"type": "git",
|
|
29
|
+
"url": "git+https://github.com/link-foundation/ui.git",
|
|
30
|
+
"directory": "packages/ui-sound"
|
|
31
|
+
},
|
|
32
|
+
"homepage": "https://github.com/link-foundation/ui/tree/main/packages/ui-sound#readme",
|
|
33
|
+
"bugs": {
|
|
34
|
+
"url": "https://github.com/link-foundation/ui/issues"
|
|
35
|
+
},
|
|
36
|
+
"engines": {
|
|
37
|
+
"node": ">=20"
|
|
38
|
+
},
|
|
39
|
+
"dependencies": {
|
|
40
|
+
"@link-foundation/ui-config": "^0.1.0",
|
|
41
|
+
"@link-foundation/ui-core": "^0.1.0",
|
|
42
|
+
"@link-foundation/ui-settings": "^0.1.0",
|
|
43
|
+
"links-notation": "^0.27.1"
|
|
44
|
+
},
|
|
45
|
+
"devDependencies": {
|
|
46
|
+
"@link-foundation/ui-components": "^0.1.0",
|
|
47
|
+
"jsdom": "^30.1.3",
|
|
48
|
+
"test-anywhere": "^0.8.48"
|
|
49
|
+
},
|
|
50
|
+
"publishConfig": {
|
|
51
|
+
"access": "public"
|
|
52
|
+
}
|
|
53
|
+
}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import { createSoundBus } from './graph.js';
|
|
2
|
+
|
|
3
|
+
/** One lazy context; failures remain opt-in diagnostics, never UI exceptions. */
|
|
4
|
+
export function audioSession({
|
|
5
|
+
theme,
|
|
6
|
+
state,
|
|
7
|
+
createContext,
|
|
8
|
+
random,
|
|
9
|
+
onDiagnostic,
|
|
10
|
+
document,
|
|
11
|
+
}) {
|
|
12
|
+
let audio;
|
|
13
|
+
let bus;
|
|
14
|
+
let failed = false;
|
|
15
|
+
const report = (error) =>
|
|
16
|
+
onDiagnostic({
|
|
17
|
+
code: 'audio-unavailable',
|
|
18
|
+
severity: 'warning',
|
|
19
|
+
message: String(error?.message ?? error),
|
|
20
|
+
});
|
|
21
|
+
const attempt = (action) => {
|
|
22
|
+
try {
|
|
23
|
+
Promise.resolve(action()).catch(report);
|
|
24
|
+
} catch (error) {
|
|
25
|
+
report(error);
|
|
26
|
+
}
|
|
27
|
+
};
|
|
28
|
+
const apply = () =>
|
|
29
|
+
bus?.configure({ ...state, volume: state.enabled ? state.volume : 0 });
|
|
30
|
+
const resume = () => {
|
|
31
|
+
if (audio?.state === 'suspended' && !document?.hidden) {
|
|
32
|
+
attempt(() => audio.resume());
|
|
33
|
+
}
|
|
34
|
+
};
|
|
35
|
+
const ensure = () => {
|
|
36
|
+
if (document?.hidden || failed) {
|
|
37
|
+
return null;
|
|
38
|
+
}
|
|
39
|
+
try {
|
|
40
|
+
if (!audio) {
|
|
41
|
+
audio = createContext();
|
|
42
|
+
bus = createSoundBus(audio, { ...theme.bus, room: state.room }, random);
|
|
43
|
+
// Start silent before routing the first source, then ramp to preference.
|
|
44
|
+
bus.master.gain.value = 0;
|
|
45
|
+
apply();
|
|
46
|
+
}
|
|
47
|
+
resume();
|
|
48
|
+
return { audio, bus };
|
|
49
|
+
} catch (error) {
|
|
50
|
+
bus?.disconnect();
|
|
51
|
+
const context = audio;
|
|
52
|
+
audio = bus = null;
|
|
53
|
+
failed = true;
|
|
54
|
+
attempt(() => context?.close?.());
|
|
55
|
+
report(error);
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
};
|
|
59
|
+
const visibility = () => {
|
|
60
|
+
if (document?.hidden && audio) {
|
|
61
|
+
attempt(() => audio.suspend());
|
|
62
|
+
}
|
|
63
|
+
};
|
|
64
|
+
document?.addEventListener('visibilitychange', visibility);
|
|
65
|
+
return {
|
|
66
|
+
ensure,
|
|
67
|
+
apply,
|
|
68
|
+
report,
|
|
69
|
+
retry() {
|
|
70
|
+
failed = false;
|
|
71
|
+
},
|
|
72
|
+
async dispose() {
|
|
73
|
+
document?.removeEventListener('visibilitychange', visibility);
|
|
74
|
+
bus?.disconnect();
|
|
75
|
+
try {
|
|
76
|
+
await audio?.close?.();
|
|
77
|
+
} catch (error) {
|
|
78
|
+
report(error);
|
|
79
|
+
}
|
|
80
|
+
},
|
|
81
|
+
};
|
|
82
|
+
}
|
package/src/bind.js
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { parseLinks } from '@link-foundation/ui-core';
|
|
2
|
+
|
|
3
|
+
export const DEFAULT_SOUND_MAPPING = `sound-map
|
|
4
|
+
press click
|
|
5
|
+
activate click
|
|
6
|
+
hover hover
|
|
7
|
+
toggle toggle
|
|
8
|
+
change toggle
|
|
9
|
+
select select
|
|
10
|
+
open open
|
|
11
|
+
close close
|
|
12
|
+
type type
|
|
13
|
+
scan scan
|
|
14
|
+
intro intro
|
|
15
|
+
notify notify
|
|
16
|
+
`;
|
|
17
|
+
|
|
18
|
+
/** Bind to the merged #33 DOM callback and interpreter subscription APIs. */
|
|
19
|
+
export function bindSound(
|
|
20
|
+
player,
|
|
21
|
+
{ mapping = DEFAULT_SOUND_MAPPING, machines = [] } = {}
|
|
22
|
+
) {
|
|
23
|
+
const entries = parseLinks(mapping);
|
|
24
|
+
if (entries.length !== 1 || entries[0][0] !== 'sound-map') {
|
|
25
|
+
throw new TypeError('Expected sound-map');
|
|
26
|
+
}
|
|
27
|
+
const table = new Map();
|
|
28
|
+
for (const row of entries[0].slice(1)) {
|
|
29
|
+
if (
|
|
30
|
+
!Array.isArray(row) ||
|
|
31
|
+
row.length !== 2 ||
|
|
32
|
+
row.some((v) => typeof v !== 'string')
|
|
33
|
+
) {
|
|
34
|
+
throw new TypeError('Expected event and cue');
|
|
35
|
+
}
|
|
36
|
+
table.set(...row);
|
|
37
|
+
}
|
|
38
|
+
let active = true;
|
|
39
|
+
// ui-dom calls onAction once per handler action. One interaction can contain
|
|
40
|
+
// several actions, so deduplicate by the actual DOM event and sound name.
|
|
41
|
+
const seen = new WeakMap();
|
|
42
|
+
const onAction = (detail, event) => {
|
|
43
|
+
if (!active) {
|
|
44
|
+
return;
|
|
45
|
+
}
|
|
46
|
+
const name = table.get(detail.event);
|
|
47
|
+
if (!name) {
|
|
48
|
+
return;
|
|
49
|
+
}
|
|
50
|
+
if (event && typeof event === 'object') {
|
|
51
|
+
const names = seen.get(event) ?? new Set();
|
|
52
|
+
if (names.has(name)) {
|
|
53
|
+
return;
|
|
54
|
+
}
|
|
55
|
+
names.add(name);
|
|
56
|
+
seen.set(event, names);
|
|
57
|
+
}
|
|
58
|
+
player.play(name);
|
|
59
|
+
};
|
|
60
|
+
const stops = machines.map((machine) =>
|
|
61
|
+
machine.subscribe((snapshot) => {
|
|
62
|
+
if (active && snapshot.event) {
|
|
63
|
+
const name = table.get(snapshot.event.type);
|
|
64
|
+
if (name) {
|
|
65
|
+
player.play(name);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
})
|
|
69
|
+
);
|
|
70
|
+
return {
|
|
71
|
+
onAction,
|
|
72
|
+
dispose() {
|
|
73
|
+
active = false;
|
|
74
|
+
stops.forEach((stop) => stop());
|
|
75
|
+
},
|
|
76
|
+
};
|
|
77
|
+
}
|
package/src/comfort.js
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { SOUND_GLOBAL_KEYS } from './settings.js';
|
|
2
|
+
import { readSchema, bindConfig } from '@link-foundation/ui-settings';
|
|
3
|
+
|
|
4
|
+
/** Register these comfort fields in the application's settings schema. */
|
|
5
|
+
export const SOUND_SETTINGS_LINO = `sound-settings: schema
|
|
6
|
+
version 1
|
|
7
|
+
sound.enabled:
|
|
8
|
+
type toggle
|
|
9
|
+
default false
|
|
10
|
+
(comfort)
|
|
11
|
+
sound.volume:
|
|
12
|
+
type range
|
|
13
|
+
default 0.5
|
|
14
|
+
min 0
|
|
15
|
+
max 1
|
|
16
|
+
step 0.01
|
|
17
|
+
(comfort)
|
|
18
|
+
`;
|
|
19
|
+
export const SOUND_COMFORT_KEYS = Object.freeze([
|
|
20
|
+
'sound.enabled',
|
|
21
|
+
'sound.volume',
|
|
22
|
+
...SOUND_GLOBAL_KEYS,
|
|
23
|
+
]);
|
|
24
|
+
export const soundSettingsSchema = () => readSchema(SOUND_SETTINGS_LINO).schema;
|
|
25
|
+
|
|
26
|
+
/** A ui-config settings element, using the existing #18 user layer. */
|
|
27
|
+
export function bindSoundConfig(
|
|
28
|
+
config,
|
|
29
|
+
{ target = 'settings', schema = soundSettingsSchema() } = {}
|
|
30
|
+
) {
|
|
31
|
+
return Object.assign(bindConfig(config, schema, { target, layer: 'user' }), {
|
|
32
|
+
schema,
|
|
33
|
+
});
|
|
34
|
+
}
|
package/src/document.js
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
const INTERACTIVE =
|
|
2
|
+
'a[href],button,input,select,textarea,summary,[role="button"],[role="checkbox"],[role="switch"],[role="tab"],[role="radio"],[aria-pressed],[data-sound]';
|
|
3
|
+
const TEXT_TYPES = new Set([
|
|
4
|
+
'text',
|
|
5
|
+
'search',
|
|
6
|
+
'email',
|
|
7
|
+
'url',
|
|
8
|
+
'tel',
|
|
9
|
+
'password',
|
|
10
|
+
'number',
|
|
11
|
+
]);
|
|
12
|
+
|
|
13
|
+
/** One delegated capture route for documents whose controls do not use ui-dom. */
|
|
14
|
+
export function bindSoundToDocument(
|
|
15
|
+
player,
|
|
16
|
+
{
|
|
17
|
+
root = globalThis.document,
|
|
18
|
+
cueEvent = 'sound-cue',
|
|
19
|
+
now = () => globalThis.performance.now(),
|
|
20
|
+
} = {}
|
|
21
|
+
) {
|
|
22
|
+
const doc = root.nodeType === 9 ? root : root.ownerDocument;
|
|
23
|
+
const window = doc.defaultView;
|
|
24
|
+
const last = new Map();
|
|
25
|
+
const stops = [];
|
|
26
|
+
const inside = (node) => node && (node === root || root.contains(node));
|
|
27
|
+
const closest = (node, selector) => {
|
|
28
|
+
const match = node?.closest?.(selector);
|
|
29
|
+
return inside(match) ? match : null;
|
|
30
|
+
};
|
|
31
|
+
const disabled = (node) =>
|
|
32
|
+
node?.matches?.(':disabled') ||
|
|
33
|
+
Boolean(node?.closest?.('[disabled],[aria-disabled="true"],[inert]'));
|
|
34
|
+
const cue = (name, event, gap = 0, channel = name) => {
|
|
35
|
+
const time = now();
|
|
36
|
+
if (!name || time - (last.get(channel) ?? -Infinity) < gap) {
|
|
37
|
+
return;
|
|
38
|
+
}
|
|
39
|
+
last.set(channel, time);
|
|
40
|
+
const x = Number.isFinite(event?.clientX)
|
|
41
|
+
? event.clientX / Math.max(1, window.innerWidth)
|
|
42
|
+
: undefined;
|
|
43
|
+
player.play(name, x === undefined ? {} : { x });
|
|
44
|
+
};
|
|
45
|
+
const target = (event) =>
|
|
46
|
+
event.target?.nodeType === 1 ? event.target : event.target?.parentElement;
|
|
47
|
+
const control = (event) => closest(target(event), INTERACTIVE);
|
|
48
|
+
const override = (node, fallback) =>
|
|
49
|
+
closest(node, '[data-sound]')?.getAttribute('data-sound') ?? fallback;
|
|
50
|
+
const handlers = {
|
|
51
|
+
pointerover(event) {
|
|
52
|
+
if (event.pointerType !== 'mouse') {
|
|
53
|
+
return;
|
|
54
|
+
}
|
|
55
|
+
const node = control(event);
|
|
56
|
+
if (!node || disabled(node) || node.contains(event.relatedTarget)) {
|
|
57
|
+
return;
|
|
58
|
+
}
|
|
59
|
+
cue(override(node, 'hover'), event, player.hoverGap ?? 80, 'hover');
|
|
60
|
+
},
|
|
61
|
+
click(event) {
|
|
62
|
+
const node = control(event);
|
|
63
|
+
if (!node || disabled(node)) {
|
|
64
|
+
return;
|
|
65
|
+
}
|
|
66
|
+
if (node.matches('summary')) {
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
const custom = closest(target(event), '[data-sound]');
|
|
70
|
+
if (custom) {
|
|
71
|
+
cue(custom.getAttribute('data-sound'), event);
|
|
72
|
+
return;
|
|
73
|
+
}
|
|
74
|
+
if (node.matches('input[type="range"],select,input[type="color"]')) {
|
|
75
|
+
return;
|
|
76
|
+
}
|
|
77
|
+
const name = node.matches(
|
|
78
|
+
'input[type="checkbox"],[aria-pressed],[role="checkbox"],[role="switch"]'
|
|
79
|
+
)
|
|
80
|
+
? 'toggle'
|
|
81
|
+
: node.matches('input[type="radio"],[role="tab"],[role="radio"]')
|
|
82
|
+
? 'select'
|
|
83
|
+
: node.matches('a[href],button,[role="button"]')
|
|
84
|
+
? 'activate'
|
|
85
|
+
: null;
|
|
86
|
+
cue(name, event);
|
|
87
|
+
},
|
|
88
|
+
toggle(event) {
|
|
89
|
+
const node = target(event);
|
|
90
|
+
if (node?.matches('details') && inside(node) && !disabled(node)) {
|
|
91
|
+
const summary = [...node.children].find((child) =>
|
|
92
|
+
child.matches('summary')
|
|
93
|
+
);
|
|
94
|
+
cue(override(summary ?? node, node.open ? 'open' : 'close'), event);
|
|
95
|
+
}
|
|
96
|
+
},
|
|
97
|
+
input(event) {
|
|
98
|
+
const node = target(event);
|
|
99
|
+
if (!inside(node) || disabled(node)) {
|
|
100
|
+
return;
|
|
101
|
+
}
|
|
102
|
+
if (node.matches('input[type="range"]')) {
|
|
103
|
+
cue(override(node, 'select'), event, 70, 'range');
|
|
104
|
+
} else if (
|
|
105
|
+
node.matches('textarea') ||
|
|
106
|
+
(node.matches('input') && TEXT_TYPES.has(node.type)) ||
|
|
107
|
+
node.isContentEditable
|
|
108
|
+
) {
|
|
109
|
+
cue(override(node, 'type'), event, 30, 'type');
|
|
110
|
+
}
|
|
111
|
+
},
|
|
112
|
+
change(event) {
|
|
113
|
+
const node = target(event);
|
|
114
|
+
if (
|
|
115
|
+
inside(node) &&
|
|
116
|
+
!disabled(node) &&
|
|
117
|
+
node.matches('select,input[type="color"]')
|
|
118
|
+
) {
|
|
119
|
+
cue(override(node, 'select'), event);
|
|
120
|
+
}
|
|
121
|
+
},
|
|
122
|
+
pointermove(event) {
|
|
123
|
+
const node = closest(target(event), '[data-sound-scan]');
|
|
124
|
+
if (node && !disabled(target(event))) {
|
|
125
|
+
cue(override(node, 'scan'), event, 90, 'scan');
|
|
126
|
+
}
|
|
127
|
+
},
|
|
128
|
+
};
|
|
129
|
+
for (const [type, handler] of Object.entries(handlers)) {
|
|
130
|
+
root.addEventListener(type, handler, true);
|
|
131
|
+
stops.push(() => root.removeEventListener(type, handler, true));
|
|
132
|
+
}
|
|
133
|
+
const custom = (event) => {
|
|
134
|
+
const detail = event.detail;
|
|
135
|
+
const name = typeof detail === 'string' ? detail : detail?.event;
|
|
136
|
+
if (typeof name === 'string' && name) {
|
|
137
|
+
player.play(name, typeof detail === 'object' ? detail : {});
|
|
138
|
+
}
|
|
139
|
+
};
|
|
140
|
+
if (cueEvent) {
|
|
141
|
+
window.addEventListener(cueEvent, custom, true);
|
|
142
|
+
stops.push(() => window.removeEventListener(cueEvent, custom, true));
|
|
143
|
+
}
|
|
144
|
+
return {
|
|
145
|
+
dispose() {
|
|
146
|
+
stops.forEach((stop) => stop());
|
|
147
|
+
},
|
|
148
|
+
};
|
|
149
|
+
}
|