laymur 0.27.1 → 0.29.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 (138) hide show
  1. package/README.md +99 -5
  2. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.d.ts +14 -3
  3. package/dist/core/constraints/UIAspectConstraint/UIAspectConstraint.js +40 -6
  4. package/dist/core/constraints/UICustomConstraint.js +2 -2
  5. package/dist/core/constraints/UIHeightConstraint/UIHeightConstraint.js +3 -2
  6. package/dist/core/constraints/UIHorizontalDistanceConstraint/UIHorizontalDistanceConstraint.js +3 -2
  7. package/dist/core/constraints/UIHorizontalInterpolationConstraint/UIHorizontalInterpolationConstraint.js +3 -2
  8. package/dist/core/constraints/UIHorizontalProportionConstraint/UIHorizontalProportionConstraint.js +3 -2
  9. package/dist/core/constraints/UISingleParameterConstraint/UISingleParameterConstraint.d.ts +6 -0
  10. package/dist/core/constraints/UISingleParameterConstraint/UISingleParameterConstraint.js +8 -0
  11. package/dist/core/constraints/UIVerticalDistanceConstraint/UIVerticalDistanceConstraint.js +3 -2
  12. package/dist/core/constraints/UIVerticalInterpolationConstraint/UIVerticalInterpolationConstraint.js +3 -2
  13. package/dist/core/constraints/UIVerticalProportionConstraint/UIVerticalProportionConstraint.js +3 -2
  14. package/dist/core/constraints/UIWidthConstraint/UIWidthConstraint.js +3 -2
  15. package/dist/core/constraints/constraintAsserts.d.ts +41 -0
  16. package/dist/core/constraints/constraintAsserts.js +171 -0
  17. package/dist/core/elements/UICanvasElement/UICanvasElement.d.ts +54 -0
  18. package/dist/core/elements/UICanvasElement/UICanvasElement.js +70 -0
  19. package/dist/core/elements/UIDummy/UIDummy.Internal.d.ts +2 -0
  20. package/dist/core/elements/UIDummy/UIDummy.d.ts +8 -5
  21. package/dist/core/elements/UIDummy/UIDummy.js +24 -11
  22. package/dist/core/elements/UIElement/UIElement.Internal.d.ts +6 -5
  23. package/dist/core/elements/UIElement/UIElement.Internal.js +0 -4
  24. package/dist/core/elements/UIElement/UIElement.d.ts +12 -6
  25. package/dist/core/elements/UIElement/UIElement.js +14 -7
  26. package/dist/core/elements/UIGraphics/UIGraphics.Internal.d.ts +42 -2
  27. package/dist/core/elements/UIGraphics/UIGraphics.Internal.js +2 -2
  28. package/dist/core/elements/UIGraphics/UIGraphics.d.ts +48 -34
  29. package/dist/core/elements/UIGraphics/UIGraphics.js +196 -93
  30. package/dist/core/elements/UIImage/UIImage.d.ts +11 -1
  31. package/dist/core/elements/UIImage/UIImage.js +14 -0
  32. package/dist/core/elements/UIScene/UIScene.Internal.d.ts +10 -1
  33. package/dist/core/elements/UIScene/UIScene.Internal.js +1 -0
  34. package/dist/core/elements/UIScene/UIScene.d.ts +11 -1
  35. package/dist/core/elements/UIScene/UIScene.js +29 -5
  36. package/dist/core/elements/UIText/UIText.Interfaces.d.ts +2 -2
  37. package/dist/core/elements/UIText/UIText.Internal.d.ts +14 -1
  38. package/dist/core/elements/UIText/UIText.Internal.js +12 -0
  39. package/dist/core/elements/UIText/UIText.Measuring.d.ts +9 -4
  40. package/dist/core/elements/UIText/UIText.Measuring.js +17 -6
  41. package/dist/core/elements/UIText/UIText.Rendering.d.ts +7 -16
  42. package/dist/core/elements/UIText/UIText.Rendering.js +212 -46
  43. package/dist/core/elements/UIText/UIText.d.ts +64 -29
  44. package/dist/core/elements/UIText/UIText.js +134 -149
  45. package/dist/core/index.d.ts +10 -4
  46. package/dist/core/index.js +5 -1
  47. package/dist/core/layers/UILayer/UILayer.d.ts +17 -3
  48. package/dist/core/layers/UILayer/UILayer.js +35 -4
  49. package/dist/core/layers/UIViewportLayer/UIViewportLayer.d.ts +2 -0
  50. package/dist/core/layers/UIViewportLayer/UIViewportLayer.js +4 -1
  51. package/dist/core/miscellaneous/UIBlendMode.d.ts +5 -0
  52. package/dist/core/miscellaneous/UIBlendMode.js +7 -0
  53. package/dist/core/miscellaneous/asserts.d.ts +0 -41
  54. package/dist/core/miscellaneous/asserts.js +0 -170
  55. package/dist/core/miscellaneous/canvas-surface/UICanvasSurface.d.ts +46 -0
  56. package/dist/core/miscellaneous/canvas-surface/UICanvasSurface.js +86 -0
  57. package/dist/core/miscellaneous/color/UIColor.d.ts +17 -0
  58. package/dist/core/miscellaneous/color/UIColor.js +22 -0
  59. package/dist/core/miscellaneous/color/canvasColor.d.ts +9 -0
  60. package/dist/core/miscellaneous/color/canvasColor.js +15 -0
  61. package/dist/core/miscellaneous/insets/UIInsets.d.ts +3 -0
  62. package/dist/core/miscellaneous/insets/UIInsets.js +15 -0
  63. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.d.ts +10 -7
  64. package/dist/core/miscellaneous/mask-function/UIProgressMaskFunctionCircular.js +11 -8
  65. package/dist/core/miscellaneous/paint/UIGradient.Internal.d.ts +37 -0
  66. package/dist/core/miscellaneous/paint/UIGradient.Internal.js +14 -0
  67. package/dist/core/miscellaneous/paint/UIGradient.d.ts +18 -0
  68. package/dist/core/miscellaneous/paint/UIGradient.js +35 -0
  69. package/dist/core/miscellaneous/paint/UILinearGradient.d.ts +14 -0
  70. package/dist/core/miscellaneous/paint/UILinearGradient.js +22 -0
  71. package/dist/core/miscellaneous/paint/UIPaint.Internal.d.ts +21 -0
  72. package/dist/core/miscellaneous/paint/UIPaint.Internal.js +1 -0
  73. package/dist/core/miscellaneous/paint/UIPaint.d.ts +17 -0
  74. package/dist/core/miscellaneous/paint/UIPaint.js +21 -0
  75. package/dist/core/miscellaneous/paint/UIRadialGradient.d.ts +18 -0
  76. package/dist/core/miscellaneous/paint/UIRadialGradient.js +33 -0
  77. package/dist/core/miscellaneous/shared.d.ts +14 -0
  78. package/dist/core/miscellaneous/shared.js +11 -0
  79. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.d.ts +91 -30
  80. package/dist/core/miscellaneous/text-style/UITextStyle.Internal.js +12 -8
  81. package/dist/core/miscellaneous/text-style/UITextStyle.d.ts +41 -63
  82. package/dist/core/miscellaneous/text-style/UITextStyle.js +165 -291
  83. package/dist/core/miscellaneous/texture/UITextureView.Internal.d.ts +2 -1
  84. package/dist/core/miscellaneous/texture/UITextureView.Internal.js +12 -3
  85. package/dist/core/shaders/UIProgressMaskFunctionCircular.js +1 -2
  86. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.Internal.d.ts +7 -3
  87. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.d.ts +2 -1
  88. package/dist/core/wrappers/UIInputWrapper/UIInputWrapper.js +19 -10
  89. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.Internal.d.ts +6 -2
  90. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.d.ts +41 -9
  91. package/dist/core/wrappers/UISolverWrapper/UISolverWrapper.js +97 -35
  92. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.d.ts +44 -0
  93. package/dist/particles/behaviorModules/UIBehaviorAlignToVelocity.js +75 -0
  94. package/dist/particles/behaviorModules/UIBehaviorBounce.d.ts +51 -0
  95. package/dist/particles/behaviorModules/UIBehaviorBounce.js +107 -0
  96. package/dist/particles/behaviorModules/UIBehaviorOrbit.d.ts +39 -0
  97. package/dist/particles/behaviorModules/UIBehaviorOrbit.js +73 -0
  98. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.d.ts +7 -2
  99. package/dist/particles/behaviorModules/UIBehaviorScaleOverLife.js +9 -5
  100. package/dist/particles/behaviorModules/UIBehaviorSeek.d.ts +38 -0
  101. package/dist/particles/behaviorModules/UIBehaviorSeek.js +75 -0
  102. package/dist/particles/elements/UIEmitter.Internal.d.ts +48 -1
  103. package/dist/particles/elements/UIEmitter.Internal.js +26 -1
  104. package/dist/particles/elements/UIEmitter.Schedule.d.ts +31 -0
  105. package/dist/particles/elements/UIEmitter.Schedule.js +81 -0
  106. package/dist/particles/elements/UIEmitter.d.ts +79 -9
  107. package/dist/particles/elements/UIEmitter.js +241 -83
  108. package/dist/particles/index.d.ts +13 -1
  109. package/dist/particles/index.js +11 -1
  110. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.d.ts +6 -0
  111. package/dist/particles/instancedParticle/UIInstancedParticle.Internal.js +27 -0
  112. package/dist/particles/instancedParticle/UIInstancedParticle.d.ts +7 -1
  113. package/dist/particles/instancedParticle/UIInstancedParticle.js +12 -1
  114. package/dist/particles/miscellaneous/miscellaneous.d.ts +22 -0
  115. package/dist/particles/miscellaneous/miscellaneous.js +38 -0
  116. package/dist/particles/renderingModules/UIRenderingFlipbook.d.ts +41 -0
  117. package/dist/particles/renderingModules/UIRenderingFlipbook.js +70 -0
  118. package/dist/particles/renderingModules/UIRenderingModule.d.ts +2 -1
  119. package/dist/particles/renderingModules/UIRenderingModule.js +2 -1
  120. package/dist/particles/renderingModules/UIRenderingRandomColor.d.ts +19 -0
  121. package/dist/particles/renderingModules/UIRenderingRandomColor.js +28 -0
  122. package/dist/particles/renderingModules/UIRenderingShape.d.ts +31 -0
  123. package/dist/particles/renderingModules/UIRenderingShape.js +54 -0
  124. package/dist/particles/renderingModules/UIRenderingTexture.d.ts +1 -1
  125. package/dist/particles/renderingModules/UIRenderingTexture.js +4 -28
  126. package/dist/particles/shaders/UIRenderingFlipbook.d.ts +5 -0
  127. package/dist/particles/shaders/UIRenderingFlipbook.js +19 -0
  128. package/dist/particles/shaders/UIRenderingRandomColor.d.ts +2 -0
  129. package/dist/particles/shaders/UIRenderingRandomColor.js +10 -0
  130. package/dist/particles/shaders/UIRenderingShape.d.ts +6 -0
  131. package/dist/particles/shaders/UIRenderingShape.js +15 -0
  132. package/dist/particles/shaders/UIRenderingTexture.d.ts +4 -2
  133. package/dist/particles/shaders/UIRenderingTexture.js +27 -2
  134. package/dist/particles/spawnModules/UISpawnCircle.d.ts +44 -0
  135. package/dist/particles/spawnModules/UISpawnCircle.js +81 -0
  136. package/dist/particles/spawnModules/UISpawnRadialVelocity.d.ts +37 -0
  137. package/dist/particles/spawnModules/UISpawnRadialVelocity.js +75 -0
  138. package/package.json +1 -1
