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