laymur 0.2.18 → 0.3.3

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 (45) hide show
  1. package/README.md +87 -274
  2. package/dist/builders/UIConstraint2DBuilder.d.ts +1 -1
  3. package/dist/builders/UICoverConstraintBuilder.d.ts +3 -1
  4. package/dist/builders/UIFitConstraintBuilder.d.ts +3 -1
  5. package/dist/constraints/UIAspectConstraint.d.ts +0 -1
  6. package/dist/constraints/UIConstraint.d.ts +3 -0
  7. package/dist/constraints/UIHorizontalDistanceConstraint.d.ts +0 -1
  8. package/dist/constraints/UIHorizontalProportionConstraint.d.ts +2 -3
  9. package/dist/constraints/UISingleParameterConstraint.d.ts +0 -2
  10. package/dist/constraints/UIVerticalDistanceConstraint.d.ts +0 -1
  11. package/dist/constraints/UIVerticalProportionConstraint.d.ts +2 -3
  12. package/dist/elements/UIDummy.d.ts +7 -1
  13. package/dist/elements/UIElement.d.ts +52 -38
  14. package/dist/elements/UIImage.d.ts +30 -42
  15. package/dist/elements/UINineSline.d.ts +61 -68
  16. package/dist/elements/UIProgress.d.ts +86 -110
  17. package/dist/elements/UIScene.d.ts +21 -30
  18. package/dist/elements/UIText.d.ts +27 -41
  19. package/dist/index.d.ts +6 -1
  20. package/dist/index.js +1663 -939
  21. package/dist/index.js.map +1 -1
  22. package/dist/index.min.js +1 -1
  23. package/dist/index.min.js.map +1 -1
  24. package/dist/layers/UIFullscreenLayer.d.ts +0 -4
  25. package/dist/layers/UILayer.d.ts +62 -4
  26. package/dist/miscellaneous/UIColor.d.ts +171 -0
  27. package/dist/miscellaneous/UIGenericInstancedPlane.d.ts +32 -0
  28. package/dist/miscellaneous/UIInputEvent.d.ts +7 -0
  29. package/dist/miscellaneous/UIMicro.d.ts +3 -3
  30. package/dist/miscellaneous/{UIAnchorMode.d.ts → UIMicroAnchorMode.d.ts} +1 -1
  31. package/dist/miscellaneous/UINineSliceBorder.d.ts +6 -6
  32. package/dist/miscellaneous/UISceneWrapperClientAPI.d.ts +12 -0
  33. package/dist/miscellaneous/UITextPadding.d.ts +1 -1
  34. package/dist/miscellaneous/UITransparencyMode.d.ts +26 -0
  35. package/dist/miscellaneous/asserts.d.ts +9 -9
  36. package/dist/miscellaneous/textTools.d.ts +4 -4
  37. package/dist/wrappers/UISceneWrapper.d.ts +21 -14
  38. package/dist/wrappers/UISolverWrapper.d.ts +185 -0
  39. package/package.json +7 -4
  40. package/dist/materials/UIMaterial.d.ts +0 -13
  41. package/dist/materials/UINineSliceMaterial.d.ts +0 -27
  42. package/dist/materials/UIProgressMaterial.d.ts +0 -29
  43. package/dist/miscellaneous/threeInstances.d.ts +0 -2
  44. package/dist/scalable/UIScalableMesh.d.ts +0 -16
  45. package/dist/scalable/UIScalablePlaneMesh.d.ts +0 -14
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  <p align="center">
2
2
  <h1 align="center">Laymur</h1>
3
3
  <p align="center">
4
- A TypeScript Three.js UI layout library with constraint-based positioning and rendering.
4
+ A constraint-based UI library for Three.js mobile advertisements
5
5
  </p>
6
6
  </p>
7
7
 
@@ -14,18 +14,19 @@
14
14
 
15
15
  ⚠️ **Early Alpha / Work in Progress** ⚠️
16
16
 
17
- This library is in very early development stage. APIs may change significantly.
17
+ This library is in early development. APIs may change.
18
18
 
