laymur 0.26.0 → 0.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (134) hide show
  1. package/README.md +79 -35
  2. package/dist/core/constraints/UICustomConstraint.d.ts +1 -1
  3. package/dist/core/constraints/UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js +1 -1
  4. package/dist/core/constraints/UIVerticalInterpolationConstraint/UIVerticalInterpolationConstraint.js +1 -1
  5. package/dist/core/constraints/builders/UIConstraint2DBuilder.d.ts +2 -3
  6. package/dist/core/elements/UIAnimatedImage/UIAnimatedImage.d.ts +2 -2
  7. package/dist/core/elements/UIAnimatedImage/UIAnimatedImage.js +24 -12
  8. package/dist/core/elements/UIDummy/UIDummy.Internal.d.ts +10 -0
  9. package/dist/core/elements/UIDummy/UIDummy.d.ts +42 -5
  10. package/dist/core/elements/UIDummy/UIDummy.js +119 -25
  11. package/dist/core/elements/UIElement/UIElement.Internal.d.ts +1 -1
  12. package/dist/core/elements/UIElement/UIElement.d.ts +14 -0
  13. package/dist/core/elements/UIElement/UIElement.js +34 -3
  14. package/dist/core/elements/UIGraphics/UIGraphics.Internal.d.ts +1 -1
  15. package/dist/core/elements/UIGraphics/UIGraphics.d.ts +1 -1
  16. package/dist/core/elements/UIGraphics/UIGraphics.js +2 -2
  17. package/dist/core/elements/UIImage/UIImage.d.ts +2 -2
  18. package/dist/core/elements/UIImage/UIImage.js +10 -8
  19. package/dist/core/elements/UINineSlice/UINineSlice.d.ts +4 -4
  20. package/dist/core/elements/UINineSlice/UINineSlice.js +11 -9
  21. package/dist/core/elements/UIProgress/UIProgress.d.ts +2 -2
  22. package/dist/core/elements/UIProgress/UIProgress.js +15 -10
  23. package/dist/core/elements/UIScene/UIScene.Internal.d.ts +1 -1
  24. package/dist/core/elements/UIScene/UIScene.d.ts +3 -2
  25. package/dist/core/elements/UIScene/UIScene.js +18 -12
  26. package/dist/core/elements/UIText/UIText.Measuring.d.ts +1 -1
  27. package/dist/core/elements/UIText/UIText.d.ts +3 -3
  28. package/dist/core/elements/UIText/UIText.js +6 -6
  29. package/dist/core/index.d.ts +44 -41
  30. package/dist/core/index.js +12 -9
  31. package/dist/core/layers/UILayer/UILayer.d.ts +40 -4
  32. package/dist/core/layers/UILayer/UILayer.js +70 -9
  33. package/dist/core/layers/UIViewportLayer/UIViewportLayer.Internal.d.ts +27 -0
  34. package/dist/core/layers/{UIFullscreenLayer/UIFullscreenLayer.Internal.js → UIViewportLayer/UIViewportLayer.Internal.js} +1 -1
  35. package/dist/core/layers/UIViewportLayer/UIViewportLayer.d.ts +98 -0
  36. package/dist/core/layers/UIViewportLayer/UIViewportLayer.js +251 -0
  37. package/dist/core/miscellaneous/asserts.d.ts +14 -0
  38. package/dist/core/miscellaneous/asserts.js +28 -0
  39. package/dist/core/miscellaneous/canvas.js +7 -2
  40. package/dist/core/miscellaneous/color/UIColor.js +4 -2
  41. package/dist/core/miscellaneous/computeTransform.d.ts +12 -0
  42. package/dist/core/miscellaneous/computeTransform.js +20 -0
  43. package/dist/core/miscellaneous/context-monitor/UIContextMonitor.d.ts +1 -0
  44. package/dist/core/miscellaneous/context-monitor/UIContextMonitor.js +60 -0
  45. package/dist/core/miscellaneous/generic-plane/UIGenericInstancedPlane/UIGenericInstancedPlane.js +1 -1
  46. package/dist/core/miscellaneous/resize-policy/UIResizePolicy.d.ts +7 -4
  47. package/dist/core/miscellaneous/resize-policy/UIResizePolicy.js +13 -6
  48. package/dist/core/miscellaneous/resize-policy/UIResizePolicyCover.js +2 -2
  49. package/dist/core/miscellaneous/resize-policy/UIResizePolicyCross.js +2 -2
  50. package/dist/core/miscellaneous/resize-policy/UIResizePolicyCrossInverted.js +2 -2
  51. package/dist/core/miscellaneous/resize-policy/UIResizePolicyFit.js +2 -2
  52. package/dist/core/miscellaneous/resize-policy/UIResizePolicyFixedHeight.js +2 -2
  53. package/dist/core/miscellaneous/resize-policy/UIResizePolicyFixedWidth.js +2 -2
  54. package/dist/core/miscellaneous/text-style/UITextStyle.js +2 -2
  55. package/dist/core/miscellaneous/texture/UITextureView.d.ts +4 -1
  56. package/dist/core/miscellaneous/texture/UITextureView.js +10 -7
  57. package/dist/core/miscellaneous/viewport/UIElementViewport.d.ts +31 -0
  58. package/dist/core/miscellaneous/viewport/UIElementViewport.js +54 -0
  59. package/dist/core/miscellaneous/viewport/UIViewport.d.ts +37 -0
  60. package/dist/core/miscellaneous/viewport/UIViewport.js +31 -0
  61. package/dist/core/miscellaneous/viewport/UIWindowViewport.d.ts +13 -0
  62. package/dist/core/miscellaneous/viewport/UIWindowViewport.js +25 -0
  63. package/dist/core/miscellaneous/webglCapabilities.js +61 -55
  64. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.Internal.d.ts +36 -5
  65. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.d.ts +23 -2
  66. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.js +153 -15
  67. package/dist/core/wrappers/UISceneWrapper/UISceneWrapper.Internal.d.ts +1 -1
  68. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.Internal.d.ts +2 -0
  69. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.d.ts +3 -0
  70. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.js +36 -16
  71. package/dist/debug/UIAspectDebug.js +4 -0
  72. package/dist/debug/UIHeightDebug.js +4 -0
  73. package/dist/debug/UIHorizontalDistanceDebug.js +5 -0
  74. package/dist/debug/UIHorizontalInterpolationDebug.js +5 -0
  75. package/dist/debug/UILayerDebug.d.ts +7 -0
  76. package/dist/debug/UILayerDebug.js +21 -0
  77. package/dist/debug/UIVerticalDistanceDebug.js +5 -0
  78. package/dist/debug/UIVerticalInterpolationDebug.js +5 -0
  79. package/dist/debug/UIWidthDebug.js +4 -0
  80. package/dist/debug/index.d.ts +1 -1
  81. package/dist/particles/behaviorModules/UIBehaviorDirectionalGravity.d.ts +1 -1
  82. package/dist/particles/behaviorModules/UIBehaviorModule.d.ts +5 -1
  83. package/dist/particles/behaviorModules/UIBehaviorPointGravity.d.ts +2 -2
  84. package/dist/particles/behaviorModules/UIBehaviorPointGravity.js +13 -10
  85. package/dist/particles/behaviorModules/UIBehaviorScaleOscillation.d.ts +1 -1
  86. package/dist/particles/behaviorModules/UIBehaviorScaleOscillation.js +6 -4
  87. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.d.ts +1 -1
  88. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.js +4 -3
  89. package/dist/particles/behaviorModules/UIBehaviorTorqueDamping.d.ts +2 -2
  90. package/dist/particles/behaviorModules/UIBehaviorTorqueDamping.js +8 -8
  91. package/dist/particles/behaviorModules/UIBehaviorTorqueNoise.d.ts +4 -3
  92. package/dist/particles/behaviorModules/UIBehaviorTorqueNoise.js +8 -5
  93. package/dist/particles/behaviorModules/UIBehaviorVelocityDamping.d.ts +1 -1
  94. package/dist/particles/behaviorModules/UIBehaviorVelocityDamping.js +8 -8
  95. package/dist/particles/behaviorModules/UIBehaviorVelocityNoise.d.ts +7 -5
  96. package/dist/particles/behaviorModules/UIBehaviorVelocityNoise.js +12 -8
  97. package/dist/particles/elements/UIEmitter.Internal.d.ts +15 -2
  98. package/dist/particles/elements/UIEmitter.Internal.js +6 -0
  99. package/dist/particles/elements/UIEmitter.d.ts +19 -3
  100. package/dist/particles/elements/UIEmitter.js +100 -54
  101. package/dist/particles/index.d.ts +3 -2
  102. package/dist/particles/index.js +1 -0
  103. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.d.ts +8 -2
  104. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.js +16 -11
  105. package/dist/particles/instancedParticle/UIInstancedParticle.d.ts +7 -0
  106. package/dist/particles/instancedParticle/UIInstancedParticle.js +37 -2
  107. package/dist/particles/miscellaneous/miscellaneous.d.ts +34 -0
  108. package/dist/particles/miscellaneous/miscellaneous.js +72 -0
  109. package/dist/particles/renderingModules/UIRenderingColorOverLife.js +2 -2
  110. package/dist/particles/renderingModules/UIRenderingColorOverVelocity.js +2 -3
  111. package/dist/particles/renderingModules/UIRenderingModule.d.ts +3 -2
  112. package/dist/particles/renderingModules/UIRenderingModule.js +2 -1
  113. package/dist/particles/renderingModules/UIRenderingTexture.js +2 -1
  114. package/dist/particles/shaders/UIRenderingColorOverLife.d.ts +1 -2
  115. package/dist/particles/shaders/UIRenderingColorOverLife.js +5 -3
  116. package/dist/particles/shaders/UIRenderingColorOverVelocity.d.ts +1 -9
  117. package/dist/particles/shaders/UIRenderingColorOverVelocity.js +6 -13
  118. package/dist/particles/spawnModules/UISpawnModule.d.ts +5 -2
  119. package/dist/particles/spawnModules/UISpawnRandomLifetime.d.ts +2 -2
  120. package/dist/particles/spawnModules/UISpawnRandomLifetime.js +5 -5
  121. package/dist/particles/spawnModules/UISpawnRandomRotation.d.ts +1 -1
  122. package/dist/particles/spawnModules/UISpawnRandomRotation.js +5 -3
  123. package/dist/particles/spawnModules/UISpawnRandomScale.d.ts +1 -1
  124. package/dist/particles/spawnModules/UISpawnRandomScale.js +4 -3
  125. package/dist/particles/spawnModules/UISpawnRandomTorque.d.ts +1 -1
  126. package/dist/particles/spawnModules/UISpawnRandomTorque.js +5 -3
  127. package/dist/particles/spawnModules/UISpawnRandomVelocity.d.ts +1 -1
  128. package/dist/particles/spawnModules/UISpawnRandomVelocity.js +6 -4
  129. package/dist/particles/spawnModules/UISpawnRectangle.d.ts +1 -1
  130. package/dist/particles/spawnModules/UISpawnRectangle.js +6 -4
  131. package/package.json +13 -4
  132. package/dist/core/layers/UIFullscreenLayer/UIFullscreenLayer.Internal.d.ts +0 -21
  133. package/dist/core/layers/UIFullscreenLayer/UIFullscreenLayer.d.ts +0 -63
  134. package/dist/core/layers/UIFullscreenLayer/UIFullscreenLayer.js +0 -144
