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.
- package/README.md +367 -0
- package/dist/builders/UIConstraint2DBuilder.d.ts +130 -0
- package/dist/composer/UIComposer.d.ts +0 -0
- package/dist/composer/UIFullscreenQuad.d.ts +0 -0
- package/dist/composer/UIPass.d.ts +0 -0
- package/dist/constraints/UIAspectConstraint.d.ts +60 -0
- package/dist/constraints/UIConstraint.d.ts +29 -0
- package/dist/constraints/UICoverConstraint.d.ts +0 -0
- package/dist/constraints/UICustomConstraint.d.ts +60 -0
- package/dist/constraints/UIFitConstraint.d.ts +0 -0
- package/dist/constraints/UIHeightConstraint.d.ts +49 -0
- package/dist/constraints/UIHorizontalDistanceConstraint.d.ts +94 -0
- package/dist/constraints/UIHorizontalProportionConstraint.d.ts +67 -0
- package/dist/constraints/UISingleParameterConstraint.d.ts +108 -0
- package/dist/constraints/UIVerticalDistanceConstraint.d.ts +94 -0
- package/dist/constraints/UIVerticalProportionConstraint.d.ts +67 -0
- package/dist/constraints/UIWidthConstraint.d.ts +49 -0
- package/dist/elements/UIAnchor.d.ts +78 -0
- package/dist/elements/UIDummy.d.ts +72 -0
- package/dist/elements/UIElement.d.ts +121 -0
- package/dist/elements/UIImage.d.ts +88 -0
- package/dist/elements/UINineSline.d.ts +0 -0
- package/dist/elements/UIProgress.d.ts +39 -0
- package/dist/elements/UIScene.d.ts +199 -0
- package/dist/elements/UIText.d.ts +157 -0
- package/dist/index.d.ts +29 -31
- package/dist/index.js +3320 -3251
- package/dist/index.js.map +1 -1
- package/dist/index.min.js +1 -1
- package/dist/index.min.js.map +1 -1
- package/dist/layers/UIFullscreenLayer.d.ts +112 -0
- package/dist/layers/UILayer.d.ts +144 -0
- package/dist/materials/UIInstancedMaterial.d.ts +0 -0
- package/dist/materials/UIMaterial.d.ts +13 -0
- package/dist/materials/UINineSliceMaterial.d.ts +0 -0
- package/dist/{Materials → materials}/UIProgressMaterial.d.ts +0 -4
- package/dist/miscellaneous/UIExpression.d.ts +117 -0
- package/dist/miscellaneous/UIMicro.d.ts +130 -0
- package/dist/{Miscellaneous → miscellaneous}/UIOrientation.d.ts +2 -9
- package/dist/miscellaneous/UIPriority.d.ts +56 -0
- package/dist/miscellaneous/UIRelation.d.ts +43 -0
- package/dist/miscellaneous/UITextPadding.d.ts +7 -0
- package/dist/miscellaneous/UITextSpan.d.ts +6 -0
- package/dist/miscellaneous/UITextStyle.d.ts +18 -0
- package/dist/miscellaneous/asserts.d.ts +112 -0
- package/dist/miscellaneous/textInterfaces.d.ts +19 -0
- package/dist/miscellaneous/textTools.d.ts +12 -0
- package/dist/scalable/UIScalableMesh.d.ts +16 -0
- package/dist/scalable/UIScalablePlaneMesh.d.ts +14 -0
- package/dist/wrappers/UISceneWrapper.d.ts +18 -0
- package/dist/wrappers/UISolverWrapper.d.ts +29 -0
- package/package.json +3 -3
- package/dist/Builders/UIConstraint2DBuilder.d.ts +0 -42
- package/dist/Builders/UIConstraintContainerBuilder.d.ts +0 -20
- package/dist/Builders/UIConstraintStackBuilder.d.ts +0 -24
- package/dist/Constraints/UIAspectConstraint.d.ts +0 -56
- package/dist/Constraints/UIConstraint.d.ts +0 -32
- package/dist/Constraints/UIConstraintPower.d.ts +0 -57
- package/dist/Constraints/UIConstraintRule.d.ts +0 -46
- package/dist/Constraints/UICoverConstraint.d.ts +0 -72
- package/dist/Constraints/UIFitConstraint.d.ts +0 -72
- package/dist/Constraints/UIHeightConstraint.d.ts +0 -55
- package/dist/Constraints/UIHorizontalDistanceConstraint.d.ts +0 -63
- package/dist/Constraints/UIHorizontalProportionConstraint.d.ts +0 -58
- package/dist/Constraints/UIVerticalDistanceConstraint.d.ts +0 -63
- package/dist/Constraints/UIVerticalProportionConstraint.d.ts +0 -58
- package/dist/Constraints/UIWidthConstraint.d.ts +0 -55
- package/dist/Elements/UIAnchor.d.ts +0 -66
- package/dist/Elements/UIDummy.d.ts +0 -21
- package/dist/Elements/UIElement.d.ts +0 -134
- package/dist/Elements/UIImage.d.ts +0 -57
- package/dist/Elements/UIProgress.d.ts +0 -127
- package/dist/Elements/UIScene.d.ts +0 -141
- package/dist/Elements/UIText.d.ts +0 -76
- package/dist/Layers/UIFullScreenLayer.d.ts +0 -13
- package/dist/Layers/UILayer.d.ts +0 -68
- package/dist/Materials/UIMaterial.d.ts +0 -13
- package/dist/Miscellaneous/UIBlending.d.ts +0 -7
- package/dist/Miscellaneous/UIMicro.d.ts +0 -176
- package/dist/Miscellaneous/UITextInterfaces.d.ts +0 -49
- package/dist/Miscellaneous/asserts.d.ts +0 -5
- package/dist/Miscellaneous/math.d.ts +0 -1
- package/dist/Miscellaneous/microTransformationTools.d.ts +0 -3
- package/dist/Miscellaneous/symbols.d.ts +0 -1
- package/dist/Miscellaneous/textTools.d.ts +0 -9
- package/dist/Passes/UIComposer.d.ts +0 -114
- package/dist/Passes/UIFullScreenQuad.d.ts +0 -51
- package/dist/Passes/UIPass.d.ts +0 -43
- /package/dist/{Miscellaneous → miscellaneous}/UIMode.d.ts +0 -0
- /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
|