laymur 0.1.73 → 0.2.1

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 (90) hide show
  1. package/README.md +367 -0
  2. package/dist/builders/UIConstraint2DBuilder.d.ts +130 -0
  3. package/dist/composer/UIComposer.d.ts +0 -0
  4. package/dist/composer/UIFullscreenQuad.d.ts +0 -0
  5. package/dist/composer/UIPass.d.ts +0 -0
  6. package/dist/constraints/UIAspectConstraint.d.ts +60 -0
  7. package/dist/constraints/UIConstraint.d.ts +29 -0
  8. package/dist/constraints/UICoverConstraint.d.ts +0 -0
  9. package/dist/constraints/UICustomConstraint.d.ts +60 -0
  10. package/dist/constraints/UIFitConstraint.d.ts +0 -0
  11. package/dist/constraints/UIHeightConstraint.d.ts +49 -0
  12. package/dist/constraints/UIHorizontalDistanceConstraint.d.ts +94 -0
  13. package/dist/constraints/UIHorizontalProportionConstraint.d.ts +67 -0
  14. package/dist/constraints/UISingleParameterConstraint.d.ts +108 -0
  15. package/dist/constraints/UIVerticalDistanceConstraint.d.ts +94 -0
  16. package/dist/constraints/UIVerticalProportionConstraint.d.ts +67 -0
  17. package/dist/constraints/UIWidthConstraint.d.ts +49 -0
  18. package/dist/elements/UIAnchor.d.ts +78 -0
  19. package/dist/elements/UIDummy.d.ts +72 -0
  20. package/dist/elements/UIElement.d.ts +121 -0
  21. package/dist/elements/UIImage.d.ts +88 -0
  22. package/dist/elements/UINineSline.d.ts +0 -0
  23. package/dist/elements/UIProgress.d.ts +39 -0
  24. package/dist/elements/UIScene.d.ts +199 -0
  25. package/dist/elements/UIText.d.ts +157 -0
  26. package/dist/index.d.ts +29 -31
  27. package/dist/index.js +3320 -3251
  28. package/dist/index.js.map +1 -1
  29. package/dist/index.min.js +1 -1
  30. package/dist/index.min.js.map +1 -1
  31. package/dist/layers/UIFullscreenLayer.d.ts +112 -0
  32. package/dist/layers/UILayer.d.ts +144 -0
  33. package/dist/materials/UIInstancedMaterial.d.ts +0 -0
  34. package/dist/materials/UIMaterial.d.ts +13 -0
  35. package/dist/materials/UINineSliceMaterial.d.ts +0 -0
  36. package/dist/{Materials → materials}/UIProgressMaterial.d.ts +0 -4
  37. package/dist/miscellaneous/UIExpression.d.ts +117 -0
  38. package/dist/miscellaneous/UIMicro.d.ts +130 -0
  39. package/dist/{Miscellaneous → miscellaneous}/UIOrientation.d.ts +2 -9
  40. package/dist/miscellaneous/UIPriority.d.ts +56 -0
  41. package/dist/miscellaneous/UIRelation.d.ts +43 -0
  42. package/dist/miscellaneous/UITextPadding.d.ts +7 -0
  43. package/dist/miscellaneous/UITextSpan.d.ts +6 -0
  44. package/dist/miscellaneous/UITextStyle.d.ts +18 -0
  45. package/dist/miscellaneous/asserts.d.ts +112 -0
  46. package/dist/miscellaneous/textInterfaces.d.ts +19 -0
  47. package/dist/miscellaneous/textTools.d.ts +12 -0
  48. package/dist/scalable/UIScalableMesh.d.ts +16 -0
  49. package/dist/scalable/UIScalablePlaneMesh.d.ts +14 -0
  50. package/dist/wrappers/UISceneWrapper.d.ts +18 -0
  51. package/dist/wrappers/UISolverWrapper.d.ts +29 -0
  52. package/package.json +3 -3
  53. package/dist/Builders/UIConstraint2DBuilder.d.ts +0 -42
  54. package/dist/Builders/UIConstraintContainerBuilder.d.ts +0 -20
  55. package/dist/Builders/UIConstraintStackBuilder.d.ts +0 -24
  56. package/dist/Constraints/UIAspectConstraint.d.ts +0 -56
  57. package/dist/Constraints/UIConstraint.d.ts +0 -32
  58. package/dist/Constraints/UIConstraintPower.d.ts +0 -57
  59. package/dist/Constraints/UIConstraintRule.d.ts +0 -46
  60. package/dist/Constraints/UICoverConstraint.d.ts +0 -72
  61. package/dist/Constraints/UIFitConstraint.d.ts +0 -72
  62. package/dist/Constraints/UIHeightConstraint.d.ts +0 -55
  63. package/dist/Constraints/UIHorizontalDistanceConstraint.d.ts +0 -63
  64. package/dist/Constraints/UIHorizontalProportionConstraint.d.ts +0 -58
  65. package/dist/Constraints/UIVerticalDistanceConstraint.d.ts +0 -63
  66. package/dist/Constraints/UIVerticalProportionConstraint.d.ts +0 -58
  67. package/dist/Constraints/UIWidthConstraint.d.ts +0 -55
  68. package/dist/Elements/UIAnchor.d.ts +0 -66
  69. package/dist/Elements/UIDummy.d.ts +0 -21
  70. package/dist/Elements/UIElement.d.ts +0 -134
  71. package/dist/Elements/UIImage.d.ts +0 -57
  72. package/dist/Elements/UIProgress.d.ts +0 -127
  73. package/dist/Elements/UIScene.d.ts +0 -141
  74. package/dist/Elements/UIText.d.ts +0 -76
  75. package/dist/Layers/UIFullScreenLayer.d.ts +0 -13
  76. package/dist/Layers/UILayer.d.ts +0 -68
  77. package/dist/Materials/UIMaterial.d.ts +0 -13
  78. package/dist/Miscellaneous/UIBlending.d.ts +0 -7
  79. package/dist/Miscellaneous/UIMicro.d.ts +0 -176
  80. package/dist/Miscellaneous/UITextInterfaces.d.ts +0 -49
  81. package/dist/Miscellaneous/asserts.d.ts +0 -5
  82. package/dist/Miscellaneous/math.d.ts +0 -1
  83. package/dist/Miscellaneous/microTransformationTools.d.ts +0 -3
  84. package/dist/Miscellaneous/symbols.d.ts +0 -1
  85. package/dist/Miscellaneous/textTools.d.ts +0 -9
  86. package/dist/Passes/UIComposer.d.ts +0 -114
  87. package/dist/Passes/UIFullScreenQuad.d.ts +0 -51
  88. package/dist/Passes/UIPass.d.ts +0 -43
  89. /package/dist/{Miscellaneous → miscellaneous}/UIMode.d.ts +0 -0
  90. /package/dist/{Miscellaneous → miscellaneous}/threeInstances.d.ts +0 -0