package/README.md CHANGED
@@ -15,14 +15,14 @@
15
15
 
16
16
  ## Features
17
17
 
18
- * **Cassowary solver** - constraint-based layouts via `@lume/kiwi`
19
- * **Orientation-aware** - define portrait and landscape rules in one layout, solver toggles automatically
20
- * **Micro-transforms** - transforms (scale, rotation, offset) that bypass the solver; input follows them
21
- * **Masks** - analytic shader masks (rectangle, rounded rectangle, ellipse) with soft edges and input clipping
22
- * **Color adjustment** - per-element hue/saturation/lightness and additive blend mode
23
- * **Resize policies** - Cover, Fit, FixedHeight, FixedWidth, Cross strategies
24
- * **Modular particles** - separate `laymur/particles` entry point, import only if needed
25
- * **Debug overlay** - separate `laymur/debug` entry point, constraint visualization
18
+ - **Cassowary solver** - constraint-based layouts via `@lume/kiwi`
19
+ - **Orientation-aware** - define portrait and landscape rules in one layout, solver toggles automatically
20
+ - **Micro-transforms** - transforms (scale, rotation, offset) that bypass the solver; input follows them
21
+ - **Masks** - analytic shader masks (rectangle, rounded rectangle, ellipse) with soft edges and input clipping
22
+ - **Color adjustment** - per-element hue/saturation/lightness and additive blend mode
23
+ - **Resize policies** - Cover, Fit, FixedHeight, FixedWidth, Cross strategies
24
+ - **Modular particles** - separate `laymur/particles` entry point, import only if needed
25
+ - **Debug overlay** - separate `laymur/debug` entry point, constraint visualization
26
26
 