19
- ## Features
19
+ ## What it does
20
20
 
21
- - 🎯 **Constraint-Based Layout** - Powerful Cassowary constraint solver for flexible positioning
22
- - 📐 **Anchor Points** - Flexible element positioning with configurable anchor points
23
- - 🖼️ **Rich Elements** - Images, text, scenes, and custom UI components
24
- - 📱 **Responsive Design** - Orientation-aware layouts that adapt to screen changes
25
- - ✨ **Micro-Transformations** - Lightweight animations and effects without constraint changes
26
- - 🎨 **Three.js Integration** - Native 3D scene rendering within UI elements
27
- - 📦 **Full TypeScript Support** - Complete type safety and IntelliSense
28
- - 🎪 **Event System** - Comprehensive interaction and lifecycle events
21
+ A compact UI library designed for Three.js mobile advertisements where bundle size matters. Uses constraint-based positioning to handle responsive layouts across different screen sizes and orientations.
22
+
23
+ - 📱 Constraint-based layout system
24
+ - 🖼️ Basic UI elements (images, text, progress bars)
25
+ - 📐 Responsive design for mobile ads
26
+ - 🎯 Lightweight animations
27
+ - 📦 TypeScript support
28
+
29
+ Originally built for mobile ad development scenarios where you need to keep the bundle small while supporting various screen configurations.
29
30
 
30
31
  ## Installation
31
32
 
@@ -33,348 +34,160 @@ This library is in very early development stage. APIs may change significantly.
33
34
  npm install laymur
34
35
  ```
35
36
 
36
- ## Requirements
37
-
38
- - Three.js ^0.175.0 (peer dependency)
39
- - Modern JavaScript environment with ES2020+ support
40
-
41
- ## Live Examples
42
-
43
- 🎮 **[Live Examples](https://jango-git.github.io/laymur/)** - Explore constraint-based layouts, proportional positioning, and responsive UI components in action.
37
+ Requires Three.js ^0.175.0 as a peer dependency.
44
38
 
45
- ## Quick Start
39
+ ## Quick Example
46
40
 
47
41
  ```typescript
48
42
  import { UIFullscreenLayer, UIImage, UIText, UIWidthConstraint } from 'laymur';
49
- import { WebGLRenderer, TextureLoader } from 'three';
43
+ import { WebGLRenderer, TextureLoader, Clock } from 'three';
50
44
 
51
- // Create renderer and fullscreen layer
52
45
  const renderer = new WebGLRenderer();
53
- const layer = new UIFullscreenLayer(1920, 1920); // Fixed design dimensions
54
-
55
- // Load a texture
56
- const texture = new TextureLoader().load('my-image.jpg');
57
-
58
- // Create UI elements
59
- const background = new UIImage(layer, texture, 0, 0);
60
- const title = new UIText(layer, 'Welcome to Laymur!', {
61
- maxWidth: 800,
62
- commonStyle: { fontSize: 48, color: '#ffffff' }
63
- }, 100, 100);
64
-
65
- // Add constraints for responsive layout
66
- new UIWidthConstraint(background, { width: layer.width });
46
+ const layer = new UIFullscreenLayer(1920, 1920);
47
+ const clock = new Clock();
48
+
49
+ const texture = new TextureLoader().load('background.jpg');
50
+ const background = new UIImage(layer, texture, { x: 0, y: 0 });
51
+ const title = new UIText(layer, 'Mobile Ad Title', {
52
+ x: 100,
53
+ y: 100,
54
+ maxWidth: 800
55
+ });
67
56
 
68
- // Render loop
69
57
  function animate() {
70
- const deltaTime = clock.getDelta();
71
- layer.render(renderer, deltaTime);
58
+ layer.render(renderer, clock.getDelta());
72
59
  requestAnimationFrame(animate);
73
60
  }
74
61
 
75
62
  animate();
