@zcomponent/core 1.14.3 → 1.16.0-beta

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.
Files changed (141) hide show
  1. package/README.md +0 -6
  2. package/lib/actionbehavior.d.ts +12 -3
  3. package/lib/actionbehavior.js +12 -3
  4. package/lib/animation/animation.d.ts +96 -4
  5. package/lib/animation/animation.js +93 -0
  6. package/lib/animation/animationstate.d.ts +52 -2
  7. package/lib/animation/bezier.d.ts +12 -1
  8. package/lib/animation/bezier.js +15 -12
  9. package/lib/animation/clips/clip.d.ts +71 -0
  10. package/lib/animation/clips/clip.js +68 -0
  11. package/lib/animation/interpolate.d.ts +17 -0
  12. package/lib/animation/interpolate.js +71 -0
  13. package/lib/animation/keyframe.d.ts +24 -1
  14. package/lib/animation/layer.d.ts +73 -1
  15. package/lib/animation/layer.js +69 -0
  16. package/lib/animation/layerclip.d.ts +75 -0
  17. package/lib/animation/layerclip.js +69 -0
  18. package/lib/animation/stream.d.ts +49 -7
  19. package/lib/animation/stream.js +3 -0
  20. package/lib/animation/tracks/cliptrack.d.ts +64 -0
  21. package/lib/animation/tracks/cliptrack.js +65 -1
  22. package/lib/animation/tracks/functiontrack.d.ts +60 -0
  23. package/lib/animation/tracks/functiontrack.js +62 -3
  24. package/lib/animation/tracks/propertytrack.d.ts +84 -0
  25. package/lib/animation/tracks/propertytrack.js +75 -0
  26. package/lib/animation/tracks/streamtrack.d.ts +51 -0
  27. package/lib/animation/tracks/streamtrack.js +54 -3
  28. package/lib/animation/tracks/track.d.ts +56 -0
  29. package/lib/animation/tracks/track.js +40 -0
  30. package/lib/behavior.d.ts +37 -0
  31. package/lib/behavior.js +21 -0
  32. package/lib/behaviors/ActivateState.d.ts +10 -3
  33. package/lib/behaviors/ActivateState.js +8 -4
  34. package/lib/behaviors/CallFunction.d.ts +1 -1
  35. package/lib/behaviors/CallFunction.js +2 -2
  36. package/lib/behaviors/ConsoleLog.d.ts +1 -1
  37. package/lib/behaviors/ConsoleLog.js +2 -2
  38. package/lib/behaviors/DownloadSnapshot.d.ts +5 -2
  39. package/lib/behaviors/DownloadSnapshot.js +5 -2
  40. package/lib/behaviors/LaunchURL.d.ts +1 -1
  41. package/lib/behaviors/LaunchURL.js +1 -1
  42. package/lib/behaviors/LogAnalyticsEvent.d.ts +1 -1
  43. package/lib/behaviors/LogAnalyticsEvent.js +2 -2
  44. package/lib/behaviors/PauseLayerClip.d.ts +5 -3
  45. package/lib/behaviors/PauseLayerClip.js +3 -2
  46. package/lib/behaviors/PlayLayerClip.d.ts +10 -4
  47. package/lib/behaviors/PlayLayerClip.js +7 -5
  48. package/lib/behaviors/PlaySound.d.ts +4 -4
  49. package/lib/behaviors/PlaySound.js +4 -4
  50. package/lib/behaviors/SetLayerOff.d.ts +4 -3
  51. package/lib/behaviors/SetLayerOff.js +3 -2
  52. package/lib/behaviors/ShowTextAlert.d.ts +2 -2
  53. package/lib/behaviors/ShowTextAlert.js +5 -5
  54. package/lib/behaviors/ToggleLayerClips.d.ts +4 -3
  55. package/lib/behaviors/ToggleLayerClips.js +5 -4
  56. package/lib/behaviors/stream/PauseStream.d.ts +15 -3
  57. package/lib/behaviors/stream/PauseStream.js +13 -2
  58. package/lib/behaviors/stream/PlayStream.d.ts +14 -4
  59. package/lib/behaviors/stream/PlayStream.js +10 -3
  60. package/lib/behaviors/stream/SeekStream.d.ts +12 -3
  61. package/lib/behaviors/stream/SeekStream.js +10 -2
  62. package/lib/behaviors/stream/StopStream.d.ts +11 -3
  63. package/lib/behaviors/stream/StopStream.js +9 -2
  64. package/lib/component.d.ts +85 -5
  65. package/lib/component.js +49 -1
  66. package/lib/components/Audio.d.ts +14 -5
  67. package/lib/components/Audio.js +19 -10
  68. package/lib/components/AudioLayerSettings.d.ts +9 -3
  69. package/lib/components/AudioLayerSettings.js +9 -3
  70. package/lib/components/Children.d.ts +7 -2
  71. package/lib/components/Children.js +6 -1
  72. package/lib/components/DefaultCookieConsent.d.ts +13 -3
  73. package/lib/components/DefaultCookieConsent.js +62 -38
  74. package/lib/components/DefaultLoader.d.ts +14 -9
  75. package/lib/components/DefaultLoader.js +25 -20
  76. package/lib/components/Gamepad.d.ts +12 -4
  77. package/lib/components/Gamepad.js +16 -8
  78. package/lib/components/LongLoad.d.ts +7 -1
  79. package/lib/components/LongLoad.js +7 -1
  80. package/lib/components/SnapshotUI.d.ts +10 -0
  81. package/lib/components/SnapshotUI.js +24 -0
  82. package/lib/context.d.ts +117 -0
  83. package/lib/context.js +50 -71
  84. package/lib/contexts/analyticscontext.d.ts +6 -0
  85. package/lib/contexts/analyticscontext.js +6 -0
  86. package/lib/contexts/audiocontextcontext.d.ts +26 -1
  87. package/lib/contexts/audiocontextcontext.js +26 -1
  88. package/lib/contexts/canvascontext.d.ts +59 -1
  89. package/lib/contexts/canvascontext.js +54 -1
  90. package/lib/contexts/cookieconsentcontext.d.ts +84 -10
  91. package/lib/contexts/cookieconsentcontext.js +71 -0
  92. package/lib/contexts/environmentcontext.d.ts +40 -5
  93. package/lib/contexts/environmentcontext.js +40 -5
  94. package/lib/contexts/gamepadcontext.d.ts +38 -0
  95. package/lib/contexts/gamepadcontext.js +38 -0
  96. package/lib/contexts/gesturecontext.d.ts +31 -4
  97. package/lib/contexts/gesturecontext.js +28 -4
  98. package/lib/contexts/globaltagcontext.d.ts +14 -2
  99. package/lib/contexts/globaltagcontext.js +13 -1
  100. package/lib/contexts/loadcontext.d.ts +92 -5
  101. package/lib/contexts/loadcontext.js +98 -11
  102. package/lib/contexts/orientationcontext.d.ts +58 -1
  103. package/lib/contexts/orientationcontext.js +51 -1
  104. package/lib/contexts/snapshotContext.d.ts +97 -4
  105. package/lib/contexts/snapshotContext.js +115 -4
  106. package/lib/contexts/tagcontext.d.ts +56 -2
  107. package/lib/contexts/tagcontext.js +77 -7
  108. package/lib/contexts/textalertcontext.d.ts +35 -2
  109. package/lib/contexts/textalertcontext.js +20 -2
  110. package/lib/contexts/usereventcontext.d.ts +29 -0
  111. package/lib/contexts/usereventcontext.js +30 -1
  112. package/lib/data/animation.d.ts +163 -0
  113. package/lib/data/animation.js +9 -0
  114. package/lib/data/change.d.ts +199 -0
  115. package/lib/data/change.js +190 -0
  116. package/lib/emitter.d.ts +8 -1
  117. package/lib/emitter.js +7 -0
  118. package/lib/entity.d.ts +30 -5
  119. package/lib/entity.js +23 -7
  120. package/lib/event.d.ts +19 -2
  121. package/lib/event.js +19 -2
  122. package/lib/fractionalindexing.js +38 -42
  123. package/lib/inflate.d.ts +68 -0
  124. package/lib/inflate.js +76 -0
  125. package/lib/observable.d.ts +3 -3
  126. package/lib/observable.js +4 -4
  127. package/lib/profile.d.ts +27 -0
  128. package/lib/profile.js +26 -0
  129. package/lib/selectors.d.ts +114 -0
  130. package/lib/selectors.js +159 -7
  131. package/lib/types.d.ts +215 -0
  132. package/lib/types.js +110 -1
  133. package/lib/validators.d.ts +27 -0
  134. package/lib/validators.js +27 -0
  135. package/lib/values/values.d.ts +5 -0
  136. package/lib/values/values.js +5 -0
  137. package/lib/zcomponent.d.ts +72 -0
  138. package/lib/zcomponent.js +81 -0
  139. package/lib/zcomponentconstruction.d.ts +11 -1
  140. package/lib/zcomponentconstruction.js +10 -0
  141. package/package.json +7 -2
