laymur 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (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 +2867 -2718
  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
@@ -1,133 +1,121 @@
1
- import { Variable } from "@lume/kiwi";
2
- import { Eventail } from "eventail";
3
- import type { WebGLRenderer } from "three";
4
1
  import { type Object3D } from "three";
5
2
  import type { UILayer } from "../layers/UILayer";
6
- import { UIMicro, UIMicroInternal } from "../miscellaneous/UIMicro";
3
+ import type { UIPlaneElement } from "../miscellaneous/asserts";
4
+ import { UIMicro } from "../miscellaneous/UIMicro";
7
5
  import { UIMode } from "../miscellaneous/UIMode";
8
- import { UIComposer, UIComposerInternal } from "../Passes/UIComposer";
6
+ import type { UISceneWrapper } from "../wrappers/UISceneWrapper";
7
+ import { UIAnchor } from "./UIAnchor";
9
8
  /**
10
9
  * Events that can be emitted by UI elements.
11
10
  */
12
11
  export declare enum UIElementEvent {
13
- /** Triggered when an interactive element is clicked */
12
+ /** Emitted when the element is clicked. */
14
13
  CLICK = "click"
15
14
  }
16
15
  /**
17
- * Abstract base class for all UI elements in the system.
18
- * Provides core functionality for positioning, sizing, and rendering UI elements.
16
+ * Abstract base class for all renderable UI elements with dimensions.
19
17
  *
20
- * Each UI element has:
21
- * - Position (x, y) and size (width, height) variables
22
- * - Layer management integration
23
- * - Event handling capabilities
24
- * - Micro transformations support
25
- * - Rendering capabilities
18
+ * UIElement serves as the fundamental building block for all other UI elements
19
+ * that need to be visually rendered. It extends UIAnchor with dimensional properties
20
+ * and integrates with the Three.js rendering system through Object3D. This class
21
+ * provides essential functionality for positioning, sizing, rendering, visibility,
22
+ * z-index management, and user interaction.
23
+ *
24
+ * @template T - The type of Three.js Object3D used for rendering
25
+ * @see {@link UIAnchor} - Base class providing position functionality
26
+ * @see {@link UIPlaneElement} - Interface defining dimensional element behavior
27
+ * @see {@link UISceneWrapper} - Scene management for rendering
28
+ * @see {@link UIMicro} - Micro-optimization utilities
26
29
  */
27
- export declare abstract class UIElement extends Eventail {
28
- readonly layer: UILayer;
29
- protected readonly object: Object3D;
30
- /** X position variable for constraint system */
31
- ["xInternal"]: Variable;
32
- /** Y position variable for constraint system */
33
- ["yInternal"]: Variable;
34
- /** Width variable for constraint system */
35
- ["widthInternal"]: Variable;
36
- /** Height variable for constraint system */
37
- ["heightInternal"]: Variable;
38
- /** Flag indicating whether the element needs recalculation */
39
- ["needsRecalculationInternal"]: boolean;
40
- /** Unique identifier for the element */
41
- name: string;
42
- /** Micro transformation interface for the element */
30
+ export declare abstract class UIElement<T extends Object3D = Object3D> extends UIAnchor implements UIPlaneElement {
31
+ protected readonly object: T;
32
+ /** Micro-transformation system for non-constraint based positioning, scaling, and rotation adjustments. */
43
33
  readonly micro: UIMicro;
44
- /** Composer interface for the element */
45
- readonly composer: UIComposer;
46
- /** Internal micro transformation implementation */
47
- protected readonly microInternal: UIMicroInternal;
48
- /** Internal composer implementation */
49
- protected readonly composerInternal: UIComposerInternal;
50
- /** Current visibility/interactivity mode */
34
+ /**
35
+ * Solver variable descriptor for the width dimension.
36
+ * This variable is managed by the constraint solver system.
37
+ */
38
+ readonly wVariable: number;
39
+ /**
40
+ * Solver variable descriptor for the height dimension.
41
+ * This variable is managed by the constraint solver system.
42
+ */
43
+ readonly hVariable: number;
44
+ /**
45
+ * Reference to the scene wrapper for rendering management.
46
+ * @see {@link UISceneWrapper}
47
+ */
48
+ protected readonly sceneWrapper: UISceneWrapper;
49
+ /** Internal storage for the current visibility/interaction mode. */
51
50
  protected modeInternal: UIMode;
52
51
  /**
53
- * Creates a new UI element.
52
+ * Creates a new UIElement instance with rendering capabilities.
54
53
  *
55
54
  * @param layer - The UI layer that contains this element
56
- * @param object - The Three.js object that represents this element
57
- * @param x - Initial x position
58
- * @param y - Initial y position
59
- * @param width - Initial width
60
- * @param height - Initial height
55
+ * @param x - Initial x-coordinate position
56
+ * @param y - Initial y-coordinate position
57
+ * @param width - Initial width dimension (must be positive)
58
+ * @param height - Initial height dimension (must be positive)
59
+ * @param object - The Three.js Object3D used for rendering this element
60
+ * @throws Will throw an error if width or height are not valid positive numbers
61
+ * @see {@link assertValidPositiveNumber}
62
+ */
63
+ constructor(layer: UILayer, x: number, y: number, width: number, height: number, object: T);
64
+ /**
65
+ * Gets the current width value from the solver.
66
+ * @returns The current width dimension
61
67
  */
62
- constructor(layer: UILayer, object: Object3D, x: number, y: number, width: number, height: number);
63
- /** Gets the current x position of the element */
64
- get x(): number;
65
- /** Gets the current y position of the element */
66
- get y(): number;
67
- /** Gets the current width of the element */
68
68
  get width(): number;
69
- /** Gets the current height of the element */
69
+ /**
70
+ * Gets the current height value from the solver.
71
+ * @returns The current height dimension
72
+ */
70
73
  get height(): number;
71
- /** Gets the current z-index (depth) of the element */
72
- get zIndex(): number;
73
- /** Gets the current visibility/interactivity mode of the element */
74
- get mode(): UIMode;
75
- /** Gets whether the element needs recalculation */
76
- protected get needsRecalculation(): boolean;
77
74
  /**
78
- * Sets the x position of the element
79
- * @param value - New x position
75
+ * Gets the current z-index (depth) value from the scene.
76
+ * @returns The current z-index for rendering order
80
77
  */
81
- set x(value: number);
78
+ get zIndex(): number;
82
79
  /**
83
- * Sets the y position of the element
84
- * @param value - New y position
80
+ * Gets the current visibility and interaction mode.
81
+ * @returns The current UIMode setting
82
+ * @see {@link UIMode}
85
83
  */
86
- set y(value: number);
84
+ get mode(): UIMode;
87
85
  /**
88
- * Sets the width of the element
89
- * @param value - New width
86
+ * Sets the width value through the solver system.
87
+ * @param value - The new width dimension (must be positive)
88
+ * @throws Will throw an error if value is not a valid positive number
89
+ * @see {@link assertValidPositiveNumber}
90
90
  */
91
91
  set width(value: number);
92
92
  /**
93
- * Sets the height of the element
94
- * @param value - New height
93
+ * Sets the height value through the solver system.
94
+ * @param value - The new height dimension (must be positive)
95
+ * @throws Will throw an error if value is not a valid positive number
96
+ * @see {@link assertValidPositiveNumber}
95
97
  */
96
98
  set height(value: number);
97
99
  /**
98
- * Sets the z-index (depth) of the element
99
- * @param value - New z-index
100
+ * Sets the z-index (depth) value for rendering order.
101
+ * @param value - The new z-index value
102
+ * @throws Will throw an error if value is not a valid number
103
+ * @see {@link assertValidNumber}
100
104
  */
101
105
  set zIndex(value: number);
102
106
  /**
103
- * Sets the visibility/interactivity mode of the element
104
- * @param value - New UI mode
107
+ * Sets the visibility and interaction mode.
108
+ * @param value - The new UIMode setting
109
+ * @see {@link UIMode}
105
110
  */
106
111
  set mode(value: UIMode);
107
112
  /**
108
- * Destroys the element, cleaning up all resources and removing it from the layer.
109
- * This should be called when the element is no longer needed.
110
- */
111
- destroy(): void;
112
- /**
113
- * Applies transformations to the underlying Three.js object.
114
- * This is called when the element's position, size, or other properties change.
115
- */
116
- protected applyTransformations(): void;
117
- /**
118
- * Handles click events on this element.
119
- *
120
- * @param x - X coordinate of the click
121
- * @param y - Y coordinate of the click
122
- * @returns Whether the click was handled by this element
123
- */
124
- protected click(x: number, y: number): boolean;
125
- /**
126
- * Renders the element.
127
- * This must be implemented by concrete subclasses.
113
+ * Destroys the UI element by cleaning up all associated resources.
128
114
  *
129
- * @param renderer - The WebGL renderer
130
- * @param deltaTime - Time elapsed since the last frame
115
+ * This method removes the element from the rendering scene, cleans up
116
+ * dimension solver variables, and calls the parent destroy method to
117
+ * clean up position variables. After calling this method, the element
118
+ * should not be used anymore.
131
119
  */
132
- protected abstract render(renderer: WebGLRenderer, deltaTime: number): void;
120
+ destroy(): void;
133
121
  }
@@ -1,57 +1,88 @@
1
- import type { Texture, WebGLRenderer } from "three";
1
+ import type { Texture } from "three";
2
+ import { Mesh } from "three";
2
3
  import type { UILayer } from "../layers/UILayer";
3
- import { UIBlending } from "../miscellaneous/UIBlending";
4
4
  import { UIElement } from "./UIElement";
5
5
  /**
6
- * A UI element that displays an image texture.
7
- * Renders a textured mesh using the provided texture.
6
+ * UI element for displaying textured images.
7
+ *
8
+ * UIImage is a concrete implementation of UIElement that renders a textured
9
+ * image using Three.js Mesh and UIMaterial. It automatically sizes itself
10
+ * to match the texture dimensions and provides control over visual properties
11
+ * such as color tinting, opacity, and transparency.
12
+ *
13
+ * @see {@link UIElement} - Base class providing UI element functionality
14
+ * @see {@link UIMaterial} - Material system for rendering
15
+ * @see {@link Texture} - Three.js texture for image data
8
16
  */
9
- export declare class UIImage extends UIElement {
10
- /** Material used to render the image */
17
+ export declare class UIImage extends UIElement<Mesh> {
18
+ /** The material used for rendering the image. */
11
19
  private readonly material;
12
- /** The texture displayed by this image */
20
+ /** Internal storage for the current texture. */
13
21
  private readonly textureInternal;
14
- private blendingInternal;
15
22
  /**
16
- * Creates a new image UI element.
23
+ * Creates a new UIImage instance.
17
24
  *
18
- * @param layer - The UI layer that contains this element
19
- * @param texture - The texture to display
20
- * @throws Error if the texture has invalid dimensions
25
+ * The image will automatically size itself to match the texture's dimensions.
26
+ * The position defaults to (0, 0) if not specified.
27
+ *
28
+ * @param layer - The UI layer that contains this image
29
+ * @param texture - The Three.js texture to display
30
+ * @param x - Initial x-coordinate position (defaults to 0)
31
+ * @param y - Initial y-coordinate position (defaults to 0)
32
+ */
33
+ constructor(layer: UILayer, texture: Texture, x?: number, y?: number);
34
+ /**
35
+ * Gets the current texture being displayed.
36
+ * @returns The current Three.js texture
21
37
  */
22
- constructor(layer: UILayer, texture: Texture);
23
- /** Gets the texture displayed by this image */
24
38
  get texture(): Texture;
25
- /** Gets the color tint applied to the image */
39
+ /**
40
+ * Gets the current color tint applied to the image.
41
+ * @returns The color value as a number (e.g., 0xFFFFFF for white)
42
+ */
26
43
  get color(): number;
27
- /** Gets the opacity of the image */
44
+ /**
45
+ * Gets the current opacity level of the image.
46
+ * @returns The opacity value between 0.0 (transparent) and 1.0 (opaque)
47
+ */
28
48
  get opacity(): number;
29
- /** Gets the blending mode of the image */
30
- get blending(): UIBlending;
31
49
  /**
32
- * Sets the color tint applied to the image
33
- * @param value - Color in hexadecimal format
50
+ * Gets whether transparency is enabled for the image.
51
+ * @returns True if transparency is enabled, false otherwise
34
52
  */
35
- set color(value: number);
53
+ get transparency(): boolean;
36
54
  /**
37
- * Sets the opacity of the image
38
- * @param value - Opacity value between 0 (transparent) and 1 (opaque)
55
+ * Sets a new texture for the image.
56
+ *
57
+ * When setting a new texture, the image will automatically resize to match
58
+ * the new texture's dimensions.
59
+ *
60
+ * @param value - The new Three.js texture to display
61
+ * @throws Will throw an error if the texture dimensions are not valid positive numbers
62
+ * @see {@link assertValidPositiveNumber}
39
63
  */
40
- set opacity(value: number);
64
+ set texture(value: Texture);
41
65
  /**
42
- * Sets the blending mode of the image
43
- * @param value - Blending mode to apply
66
+ * Sets the color tint applied to the image.
67
+ * @param value - The color value as a number (e.g., 0xFFFFFF for white)
44
68
  */
45
- set blending(value: UIBlending);
69
+ set color(value: number);
46
70
  /**
47
- * Destroys the image element, disposing of all resources and removing it from the layer.
48
- * This should be called when the element is no longer needed.
71
+ * Sets the opacity level of the image.
72
+ * @param value - The opacity value between 0.0 (transparent) and 1.0 (opaque)
49
73
  */
50
- destroy(): void;
74
+ set opacity(value: number);
75
+ /**
76
+ * Sets whether transparency is enabled for the image.
77
+ * @param value - True to enable transparency, false to disable
78
+ */
79
+ set transparency(value: boolean);
51
80
  /**
52
- * Renders the image element.
81
+ * Destroys the image by cleaning up all associated resources.
53
82
  *
54
- * @param renderer - The WebGL renderer
83
+ * This method disposes of the material resources and calls the parent
84
+ * destroy method to clean up the underlying UI element. After calling
85
+ * this method, the image should not be used anymore.
55
86
  */
56
- protected render(renderer: WebGLRenderer): void;
87
+ destroy(): void;
57
88
  }
File without changes
@@ -1,127 +1,39 @@
1
- import type { Texture, WebGLRenderer } from "three";
1
+ import type { Texture } from "three";
2
+ import { Mesh } from "three";
2
3
  import type { UILayer } from "../layers/UILayer";
3
4
  import { UIElement } from "./UIElement";
4
- /**
5
- * Options for customizing the UIProgress element.
6
- */
7
5
  export interface UIProgressOptions {
8
- /** Optional background texture to display behind the progress indicator */
6
+ x: number;
7
+ y: number;
9
8
  textureBackground: Texture;
10
- /** Progress value from 0 to 1 */
11
9
  progress: number;
12
- /** Whether progress increases in the direction specified by angle (true) or opposite to it (false) */
13
10
  isForegroundDirection: boolean;
14
- /** Angle in degrees specifying the direction of progress */
15
11
  angle: number;
16
- /** Overall color tint applied to both textures */
17
- color: number;
18
- /** Overall opacity applied to both textures */
19
- opacity: number;
20
- /** Color tint applied to the background texture */
21
12
  backgroundColor: number;
22
- /** Color tint applied to the foreground texture */
23
13
  foregroundColor: number;
24
- /** Opacity of the background texture */
25
14
  backgroundOpacity: number;
26
- /** Opacity of the foreground texture */
27
15
  foregroundOpacity: number;
28
16
  }
29
- /**
30
- * A UI element that displays a progress indicator.
31
- * Can be used for loading bars, health bars, sliders, etc.
32
- */
33
- export declare class UIProgress extends UIElement {
34
- /** Material used to render the progress indicator */
17
+ export declare class UIProgress extends UIElement<Mesh> {
35
18
  private readonly material;
36
- /** Width of the underlying image texture */
37
- private readonly imageWidth;
38
- /** Height of the underlying image texture */
39
- private readonly imageHeight;
40
- /**
41
- * Creates a new progress UI element.
42
- *
43
- * @param layer - The UI layer that contains this element
44
- * @param textureForeground - The texture to use for the progress indicator
45
- * @param options - Options to customize the progress indicator
46
- * @throws Error if either texture has invalid dimensions
47
- */
48
19
  constructor(layer: UILayer, textureForeground: Texture, options?: Partial<UIProgressOptions>);
49
- /** Gets the current progress value (0 to 1) */
50
20
  get progress(): number;
51
- /** Gets the background texture if one was provided */
52
21
  get backgroundTexture(): Texture | undefined;
53
- /** Gets the foreground texture used for the progress indicator */
54
22
  get foregroundTexture(): Texture;
55
- /** Gets the color tint applied to the background texture */
56
23
  get backgroundColor(): number;
57
- /** Gets the color tint applied to the foreground texture */
58
24
  get foregroundColor(): number;
59
- /** Gets the overall color tint applied to both textures */
60
- get color(): number;
61
- /** Gets the opacity of the background texture */
62
25
  get backgroundOpacity(): number;
63
- /** Gets the opacity of the foreground texture */
64
26
  get foregroundOpacity(): number;
65
- /** Gets the overall opacity applied to both textures */
66
- get opacity(): number;
67
- /** Gets the angle in degrees specifying the direction of progress */
68
27
  get angle(): number;
69
- /** Gets whether progress increases in the direction specified by angle (true) or opposite to it (false) */
70
28
  get isForwardDirection(): boolean;
71
- /**
72
- * Sets the progress value
73
- * @param value - Progress value between 0 (empty) and 1 (full)
74
- */
75
29
  set progress(value: number);
76
- /**
77
- * Sets the color tint applied to the background texture
78
- * @param value - Color in hexadecimal format
79
- */
30
+ set backgroundTexture(value: Texture | undefined);
31
+ set foregroundTexture(value: Texture);
80
32
  set backgroundColor(value: number);
81
- /**
82
- * Sets the color tint applied to the foreground texture
83
- * @param value - Color in hexadecimal format
84
- */
85
33
  set foregroundColor(value: number);
86
- /**
87
- * Sets the overall color tint applied to both textures
88
- * @param value - Color in hexadecimal format
89
- */
90
- set color(value: number);
91
- /**
92
- * Sets the opacity of the background texture
93
- * @param value - Opacity value between 0 (transparent) and 1 (opaque)
94
- */
95
34
  set backgroundOpacity(value: number);
96
- /**
97
- * Sets the opacity of the foreground texture
98
- * @param value - Opacity value between 0 (transparent) and 1 (opaque)
99
- */
100
35
  set foregroundOpacity(value: number);
101
- /**
102
- * Sets the overall opacity applied to both textures
103
- * @param value - Opacity value between 0 (transparent) and 1 (opaque)
104
- */
105
- set opacity(value: number);
106
- /**
107
- * Sets the angle specifying the direction of progress
108
- * @param value - Angle in degrees
109
- */
110
36
  set angle(value: number);
111
- /**
112
- * Sets whether progress increases in the direction specified by angle
113
- * @param value - true to increase in the direction of angle, false for opposite
114
- */
115
37
  set isForwardDirection(value: boolean);
116
- /**
117
- * Destroys the progress element, disposing of all resources and removing it from the layer.
118
- * This should be called when the element is no longer needed.
119
- */
120
38
  destroy(): void;
121
- /**
122
- * Renders the progress element.
123
- *
124
- * @param renderer - The WebGL renderer
125
- */
126
- protected render(renderer: WebGLRenderer): void;
127
39
  }