package/README.md CHANGED
@@ -19,6 +19,7 @@
19
19
  - **Orientation-aware** - define portrait and landscape rules in one layout, solver toggles automatically
20
20
  - **Micro-transforms** - transforms (scale, rotation, offset) that bypass the solver; input follows them
21
21
  - **Masks** - analytic shader masks (rectangle, rounded rectangle, ellipse) with soft edges and input clipping
22
+ - **Text effects** - gradient fills, stacked outlines, shadows and glows, drawn at screen resolution
22
23
  - **Color adjustment** - per-element hue/saturation/lightness and additive blend mode
23
24
  - **Resize policies** - Cover, Fit, FixedHeight, FixedWidth, Cross strategies
24
25
  - **Modular particles** - separate `laymur/particles` entry point, import only if needed
@@ -184,7 +185,55 @@ element.lightness = 0.1; // offset (0 = unchanged)
184
185
  element.blendMode = UIBlendMode.ADDITIVE;
185
186
  ```
186
187
 
187
- ### 6. Particle System
188
+ ### 6. Text and Graphics
189
+
190
+ `UIText` and `UIGraphics` draw on a canvas. Both redraw it at the size the element takes on the
191
+ screen, so they stay sharp on high-DPI screens and when constraints enlarge them.
192
+
193
+ ```typescript
194
+ import { UIGraphics, UILinearGradient, UIText } from "laymur";
195
+
196
+ const title = new UIText(layer, "WELL DONE!", {
197
+ commonStyle: {
198
+ fontSize: 64,
199
+ fontWeight: "bold",
200
+ color: new UILinearGradient([
201
+ { offset: 0, color: "#fff6b0" },
202
+ { offset: 1, color: "#ff7a00" },
203
+ ]),
204
+ strokes: [
205
+ { paint: "#7a2a00", thickness: 4 },
206
+ { paint: "#ffffff", thickness: 4 },
207
+ ],
208
+ shadows: [
209
+ { color: "rgba(0, 0, 0, 0.6)", offsetY: 6 },
210
+ { color: "rgba(255, 230, 0, 0.9)", blur: 12 },
211
+ ],
212
+ },
213
+ });
214
+
215
+ const panel = new UIGraphics(layer, { width: 300, height: 200 });
216
+ panel.drawRoundedRect(0, 0, 300, 200, 24, {
217
+ fill: "#2060ff",
218
+ stroke: { paint: "#ffffff", width: 4 },
219
+ });
220
+ ```
221
+
222
+ - Text is laid out in pixels of its style. With `UITextResizeMode.SCALE`, scaling the element with
223
+ constraints does not change the line breaks. With `BREAK` the text rewraps to the width.
224
+ - A gradient is laid over the box of what it fills, in fractions of that box from its top left
225
+ corner. For text the box is each line or the whole text (`paintBox`), for a shape its bounds.
226
+ - Strokes stack outward from the glyphs in list order. Shadows are cast by the outlined glyphs,
227
+ the first one on top, and a shadow without an offset is a glow.
228
+ - `UIGraphics` keeps its shapes until `clear()`. They are drawn in a box as large as the width and
229
+ height the element is created with, y pointing down, and the box is stretched over the element.
230
+ - With `lineBox: UITextLineBox.FONT` the height of a line comes from the font metrics, so texts
231
+ of one font aligned by an edge share the baseline.
232
+ - A `UIAspectConstraint` without an aspect follows the aspect of the text as it rewraps, and the
233
+ aspect of the texture of a `UIImage`.
234
+ - Micro transforms do not redraw the canvas.
235
+
236
+ ### 7. Particle System
188
237
 
189
238
  Modular pipeline: Spawn -> Behavior -> Rendering.
190
239
 
@@ -214,7 +263,52 @@ const emitter = new UIEmitter(
214
263
  emitter.play(60); // particles/sec
215
264
  ```
