laymur 0.27.1 → 0.28.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 (82) hide show
  1. package/README.md +46 -1
  2. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.js +2 -1
  3. package/dist/core/constraints/UICustomConstraint.js +1 -1
  4. package/dist/core/constraints/UIHeightConstraint/UIHeightConstraint.js +2 -1
  5. package/dist/core/constraints/UIHorizontalDistanceConstraint/UIHorizontalDistanceConstraint.js +2 -1
  6. package/dist/core/constraints/UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js +2 -1
  7. package/dist/core/constraints/UIHorizontalProportionConstraint/UIHorizontalProportionConstraint.js +2 -1
  8. package/dist/core/constraints/UIVerticalDistanceConstraint/UIVerticalDistanceConstraint.js +2 -1
  9. package/dist/core/constraints/UIVerticalInterpolationConstraint/UIVerticalInterpolationConstraint.js +2 -1
  10. package/dist/core/constraints/UIVerticalProportionConstraint/UIVerticalProportionConstraint.js +2 -1
  11. package/dist/core/constraints/UIWidthConstraint/UIWidthConstraint.js +2 -1
  12. package/dist/core/constraints/constraintAsserts.d.ts +41 -0
  13. package/dist/core/constraints/constraintAsserts.js +171 -0
  14. package/dist/core/elements/UIDummy/UIDummy.d.ts +8 -5
  15. package/dist/core/elements/UIDummy/UIDummy.js +21 -10
  16. package/dist/core/elements/UIElement/UIElement.Internal.d.ts +6 -5
  17. package/dist/core/elements/UIElement/UIElement.Internal.js +0 -4
  18. package/dist/core/elements/UIElement/UIElement.d.ts +12 -6
  19. package/dist/core/elements/UIElement/UIElement.js +14 -7
  20. package/dist/core/elements/UIText/UIText.d.ts +6 -1
  21. package/dist/core/elements/UIText/UIText.js +22 -12
  22. package/dist/core/layers/UIViewportLayer/UIViewportLayer.js +1 -1
  23. package/dist/core/miscellaneous/UIBlendMode.d.ts +5 -0
  24. package/dist/core/miscellaneous/UIBlendMode.js +7 -0
  25. package/dist/core/miscellaneous/asserts.d.ts +0 -41
  26. package/dist/core/miscellaneous/asserts.js +0 -170
  27. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.d.ts +10 -7
  28. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.js +11 -8
  29. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.d.ts +4 -1
  30. package/dist/core/miscellaneous/text-style/UITextStyle.d.ts +4 -1
  31. package/dist/core/miscellaneous/text-style/UITextStyle.js +4 -1
  32. package/dist/core/shaders/UIProgressMaskFunctionCircular.js +1 -2
  33. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.Internal.d.ts +6 -2
  34. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.d.ts +1 -0
  35. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.js +18 -9
  36. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.d.ts +44 -0
  37. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.js +75 -0
  38. package/dist/particles/behaviorModules/UIBehaviorBounce.d.ts +51 -0
  39. package/dist/particles/behaviorModules/UIBehaviorBounce.js +107 -0
  40. package/dist/particles/behaviorModules/UIBehaviorOrbit.d.ts +39 -0
  41. package/dist/particles/behaviorModules/UIBehaviorOrbit.js +73 -0
  42. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.d.ts +7 -2
  43. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.js +9 -5
  44. package/dist/particles/behaviorModules/UIBehaviorSeek.d.ts +38 -0
  45. package/dist/particles/behaviorModules/UIBehaviorSeek.js +75 -0
  46. package/dist/particles/elements/UIEmitter.Internal.d.ts +45 -1
  47. package/dist/particles/elements/UIEmitter.Internal.js +25 -1
  48. package/dist/particles/elements/UIEmitter.Schedule.d.ts +31 -0
  49. package/dist/particles/elements/UIEmitter.Schedule.js +81 -0
  50. package/dist/particles/elements/UIEmitter.d.ts +79 -9
  51. package/dist/particles/elements/UIEmitter.js +239 -82
  52. package/dist/particles/index.d.ts +13 -1
  53. package/dist/particles/index.js +11 -1
  54. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.d.ts +6 -0
  55. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.js +27 -0
  56. package/dist/particles/instancedParticle/UIInstancedParticle.d.ts +7 -1
  57. package/dist/particles/instancedParticle/UIInstancedParticle.js +12 -1
  58. package/dist/particles/miscellaneous/miscellaneous.d.ts +22 -0
  59. package/dist/particles/miscellaneous/miscellaneous.js +38 -0
  60. package/dist/particles/renderingModules/UIRenderingFlipbook.d.ts +41 -0
  61. package/dist/particles/renderingModules/UIRenderingFlipbook.js +70 -0
  62. package/dist/particles/renderingModules/UIRenderingModule.d.ts +2 -1
  63. package/dist/particles/renderingModules/UIRenderingModule.js +2 -1
  64. package/dist/particles/renderingModules/UIRenderingRandomColor.d.ts +19 -0
  65. package/dist/particles/renderingModules/UIRenderingRandomColor.js +28 -0
  66. package/dist/particles/renderingModules/UIRenderingShape.d.ts +31 -0
  67. package/dist/particles/renderingModules/UIRenderingShape.js +54 -0
  68. package/dist/particles/renderingModules/UIRenderingTexture.d.ts +1 -1
  69. package/dist/particles/renderingModules/UIRenderingTexture.js +4 -28
  70. package/dist/particles/shaders/UIRenderingFlipbook.d.ts +5 -0
  71. package/dist/particles/shaders/UIRenderingFlipbook.js +19 -0
  72. package/dist/particles/shaders/UIRenderingRandomColor.d.ts +2 -0
  73. package/dist/particles/shaders/UIRenderingRandomColor.js +10 -0
  74. package/dist/particles/shaders/UIRenderingShape.d.ts +6 -0
  75. package/dist/particles/shaders/UIRenderingShape.js +15 -0
  76. package/dist/particles/shaders/UIRenderingTexture.d.ts +4 -2
  77. package/dist/particles/shaders/UIRenderingTexture.js +27 -2
  78. package/dist/particles/spawnModules/UISpawnCircle.d.ts +44 -0
  79. package/dist/particles/spawnModules/UISpawnCircle.js +81 -0
  80. package/dist/particles/spawnModules/UISpawnRadialVelocity.d.ts +37 -0
  81. package/dist/particles/spawnModules/UISpawnRadialVelocity.js +75 -0
  82. package/package.json +1 -1
