laymur 0.2.0 → 0.2.2

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 (64) hide show
  1. package/README.md +353 -2
  2. package/dist/builders/UIConstraint2DBuilder.d.ts +102 -14
  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 +40 -36
  7. package/dist/constraints/UIConstraint.d.ts +17 -20
  8. package/dist/constraints/UICoverConstraint.d.ts +0 -72
  9. package/dist/constraints/UICustomConstraint.d.ts +60 -0
  10. package/dist/constraints/UIFitConstraint.d.ts +0 -72
  11. package/dist/constraints/UIHeightConstraint.d.ts +32 -38
  12. package/dist/constraints/UIHorizontalDistanceConstraint.d.ts +77 -46
  13. package/dist/constraints/UIHorizontalProportionConstraint.d.ts +49 -40
  14. package/dist/constraints/UISingleParameterConstraint.d.ts +108 -0
  15. package/dist/constraints/UIVerticalDistanceConstraint.d.ts +77 -46
  16. package/dist/constraints/UIVerticalProportionConstraint.d.ts +49 -40
  17. package/dist/constraints/UIWidthConstraint.d.ts +32 -38
  18. package/dist/elements/UIAnchor.d.ts +58 -45
  19. package/dist/elements/UIDummy.d.ts +63 -12
  20. package/dist/elements/UIElement.d.ts +81 -93
  21. package/dist/elements/UIImage.d.ts +64 -33
  22. package/dist/elements/UINineSline.d.ts +0 -0
  23. package/dist/elements/UIProgress.d.ts +7 -95
  24. package/dist/elements/UIScene.d.ts +142 -84
  25. package/dist/elements/UIText.d.ts +124 -43
  26. package/dist/index.d.ts +10 -11
  27. package/dist/index.js +2887 -2716
  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 +134 -57
  33. package/dist/materials/UIInstancedMaterial.d.ts +0 -0
  34. package/dist/materials/UIMaterial.d.ts +6 -6
  35. package/dist/materials/UINineSliceMaterial.d.ts +0 -0
  36. package/dist/materials/UIProgressMaterial.d.ts +0 -4
  37. package/dist/miscellaneous/UIExpression.d.ts +117 -0
  38. package/dist/miscellaneous/UIMicro.d.ts +73 -119
  39. package/dist/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 +111 -4
  46. package/dist/miscellaneous/textInterfaces.d.ts +19 -0
  47. package/dist/miscellaneous/textTools.d.ts +8 -5
  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 +1 -1
  53. package/dist/Passes/UIComposer.d.ts +0 -114
  54. package/dist/Passes/UIFullScreenQuad.d.ts +0 -51
  55. package/dist/Passes/UIPass.d.ts +0 -43
  56. package/dist/builders/UIConstraintContainerBuilder.d.ts +0 -20
  57. package/dist/builders/UIConstraintStackBuilder.d.ts +0 -24
  58. package/dist/constraints/UIConstraintPower.d.ts +0 -57
  59. package/dist/constraints/UIConstraintRule.d.ts +0 -46
  60. package/dist/layers/UIFullScreenLayer.d.ts +0 -13
  61. package/dist/miscellaneous/UIBlending.d.ts +0 -7
  62. package/dist/miscellaneous/UITextInterfaces.d.ts +0 -49
  63. package/dist/miscellaneous/math.d.ts +0 -1
  64. package/dist/miscellaneous/microTransformationTools.d.ts +0 -3
package/README.md CHANGED
@@ -1,10 +1,354 @@
1
- # Laymur
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>
2
13
 
3
14
  ⚠️ **Early Alpha / Work in Progress** ⚠️
4
15
 
5
16
  This library is in very early development stage. APIs may change significantly.
6
17
 
7
- A TypeScript Three.js UI layout library with constraint-based positioning.
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
8
352
 
9
353
  ## License
10
354
 