package/README.md ADDED
@@ -0,0 +1,367 @@
1
+ <p align="center">
2
+ <h1 align="center">Laymur</h1>
3
+ <p align="center">
4
+ A TypeScript Three.js UI layout library with constraint-based positioning and rendering.
5
+ </p>
6
+ </p>
7
+
8
+ <p align="center">
9
+ <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
10
+ <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-%5E5.8.0-blue" alt="TypeScript"></a>
11
+ <a href="https://threejs.org/"><img src="https://img.shields.io/badge/Three.js-%5E0.175.0-green" alt="Three.js"></a>
12
+ </p>
13
+
14
+ ⚠️ **Early Alpha / Work in Progress** ⚠️
15
+
16
+ This library is in very early development stage. APIs may change significantly.
17
+
18
+ ## Features
19
+
20
+ - 🎯 **Constraint-Based Layout** - Powerful Cassowary constraint solver for flexible positioning
21
+ - 📐 **Anchor Points** - Flexible element positioning with configurable anchor points
22
+ - 🖼️ **Rich Elements** - Images, text, scenes, and custom UI components
23
+ - 📱 **Responsive Design** - Orientation-aware layouts that adapt to screen changes
24
+ - ✨ **Micro-Transformations** - Lightweight animations and effects without constraint changes
25
+ - 🎨 **Three.js Integration** - Native 3D scene rendering within UI elements
26
+ - 📦 **Full TypeScript Support** - Complete type safety and IntelliSense
27
+ - 🎪 **Event System** - Comprehensive interaction and lifecycle events
28
+
29
+ ## Installation
30
+
31
+ ```bash
32
+ npm install laymur
33
+ ```
34
+
35
+ ## Requirements
36
+
37
+ - Three.js ^0.175.0 (peer dependency)
38
+ - Modern JavaScript environment with ES2020+ support
39
+
40
+ ## Quick Start
41
+
42
+ ```typescript
43
+ import { UIFullscreenLayer, UIImage, UIText, UIWidthConstraint } from 'laymur';
44
+ import { WebGLRenderer, TextureLoader } from 'three';
45
+
46
+ // Create renderer and fullscreen layer
47
+ const renderer = new WebGLRenderer();
48
+ const layer = new UIFullscreenLayer(1920, 1920); // Fixed design dimensions
49
+
50
+ // Load a texture
51
+ const texture = new TextureLoader().load('my-image.jpg');
52
+
53
+ // Create UI elements
54
+ const background = new UIImage(layer, texture, 0, 0);
55
+ const title = new UIText(layer, 'Welcome to Laymur!', {
56
+ maxWidth: 800,
57
+ commonStyle: { fontSize: 48, color: '#ffffff' }
58
+ }, 100, 100);
59
+
60
+ // Add constraints for responsive layout
61
+ new UIWidthConstraint(background, { width: layer.width });
62
+
63
+ // Render loop
64
+ function animate() {
65
+ const deltaTime = clock.getDelta();
66
+ layer.render(renderer, deltaTime);
67
+ requestAnimationFrame(animate);
68
+ }
69
+
70
+ animate();
71
+ ```
72
+
73
+ ## Core Concepts
74
+
75
+ ### Layers
76
+
77
+ Layers are containers that manage UI elements, constraint solving, and rendering:
78
+
79
+ - **UIFullscreenLayer** - Automatic browser window integration with responsive scaling
80
+ - **UILayer** - Base layer class for custom implementations
81
+
82
+ ### Elements
83
+
84
+ UI elements are the building blocks of your interface:
85
+
86
+ - **UIAnchor** - Basic positioned point in 2D space
87
+ - **UIImage** - Textured image display with color tinting
88
+ - **UIText** - Dynamic text rendering with rich formatting
89
+ - **UIScene** - Embedded 3D scene rendering
90
+ - **UIElement** - Base class for custom elements
91
+
92
+ ### Constraints
93
+
94
+ Constraints define relationships between elements for automatic layout:
95
+
96
+ - **UIWidthConstraint** / **UIHeightConstraint** - Fixed dimensions
97
+ - **UIAspectConstraint** - Maintain aspect ratios
98
+ - **UIHorizontalDistanceConstraint** / **UIVerticalDistanceConstraint** - Spacing between elements
99
+ - **UIHorizontalProportionConstraint** / **UIVerticalProportionConstraint** - Proportional sizing
100
+ - **UICustomConstraint** - Custom mathematical relationships
101
+
102
+ ## Layout System
103
+
104
+ ### Constraint-Based Positioning
105
+
106
+ Laymur uses the Cassowary constraint solving algorithm to automatically calculate element positions and sizes based on relationships you define:
107
+
108
+ ```typescript
109
+ import { UIImage, UIText, UIHorizontalDistanceConstraint, UIWidthConstraint } from 'laymur';
110
+
111
+ // Create elements
112
+ const sidebar = new UIImage(layer, sidebarTexture, 0, 0);
113
+ const content = new UIText(layer, 'Main content', {}, 0, 0);
114
+
115
+ // Define layout constraints
116
+ new UIWidthConstraint(sidebar, { width: 300 }); // Fixed sidebar width
117
+ new UIHorizontalDistanceConstraint(sidebar, content, {
118
+ distance: 20, // 20px spacing
119
+ anchorA: 1.0, // Right edge of sidebar
120
+ anchorB: 0.0 // Left edge of content
121
+ });
122
+ ```
123
+
124
+ ### Anchor Points
125
+
126
+ Elements support flexible anchor points for precise positioning control:
127
+
128
+ ```typescript
129
+ // Anchor values: 0.0 = left/top, 0.5 = center, 1.0 = right/bottom
130
+ new UIHorizontalDistanceConstraint(elementA, elementB, {
131
+ anchorA: 0.5, // Center of element A
132
+ anchorB: 0.5, // Center of element B
133
+ distance: 100 // 100px between centers
134
+ });
135
+ ```
136
+
137
+ ### Proportional Layouts
138
+
139
+ Create responsive layouts that maintain proportions:
140
+
141
+ ```typescript
142
+ import { UIHorizontalProportionConstraint } from 'laymur';
143
+
144
+ // Make content area 3x wider than sidebar
145
+ new UIHorizontalProportionConstraint(content, sidebar, {
146
+ proportion: 3.0
147
+ });
148
+ ```
149
+
150
+ ## UI Elements
151
+
152
+ ### UIImage - Textured Images
153
+
154
+ Display and manipulate images with full control over appearance:
155
+
156
+ ```typescript
157
+ import { UIImage } from 'laymur';
158
+ import { TextureLoader } from 'three';
159
+
160
+ const texture = new TextureLoader().load('hero-image.jpg');
161
+ const heroImage = new UIImage(layer, texture, 0, 0);
162
+
163
+ // Modify appearance
164
+ heroImage.color = 0xff8844; // Orange tint
165
+ heroImage.opacity = 0.8; // Semi-transparent
166
+ heroImage.transparency = true; // Enable alpha blending
167
+ ```
168
+
169
+ ### UIText - Dynamic Text Rendering
170
+
171
+ Render text with automatic word wrapping and styling:
172
+
173
+ ```typescript
174
+ import { UIText } from 'laymur';
175
+
176
+ const description = new UIText(layer, {
177
+ content: [
178
+ { text: 'Welcome to ', style: { fontSize: 24, color: '#333333' } },
179
+ { text: 'Laymur', style: { fontSize: 32, color: '#0066cc', fontWeight: 'bold' } },
180
+ { text: '!', style: { fontSize: 24, color: '#333333' } }
181
+ ]
182
+ }, {
183
+ maxWidth: 600,
184
+ padding: { top: 20, left: 20, right: 20, bottom: 20 },
185
+ commonStyle: { fontFamily: 'Arial, sans-serif' }
186
+ });
187
+
188
+ // Update content dynamically
189
+ description.content = 'New text content';
190
+ ```
191
+
192
+ ### UIScene - Embedded 3D Scenes
193
+
194
+ Render Three.js scenes directly within your UI:
195
+
196
+ ```typescript
197
+ import { UIScene, UISceneUpdateMode } from 'laymur';
198
+ import { Scene, PerspectiveCamera, BoxGeometry, Mesh } from 'three';
199
+
200
+ // Create 3D scene
201
+ const scene3d = new Scene();
202
+ const camera = new PerspectiveCamera(75, 1, 0.1, 1000);
203
+ const cube = new Mesh(new BoxGeometry(), new MeshBasicMaterial({ color: 0x00ff00 }));
204
+ scene3d.add(cube);
205
+
206
+ // Embed in UI
207
+ const sceneElement = new UIScene(layer, {
208
+ width: 400,
209
+ height: 300,
210
+ scene: scene3d,
211
+ camera: camera,
212
+ updateMode: UISceneUpdateMode.EACH_FRAME,
213
+ resolutionFactor: 1.0
214
+ });
215
+ ```
216
+
217
+ ## Micro-Transformations
218
+
219
+ Apply lightweight transformations independent of the constraint system:
220
+
221
+ ```typescript
222
+ // Access micro-transformation system
223
+ const element = new UIImage(layer, texture);
224
+
225
+ // Apply transformations for animations or effects
226
+ element.micro.x = 10; // Offset position
227
+ element.micro.y = -5;
228
+ element.micro.scaleX = 1.2; // Scale up horizontally
229
+ element.micro.rotation = 0.1; // Rotate in radians
230
+ element.micro.anchorX = 0.5; // Transform around center
231
+ element.micro.anchorY = 0.5;
232
+
233
+ // Reset all transformations
234
+ element.micro.reset();
235
+ ```
236
+
237
+ ## Event Handling
238
+
239
+ ### Element Events
240
+
241
+ Listen for user interactions and lifecycle events:
242
+
243
+ ```typescript
244
+ import { UIElementEvent } from 'laymur';
245
+
246
+ const button = new UIImage(layer, buttonTexture);
247
+ button.mode = UIMode.INTERACTIVE; // Enable interaction
248
+
249
+ button.on(UIElementEvent.CLICK, (x, y, element) => {
250
+ console.log(`Button clicked at ${x}, ${y}`);
251
+ // Handle button click
252
+ });
253
+ ```
254
+
255
+ ### Layer Events
256
+
257
+ Respond to layer-level changes:
258
+
259
+ ```typescript
260
+ import { UILayerEvent } from 'laymur';
261
+
262
+ layer.on(UILayerEvent.ORIENTATION_CHANGE, (orientation, layer) => {
263
+ console.log('Orientation changed to:', orientation);
264
+ // Adjust layout for new orientation
265
+ });
266
+
267
+ layer.on(UILayerEvent.MODE_CHANGE, (mode, layer) => {
268
+ console.log('Layer mode changed to:', mode);
269
+ });
270
+ ```
271
+
272
+ ## Advanced Features
273
+
274
+ ### Custom Constraints
275
+
276
+ Create complex mathematical relationships:
277
+
278
+ ```typescript
279
+ import { UICustomConstraint, UIExpression } from 'laymur';
280
+
281
+ // Create custom constraint: elementA.width = elementB.width + elementC.height * 2
282
+ const lhs = new UIExpression(0, [[elementA.wVariable, 1]]);
283
+ const rhs = new UIExpression(0, [
284
+ [elementB.wVariable, 1],
285
+ [elementC.hVariable, 2]
286
+ ]);
287
+
288
+ new UICustomConstraint(layer, lhs, rhs, {
289
+ priority: UIPriority.P2,
290
+ relation: UIRelation.EQUAL
291
+ });
292
+ ```
293
+
294
+ ### Responsive Design
295
+
296
+ Handle different screen orientations and sizes:
297
+
298
+ ```typescript
299
+ import { UIOrientation } from 'laymur';
300
+
301
+ // Constraints that only apply in specific orientations
302
+ new UIWidthConstraint(sidebar, {
303
+ width: 300,
304
+ orientation: UIOrientation.HORIZONTAL // Only in landscape
305
+ });
306
+
307
+ new UIWidthConstraint(sidebar, {
308
+ width: 200,
309
+ orientation: UIOrientation.VERTICAL // Only in portrait
310
+ });
311
+ ```
312
+
313
+ ## API Reference
314
+
315
+ ### Priority Levels
316
+
317
+ Constraint priorities from highest to lowest:
318
+
319
+ - `UIPriority.P0` - Required constraints (highest)
320
+ - `UIPriority.P1` - Strong constraints
321
+ - `UIPriority.P2` - Medium-strong constraints
322
+ - `UIPriority.P3` - Medium constraints
323
+ - `UIPriority.P4` - Medium-weak constraints
324
+ - `UIPriority.P5` - Weak constraints
325
+ - `UIPriority.P6` - Very weak constraints
326
+ - `UIPriority.P7` - Suggestion constraints (lowest)
327
+
328
+ ### Relation Types
329
+
330
+ Mathematical relationships for constraints:
331
+
332
+ - `UIRelation.EQUAL` - Left-hand side equals right-hand side
333
+ - `UIRelation.LESS_THAN` - Left-hand side ≤ right-hand side
334
+ - `UIRelation.GREATER_THAN` - Left-hand side ≥ right-hand side
335
+
336
+ ### UI Modes
337
+
338
+ Element visibility and interaction states:
339
+
340
+ - `UIMode.HIDDEN` - Not rendered, no interaction
341
+ - `UIMode.VISIBLE` - Rendered, no interaction
342
+ - `UIMode.INTERACTIVE` - Rendered with interaction
343
+
344
+ ## Contributing
345
+
346
+ Contributions are welcome! Please feel free to submit issues and pull requests.
347
+
348
+ 1. Fork the repository
349
+ 2. Create a feature branch
350
+ 3. Make your changes with tests
351
+ 4. Submit a pull request
352
+
353
+ ## License
354
+
355
+ Laymur is licensed under the [MIT License](./LICENSE).
356
+
357
+ It uses [Kiwi.js](https://github.com/lume/kiwi) as its constraint solving engine — a fast and lightweight Cassowary implementation in TypeScript.
358
+
359
+ Kiwi.js is licensed under the [BSD-3-Clause License](https://github.com/lume/kiwi/blob/main/LICENSE).
360
+ The MIT and BSD-3-Clause licenses are [compatible](https://opensource.org/license/bsd-3-clause/) and permissive.
361
+
362
+ ## Credits
363
+
364
+ - Constraint solving powered by [Kiwi.js](https://github.com/lume/kiwi)
365
+ - Built with [Three.js](https://threejs.org/) for 3D rendering support
366
+ - Event system powered by [eventail](https://www.npmjs.com/package/eventail)
367
+ - Mathematical foundations based on the Cassowary constraint solving algorithm
@@ -0,0 +1,130 @@
1
+ import { UIHeightConstraint } from "../constraints/UIHeightConstraint";
2
+ import { UIHorizontalDistanceConstraint } from "../constraints/UIHorizontalDistanceConstraint";
3
+ import { UIHorizontalProportionConstraint } from "../constraints/UIHorizontalProportionConstraint";
4
+ import { UIVerticalDistanceConstraint } from "../constraints/UIVerticalDistanceConstraint";
5
+ import { UIVerticalProportionConstraint } from "../constraints/UIVerticalProportionConstraint";
6
+ import { UIWidthConstraint } from "../constraints/UIWidthConstraint";
7
+ import type { UIElement } from "../elements/UIElement";
8
+ import type { UIPlaneElement, UIPointElement } from "../miscellaneous/asserts";
9
+ import type { UIOrientation } from "../miscellaneous/UIOrientation";
10
+ import type { UIPriority } from "../miscellaneous/UIPriority";
11
+ import type { UIRelation } from "../miscellaneous/UIRelation";
12
+ /**
13
+ * Generic 2D type for specifying horizontal and vertical values.
14
+ *
15
+ * This interface allows configuration of properties that can have
16
+ * different values for horizontal and vertical directions.
17
+ *
18
+ * @template T - The type of values for horizontal and vertical properties
19
+ */
20
+ export interface UIType2D<T> {
21
+ /** Horizontal (x-axis) value. */
22
+ h?: T;
23
+ /** Vertical (y-axis) value. */
24
+ v?: T;
25
+ }
26
+ /**
27
+ * Base options for 2D constraint configuration.
28
+ */
29
+ interface UIConstraint2DOptions {
30
+ /** Priority levels for horizontal and vertical constraints. */
31
+ priority: UIType2D<UIPriority>;
32
+ /** Mathematical relations for horizontal and vertical constraints. */
33
+ relation: UIType2D<UIRelation>;
34
+ /** Orientation settings for horizontal and vertical constraints. */
35
+ orientation: UIType2D<UIOrientation>;
36
+ }
37
+ /**
38
+ * Configuration options for 2D size constraints.
39
+ */
40
+ export interface UIConstraintSize2DOptions extends UIConstraint2DOptions {
41
+ /** Size values for horizontal (width) and vertical (height) dimensions. */
42
+ size: UIType2D<number>;
43
+ }
44
+ /**
45
+ * Configuration options for 2D distance constraints.
46
+ */
47
+ export interface UIConstraintDistance2DOptions extends UIConstraint2DOptions {
48
+ /** Anchor points for element A in horizontal and vertical directions. */
49
+ anchorA: UIType2D<number>;
50
+ /** Anchor points for element B in horizontal and vertical directions. */
51
+ anchorB: UIType2D<number>;
52
+ /** Distance values for horizontal and vertical spacing. */
53
+ distance: UIType2D<number>;
54
+ }
55
+ /**
56
+ * Configuration options for 2D proportion constraints.
57
+ */
58
+ export interface UIConstraintProportion2DOptions extends UIConstraint2DOptions {
59
+ /** Proportion ratios for horizontal and vertical relationships. */
60
+ proportion: UIType2D<number>;
61
+ }
62
+ /**
63
+ * Result object containing horizontal and vertical constraint instances.
64
+ *
65
+ * @template TH - The type of the horizontal constraint
66
+ * @template TV - The type of the vertical constraint
67
+ */
68
+ export interface UIConstraint2DResult<TH, TV> {
69
+ /** The horizontal constraint instance. */
70
+ h: TH;
71
+ /** The vertical constraint instance. */
72
+ v: TV;
73
+ }
74
+ /**
75
+ * Builder utility for creating paired horizontal and vertical constraints.
76
+ *
77
+ * UIConstraint2DBuilder simplifies the creation of constraint pairs that work
78
+ * together to define 2D relationships between UI elements. Instead of manually
79
+ * creating separate horizontal and vertical constraints, this builder allows
80
+ * you to specify both dimensions at once with a unified interface.
81
+ *
82
+ * This is particularly useful for creating consistent spacing, sizing, and
83
+ * proportional relationships across both axes simultaneously.
84
+ *
85
+ * @see {@link UIWidthConstraint} - Horizontal size constraints
86
+ * @see {@link UIHeightConstraint} - Vertical size constraints
87
+ * @see {@link UIHorizontalDistanceConstraint} - Horizontal spacing constraints
88
+ * @see {@link UIVerticalDistanceConstraint} - Vertical spacing constraints
89
+ */
90
+ export declare class UIConstraint2DBuilder {
91
+ /**
92
+ * Creates paired width and height constraints for an element.
93
+ *
94
+ * This method generates both horizontal (width) and vertical (height)
95
+ * size constraints simultaneously, allowing you to set fixed dimensions
96
+ * for both axes with a single call.
97
+ *
98
+ * @param element - The UI element to apply size constraints to
99
+ * @param options - Configuration options for both width and height constraints
100
+ * @returns Object containing the created width and height constraint instances
101
+ */
102
+ static size(element: UIElement, options?: Partial<UIConstraintSize2DOptions>): UIConstraint2DResult<UIWidthConstraint, UIHeightConstraint>;
103
+ /**
104
+ * Creates paired horizontal and vertical distance constraints between two elements.
105
+ *
106
+ * This method generates both horizontal and vertical spacing constraints
107
+ * simultaneously, allowing you to define 2D spacing relationships with
108
+ * configurable anchor points for both axes.
109
+ *
110
+ * @param a - The first UI element (point or plane element)
111
+ * @param b - The second UI element (point or plane element)
112
+ * @param options - Configuration options for both horizontal and vertical distance constraints
113
+ * @returns Object containing the created horizontal and vertical distance constraint instances
114
+ */
115
+ static distance(a: UIPointElement | UIPlaneElement, b: UIPointElement | UIPlaneElement, options?: Partial<UIConstraintDistance2DOptions>): UIConstraint2DResult<UIHorizontalDistanceConstraint, UIVerticalDistanceConstraint>;
116
+ /**
117
+ * Creates paired horizontal and vertical proportion constraints between two elements.
118
+ *
119
+ * This method generates both horizontal (width) and vertical (height)
120
+ * proportion constraints simultaneously, allowing you to define proportional
121
+ * relationships for both dimensions with a single call.
122
+ *
123
+ * @param a - The first UI plane element (whose dimensions will be multiplied by proportion)
124
+ * @param b - The second UI plane element (target dimensions for the proportion)
125
+ * @param options - Configuration options for both horizontal and vertical proportion constraints
126
+ * @returns Object containing the created horizontal and vertical proportion constraint instances
127
+ */
128
+ static proportion(a: UIPlaneElement, b: UIPlaneElement, options?: Partial<UIConstraintProportion2DOptions>): UIConstraint2DResult<UIHorizontalProportionConstraint, UIVerticalProportionConstraint>;
129
+ }
130
+ export {};
File without changes
File without changes
File without changes
@@ -0,0 +1,60 @@
1
+ import type { UIElement } from "../elements/UIElement";
2
+ import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
3
+ import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
4
+ /**
5
+ * Configuration options for UIAspectConstraint creation.
6
+ */
7
+ export interface UIAspectConstraintOptions extends UISingleParameterConstraintOptions {
8
+ /** The desired aspect ratio (width/height) for the element. */
9
+ aspect: number;
10
+ }
11
+ /**
12
+ * Constraint that maintains a specific aspect ratio for UI elements.
13
+ *
14
+ * UIAspectConstraint enforces a mathematical relationship between an element's
15
+ * width and height to maintain a constant aspect ratio. The constraint equation
16
+ * is: width = height * aspect. This is useful for ensuring elements maintain
17
+ * their proportions during layout changes or for enforcing specific aspect
18
+ * ratios like 16:9 for video content.
19
+ *
20
+ * @see {@link UISingleParameterConstraint} - Base class for single-parameter constraints
21
+ * @see {@link UIElement} - Elements that can have aspect constraints applied
22
+ * @see {@link UIExpression} - Mathematical expressions for constraint equations
23
+ */
24
+ export declare class UIAspectConstraint extends UISingleParameterConstraint {
25
+ private readonly element;
26
+ /** The constraint descriptor managed by the solver system. */
27
+ protected readonly constraint: number;
28
+ /** Internal storage for the current aspect ratio value. */
29
+ private aspectInternal;
30
+ /**
31
+ * Creates a new UIAspectConstraint instance.
32
+ *
33
+ * If no aspect ratio is specified in options, the constraint will use the
34
+ * element's current width-to-height ratio as the target aspect ratio.
35
+ *
36
+ * @param element - The UI element to apply the aspect constraint to
37
+ * @param options - Configuration options for the constraint
38
+ */
39
+ constructor(element: UIElement, options?: Partial<UIAspectConstraintOptions>);
40
+ /**
41
+ * Gets the current aspect ratio being enforced.
42
+ * @returns The aspect ratio (width/height)
43
+ */
44
+ get aspect(): number;
45
+ /**
46
+ * Sets a new aspect ratio and updates the constraint equation.
47
+ * @param value - The new aspect ratio (width/height)
48
+ */
49
+ set aspect(value: number);
50
+ /**
51
+ * Builds the left-hand side expression for the constraint equation.
52
+ *
53
+ * Creates the expression: width - (height * aspect) = 0
54
+ * This enforces the relationship: width = height * aspect
55
+ *
56
+ * @returns The UIExpression representing the constraint equation
57
+ * @private
58
+ */
59
+ private buildLHS;
60
+ }
@@ -0,0 +1,29 @@
1
+ import { type UILayer } from "../layers/UILayer";
2
+ import type { UISolverWrapper } from "../wrappers/UISolverWrapper";
3
+ /**
4
+ * Abstract base class for all UI layout constraints.
5
+ *
6
+ * UIConstraint serves as the fundamental building block for the constraint-based
7
+ * layout system. It provides access to the solver wrapper for creating and
8
+ * managing constraint relationships between UI elements. All concrete constraint
9
+ * implementations must extend this class to participate in the layout solving process.
10
+ *
11
+ * @see {@link UILayer} - Container layer for constraints
12
+ * @see {@link UISolverWrapper} - Constraint solver integration
13
+ */
14
+ export declare abstract class UIConstraint {
15
+ readonly layer: UILayer;
16
+ /** Optional name identifier for the constraint. */
17
+ name: string;
18
+ /**
19
+ * Reference to the constraint solver wrapper for managing solver operations.
20
+ * @see {@link UISolverWrapper}
21
+ */
22
+ protected readonly solverWrapper: UISolverWrapper;
23
+ /**
24
+ * Creates a new UIConstraint instance.
25
+ *
26
+ * @param layer - The UI layer that contains this constraint
27
+ */
28
+ constructor(layer: UILayer);
29
+ }
File without changes
@@ -0,0 +1,60 @@
1
+ import type { UILayer } from "../layers/UILayer";
2
+ import type { UIExpression } from "../miscellaneous/UIExpression";
3
+ import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
4
+ import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
5
+ /**
6
+ * Constraint that allows custom mathematical relationships between UI elements.
7
+ *
8
+ * UICustomConstraint provides maximum flexibility by allowing direct specification
9
+ * of the left-hand side (LHS) and right-hand side (RHS) expressions for constraint
10
+ * equations. This enables creation of complex mathematical relationships that may
11
+ * not be covered by the specialized constraint types. The constraint equation is:
12
+ * LHS relation RHS (e.g., LHS = RHS, LHS ≤ RHS, or LHS ≥ RHS)
13
+ *
14
+ * This is useful for implementing custom layout logic, complex mathematical
15
+ * relationships between multiple elements, or prototype new constraint types.
16
+ *
17
+ * @see {@link UISingleParameterConstraint} - Base class for single-parameter constraints
18
+ * @see {@link UIExpression} - Mathematical expressions for constraint equations
19
+ * @see {@link UILayer} - Container layer for constraints
20
+ */
21
+ export declare class UICustomConstraint extends UISingleParameterConstraint {
22
+ /** The constraint descriptor managed by the solver system. */
23
+ protected readonly constraint: number;
24
+ /** Internal storage for the left-hand side expression. */
25
+ private lhsInternal;
26
+ /** Internal storage for the right-hand side expression. */
27
+ private rhsInternal;
28
+ /**
29
+ * Creates a new UICustomConstraint instance with custom expressions.
30
+ *
31
+ * The constraint will enforce the relationship: LHS relation RHS, where
32
+ * the relation is determined by the options (defaults to equality).
33
+ *
34
+ * @param layer - The UI layer that contains this constraint
35
+ * @param lhs - The left-hand side expression of the constraint equation
36
+ * @param rhs - The right-hand side expression of the constraint equation
37
+ * @param options - Configuration options for the constraint
38
+ */
39
+ constructor(layer: UILayer, lhs: UIExpression, rhs: UIExpression, options?: Partial<UISingleParameterConstraintOptions>);
40
+ /**
41
+ * Gets the current left-hand side expression.
42
+ * @returns The LHS expression of the constraint equation
43
+ */
44
+ get lhs(): UIExpression;
45
+ /**
46
+ * Gets the current right-hand side expression.
47
+ * @returns The RHS expression of the constraint equation
48
+ */
49
+ get rhs(): UIExpression;
50
+ /**
51
+ * Sets a new left-hand side expression and updates the constraint.
52
+ * @param value - The new LHS expression for the constraint equation
53
+ */
54
+ setLHS(value: UIExpression): void;
55
+ /**
56
+ * Sets a new right-hand side expression and updates the constraint.
57
+ * @param value - The new RHS expression for the constraint equation
58
+ */
59
+ setRHS(value: UIExpression): void;
60
+ }
File without changes