package/README.md CHANGED
@@ -214,6 +214,51 @@ const emitter = new UIEmitter(
214
214
  emitter.play(60); // particles/sec
215
215
  ```
216
216
 
217
+ A ring of sparkles drawn without a texture, and a trail that stays on the layer behind a moving
218
+ emitter:
219
+
220
+ ```typescript
221
+ const ring = new UIEmitter(
222
+ layer,
223
+ [
224
+ new UISpawnCircle(20, [-Math.PI, Math.PI], UICircleDistribution.EVEN),
225
+ new UISpawnRadialVelocity(260), // after the shape: reads the spawn position
226
+ new UISpawnRandomScale(26),
227
+ ],
228
+ [new UIBehaviorVelocityDamping(0.6)],
229
+ [new UIRenderingShape(UIParticleShape.SPARKLE), new UIRenderingColorOverLife(colors)],
230
+ { blendMode: UIBlendMode.ADDITIVE },
231
+ );
232
+ ring.burst(16);
233
+
234
+ const trail = new UIEmitter(layer, spawnModules, behaviorModules, renderingModules, {
235
+ space: UIEmitterSpace.WORLD,
236
+ });
237
+ trail.play(240);
238
+ ```
239
+
240
+ Coins that fly into a counter, which counts each one as it lands:
241
+
242
+ ```typescript
243
+ const coins = new UIEmitter(
244
+ layer,
245
+ [new UISpawnRandomLifetime([0.9, 1.4]), new UISpawnRandomVelocity([-Math.PI, Math.PI], 300)],
246
+ [new UIBehaviorSeek(counterPosition, 0.25)], // last: arrives at the end of life
247
+ [new UIRenderingTexture(coinTexture)],
248
+ { space: UIEmitterSpace.WORLD },
249
+ );
250
+ coins.signalParticleDied.on((x, y) => {
251
+ counter.add(1);
252
+ sparks.burstAt(6, x, y);
253
+ });
254
+ coins.burst(20);
255
+ ```
256
+
257
+ Spawn modules write positions relative to the emitter. In `UIEmitterSpace.WORLD` the emitter then
258
+ places each particle where it was at the particle's moment within the frame, and particle
259
+ positions and the points of behavior modules are layer coordinates. In `LOCAL` space, the default,
260
+ live particles move with the emitter.
261
+
217
262
  ### 7. Debug Overlay
218
263
 
219
264
  `laymur/debug` renders visual overlays for constraints - useful during development to inspect layout relationships.
@@ -262,7 +307,7 @@ UIRenderingModule, UISpawnModule, UIBehaviorModule (laymur/particles)
262
307
 
263
308
  ### Particles (laymur/particles)
264
309
 
265
- UIEmitter, UISpawnRectangle, UISpawnRandomLifetime, UIBehaviorDirectionalGravity, UIBehaviorVelocityDamping, UIRenderingTexture, UIRenderingColorOverLife
310
+ UIEmitter, UISpawnRectangle, UISpawnCircle, UISpawnRandomLifetime, UISpawnRadialVelocity, UIBehaviorDirectionalGravity, UIBehaviorVelocityDamping, UIBehaviorScaleOverLife, UIBehaviorAlignToVelocity, UIBehaviorOrbit, UIBehaviorBounce, UIBehaviorSeek, UIRenderingTexture, UIRenderingFlipbook, UIRenderingShape, UIRenderingColorOverLife, UIRenderingRandomColor
266
311
 
267
312
  ### Debug (laymur/debug)
268
313
 
@@ -1,5 +1,6 @@
1
- import { assertValidConstraintElement, assertValidPositiveNumber, } from "../../miscellaneous/asserts.js";
1
+ import { assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
2
2
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
3
+ import { assertValidConstraintElement } from "../constraintAsserts.js";
3
4
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
4
5
  /** Maintains element aspect ratio (width = height * aspect) */
5
6
  export class UIAspectConstraint extends UISingleParameterConstraint {
@@ -1,4 +1,4 @@
1
- import { assertValidConstraintExpressions } from "../miscellaneous/asserts.js";
1
+ import { assertValidConstraintExpressions } from "./constraintAsserts.js";
2
2
  import { UISingleParameterConstraint } from "./UISingleParameterConstraint/UISingleParameterConstraint.js";
3
3
  /** Constraint with custom LHS and RHS expressions */
4
4
  export class UICustomConstraint extends UISingleParameterConstraint {
@@ -1,5 +1,6 @@
1
- import { assertValidConstraintElement, assertValidPositiveNumber, } from "../../miscellaneous/asserts.js";
1
+ import { assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
2
2
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
3
+ import { assertValidConstraintElement } from "../constraintAsserts.js";
3
4
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
4
5
  /** Fixes element height to constant value */
5
6
  export class UIHeightConstraint extends UISingleParameterConstraint {
@@ -1,6 +1,7 @@
1
- import { assertValidConstraintArguments, assertValidNumber } from "../../miscellaneous/asserts.js";
1
+ import { assertValidNumber } from "../../miscellaneous/asserts.js";
2
2
  import { isUIPlaneElement, isUIPointElement } from "../../miscellaneous/shared.js";
3
3
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
4
+ import { assertValidConstraintArguments } from "../constraintAsserts.js";
4
5
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
5
6
  import { DEFAULT_ANCHOR } from "./UIHorizontalDistanceConstraint.Internal.js";
6
7
  /** Maintains horizontal distance between elements with configurable anchors */
@@ -1,6 +1,7 @@
1
- import { assertValidInterpolationConstraintArguments, assertValidNumber, } from "../../miscellaneous/asserts.js";
1
+ import { assertValidNumber } from "../../miscellaneous/asserts.js";
2
2
  import { isUIPlaneElement, isUIPointElement } from "../../miscellaneous/shared.js";
3
3
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
4
+ import { assertValidInterpolationConstraintArguments } from "../constraintAsserts.js";
4
5
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
5
6
  import { DEFAULT_ANCHOR, DEFAULT_T } from "./UIHorizontalInterpolationConstraint.Internal.js";
6
7
  /** Positions element C horizontally between A and B based on interpolation factor */
@@ -1,5 +1,6 @@
1
- import { assertValidConstraintArguments, assertValidPositiveNumber, } from "../../miscellaneous/asserts.js";
1
+ import { assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
2
2
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
3
+ import { assertValidConstraintArguments } from "../constraintAsserts.js";
3
4
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
4
5
  /** Maintains proportional width relationship (A.width * proportion = B.width) */
5
6
  export class UIHorizontalProportionConstraint extends UISingleParameterConstraint {
@@ -1,6 +1,7 @@
1
- import { assertValidConstraintArguments, assertValidNumber } from "../../miscellaneous/asserts.js";
1
+ import { assertValidNumber } from "../../miscellaneous/asserts.js";
2
2
  import { isUIPlaneElement, isUIPointElement } from "../../miscellaneous/shared.js";
3
3
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
4
+ import { assertValidConstraintArguments } from "../constraintAsserts.js";
4
5
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
5
6
  import { DEFAULT_ANCHOR } from "./UIVerticalDistanceConstraint.Internal.js";
6
7
  /** Maintains vertical distance between elements with configurable anchors */
@@ -1,6 +1,7 @@
1
- import { assertValidInterpolationConstraintArguments, assertValidNumber, } from "../../miscellaneous/asserts.js";
1
+ import { assertValidNumber } from "../../miscellaneous/asserts.js";
2
2
  import { isUIPlaneElement, isUIPointElement } from "../../miscellaneous/shared.js";
3
3
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
4
+ import { assertValidInterpolationConstraintArguments } from "../constraintAsserts.js";
4
5
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
5
6
  import { DEFAULT_ANCHOR, DEFAULT_T } from "./UIVerticalInterpolationConstraint.Internal.js";
6
7
  /** Positions element C vertically between A and B based on interpolation factor */
@@ -1,5 +1,6 @@
1
- import { assertValidConstraintArguments, assertValidPositiveNumber, } from "../../miscellaneous/asserts.js";
1
+ import { assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
2
2
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
3
+ import { assertValidConstraintArguments } from "../constraintAsserts.js";
3
4
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
4
5
  /** Maintains proportional height relationship (A.height * proportion = B.height) */
5
6
  export class UIVerticalProportionConstraint extends UISingleParameterConstraint {
@@ -1,5 +1,6 @@
1
- import { assertValidConstraintElement, assertValidPositiveNumber, } from "../../miscellaneous/asserts.js";
1
+ import { assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
2
2
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
3
+ import { assertValidConstraintElement } from "../constraintAsserts.js";
3
4
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
4
5
  /** Fixes element width to constant value */
5
6
  export class UIWidthConstraint extends UISingleParameterConstraint {
@@ -0,0 +1,41 @@
1
+ import { UILayer } from "../layers/UILayer/UILayer.js";
2
+ import type { UILayerElement } from "../miscellaneous/shared.js";
3
+ import type { UIExpression } from "../miscellaneous/UIExpression.js";
4
+ /**
5
+ * Validates constraint arguments are from same layer.
6
+ * @param a First constraint subject
7
+ * @param b Second constraint subject
8
+ * @param subject Constraint name for error messages
9
+ * @returns Common layer for both subjects
10
+ * @throws If subjects are invalid or from different layers
11
+ */
12
+ export declare function assertValidConstraintArguments(a: unknown, b: unknown, subject: string): UILayer;
13
+ /**
14
+ * Validates interpolation constraint subjects.
15
+ * @param subject Constraint name for error messages
16
+ * @param a First element
17
+ * @param b Second element
18
+ * @param c Element to interpolate
19
+ * @param anchorA Anchor on element A
20
+ * @param anchorB Anchor on element B
21
+ * @returns Common layer for all subjects
22
+ * @throws If subjects violate interpolation constraints
23
+ */
24
+ export declare function assertValidInterpolationConstraintArguments(subject: string, a: unknown, b: unknown, c: unknown, anchorA: number, anchorB: number): UILayer;
25
+ /**
26
+ * Validates the element of a single element constraint.
27
+ * @param element Constrained element
28
+ * @param subject Constraint name for error messages
29
+ * @returns Layer of the element
30
+ * @throws If the element is destroyed
31
+ */
32
+ export declare function assertValidConstraintElement(element: UILayerElement, subject: string): UILayer;
33
+ /**
34
+ * Validates that the expressions of a custom constraint refer only to existing variables.
35
+ * @param layer Layer of the constraint
36
+ * @param expressions Constraint expressions
37
+ * @param subject Constraint name for error messages
38
+ * @returns The layer
39
+ * @throws If the layer is destroyed or a variable does not exist
40
+ */
41
+ export declare function assertValidConstraintExpressions(layer: UILayer, expressions: UIExpression[], subject: string): UILayer;
@@ -0,0 +1,171 @@
1
+ import { UILayer } from "../layers/UILayer/UILayer.js";
2
+ import { EPSILON } from "../miscellaneous/math.js";
3
+ import { isUILayerElement } from "../miscellaneous/shared.js";
4
+ /**
5
+ * Validates constraint arguments are from same layer.
6
+ * @param a First constraint subject
7
+ * @param b Second constraint subject
8
+ * @param subject Constraint name for error messages
9
+ * @returns Common layer for both subjects
10
+ * @throws If subjects are invalid or from different layers
11
+ */
12
+ export function assertValidConstraintArguments(a, b, subject) {
13
+ if (process.env.NODE_ENV !== "production") {
14
+ assertNotDestroyed(a, "A", subject);
15
+ assertNotDestroyed(b, "B", subject);
16
+ if (a instanceof UILayer && b instanceof UILayer) {
17
+ throw new Error(`${subject}: layer cannot be snapped to another layer`);
18
+ }
19
+ let layerA;
20
+ let layerB;
21
+ if (a instanceof UILayer) {
22
+ layerA = a;
23
+ }
24
+ else if (isUILayerElement(a)) {
25
+ layerA = a.layer;
26
+ }
27
+ else {
28
+ throw new Error(`${subject}: A must be a UILayer or a UILayerElement`);
29
+ }
30
+ if (b instanceof UILayer) {
31
+ layerB = b;
32
+ }
33
+ else if (isUILayerElement(b)) {
34
+ layerB = b.layer;
35
+ }
36
+ else {
37
+ throw new Error(`${subject}: B must be a UILayer or a UILayerElement`);
38
+ }
39
+ if (layerA !== layerB) {
40
+ throw new Error(`${subject}: elements must be on the same layer`);
41
+ }
42
+ return layerA;
43
+ }
44
+ if (a instanceof UILayer) {
45
+ return a;
46
+ }
47
+ if (isUILayerElement(a)) {
48
+ return a.layer;
49
+ }
50
+ if (b instanceof UILayer) {
51
+ return b;
52
+ }
53
+ if (isUILayerElement(b)) {
54
+ return b.layer;
55
+ }
56
+ throw new Error(`${subject}: A or B must be a UILayer or a UILayerElement`);
57
+ }
58
+ /**
59
+ * Validates interpolation constraint subjects.
60
+ * @param subject Constraint name for error messages
61
+ * @param a First element
62
+ * @param b Second element
63
+ * @param c Element to interpolate
64
+ * @param anchorA Anchor on element A
65
+ * @param anchorB Anchor on element B
66
+ * @returns Common layer for all subjects
67
+ * @throws If subjects violate interpolation constraints
68
+ */
69
+ export function assertValidInterpolationConstraintArguments(subject, a, b, c, anchorA, anchorB) {
70
+ if (process.env.NODE_ENV !== "production") {
71
+ assertNotDestroyed(a, "A", subject);
72
+ assertNotDestroyed(b, "B", subject);
73
+ assertNotDestroyed(c, "C", subject);
74
+ if (c instanceof UILayer) {
75
+ throw new Error(`${subject}: C cannot be a layer`);
76
+ }
77
+ if (!isUILayerElement(c)) {
78
+ throw new Error(`${subject}: C must be a UILayerElement`);
79
+ }
80
+ let layerA;
81
+ let layerB;
82
+ if (a instanceof UILayer || isUILayerElement(a)) {
83
+ layerA = a instanceof UILayer ? a : a.layer;
84
+ }
85
+ else {
86
+ throw new Error(`${subject}: A must be a UILayer or a UILayerElement`);
87
+ }
88
+ if (b instanceof UILayer || isUILayerElement(b)) {
89
+ layerB = b instanceof UILayer ? b : b.layer;
90
+ }
91
+ else {
92
+ throw new Error(`${subject}: B must be a UILayer or a UILayerElement`);
93
+ }
94
+ const layerC = c.layer;
95
+ if (layerA !== layerB || layerA !== layerC) {
96
+ throw new Error(`${subject}: all elements must be on the same layer`);
97
+ }
98
+ if (c === a || c === b) {
99
+ throw new Error(`${subject}: C cannot be equal to A or B`);
100
+ }
101
+ if (a === b) {
102
+ if (Math.abs(anchorA - anchorB) <= EPSILON) {
103
+ throw new Error(`${subject}: when A and B are the same, anchorA and anchorB must differ by more than ${EPSILON}`);
104
+ }
105
+ }
106
+ return layerA;
107
+ }
108
+ if (isUILayerElement(a)) {
109
+ return a.layer;
110
+ }
111
+ if (isUILayerElement(b)) {
112
+ return b.layer;
113
+ }
114
+ if (a instanceof UILayer) {
115
+ return a;
116
+ }
117
+ if (b instanceof UILayer) {
118
+ return b;
119
+ }
120
+ throw new Error(`${subject}: A or B must be a UILayer or a UILayerElement`);
121
+ }
122
+ /**
123
+ * Validates the element of a single element constraint.
124
+ * @param element Constrained element
125
+ * @param subject Constraint name for error messages
126
+ * @returns Layer of the element
127
+ * @throws If the element is destroyed
128
+ */
129
+ export function assertValidConstraintElement(element, subject) {
130
+ if (process.env.NODE_ENV !== "production") {
131
+ assertNotDestroyed(element, "element", subject);
132
+ }
133
+ return element.layer;
134
+ }
135
+ /**
136
+ * Validates that the expressions of a custom constraint refer only to existing variables.
137
+ * @param layer Layer of the constraint
138
+ * @param expressions Constraint expressions
139
+ * @param subject Constraint name for error messages
140
+ * @returns The layer
141
+ * @throws If the layer is destroyed or a variable does not exist
142
+ */
143
+ export function assertValidConstraintExpressions(layer, expressions, subject) {
144
+ if (process.env.NODE_ENV !== "production") {
145
+ assertNotDestroyed(layer, "layer", subject);
146
+ for (const expression of expressions) {
147
+ for (const [variableIndex] of expression.prepareTerms()) {
148
+ if (!layer.solverWrapper.hasVariable(variableIndex)) {
149
+ throw new Error(`${subject}: variable ${variableIndex} does not exist`);
150
+ }
151
+ }
152
+ }
153
+ }
154
+ return layer;
155
+ }
156
+ /**
157
+ * Validates that a constraint subject is not destroyed. A constraint made with a destroyed
158
+ * subject would stay in the layer without a solver constraint.
159
+ * @param value Element or layer
160
+ * @param name Subject name for error messages
161
+ * @param subject Constraint name for error messages
162
+ * @throws If the subject is destroyed
163
+ */
164
+ function assertNotDestroyed(value, name, subject) {
165
+ if (typeof value === "object" &&
166
+ value !== null &&
167
+ "destroyed" in value &&
168
+ value.destroyed === true) {
169
+ throw new Error(`${subject}: ${name} is destroyed`);
170
+ }
171
+ }
@@ -71,8 +71,8 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
71
71
  /** Signal fired when pointer enters element */
72
72
  get signalPointerEntered(): FerrsignView1<UIInputEventData>;
73
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.
74
+ * Signal fired when pointer leaves element. A released touch or pen and a cancelled pointer
75
+ * leave too; a released mouse stays over the element.
76
76
  */
77
77
  get signalPointerLeft(): FerrsignView1<UIInputEventData>;
78
78
  /** Signal fired when a pointer pressed on the element is released over it */
@@ -129,7 +129,8 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
129
129
  protected destroyInternal(): void;
130
130
  protected readonly catchPointerDown: (x: number, y: number, identifier: number) => boolean;
131
131
  protected readonly catchPointerMove: (x: number, y: number, identifier: number) => boolean;
132
- protected readonly catchPointerUp: (x: number, y: number, identifier: number) => boolean;
132
+ /** A mouse stays over the element after the release; a touch or a pen leaves it */
133
+ protected readonly catchPointerUp: (x: number, y: number, identifier: number, hovering: boolean) => boolean;
133
134
  /** Signals of a cancel carry the last known position */
134
135
  protected readonly catchPointerCancel: (identifier: number) => void;
135
136
  /**
@@ -139,10 +140,12 @@ export declare class UIDummy extends UIAnchor implements UIPlaneElement {
139
140
  private trackPointer;
140
141
  /**
141
142
  * 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.
143
+ * leaves. The pointer is forgotten, so that a touch, which never comes back with the same
144
+ * identifier, does not stay over the element.
144
145
  */
145
146
  private endPointer;
147
+ /** Ends a press on the element, if there is one, as a click or as cancelled */
148
+ private endPress;
146
149
  /** Ends every pointer, for an element that stops taking input */
147
150
  private dropPointers;
148
151
  private forgetIfUntracked;
@@ -49,10 +49,17 @@ export class UIDummy extends UIAnchor {
49
49
  this.forgetIfUntracked(identifier, state);
50
50
  return this.catches(state);
51
51
  };
52
- this.catchPointerUp = (x, y, identifier) => {
52
+ /** A mouse stays over the element after the release; a touch or a pen leaves it */
53
+ this.catchPointerUp = (x, y, identifier, hovering) => {
53
54
  const state = this.trackPointer(x, y, identifier, this.signalPointerReleasedInternal);
54
55
  const caught = this.catches(state);
55
- this.endPointer(identifier, state, state.inside);
56
+ if (hovering) {
57
+ this.endPress(identifier, state, state.inside);
58
+ this.forgetIfUntracked(identifier, state);
59
+ }
60
+ else {
61
+ this.endPointer(identifier, state, state.inside);
62
+ }
56
63
  return caught;
57
64
  };
58
65
  /** Signals of a cancel carry the last known position */
@@ -141,8 +148,8 @@ export class UIDummy extends UIAnchor {
141
148
  return this.signalPointerEnteredInternal;
142
149
  }
143
150
  /**
144
- * Signal fired when pointer leaves element. A released or cancelled pointer leaves too: a
145
- * mouse still over the element enters again on its next move.
151
+ * Signal fired when pointer leaves element. A released touch or pen and a cancelled pointer
152
+ * leave too; a released mouse stays over the element.
146
153
  */
147
154
  get signalPointerLeft() {
148
155
  return this.signalPointerLeftInternal;
@@ -312,20 +319,24 @@ export class UIDummy extends UIAnchor {
312
319
  }
313
320
  /**
314
321
  * Ends a pointer: a press on the element ends as a click or as cancelled, and the pointer
315
- * leaves. A released or cancelled pointer is forgotten, so that a touch, which never comes
316
- * back with the same identifier, does not stay over the element.
322
+ * leaves. The pointer is forgotten, so that a touch, which never comes back with the same
323
+ * identifier, does not stay over the element.
317
324
  */
318
325
  endPointer(identifier, state, clicked) {
319
326
  this.pointers.delete(identifier);
320
- if (state.pressed) {
321
- state.pressed = false;
322
- this.emitPointer(clicked ? this.signalPointerClickedInternal : this.signalPointerCancelledInternal, state, identifier);
323
- }
327
+ this.endPress(identifier, state, clicked);
324
328
  if (state.inside) {
325
329
  state.inside = false;
326
330
  this.emitPointer(this.signalPointerLeftInternal, state, identifier);
327
331
  }
328
332
  }
333
+ /** Ends a press on the element, if there is one, as a click or as cancelled */
334
+ endPress(identifier, state, clicked) {
335
+ if (state.pressed) {
336
+ state.pressed = false;
337
+ this.emitPointer(clicked ? this.signalPointerClickedInternal : this.signalPointerCancelledInternal, state, identifier);
338
+ }
339
+ }
329
340
  /** Ends every pointer, for an element that stops taking input */
330
341
  dropPointers() {
331
342
  for (const [identifier, state] of [...this.pointers]) {
@@ -11,11 +11,14 @@ export interface UIElementOptions extends UIDummyOptions {
11
11
  transparencyMode: UITransparencyMode;
12
12
  /** Color blending mode (only affects BLEND transparency) */
13
13
  blendMode: UIBlendMode;
14
- /** Hue shift in degrees */
14
+ /**
15
+ * Hue shift in degrees. Applied to the linear color, so the hue of a color is not the one a
16
+ * color picker shows for its sRGB value.
17
+ */
15
18
  hue: number;
16
- /** Saturation multiplier (1 = unchanged, 0 = grayscale) */
19
+ /** Saturation multiplier (1 = unchanged, 0 = grayscale), applied to the linear color */
17
20
  saturation: number;
18
- /** Lightness offset (0 = unchanged) */
21
+ /** Lightness offset (0 = unchanged), applied to the linear color */
19
22
  lightness: number;
20
23
  }
21
24
  export declare const ELEMENT_DEFAULT_TRANSPARENCY_MODE = UITransparencyMode.BLEND;
@@ -23,8 +26,6 @@ export declare const ELEMENT_DEFAULT_BLEND_MODE = UIBlendMode.NORMAL;
23
26
  export declare const ELEMENT_DEFAULT_HUE = 0;
24
27
  export declare const ELEMENT_DEFAULT_SATURATION = 1;
25
28
  export declare const ELEMENT_DEFAULT_LIGHTNESS = 0;
26
- /** Maps a blend mode to the output-alpha multiplier used by the premultiplied shader. */
27
- export declare function blendModeToFactor(mode: UIBlendMode): number;
28
29
  /**
29
30
  * Packs HSL adjustment into the shader attribute layout (hue in turns, saturation
30
31
  * multiplier, lightness offset). Hue degrees become turns so the shader can wrap
@@ -5,10 +5,6 @@ export const ELEMENT_DEFAULT_BLEND_MODE = UIBlendMode.NORMAL;
5
5
  export const ELEMENT_DEFAULT_HUE = 0;
6
6
  export const ELEMENT_DEFAULT_SATURATION = 1;
7
7
  export const ELEMENT_DEFAULT_LIGHTNESS = 0;
8
- /** Maps a blend mode to the output-alpha multiplier used by the premultiplied shader. */
9
- export function blendModeToFactor(mode) {
10
- return mode === UIBlendMode.ADDITIVE ? 0 : 1;
11
- }
12
8
  /**
13
9
  * Packs HSL adjustment into the shader attribute layout (hue in turns, saturation
14
10
  * multiplier, lightness offset). Hue degrees become turns so the shader can wrap
@@ -53,11 +53,14 @@ export declare abstract class UIElement extends UIDummy {
53
53
  get transparencyMode(): UITransparencyMode;
54
54
  /** Color blending mode (only affects BLEND transparency) */
55
55
  get blendMode(): UIBlendMode;
56
- /** Hue shift in degrees */
56
+ /**
57
+ * Hue shift in degrees. Applied to the linear color, so the hue of a color is not the one a
58
+ * color picker shows for its sRGB value.
59
+ */
57
60
  get hue(): number;
58
- /** Saturation multiplier (1 = unchanged, 0 = grayscale) */
61
+ /** Saturation multiplier (1 = unchanged, 0 = grayscale), applied to the linear color */
59
62
  get saturation(): number;
60
- /** Lightness offset (0 = unchanged) */
63
+ /** Lightness offset (0 = unchanged), applied to the linear color */
61
64
  get lightness(): number;
62
65
  /**
63
66
  * Controls visibility and interactivity.
@@ -72,11 +75,14 @@ export declare abstract class UIElement extends UIDummy {
72
75
  set transparencyMode(value: UITransparencyMode);
73
76
  /** Color blending mode (only affects BLEND transparency) */
74
77
  set blendMode(value: UIBlendMode);
75
- /** Hue shift in degrees */
78
+ /**
79
+ * Hue shift in degrees. Applied to the linear color, so the hue of a color is not the one a
80
+ * color picker shows for its sRGB value.
81
+ */
76
82
  set hue(value: number);
77
- /** Saturation multiplier (1 = unchanged, 0 = grayscale) */
83
+ /** Saturation multiplier (1 = unchanged, 0 = grayscale), applied to the linear color */
78
84
  set saturation(value: number);
79
- /** Lightness offset (0 = unchanged) */
85
+ /** Lightness offset (0 = unchanged), applied to the linear color */
80
86
  set lightness(value: number);
81
87
  /** Controls visibility and interactivity */
82
88
  set mode(value: UIMode);
@@ -1,8 +1,9 @@
1
1
  import { Matrix4 } from "three";
2
2
  import { UIMicro } from "../../miscellaneous/micro/UIMicro.js";
3
+ import { blendModeToFactor } from "../../miscellaneous/UIBlendMode.js";
3
4
  import { isUIModeVisible } from "../../miscellaneous/UIMode.js";
4
5
  import { UIDummy } from "../UIDummy/UIDummy.js";
5
- import { blendModeToFactor, ELEMENT_DEFAULT_BLEND_MODE, ELEMENT_DEFAULT_HUE, ELEMENT_DEFAULT_LIGHTNESS, ELEMENT_DEFAULT_SATURATION, ELEMENT_DEFAULT_TRANSPARENCY_MODE, packHSL, } from "./UIElement.Internal.js";
6
+ import { ELEMENT_DEFAULT_BLEND_MODE, ELEMENT_DEFAULT_HUE, ELEMENT_DEFAULT_LIGHTNESS, ELEMENT_DEFAULT_SATURATION, ELEMENT_DEFAULT_TRANSPARENCY_MODE, packHSL, } from "./UIElement.Internal.js";
6
7
  const TEMP_TRANSFORM = new Matrix4();
7
8
  /**
8
9
  * Base class for renderable UI elements: a quad drawn with a custom fragment shader.
@@ -60,15 +61,18 @@ export class UIElement extends UIDummy {
60
61
  get blendMode() {
61
62
  return this.blendModeInternal;
62
63
  }
63
- /** Hue shift in degrees */
64
+ /**
65
+ * Hue shift in degrees. Applied to the linear color, so the hue of a color is not the one a
66
+ * color picker shows for its sRGB value.
67
+ */
64
68
  get hue() {
65
69
  return this.hueInternal;
66
70
  }
67
- /** Saturation multiplier (1 = unchanged, 0 = grayscale) */
71
+ /** Saturation multiplier (1 = unchanged, 0 = grayscale), applied to the linear color */
68
72
  get saturation() {
69
73
  return this.saturationInternal;
70
74
  }
71
- /** Lightness offset (0 = unchanged) */
75
+ /** Lightness offset (0 = unchanged), applied to the linear color */
72
76
  get lightness() {
73
77
  return this.lightnessInternal;
74
78
  }
@@ -100,21 +104,24 @@ export class UIElement extends UIDummy {
100
104
  this.blendModeDirty = true;
101
105
  }
102
106
  }
103
- /** Hue shift in degrees */
107
+ /**
108
+ * Hue shift in degrees. Applied to the linear color, so the hue of a color is not the one a
109
+ * color picker shows for its sRGB value.
110
+ */
104
111
  set hue(value) {
105
112
  if (this.hueInternal !== value) {
106
113
  this.hueInternal = value;
107
114
  this.hslDirty = true;
108
115
  }
109
116
  }
110
- /** Saturation multiplier (1 = unchanged, 0 = grayscale) */
117
+ /** Saturation multiplier (1 = unchanged, 0 = grayscale), applied to the linear color */
111
118
  set saturation(value) {
112
119
  if (this.saturationInternal !== value) {
113
120
  this.saturationInternal = value;
114
121
  this.hslDirty = true;
115
122
  }
116
123
  }
117
- /** Lightness offset (0 = unchanged) */
124
+ /** Lightness offset (0 = unchanged), applied to the linear color */
118
125
  set lightness(value) {
119
126
  if (this.lightnessInternal !== value) {
120
127
  this.lightnessInternal = value;
@@ -61,7 +61,10 @@ export declare class UIText extends UIElement {
61
61
  get direction(): UITextDirection;
62
62
  /** Multiplicative tint. Alpha channel controls opacity. */
63
63
  set color(value: UIColorConfig);
64
- /** Text content as string, span config, or array */
64
+ /**
65
+ * Text content as string, span config, or array. Text without visible characters keeps the
66
+ * element at least 1 world unit wide and high.
67
+ */
65
68
  set content(value: UITextContent);
66
69
  /** Maximum line width before wrapping in pixels */
67
70
  set maxLineWidth(value: number);
@@ -81,6 +84,8 @@ export declare class UIText extends UIElement {
81
84
  protected onWillRender(renderer: WebGLRenderer, deltaTime: number): void;
82
85
  private tryToRenderTextScaleMode;
83
86
  private tryToRenderTextBreakMode;
87
+ /** The element size for a text size: the padding added, at least the minimum each way */
88
+ private elementSize;
84
89
  private updateProperties;
85
90
  private updateAutoPadding;
86
91
  private buildTextChunks;