216
265
 
217
- ### 7. Debug Overlay
266
+ A ring of sparkles drawn without a texture, and a trail that stays on the layer behind a moving
267
+ emitter:
268
+
269
+ ```typescript
270
+ const ring = new UIEmitter(
271
+ layer,
272
+ [
273
+ new UISpawnCircle(20, [-Math.PI, Math.PI], UICircleDistribution.EVEN),
274
+ new UISpawnRadialVelocity(260), // after the shape: reads the spawn position
275
+ new UISpawnRandomScale(26),
276
+ ],
277
+ [new UIBehaviorVelocityDamping(0.6)],
278
+ [new UIRenderingShape(UIParticleShape.SPARKLE), new UIRenderingColorOverLife(colors)],
279
+ { blendMode: UIBlendMode.ADDITIVE },
280
+ );
281
+ ring.burst(16);
282
+
283
+ const trail = new UIEmitter(layer, spawnModules, behaviorModules, renderingModules, {
284
+ space: UIEmitterSpace.WORLD,
285
+ });
286
+ trail.play(240);
287
+ ```
288
+
289
+ Coins that fly into a counter, which counts each one as it lands:
290
+
291
+ ```typescript
292
+ const coins = new UIEmitter(
293
+ layer,
294
+ [new UISpawnRandomLifetime([0.9, 1.4]), new UISpawnRandomVelocity([-Math.PI, Math.PI], 300)],
295
+ [new UIBehaviorSeek(counterPosition, 0.25)], // last: arrives at the end of life
296
+ [new UIRenderingTexture(coinTexture)],
297
+ { space: UIEmitterSpace.WORLD },
298
+ );
299
+ coins.signalParticleDied.on((x, y) => {
300
+ counter.add(1);
301
+ sparks.burstAt(6, x, y);
302
+ });
303
+ coins.burst(20);
304
+ ```
305
+
306
+ Spawn modules write positions relative to the emitter. In `UIEmitterSpace.WORLD` the emitter then
307
+ places each particle where it was at the particle's moment within the frame, and particle
308
+ positions and the points of behavior modules are layer coordinates. In `LOCAL` space, the default,
309
+ live particles move with the emitter.
310
+
311
+ ### 8. Debug Overlay
218
312
 
