@fiddle-digital/string-tune 1.1.25 → 1.1.27
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/dist/index.cjs +3 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +375 -284
- package/dist/index.d.ts +375 -284
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +3 -3
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -12,96 +12,16 @@ interface StringSettings {
|
|
|
12
12
|
[key: string]: string | number | boolean;
|
|
13
13
|
}
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
constructor();
|
|
26
|
-
/**
|
|
27
|
-
* Subscribes to an event.
|
|
28
|
-
* Optionally appends an `id` to the event name for namespacing.
|
|
29
|
-
*
|
|
30
|
-
* @param eventName The base event name (e.g. "scroll", "update").
|
|
31
|
-
* @param callback The function to call when the event is emitted.
|
|
32
|
-
* @param id Optional unique identifier to scope the event (e.g. element ID).
|
|
33
|
-
*/
|
|
34
|
-
on<T = any>(eventName: string, callback: EventCallback<T>, id?: string | null): void;
|
|
35
|
-
/**
|
|
36
|
-
* Unsubscribes from a specific event listener.
|
|
37
|
-
* Must match the original `eventName`, `callback`, and optional `id`.
|
|
38
|
-
*
|
|
39
|
-
* @param eventName The base event name to unsubscribe from.
|
|
40
|
-
* @param callback The callback function to remove.
|
|
41
|
-
* @param id Optional identifier used when subscribing.
|
|
42
|
-
*/
|
|
43
|
-
off<T = any>(eventName: string, callback: EventCallback<T>, id?: string): void;
|
|
44
|
-
/**
|
|
45
|
-
* Emits an event with an optional payload.
|
|
46
|
-
* All matching listeners will be called.
|
|
47
|
-
*
|
|
48
|
-
* @param eventName The full event name (must include `id` if used).
|
|
49
|
-
* @param payload Optional data passed to event listeners.
|
|
50
|
-
*/
|
|
51
|
-
emit<T = any>(eventName: string, payload?: T): void;
|
|
52
|
-
/**
|
|
53
|
-
* Subscribes to a per-object progress event.
|
|
54
|
-
* @param id The object ID.
|
|
55
|
-
* @param callback The callback to handle progress value.
|
|
56
|
-
*/
|
|
57
|
-
onProgress(id: string, callback: EventCallback<number>): void;
|
|
58
|
-
/**
|
|
59
|
-
* Emits a per-object progress event.
|
|
60
|
-
* @param id The object ID.
|
|
61
|
-
* @param value The progress value.
|
|
62
|
-
*/
|
|
63
|
-
emitProgress(id: string, value: number): void;
|
|
64
|
-
/**
|
|
65
|
-
* Subscribes to a per-object in-view event.
|
|
66
|
-
* @param id The object ID.
|
|
67
|
-
* @param callback The callback to handle visibility.
|
|
68
|
-
*/
|
|
69
|
-
onInview(id: string, callback: EventCallback<boolean>): void;
|
|
70
|
-
/**
|
|
71
|
-
* Emits a per-object in-view event.
|
|
72
|
-
* @param id The object ID.
|
|
73
|
-
* @param visible Whether the object is visible.
|
|
74
|
-
*/
|
|
75
|
-
emitInview(id: string, visible: boolean): void;
|
|
76
|
-
/**
|
|
77
|
-
* Subscribes to the global scroll event.
|
|
78
|
-
* @param callback The callback to handle scroll value.
|
|
79
|
-
*/
|
|
80
|
-
onScroll(callback: EventCallback<number>): void;
|
|
81
|
-
/**
|
|
82
|
-
* Emits the global scroll event.
|
|
83
|
-
* @param value The scroll value.
|
|
84
|
-
*/
|
|
85
|
-
emitScroll(value: number): void;
|
|
86
|
-
/**
|
|
87
|
-
* Subscribes to the global update event.
|
|
88
|
-
* @param callback The callback to handle update.
|
|
89
|
-
*/
|
|
90
|
-
onUpdate(callback: EventCallback<void>): void;
|
|
91
|
-
/**
|
|
92
|
-
* Emits the global update event.
|
|
93
|
-
*/
|
|
94
|
-
emitUpdate(): void;
|
|
95
|
-
/**
|
|
96
|
-
* Clears all listeners for a specific event.
|
|
97
|
-
*
|
|
98
|
-
* @param eventName The full event name (including optional `id`).
|
|
99
|
-
*/
|
|
100
|
-
clear(eventName: string): void;
|
|
101
|
-
/**
|
|
102
|
-
* Clears all registered events.
|
|
103
|
-
*/
|
|
104
|
-
clearAll(): void;
|
|
15
|
+
interface ModuleLifecyclePermissionsItem {
|
|
16
|
+
rebuild: {
|
|
17
|
+
width: boolean;
|
|
18
|
+
height: boolean;
|
|
19
|
+
scrollHeight: boolean;
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
declare class ModuleLifecyclePermissions {
|
|
23
|
+
desktop: ModuleLifecyclePermissionsItem;
|
|
24
|
+
mobile: ModuleLifecyclePermissionsItem;
|
|
105
25
|
}
|
|
106
26
|
|
|
107
27
|
/**
|
|
@@ -132,6 +52,14 @@ declare class CursorState {
|
|
|
132
52
|
* Delta step between current and target Y.
|
|
133
53
|
*/
|
|
134
54
|
stepY: number;
|
|
55
|
+
/**
|
|
56
|
+
* Velocity in X direction, calculated from smoothed position.
|
|
57
|
+
*/
|
|
58
|
+
velocityX: number;
|
|
59
|
+
/**
|
|
60
|
+
* Velocity in Y direction, calculated from smoothed position.
|
|
61
|
+
*/
|
|
62
|
+
velocityY: number;
|
|
135
63
|
}
|
|
136
64
|
|
|
137
65
|
/**
|
|
@@ -255,36 +183,310 @@ declare class ViewportState {
|
|
|
255
183
|
*/
|
|
256
184
|
declare class StringData {
|
|
257
185
|
/**
|
|
258
|
-
* Scroll-related state object.
|
|
259
|
-
* Contains live values like `target`, `current`, `delta`, `direction`, and more.
|
|
260
|
-
* Used for scroll-based animations, transitions, and effects.
|
|
186
|
+
* Scroll-related state object.
|
|
187
|
+
* Contains live values like `target`, `current`, `delta`, `direction`, and more.
|
|
188
|
+
* Used for scroll-based animations, transitions, and effects.
|
|
189
|
+
*/
|
|
190
|
+
scroll: ScrollState;
|
|
191
|
+
/**
|
|
192
|
+
* Viewport-related state object.
|
|
193
|
+
* Holds dimensions like window size, content size, aspect ratios, and more.
|
|
194
|
+
* Useful for layout calculations, unit parsing, and element positioning.
|
|
195
|
+
*/
|
|
196
|
+
viewport: ViewportState;
|
|
197
|
+
/**
|
|
198
|
+
* Cursor-related state object.
|
|
199
|
+
* Tracks cursor position, velocity, movement, and derived values.
|
|
200
|
+
* Can be used for pointer interactions, proximity effects, and hover states.
|
|
201
|
+
*/
|
|
202
|
+
cursor: CursorState;
|
|
203
|
+
/**
|
|
204
|
+
* Render-related state object.
|
|
205
|
+
* Stores data related to rendering context (e.g. WebGL, Three.js),
|
|
206
|
+
* such as shared materials, textures, or active render frame data.
|
|
207
|
+
*/
|
|
208
|
+
render: RenderState;
|
|
209
|
+
/**
|
|
210
|
+
* Time-related state object.
|
|
211
|
+
* Tracks frame timings, including current timestamp, delta between frames,
|
|
212
|
+
* and total elapsed time since animation start.
|
|
213
|
+
* Useful for time-based animations, easing, frame consistency, and syncing logic.
|
|
214
|
+
*/
|
|
215
|
+
time: TimeState;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
/**
|
|
219
|
+
* Base interface for scroll/interaction modules in the StringScroll system.
|
|
220
|
+
*/
|
|
221
|
+
interface IStringModule {
|
|
222
|
+
permissions: ModuleLifecyclePermissions;
|
|
223
|
+
/** Cleans up all internal state and detaches from the system. */
|
|
224
|
+
destroy(): void;
|
|
225
|
+
/** Called once when the module is initialized. */
|
|
226
|
+
onInit(): void;
|
|
227
|
+
/** Called on each frame with current scroll and state data. */
|
|
228
|
+
onFrame(data: StringData): void;
|
|
229
|
+
/** Called when the window or layout is resized. */
|
|
230
|
+
onResize(): void;
|
|
231
|
+
/** Called when the layout is resize width. */
|
|
232
|
+
onResizeWidth(): void;
|
|
233
|
+
/** Called when the system rebuilds the DOM (e.g. after mutations). */
|
|
234
|
+
onDOMRebuild(): void;
|
|
235
|
+
/** Called when scroll position changes. */
|
|
236
|
+
onScroll(data: StringData): void;
|
|
237
|
+
/** Called when scroll change diraction. */
|
|
238
|
+
onDirectionChange(): void;
|
|
239
|
+
/** Called when scrolling starts (user begins scroll). */
|
|
240
|
+
onScrollStart(): void;
|
|
241
|
+
/** Called when scrolling ends (user stops scroll). */
|
|
242
|
+
onScrollStop(): void;
|
|
243
|
+
/** Called when scroll direction changes (e.g. up → down). */
|
|
244
|
+
onScrollDirectionChange(): void;
|
|
245
|
+
/** Called when overall scroll axis changes (vertical ↔ horizontal). */
|
|
246
|
+
onAxisChange(): void;
|
|
247
|
+
/** Called when device type changes (e.g. desktop ↔ mobile). */
|
|
248
|
+
onDeviceChange(): void;
|
|
249
|
+
/** Called when scroll-related system settings or params are updated. */
|
|
250
|
+
onScrollConfigChange(): void;
|
|
251
|
+
/**
|
|
252
|
+
* Called when global system settings are updated via `setupSettings`.
|
|
253
|
+
* Modules can override this to re-read default values, refresh configs,
|
|
254
|
+
* or reapply any cached parameters that depend on settings.
|
|
255
|
+
*
|
|
256
|
+
* This method is triggered after global fallback settings are merged into context.
|
|
257
|
+
*
|
|
258
|
+
* Example use cases:
|
|
259
|
+
* - Recalculating default lerp, anchor, radius, etc.
|
|
260
|
+
* - Updating internal thresholds or animation values.
|
|
261
|
+
* - Reacting to system-wide design changes.
|
|
262
|
+
*/
|
|
263
|
+
onSettingsChange(): void;
|
|
264
|
+
/** Called on mouse move (for interaction-based modules). */
|
|
265
|
+
onMouseMove(event: MouseEvent): void;
|
|
266
|
+
/** Called on wheel scroll (separate from general scroll). */
|
|
267
|
+
onWheel(event: WheelEvent): void;
|
|
268
|
+
/**
|
|
269
|
+
* Called when the DOM mutates — useful for detecting new or removed elements.
|
|
270
|
+
*/
|
|
271
|
+
onDOMMutate(added: NodeList, removed: NodeList): void;
|
|
272
|
+
/**
|
|
273
|
+
* Triggered when an object was successfully connected.
|
|
274
|
+
*/
|
|
275
|
+
onObjectConnected(object: StringObject): void;
|
|
276
|
+
/**
|
|
277
|
+
* Called when a DOM element is detected as a potential interactive object.
|
|
278
|
+
*/
|
|
279
|
+
initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
|
|
280
|
+
calculatePositions(object: StringObject, windowSize: number): void;
|
|
281
|
+
/**
|
|
282
|
+
* Check if a module should connect to a given object.
|
|
283
|
+
*/
|
|
284
|
+
canConnect(object: StringObject): boolean;
|
|
285
|
+
/**
|
|
286
|
+
* Called to connect this module to the object.
|
|
287
|
+
*/
|
|
288
|
+
connectObject(object: StringObject): void;
|
|
289
|
+
/**
|
|
290
|
+
* Called when the cursor or interaction enters an object's area.
|
|
291
|
+
*/
|
|
292
|
+
enterObject(id: string, object: StringObject): void;
|
|
293
|
+
/**
|
|
294
|
+
* Called when the interaction leaves the object's area.
|
|
295
|
+
*/
|
|
296
|
+
exitObject(id: string): void;
|
|
297
|
+
addObject(id: string, object: StringObject): void;
|
|
298
|
+
removeObject(id: string): void;
|
|
299
|
+
}
|
|
300
|
+
|
|
301
|
+
type EventCallback<T = any> = (payload: T) => void;
|
|
302
|
+
|
|
303
|
+
/**
|
|
304
|
+
* Manages custom event subscriptions and dispatching.
|
|
305
|
+
* Allows multiple listeners per event and supports optional `id` suffixing.
|
|
306
|
+
*/
|
|
307
|
+
declare class EventManager {
|
|
308
|
+
private listeners;
|
|
309
|
+
private stateEvents;
|
|
310
|
+
private lastPayloads;
|
|
311
|
+
constructor();
|
|
312
|
+
/**
|
|
313
|
+
* Subscribes to an event.
|
|
314
|
+
* Optionally appends an `id` to the event name for namespacing.
|
|
315
|
+
*
|
|
316
|
+
* @param eventName The base event name (e.g. "scroll", "update").
|
|
317
|
+
* @param callback The function to call when the event is emitted.
|
|
318
|
+
* @param id Optional unique identifier to scope the event (e.g. element ID).
|
|
319
|
+
*/
|
|
320
|
+
on<T = any>(eventName: string, callback: EventCallback<T>, id?: string | null): void;
|
|
321
|
+
/**
|
|
322
|
+
* Unsubscribes from a specific event listener.
|
|
323
|
+
* Must match the original `eventName`, `callback`, and optional `id`.
|
|
324
|
+
*
|
|
325
|
+
* @param eventName The base event name to unsubscribe from.
|
|
326
|
+
* @param callback The callback function to remove.
|
|
327
|
+
* @param id Optional identifier used when subscribing.
|
|
328
|
+
*/
|
|
329
|
+
off<T = any>(eventName: string, callback: EventCallback<T>, id?: string): void;
|
|
330
|
+
/**
|
|
331
|
+
* Emits an event with an optional payload.
|
|
332
|
+
* All matching listeners will be called.
|
|
333
|
+
*
|
|
334
|
+
* @param eventName The full event name (must include `id` if used).
|
|
335
|
+
* @param payload Optional data passed to event listeners.
|
|
336
|
+
*/
|
|
337
|
+
emit<T = any>(eventName: string, payload?: T): void;
|
|
338
|
+
/**
|
|
339
|
+
* Subscribes to a per-object progress event.
|
|
340
|
+
* @param id The object ID.
|
|
341
|
+
* @param callback The callback to handle progress value.
|
|
342
|
+
*/
|
|
343
|
+
onProgress(id: string, callback: EventCallback<number>): void;
|
|
344
|
+
/**
|
|
345
|
+
* Emits a per-object progress event.
|
|
346
|
+
* @param id The object ID.
|
|
347
|
+
* @param value The progress value.
|
|
348
|
+
*/
|
|
349
|
+
emitProgress(id: string, value: number): void;
|
|
350
|
+
/**
|
|
351
|
+
* Subscribes to a per-object in-view event.
|
|
352
|
+
* @param id The object ID.
|
|
353
|
+
* @param callback The callback to handle visibility.
|
|
354
|
+
*/
|
|
355
|
+
onInview(id: string, callback: EventCallback<boolean>): void;
|
|
356
|
+
/**
|
|
357
|
+
* Emits a per-object in-view event.
|
|
358
|
+
* @param id The object ID.
|
|
359
|
+
* @param visible Whether the object is visible.
|
|
360
|
+
*/
|
|
361
|
+
emitInview(id: string, visible: boolean): void;
|
|
362
|
+
/**
|
|
363
|
+
* Subscribes to the global scroll event.
|
|
364
|
+
* @param callback The callback to handle scroll value.
|
|
365
|
+
*/
|
|
366
|
+
onScroll(callback: EventCallback<number>): void;
|
|
367
|
+
/**
|
|
368
|
+
* Emits the global scroll event.
|
|
369
|
+
* @param value The scroll value.
|
|
370
|
+
*/
|
|
371
|
+
emitScroll(value: number): void;
|
|
372
|
+
/**
|
|
373
|
+
* Subscribes to the global update event.
|
|
374
|
+
* @param callback The callback to handle update.
|
|
375
|
+
*/
|
|
376
|
+
onUpdate(callback: EventCallback<void>): void;
|
|
377
|
+
/**
|
|
378
|
+
* Emits the global update event.
|
|
379
|
+
*/
|
|
380
|
+
emitUpdate(): void;
|
|
381
|
+
/**
|
|
382
|
+
* Clears all listeners for a specific event.
|
|
383
|
+
*
|
|
384
|
+
* @param eventName The full event name (including optional `id`).
|
|
385
|
+
*/
|
|
386
|
+
clear(eventName: string): void;
|
|
387
|
+
/**
|
|
388
|
+
* Clears all registered events.
|
|
389
|
+
*/
|
|
390
|
+
clearAll(): void;
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
/**
|
|
394
|
+
* Internal class representing a DOM-bound interactive object.
|
|
395
|
+
* Connected to modules and holds its own internal state.
|
|
396
|
+
*/
|
|
397
|
+
declare class StringObject {
|
|
398
|
+
/**
|
|
399
|
+
* The DOM element this object wraps.
|
|
400
|
+
*/
|
|
401
|
+
htmlElement: HTMLElement;
|
|
402
|
+
/**
|
|
403
|
+
* Unique global ID assigned by the system.
|
|
404
|
+
*/
|
|
405
|
+
id: string;
|
|
406
|
+
/**
|
|
407
|
+
* Space-separated list of all attribute keys associated with this object.
|
|
408
|
+
*/
|
|
409
|
+
keys: string[];
|
|
410
|
+
/**
|
|
411
|
+
* A list of elements that should be affected in sync with this one.
|
|
412
|
+
*/
|
|
413
|
+
connects: HTMLElement[];
|
|
414
|
+
/**
|
|
415
|
+
* Internal key-value store of dynamic object properties (like offsets, progress, etc.).
|
|
416
|
+
*/
|
|
417
|
+
private properties;
|
|
418
|
+
/**
|
|
419
|
+
* Modules currently connected to this object.
|
|
420
|
+
*/
|
|
421
|
+
private modules;
|
|
422
|
+
/**
|
|
423
|
+
* Manages and handles events for the object.
|
|
424
|
+
* Provides functionality to register, trigger, and manage event listeners.
|
|
425
|
+
*/
|
|
426
|
+
events: EventManager;
|
|
427
|
+
constructor(id: string, element: HTMLElement);
|
|
428
|
+
/**
|
|
429
|
+
* Stores a property value for this object.
|
|
430
|
+
* @param key - Property name
|
|
431
|
+
* @param value - Value to store
|
|
261
432
|
*/
|
|
262
|
-
|
|
433
|
+
setProperty<T>(key: string, value: T): void;
|
|
263
434
|
/**
|
|
264
|
-
*
|
|
265
|
-
*
|
|
266
|
-
*
|
|
435
|
+
* Retrieves a previously stored property value.
|
|
436
|
+
* @param key - Property name
|
|
437
|
+
* @returns The value or null if not set
|
|
267
438
|
*/
|
|
268
|
-
|
|
439
|
+
getProperty<T>(key: string): T;
|
|
269
440
|
/**
|
|
270
|
-
*
|
|
271
|
-
* Tracks cursor position, velocity, movement, and derived values.
|
|
272
|
-
* Can be used for pointer interactions, proximity effects, and hover states.
|
|
441
|
+
* Marks this object as "active" (usually on intersection/scroll enter).
|
|
273
442
|
*/
|
|
274
|
-
|
|
443
|
+
enter(): void;
|
|
275
444
|
/**
|
|
276
|
-
*
|
|
277
|
-
* Stores data related to rendering context (e.g. WebGL, Three.js),
|
|
278
|
-
* such as shared materials, textures, or active render frame data.
|
|
445
|
+
* Marks this object as "inactive" (usually on intersection/scroll leave).
|
|
279
446
|
*/
|
|
280
|
-
|
|
447
|
+
leave(): void;
|
|
281
448
|
/**
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
449
|
+
* Removes the current object by iterating through all associated modules
|
|
450
|
+
* and invoking their `removeObject` method with the object's ID.
|
|
451
|
+
*
|
|
452
|
+
* This method ensures that the object is properly removed from all
|
|
453
|
+
* modules it is associated with.
|
|
454
|
+
*/
|
|
455
|
+
remove(): void;
|
|
456
|
+
/**
|
|
457
|
+
* Shows the object, applies visual class and notifies connected modules.
|
|
458
|
+
*/
|
|
459
|
+
show(): void;
|
|
460
|
+
/**
|
|
461
|
+
* Hides the object, removes visual class (if repeat is enabled), and notifies modules.
|
|
462
|
+
*/
|
|
463
|
+
hide(): void;
|
|
464
|
+
/**
|
|
465
|
+
* Connects a module to this object if not already connected.
|
|
466
|
+
* @param module - The module to connect
|
|
467
|
+
*/
|
|
468
|
+
connect(module: IStringModule): void;
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
declare class CenterCache {
|
|
472
|
+
private map;
|
|
473
|
+
private all;
|
|
474
|
+
attach(obj: StringObject): void;
|
|
475
|
+
detach(obj: StringObject): void;
|
|
476
|
+
invalidateAll(): void;
|
|
477
|
+
getCenter(obj: StringObject): {
|
|
478
|
+
cx: number;
|
|
479
|
+
cy: number;
|
|
480
|
+
};
|
|
481
|
+
}
|
|
482
|
+
|
|
483
|
+
declare class HoverTracker {
|
|
484
|
+
private active;
|
|
485
|
+
private subs;
|
|
486
|
+
track(obj: StringObject): void;
|
|
487
|
+
untrack(obj: StringObject): void;
|
|
488
|
+
isActive(obj: StringObject): boolean;
|
|
489
|
+
activeObjects(): StringObject[];
|
|
288
490
|
}
|
|
289
491
|
|
|
290
492
|
/**
|
|
@@ -460,7 +662,7 @@ declare class UnitParserTool implements IStringTool<UnitParserInput, number> {
|
|
|
460
662
|
/**
|
|
461
663
|
* @returns Numeric value in pixels (positive or negative).
|
|
462
664
|
*/
|
|
463
|
-
process({ value, element, viewportHeight, baseRem, boundingRect
|
|
665
|
+
process({ value, element, viewportHeight, baseRem, boundingRect }: UnitParserInput): number;
|
|
464
666
|
}
|
|
465
667
|
|
|
466
668
|
/**
|
|
@@ -871,182 +1073,17 @@ interface StringContext {
|
|
|
871
1073
|
* Centralized event emitter and listener system.
|
|
872
1074
|
*/
|
|
873
1075
|
events: EventManager;
|
|
874
|
-
}
|
|
875
|
-
|
|
876
|
-
interface ModuleLifecyclePermissionsItem {
|
|
877
|
-
rebuild: {
|
|
878
|
-
width: boolean;
|
|
879
|
-
height: boolean;
|
|
880
|
-
scrollHeight: boolean;
|
|
881
|
-
};
|
|
882
|
-
}
|
|
883
|
-
declare class ModuleLifecyclePermissions {
|
|
884
|
-
desktop: ModuleLifecyclePermissionsItem;
|
|
885
|
-
mobile: ModuleLifecyclePermissionsItem;
|
|
886
|
-
}
|
|
887
|
-
|
|
888
|
-
/**
|
|
889
|
-
* Internal class representing a DOM-bound interactive object.
|
|
890
|
-
* Connected to modules and holds its own internal state.
|
|
891
|
-
*/
|
|
892
|
-
declare class StringObject {
|
|
893
|
-
/**
|
|
894
|
-
* The DOM element this object wraps.
|
|
895
|
-
*/
|
|
896
|
-
htmlElement: HTMLElement;
|
|
897
|
-
/**
|
|
898
|
-
* Unique global ID assigned by the system.
|
|
899
|
-
*/
|
|
900
|
-
id: string;
|
|
901
|
-
/**
|
|
902
|
-
* Space-separated list of all attribute keys associated with this object.
|
|
903
|
-
*/
|
|
904
|
-
keys: string[];
|
|
905
|
-
/**
|
|
906
|
-
* A list of elements that should be affected in sync with this one.
|
|
907
|
-
*/
|
|
908
|
-
connects: HTMLElement[];
|
|
909
|
-
/**
|
|
910
|
-
* Internal key-value store of dynamic object properties (like offsets, progress, etc.).
|
|
911
|
-
*/
|
|
912
|
-
private properties;
|
|
913
|
-
/**
|
|
914
|
-
* Modules currently connected to this object.
|
|
915
|
-
*/
|
|
916
|
-
private modules;
|
|
917
|
-
/**
|
|
918
|
-
* Manages and handles events for the object.
|
|
919
|
-
* Provides functionality to register, trigger, and manage event listeners.
|
|
920
|
-
*/
|
|
921
|
-
events: EventManager;
|
|
922
|
-
constructor(id: string, element: HTMLElement);
|
|
923
|
-
/**
|
|
924
|
-
* Stores a property value for this object.
|
|
925
|
-
* @param key - Property name
|
|
926
|
-
* @param value - Value to store
|
|
927
|
-
*/
|
|
928
|
-
setProperty<T>(key: string, value: T): void;
|
|
929
|
-
/**
|
|
930
|
-
* Retrieves a previously stored property value.
|
|
931
|
-
* @param key - Property name
|
|
932
|
-
* @returns The value or null if not set
|
|
933
|
-
*/
|
|
934
|
-
getProperty<T>(key: string): T;
|
|
935
|
-
/**
|
|
936
|
-
* Marks this object as "active" (usually on intersection/scroll enter).
|
|
937
|
-
*/
|
|
938
|
-
enter(): void;
|
|
939
|
-
/**
|
|
940
|
-
* Marks this object as "inactive" (usually on intersection/scroll leave).
|
|
941
|
-
*/
|
|
942
|
-
leave(): void;
|
|
943
|
-
/**
|
|
944
|
-
* Removes the current object by iterating through all associated modules
|
|
945
|
-
* and invoking their `removeObject` method with the object's ID.
|
|
946
|
-
*
|
|
947
|
-
* This method ensures that the object is properly removed from all
|
|
948
|
-
* modules it is associated with.
|
|
949
|
-
*/
|
|
950
|
-
remove(): void;
|
|
951
|
-
/**
|
|
952
|
-
* Shows the object, applies visual class and notifies connected modules.
|
|
953
|
-
*/
|
|
954
|
-
show(): void;
|
|
955
|
-
/**
|
|
956
|
-
* Hides the object, removes visual class (if repeat is enabled), and notifies modules.
|
|
957
|
-
*/
|
|
958
|
-
hide(): void;
|
|
959
|
-
/**
|
|
960
|
-
* Connects a module to this object if not already connected.
|
|
961
|
-
* @param module - The module to connect
|
|
962
|
-
*/
|
|
963
|
-
connect(module: IStringModule): void;
|
|
964
|
-
}
|
|
965
|
-
|
|
966
|
-
/**
|
|
967
|
-
* Base interface for scroll/interaction modules in the StringScroll system.
|
|
968
|
-
*/
|
|
969
|
-
interface IStringModule {
|
|
970
|
-
permissions: ModuleLifecyclePermissions;
|
|
971
|
-
/** Cleans up all internal state and detaches from the system. */
|
|
972
|
-
destroy(): void;
|
|
973
|
-
/** Called once when the module is initialized. */
|
|
974
|
-
onInit(): void;
|
|
975
|
-
/** Called on each frame with current scroll and state data. */
|
|
976
|
-
onFrame(data: StringData): void;
|
|
977
|
-
/** Called when the window or layout is resized. */
|
|
978
|
-
onResize(): void;
|
|
979
|
-
/** Called when the layout is resize width. */
|
|
980
|
-
onResizeWidth(): void;
|
|
981
|
-
/** Called when the system rebuilds the DOM (e.g. after mutations). */
|
|
982
|
-
onDOMRebuild(): void;
|
|
983
|
-
/** Called when scroll position changes. */
|
|
984
|
-
onScroll(data: StringData): void;
|
|
985
|
-
/** Called when scroll change diraction. */
|
|
986
|
-
onDirectionChange(): void;
|
|
987
|
-
/** Called when scrolling starts (user begins scroll). */
|
|
988
|
-
onScrollStart(): void;
|
|
989
|
-
/** Called when scrolling ends (user stops scroll). */
|
|
990
|
-
onScrollStop(): void;
|
|
991
|
-
/** Called when scroll direction changes (e.g. up → down). */
|
|
992
|
-
onScrollDirectionChange(): void;
|
|
993
|
-
/** Called when overall scroll axis changes (vertical ↔ horizontal). */
|
|
994
|
-
onAxisChange(): void;
|
|
995
|
-
/** Called when device type changes (e.g. desktop ↔ mobile). */
|
|
996
|
-
onDeviceChange(): void;
|
|
997
|
-
/** Called when scroll-related system settings or params are updated. */
|
|
998
|
-
onScrollConfigChange(): void;
|
|
999
|
-
/**
|
|
1000
|
-
* Called when global system settings are updated via `setupSettings`.
|
|
1001
|
-
* Modules can override this to re-read default values, refresh configs,
|
|
1002
|
-
* or reapply any cached parameters that depend on settings.
|
|
1003
|
-
*
|
|
1004
|
-
* This method is triggered after global fallback settings are merged into context.
|
|
1005
|
-
*
|
|
1006
|
-
* Example use cases:
|
|
1007
|
-
* - Recalculating default lerp, anchor, radius, etc.
|
|
1008
|
-
* - Updating internal thresholds or animation values.
|
|
1009
|
-
* - Reacting to system-wide design changes.
|
|
1010
|
-
*/
|
|
1011
|
-
onSettingsChange(): void;
|
|
1012
|
-
/** Called on mouse move (for interaction-based modules). */
|
|
1013
|
-
onMouseMove(event: MouseEvent): void;
|
|
1014
|
-
/** Called on wheel scroll (separate from general scroll). */
|
|
1015
|
-
onWheel(event: WheelEvent): void;
|
|
1016
|
-
/**
|
|
1017
|
-
* Called when the DOM mutates — useful for detecting new or removed elements.
|
|
1018
|
-
*/
|
|
1019
|
-
onDOMMutate(added: NodeList, removed: NodeList): void;
|
|
1020
|
-
/**
|
|
1021
|
-
* Triggered when an object was successfully connected.
|
|
1022
|
-
*/
|
|
1023
|
-
onObjectConnected(object: StringObject): void;
|
|
1024
|
-
/**
|
|
1025
|
-
* Called when a DOM element is detected as a potential interactive object.
|
|
1026
|
-
*/
|
|
1027
|
-
initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
|
|
1028
|
-
calculatePositions(object: StringObject, windowSize: number): void;
|
|
1029
|
-
/**
|
|
1030
|
-
* Check if a module should connect to a given object.
|
|
1031
|
-
*/
|
|
1032
|
-
canConnect(object: StringObject): boolean;
|
|
1033
|
-
/**
|
|
1034
|
-
* Called to connect this module to the object.
|
|
1035
|
-
*/
|
|
1036
|
-
connectObject(object: StringObject): void;
|
|
1037
1076
|
/**
|
|
1038
|
-
*
|
|
1077
|
+
* Caches the center positions of string objects.
|
|
1039
1078
|
*/
|
|
1040
|
-
|
|
1079
|
+
centers: CenterCache;
|
|
1041
1080
|
/**
|
|
1042
|
-
*
|
|
1081
|
+
* Tracks hover states of string objects.
|
|
1043
1082
|
*/
|
|
1044
|
-
|
|
1045
|
-
addObject(id: string, object: StringObject): void;
|
|
1046
|
-
removeObject(id: string): void;
|
|
1083
|
+
hover: HoverTracker;
|
|
1047
1084
|
}
|
|
1048
1085
|
|
|
1049
|
-
type AttributeType = "string" | "number" | "boolean" | "json" | "dimension" | "tuple" | "easing" | "color" | {
|
|
1086
|
+
type AttributeType = "string" | "number" | "boolean" | "json" | "dimension" | "breakpoint-dimension" | "tuple" | "easing" | "color" | {
|
|
1050
1087
|
type: "enum";
|
|
1051
1088
|
values: string[];
|
|
1052
1089
|
};
|
|
@@ -1145,6 +1182,14 @@ declare class StringModule implements IStringModule {
|
|
|
1145
1182
|
* Supports custom event emitting, listening, and unsubscription.
|
|
1146
1183
|
*/
|
|
1147
1184
|
protected events: EventManager;
|
|
1185
|
+
/**
|
|
1186
|
+
* Cache for storing and managing object centers.
|
|
1187
|
+
*/
|
|
1188
|
+
protected centers: CenterCache;
|
|
1189
|
+
/**
|
|
1190
|
+
* Tracker for managing hover states of objects.
|
|
1191
|
+
*/
|
|
1192
|
+
protected hover: HoverTracker;
|
|
1148
1193
|
permissions: ModuleLifecyclePermissions;
|
|
1149
1194
|
constructor(context: StringContext);
|
|
1150
1195
|
/**
|
|
@@ -1242,6 +1287,11 @@ declare class StringModule implements IStringModule {
|
|
|
1242
1287
|
* @param object The connected object.
|
|
1243
1288
|
*/
|
|
1244
1289
|
onObjectConnected(object: StringObject): void;
|
|
1290
|
+
/**
|
|
1291
|
+
* Called when an object is disconnected. Can be overridden to clean up styles or logic.
|
|
1292
|
+
* @param object The disconnected object.
|
|
1293
|
+
*/
|
|
1294
|
+
onObjectDisconnected(object: StringObject): void;
|
|
1245
1295
|
/**
|
|
1246
1296
|
* Applies a style or callback to both the main element and all its connected elements.
|
|
1247
1297
|
*
|
|
@@ -1775,6 +1825,41 @@ declare class StringForm extends StringModule {
|
|
|
1775
1825
|
getFieldValue(field: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): any;
|
|
1776
1826
|
}
|
|
1777
1827
|
|
|
1828
|
+
declare abstract class CursorReactiveModule extends StringModule {
|
|
1829
|
+
protected nearOnly: boolean;
|
|
1830
|
+
protected emitEveryN: number;
|
|
1831
|
+
protected updateThreshold: number;
|
|
1832
|
+
private rafFrame;
|
|
1833
|
+
constructor(context: StringContext);
|
|
1834
|
+
onObjectConnected(object: StringObject): void;
|
|
1835
|
+
removeObject(id: string): void;
|
|
1836
|
+
onScroll(): void;
|
|
1837
|
+
onMouseMove(e: MouseEvent): void;
|
|
1838
|
+
onFrame(data: StringData): void;
|
|
1839
|
+
protected abstract onPointerDelta(obj: StringObject, dx: number, dy: number, dist: number): void;
|
|
1840
|
+
protected abstract onCursorFrame(data: StringData, frame: number): void;
|
|
1841
|
+
}
|
|
1842
|
+
|
|
1843
|
+
declare class StringScroller extends StringModule {
|
|
1844
|
+
constructor(context: StringContext);
|
|
1845
|
+
onObjectConnected(object: StringObject): void;
|
|
1846
|
+
onObjectDisconnected(object: StringObject): void;
|
|
1847
|
+
}
|
|
1848
|
+
|
|
1849
|
+
declare class StringImpulse extends StringModule {
|
|
1850
|
+
constructor(context: StringContext);
|
|
1851
|
+
onObjectConnected(object: StringObject): void;
|
|
1852
|
+
onObjectDisconnected(object: StringObject): void;
|
|
1853
|
+
onMouseMove(_e?: MouseEvent): void;
|
|
1854
|
+
onFrame(_: StringData): void;
|
|
1855
|
+
}
|
|
1856
|
+
|
|
1857
|
+
declare class StringProgressPart extends StringModule {
|
|
1858
|
+
constructor(context: StringContext);
|
|
1859
|
+
onObjectConnected(object: StringObject): void;
|
|
1860
|
+
onObjectDisconnected(object: StringObject): void;
|
|
1861
|
+
}
|
|
1862
|
+
|
|
1778
1863
|
declare class StringTune {
|
|
1779
1864
|
/** Bound handler for the scroll start event */
|
|
1780
1865
|
private onScrollStartBind;
|
|
@@ -1790,6 +1875,7 @@ declare class StringTune {
|
|
|
1790
1875
|
private onResizeBind;
|
|
1791
1876
|
/** Bound mouse move handler */
|
|
1792
1877
|
private onMouseMoveBind;
|
|
1878
|
+
private onContainerTransitionEndBind;
|
|
1793
1879
|
/** Singleton instance of StringTune */
|
|
1794
1880
|
private static i;
|
|
1795
1881
|
/** Root scrollable element (typically <body>) */
|
|
@@ -1818,6 +1904,10 @@ declare class StringTune {
|
|
|
1818
1904
|
private data;
|
|
1819
1905
|
/** Context shared across all modules (events, data, tools, settings) */
|
|
1820
1906
|
private context;
|
|
1907
|
+
/** Caches the center positions of string objects. */
|
|
1908
|
+
private centers;
|
|
1909
|
+
/** Tracks hover states of string objects. */
|
|
1910
|
+
private hoverManager;
|
|
1821
1911
|
/**
|
|
1822
1912
|
* Sets the scroll position manually.
|
|
1823
1913
|
* This overrides all internal scroll states including target and lerped values.
|
|
@@ -1947,6 +2037,7 @@ declare class StringTune {
|
|
|
1947
2037
|
* @param settings A key-value map of default settings (e.g. 'offset-top': '-10%').
|
|
1948
2038
|
*/
|
|
1949
2039
|
setupSettings(settings: StringSettings): void;
|
|
2040
|
+
private onContainerTransitionEnd;
|
|
1950
2041
|
/**
|
|
1951
2042
|
* Handles mouse move event and dispatches it to cursor and modules.
|
|
1952
2043
|
* @param e Native mouse move event.
|
|
@@ -2012,4 +2103,4 @@ declare class StringTune {
|
|
|
2012
2103
|
destroy(): void;
|
|
2013
2104
|
}
|
|
2014
2105
|
|
|
2015
|
-
export { type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringResponsive, StringScrollbar, StringSequence, StringSplit, StringTune, StringVideoAutoplay, StringTune as default };
|
|
2106
|
+
export { CursorReactiveModule, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringResponsive, StringScrollbar, StringScroller, StringSequence, StringSplit, StringTune, StringVideoAutoplay, StringTune as default };
|