@@ -14,3 +358,10 @@ It uses [Kiwi.js](https://github.com/lume/kiwi) as its constraint solving engine
14
358
 
15
359
  Kiwi.js is licensed under the [BSD-3-Clause License](https://github.com/lume/kiwi/blob/main/LICENSE).
16
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
@@ -1,42 +1,130 @@
1
- import type { UIConstraintPower } from "../constraints/UIConstraintPower";
2
- import type { UIConstraintRule } from "../constraints/UIConstraintRule";
3
1
  import { UIHeightConstraint } from "../constraints/UIHeightConstraint";
4
2
  import { UIHorizontalDistanceConstraint } from "../constraints/UIHorizontalDistanceConstraint";
5
3
  import { UIHorizontalProportionConstraint } from "../constraints/UIHorizontalProportionConstraint";
6
4
  import { UIVerticalDistanceConstraint } from "../constraints/UIVerticalDistanceConstraint";
7
5
  import { UIVerticalProportionConstraint } from "../constraints/UIVerticalProportionConstraint";
8
6
  import { UIWidthConstraint } from "../constraints/UIWidthConstraint";
9
- import type { UIAnchor } from "../elements/UIAnchor";
10
7
  import type { UIElement } from "../elements/UIElement";
11
- import type { UILayer } from "../layers/UILayer";
8
+ import type { UIPlaneElement, UIPointElement } from "../miscellaneous/asserts";
12
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
+ */
13
20
  export interface UIType2D<T> {
21
+ /** Horizontal (x-axis) value. */
14
22
  h?: T;
23
+ /** Vertical (y-axis) value. */
15
24
  v?: T;
16
25
  }
26
+ /**
27
+ * Base options for 2D constraint configuration.
28
+ */
17
29
  interface UIConstraint2DOptions {
18
- power: UIType2D<UIConstraintPower>;
19
- rule: UIType2D<UIConstraintRule>;
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. */
20
35
  orientation: UIType2D<UIOrientation>;
21
36
  }
37
+ /**
38
+ * Configuration options for 2D size constraints.
39
+ */
22
40
  export interface UIConstraintSize2DOptions extends UIConstraint2DOptions {
41
+ /** Size values for horizontal (width) and vertical (height) dimensions. */
23
42
  size: UIType2D<number>;
24
43
  }
25
- export interface UIConstraintSize2DOptions extends UIConstraint2DOptions {
26
- anchorOne: UIType2D<number>;
27
- anchorTwo: UIType2D<number>;
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. */
28
53
  distance: UIType2D<number>;
29
54
  }
55
+ /**
56
+ * Configuration options for 2D proportion constraints.
57
+ */
30
58
  export interface UIConstraintProportion2DOptions extends UIConstraint2DOptions {
59
+ /** Proportion ratios for horizontal and vertical relationships. */
31
60
  proportion: UIType2D<number>;
32
61
  }
33
- export interface UIConstraint2DResult<TX, TY> {
34
- x: TX;
35
- y: TY;
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;
36
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
+ */
37
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
+ */
38
102
  static size(element: UIElement, options?: Partial<UIConstraintSize2DOptions>): UIConstraint2DResult<UIWidthConstraint, UIHeightConstraint>;
39
- static distance(elementOne: UIElement | UIAnchor | UILayer, elementTwo: UIElement | UIAnchor, options?: Partial<UIConstraintSize2DOptions>): UIConstraint2DResult<UIHorizontalDistanceConstraint, UIVerticalDistanceConstraint>;
40
- static proportion(elementOne: UIElement | UILayer, elementTwo: UIElement, options?: Partial<UIConstraintProportion2DOptions>): UIConstraint2DResult<UIHorizontalProportionConstraint, UIVerticalProportionConstraint>;
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>;
41
129
  }
42
130
  export {};
File without changes
File without changes
File without changes
@@ -1,56 +1,60 @@
1
1
  import type { UIElement } from "../elements/UIElement";
2
- import { UIOrientation } from "../miscellaneous/UIOrientation";
3
- import { UIConstraint } from "./UIConstraint";
4
- import type { UIConstraintPower } from "./UIConstraintPower";
5
- import type { UIConstraintRule } from "./UIConstraintRule";
2
+ import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
3
+ import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
6
4
  /**
7
- * Configuration options for aspect ratio constraints.
5
+ * Configuration options for UIAspectConstraint creation.
8
6
  */
9
- export interface UIAspectOptions {
10
- /** The aspect ratio to maintain (width / height) */
7
+ export interface UIAspectConstraintOptions extends UISingleParameterConstraintOptions {
8
+ /** The desired aspect ratio (width/height) for the element. */
11
9
  aspect: number;
12
- /** Priority level for this constraint */
13
- power: UIConstraintPower;
14
- /** Rule for the constraint relationship (equal, less than, greater than) */
15
- rule: UIConstraintRule;
16
- /** Screen orientation when this constraint should be active */
17
- orientation: UIOrientation;
18
10
  }
19
11
  /**
20
- * Constraint that maintains a specific aspect ratio for a UI element.
12
+ * Constraint that maintains a specific aspect ratio for UI elements.
21
13
  *
22
- * The aspect ratio is defined as width divided by height (w/h).
23
- * This constraint ensures that an element maintains its proportions
24
- * during layout calculations.
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
25
23
  */
26
- export declare class UIAspectConstraint extends UIConstraint {
24
+ export declare class UIAspectConstraint extends UISingleParameterConstraint {
27
25
  private readonly element;
28
- /** The configuration options for this constraint */
29
- private readonly options;
30
- /** The Kiwi.js constraint object */
31
- private constraint?;
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;
32
30
  /**
33
- * Creates a new aspect ratio constraint.
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.
34
35
  *
35
- * @param element - The UI element to constrain
36
- * @param options - Configuration options
36
+ * @param element - The UI element to apply the aspect constraint to
37
+ * @param options - Configuration options for the constraint
37
38
  */
38
- constructor(element: UIElement, options?: Partial<UIAspectOptions>);
39
+ constructor(element: UIElement, options?: Partial<UIAspectConstraintOptions>);
39
40
  /**
40
- * Destroys this constraint, removing it from the constraint system.
41
+ * Gets the current aspect ratio being enforced.
42
+ * @returns The aspect ratio (width/height)
41
43
  */
42
- destroy(): void;
44
+ get aspect(): number;
43
45
  /**
44
- * Builds and adds the aspect ratio constraint to the constraint solver.
45
- *
46
- * Creates a constraint expression in the form: width - (height * aspect) = 0
47
- * This ensures that width/height = aspect.
48
- *
46
+ * Sets a new aspect ratio and updates the constraint equation.
47
+ * @param value - The new aspect ratio (width/height)
49
48
  */
50
- protected buildConstraints(): void;
49
+ set aspect(value: number);
51
50
  /**
52
- * Removes the aspect ratio constraint from the constraint solver.
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
53
55
  *
56
+ * @returns The UIExpression representing the constraint equation
57
+ * @private
54
58
  */
55
- protected destroyConstraints(): void;
59
+ private buildLHS;
56
60
  }
@@ -1,32 +1,29 @@
1
- import type { UIAnchor } from "../elements/UIAnchor";
2
- import type { UIElement } from "../elements/UIElement";
3
- import type { UILayer } from "../layers/UILayer";
1
+ import { type UILayer } from "../layers/UILayer";
2
+ import type { UISolverWrapper } from "../wrappers/UISolverWrapper";
4
3
  /**
5
- * Abstract base class for all UI constraints in the system.
4
+ * Abstract base class for all UI layout constraints.
6
5
  *
7
- * Constraints control the layout of UI elements by establishing relationships
8
- * between their properties (position, size) and other elements or the screen.
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.
9
10
  *
10
- * The constraint system uses Kiwi.js under the hood for solving the constraint system.
11
- * Each constraint adds specific rules to the solver that determine element positioning.
11
+ * @see {@link UILayer} - Container layer for constraints
12
+ * @see {@link UISolverWrapper} - Constraint solver integration
12
13
  */
13
14
  export declare abstract class UIConstraint {
14
15
  readonly layer: UILayer;
15
- /**
16
- * Optional identifier for the constraint.
17
- * Useful for debugging and identifying constraints.
18
- */
16
+ /** Optional name identifier for the constraint. */
19
17
  name: string;
20
18
  /**
21
- * Creates a new UI constraint.
22
- *
23
- * @param layer - The UI layer that will manage this constraint
24
- * @param elements - The set of UI elements affected by this constraint
19
+ * Reference to the constraint solver wrapper for managing solver operations.
20
+ * @see {@link UISolverWrapper}
25
21
  */
26
- constructor(layer: UILayer, elements: Set<UIElement | UIAnchor>);
22
+ protected readonly solverWrapper: UISolverWrapper;
27
23
  /**
28
- * Destroys the constraint, removing it from the layer and solver.
29
- * This should be called when the constraint is no longer needed.
24
+ * Creates a new UIConstraint instance.
25
+ *
26
+ * @param layer - The UI layer that contains this constraint
30
27
  */
31
- destroy(): void;
28
+ constructor(layer: UILayer);
32
29
  }