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