76
63
  ```
77
64
 
78
- ## Core Concepts
65
+ ## Basic Components
79
66
 
80
67
  ### Layers
81
-
82
- Layers are containers that manage UI elements, constraint solving, and rendering:
83
-
84
- - **UIFullscreenLayer** - Automatic browser window integration with responsive scaling
85
- - **UILayer** - Base layer class for custom implementations
68
+ - **UIFullscreenLayer** - Handles browser window scaling
69
+ - **UILayer** - Base layer for custom setups
86
70
 
87
71
  ### Elements
88
-
89
- UI elements are the building blocks of your interface:
90
-
91
- - **UIAnchor** - Basic positioned point in 2D space
92
- - **UIImage** - Textured image display with color tinting
93
- - **UIText** - Dynamic text rendering with rich formatting
94
- - **UIScene** - Embedded 3D scene rendering
95
- - **UIElement** - Base class for custom elements
72
+ - **UIImage** - Display textures
73
+ - **UIText** - Text rendering with word wrapping
74
+ - **UIScene** - Embed 3D scenes
75
+ - **UIProgress** - Progress bars
76
+ - **UINineSline** - Scalable UI panels
77
+ - **UIAnchor** - Positioning points
96
78
 
97
79
  ### Constraints
98
-
99
- Constraints define relationships between elements for automatic layout:
100
-
101
- - **UIWidthConstraint** / **UIHeightConstraint** - Fixed dimensions
80
+ - **UIWidthConstraint** / **UIHeightConstraint** - Fixed sizes
102
81
  - **UIAspectConstraint** - Maintain aspect ratios
103
- - **UIHorizontalDistanceConstraint** / **UIVerticalDistanceConstraint** - Spacing between elements
82
+ - **UIHorizontalDistanceConstraint** / **UIVerticalDistanceConstraint** - Spacing
104
83
  - **UIHorizontalProportionConstraint** / **UIVerticalProportionConstraint** - Proportional sizing
105
- - **UICustomConstraint** - Custom mathematical relationships
106
-
107
- ## Layout System
108
84
 
109
- ### Constraint-Based Positioning
85
+ ## Constraint Layout
110
86
 
111
- Laymur uses the Cassowary constraint solving algorithm to automatically calculate element positions and sizes based on relationships you define:
87
+ The constraint system automatically calculates positions and sizes based on relationships you define:
112
88
 
113
89
  ```typescript
114
- import { UIImage, UIText, UIHorizontalDistanceConstraint, UIWidthConstraint } from 'laymur';
90
+ import { UIImage, UIHorizontalDistanceConstraint, UIWidthConstraint } from 'laymur';
115
91
 
116
- // Create elements
117
- const sidebar = new UIImage(layer, sidebarTexture, 0, 0);
118
- const content = new UIText(layer, 'Main content', {}, 0, 0);
92
+ const sidebar = new UIImage(layer, sidebarTexture, { x: 0, y: 0 });
93
+ const content = new UIImage(layer, contentTexture, { x: 0, y: 0 });
119
94
 