219
313
  `laymur/debug` renders visual overlays for constraints - useful during development to inspect layout relationships.
220
314
 
@@ -248,7 +342,7 @@ Most commonly used exports (not exhaustive):
248
342
 
249
343
  ### Core
250
344
 
251
- UIViewportLayer, UIImage, UIAnimatedImage, UIText, UINineSlice, UIProgress, UIMask
345
+ UIViewportLayer, UIImage, UIAnimatedImage, UIText, UIGraphics, UINineSlice, UIProgress, UIMask, UILinearGradient, UIRadialGradient
252
346
 
253
347
  ### Constraints
254
348
 
@@ -256,13 +350,13 @@ UIAspectConstraint, UIHorizontalDistanceConstraint, UIVerticalDistanceConstraint
256
350
 
257
351
  ### Extension Points
258
352
 
259
- UIElement, UIArea, UIResizePolicy, UIViewport, UIProgressMaskFunction, UIMaskMaterialPatch, UIAffineMatrix3
353
+ UIElement, UIArea, UIGradient, UIResizePolicy, UIViewport, UIProgressMaskFunction, UIMaskMaterialPatch, UIAffineMatrix3
260
354
 
261
355
  UIRenderingModule, UISpawnModule, UIBehaviorModule (laymur/particles)
262
356
 