@@ -2,9 +2,24 @@ import { FadeParameters, BlendType } from '../../data';
2
2
  import { Animation } from '../animation';
3
3
  import { Keyframe } from '../keyframe';
4
4
  import { Track } from './track';
5
+ /**
6
+ * Manages keyframes for animating entity properties over time.
7
+ * Handles initialization of property paths, registration of entities and paths, sorting of keyframes and weights.
8
+ * Supports computation of interpolated values between keyframes based on blend types.
9
+ * Facilitates adding, retrieving, and setting keyframes and weights, enabling precise and flexible property animation.
10
+ *
11
+ * @param anim The associated Animation instance.
12
+ * @param _entityID The ID of the entity associated with the track.
13
+ * @param _entity The entity itself.
14
+ * @param property The property or array of properties to be animated.
15
+ * @param id Optional unique identifier for the PropertyTrack.
16
+ */
5
17
  export declare class PropertyTrack extends Track {
6
18
  private _entityID;
7
19
  private _entity;
20
+ /**
21
+ * Path representing the property being animated.
22
+ */
8
23
  path: string;
9
24
  private _property;
10
25
  private _path;
@@ -14,22 +29,91 @@ export declare class PropertyTrack extends Track {
14
29
  private _weights;
15
30
  private _weightsById;
16
31
  private _weightsDirty;
32
+ /**
33
+ * Optional parameters for fading animation properties.
34
+ */
17
35
  fadeParameters?: Partial<FadeParameters>;
36
+ /**
37
+ * Blend type for interpolating values.
38
+ */
18
39
  blend: BlendType;
40
+ /**
41
+ * Paths influenced by this track.
42
+ */
19
43
  influencedPaths: string[];
44
+ /**
45
+ * Creates an instance of PropertyTrack.
46
+ * @param anim - The associated Animation instance.
47
+ * @param _entityID - The ID of the entity associated with the track.
48
+ * @param _entity - The entity itself.
49
+ * @param property - The property or array of properties to be animated.
50
+ * @param id - Optional unique identifier for the PropertyTrack.
51
+ */
20
52
  constructor(anim: Animation, _entityID: string, _entity: any, property: string | number | (string | number)[], id?: string);
53
+ /**
54
+ * Adds a keyframe to manage the property's animation.
55
+ *
56
+ * @param k The keyframe to be added.
57
+ */
21
58
  addKeyframe(k: Keyframe): void;
59
+ /**
60
+ * Retrieves a keyframe by its ID.
61
+ *
62
+ * @param id The ID of the keyframe to retrieve.
63
+ * @returns The keyframe, if found; otherwise undefined.
64
+ */
22
65
  getKeyframeById(id: string): Keyframe | undefined;
66
+ /**
67
+ * Sets the keyframes for the track using an id-indexed object.
68
+ *
69
+ * @param keyframes An object mapping keyframe IDs to keyframes.
70
+ */
23
71
  setKeyframesById(keyframes: {
24
72
  [id: string]: Keyframe;
25
73
  }): void;
74
+ /**
75
+ * Getter for sorted keyframes by their time values.
76
+ *
77
+ * @returns A sorted array of keyframes.
78
+ */
26
79
  get sortedKeyframes(): Keyframe[];
80
+ /**
81
+ * Adds a weight keyframe to influence the property's animation.
82
+ *
83
+ * @param k The weight keyframe to be added.
84
+ */
27
85
  addWeight(k: Keyframe): void;
86
+ /**
87
+ * Sets the weight keyframes for the track using an id-indexed object.
88
+ *
89
+ * @param weights An object mapping weight keyframe IDs to keyframes.
90
+ */
28
91
  setWeightsById(weights: {
29
92
  [id: string]: Keyframe;
30
93
  }): void;
94
+ /**
95
+ * Getter for sorted weight keyframes by their time values.
96
+ *
97
+ * @returns A sorted array of weight keyframes.
98
+ */
31
99
  get sortedWeights(): Keyframe[];
100
+ /**
101
+ * Computes the fade length for a given path.
102
+ *
103
+ * @param path The path for which to compute the fade length.
104
+ * @returns The fade length, defaulting to 0 if not specified.
105
+ */
32
106
  getFadeLengthForPath(path: string): number;
107
+ /**
108
+ * Computes the property value for a given path at a specific time.
109
+ * Interpolates between keyframe values based on the specified blend type.
110
+ *
111
+ * @param t The time at which to compute the property.
112
+ * @param p The path of the property to compute.
113
+ * @param valueBefore The initial value of the property before computation.
114
+ * @param parentWeight Optional weight from the parent track.
115
+ * @returns The computed property value.
116
+ */
33
117
  computePathProperty(t: number, p: string, valueBefore: any, parentWeight?: number): any;
34
118
  private _computePathProperty;
35
119
  }
@@ -2,7 +2,27 @@ import { Observable } from '../../observable';
2
2
  import { addBlend, interpolate } from '../interpolate';
3
3
  import { resolveKeyframes, resolveKeyframeValue, Track } from './track';
4
4
  const _scratch = new Observable(undefined);
5
+ /**
6
+ * Manages keyframes for animating entity properties over time.
7
+ * Handles initialization of property paths, registration of entities and paths, sorting of keyframes and weights.
8
+ * Supports computation of interpolated values between keyframes based on blend types.
9
+ * Facilitates adding, retrieving, and setting keyframes and weights, enabling precise and flexible property animation.
10
+ *
11
+ * @param anim The associated Animation instance.
12
+ * @param _entityID The ID of the entity associated with the track.
13
+ * @param _entity The entity itself.
14
+ * @param property The property or array of properties to be animated.
15
+ * @param id Optional unique identifier for the PropertyTrack.
16
+ */
5
17
  export class PropertyTrack extends Track {
18
+ /**
19
+ * Creates an instance of PropertyTrack.
20
+ * @param anim - The associated Animation instance.
21
+ * @param _entityID - The ID of the entity associated with the track.
22
+ * @param _entity - The entity itself.
23
+ * @param property - The property or array of properties to be animated.
24
+ * @param id - Optional unique identifier for the PropertyTrack.
25
+ */
6
26
  constructor(anim, _entityID, _entity, property, id) {
7
27
  super(anim, id);
8
28
  this._entityID = _entityID;
@@ -13,6 +33,9 @@ export class PropertyTrack extends Track {
13
33
  this._weights = [];
14
34
  this._weightsById = {};
15
35
  this._weightsDirty = false;
36
+ /**
37
+ * Blend type for interpolating values.
38
+ */
16
39
  this.blend = 'overlay';
17
40
  if (Array.isArray(property)) {
18
41
  this._property = property[0];
@@ -26,17 +49,38 @@ export class PropertyTrack extends Track {
26
49
  this.influencedPaths = [this.path];
27
50
  anim.registerEntityProperty(this.path, _entity, this._property);
28
51
  }
52
+ /**
53
+ * Adds a keyframe to manage the property's animation.
54
+ *
55
+ * @param k The keyframe to be added.
56
+ */
29
57
  addKeyframe(k) {
30
58
  this._keyframesById[k.id] = k;
31
59
  this._keyframesDirty = true;
32
60
  }
61
+ /**
62
+ * Retrieves a keyframe by its ID.
63
+ *
64
+ * @param id The ID of the keyframe to retrieve.
65
+ * @returns The keyframe, if found; otherwise undefined.
66
+ */
33
67
  getKeyframeById(id) {
34
68
  return this._keyframesById[id];
35
69
  }
70
+ /**
71
+ * Sets the keyframes for the track using an id-indexed object.
72
+ *
73
+ * @param keyframes An object mapping keyframe IDs to keyframes.
74
+ */
36
75
  setKeyframesById(keyframes) {
37
76
  this._keyframesById = keyframes;
38
77
  this._keyframesDirty = true;
39
78
  }
79
+ /**
80
+ * Getter for sorted keyframes by their time values.
81
+ *
82
+ * @returns A sorted array of keyframes.
83
+ */
40
84
  get sortedKeyframes() {
41
85
  if (!this._keyframesDirty)
42
86
  return this._keyframes;
@@ -45,14 +89,29 @@ export class PropertyTrack extends Track {
45
89
  this._keyframesDirty = false;
46
90
  return this._keyframes;
47
91
  }
92
+ /**
93
+ * Adds a weight keyframe to influence the property's animation.
94
+ *
95
+ * @param k The weight keyframe to be added.
96
+ */
48
97
  addWeight(k) {
49
98
  this._weightsById[k.id] = k;
50
99
  this._weightsDirty = true;
51
100
  }
101
+ /**
102
+ * Sets the weight keyframes for the track using an id-indexed object.
103
+ *
104
+ * @param weights An object mapping weight keyframe IDs to keyframes.
105
+ */
52
106
  setWeightsById(weights) {
53
107
  this._weightsById = weights;
54
108
  this._weightsDirty = true;
55
109
  }
110
+ /**
111
+ * Getter for sorted weight keyframes by their time values.
112
+ *
113
+ * @returns A sorted array of weight keyframes.
114
+ */
56
115
  get sortedWeights() {
57
116
  if (!this._weightsDirty)
58
117
  return this._weights;
@@ -61,9 +120,25 @@ export class PropertyTrack extends Track {
61
120
  this._weightsDirty = false;
62
121
  return this._weights;
63
122
  }
123
+ /**
124
+ * Computes the fade length for a given path.
125
+ *
126
+ * @param path The path for which to compute the fade length.
127
+ * @returns The fade length, defaulting to 0 if not specified.
128
+ */
64
129
  getFadeLengthForPath(path) {
65
130
  return this.fadeParameters?.time ?? 0;
66
131
  }
132
+ /**
133
+ * Computes the property value for a given path at a specific time.
134
+ * Interpolates between keyframe values based on the specified blend type.
135
+ *
136
+ * @param t The time at which to compute the property.
137
+ * @param p The path of the property to compute.
138
+ * @param valueBefore The initial value of the property before computation.
139
+ * @param parentWeight Optional weight from the parent track.
140
+ * @returns The computed property value.
141
+ */
67
142
  computePathProperty(t, p, valueBefore, parentWeight) {
68
143
  if (this._path.length === 0) {
69
144
  return this._computePathProperty(t, p, valueBefore, parentWeight);
@@ -4,6 +4,13 @@ import { Keyframe } from '../keyframe';
4
4
  import { LayerClip } from '../layerclip';
5
5
  import { Stream, StreamState } from '../stream';
6
6
  import { Track } from './track';
7
+ /**
8
+ * Allows a stream (e.g a video, audio, 3D model animation, anything extending the Stream interface) to be added to a clip.
9
+ *
10
+ * @param animation The associated Animation instance.
11
+ * @param _entity The entity whose stream is being managed.
12
+ * @param _property The property or array of properties targeted by the stream.
13
+ */
7
14
  export declare class StreamTrack extends Track {
8
15
  readonly animation: Animation;
9
16
  private _entity;
@@ -20,24 +27,68 @@ export declare class StreamTrack extends Track {
20
27
  private _lastState;
21
28
  private _lastRate;
22
29
  constructor(animation: Animation, _entity: any, _property: (string | number)[]);
30
+ /**
31
+ * Getter for the list of paths influenced by the track.
32
+ * As this track does not influence any paths, it returns an empty array.
33
+ *
34
+ * @returns An empty array.
35
+ */
23
36
  get influencedPaths(): string[];
37
+ /**
38
+ * Getter for the stream associated with the entity.
39
+ *
40
+ * @returns The Stream associated with the entity, if available.
41
+ */
24
42
  get stream(): Stream | undefined;
25
43
  computePathProperty(t: number, p: string, valueBefore: any, parentWeight?: number): any;
44
+ /**
45
+ * Sets the weight keyframes for the track using an id-indexed object.
46
+ *
47
+ * @param weights An object mapping weight keyframe IDs to keyframes.
48
+ */
26
49
  setWeightsById(weights: {
27
50
  [id: string]: Keyframe;
28
51
  }): void;
52
+ /**
53
+ * Getter for sorted weight keyframes by their time values.
54
+ *
55
+ * @returns A sorted array of weight keyframes.
56
+ */
29
57
  get sortedWeights(): Keyframe[];
58
+ /**
59
+ * Adds a block (StreamTrackEntity) representing a stream state in the timeline.
60
+ *
61
+ * @param k The block to be added.
62
+ */
30
63
  addBlock(k: StreamTrackEntity): void;
64
+ /**
65
+ * Sets the blocks for the track using an id-indexed object.
66
+ *
67
+ * @param blocks An object mapping block IDs to StreamTrackEntities.
68
+ */
31
69
  setBlocksById(weights: {
32
70
  [id: string]: StreamTrackEntity;
33
71
  }): void;
72
+ /**
73
+ * Getter for sorted blocks by their start time.
74
+ *
75
+ * @returns A sorted array of StreamTrackEntities.
76
+ */
34
77
  get sortedBlocks(): StreamTrackEntity[];
78
+ /** @internal */
35
79
  streamPause(isActive: boolean, active: LayerClip | null | undefined): void;
80
+ /** @internal */
36
81
  streamSeek(t: number, resolvedRate: number, isActive: boolean, active: LayerClip | null | undefined): void;
37
82
  private _isPlayingInClip;
38
83
  private _isPlayingInLayerClip;
84
+ /** @internal */
39
85
  streamTick(clipState: StreamState, t: number, rate: number, isActive: boolean, active: LayerClip | null | undefined, force?: boolean, stalled?: boolean, parentWeight?: number): void;
40
86
  private _applyState;
41
87
  private _resolveBlock;
88
+ /**
89
+ * Determines if the track's stream is stalled.
90
+ *
91
+ * @returns A boolean indicating if the stream is stalled.
92
+ */
42
93
  isStalled(): boolean;
43
94
  }
@@ -1,6 +1,13 @@
1
1
  import { StreamState } from '../stream';
2
2
  import { ClipTrack } from './cliptrack';
3
3
  import { resolveClipTimeLoops, Track } from './track';
4
+ /**
5
+ * Allows a stream (e.g a video, audio, 3D model animation, anything extending the Stream interface) to be added to a clip.
6
+ *
7
+ * @param animation The associated Animation instance.
8
+ * @param _entity The entity whose stream is being managed.
9
+ * @param _property The property or array of properties targeted by the stream.
10
+ */
4
11
  export class StreamTrack extends Track {
5
12
  constructor(animation, _entity, _property) {
6
13
  super(animation);
@@ -14,9 +21,20 @@ export class StreamTrack extends Track {
14
21
  this._weightsById = {};
15
22
  this._weightsDirty = false;
16
23
  }
24
+ /**
25
+ * Getter for the list of paths influenced by the track.
26
+ * As this track does not influence any paths, it returns an empty array.
27
+ *
28
+ * @returns An empty array.
29
+ */
17
30
  get influencedPaths() {
18
31
  return [];
19
32
  }
33
+ /**
34
+ * Getter for the stream associated with the entity.
35
+ *
36
+ * @returns The Stream associated with the entity, if available.
37
+ */
20
38
  get stream() {
21
39
  if (!this._stream) {
22
40
  let obj = this._entity;
@@ -32,10 +50,20 @@ export class StreamTrack extends Track {
32
50
  computePathProperty(t, p, valueBefore, parentWeight) {
33
51
  // n/a
34
52
  }
53
+ /**
54
+ * Sets the weight keyframes for the track using an id-indexed object.
55
+ *
56
+ * @param weights An object mapping weight keyframe IDs to keyframes.
57
+ */
35
58
  setWeightsById(weights) {
36
59
  this._weightsById = weights;
37
60
  this._weightsDirty = true;
38
61
  }
62
+ /**
63
+ * Getter for sorted weight keyframes by their time values.
64
+ *
65
+ * @returns A sorted array of weight keyframes.
66
+ */
39
67
  get sortedWeights() {
40
68
  if (!this._weightsDirty)
41
69
  return this._weights;
@@ -44,14 +72,29 @@ export class StreamTrack extends Track {
44
72
  this._weightsDirty = false;
45
73
  return this._weights;
46
74
  }
75
+ /**
76
+ * Adds a block (StreamTrackEntity) representing a stream state in the timeline.
77
+ *
78
+ * @param k The block to be added.
79
+ */
47
80
  addBlock(k) {
48
81
  this._entitiesById[k.id] = k;
49
82
  this._entitiesDirty = true;
50
83
  }
84
+ /**
85
+ * Sets the blocks for the track using an id-indexed object.
86
+ *
87
+ * @param blocks An object mapping block IDs to StreamTrackEntities.
88
+ */
51
89
  setBlocksById(weights) {
52
90
  this._entitiesById = weights;
53
91
  this._entitiesDirty = true;
54
92
  }
93
+ /**
94
+ * Getter for sorted blocks by their start time.
95
+ *
96
+ * @returns A sorted array of StreamTrackEntities.
97
+ */
55
98
  get sortedBlocks() {
56
99
  if (!this._entitiesDirty)
57
100
  return this._entities;
@@ -60,6 +103,7 @@ export class StreamTrack extends Track {
60
103
  this._entitiesDirty = false;
61
104
  return this._entities;
62
105
  }
106
+ /** @internal */
63
107
  streamPause(isActive, active) {
64
108
  if (!isActive && this._isPlayingInLayerClip(active)) {
65
109
  delete this._lastLoopNumber;
@@ -70,6 +114,7 @@ export class StreamTrack extends Track {
70
114
  this.stream?.pause();
71
115
  this._lastState = StreamState.Paused;
72
116
  }
117
+ /** @internal */
73
118
  streamSeek(t, resolvedRate, isActive, active) {
74
119
  if (!isActive && this._isPlayingInLayerClip(active)) {
75
120
  delete this._lastLoopNumber;
@@ -78,12 +123,12 @@ export class StreamTrack extends Track {
78
123
  const blockNow = this._resolveBlock(t, 1);
79
124
  if (!blockNow)
80
125
  return;
81
- const [bt, loopNumber] = resolveClipTimeLoops(t, blockNow.t0, blockNow.s0, blockNow.rate, this.stream?.length?.() ?? Infinity, (resolvedRate * blockNow.rate) < 0, blockNow.t1);
126
+ const [bt, loopNumber] = resolveClipTimeLoops(t, blockNow.t0, blockNow.s0, blockNow.rate, this.stream?.length?.() ?? Infinity, resolvedRate * blockNow.rate < 0, blockNow.t1);
82
127
  this.stream?.seek(bt);
83
128
  this._lastLoopNumber = loopNumber;
84
129
  }
85
130
  _isPlayingInClip(stream, clip) {
86
- for (let s of clip._streamTracks) {
131
+ for (const s of clip._streamTracks) {
87
132
  if (s instanceof StreamTrack && s.stream === stream)
88
133
  return true;
89
134
  if (s instanceof ClipTrack && this._isPlayingInClip(stream, s.clip))
@@ -99,6 +144,7 @@ export class StreamTrack extends Track {
99
144
  return false;
100
145
  return this._isPlayingInClip(stream, layerClip.clip);
101
146
  }
147
+ /** @internal */
102
148
  streamTick(clipState, t, rate, isActive, active, force = false, stalled = false, parentWeight) {
103
149
  if (!isActive && this._isPlayingInLayerClip(active)) {
104
150
  delete this._lastLoopNumber;
@@ -114,7 +160,7 @@ export class StreamTrack extends Track {
114
160
  desiredState = StreamState.Paused;
115
161
  }
116
162
  else {
117
- const [bt, loopNumber] = resolveClipTimeLoops(t, block.t0, block.s0, block.rate, this.stream?.length?.() ?? Infinity, (rate * block.rate) < 0, block.t1);
163
+ const [bt, loopNumber] = resolveClipTimeLoops(t, block.t0, block.s0, block.rate, this.stream?.length?.() ?? Infinity, rate * block.rate < 0, block.t1);
118
164
  if ((t === block.t1 && rate >= +0) || (t === block.t0 && rate < 0)) {
119
165
  desiredState = StreamState.Paused;
120
166
  force = true;
@@ -158,6 +204,11 @@ export class StreamTrack extends Track {
158
204
  }
159
205
  return undefined;
160
206
  }
207
+ /**
208
+ * Determines if the track's stream is stalled.
209
+ *
210
+ * @returns A boolean indicating if the stream is stalled.
211
+ */
161
212
  isStalled() {
162
213
  return this.stream?.isStalled?.() ?? false;
163
214
  }
@@ -1,14 +1,70 @@
1
1
  import { Observable } from '../../observable';
2
2
  import { Animation } from '../animation';
3
3
  import { Keyframe } from '../keyframe';
4
+ /**
5
+ * Abstract base class for animation tracks.
6
+ * Tracks are responsible for managing animated properties and responding to time-based updates.
7
+ *
8
+ * @param anim The associated Animation instance.
9
+ * @param id Optional unique identifier for the track.
10
+ */
4
11
  export declare abstract class Track {
5
12
  readonly id?: string | undefined;
13
+ /** @internal */
6
14
  influencedPathsDirty: Observable<boolean, never>;
7
15
  constructor(anim: Animation, id?: string | undefined);
16
+ /**
17
+ * Abstract getter for the list of paths influenced by the track.
18
+ * Must be implemented by subclasses to return the relevant paths.
19
+ *
20
+ * @returns An array of strings representing the influenced paths.
21
+ */
8
22
  abstract get influencedPaths(): string[];
23
+ /**
24
+ * Abstract method to compute the property value for a given path at a specific time.
25
+ * Must be implemented by subclasses to provide the property computation logic.
26
+ *
27
+ * @param t The time at which to compute the property.
28
+ * @param p The path of the property to compute.
29
+ * @param valueBefore The initial value of the property before computation.
30
+ * @param parentWeight Optional weight from the parent track.
31
+ * @returns The computed property value.
32
+ */
9
33
  abstract computePathProperty(t: number, p: string, valueBefore: any, parentWeight?: number): any;
34
+ /**
35
+ * Determines if the track is stalled. Default implementation returns false.
36
+ *
37
+ * @returns A boolean indicating if the track is stalled.
38
+ */
10
39
  isStalled(): boolean;
11
40
  }
41
+ /**
42
+ * Resolves the interpolated value between two keyframes at a given time.
43
+ *
44
+ * @param t The current time.
45
+ * @param before The keyframe before the current time.
46
+ * @param after The keyframe after the current time, if any.
47
+ * @returns The interpolated value.
48
+ */
12
49
  export declare function resolveKeyframeValue(t: number, before: Keyframe, after: Keyframe | undefined): any;
50
+ /**
51
+ * Finds the keyframes before and after a given time.
52
+ *
53
+ * @param keyframes An array of keyframes.
54
+ * @param t The time for which to find the keyframes.
55
+ * @returns A tuple containing the keyframes before and after the given time.
56
+ */
13
57
  export declare function resolveKeyframes(keyframes: Keyframe[], t: number): [before: Keyframe | undefined, after: Keyframe | undefined];
58
+ /**
59
+ * Resolves the clip time and loop number for a given time within a clip.
60
+ *
61
+ * @param t The current time.
62
+ * @param t0 The start time of the clip.
63
+ * @param s0 The initial state time of the clip.
64
+ * @param rate The rate of playback.
65
+ * @param length The length of the clip.
66
+ * @param timeBackwards A boolean indicating if time is moving backwards.
67
+ * @param t1 Optional end time of the clip.
68
+ * @returns A tuple containing the resolved clip time and loop number.
69
+ */
14
70
  export declare function resolveClipTimeLoops(t: number, t0: number, s0: number, rate: number, length: number, timeBackwards: boolean, t1?: number): [ct: number, loop: number];
@@ -1,23 +1,51 @@
1
1
  import { Observable } from '../../observable';
2
2
  import { computeEasing } from '../bezier';
3
3
  import { interpolate } from '../interpolate';
4
+ /**
5
+ * Abstract base class for animation tracks.
6
+ * Tracks are responsible for managing animated properties and responding to time-based updates.
7
+ *
8
+ * @param anim The associated Animation instance.
9
+ * @param id Optional unique identifier for the track.
10
+ */
4
11
  export class Track {
5
12
  constructor(anim, id) {
6
13
  this.id = id;
14
+ /** @internal */
7
15
  this.influencedPathsDirty = new Observable(false);
8
16
  if (id)
9
17
  anim.trackByID.set(id, this);
10
18
  }
19
+ /**
20
+ * Determines if the track is stalled. Default implementation returns false.
21
+ *
22
+ * @returns A boolean indicating if the track is stalled.
23
+ */
11
24
  isStalled() {
12
25
  return false;
13
26
  }
14
27
  }
28
+ /**
29
+ * Resolves the interpolated value between two keyframes at a given time.
30
+ *
31
+ * @param t The current time.
32
+ * @param before The keyframe before the current time.
33
+ * @param after The keyframe after the current time, if any.
34
+ * @returns The interpolated value.
35
+ */
15
36
  export function resolveKeyframeValue(t, before, after) {
16
37
  if (!after || !before.easing)
17
38
  return before.v;
18
39
  const tprop = computeEasing((t - before.t) / (after.t - before.t), before.easing);
19
40
  return interpolate(before.v, after.v, tprop);
20
41
  }
42
+ /**
43
+ * Finds the keyframes before and after a given time.
44
+ *
45
+ * @param keyframes An array of keyframes.
46
+ * @param t The time for which to find the keyframes.
47
+ * @returns A tuple containing the keyframes before and after the given time.
48
+ */
21
49
  export function resolveKeyframes(keyframes, t) {
22
50
  let keyframeBefore;
23
51
  let keyframeAfter;
@@ -34,6 +62,18 @@ export function resolveKeyframes(keyframes, t) {
34
62
  }
35
63
  return [keyframeBefore, keyframeAfter];
36
64
  }
65
+ /**
66
+ * Resolves the clip time and loop number for a given time within a clip.
67
+ *
68
+ * @param t The current time.
69
+ * @param t0 The start time of the clip.
70
+ * @param s0 The initial state time of the clip.
71
+ * @param rate The rate of playback.
72
+ * @param length The length of the clip.
73
+ * @param timeBackwards A boolean indicating if time is moving backwards.
74
+ * @param t1 Optional end time of the clip.
75
+ * @returns A tuple containing the resolved clip time and loop number.
76
+ */
37
77
  export function resolveClipTimeLoops(t, t0, s0, rate, length, timeBackwards, t1 = Infinity) {
38
78
  if (length === 0)
39
79
  return [0, 0];
package/lib/behavior.d.ts CHANGED
@@ -1,11 +1,36 @@
1
1
  import { Component } from './component';
2
2
  import { ContextManager } from './context';
3
3
  import { Entity } from './entity';
4
+ /**
5
+ * Represents a factory function for creating new Behavior instances.
6
+ *
7
+ * @typeParam BehaviorType - The specific type of Behavior to be constructed.
8
+ * @typeParam K - The type of Component associated with the Behavior.
9
+ * @returns A new instance of the specified BehaviorType.
10
+ */
4
11
  export type BehaviorConstructor<BehaviorType = Behavior, K extends Component = Component> = BehaviorType extends Behavior<K> ? new (contextManager: ContextManager, instance: K, ...args: any[]) => BehaviorType : never;
12
+ /**
13
+ * Extracts the constructor properties of a specified Behavior type.
14
+ *
15
+ * @typeParam BehaviorType - The Behavior type for which the constructor properties are to be extracted.
16
+ * @returns The type of the component that the specified Behavior type is associated with.
17
+ */
5
18
  export type ConstructorPropsOfBehavior<BehaviorType> = BehaviorType extends Behavior<infer R> ? R : never;
19
+ /**
20
+ * Defines a mapping of behavior IDs to their respective properties.
21
+ */
6
22
  export type BehaviorConstructorProps = {
7
23
  [id: string]: unknown;
8
24
  };
25
+ /**
26
+ * Base class for all behaviors.
27
+ *
28
+ * Behaviors are a versatile way to add interactivity to your experience. They’re often used to:
29
+ * - Listen to the events emitted by a node and then perform an action, such as playing an animation or calling a function in a context.
30
+ * - Change the behavior or properties of the node they're attached to.
31
+ *
32
+ * @link [custom-behaviors](https://docs.zap.works/mattercraft/scripting/custom-behaviors/)
33
+ */
9
34
  export declare class Behavior<InstanceType extends Component = Component> extends Entity {
10
35
  readonly instance: InstanceType;
11
36
  /**
@@ -18,5 +43,17 @@ export declare class Behavior<InstanceType extends Component = Component> extend
18
43
  private _updateEnabledResolved;
19
44
  dispose(): never;
20
45
  }
46
+ /**
47
+ * Checks if a specified Behavior should run at design time.
48
+ *
49
+ * @param b - The BehaviorConstructor to check.
50
+ * @returns A boolean indicating whether the behavior should run at design time.
51
+ */
21
52
  export declare function shouldBehaviorRunAtDesignTime(b: BehaviorConstructor): boolean;
53
+ /**
54
+ * Registers a Behavior to run at design time.
55
+ *
56
+ * @param b - The BehaviorConstructor to register.
57
+ * @returns The updated Set containing all registered BehaviorConstructors.
58
+ */
22
59
  export declare function registerBehaviorRunAtDesignTime(b: BehaviorConstructor): Set<new (contextManager: ContextManager, instance: Component<any, import("./component").ConstructorProps>, ...args: any[]) => Behavior<Component<any, import("./component").ConstructorProps>>>;