27
27
  ## Installation
28
28
 
@@ -32,10 +32,29 @@ npm install laymur
32
32
 
33
33
  Peer Dependencies:
34
34
 
35
- * `three` (>=0.157.0 <0.180.0)
36
- * `@lume/kiwi` (^0.4.4)
37
- * `ferrsign` (^0.0.4)
38
- * `fast-simplex-noise` (^4.0.0) - only required when using `laymur/particles`
35
+ - `three` (>=0.157.0 <0.180.0)
36
+ - `@lume/kiwi` (^0.4.4)
37
+ - `ferrsign` (^0.0.4)
38
+ - `fast-simplex-noise` (^4.0.0) - only required when using `laymur/particles`
39
+
40
+ ### Development checks
41
+
42
+ Laymur validates arguments (finite numbers, ranges, destroyed objects) unless
43
+ `process.env.NODE_ENV` is `"production"`. A bundler replaces that expression with a string, and
44
+ the minifier then removes the checks from the production build:
45
+
46
+ - Vite and webpack set it for you (`"production"` in production builds).
47
+ - esbuild: `--define:process.env.NODE_ENV='"production"'`.
48
+ - Rollup: `@rollup/plugin-replace` with `"process.env.NODE_ENV": JSON.stringify("production")`.
49
+
50
+ Without a bundler (an import map, a CDN), `process` does not exist: define it before importing
51
+ laymur.
52
+
53
+ ```html
54
+ <script>
55
+ globalThis.process = { env: { NODE_ENV: "development" } }; // or "production"
56
+ </script>
57
+ ```
39
58
 