263
357
  ### Particles (laymur/particles)
264
358
 
265
- UIEmitter, UISpawnRectangle, UISpawnRandomLifetime, UIBehaviorDirectionalGravity, UIBehaviorVelocityDamping, UIRenderingTexture, UIRenderingColorOverLife
359
+ UIEmitter, UISpawnRectangle, UISpawnCircle, UISpawnRandomLifetime, UISpawnRadialVelocity, UIBehaviorDirectionalGravity, UIBehaviorVelocityDamping, UIBehaviorScaleOverLife, UIBehaviorAlignToVelocity, UIBehaviorOrbit, UIBehaviorBounce, UIBehaviorSeek, UIRenderingTexture, UIRenderingFlipbook, UIRenderingShape, UIRenderingColorOverLife, UIRenderingRandomColor
266
360
 
267
361
  ### Debug (laymur/debug)
268
362
 
@@ -1,22 +1,33 @@
1
1
  import type { UILayerElement, UIPlaneElement } from "../../miscellaneous/shared.js";
2
2
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
3
3
  import type { UIAspectConstraintOptions } from "./UIAspectConstraint.Internal.js";
4
- /** Maintains element aspect ratio (width = height * aspect) */
4
+ /**
5
+ * Maintains element aspect ratio (width = height * aspect). Without an aspect in the options it
6
+ * follows the content of an element that has its own aspect, such as `UIText` or `UIImage`, and
7
+ * keeps the current ratio of any other element.
8
+ */
5
9
  export declare class UIAspectConstraint extends UISingleParameterConstraint {
6
10
  readonly element: UIPlaneElement & UILayerElement;
7
11
  /** Solver constraint descriptor */
8
12
  protected readonly constraint: number;
9
13
  /** Current aspect ratio */
10
14
  private aspectInternal;
15
+ /** Element whose content aspect the constraint follows, null once an aspect is set */
16
+ private followedContent;
11
17
  /**
12
18
  * @param element Element to constrain
13
- * @param options Aspect configuration. Defaults to element's current ratio.
19
+ * @param options Aspect configuration. Without an aspect, the content aspect of the element or
20
+ * its current ratio.
14
21
  */
15
22
  constructor(element: UIPlaneElement & UILayerElement, options?: Partial<UIAspectConstraintOptions>);
16
23
  /** Current aspect ratio (width/height) */
17
24
  get aspect(): number;
18
- /** Updates aspect ratio */
25
+ /** Updates aspect ratio. The constraint stops following the content aspect of the element. */
19
26
  set aspect(value: number);
27
+ protected destroyInternal(): void;
28
+ private applyAspect;
29
+ private stopFollowingContent;
20
30
  /** Builds constraint expression: width - (height * aspect) = 0 */
21
31
  private buildLHS;
32
+ private readonly onContentAspectChanged;
22
33
  }
