@hypersoniclabs/helix-sdk 0.1.1 → 0.1.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +954 -2
- package/dist/action-surface.d.ts +182 -0
- package/dist/action-surface.js +1032 -0
- package/dist/action-surface.js.map +1 -0
- package/dist/camera.d.ts +78 -0
- package/dist/camera.js +640 -0
- package/dist/camera.js.map +1 -0
- package/dist/dev-shell/criteria.d.ts +46 -0
- package/dist/dev-shell/criteria.js +98 -0
- package/dist/dev-shell/criteria.js.map +1 -0
- package/dist/dev-shell/index.d.ts +189 -0
- package/dist/dev-shell/index.js +287 -0
- package/dist/dev-shell/index.js.map +1 -0
- package/dist/dev-shell/keys.d.ts +14 -0
- package/dist/dev-shell/keys.js +78 -0
- package/dist/dev-shell/keys.js.map +1 -0
- package/dist/dev-shell/simulator.d.ts +436 -0
- package/dist/dev-shell/simulator.js +1634 -0
- package/dist/dev-shell/simulator.js.map +1 -0
- package/dist/dev-shell/state.d.ts +148 -0
- package/dist/dev-shell/state.js +196 -0
- package/dist/dev-shell/state.js.map +1 -0
- package/dist/device-definition-resolver.d.ts +34 -0
- package/dist/device-definition-resolver.js +172 -0
- package/dist/device-definition-resolver.js.map +1 -0
- package/dist/device-trial.d.ts +3 -0
- package/dist/device-trial.js +132 -0
- package/dist/device-trial.js.map +1 -0
- package/dist/devices.d.ts +228 -0
- package/dist/devices.js +198 -0
- package/dist/devices.js.map +1 -0
- package/dist/dreamerAudio.d.ts +126 -0
- package/dist/dreamerAudio.js +135 -0
- package/dist/dreamerAudio.js.map +1 -0
- package/dist/generated/runtime-contract.d.ts +15529 -0
- package/dist/generated/runtime-contract.js +20470 -0
- package/dist/generated/runtime-contract.js.map +1 -0
- package/dist/index.d.ts +364 -3
- package/dist/index.js +1954 -13
- package/dist/index.js.map +1 -1
- package/dist/interaction-mode.d.ts +172 -0
- package/dist/interaction-mode.js +553 -0
- package/dist/interaction-mode.js.map +1 -0
- package/dist/internal/avatar-pose.d.ts +25 -0
- package/dist/internal/avatar-pose.js +46 -0
- package/dist/internal/avatar-pose.js.map +1 -0
- package/dist/internal/keyed-collection.d.ts +2 -0
- package/dist/internal/keyed-collection.js +12 -0
- package/dist/internal/keyed-collection.js.map +1 -0
- package/dist/internal/vehicle-detach-action.d.ts +2 -0
- package/dist/internal/vehicle-detach-action.js +6 -0
- package/dist/internal/vehicle-detach-action.js.map +1 -0
- package/dist/matchmaking.d.ts +433 -0
- package/dist/matchmaking.js +1487 -0
- package/dist/matchmaking.js.map +1 -0
- package/dist/materials.d.ts +122 -0
- package/dist/materials.js +217 -0
- package/dist/materials.js.map +1 -0
- package/dist/multiplayer-accessors.d.ts +100 -0
- package/dist/multiplayer-accessors.js +200 -0
- package/dist/multiplayer-accessors.js.map +1 -0
- package/dist/multiplayer-contract/avatar-pose.d.ts +112 -0
- package/dist/multiplayer-contract/avatar-pose.js +250 -0
- package/dist/multiplayer-contract/avatar-pose.js.map +1 -0
- package/dist/multiplayer-contract/credential.d.ts +80 -0
- package/dist/multiplayer-contract/credential.js +5 -0
- package/dist/multiplayer-contract/credential.js.map +1 -0
- package/dist/multiplayer-contract/final-rest.d.ts +66 -0
- package/dist/multiplayer-contract/final-rest.js +38 -0
- package/dist/multiplayer-contract/final-rest.js.map +1 -0
- package/dist/multiplayer-contract/index.d.ts +20 -0
- package/dist/multiplayer-contract/index.js +41 -0
- package/dist/multiplayer-contract/index.js.map +1 -0
- package/dist/multiplayer-contract/messages.d.ts +731 -0
- package/dist/multiplayer-contract/messages.js +237 -0
- package/dist/multiplayer-contract/messages.js.map +1 -0
- package/dist/multiplayer-contract/room.d.ts +177 -0
- package/dist/multiplayer-contract/room.js +17 -0
- package/dist/multiplayer-contract/room.js.map +1 -0
- package/dist/multiplayer-contract/state.d.ts +241 -0
- package/dist/multiplayer-contract/state.js +15 -0
- package/dist/multiplayer-contract/state.js.map +1 -0
- package/dist/multiplayer-final-rest.d.ts +32 -0
- package/dist/multiplayer-final-rest.js +217 -0
- package/dist/multiplayer-final-rest.js.map +1 -0
- package/dist/multiplayer.d.ts +624 -0
- package/dist/multiplayer.js +2503 -0
- package/dist/multiplayer.js.map +1 -0
- package/dist/package.json +3 -0
- package/dist/protocol.d.ts +859 -1
- package/dist/protocol.js +117 -5
- package/dist/protocol.js.map +1 -1
- package/dist/runtime-contract/index.d.ts +15 -0
- package/dist/runtime-contract/index.js +12 -0
- package/dist/runtime-contract/index.js.map +1 -0
- package/dist/server-clock.d.ts +25 -0
- package/dist/server-clock.js +88 -0
- package/dist/server-clock.js.map +1 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -1
- package/dist/universal-vehicles.d.ts +111 -0
- package/dist/universal-vehicles.js +2 -0
- package/dist/universal-vehicles.js.map +1 -0
- package/dist/vault.d.ts +562 -0
- package/dist/vault.js +365 -0
- package/dist/vault.js.map +1 -0
- package/dist/vehicle-specialty-placement.d.ts +28 -0
- package/dist/vehicle-specialty-placement.js +154 -0
- package/dist/vehicle-specialty-placement.js.map +1 -0
- package/dist/vehicle-specialty-transport.d.ts +78 -0
- package/dist/vehicle-specialty-transport.js +183 -0
- package/dist/vehicle-specialty-transport.js.map +1 -0
- package/dist/voice.d.ts +229 -0
- package/dist/voice.js +1348 -0
- package/dist/voice.js.map +1 -0
- package/generated/runtime-contract/helix-runtime-contract.json +13332 -0
- package/generated/runtime-contract/known-answer.json +20471 -0
- package/generated/runtime-contract/known-answer.schema.json +630 -0
- package/generated/runtime-contract/runtime-contract.schema.json +607 -0
- package/generated/runtime-contract/unreal/HelixRuntimeContract.generated.h +908 -0
- package/package.json +44 -5
|
@@ -0,0 +1,1032 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* How far a mouse must travel before it takes the selection back from the
|
|
3
|
+
* keyboard. Small enough to feel immediate when you reach for the mouse, large
|
|
4
|
+
* enough to ignore the wobble a resting hand puts through it.
|
|
5
|
+
*/
|
|
6
|
+
const POINTER_WAKE_PX = 6;
|
|
7
|
+
/** Ignore analog noise below the deliberate navigation threshold. */
|
|
8
|
+
const NAV_PRESS = 0.5;
|
|
9
|
+
const ACTION_KINDS = new Set([
|
|
10
|
+
'run',
|
|
11
|
+
'choice',
|
|
12
|
+
'number',
|
|
13
|
+
'text',
|
|
14
|
+
'point',
|
|
15
|
+
'asset',
|
|
16
|
+
'takeover',
|
|
17
|
+
]);
|
|
18
|
+
/** Fail-fast validation for the trusted host-to-presentation boundary. */
|
|
19
|
+
export function validateActionSurfaceSnapshot(snapshot) {
|
|
20
|
+
const errors = [];
|
|
21
|
+
if (!snapshot.instanceId.trim())
|
|
22
|
+
errors.push('instanceId is required');
|
|
23
|
+
if (!snapshot.title.trim())
|
|
24
|
+
errors.push('title is required');
|
|
25
|
+
const ids = new Set();
|
|
26
|
+
for (const [index, action] of snapshot.actions.entries()) {
|
|
27
|
+
const at = `actions[${index}]`;
|
|
28
|
+
if (!action.id.trim())
|
|
29
|
+
errors.push(`${at}.id is required`);
|
|
30
|
+
else if (ids.has(action.id))
|
|
31
|
+
errors.push(`${at}.id duplicates '${action.id}'`);
|
|
32
|
+
else
|
|
33
|
+
ids.add(action.id);
|
|
34
|
+
if (!action.label.trim())
|
|
35
|
+
errors.push(`${at}.label is required`);
|
|
36
|
+
if (!ACTION_KINDS.has(action.kind))
|
|
37
|
+
errors.push(`${at}.kind '${String(action.kind)}' is unsupported`);
|
|
38
|
+
if (action.enabled === false && !readableReason(action)) {
|
|
39
|
+
errors.push(`${at} is disabled without a player-readable reason`);
|
|
40
|
+
}
|
|
41
|
+
if (action.kind === 'number') {
|
|
42
|
+
const min = action.min ?? 0;
|
|
43
|
+
const max = action.max ?? 1;
|
|
44
|
+
const step = action.step ?? 0.01;
|
|
45
|
+
if (![min, max, step].every((value) => Number.isFinite(value))) {
|
|
46
|
+
errors.push(`${at} has non-finite number bounds`);
|
|
47
|
+
}
|
|
48
|
+
else {
|
|
49
|
+
if (max <= min)
|
|
50
|
+
errors.push(`${at}.max must be greater than min`);
|
|
51
|
+
if (step <= 0)
|
|
52
|
+
errors.push(`${at}.step must be positive`);
|
|
53
|
+
}
|
|
54
|
+
if (action.value !== undefined && action.value !== null && typeof action.value !== 'number') {
|
|
55
|
+
errors.push(`${at}.value must be a number`);
|
|
56
|
+
}
|
|
57
|
+
else if (typeof action.value === 'number' && !Number.isFinite(action.value)) {
|
|
58
|
+
errors.push(`${at}.value must be finite`);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
if (action.kind === 'text') {
|
|
62
|
+
if (action.value !== undefined && action.value !== null && typeof action.value !== 'string') {
|
|
63
|
+
errors.push(`${at}.value must be a string`);
|
|
64
|
+
}
|
|
65
|
+
if (action.maxLength !== undefined && (!Number.isInteger(action.maxLength) || action.maxLength < 1 || action.maxLength > 4096)) {
|
|
66
|
+
errors.push(`${at}.maxLength must be an integer between 1 and 4096`);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
if (action.kind === 'choice' || action.kind === 'asset') {
|
|
70
|
+
const optionValues = new Set();
|
|
71
|
+
for (const [optionIndex, option] of (action.options ?? []).entries()) {
|
|
72
|
+
const optionAt = `${at}.options[${optionIndex}]`;
|
|
73
|
+
if (!option.value)
|
|
74
|
+
errors.push(`${optionAt}.value is required`);
|
|
75
|
+
else if (optionValues.has(option.value))
|
|
76
|
+
errors.push(`${optionAt}.value duplicates '${option.value}'`);
|
|
77
|
+
else
|
|
78
|
+
optionValues.add(option.value);
|
|
79
|
+
if (!option.label.trim())
|
|
80
|
+
errors.push(`${optionAt}.label is required`);
|
|
81
|
+
if (option.disabled === true && !(option.reason?.trim())) {
|
|
82
|
+
errors.push(`${optionAt} is disabled without a player-readable reason`);
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
return errors;
|
|
88
|
+
}
|
|
89
|
+
/**
|
|
90
|
+
* Portable DOM component for a proximity/list presentation.
|
|
91
|
+
*
|
|
92
|
+
* It installs no keyboard, pointer-lock, gamepad, or raw touch listeners. A
|
|
93
|
+
* trusted mode host delivers the three semantic actions through `handleVerb`,
|
|
94
|
+
* while ordinary DOM activation keeps the rendered controls accessible.
|
|
95
|
+
*/
|
|
96
|
+
export class UniversalActionSurface {
|
|
97
|
+
element;
|
|
98
|
+
#document;
|
|
99
|
+
#hints;
|
|
100
|
+
#onInvoke;
|
|
101
|
+
#onDismiss;
|
|
102
|
+
#onOpenChange;
|
|
103
|
+
#title;
|
|
104
|
+
#status;
|
|
105
|
+
#list;
|
|
106
|
+
#hint;
|
|
107
|
+
#unsubscribeHints;
|
|
108
|
+
#snapshot = null;
|
|
109
|
+
#actions = [];
|
|
110
|
+
#cursor = 0;
|
|
111
|
+
#mode = { type: 'browse' };
|
|
112
|
+
/** Last position any pointer event reported, moved or not. */
|
|
113
|
+
#lastPointer = { x: Number.NaN, y: Number.NaN };
|
|
114
|
+
/**
|
|
115
|
+
* Where the pointer was when the keyboard or gamepad last took the selection.
|
|
116
|
+
* Hover only takes over again once the pointer travels further than
|
|
117
|
+
* POINTER_WAKE_PX from here — see `#onListPointerMove`.
|
|
118
|
+
*/
|
|
119
|
+
#pointerBaseline = { x: Number.NaN, y: Number.NaN };
|
|
120
|
+
#pointerActive = false;
|
|
121
|
+
/**
|
|
122
|
+
* Whether the player is currently touching THIS surface.
|
|
123
|
+
*
|
|
124
|
+
* The hint source reports the device the game input router last saw, which
|
|
125
|
+
* stays `keyboard` for someone who only ever taps the menu — so the touch
|
|
126
|
+
* affordances (the close control, the key caps that mean nothing without a
|
|
127
|
+
* keyboard) never appeared for the people who need them. A touch pointer
|
|
128
|
+
* landing on the surface is first-hand evidence, and a mouse or a key takes
|
|
129
|
+
* it back.
|
|
130
|
+
*/
|
|
131
|
+
#touchObserved = false;
|
|
132
|
+
/** null when released; 0 when an active axis has not crossed the presentation deadzone. */
|
|
133
|
+
#navHeld = null;
|
|
134
|
+
#dismissedFor = null;
|
|
135
|
+
#disposed = false;
|
|
136
|
+
constructor(options) {
|
|
137
|
+
this.#document = options.document ?? options.host.ownerDocument;
|
|
138
|
+
this.#hints = options.hints;
|
|
139
|
+
this.#onInvoke = options.onInvoke;
|
|
140
|
+
this.#onDismiss = options.onDismiss;
|
|
141
|
+
this.#onOpenChange = options.onOpenChange;
|
|
142
|
+
ensureActionSurfaceStyles(this.#document);
|
|
143
|
+
this.element = make(this.#document, 'section', 'helix-action-surface');
|
|
144
|
+
this.element.dataset.testid = 'action-surface';
|
|
145
|
+
this.element.setAttribute('aria-live', 'polite');
|
|
146
|
+
this.element.hidden = true;
|
|
147
|
+
const header = make(this.#document, 'header', 'helix-action-surface__header');
|
|
148
|
+
this.#title = make(this.#document, 'h2', 'helix-action-surface__title');
|
|
149
|
+
this.#status = make(this.#document, 'span', 'helix-action-surface__status');
|
|
150
|
+
// Close stays visible for every pointer device. It is also the only way a
|
|
151
|
+
// tap-only player can leave a sustained control without a cancel key.
|
|
152
|
+
const close = make(this.#document, 'button', 'helix-action-surface__close');
|
|
153
|
+
close.type = 'button';
|
|
154
|
+
close.dataset.testid = 'action-surface-close';
|
|
155
|
+
close.setAttribute('aria-label', 'Close');
|
|
156
|
+
close.textContent = '✕';
|
|
157
|
+
close.addEventListener('click', () => this.cancel());
|
|
158
|
+
header.append(this.#title, this.#status, close);
|
|
159
|
+
this.#list = make(this.#document, 'div', 'helix-action-surface__list');
|
|
160
|
+
this.#list.addEventListener('pointermove', (event) => this.#onListPointerMove(event));
|
|
161
|
+
this.element.addEventListener('pointerdown', (event) => this.observePointer(event.pointerType));
|
|
162
|
+
this.#hint = make(this.#document, 'footer', 'helix-action-surface__hint');
|
|
163
|
+
this.element.append(header, this.#list, this.#hint);
|
|
164
|
+
options.host.append(this.element);
|
|
165
|
+
this.#unsubscribeHints = this.#hints.subscribe?.(() => this.#renderHints()) ?? (() => undefined);
|
|
166
|
+
}
|
|
167
|
+
get isOpen() { return this.#snapshot !== null; }
|
|
168
|
+
get instanceId() { return this.#snapshot?.instanceId ?? null; }
|
|
169
|
+
get mode() { return this.#mode.type; }
|
|
170
|
+
get selectedAction() { return this.#actions[this.#cursor] ?? null; }
|
|
171
|
+
get visibleActions() { return this.#actions; }
|
|
172
|
+
get liveNumber() { return this.#mode.type === 'number' ? this.#mode.value : null; }
|
|
173
|
+
get liveText() { return this.#mode.type === 'text' ? this.#mode.value : null; }
|
|
174
|
+
/** Open or refresh the caller-scoped cache. Pass null to withdraw it. */
|
|
175
|
+
setSnapshot(snapshot) {
|
|
176
|
+
this.#assertLive();
|
|
177
|
+
if (snapshot === null) {
|
|
178
|
+
this.hide();
|
|
179
|
+
return;
|
|
180
|
+
}
|
|
181
|
+
if (this.#dismissedFor === snapshot.instanceId)
|
|
182
|
+
return;
|
|
183
|
+
const errors = validateActionSurfaceSnapshot(snapshot);
|
|
184
|
+
if (errors.length)
|
|
185
|
+
throw new Error(`invalid action-surface snapshot: ${errors.join('; ')}`);
|
|
186
|
+
const wasOpen = this.isOpen;
|
|
187
|
+
const sameInstance = this.#snapshot?.instanceId === snapshot.instanceId;
|
|
188
|
+
const selectedId = sameInstance ? this.selectedAction?.id : undefined;
|
|
189
|
+
const visible = snapshot.actions.filter((action) => action.visible !== false);
|
|
190
|
+
this.#snapshot = snapshot;
|
|
191
|
+
this.#actions = visible;
|
|
192
|
+
if (!sameInstance) {
|
|
193
|
+
this.#mode = { type: 'browse' };
|
|
194
|
+
this.#cursor = firstEnabled(visible, snapshot.availability);
|
|
195
|
+
this.#navHeld = null;
|
|
196
|
+
// A freshly opened surface belongs to the keys until the pointer moves.
|
|
197
|
+
this.#parkPointer();
|
|
198
|
+
}
|
|
199
|
+
else {
|
|
200
|
+
const selectedIndex = selectedId ? visible.findIndex((action) => action.id === selectedId) : -1;
|
|
201
|
+
this.#cursor = selectedIndex >= 0 ? selectedIndex : Math.min(this.#cursor, Math.max(0, visible.length - 1));
|
|
202
|
+
this.#refreshSustainedAction();
|
|
203
|
+
}
|
|
204
|
+
if (visible.length === 0) {
|
|
205
|
+
this.hide();
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
this.element.hidden = false;
|
|
209
|
+
this.#title.textContent = snapshot.title;
|
|
210
|
+
this.#renderStatus();
|
|
211
|
+
// Never replace a native range beneath an active drag merely because the
|
|
212
|
+
// authority refreshed its cache. Its live echo is updated in place.
|
|
213
|
+
if (this.#mode.type === 'number' && sameInstance)
|
|
214
|
+
this.#refreshNumberDom();
|
|
215
|
+
else if (this.#mode.type === 'text' && sameInstance)
|
|
216
|
+
this.#refreshTextDom();
|
|
217
|
+
else
|
|
218
|
+
this.#render();
|
|
219
|
+
if (!wasOpen)
|
|
220
|
+
this.#onOpenChange?.(true);
|
|
221
|
+
}
|
|
222
|
+
hide() {
|
|
223
|
+
if (!this.isOpen)
|
|
224
|
+
return;
|
|
225
|
+
this.#snapshot = null;
|
|
226
|
+
this.#actions = [];
|
|
227
|
+
this.#cursor = 0;
|
|
228
|
+
this.#mode = { type: 'browse' };
|
|
229
|
+
this.#navHeld = null;
|
|
230
|
+
this.element.hidden = true;
|
|
231
|
+
this.#list.replaceChildren();
|
|
232
|
+
this.#hint.replaceChildren();
|
|
233
|
+
this.#onOpenChange?.(false);
|
|
234
|
+
}
|
|
235
|
+
/** Dismiss this proximity offer until the host explicitly rearms it. */
|
|
236
|
+
dismiss() {
|
|
237
|
+
const id = this.#snapshot?.instanceId;
|
|
238
|
+
if (!id)
|
|
239
|
+
return;
|
|
240
|
+
this.#dismissedFor = id;
|
|
241
|
+
this.hide();
|
|
242
|
+
this.#onDismiss?.(id);
|
|
243
|
+
}
|
|
244
|
+
rearm() { this.#dismissedFor = null; }
|
|
245
|
+
/** Refresh active-device/rebind text when the router has no subscription API. */
|
|
246
|
+
refreshHints() {
|
|
247
|
+
this.#assertLive();
|
|
248
|
+
this.#renderHints();
|
|
249
|
+
}
|
|
250
|
+
/**
|
|
251
|
+
* Record pointer input that reaches the host's opener before this surface.
|
|
252
|
+
* This keeps the first rendered hints aligned with the input that opened it.
|
|
253
|
+
*/
|
|
254
|
+
observePointer(pointerType) {
|
|
255
|
+
this.#assertLive();
|
|
256
|
+
const touch = pointerType === 'touch';
|
|
257
|
+
if (touch === this.#touchObserved)
|
|
258
|
+
return;
|
|
259
|
+
this.#touchObserved = touch;
|
|
260
|
+
this.#renderHints();
|
|
261
|
+
}
|
|
262
|
+
/** Navigate one row/option or nudge a sustained number. */
|
|
263
|
+
move(delta) {
|
|
264
|
+
if (!this.#snapshot || this.#actions.length === 0)
|
|
265
|
+
return;
|
|
266
|
+
// Every caller of `move` is a key, stick or d-pad. Whatever it chooses must
|
|
267
|
+
// survive a resting mouse.
|
|
268
|
+
this.#parkPointer();
|
|
269
|
+
if (this.#touchObserved) {
|
|
270
|
+
this.#touchObserved = false;
|
|
271
|
+
this.#renderHints();
|
|
272
|
+
}
|
|
273
|
+
if (this.#mode.type === 'number') {
|
|
274
|
+
this.#setNumber(this.#mode.value + delta * (this.#mode.action.step ?? 0.01));
|
|
275
|
+
return;
|
|
276
|
+
}
|
|
277
|
+
if (this.#mode.type === 'picker') {
|
|
278
|
+
this.#movePicker(delta);
|
|
279
|
+
return;
|
|
280
|
+
}
|
|
281
|
+
const count = this.#actions.length;
|
|
282
|
+
let index = this.#cursor;
|
|
283
|
+
for (let step = 0; step < count; step++) {
|
|
284
|
+
index = (index + delta + count) % count;
|
|
285
|
+
if (isActionEnabled(this.#actions[index], this.#snapshot.availability))
|
|
286
|
+
break;
|
|
287
|
+
}
|
|
288
|
+
this.#cursor = index;
|
|
289
|
+
this.#refreshBrowseSelection();
|
|
290
|
+
}
|
|
291
|
+
confirm() {
|
|
292
|
+
const action = this.#mode.type === 'browse' ? this.selectedAction : this.#mode.action;
|
|
293
|
+
if (!action || !this.#snapshot)
|
|
294
|
+
return;
|
|
295
|
+
if (this.#mode.type === 'number') {
|
|
296
|
+
this.#endSustained();
|
|
297
|
+
return;
|
|
298
|
+
}
|
|
299
|
+
if (this.#mode.type === 'text') {
|
|
300
|
+
this.#onInvoke({ action, kind: 'text', value: this.#mode.value });
|
|
301
|
+
this.#endSustained();
|
|
302
|
+
return;
|
|
303
|
+
}
|
|
304
|
+
if (this.#mode.type === 'picker') {
|
|
305
|
+
const option = action.options?.[this.#mode.index];
|
|
306
|
+
if (option && option.disabled !== true) {
|
|
307
|
+
this.#onInvoke({ action, kind: action.kind, value: option.value });
|
|
308
|
+
this.#endSustained();
|
|
309
|
+
}
|
|
310
|
+
return;
|
|
311
|
+
}
|
|
312
|
+
if (!isActionEnabled(action, this.#snapshot.availability))
|
|
313
|
+
return;
|
|
314
|
+
if (action.kind === 'number') {
|
|
315
|
+
this.#beginNumber(action);
|
|
316
|
+
return;
|
|
317
|
+
}
|
|
318
|
+
if (action.kind === 'text') {
|
|
319
|
+
this.#beginText(action);
|
|
320
|
+
return;
|
|
321
|
+
}
|
|
322
|
+
if (action.kind === 'choice' || action.kind === 'asset') {
|
|
323
|
+
this.#beginPicker(action);
|
|
324
|
+
return;
|
|
325
|
+
}
|
|
326
|
+
this.#onInvoke({ action, kind: action.kind });
|
|
327
|
+
}
|
|
328
|
+
/** Back out of a sustained control; dismiss the proximity list at root. */
|
|
329
|
+
cancel() {
|
|
330
|
+
if (this.#mode.type !== 'browse')
|
|
331
|
+
this.#endSustained();
|
|
332
|
+
else
|
|
333
|
+
this.dismiss();
|
|
334
|
+
}
|
|
335
|
+
/** Release modal focus without dismissing the still-valid proximity offer. */
|
|
336
|
+
endEngagement() {
|
|
337
|
+
this.#navHeld = null;
|
|
338
|
+
if (this.#mode.type === 'browse')
|
|
339
|
+
return;
|
|
340
|
+
this.#endSustained();
|
|
341
|
+
}
|
|
342
|
+
/** Semantic input entry point used by `createActionSurfaceMode`. */
|
|
343
|
+
handleVerb(verb, event) {
|
|
344
|
+
if (verb === 'navigate' && event.phase === 'end') {
|
|
345
|
+
this.#navHeld = null;
|
|
346
|
+
return;
|
|
347
|
+
}
|
|
348
|
+
if (event.phase === 'end')
|
|
349
|
+
return;
|
|
350
|
+
if (verb === 'activate') {
|
|
351
|
+
if (event.phase === 'start')
|
|
352
|
+
this.confirm();
|
|
353
|
+
return;
|
|
354
|
+
}
|
|
355
|
+
if (verb === 'back') {
|
|
356
|
+
if (event.phase === 'start')
|
|
357
|
+
this.cancel();
|
|
358
|
+
return;
|
|
359
|
+
}
|
|
360
|
+
const vector = event.vector;
|
|
361
|
+
if (!vector)
|
|
362
|
+
return;
|
|
363
|
+
if (this.#mode.type === 'text')
|
|
364
|
+
return;
|
|
365
|
+
const axis = this.#mode.type === 'number'
|
|
366
|
+
? Math.abs(vector.x) >= Math.abs(vector.y)
|
|
367
|
+
? vector.x
|
|
368
|
+
: vector.y
|
|
369
|
+
: Math.abs(vector.y) >= Math.abs(vector.x)
|
|
370
|
+
? vector.y
|
|
371
|
+
: -vector.x;
|
|
372
|
+
// A number control reads the raw axis; a list inverts it, because "down"
|
|
373
|
+
// on a stick means the NEXT row.
|
|
374
|
+
const delta = this.#mode.type === 'number'
|
|
375
|
+
? axis > 0
|
|
376
|
+
? 1
|
|
377
|
+
: -1
|
|
378
|
+
: axis > 0
|
|
379
|
+
? -1
|
|
380
|
+
: 1;
|
|
381
|
+
const direction = axis === 0 ? 0 : delta;
|
|
382
|
+
if (event.phase === 'start') {
|
|
383
|
+
// A start is a fresh semantic edge even when it follows the same direction as the prior gesture.
|
|
384
|
+
// Latch sub-threshold analog starts too, so a later valid repeat can cross the presentation deadzone.
|
|
385
|
+
this.#navHeld = Math.abs(axis) >= NAV_PRESS ? direction : 0;
|
|
386
|
+
if (Math.abs(axis) >= NAV_PRESS)
|
|
387
|
+
this.move(delta);
|
|
388
|
+
return;
|
|
389
|
+
}
|
|
390
|
+
// The trusted mode host owns repeat timing and dominant-axis change detection. Consume each repeat
|
|
391
|
+
// exactly once while this engagement is held; a delayed repeat after end/open-close is stale.
|
|
392
|
+
if (this.#navHeld === null || Math.abs(axis) < NAV_PRESS)
|
|
393
|
+
return;
|
|
394
|
+
this.#navHeld = direction;
|
|
395
|
+
this.move(delta);
|
|
396
|
+
}
|
|
397
|
+
dispose() {
|
|
398
|
+
if (this.#disposed)
|
|
399
|
+
return;
|
|
400
|
+
this.#disposed = true;
|
|
401
|
+
this.#unsubscribeHints();
|
|
402
|
+
this.element.remove();
|
|
403
|
+
this.#snapshot = null;
|
|
404
|
+
this.#actions = [];
|
|
405
|
+
this.#navHeld = null;
|
|
406
|
+
}
|
|
407
|
+
#beginNumber(action) {
|
|
408
|
+
const min = action.min ?? 0;
|
|
409
|
+
const max = action.max ?? 1;
|
|
410
|
+
const initial = typeof action.value === 'number' ? action.value : min;
|
|
411
|
+
this.#mode = { type: 'number', action, value: clamp(initial, min, max) };
|
|
412
|
+
this.#render();
|
|
413
|
+
}
|
|
414
|
+
#beginText(action) {
|
|
415
|
+
const initial = typeof action.value === 'string' ? action.value : '';
|
|
416
|
+
this.#mode = { type: 'text', action, value: initial.slice(0, action.maxLength ?? 4096) };
|
|
417
|
+
this.#render();
|
|
418
|
+
}
|
|
419
|
+
#beginPicker(action) {
|
|
420
|
+
const options = action.options ?? [];
|
|
421
|
+
if (options.length === 0)
|
|
422
|
+
return;
|
|
423
|
+
const current = action.value === undefined || action.value === null
|
|
424
|
+
? -1
|
|
425
|
+
: options.findIndex((option) => option.value === String(action.value));
|
|
426
|
+
const first = firstEnabledOption(options, current >= 0 ? current : 0);
|
|
427
|
+
this.#mode = { type: 'picker', action, index: first };
|
|
428
|
+
this.#render();
|
|
429
|
+
}
|
|
430
|
+
#movePicker(delta) {
|
|
431
|
+
if (this.#mode.type !== 'picker')
|
|
432
|
+
return;
|
|
433
|
+
const options = this.#mode.action.options ?? [];
|
|
434
|
+
if (options.length === 0)
|
|
435
|
+
return;
|
|
436
|
+
let index = this.#mode.index;
|
|
437
|
+
for (let step = 0; step < options.length; step++) {
|
|
438
|
+
index = (index + delta + options.length) % options.length;
|
|
439
|
+
if (options[index].disabled !== true)
|
|
440
|
+
break;
|
|
441
|
+
}
|
|
442
|
+
this.#mode.index = index;
|
|
443
|
+
this.#render();
|
|
444
|
+
}
|
|
445
|
+
#setNumber(raw) {
|
|
446
|
+
if (this.#mode.type !== 'number' || !Number.isFinite(raw))
|
|
447
|
+
return;
|
|
448
|
+
const action = this.#mode.action;
|
|
449
|
+
const min = action.min ?? 0;
|
|
450
|
+
const max = action.max ?? 1;
|
|
451
|
+
const step = action.step ?? 0.01;
|
|
452
|
+
const rounded = roundToStep(clamp(raw, min, max), min, step);
|
|
453
|
+
if (!Number.isFinite(rounded))
|
|
454
|
+
return;
|
|
455
|
+
const value = clamp(rounded, min, max);
|
|
456
|
+
if (value === this.#mode.value)
|
|
457
|
+
return;
|
|
458
|
+
this.#mode.value = value;
|
|
459
|
+
this.#refreshNumberDom();
|
|
460
|
+
// Live authority update, matching the prototype walkthrough. Confirm and
|
|
461
|
+
// cancel end the sustained UI; neither invents a client-side transaction.
|
|
462
|
+
this.#onInvoke({ action, kind: 'number', value });
|
|
463
|
+
}
|
|
464
|
+
#endSustained() {
|
|
465
|
+
this.#parkPointer();
|
|
466
|
+
const active = this.#document.activeElement;
|
|
467
|
+
if (active instanceof this.#document.defaultView.HTMLElement && this.#list.contains(active))
|
|
468
|
+
active.blur();
|
|
469
|
+
this.#mode = { type: 'browse' };
|
|
470
|
+
this.#render();
|
|
471
|
+
}
|
|
472
|
+
#refreshSustainedAction() {
|
|
473
|
+
const mode = this.#mode;
|
|
474
|
+
if (mode.type === 'browse' || !this.#snapshot)
|
|
475
|
+
return;
|
|
476
|
+
const focusedValue = mode.type === 'picker' ? mode.action.options?.[mode.index]?.value : undefined;
|
|
477
|
+
const action = this.#actions.find((candidate) => candidate.id === mode.action.id);
|
|
478
|
+
if (!action || !isActionEnabled(action, this.#snapshot.availability) || action.kind !== mode.action.kind) {
|
|
479
|
+
this.#mode = { type: 'browse' };
|
|
480
|
+
return;
|
|
481
|
+
}
|
|
482
|
+
mode.action = action;
|
|
483
|
+
if (mode.type === 'number') {
|
|
484
|
+
// Keep the player's live edit across advisory echoes, but never retain a
|
|
485
|
+
// value outside refreshed authority bounds. Refresh alone does not invoke.
|
|
486
|
+
mode.value = clamp(mode.value, action.min ?? 0, action.max ?? 1);
|
|
487
|
+
}
|
|
488
|
+
if (mode.type === 'picker') {
|
|
489
|
+
const options = action.options ?? [];
|
|
490
|
+
const index = focusedValue ? options.findIndex((option) => option.value === focusedValue) : -1;
|
|
491
|
+
mode.index = firstEnabledOption(options, index >= 0 ? index : 0);
|
|
492
|
+
}
|
|
493
|
+
}
|
|
494
|
+
#render() {
|
|
495
|
+
if (!this.#snapshot)
|
|
496
|
+
return;
|
|
497
|
+
this.#renderStatus();
|
|
498
|
+
if (this.#mode.type === 'number')
|
|
499
|
+
this.#renderNumber();
|
|
500
|
+
else if (this.#mode.type === 'text')
|
|
501
|
+
this.#renderText();
|
|
502
|
+
else if (this.#mode.type === 'picker')
|
|
503
|
+
this.#renderPicker();
|
|
504
|
+
else
|
|
505
|
+
this.#renderBrowse();
|
|
506
|
+
this.#renderHints();
|
|
507
|
+
}
|
|
508
|
+
#renderStatus() {
|
|
509
|
+
const availability = this.#snapshot?.availability;
|
|
510
|
+
this.#status.textContent = availability?.state === 'available'
|
|
511
|
+
? ''
|
|
512
|
+
: availability?.label ?? (availability?.state === 'occupied' ? 'Occupied' : availability?.state === 'busy' ? 'Busy' : '');
|
|
513
|
+
this.#status.dataset.state = availability?.state ?? 'available';
|
|
514
|
+
}
|
|
515
|
+
#renderBrowse() {
|
|
516
|
+
this.element.dataset.mode = 'browse';
|
|
517
|
+
const rows = this.#actions.map((action, index) => {
|
|
518
|
+
const button = make(this.#document, 'button', 'helix-action-surface__row');
|
|
519
|
+
const enabled = isActionEnabled(action, this.#snapshot?.availability);
|
|
520
|
+
button.type = 'button';
|
|
521
|
+
button.dataset.testid = `action-${action.id}`;
|
|
522
|
+
button.dataset.index = String(index);
|
|
523
|
+
button.dataset.selected = String(index === this.#cursor);
|
|
524
|
+
button.setAttribute('aria-selected', String(index === this.#cursor));
|
|
525
|
+
button.disabled = !enabled;
|
|
526
|
+
const label = make(this.#document, 'span', 'helix-action-surface__label');
|
|
527
|
+
label.textContent = action.label;
|
|
528
|
+
const metaText = actionMeta(action);
|
|
529
|
+
button.append(label);
|
|
530
|
+
if (metaText) {
|
|
531
|
+
const meta = make(this.#document, 'span', 'helix-action-surface__meta');
|
|
532
|
+
meta.textContent = metaText;
|
|
533
|
+
button.append(meta);
|
|
534
|
+
}
|
|
535
|
+
button.addEventListener('click', () => {
|
|
536
|
+
// A click (or tap) is unambiguous: it selects and activates whatever it
|
|
537
|
+
// landed on, whichever input drove the selection a moment earlier.
|
|
538
|
+
this.#pointerActive = true;
|
|
539
|
+
this.#cursor = index;
|
|
540
|
+
this.#refreshBrowseSelection();
|
|
541
|
+
this.confirm();
|
|
542
|
+
});
|
|
543
|
+
return button;
|
|
544
|
+
});
|
|
545
|
+
this.#list.replaceChildren(...rows);
|
|
546
|
+
}
|
|
547
|
+
/**
|
|
548
|
+
* Let the pointer drive the selection, but only once it has actually moved.
|
|
549
|
+
*
|
|
550
|
+
* The listener lives on the list, not on each row, so replacing the rows
|
|
551
|
+
* cannot drop it or resurrect it against a stationary cursor.
|
|
552
|
+
*
|
|
553
|
+
* A player navigating with WASD keeps a hand on the mouse, and a mouse at
|
|
554
|
+
* rest still emits `pointermove` — a single pixel of desk wobble, or the
|
|
555
|
+
* camera look that the same mouse is driving. Honouring those events made
|
|
556
|
+
* every keyboard press appear to do nothing: the selection snapped straight
|
|
557
|
+
* back to whatever row sat under the cursor. So after a keyboard or gamepad
|
|
558
|
+
* move the pointer is parked, and it only takes the selection back once it
|
|
559
|
+
* travels past POINTER_WAKE_PX — far enough to be a decision rather than a
|
|
560
|
+
* tremor.
|
|
561
|
+
*/
|
|
562
|
+
#onListPointerMove(event) {
|
|
563
|
+
if (event.clientX === this.#lastPointer.x && event.clientY === this.#lastPointer.y)
|
|
564
|
+
return;
|
|
565
|
+
this.#lastPointer = { x: event.clientX, y: event.clientY };
|
|
566
|
+
// Touch reports a move for every tap. Selection there comes from the tap
|
|
567
|
+
// itself, so hover must never pre-empt it.
|
|
568
|
+
if (event.pointerType === 'touch')
|
|
569
|
+
return;
|
|
570
|
+
if (this.#mode.type !== 'browse')
|
|
571
|
+
return;
|
|
572
|
+
if (!this.#pointerActive) {
|
|
573
|
+
const dx = event.clientX - this.#pointerBaseline.x;
|
|
574
|
+
const dy = event.clientY - this.#pointerBaseline.y;
|
|
575
|
+
// NaN baseline (no pointer seen yet) compares false, so the first real
|
|
576
|
+
// movement wakes the pointer rather than being swallowed.
|
|
577
|
+
if (Math.hypot(dx, dy) < POINTER_WAKE_PX)
|
|
578
|
+
return;
|
|
579
|
+
this.#pointerActive = true;
|
|
580
|
+
}
|
|
581
|
+
const row = event.target?.closest?.('[data-index]');
|
|
582
|
+
if (!(row instanceof this.#document.defaultView.HTMLElement))
|
|
583
|
+
return;
|
|
584
|
+
if (row.hasAttribute('disabled'))
|
|
585
|
+
return;
|
|
586
|
+
const index = Number(row.dataset.index);
|
|
587
|
+
if (!Number.isInteger(index) || index === this.#cursor)
|
|
588
|
+
return;
|
|
589
|
+
this.#cursor = index;
|
|
590
|
+
this.#refreshBrowseSelection();
|
|
591
|
+
}
|
|
592
|
+
/** Hand the selection back to the keys until the pointer moves deliberately. */
|
|
593
|
+
#parkPointer() {
|
|
594
|
+
this.#pointerActive = false;
|
|
595
|
+
this.#pointerBaseline = { ...this.#lastPointer };
|
|
596
|
+
}
|
|
597
|
+
#refreshBrowseSelection() {
|
|
598
|
+
if (this.#mode.type !== 'browse')
|
|
599
|
+
return;
|
|
600
|
+
for (const row of this.#list.querySelectorAll('[data-index]')) {
|
|
601
|
+
const selected = Number(row.dataset.index) === this.#cursor;
|
|
602
|
+
row.dataset.selected = String(selected);
|
|
603
|
+
row.setAttribute('aria-selected', String(selected));
|
|
604
|
+
}
|
|
605
|
+
}
|
|
606
|
+
#renderNumber() {
|
|
607
|
+
if (this.#mode.type !== 'number')
|
|
608
|
+
return;
|
|
609
|
+
const action = this.#mode.action;
|
|
610
|
+
const min = action.min ?? 0;
|
|
611
|
+
const max = action.max ?? 1;
|
|
612
|
+
this.element.dataset.mode = 'number';
|
|
613
|
+
const wrap = make(this.#document, 'div', 'helix-action-surface__adjust');
|
|
614
|
+
wrap.dataset.testid = `number-${action.id}`;
|
|
615
|
+
const head = make(this.#document, 'div', 'helix-action-surface__adjust-head');
|
|
616
|
+
const label = make(this.#document, 'span', 'helix-action-surface__label');
|
|
617
|
+
label.textContent = action.label;
|
|
618
|
+
const output = make(this.#document, 'output', 'helix-action-surface__value');
|
|
619
|
+
output.dataset.testid = 'number-value';
|
|
620
|
+
head.append(label, output);
|
|
621
|
+
const input = make(this.#document, 'input', 'helix-action-surface__range');
|
|
622
|
+
input.type = 'range';
|
|
623
|
+
input.min = String(min);
|
|
624
|
+
input.max = String(max);
|
|
625
|
+
input.step = String(action.step ?? 0.01);
|
|
626
|
+
input.dataset.testid = 'number-range';
|
|
627
|
+
input.setAttribute('aria-label', action.label);
|
|
628
|
+
const push = () => this.#setNumber(Number(input.value));
|
|
629
|
+
input.addEventListener('input', push);
|
|
630
|
+
input.addEventListener('change', push);
|
|
631
|
+
const submit = make(this.#document, 'button', 'helix-action-surface__number-submit');
|
|
632
|
+
submit.type = 'button';
|
|
633
|
+
submit.dataset.testid = 'number-submit';
|
|
634
|
+
submit.textContent = 'Done';
|
|
635
|
+
submit.addEventListener('click', () => this.confirm());
|
|
636
|
+
wrap.append(head, input, submit);
|
|
637
|
+
this.#list.replaceChildren(wrap);
|
|
638
|
+
this.#refreshNumberDom();
|
|
639
|
+
}
|
|
640
|
+
#refreshNumberDom() {
|
|
641
|
+
if (this.#mode.type !== 'number')
|
|
642
|
+
return;
|
|
643
|
+
const action = this.#mode.action;
|
|
644
|
+
const value = this.#mode.value;
|
|
645
|
+
const output = this.#list.querySelector('[data-testid="number-value"]');
|
|
646
|
+
if (output)
|
|
647
|
+
output.textContent = formatNumber(value, action.step, action.unit);
|
|
648
|
+
const input = this.#list.querySelector('[data-testid="number-range"]');
|
|
649
|
+
if (input) {
|
|
650
|
+
input.min = String(action.min ?? 0);
|
|
651
|
+
input.max = String(action.max ?? 1);
|
|
652
|
+
input.step = String(action.step ?? 0.01);
|
|
653
|
+
input.setAttribute('aria-label', action.label);
|
|
654
|
+
// Ranges have no text caret. Synchronize keyboard edits and clamped values
|
|
655
|
+
// even while focused, retaining the element that owns the active drag.
|
|
656
|
+
if (Number(input.value) !== value)
|
|
657
|
+
input.value = String(value);
|
|
658
|
+
}
|
|
659
|
+
}
|
|
660
|
+
#renderText() {
|
|
661
|
+
if (this.#mode.type !== 'text')
|
|
662
|
+
return;
|
|
663
|
+
const action = this.#mode.action;
|
|
664
|
+
this.element.dataset.mode = 'text';
|
|
665
|
+
const wrap = make(this.#document, 'div', 'helix-action-surface__text');
|
|
666
|
+
wrap.dataset.testid = `text-${action.id}`;
|
|
667
|
+
const label = make(this.#document, 'label', 'helix-action-surface__label');
|
|
668
|
+
label.textContent = action.label;
|
|
669
|
+
const input = make(this.#document, 'input', 'helix-action-surface__text-input');
|
|
670
|
+
input.type = 'text';
|
|
671
|
+
input.dataset.testid = 'text-input';
|
|
672
|
+
input.value = this.#mode.value;
|
|
673
|
+
input.placeholder = action.placeholder ?? '';
|
|
674
|
+
input.inputMode = action.inputMode ?? 'text';
|
|
675
|
+
if (action.maxLength !== undefined)
|
|
676
|
+
input.maxLength = action.maxLength;
|
|
677
|
+
label.htmlFor = `${this.#snapshot?.instanceId ?? 'action'}-${action.id}-input`;
|
|
678
|
+
input.id = label.htmlFor;
|
|
679
|
+
input.addEventListener('input', () => {
|
|
680
|
+
if (this.#mode.type === 'text')
|
|
681
|
+
this.#mode.value = input.value;
|
|
682
|
+
});
|
|
683
|
+
input.addEventListener('keydown', (event) => {
|
|
684
|
+
event.stopPropagation();
|
|
685
|
+
if (event.key === 'Enter' && !event.isComposing) {
|
|
686
|
+
event.preventDefault();
|
|
687
|
+
this.confirm();
|
|
688
|
+
}
|
|
689
|
+
else if (event.key === 'Escape') {
|
|
690
|
+
event.preventDefault();
|
|
691
|
+
this.cancel();
|
|
692
|
+
}
|
|
693
|
+
});
|
|
694
|
+
const submit = make(this.#document, 'button', 'helix-action-surface__text-submit');
|
|
695
|
+
submit.type = 'button';
|
|
696
|
+
submit.dataset.testid = 'text-submit';
|
|
697
|
+
submit.textContent = 'Submit';
|
|
698
|
+
submit.addEventListener('click', () => this.confirm());
|
|
699
|
+
wrap.append(label, input, submit);
|
|
700
|
+
this.#list.replaceChildren(wrap);
|
|
701
|
+
input.focus({ preventScroll: true });
|
|
702
|
+
}
|
|
703
|
+
#refreshTextDom() {
|
|
704
|
+
if (this.#mode.type !== 'text')
|
|
705
|
+
return;
|
|
706
|
+
const action = this.#mode.action;
|
|
707
|
+
const input = this.#list.querySelector('[data-testid="text-input"]');
|
|
708
|
+
if (!input)
|
|
709
|
+
return;
|
|
710
|
+
input.placeholder = action.placeholder ?? '';
|
|
711
|
+
input.inputMode = action.inputMode ?? 'text';
|
|
712
|
+
if (action.maxLength !== undefined)
|
|
713
|
+
input.maxLength = action.maxLength;
|
|
714
|
+
else
|
|
715
|
+
input.removeAttribute('maxlength');
|
|
716
|
+
if (this.#document.activeElement !== input)
|
|
717
|
+
input.value = this.#mode.value;
|
|
718
|
+
}
|
|
719
|
+
#renderPicker() {
|
|
720
|
+
if (this.#mode.type !== 'picker')
|
|
721
|
+
return;
|
|
722
|
+
const action = this.#mode.action;
|
|
723
|
+
this.element.dataset.mode = 'picker';
|
|
724
|
+
const current = action.value === undefined || action.value === null ? null : String(action.value);
|
|
725
|
+
const rows = (action.options ?? []).map((option, index) => {
|
|
726
|
+
const button = make(this.#document, 'button', 'helix-action-surface__row');
|
|
727
|
+
button.type = 'button';
|
|
728
|
+
button.dataset.testid = `option-${option.value}`;
|
|
729
|
+
button.dataset.selected = String(index === this.#modePickerIndex());
|
|
730
|
+
button.dataset.current = String(option.value === current);
|
|
731
|
+
button.setAttribute('role', 'radio');
|
|
732
|
+
button.setAttribute('aria-selected', String(index === this.#modePickerIndex()));
|
|
733
|
+
button.setAttribute('aria-checked', String(option.value === current));
|
|
734
|
+
button.disabled = option.disabled === true;
|
|
735
|
+
const mark = make(this.#document, 'span', 'helix-action-surface__mark');
|
|
736
|
+
mark.textContent = option.value === current ? '✓' : '';
|
|
737
|
+
mark.setAttribute('aria-hidden', 'true');
|
|
738
|
+
const label = make(this.#document, 'span', 'helix-action-surface__label');
|
|
739
|
+
label.textContent = option.label;
|
|
740
|
+
button.append(mark, label);
|
|
741
|
+
if (option.reason) {
|
|
742
|
+
const reason = make(this.#document, 'span', 'helix-action-surface__meta');
|
|
743
|
+
reason.textContent = option.reason;
|
|
744
|
+
button.append(reason);
|
|
745
|
+
}
|
|
746
|
+
button.addEventListener('click', () => {
|
|
747
|
+
if (this.#mode.type !== 'picker')
|
|
748
|
+
return;
|
|
749
|
+
this.#mode.index = index;
|
|
750
|
+
this.confirm();
|
|
751
|
+
});
|
|
752
|
+
return button;
|
|
753
|
+
});
|
|
754
|
+
this.#list.replaceChildren(...rows);
|
|
755
|
+
}
|
|
756
|
+
#modePickerIndex() { return this.#mode.type === 'picker' ? this.#mode.index : -1; }
|
|
757
|
+
#renderHints() {
|
|
758
|
+
if (!this.#snapshot)
|
|
759
|
+
return;
|
|
760
|
+
const reported = this.#hints.activeDevice();
|
|
761
|
+
// Touch we saw ourselves outranks a router that only watches game input.
|
|
762
|
+
const device = this.#touchObserved && reported === 'keyboard' ? 'touch' : reported;
|
|
763
|
+
this.element.dataset.device = device;
|
|
764
|
+
const rows = this.#mode.type === 'number'
|
|
765
|
+
? [['move', 'adjust'], ['primary', 'done'], ['cancel', 'back']]
|
|
766
|
+
: this.#mode.type === 'text'
|
|
767
|
+
? [['primary', 'submit'], ['cancel', 'back']]
|
|
768
|
+
: this.#mode.type === 'picker'
|
|
769
|
+
? [['move', 'choose'], ['primary', 'set'], ['cancel', 'back']]
|
|
770
|
+
: [['move', 'choose'], ['primary', 'select'], ['cancel', 'close']];
|
|
771
|
+
const fragments = [];
|
|
772
|
+
for (const [action, label] of rows) {
|
|
773
|
+
const hint = make(this.#document, 'span', 'helix-action-surface__hint-item');
|
|
774
|
+
const key = make(this.#document, 'kbd', 'helix-action-surface__key');
|
|
775
|
+
key.textContent = this.#hints.hint(action);
|
|
776
|
+
const text = make(this.#document, 'span', 'helix-action-surface__hint-label');
|
|
777
|
+
text.textContent = label;
|
|
778
|
+
hint.append(key, text);
|
|
779
|
+
fragments.push(hint);
|
|
780
|
+
}
|
|
781
|
+
this.#hint.replaceChildren(...fragments);
|
|
782
|
+
}
|
|
783
|
+
#assertLive() {
|
|
784
|
+
if (this.#disposed)
|
|
785
|
+
throw new Error('action surface is disposed');
|
|
786
|
+
}
|
|
787
|
+
}
|
|
788
|
+
/** Fresh semantic map so hosts may safely decorate it per instance. */
|
|
789
|
+
export function createActionSurfaceInputMap() {
|
|
790
|
+
return {
|
|
791
|
+
navigate: {
|
|
792
|
+
action: 'move',
|
|
793
|
+
label: 'Navigate',
|
|
794
|
+
touch: { kind: 'stick', zone: 'left' },
|
|
795
|
+
continuous: true,
|
|
796
|
+
repeatMs: 140,
|
|
797
|
+
},
|
|
798
|
+
activate: {
|
|
799
|
+
action: 'primary',
|
|
800
|
+
label: 'Select',
|
|
801
|
+
touch: { kind: 'tap', zone: 'primary' },
|
|
802
|
+
},
|
|
803
|
+
back: {
|
|
804
|
+
action: 'cancel',
|
|
805
|
+
label: 'Back',
|
|
806
|
+
touch: { kind: 'button', zone: 'secondary' },
|
|
807
|
+
},
|
|
808
|
+
};
|
|
809
|
+
}
|
|
810
|
+
/**
|
|
811
|
+
* Opt-in engaged menu mode. Showing a proximity offer alone must not push it:
|
|
812
|
+
* callers engage explicitly, so merely walking near an item never captures the
|
|
813
|
+
* player. The mode uses the same stack/lease as every takeover.
|
|
814
|
+
*/
|
|
815
|
+
export function createActionSurfaceMode(options) {
|
|
816
|
+
let unbind = [];
|
|
817
|
+
return {
|
|
818
|
+
id: options.id ?? 'helix.action-surface',
|
|
819
|
+
suppress: {
|
|
820
|
+
locomotion: true,
|
|
821
|
+
defaultHud: true,
|
|
822
|
+
interaction: true,
|
|
823
|
+
...options.suppression,
|
|
824
|
+
},
|
|
825
|
+
input: createActionSurfaceInputMap(),
|
|
826
|
+
enter(ctx) {
|
|
827
|
+
unbind = [
|
|
828
|
+
ctx.onVerb('navigate', (event) => options.surface.handleVerb('navigate', event)),
|
|
829
|
+
ctx.onVerb('activate', (event) => options.surface.handleVerb('activate', event)),
|
|
830
|
+
ctx.onVerb('back', (event) => {
|
|
831
|
+
const dismissingRoot = event.phase === 'start' && options.surface.mode === 'browse';
|
|
832
|
+
options.surface.handleVerb('back', event);
|
|
833
|
+
if (dismissingRoot)
|
|
834
|
+
ctx.release();
|
|
835
|
+
}),
|
|
836
|
+
];
|
|
837
|
+
},
|
|
838
|
+
exit() {
|
|
839
|
+
for (const dispose of unbind.splice(0))
|
|
840
|
+
dispose();
|
|
841
|
+
options.surface.endEngagement();
|
|
842
|
+
},
|
|
843
|
+
};
|
|
844
|
+
}
|
|
845
|
+
function firstEnabled(actions, parent) {
|
|
846
|
+
const index = actions.findIndex((action) => isActionEnabled(action, parent));
|
|
847
|
+
return index >= 0 ? index : 0;
|
|
848
|
+
}
|
|
849
|
+
function firstEnabledOption(options, preferred) {
|
|
850
|
+
if (options.length === 0)
|
|
851
|
+
return 0;
|
|
852
|
+
if (options[preferred]?.disabled !== true)
|
|
853
|
+
return preferred;
|
|
854
|
+
const index = options.findIndex((option) => option.disabled !== true);
|
|
855
|
+
return index >= 0 ? index : 0;
|
|
856
|
+
}
|
|
857
|
+
function isActionEnabled(action, parent) {
|
|
858
|
+
return action.enabled !== false
|
|
859
|
+
&& (parent?.state ?? 'available') === 'available'
|
|
860
|
+
&& (action.availability?.state ?? 'available') === 'available';
|
|
861
|
+
}
|
|
862
|
+
function readableReason(action) {
|
|
863
|
+
return action.reason?.trim() || action.availability?.label?.trim()
|
|
864
|
+
|| (action.availability?.state === 'occupied' ? 'Occupied' : action.availability?.state === 'busy' ? 'Busy' : undefined);
|
|
865
|
+
}
|
|
866
|
+
function actionMeta(action) {
|
|
867
|
+
const reason = readableReason(action);
|
|
868
|
+
if (reason)
|
|
869
|
+
return reason;
|
|
870
|
+
if (action.kind === 'number' && typeof action.value === 'number') {
|
|
871
|
+
return formatNumber(action.value, action.step, action.unit);
|
|
872
|
+
}
|
|
873
|
+
if (action.kind === 'text' && typeof action.value === 'string' && action.value.length > 0) {
|
|
874
|
+
return action.value.length > 28 ? `${action.value.slice(0, 27)}…` : action.value;
|
|
875
|
+
}
|
|
876
|
+
if ((action.kind === 'choice' || action.kind === 'asset') && action.value !== undefined && action.value !== null) {
|
|
877
|
+
return action.options?.find((option) => option.value === String(action.value))?.label ?? 'Choose';
|
|
878
|
+
}
|
|
879
|
+
if (action.kind === 'takeover')
|
|
880
|
+
return 'Play';
|
|
881
|
+
if (action.kind === 'point')
|
|
882
|
+
return 'Use';
|
|
883
|
+
return '';
|
|
884
|
+
}
|
|
885
|
+
function formatNumber(value, step = 0.01, unit) {
|
|
886
|
+
const decimals = Math.min(6, Math.max(0, decimalPlaces(step)));
|
|
887
|
+
return `${value.toFixed(decimals)}${unit ? ` ${unit}` : ''}`;
|
|
888
|
+
}
|
|
889
|
+
function decimalPlaces(value) {
|
|
890
|
+
const text = String(value);
|
|
891
|
+
if (text.includes('e-'))
|
|
892
|
+
return Number(text.split('e-')[1]);
|
|
893
|
+
return text.includes('.') ? text.length - text.indexOf('.') - 1 : 0;
|
|
894
|
+
}
|
|
895
|
+
function roundToStep(value, min, step) {
|
|
896
|
+
const steps = Math.round((value - min) / step);
|
|
897
|
+
const decimals = Math.min(12, decimalPlaces(step));
|
|
898
|
+
return Number((min + steps * step).toFixed(decimals));
|
|
899
|
+
}
|
|
900
|
+
function clamp(value, min, max) {
|
|
901
|
+
return Math.max(min, Math.min(max, value));
|
|
902
|
+
}
|
|
903
|
+
function make(document, tag, className) {
|
|
904
|
+
const element = document.createElement(tag);
|
|
905
|
+
element.className = className;
|
|
906
|
+
return element;
|
|
907
|
+
}
|
|
908
|
+
const STYLED_DOCUMENTS = new WeakSet();
|
|
909
|
+
function ensureActionSurfaceStyles(document) {
|
|
910
|
+
if (STYLED_DOCUMENTS.has(document))
|
|
911
|
+
return;
|
|
912
|
+
STYLED_DOCUMENTS.add(document);
|
|
913
|
+
const style = document.createElement('style');
|
|
914
|
+
style.dataset.helixActionSurface = 'v0.3';
|
|
915
|
+
style.textContent = `
|
|
916
|
+
/*
|
|
917
|
+
* PALETTE PARITY WITH THE UNIVERSAL PROMPT PILL.
|
|
918
|
+
*
|
|
919
|
+
* This panel is what the pill's activation OPENS — the same "E times Bed"
|
|
920
|
+
* (now key-cap) offer, expanded into a list once there is more than one
|
|
921
|
+
* thing to pick. A player who just read the pill in one visual language
|
|
922
|
+
* must not land in a second one a beat later: same glass depth, same
|
|
923
|
+
* hairline, same corner radius family, same key-cap chip as the host's
|
|
924
|
+
* INTERACTION_PROMPT_CSS (interactionPrompt.ts) and the engine's own
|
|
925
|
+
* sit/lie pill (fx/SitPrompt.ts). Three components, one material.
|
|
926
|
+
*/
|
|
927
|
+
.helix-action-surface {
|
|
928
|
+
--helix-action-fill: rgba(18, 21, 28, .86);
|
|
929
|
+
--helix-action-line: rgba(255, 255, 255, .24);
|
|
930
|
+
--helix-action-radius: 14px;
|
|
931
|
+
box-sizing: border-box;
|
|
932
|
+
position: fixed;
|
|
933
|
+
left: 50%;
|
|
934
|
+
bottom: max(18px, env(safe-area-inset-bottom));
|
|
935
|
+
z-index: 40;
|
|
936
|
+
width: min(340px, 92vw);
|
|
937
|
+
transform: translateX(-50%);
|
|
938
|
+
overflow: hidden;
|
|
939
|
+
color: rgba(255, 255, 255, .92);
|
|
940
|
+
border: 1px solid var(--helix-action-line);
|
|
941
|
+
border-radius: var(--helix-action-radius);
|
|
942
|
+
background: var(--helix-action-fill);
|
|
943
|
+
box-shadow: 0 8px 28px rgba(0, 0, 0, .28);
|
|
944
|
+
backdrop-filter: blur(18px);
|
|
945
|
+
font: 600 12px/1.25 Inter, system-ui, sans-serif;
|
|
946
|
+
}
|
|
947
|
+
.helix-action-surface[hidden] { display: none; }
|
|
948
|
+
.helix-action-surface *, .helix-action-surface *::before, .helix-action-surface *::after { box-sizing: border-box; }
|
|
949
|
+
.helix-action-surface__header { display: flex; align-items: center; gap: 8px; padding: 6px 6px 6px 12px; }
|
|
950
|
+
/* Sentence case, the item's own display name verbatim — never an ALL-CAPS
|
|
951
|
+
* brand shout. A device titled "Continuum Lie Spot" by whoever authored it
|
|
952
|
+
* is not this component's business to editorialise; it is this component's
|
|
953
|
+
* business not to make it look like an internal identifier by shouting it. */
|
|
954
|
+
.helix-action-surface__title { flex: 1; min-width: 0; margin: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: rgba(255,255,255,.7); font-family: inherit; font-size: 12px; font-weight: 600; line-height: 1.2; }
|
|
955
|
+
.helix-action-surface__status { color: #ffd4a3; font-size: 9px; letter-spacing: .08em; text-transform: uppercase; }
|
|
956
|
+
.helix-action-surface__list { display: flex; flex-direction: column; gap: 2px; padding: 0 6px 6px; }
|
|
957
|
+
.helix-action-surface__row { display: flex; align-items: center; gap: 8px; width: 100%; min-height: 34px; padding: 8px; border: 0; border-radius: 8px; background: transparent; color: inherit; font: inherit; text-align: left; cursor: pointer; }
|
|
958
|
+
.helix-action-surface__row:hover:not(:disabled) { background: rgba(255,255,255,.08); }
|
|
959
|
+
.helix-action-surface__row[data-selected="true"] { background: rgba(255,255,255,.92); color: #0a0a0a; }
|
|
960
|
+
.helix-action-surface__row[data-selected="true"]:hover:not(:disabled) { background: rgba(255,255,255,.92); color: #0a0a0a; }
|
|
961
|
+
.helix-action-surface__row:disabled { color: rgba(255,255,255,.34); cursor: default; }
|
|
962
|
+
.helix-action-surface__label { flex: 1; }
|
|
963
|
+
.helix-action-surface__meta { color: rgba(255,255,255,.46); font-size: 9px; letter-spacing: .08em; text-transform: uppercase; }
|
|
964
|
+
.helix-action-surface__row[data-selected="true"] .helix-action-surface__meta { color: rgba(10,10,10,.58); }
|
|
965
|
+
.helix-action-surface__mark { display: grid; place-items: center; width: 16px; height: 16px; border: 1px solid currentColor; border-radius: 4px; font-size: 10px; }
|
|
966
|
+
.helix-action-surface__adjust { padding: 4px 7px 10px; }
|
|
967
|
+
.helix-action-surface__adjust-head { display: flex; align-items: baseline; gap: 8px; margin-bottom: 8px; }
|
|
968
|
+
.helix-action-surface__value { font-variant-numeric: tabular-nums; }
|
|
969
|
+
.helix-action-surface__range { width: 100%; min-height: 28px; accent-color: white; cursor: pointer; }
|
|
970
|
+
.helix-action-surface__text { display: grid; grid-template-columns: 1fr auto; gap: 7px; padding: 5px 7px 10px; }
|
|
971
|
+
.helix-action-surface__text > .helix-action-surface__label { grid-column: 1 / -1; color: rgba(255,255,255,.72); font-size: 10px; }
|
|
972
|
+
.helix-action-surface__text-input { min-width: 0; height: 36px; padding: 0 10px; border: 1px solid rgba(255,255,255,.24); border-radius: 8px; outline: none; background: rgba(0,0,0,.28); color: white; font: inherit; }
|
|
973
|
+
.helix-action-surface__text-input:focus { border-color: rgba(255,255,255,.7); box-shadow: 0 0 0 2px rgba(255,255,255,.1); }
|
|
974
|
+
.helix-action-surface__text-submit { height: 36px; padding: 0 13px; border: 0; border-radius: 8px; background: rgba(255,255,255,.92); color: #0a0a0a; font: 600 10px/1 Inter, system-ui, sans-serif; letter-spacing: .04em; text-transform: uppercase; cursor: pointer; }
|
|
975
|
+
/* Same footer language as the pill's own key cap — a rebound "E" reads
|
|
976
|
+
* identically here and at the prompt that opened this. */
|
|
977
|
+
.helix-action-surface__hint { display: flex; flex-wrap: wrap; gap: 8px; padding: 8px 12px; border-top: 1px solid rgba(255,255,255,.12); background: transparent; color: rgba(255,255,255,.6); font-size: 10px; text-transform: none; }
|
|
978
|
+
.helix-action-surface__hint-item { display: inline-flex; align-items: center; gap: 5px; }
|
|
979
|
+
.helix-action-surface__key { min-width: 20px; padding: 2px 6px; border: 1px solid rgba(255,255,255,.24); border-radius: 6px; background: rgba(255,255,255,.12); color: white; font-family: inherit; font-size: 10px; font-weight: 600; line-height: 1.3; text-align: center; text-transform: none; }
|
|
980
|
+
/* A Device may declare up to sixteen actions. The list scrolls so a long
|
|
981
|
+
one can never grow the panel until it swallows the world behind it. */
|
|
982
|
+
.helix-action-surface__list { max-height: min(46dvh, 340px); overflow-y: auto; overscroll-behavior: contain; }
|
|
983
|
+
|
|
984
|
+
@media (pointer: coarse) {
|
|
985
|
+
.helix-action-surface__row { min-height: 46px; padding: 11px 10px; font-size: 13px; }
|
|
986
|
+
.helix-action-surface__range { min-height: 38px; }
|
|
987
|
+
.helix-action-surface__text-input, .helix-action-surface__text-submit { height: 46px; }
|
|
988
|
+
}
|
|
989
|
+
|
|
990
|
+
/* Keep the whole touch target inside the header's rounded edge, even when
|
|
991
|
+
a long title leaves little room. */
|
|
992
|
+
.helix-action-surface__close {
|
|
993
|
+
display: grid; place-items: center; flex-shrink: 0; width: 44px; height: 44px; margin: 0; padding: 0;
|
|
994
|
+
border: 0; border-radius: 8px; background: rgba(255,255,255,.1); color: inherit;
|
|
995
|
+
font: 600 15px/1 Inter, system-ui, sans-serif; cursor: pointer;
|
|
996
|
+
}
|
|
997
|
+
/* The key caps mean nothing without a keyboard; the labels still do. */
|
|
998
|
+
.helix-action-surface[data-device="touch"] .helix-action-surface__key { display: none; }
|
|
999
|
+
.helix-action-surface[data-device="touch"] .helix-action-surface__hint { gap: 10px; font-size: 10px; }
|
|
1000
|
+
|
|
1001
|
+
/* Portrait phone: a bottom sheet, full-width within the safe area and
|
|
1002
|
+
sitting under the thumb rather than over the middle of the scene. */
|
|
1003
|
+
@media (pointer: coarse) and (orientation: portrait) {
|
|
1004
|
+
.helix-action-surface {
|
|
1005
|
+
width: min(420px, calc(100vw - 20px));
|
|
1006
|
+
bottom: max(12px, env(safe-area-inset-bottom));
|
|
1007
|
+
}
|
|
1008
|
+
.helix-action-surface__list { max-height: min(44dvh, 320px); }
|
|
1009
|
+
}
|
|
1010
|
+
|
|
1011
|
+
/* Landscape phone: the viewport is short, so a bottom sheet would cover
|
|
1012
|
+
most of it. Dock to the trailing edge instead — the world stays visible
|
|
1013
|
+
across the rest of the screen, and the panel stays inside the notch. */
|
|
1014
|
+
@media (pointer: coarse) and (orientation: landscape) {
|
|
1015
|
+
.helix-action-surface {
|
|
1016
|
+
left: auto;
|
|
1017
|
+
right: max(12px, env(safe-area-inset-right));
|
|
1018
|
+
top: 50%;
|
|
1019
|
+
bottom: auto;
|
|
1020
|
+
width: min(340px, 46vw);
|
|
1021
|
+
transform: translateY(-50%);
|
|
1022
|
+
}
|
|
1023
|
+
.helix-action-surface__list { max-height: calc(100dvh - 132px); }
|
|
1024
|
+
}
|
|
1025
|
+
|
|
1026
|
+
@media (prefers-reduced-motion: reduce) {
|
|
1027
|
+
.helix-action-surface, .helix-action-surface__row { transition: none; }
|
|
1028
|
+
}
|
|
1029
|
+
`;
|
|
1030
|
+
document.head.append(style);
|
|
1031
|
+
}
|
|
1032
|
+
//# sourceMappingURL=action-surface.js.map
|