120
- // Define layout constraints
121
- new UIWidthConstraint(sidebar, { width: 300 }); // Fixed sidebar width
122
- new UIHorizontalDistanceConstraint(sidebar, content, {
123
- distance: 20, // 20px spacing
124
- anchorA: 1.0, // Right edge of sidebar
125
- anchorB: 0.0 // Left edge of content
126
- });
127
- ```
128
-
129
- ### Anchor Points
95
+ // Fixed sidebar width
96
+ new UIWidthConstraint(sidebar, { width: 300 });
130
97
 
131
- Elements support flexible anchor points for precise positioning control:
132
-
133
- ```typescript
134
- // Anchor values: 0.0 = left/top, 0.5 = center, 1.0 = right/bottom
135
- new UIHorizontalDistanceConstraint(elementA, elementB, {
136
- anchorA: 0.5, // Center of element A
137
- anchorB: 0.5, // Center of element B
138
- distance: 100 // 100px between centers
98
+ // 20px spacing between sidebar and content
99
+ new UIHorizontalDistanceConstraint(sidebar, content, {
100
+ distance: 20,
101
+ anchorA: 1.0, // Right edge of sidebar
102
+ anchorB: 0.0 // Left edge of content
139
103
  });
140
104
  ```
141
105
 
142
- ### Proportional Layouts
106
+ ## Responsive Design
143
107
 
144
- Create responsive layouts that maintain proportions:
108
+ Handle different orientations:
145
109
 
146
110
  ```typescript
147
- import { UIHorizontalProportionConstraint } from 'laymur';
111
+ import { UIOrientation } from 'laymur';
148
112
 
149
- // Make content area 3x wider than sidebar
150
- new UIHorizontalProportionConstraint(content, sidebar, {
151
- proportion: 3.0
113
+ // Different widths for landscape vs portrait
114
+ new UIWidthConstraint(sidebar, {
115
+ width: 300,
116
+ orientation: UIOrientation.HORIZONTAL
152
117
  });
153
- ```
154
-
155
- ## UI Elements
156
118
 
157
- ### UIImage - Textured Images
158
-
159
- Display and manipulate images with full control over appearance:
160
-
161
- ```typescript
162
- import { UIImage } from 'laymur';
163
- import { TextureLoader } from 'three';
164
-
165
- const texture = new TextureLoader().load('hero-image.jpg');
166
- const heroImage = new UIImage(layer, texture, 0, 0);
167
-
168
- // Modify appearance
169
- heroImage.color = 0xff8844; // Orange tint
170
- heroImage.opacity = 0.8; // Semi-transparent
171
- heroImage.transparency = true; // Enable alpha blending
119
+ new UIWidthConstraint(sidebar, {
120
+ width: 200,
121
+ orientation: UIOrientation.VERTICAL
122
+ });
172
123
  ```
173
124
 
174
- ### UIText - Dynamic Text Rendering
175
-
176
- Render text with automatic word wrapping and styling:
125
+ ## Text Rendering
177
126
 
178
127
  ```typescript
179
128
  import { UIText } from 'laymur';
180
129
 
181
- const description = new UIText(layer, {
182
- content: [
183
- { text: 'Welcome to ', style: { fontSize: 24, color: '#333333' } },
184
- { text: 'Laymur', style: { fontSize: 32, color: '#0066cc', fontWeight: 'bold' } },
185
- { text: '!', style: { fontSize: 24, color: '#333333' } }
186
- ]
187
- }, {
130
+ const text = new UIText(layer, [
131
+ { text: 'Download ', style: { fontSize: 24, color: '#333333' } },
132
+ { text: 'Now!', style: { fontSize: 32, color: '#ff0000', fontWeight: 'bold' } }
133
+ ], {
188
134
  maxWidth: 600,
189
- padding: { top: 20, left: 20, right: 20, bottom: 20 },
190
- commonStyle: { fontFamily: 'Arial, sans-serif' }
191
- });
192
-
193
- // Update content dynamically
194
- description.content = 'New text content';
195
- ```
196
-
197
- ### UIScene - Embedded 3D Scenes
198
-
199
- Render Three.js scenes directly within your UI:
200
-
201
- ```typescript
202
- import { UIScene, UISceneUpdateMode } from 'laymur';
203
- import { Scene, PerspectiveCamera, BoxGeometry, Mesh } from 'three';
204
-
205
- // Create 3D scene
206
- const scene3d = new Scene();
207
- const camera = new PerspectiveCamera(75, 1, 0.1, 1000);
208
- const cube = new Mesh(new BoxGeometry(), new MeshBasicMaterial({ color: 0x00ff00 }));
209
- scene3d.add(cube);
210
-
211
- // Embed in UI
212
- const sceneElement = new UIScene(layer, {
213
- width: 400,
214
- height: 300,
215
- scene: scene3d,
216
- camera: camera,
217
- updateMode: UISceneUpdateMode.EACH_FRAME,
218
- resolutionFactor: 1.0
135
+ padding: { top: 10, left: 10, right: 10, bottom: 10 }
219
136
  });
220
137
  ```
221
138
 
222
139
  ## Micro-Transformations
223
140
 
224
- Apply lightweight transformations independent of the constraint system:
141
+ Apply lightweight animations without affecting the constraint layout:
225
142
 
226
143
  ```typescript
227
- // Access micro-transformation system
228
144
  const element = new UIImage(layer, texture);
229
145
 
230
- // Apply transformations for animations or effects
231
- element.micro.x = 10; // Offset position
232
- element.micro.y = -5;
233
- element.micro.scaleX = 1.2; // Scale up horizontally
234
- element.micro.rotation = 0.1; // Rotate in radians
235
- element.micro.anchorX = 0.5; // Transform around center
236
- element.micro.anchorY = 0.5;
146
+ // Apply transformations for animations
147
+ element.micro.x = 10;
148
+ element.micro.scaleX = 1.2;
149
+ element.micro.rotation = 0.1;
150
+ element.micro.anchorX = 0.5;
237
151
 
238
- // Reset all transformations
152
+ // Reset transformations
239
153
  element.micro.reset();
240
154
  ```
241
155
 
242
156
  ## Event Handling
243
157
 
244
- ### Element Events
245
-
246
- Listen for user interactions and lifecycle events:
247
-
248
158
  ```typescript
249
- import { UIElementEvent } from 'laymur';
159
+ import { UIInputEvent, UIMode } from 'laymur';
250
160
 
251
161
  const button = new UIImage(layer, buttonTexture);
252
- button.mode = UIMode.INTERACTIVE; // Enable interaction
253
-
254
- button.on(UIElementEvent.CLICK, (x, y, element) => {
255
- console.log(`Button clicked at ${x}, ${y}`);
256
- // Handle button click
257
- });
258
- ```
259
-
260
- ### Layer Events
261
-
262
- Respond to layer-level changes:
162
+ button.mode = UIMode.INTERACTIVE;
263
163
 
264
- ```typescript
265
- import { UILayerEvent } from 'laymur';
266
-
267
- layer.on(UILayerEvent.ORIENTATION_CHANGE, (orientation, layer) => {
268
- console.log('Orientation changed to:', orientation);
269
- // Adjust layout for new orientation
270
- });
271
-
272
- layer.on(UILayerEvent.MODE_CHANGE, (mode, layer) => {
273
- console.log('Layer mode changed to:', mode);
164
+ button.on(UIInputEvent.CLICK, (x, y, element) => {
165
+ console.log('Button clicked');
274
166
  });
275
167
  ```
276
168
 
277
- ## Advanced Features
278
-
279
- ### Custom Constraints
280
-
281
- Create complex mathematical relationships:
282
-
283
- ```typescript
284
- import { UICustomConstraint, UIExpression } from 'laymur';
285
-
286
- // Create custom constraint: elementA.width = elementB.width + elementC.height * 2
287
- const lhs = new UIExpression(0, [[elementA.wVariable, 1]]);
288
- const rhs = new UIExpression(0, [
289
- [elementB.wVariable, 1],
290
- [elementC.hVariable, 2]
291
- ]);
292
-
293
- new UICustomConstraint(layer, lhs, rhs, {
294
- priority: UIPriority.P2,
295
- relation: UIRelation.EQUAL
296
- });
297
- ```
298
-
299
- ### Responsive Design
300
-
301
- Handle different screen orientations and sizes:
302
-
303
- ```typescript
304
- import { UIOrientation } from 'laymur';
305
-
306
- // Constraints that only apply in specific orientations
307
- new UIWidthConstraint(sidebar, {
308
- width: 300,
309
- orientation: UIOrientation.HORIZONTAL // Only in landscape
310
- });
311
-
312
- new UIWidthConstraint(sidebar, {
313
- width: 200,
314
- orientation: UIOrientation.VERTICAL // Only in portrait
315
- });
316
- ```
317
-
318
- ## API Reference
319
-
320
- ### Priority Levels
321
-
322
- Constraint priorities from highest to lowest:
323
-
324
- - `UIPriority.P0` - Required constraints (highest)
325
- - `UIPriority.P1` - Strong constraints
326
- - `UIPriority.P2` - Medium-strong constraints
327
- - `UIPriority.P3` - Medium constraints
328
- - `UIPriority.P4` - Medium-weak constraints
329
- - `UIPriority.P5` - Weak constraints
330
- - `UIPriority.P6` - Very weak constraints
331
- - `UIPriority.P7` - Suggestion constraints (lowest)
332
-
333
- ### Relation Types
334
-
335
- Mathematical relationships for constraints:
336
-
337
- - `UIRelation.EQUAL` - Left-hand side equals right-hand side
338
- - `UIRelation.LESS_THAN` - Left-hand side ≤ right-hand side
339
- - `UIRelation.GREATER_THAN` - Left-hand side ≥ right-hand side
340
-
341
- ### UI Modes
342
-
343
- Element visibility and interaction states:
169
+ ## Live Examples
344
170
 
345
- - `UIMode.HIDDEN` - Not rendered, no interaction
346
- - `UIMode.VISIBLE` - Rendered, no interaction
347
- - `UIMode.INTERACTIVE` - Rendered with interaction
171
+ 🎮 **[Live Examples](https://jango-git.github.io/laymur/)** - See constraint-based layouts and responsive components in action.
348
172
 
349
173
  ## Addons
350
174
 
351
175
  ### laymur-animations
352
176
 
353
- A collection of standard UI animations for smooth, performant motion effects built on top of GSAP.
177
+ Animation library built on GSAP for common UI effects:
354
178
 
355
179
  - **GitHub**: [https://github.com/jango-git/laymur-animations](https://github.com/jango-git/laymur-animations)
356
180
  - **NPM**: [https://www.npmjs.com/package/laymur-animations](https://www.npmjs.com/package/laymur-animations)
357
181
 
358
- Includes common animations like appear/disappear effects, pulsing, jumping, spinning, and click feedback for Laymur UI elements.
182
+ ## Notes
359
183
 
360
- ## Contributing
361
-
362
- Contributions are welcome! Please feel free to submit issues and pull requests.
363
-
364
- 1. Fork the repository
365
- 2. Create a feature branch
366
- 3. Make your changes with tests
367
- 4. Submit a pull request
184
+ - This was built specifically for mobile ad development where bundle size is important
185
+ - The constraint solver is based on Cassowary algorithm via Kiwi.js
186
+ - Currently in alpha - expect API changes
187
+ - Works best for relatively simple UI layouts
368
188
 
369
189
  ## License
370
190
 
371
- Laymur is licensed under the [MIT License](./LICENSE).
372
-
373
- It uses [Kiwi.js](https://github.com/lume/kiwi) as its constraint solving engine — a fast and lightweight Cassowary implementation in TypeScript.
374
-
375
- Kiwi.js is licensed under the [BSD-3-Clause License](https://github.com/lume/kiwi/blob/main/LICENSE).
376
-
377
- It is built on top of [Three.js](https://threejs.org/) for 3D rendering support — a cross-browser JavaScript library for creating and displaying 3D graphics.
191
+ MIT © [jango](https://github.com/jango-git)
378
192
 
379
- Three.js is licensed under the [MIT License](https://github.com/mrdoob/three.js/blob/dev/LICENSE).
380
- All licenses used are compatible and permissive.
193
+ Uses [Kiwi.js](https://github.com/lume/kiwi) (BSD-3-Clause) for constraint solving and [Three.js](https://threejs.org/) (MIT) for 3D rendering.
@@ -17,7 +17,7 @@ import type { UIRelation } from "../miscellaneous/UIRelation";
17
17
  *
18
18
  * @template T - The type of values for horizontal and vertical properties
19
19
  */
20
- export interface UIType2D<T> {
20
+ interface UIType2D<T> {
21
21
  /** Horizontal (x-axis) value. */
22
22
  h?: T;
23
23
  /** Vertical (y-axis) value. */
@@ -13,7 +13,7 @@ export interface UICoverConstraintBuilderOptions {
13
13
  keepActiveAspect: boolean;
14
14
  /** Horizontal anchor point (0.0 = left, 0.5 = center, 1.0 = right) */
15
15
  anchorH: number;
16
- /** Vertical anchor point (0.0 = bottom, 0.5 = center, 1.0 = top) */
16
+ /** Vertical anchor point (0.0 = top, 0.5 = center, 1.0 = bottom) */
17
17
  anchorV: number;
18
18
  /** Orientation context for constraint calculations */
19
19
  orientation: UIOrientation;
@@ -29,6 +29,8 @@ export interface UICoverConstraintBuilderOptions {
29
29
  * - Positioned at the specified anchor point within the passive element
30
30
  * - Sized to be at least as large as the passive element in both dimensions
31
31
  * - Scaled proportionally to maintain aspect ratio (if enabled)
32
+ *
33
+ * The constraints ensure: passive.dimension * 1 ≤ active.dimension (active covers passive)
32
34
  */
33
35
  export declare class UICoverConstraintBuilder {
34
36
  /**
@@ -13,7 +13,7 @@ export interface UIFitConstraintBuilderOptions {
13
13
  keepActiveAspect: boolean;
14
14
  /** Horizontal anchor point (0.0 = left, 0.5 = center, 1.0 = right) */
15
15
  anchorH: number;
16
- /** Vertical anchor point (0.0 = bottom, 0.5 = center, 1.0 = top) */
16
+ /** Vertical anchor point (0.0 = top, 0.5 = center, 1.0 = bottom) */
17
17
  anchorV: number;
18
18
  /** Orientation context for constraint calculations */
19
19
  orientation: UIOrientation;
@@ -29,6 +29,8 @@ export interface UIFitConstraintBuilderOptions {
29
29
  * - Positioned at the specified anchor point within the passive element
30
30
  * - Sized to fit entirely within the passive element in both dimensions
31
31
  * - Scaled proportionally to maintain aspect ratio (if enabled)
32
+ *
33
+ * The constraints ensure: passive.dimension * 1 ≥ active.dimension (active fits within passive)
32
34
  */
33
35
  export declare class UIFitConstraintBuilder {
34
36
  /**
@@ -54,7 +54,6 @@ export declare class UIAspectConstraint extends UISingleParameterConstraint {
54
54
  * This enforces the relationship: width = height * aspect
55
55
  *
56
56
  * @returns The UIExpression representing the constraint equation
57
- * @private
58
57
  */
59
58
  private buildLHS;
60
59
  }
@@ -23,6 +23,9 @@ export declare abstract class UIConstraint {
23
23
  /**
24
24
  * Creates a new UIConstraint instance.
25
25
  *
26
+ * Automatically connects to the layer's constraint solver for managing
27
+ * layout relationships and constraint operations.
28
+ *
26
29
  * @param layer - The UI layer that contains this constraint
27
30
  */
28
31
  constructor(layer: UILayer);
@@ -88,7 +88,6 @@ export declare class UIHorizontalDistanceConstraint extends UISingleParameterCon
88
88
  * For plane elements, the anchor determines the reference point within the element's width.
89
89
  *
90
90
  * @returns The UIExpression representing the horizontal distance calculation
91
- * @private
92
91
  */
93
92
  private buildLHS;
94
93
  }
@@ -5,7 +5,7 @@ import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
5
5
  * Configuration options for UIHorizontalProportionConstraint creation.
6
6
  */
7
7
  export interface UIHorizontalProportionConstraintOptions extends UISingleParameterConstraintOptions {
8
- /** The proportional relationship between element widths (elementA.width = elementB.width * proportion). */
8
+ /** The proportional relationship between element widths (elementA.width * proportion = elementB.width). */
9
9
  proportion: number;
10
10
  }
11
11
  /**
@@ -46,7 +46,7 @@ export declare class UIHorizontalProportionConstraint extends UISingleParameterC
46
46
  constructor(a: UIPlaneElement, b: UIPlaneElement, options?: Partial<UIHorizontalProportionConstraintOptions>);
47
47
  /**
48
48
  * Gets the current proportion value being enforced.
49
- * @returns The proportion ratio (elementA.width = elementB.width * proportion)
49
+ * @returns The proportion ratio (elementA.width * proportion = elementB.width)
50
50
  */
51
51
  get proportion(): number;
52
52
  /**
@@ -61,7 +61,6 @@ export declare class UIHorizontalProportionConstraint extends UISingleParameterC
61
61
  * This enforces the relationship: elementA.width * proportion = elementB.width
62
62
  *
63
63
  * @returns The UIExpression representing the proportional width relationship
64
- * @private
65
64
  */
66
65
  private buildRHS;
67
66
  }
@@ -101,8 +101,6 @@ export declare abstract class UISingleParameterConstraint extends UIConstraint {
101
101
  *
102
102
  * Updates the constraint's enabled state in the solver based on the
103
103
  * current orientation and the constraint's orientation setting.
104
- *
105
- * @private
106
104
  */
107
105
  private readonly onOrientationChange;
108
106
  }
@@ -88,7 +88,6 @@ export declare class UIVerticalDistanceConstraint extends UISingleParameterConst
88
88
  * For plane elements, the anchor determines the reference point within the element's height.
89
89
  *
90
90
  * @returns The UIExpression representing the vertical distance calculation
91
- * @private
92
91
  */
93
92
  private buildLHS;
94
93
  }
@@ -5,7 +5,7 @@ import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
5
5
  * Configuration options for UIVerticalProportionConstraint creation.
6
6
  */
7
7
  export interface UIVerticalProportionConstraintOptions extends UISingleParameterConstraintOptions {
8
- /** The proportional relationship between element heights (elementA.height = elementB.height * proportion). */
8
+ /** The proportional relationship between element heights (elementA.height * proportion = elementB.height). */
9
9
  proportion: number;
10
10
  }
11
11
  /**
@@ -46,7 +46,7 @@ export declare class UIVerticalProportionConstraint extends UISingleParameterCon
46
46
  constructor(a: UIPlaneElement, b: UIPlaneElement, options?: Partial<UIVerticalProportionConstraintOptions>);
47
47
  /**
48
48
  * Gets the current proportion value being enforced.
49
- * @returns The proportion ratio (elementA.height = elementB.height * proportion)
49
+ * @returns The proportion ratio (elementA.height * proportion = elementB.height)
50
50
  */
51
51
  get proportion(): number;
52
52
  /**
@@ -61,7 +61,6 @@ export declare class UIVerticalProportionConstraint extends UISingleParameterCon
61
61
  * This enforces the relationship: elementA.height * proportion = elementB.height
62
62
  *
63
63
  * @returns The UIExpression representing the proportional height relationship
64
- * @private
65
64
  */
66
65
  private buildRHS;
67
66
  }
@@ -1,6 +1,12 @@
1
1
  import type { UILayer } from "../layers/UILayer";
2
2
  import { type UIPlaneElement } from "../miscellaneous/asserts";
3
3
  import { UIAnchor } from "./UIAnchor";
4
+ export interface UIDummyOptions {
5
+ x: number;
6
+ y: number;
7
+ width: number;
8
+ height: number;
9
+ }
4
10
  /**
5
11
  * Abstract UI element that extends UIAnchor with dimensions but without rendering.
6
12
  *
@@ -35,7 +41,7 @@ export declare abstract class UIDummy extends UIAnchor implements UIPlaneElement
35
41
  * @throws Will throw an error if width or height are not valid positive numbers
36
42
  * @see {@link assertValidPositiveNumber}
37
43
  */
38
- constructor(layer: UILayer, x: number, y: number, width?: number, height?: number);
44
+ constructor(layer: UILayer, options?: Partial<UIDummyOptions>);
39
45
  /**
40
46
  * Gets the current width value from the solver.
41
47
  * @returns The current width dimension