@@ -1,11 +1,18 @@
1
- import { assertValidConstraintElement, assertValidPositiveNumber, } from "../../miscellaneous/asserts.js";
1
+ import { assertValidPositiveNumber } from "../../miscellaneous/asserts.js";
2
+ import { isUIContentAspectElement } from "../../miscellaneous/shared.js";
2
3
  import { UIExpression } from "../../miscellaneous/UIExpression.js";
4
+ import { assertValidConstraintElement } from "../constraintAsserts.js";
3
5
  import { UISingleParameterConstraint } from "../UISingleParameterConstraint/UISingleParameterConstraint.js";
4
- /** Maintains element aspect ratio (width = height * aspect) */
6
+ /**
7
+ * Maintains element aspect ratio (width = height * aspect). Without an aspect in the options it
8
+ * follows the content of an element that has its own aspect, such as `UIText` or `UIImage`, and
9
+ * keeps the current ratio of any other element.
10
+ */
5
11
  export class UIAspectConstraint extends UISingleParameterConstraint {
6
12
  /**
7
13
  * @param element Element to constrain
8
- * @param options Aspect configuration. Defaults to element's current ratio.
14
+ * @param options Aspect configuration. Without an aspect, the content aspect of the element or
15
+ * its current ratio.
9
16
  */
10
17
  constructor(element, options = {}) {
11
18
  if (options.aspect !== undefined) {
@@ -13,22 +20,49 @@ export class UIAspectConstraint extends UISingleParameterConstraint {
13
20
  }
14
21
  super(assertValidConstraintElement(element, "UIAspectConstraint.constructor"), options);
15
22
  this.element = element;
16
- this.aspectInternal = options.aspect ?? element.width / element.height;
17
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
23
+ /** Element whose content aspect the constraint follows, null once an aspect is set */
24
+ this.followedContent = null;
25
+ this.onContentAspectChanged = (aspect) => {
26
+ this.applyAspect(aspect);
27
+ };
28
+ if (options.aspect !== undefined) {
29
+ this.aspectInternal = options.aspect;
30
+ }
31
+ else if (isUIContentAspectElement(element)) {
32
+ this.aspectInternal = element.contentAspect;
33
+ this.followedContent = element;
34
+ element.signalContentAspectChanged.on(this.onContentAspectChanged);
35
+ }
36
+ else {
37
+ this.aspectInternal = element.width / element.height;
38
+ }
39
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled(), this);
18
40
  }
19
41
  /** Current aspect ratio (width/height) */
20
42
  get aspect() {
21
43
  return this.aspectInternal;
22
44
  }
23
- /** Updates aspect ratio */
45
+ /** Updates aspect ratio. The constraint stops following the content aspect of the element. */
24
46
  set aspect(value) {
25
47
  this.assertNotDestroyed("UIAspectConstraint.aspect");
26
48
  assertValidPositiveNumber(value, "UIAspectConstraint.aspect");
49
+ this.stopFollowingContent();
50
+ this.applyAspect(value);
51
+ }
52
+ destroyInternal() {
53
+ this.stopFollowingContent();
54
+ super.destroyInternal();
55
+ }
56
+ applyAspect(value) {
27
57
  if (this.aspectInternal !== value) {
28
58
  this.aspectInternal = value;
29
59
  this.solverWrapper.setConstraintLHS(this.constraint, this.buildLHS());
30
60
  }
31
61
  }
62
+ stopFollowingContent() {
63
+ this.followedContent?.signalContentAspectChanged.off(this.onContentAspectChanged);
64
+ this.followedContent = null;
65
+ }
32
66
  /** Builds constraint expression: width - (height * aspect) = 0 */
33
67
  buildLHS() {
34
68
  return new UIExpression(0, [
@@ -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 {
@@ -12,7 +12,7 @@ export class UICustomConstraint extends UISingleParameterConstraint {
12
12
  super(assertValidConstraintExpressions(layer, [lhs, rhs], "UICustomConstraint.constructor"), options);
13
13
  this.lhsInternal = lhs;
14
14
  this.rhsInternal = rhs;
15
- this.constraint = this.solverWrapper.createConstraint(this.lhsInternal, this.rhsInternal, this.relation, this.priority, this.isConstraintEnabled());
15
+ this.constraint = this.solverWrapper.createConstraint(this.lhsInternal, this.rhsInternal, this.relation, this.priority, this.isConstraintEnabled(), this);
16
16
  }
17
17
  /** Left-hand side expression */
18
18
  get lhs() {
@@ -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 {
@@ -14,7 +15,7 @@ export class UIHeightConstraint extends UISingleParameterConstraint {
14
15
  super(assertValidConstraintElement(element, "UIHeightConstraint.constructor"), options);
15
16
  this.element = element;
16
17
  this.heightInternal = options.height ?? element.height;
17
- this.constraint = this.solverWrapper.createConstraint(new UIExpression(0, [[this.element.hVariable, 1]]), new UIExpression(this.heightInternal), this.relation, this.priority, this.isConstraintEnabled());
18
+ this.constraint = this.solverWrapper.createConstraint(new UIExpression(0, [[this.element.hVariable, 1]]), new UIExpression(this.heightInternal), this.relation, this.priority, this.isConstraintEnabled(), this);
18
19
  }
19
20
  /** Current height in world units */
20
21
  get height() {
@@ -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 */
@@ -26,7 +27,7 @@ export class UIHorizontalDistanceConstraint extends UISingleParameterConstraint
26
27
  this.anchorAInternal = options.anchorA ?? DEFAULT_ANCHOR;
27
28
  this.anchorBInternal = options.anchorB ?? DEFAULT_ANCHOR;
28
29
  this.distanceInternal = options.distance ?? 0;
29
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(this.distanceInternal), this.relation, this.priority, this.isConstraintEnabled());
30
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(this.distanceInternal), this.relation, this.priority, this.isConstraintEnabled(), this);
30
31
  }
31
32
  /** Current distance in world units */
32
33
  get distance() {
@@ -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 */
@@ -34,7 +35,7 @@ export class UIHorizontalInterpolationConstraint extends UISingleParameterConstr
34
35
  this.anchorBInternal = anchorB;
35
36
  this.anchorCInternal = options.anchorC ?? DEFAULT_ANCHOR;
36
37
  this.tInternal = options.t ?? DEFAULT_T;
37
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
38
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled(), this);
38
39
  }
39
40
  /** Interpolation factor (0 = A position, 1 = B position) */
40
41
  get t() {
@@ -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 {
@@ -16,7 +17,7 @@ export class UIHorizontalProportionConstraint extends UISingleParameterConstrain
16
17
  this.a = a;
17
18
  this.b = b;
18
19
  this.proportionInternal = options.proportion ?? 1;
19
- this.constraint = this.solverWrapper.createConstraint(new UIExpression(0), this.buildRHS(), this.relation, this.priority, this.isConstraintEnabled());
20
+ this.constraint = this.solverWrapper.createConstraint(new UIExpression(0), this.buildRHS(), this.relation, this.priority, this.isConstraintEnabled(), this);
20
21
  }
21
22
  /** Current proportion multiplier */
22
23
  get proportion() {
@@ -25,6 +25,12 @@ export declare abstract class UISingleParameterConstraint extends UIConstraint {
25
25
  get relation(): UIRelation;
26
26
  /** When constraint is active */
27
27
  get orientation(): UIOrientation;
28
+ /**
29
+ * Whether the solver applies the constraint. False while the orientation of the layer disables
30
+ * it, or while it conflicts with other required (P0) constraints, the later created of which is
31
+ * not applied. A conflict throws in development builds and warns in production builds.
32
+ */
33
+ get applied(): boolean;
28
34
  /** Updates constraint priority */
29
35
  set priority(value: UIPriority);
30
36
  /** Updates constraint relation */
@@ -31,6 +31,14 @@ export class UISingleParameterConstraint extends UIConstraint {
31
31
  get orientation() {
32
32
  return this.orientationInternal;
33
33
  }
34
+ /**
35
+ * Whether the solver applies the constraint. False while the orientation of the layer disables
36
+ * it, or while it conflicts with other required (P0) constraints, the later created of which is
37
+ * not applied. A conflict throws in development builds and warns in production builds.
38
+ */
39
+ get applied() {
40
+ return !this.destroyed && this.solverWrapper.isConstraintApplied(this.constraint);
41
+ }
34
42
  /** Updates constraint priority */
35
43
  set priority(value) {
36
44
  this.assertNotDestroyed("UISingleParameterConstraint.priority");
@@ -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 */
@@ -26,7 +27,7 @@ export class UIVerticalDistanceConstraint extends UISingleParameterConstraint {
26
27
  this.anchorAInternal = options.anchorA ?? DEFAULT_ANCHOR;
27
28
  this.anchorBInternal = options.anchorB ?? DEFAULT_ANCHOR;
28
29
  this.distanceInternal = options.distance ?? 0;
29
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(this.distanceInternal), this.relation, this.priority, this.isConstraintEnabled());
30
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(this.distanceInternal), this.relation, this.priority, this.isConstraintEnabled(), this);
30
31
  }
31
32
  /** Current distance in world units */
32
33
  get distance() {
@@ -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 */
@@ -34,7 +35,7 @@ export class UIVerticalInterpolationConstraint extends UISingleParameterConstrai
34
35
  this.anchorBInternal = anchorB;
35
36
  this.anchorCInternal = options.anchorC ?? DEFAULT_ANCHOR;
36
37
  this.tInternal = options.t ?? DEFAULT_T;
37
- this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled());
38
+ this.constraint = this.solverWrapper.createConstraint(this.buildLHS(), new UIExpression(0), this.relation, this.priority, this.isConstraintEnabled(), this);
38
39
  }
39
40
  /** Interpolation factor (0 = A position, 1 = B position) */
40
41
  get t() {
@@ -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 {
@@ -16,7 +17,7 @@ export class UIVerticalProportionConstraint extends UISingleParameterConstraint
16
17
  this.a = a;
17
18
  this.b = b;
18
19
  this.proportionInternal = options.proportion ?? 1;
19
- this.constraint = this.solverWrapper.createConstraint(new UIExpression(0), this.buildRHS(), this.relation, this.priority, this.isConstraintEnabled());
20
+ this.constraint = this.solverWrapper.createConstraint(new UIExpression(0), this.buildRHS(), this.relation, this.priority, this.isConstraintEnabled(), this);
20
21
  }
21
22
  /** Current proportion multiplier */
22
23
  get proportion() {
@@ -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 {
@@ -14,7 +15,7 @@ export class UIWidthConstraint extends UISingleParameterConstraint {
14
15
  super(assertValidConstraintElement(element, "UIWidthConstraint.constructor"), options);
15
16
  this.element = element;
16
17
  this.widthInternal = options.width ?? element.width;
17
- this.constraint = this.solverWrapper.createConstraint(new UIExpression(0, [[this.element.wVariable, 1]]), new UIExpression(this.widthInternal), this.relation, this.priority, this.isConstraintEnabled());
18
+ this.constraint = this.solverWrapper.createConstraint(new UIExpression(0, [[this.element.wVariable, 1]]), new UIExpression(this.widthInternal), this.relation, this.priority, this.isConstraintEnabled(), this);
18
19
  }
19
20
  /** Current width in world units */
20
21
  get width() {
@@ -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;