40
59
  ## Visual Editor & Live Examples
41
60
 
@@ -45,36 +64,45 @@ Check out visual editor and interactive examples at:
45
64
 
46
65
  **[EXAMPLES](https://jango-git.github.io/laymur/examples/index.html)**
47
66
 
48
-
49
67
  ## Core Concepts
50
68
 
51
69
  ### 1. Layers & Elements
52
70
 
53
- `UIFullscreenLayer` manages coordinate system, canvas scaling, and input. All UI elements attach to a layer.
71
+ `UIViewportLayer` manages coordinate system, canvas scaling, and input. All UI elements attach to a layer.
54
72
 
55
73
  ```typescript
56
- import { UIFullscreenLayer, UIImage, UIMode, UIResizePolicyFixedHeight } from 'laymur';
74
+ import { UIViewportLayer, UIImage, UIMode, UIResizePolicyFixedHeight } from "laymur";
57
75
 
58
- const layer = new UIFullscreenLayer({
59
- name: "MainHUD",
76
+ const layer = new UIViewportLayer({
77
+ name: "MainHUD",
60
78
  mode: UIMode.VISIBLE,
61
- resizePolicy: new UIResizePolicyFixedHeight(1080, 1920)
79
+ resizePolicy: new UIResizePolicyFixedHeight(1080, 1920),
62
80
  });
63
81
  ```
64
82
 
83
+ The layer covers the whole window by default. For a canvas that does not fill the window (an editor preview, a page with margins), pass the area it covers; the layer then takes its size and the origin of input positions from that element:
84
+
85
+ ```typescript
86
+ import { UIElementViewport, UIViewportLayer } from "laymur";
87
+
88
+ const viewport = new UIElementViewport(renderer.domElement);
89
+ const layer = new UIViewportLayer({ viewport });
90
+ // The viewport belongs to the caller and may serve several layers: destroy it after them
91
+ ```
92
+
65
93
  ### 2. Constraint System
66
94
 
67
95
  Cassowary-based constraint solver. Supports priorities, element relationships, orientation-specific rules, and inequality relations.
68
96
 
69
97
  ```typescript
70
- import {
71
- UIHorizontalDistanceConstraint,
98
+ import {
99
+ UIHorizontalDistanceConstraint,
72
100
  UIVerticalProportionConstraint,
73
101
  UIAspectConstraint,
74
- UIOrientation,
102
+ UIOrientation,
75
103
  UIPriority,
76
- UIRelation
77
- } from 'laymur';
104
+ UIRelation,
105
+ } from "laymur";
78
106
 
79
107
  // Lock aspect ratio
80
108
  new UIAspectConstraint(element);
@@ -119,7 +147,7 @@ button.micro.affectsInput = false;
119
147
  `UIMask` follows the rectangle of a source element or of the layer, so it is laid out with constraints. Masks are computed in the shader: edges can be soft and masked elements keep batching together.
120
148
 
121
149
  ```typescript
122
- import { UIDummy, UIMask, UIMaskShape } from 'laymur';
150
+ import { UIDummy, UIMask, UIMaskShape } from "laymur";
123
151
 
124
152
  // Scroll view: content moves, the viewport stays
125
153
  const viewport = new UIDummy(layer);
@@ -132,7 +160,11 @@ for (const item of items) {
132
160
  avatar.mask = new UIMask(avatarFrame, { shape: UIMaskShape.ELLIPSE, softness: 2 });
133
161
 
134
162
  // Tutorial spotlight: taps inside the hole reach the button below the overlay
135
- dimOverlay.mask = new UIMask(ctaButton, { shape: UIMaskShape.ELLIPSE, inverted: true, softness: 40 });
163
+ dimOverlay.mask = new UIMask(ctaButton, {
164
+ shape: UIMaskShape.ELLIPSE,
165
+ inverted: true,
166
+ softness: 40,
167
+ });
136
168
  ```
137
169
 
138
170
  A mask also clips input and lives as long as its source. Particles are not clipped; three.js materials of your own can be, through `UIMaskMaterialPatch`.
@@ -142,11 +174,11 @@ A mask also clips input and lives as long as its source. Particles are not clipp
142
174
  Every element supports per-element color tweaks that run in the shader, independent of the layout solver.
143
175
 
144
176
  ```typescript
145
- import { UIBlendMode } from 'laymur';
177
+ import { UIBlendMode } from "laymur";
146
178
 
147
- element.hue = 180; // hue shift in degrees
179
+ element.hue = 180; // hue shift in degrees
148
180
  element.saturation = 0.5; // multiplier (1 = unchanged, 0 = grayscale)
149
- element.lightness = 0.1; // offset (0 = unchanged)
181
+ element.lightness = 0.1; // offset (0 = unchanged)
150
182
 
151
183
  // Additive blending (light accumulation), only affects BLEND transparency
152
184
  element.blendMode = UIBlendMode.ADDITIVE;
@@ -157,14 +189,26 @@ element.blendMode = UIBlendMode.ADDITIVE;
157
189
  Modular pipeline: Spawn -> Behavior -> Rendering.
158
190
 
159
191
  ```typescript
160
- import { UIEmitter, UISpawnRectangle, UIBehaviorDirectionalGravity, UIRenderingTexture } from 'laymur/particles';
161
-
192
+ import {
193
+ UIEmitter,
194
+ UISpawnRectangle,
195
+ UISpawnRandomLifetime,
196
+ UISpawnRandomScale,
197
+ UIBehaviorDirectionalGravity,
198
+ UIRenderingTexture,
199
+ } from "laymur/particles";
200
+
201
+ // Unset, a particle lives 1 second at scale 1 (1 px)
162
202
  const emitter = new UIEmitter(
163
203
  layer,
164
- [new UISpawnRectangle([-500, 0], [500, 0])],
204
+ [
205
+ new UISpawnRectangle([-500, 0], [500, 0]),
206
+ new UISpawnRandomLifetime([2, 3]), // seconds
207
+ new UISpawnRandomScale([24, 48], particleTexture), // px, aspect from the texture
208
+ ],
165
209
  [new UIBehaviorDirectionalGravity({ x: 0, y: 100 })],
166
210
  [new UIRenderingTexture(particleTexture)],
167
- { expectedCapacity: 1024 } // Pre-allocation hint, not a hard limit
211
+ { expectedCapacity: 1024 }, // Pre-allocation hint, not a hard limit
168
212
  );
169
213
 
170
214
  emitter.play(60); // particles/sec
@@ -177,7 +221,7 @@ emitter.play(60); // particles/sec
177
221
  `UILayerDebug` automatically tracks all constraints on a layer and creates the corresponding overlays. Individual constraint types can be toggled on/off.
178
222
 
179
223
  ```typescript
180
- import { UILayerDebug } from 'laymur/debug';
224
+ import { UILayerDebug } from "laymur/debug";
181
225
 
182
226
  const debug = new UILayerDebug(layer, {
183
227
  showAspect: true,
@@ -204,7 +248,7 @@ Most commonly used exports (not exhaustive):
204
248
 
205
249
  ### Core
206
250
 
207
- UIFullscreenLayer, UIImage, UIAnimatedImage, UIText, UINineSlice, UIProgress, UIMask
251
+ UIViewportLayer, UIImage, UIAnimatedImage, UIText, UINineSlice, UIProgress, UIMask
208
252
 
209
253
  ### Constraints
210
254
 
@@ -212,7 +256,7 @@ UIAspectConstraint, UIHorizontalDistanceConstraint, UIVerticalDistanceConstraint
212
256
 
213
257
  ### Extension Points
214
258
 
215
- UIElement, UIArea, UIResizePolicy, UIProgressMaskFunction, UIMaskMaterialPatch, UIAffineMatrix3
259
+ UIElement, UIArea, UIResizePolicy, UIViewport, UIProgressMaskFunction, UIMaskMaterialPatch, UIAffineMatrix3
216
260
 
217
261
  UIRenderingModule, UISpawnModule, UIBehaviorModule (laymur/particles)
218
262
 
@@ -1,7 +1,7 @@
1
1
  import type { UILayer } from "../layers/UILayer/UILayer.js";
2
2
  import type { UIExpression } from "../miscellaneous/UIExpression.js";
3
- import { UISingleParameterConstraint } from "./UISingleParameterConstraint/UISingleParameterConstraint.js";
4
3
  import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint/UISingleParameterConstraint.Internal.js";
4
+ import { UISingleParameterConstraint } from "./UISingleParameterConstraint/UISingleParameterConstraint.js";
5
5
  /** Constraint with custom LHS and RHS expressions */
6
6
  export declare class UICustomConstraint extends UISingleParameterConstraint {
7
7
  /** Solver constraint descriptor */
@@ -31,7 +31,7 @@ export class UIHorizontalInterpolationConstraint extends UISingleParameterConstr
31
31
  this.b = b;
32
32
  this.c = c;
33
33
  this.anchorAInternal = anchorA;
34
- this.anchorBInternal = anchorA;
34
+ this.anchorBInternal = anchorB;
35
35
  this.anchorCInternal = options.anchorC ?? DEFAULT_ANCHOR;
36
36
  this.tInternal = options.t ?? DEFAULT_T;
37
37
  this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
@@ -31,7 +31,7 @@ export class UIVerticalInterpolationConstraint extends UISingleParameterConstrai
31
31
  this.b = b;
32
32
  this.c = c;
33
33
  this.anchorAInternal = anchorA;
34
- this.anchorBInternal = anchorA;
34
+ this.anchorBInternal = anchorB;
35
35
  this.anchorCInternal = options.anchorC ?? DEFAULT_ANCHOR;
36
36
  this.tInternal = options.t ?? DEFAULT_T;
37
37
  this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
@@ -1,5 +1,4 @@
1
- import type { UIElement } from "../../elements/UIElement/UIElement.js";
2
- import type { UIPlaneElement, UIPointElement } from "../../miscellaneous/shared.js";
1
+ import type { UILayerElement, UIPlaneElement, UIPointElement } from "../../miscellaneous/shared.js";
3
2
  import { UIHeightConstraint } from "../UIHeightConstraint/UIHeightConstraint.js";
4
3
  import { UIHorizontalDistanceConstraint } from "../UIHorizontalDistanceConstraint/UIHorizontalDistanceConstraint.js";
5
4
  import { UIHorizontalInterpolationConstraint } from "../UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js";
@@ -17,7 +16,7 @@ export declare class UIConstraint2DBuilder {
17
16
  * @param options Size configuration for both axes
18
17
  * @returns Width and height constraints
19
18
  */
20
- static size(element: UIElement, options?: Partial<UIConstraintSize2DOptions>): UIConstraint2DResult<UIWidthConstraint, UIHeightConstraint>;
19
+ static size(element: UIPlaneElement & UILayerElement, options?: Partial<UIConstraintSize2DOptions>): UIConstraint2DResult<UIWidthConstraint, UIHeightConstraint>;
21
20
  /**
22
21
  * Creates horizontal and vertical distance constraints.
23
22
  * @param a First element
@@ -1,10 +1,10 @@
1
1
  import type { FerrsignView0 } from "ferrsign";
2
2
  import type { WebGLRenderer } from "three";
3
3
  import type { UILayer } from "../../layers/UILayer/UILayer.js";
4
- import { UIColor } from "../../miscellaneous/color/UIColor.js";
5
4
  import type { UIColorConfig } from "../../miscellaneous/color/UIColor.Internal.js";
6
- import { UITextureView } from "../../miscellaneous/texture/UITextureView.js";
5
+ import { UIColor } from "../../miscellaneous/color/UIColor.js";
7
6
  import type { UITextureConfig } from "../../miscellaneous/texture/UITextureView.Internal.js";
7
+ import { UITextureView } from "../../miscellaneous/texture/UITextureView.js";
8
8
  import { UIElement } from "../UIElement/UIElement.js";
9
9
  import type { UIAnimatedImageOptions } from "./UIAnimatedImage.Internal.js";
10
10
  import { UIAnimatedImageLoopMode } from "./UIAnimatedImage.Internal.js";
@@ -1,7 +1,7 @@
1
1
  import { Ferrsign0 } from "ferrsign";
2
2
  import { assertValidNumber, assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
3
3
  import { UIColor } from "../../miscellaneous/color/UIColor.js";
4
- import { computeTrimmedTransformMatrix } from "../../miscellaneous/computeTransform.js";
4
+ import { computeTrimmedTransformMatrix, scaleTrim } from "../../miscellaneous/computeTransform.js";
5
5
  import { UITextureView } from "../../miscellaneous/texture/UITextureView.js";
6
6
  import source from "../../shaders/UIImage.js";
7
7
  import { UIElement } from "../UIElement/UIElement.js";
@@ -18,11 +18,16 @@ export class UIAnimatedImage extends UIElement {
18
18
  * @param options - Configuration options
19
19
  */
20
20
  constructor(layer, sequence, options = {}) {
21
+ assertNonEmptySequence(sequence, "UIAnimatedImage.constructor.sequence");
21
22
  const color = new UIColor(options.color);
22
23
  const uiTextures = sequence.map((textureConfig) => new UITextureView(textureConfig));
23
24
  const frame = uiTextures[0];
24
- options.width = options.width ?? frame.width;
25
- options.height = options.height ?? frame.height;
25
+ // A copy: the caller may pass the same options to several elements
26
+ options = {
27
+ ...options,
28
+ width: options.width ?? frame.width,
29
+ height: options.height ?? frame.height,
30
+ };
26
31
  const textureTransform = frame.calculateUVTransform();
27
32
  super(layer, source, {
28
33
  texture: frame.texture,
@@ -104,22 +109,27 @@ export class UIAnimatedImage extends UIElement {
104
109
  }
105
110
  /** Replaces animation frames. Stops playback. */
106
111
  set sequence(sequence) {
112
+ assertNonEmptySequence(sequence, "UIAnimatedImage.sequence");
107
113
  this.stop();
108
- this.unsubscribeSequenceEvents();
109
114
  const newLength = sequence.length;
110
115
  const currentLength = this.sequenceInternal.length;
116
+ // Kept subscribed while set, so that the element follows the size of the new first frame
111
117
  for (let i = 0; i < Math.min(newLength, currentLength); i++) {
112
118
  this.sequenceInternal[i].set(sequence[i]);
113
119
  }
114
120
  if (newLength < currentLength) {
121
+ for (let i = newLength; i < currentLength; i++) {
122
+ this.sequenceInternal[i].signalDimensionsChanged.off(this.onTextureDimensionsChanged);
123
+ }
115
124
  this.sequenceInternal.length = newLength;
116
125
  }
117
126
  else if (newLength > currentLength) {
118
127
  for (let i = currentLength; i < newLength; i++) {
119
- this.sequenceInternal.push(new UITextureView(sequence[i]));
128
+ const frame = new UITextureView(sequence[i]);
129
+ frame.signalDimensionsChanged.on(this.onTextureDimensionsChanged);
130
+ this.sequenceInternal.push(frame);
120
131
  }
121
132
  }
122
- this.subscribeSequenceEvents();
123
133
  }
124
134
  /** Playback speed multiplier. Can be negative for reverse playback. */
125
135
  set timeScale(value) {
@@ -229,18 +239,15 @@ export class UIAnimatedImage extends UIElement {
229
239
  if (properties) {
230
240
  this.sceneWrapper.setProperties(this.planeHandler, properties);
231
241
  }
232
- const isTransformDirty = this.currentFrameIndexDirty ||
233
- this.micro.dirty ||
234
- frame.trimDirty ||
235
- this.inputWrapper.dirty ||
236
- this.solverWrapper.dirty;
242
+ const isTransformDirty = this.currentFrameIndexDirty || this.micro.dirty || frame.trimDirty || this.placementDirty;
237
243
  if (isTransformDirty) {
238
244
  const micro = this.micro;
239
- const textureTrim = frame.trim;
245
+ const textureTrim = scaleTrim(frame.trim, this.width, this.height, frame.width, frame.height);
240
246
  this.sceneWrapper.setTransform(this.planeHandler, computeTrimmedTransformMatrix(this.x, this.y, this.width, this.height, this.renderDepth, micro.x, micro.y, micro.anchorX, micro.anchorY, micro.scaleX, micro.scaleY, micro.rotation, micro.anchorMode, textureTrim.left, textureTrim.right, textureTrim.top, textureTrim.bottom));
241
247
  this.currentFrameIndexDirty = false;
242
248
  this.micro.setDirtyFalse();
243
249
  frame.setTrimDirtyFalse();
250
+ this.setPlacementDirtyFalse();
244
251
  }
245
252
  }
246
253
  subscribeSequenceEvents() {
@@ -254,3 +261,8 @@ export class UIAnimatedImage extends UIElement {
254
261
  }
255
262
  }
256
263
  }
264
+ function assertNonEmptySequence(sequence, subject) {
265
+ if (sequence.length === 0) {
266
+ throw new Error(`${subject}: sequence must have at least one frame`);
267
+ }
268
+ }
@@ -14,6 +14,16 @@ export interface UIInputEventData {
14
14
  /** Element that emitted the event */
15
15
  element: UIDummy;
16
16
  }
17
+ /** What an element knows of a pointer: kept while it is over the element or pressed on it */
18
+ export interface UIDummyPointerState {
19
+ /** Last position, for signals of a cancel, which comes with none */
20
+ x: number;
21
+ y: number;
22
+ /** Over the element as of the last event */
23
+ inside: boolean;
24
+ /** Pressed on the element and not released yet: the element holds the pointer */
25
+ pressed: boolean;
26
+ }
17
27
  /** Configuration options for UIDummy */
18
28
  export interface UIDummyOptions extends UIAnchorOptions {
19
29
  /** Width in world units */
@@ -1,5 +1,4 @@
1
1
  import type { FerrsignView1 } from "ferrsign";
2
- import { Ferrsign1 } from "ferrsign";
3
2
  import { Matrix4 } from "three";
4
3
  import type { UILayer } from "../../layers/UILayer/UILayer.js";
5
4
  import type { UIArea } from "../../miscellaneous/area/UIArea.js";
@@ -21,13 +20,16 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
21
20
  protected modeInternal: UIMode;
22
21
  protected readonly inputWrapper: UIInputWrapperView;
23
22
  private readonly catcherHandler;
24
- private wasPointerInside;
23
+ private readonly pointers;
25
24
  private maskInternal;
26
25
  private readonly signalPointerPressedInternal;
27
26
  private readonly signalPointerMovedInternal;
28
27
  private readonly signalPointerReleasedInternal;
29
28
  private readonly signalPointerEnteredInternal;
30
29
  private readonly signalPointerLeftInternal;
30
+ private readonly signalPointerCancelledInternal;
31
+ private readonly signalPointerClickedInternal;
32
+ private readonly signalPointerDraggedInternal;
31
33
  /**
32
34
  * Creates a new UIDummy instance.
33
35
  *
@@ -56,7 +58,11 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
56
58
  get zIndex(): number;
57
59
  /** Mask clipping the element (input only, for an element that draws nothing); null for none */
58
60
  get mask(): UIMask | null;
59
- /** Signal fired when pointer is pressed */
61
+ /**
62
+ * Signal fired when pointer is pressed over the element. An element that catches the press
63
+ * (any interactive mode but INTERACTIVE_TRANSPARENT) holds the pointer until it is released:
64
+ * then exactly one of `signalPointerClicked` and `signalPointerCancelled` follows.
65
+ */
60
66
  get signalPointerPressed(): FerrsignView1<UIInputEventData>;
61
67
  /** Signal fired when pointer is moved */
62
68
  get signalPointerMoved(): FerrsignView1<UIInputEventData>;
@@ -64,8 +70,21 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
64
70
  get signalPointerReleased(): FerrsignView1<UIInputEventData>;
65
71
  /** Signal fired when pointer enters element */
66
72
  get signalPointerEntered(): FerrsignView1<UIInputEventData>;
67
- /** Signal fired when pointer leaves element */
73
+ /**
74
+ * Signal fired when pointer leaves element. A released or cancelled pointer leaves too: a
75
+ * mouse still over the element enters again on its next move.
76
+ */
68
77
  get signalPointerLeft(): FerrsignView1<UIInputEventData>;
78
+ /** Signal fired when a pointer pressed on the element is released over it */
79
+ get signalPointerClicked(): FerrsignView1<UIInputEventData>;
80
+ /** Signal fired when a pointer pressed on the element moves, over the element or not */
81
+ get signalPointerDragged(): FerrsignView1<UIInputEventData>;
82
+ /**
83
+ * Signal fired when a press on the element ends without a click: released outside the
84
+ * element, cancelled by the browser (a system gesture, scrolling, a popup), or the element
85
+ * stopped taking input. Reset what was started on press. The position is the last known one.
86
+ */
87
+ get signalPointerCancelled(): FerrsignView1<UIInputEventData>;
69
88
  /** Unique depth of the element among the elements of the layer, derived from `zIndex` */
70
89
  protected get renderDepth(): number;
71
90
  /** Width in world units */
@@ -111,7 +130,25 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
111
130
  protected readonly catchPointerDown: (x: number, y: number, identifier: number) => boolean;
112
131
  protected readonly catchPointerMove: (x: number, y: number, identifier: number) => boolean;
113
132
  protected readonly catchPointerUp: (x: number, y: number, identifier: number) => boolean;
114
- protected handleInputEvent(x: number, y: number, identifier: number, signal: Ferrsign1<UIInputEventData>): boolean;
133
+ /** Signals of a cancel carry the last known position */
134
+ protected readonly catchPointerCancel: (identifier: number) => void;
135
+ /**
136
+ * Updates what the element knows of a pointer: fires the signal of the event if the pointer
137
+ * is over the element, then entered or left if that changed.
138
+ */
139
+ private trackPointer;
140
+ /**
141
+ * Ends a pointer: a press on the element ends as a click or as cancelled, and the pointer
142
+ * leaves. A released or cancelled pointer is forgotten, so that a touch, which never comes
143
+ * back with the same identifier, does not stay over the element.
144
+ */
145
+ private endPointer;
146
+ /** Ends every pointer, for an element that stops taking input */
147
+ private dropPointers;
148
+ private forgetIfUntracked;
149
+ /** Whether the event stops at the element: catchers below do not get it */
150
+ private catches;
151
+ private emitPointer;
115
152
  /**
116
153
  * Whether a point in layer coordinates hits the element: it is in the visible part of the
117
154
  * mask, if the mask clips input, and in the interaction area of the rectangle as drawn, when