laymur 0.2.10 → 0.2.12

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.
@@ -0,0 +1,54 @@
1
+ import { UIAspectConstraint } from "../constraints/UIAspectConstraint";
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 type { UILayerElement, UIPlaneElement } from "../miscellaneous/asserts";
7
+ import { type UIOrientation } from "../miscellaneous/UIOrientation";
8
+ /**
9
+ * Configuration options for the UICoverConstraintBuilder.
10
+ */
11
+ export interface UICoverConstraintBuilderOptions {
12
+ /** Whether to maintain the aspect ratio of the active (content) element */
13
+ keepActiveAspect: boolean;
14
+ /** Horizontal anchor point (0.0 = left, 0.5 = center, 1.0 = right) */
15
+ anchorH: number;
16
+ /** Vertical anchor point (0.0 = bottom, 0.5 = center, 1.0 = top) */
17
+ anchorV: number;
18
+ /** Orientation context for constraint calculations */
19
+ orientation: UIOrientation;
20
+ }
21
+ /**
22
+ * Builder for creating "cover" layout constraints that make an element cover its container.
23
+ *
24
+ * Cover layout ensures the active element is large enough to completely cover the passive
25
+ * element while maintaining proportions. This is similar to CSS `background-size: cover`
26
+ * or `object-fit: cover` behavior.
27
+ *
28
+ * The active element will be:
29
+ * - Positioned at the specified anchor point within the passive element
30
+ * - Sized to be at least as large as the passive element in both dimensions
31
+ * - Scaled proportionally to maintain aspect ratio (if enabled)
32
+ */
33
+ export declare class UICoverConstraintBuilder {
34
+ /**
35
+ * Creates a set of constraints for cover layout behavior.
36
+ *
37
+ * @param passive - The container element (what gets covered)
38
+ * @param active - The content element (what does the covering)
39
+ * @param options - Configuration options for the cover layout
40
+ * @returns Object containing all created constraints
41
+ */
42
+ static build(passive: UIPlaneElement, active: UIPlaneElement & UILayerElement, options?: Partial<UICoverConstraintBuilderOptions>): {
43
+ /** Aspect constraint for the active element (if keepActiveAspect is true) */
44
+ activeAspectConstraint?: UIAspectConstraint;
45
+ /** Horizontal positioning constraint */
46
+ xConstraint: UIHorizontalDistanceConstraint;
47
+ /** Vertical positioning constraint */
48
+ yConstraint: UIVerticalDistanceConstraint;
49
+ /** Width proportion constraint (ensures coverage) */
50
+ widthConstraint: UIHorizontalProportionConstraint;
51
+ /** Height proportion constraint (ensures coverage) */
52
+ heightConstraint: UIVerticalProportionConstraint;
53
+ };
54
+ }
@@ -0,0 +1,54 @@
1
+ import { UIAspectConstraint } from "../constraints/UIAspectConstraint";
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 type { UILayerElement, UIPlaneElement } from "../miscellaneous/asserts";
7
+ import { type UIOrientation } from "../miscellaneous/UIOrientation";
8
+ /**
9
+ * Configuration options for the UIFitConstraintBuilder.
10
+ */
11
+ export interface UIFitConstraintBuilderOptions {
12
+ /** Whether to maintain the aspect ratio of the active (content) element */
13
+ keepActiveAspect: boolean;
14
+ /** Horizontal anchor point (0.0 = left, 0.5 = center, 1.0 = right) */
15
+ anchorH: number;
16
+ /** Vertical anchor point (0.0 = bottom, 0.5 = center, 1.0 = top) */
17
+ anchorV: number;
18
+ /** Orientation context for constraint calculations */
19
+ orientation: UIOrientation;
20
+ }
21
+ /**
22
+ * Builder for creating "fit" layout constraints that make an element fit within its container.
23
+ *
24
+ * Fit layout ensures the active element is sized to completely fit within the passive
25
+ * element while maintaining proportions. This is similar to CSS `background-size: contain`
26
+ * or `object-fit: contain` behavior.
27
+ *
28
+ * The active element will be:
29
+ * - Positioned at the specified anchor point within the passive element
30
+ * - Sized to fit entirely within the passive element in both dimensions
31
+ * - Scaled proportionally to maintain aspect ratio (if enabled)
32
+ */
33
+ export declare class UIFitConstraintBuilder {
34
+ /**
35
+ * Creates a set of constraints for fit layout behavior.
36
+ *
37
+ * @param passive - The container element (what contains the content)
38
+ * @param active - The content element (what gets fitted within the container)
39
+ * @param options - Configuration options for the fit layout
40
+ * @returns Object containing all created constraints
41
+ */
42
+ static build(passive: UIPlaneElement, active: UIPlaneElement & UILayerElement, options?: Partial<UIFitConstraintBuilderOptions>): {
43
+ /** Aspect constraint for the active element (if keepActiveAspect is true) */
44
+ activeAspectConstraint?: UIAspectConstraint;
45
+ /** Horizontal positioning constraint */
46
+ xConstraint: UIHorizontalDistanceConstraint;
47
+ /** Vertical positioning constraint */
48
+ yConstraint: UIVerticalDistanceConstraint;
49
+ /** Width proportion constraint (ensures fitting) */
50
+ widthConstraint: UIHorizontalProportionConstraint;
51
+ /** Height proportion constraint (ensures fitting) */
52
+ heightConstraint: UIVerticalProportionConstraint;
53
+ };
54
+ }
@@ -1,4 +1,4 @@
1
- import type { UIElement } from "../elements/UIElement";
1
+ import type { UILayerElement, UIPlaneElement } from "../miscellaneous/asserts";
2
2
  import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
3
3
  import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
4
4
  /**
@@ -18,7 +18,7 @@ export interface UIAspectConstraintOptions extends UISingleParameterConstraintOp
18
18
  * ratios like 16:9 for video content.
19
19
  *
20
20
  * @see {@link UISingleParameterConstraint} - Base class for single-parameter constraints
21
- * @see {@link UIElement} - Elements that can have aspect constraints applied
21
+ * @see {@link UIPlaneElement} - Elements that can have aspect constraints applied
22
22
  * @see {@link UIExpression} - Mathematical expressions for constraint equations
23
23
  */
24
24
  export declare class UIAspectConstraint extends UISingleParameterConstraint {
@@ -36,7 +36,7 @@ export declare class UIAspectConstraint extends UISingleParameterConstraint {
36
36
  * @param element - The UI element to apply the aspect constraint to
37
37
  * @param options - Configuration options for the constraint
38
38
  */
39
- constructor(element: UIElement, options?: Partial<UIAspectConstraintOptions>);
39
+ constructor(element: UIPlaneElement & UILayerElement, options?: Partial<UIAspectConstraintOptions>);
40
40
  /**
41
41
  * Gets the current aspect ratio being enforced.
42
42
  * @returns The aspect ratio (width/height)
@@ -1,4 +1,4 @@
1
- import type { UIElement } from "../elements/UIElement";
1
+ import type { UILayerElement, UIPlaneElement } from "../miscellaneous/asserts";
2
2
  import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
3
3
  import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
4
4
  /**
@@ -17,7 +17,7 @@ export interface UIHeightConstraintOptions extends UISingleParameterConstraintOp
17
17
  * other layout changes or for setting fixed dimensions in responsive layouts.
18
18
  *
19
19
  * @see {@link UISingleParameterConstraint} - Base class for single-parameter constraints
20
- * @see {@link UIElement} - Elements that can have height constraints applied
20
+ * @see {@link UIPlaneElement} - Elements that can have height constraints applied
21
21
  * @see {@link UIExpression} - Mathematical expressions for constraint equations
22
22
  */
23
23
  export declare class UIHeightConstraint extends UISingleParameterConstraint {
@@ -35,7 +35,7 @@ export declare class UIHeightConstraint extends UISingleParameterConstraint {
35
35
  * @param element - The UI element to apply the height constraint to
36
36
  * @param options - Configuration options for the constraint
37
37
  */
38
- constructor(element: UIElement, options?: Partial<UIHeightConstraintOptions>);
38
+ constructor(element: UIPlaneElement & UILayerElement, options?: Partial<UIHeightConstraintOptions>);
39
39
  /**
40
40
  * Gets the current height value being enforced.
41
41
  * @returns The height value in pixels
@@ -1,4 +1,4 @@
1
- import type { UIElement } from "../elements/UIElement";
1
+ import type { UILayerElement, UIPlaneElement } from "../miscellaneous/asserts";
2
2
  import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
3
3
  import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
4
4
  /**
@@ -17,7 +17,7 @@ export interface UIWidthConstraintOptions extends UISingleParameterConstraintOpt
17
17
  * other layout changes or for setting fixed dimensions in responsive layouts.
18
18
  *
19
19
  * @see {@link UISingleParameterConstraint} - Base class for single-parameter constraints
20
- * @see {@link UIElement} - Elements that can have width constraints applied
20
+ * @see {@link UIPlaneElement} - Elements that can have width constraints applied
21
21
  * @see {@link UIExpression} - Mathematical expressions for constraint equations
22
22
  */
23
23
  export declare class UIWidthConstraint extends UISingleParameterConstraint {
@@ -35,7 +35,7 @@ export declare class UIWidthConstraint extends UISingleParameterConstraint {
35
35
  * @param element - The UI element to apply the width constraint to
36
36
  * @param options - Configuration options for the constraint
37
37
  */
38
- constructor(element: UIElement, options?: Partial<UIWidthConstraintOptions>);
38
+ constructor(element: UIPlaneElement & UILayerElement, options?: Partial<UIWidthConstraintOptions>);
39
39
  /**
40
40
  * Gets the current width value being enforced.
41
41
  * @returns The width value in pixels
@@ -1,6 +1,6 @@
1
1
  import { type Object3D } from "three";
2
2
  import type { UILayer } from "../layers/UILayer";
3
- import type { UIPlaneElement } from "../miscellaneous/asserts";
3
+ import type { UILayerElement, UIPlaneElement } from "../miscellaneous/asserts";
4
4
  import { UIMicro } from "../miscellaneous/UIMicro";
5
5
  import { UIMode } from "../miscellaneous/UIMode";
6
6
  import type { UISceneWrapper } from "../wrappers/UISceneWrapper";
@@ -27,7 +27,7 @@ export declare enum UIElementEvent {
27
27
  * @see {@link UISceneWrapper} - Scene management for rendering
28
28
  * @see {@link UIMicro} - Micro-optimization utilities
29
29
  */
30
- export declare abstract class UIElement<T extends Object3D = Object3D> extends UIAnchor implements UIPlaneElement {
30
+ export declare abstract class UIElement<T extends Object3D = Object3D> extends UIAnchor implements UIPlaneElement, UILayerElement {
31
31
  protected readonly object: T;
32
32
  /** Micro-transformation system for non-constraint based positioning, scaling, and rotation adjustments. */
33
33
  readonly micro: UIMicro;
@@ -118,4 +118,15 @@ export declare abstract class UIElement<T extends Object3D = Object3D> extends U
118
118
  * should not be used anymore.
119
119
  */
120
120
  destroy(): void;
121
+ /**
122
+ * Internal method for handling click events.
123
+ *
124
+ * Determines if the click coordinates intersect with this element's bounds
125
+ * and emits a CLICK event if the element is in interactive mode.
126
+ *
127
+ * @param x - The x-coordinate of the click
128
+ * @param y - The y-coordinate of the click
129
+ * @returns True if the click was handled by this element
130
+ */
131
+ protected ["onClickInternal"](x: number, y: number): boolean;
121
132
  }
@@ -1,11 +1,143 @@
1
- import type { Texture, WebGLRenderer } from "three";
1
+ import type { Texture } from "three";
2
2
  import { Mesh } from "three";
3
- import type { UILayer } from "../layers/UILayer";
3
+ import { type UILayer } from "../layers/UILayer";
4
+ import { type UINineSliceBorder } from "../miscellaneous/UINineSliceBorder";
4
5
  import { UIElement } from "./UIElement";
6
+ /**
7
+ * Configuration options for creating a UINineSlice element.
8
+ */
9
+ export interface UINineSliceOptions {
10
+ /** Nine-slice border configuration (can be number, object with horizontal/vertical, or full border object) */
11
+ sliceBorder: UINineSliceBorder;
12
+ /** X position of the element */
13
+ x: number;
14
+ /** Y position of the element */
15
+ y: number;
16
+ }
17
+ /**
18
+ * Nine-slice UI element for scalable images with preserved border regions.
19
+ *
20
+ * Nine-slice scaling divides an image into 9 regions: 4 corners, 4 edges, and 1 center.
21
+ * The corners maintain their original size, edges scale in one dimension, and the center
22
+ * scales in both dimensions. This technique is commonly used for creating scalable UI
23
+ * panels, buttons, and borders that maintain visual quality at any size.
24
+ */
5
25
  export declare class UINineSlice extends UIElement<Mesh> {
6
26
  private readonly material;
7
27
  private readonly textureInternal;
8
- constructor(layer: UILayer, texture: Texture, x?: number, y?: number);
28
+ /**
29
+ * Creates a new nine-slice UI element.
30
+ *
31
+ * @param layer - The UI layer to add this element to
32
+ * @param texture - The texture to use for nine-slice rendering
33
+ * @param options - Configuration options for the nine-slice element
34
+ */
35
+ constructor(layer: UILayer, texture: Texture, options?: Partial<UINineSliceOptions>);
36
+ /**
37
+ * Gets the left border size for nine-slice scaling.
38
+ * @returns The left border size in texture UV coordinates
39
+ */
40
+ get sliceBorderLeft(): number;
41
+ /**
42
+ * Gets the right border size for nine-slice scaling.
43
+ * @returns The right border size in texture UV coordinates
44
+ */
45
+ get sliceBorderRight(): number;
46
+ /**
47
+ * Gets the top border size for nine-slice scaling.
48
+ * @returns The top border size in texture UV coordinates
49
+ */
50
+ get sliceBorderTop(): number;
51
+ /**
52
+ * Gets the bottom border size for nine-slice scaling.
53
+ * @returns The bottom border size in texture UV coordinates
54
+ */
55
+ get sliceBorderBottom(): number;
56
+ /**
57
+ * Gets the current texture being displayed.
58
+ * @returns The current Three.js texture
59
+ */
60
+ get texture(): Texture;
61
+ /**
62
+ * Gets the current color tint applied to the image.
63
+ * @returns The color value as a number (e.g., 0xFFFFFF for white)
64
+ */
65
+ get color(): number;
66
+ /**
67
+ * Gets the current opacity level of the image.
68
+ * @returns The opacity value between 0.0 (transparent) and 1.0 (opaque)
69
+ */
70
+ get opacity(): number;
71
+ /**
72
+ * Gets whether transparency is enabled for the image.
73
+ * @returns True if transparency is enabled, false otherwise
74
+ */
75
+ get transparency(): boolean;
76
+ /**
77
+ * Sets the left border size for nine-slice scaling.
78
+ * @param value - The left border size in texture UV coordinates
79
+ */
80
+ set sliceBorderLeft(value: number);
81
+ /**
82
+ * Sets the right border size for nine-slice scaling.
83
+ * @param value - The right border size in texture UV coordinates
84
+ */
85
+ set sliceBorderRight(value: number);
86
+ /**
87
+ * Sets the top border size for nine-slice scaling.
88
+ * @param value - The top border size in texture UV coordinates
89
+ */
90
+ set sliceBorderTop(value: number);
91
+ /**
92
+ * Sets the bottom border size for nine-slice scaling.
93
+ * @param value - The bottom border size in texture UV coordinates
94
+ */
95
+ set sliceBorderBottom(value: number);
96
+ /**
97
+ * Sets a new texture for the image.
98
+ *
99
+ * When setting a new texture, the image will automatically resize to match
100
+ * the new texture's dimensions.
101
+ *
102
+ * @param value - The new Three.js texture to display
103
+ * @throws Will throw an error if the texture dimensions are not valid positive numbers
104
+ * @see {@link assertValidPositiveNumber}
105
+ */
106
+ set texture(value: Texture);
107
+ /**
108
+ * Sets the color tint applied to the image.
109
+ * @param value - The color value as a number (e.g., 0xFFFFFF for white)
110
+ */
111
+ set color(value: number);
112
+ /**
113
+ * Sets the opacity level of the image.
114
+ * @param value - The opacity value between 0.0 (transparent) and 1.0 (opaque)
115
+ */
116
+ set opacity(value: number);
117
+ /**
118
+ * Sets whether transparency is enabled for the image.
119
+ * @param value - True to enable transparency, false to disable
120
+ */
121
+ set transparency(value: boolean);
122
+ /**
123
+ * Sets all four border sizes for nine-slice scaling at once.
124
+ *
125
+ * @param left - The left border size in texture UV coordinates
126
+ * @param right - The right border size in texture UV coordinates
127
+ * @param top - The top border size in texture UV coordinates
128
+ * @param bottom - The bottom border size in texture UV coordinates
129
+ */
130
+ setSliceBorders(left: number, right: number, top: number, bottom: number): void;
131
+ /**
132
+ * Destroys the nine-slice element and cleans up resources.
133
+ *
134
+ * This method removes event listeners, disposes of the material,
135
+ * and calls the parent destroy method.
136
+ */
9
137
  destroy(): void;
10
- protected ["onBeforeRenderInternal"](renderer: WebGLRenderer, deltaTime: number): void;
138
+ /**
139
+ * Internal render callback that updates the material's quad size.
140
+ * This ensures the nine-slice scaling works correctly with micro transformations.
141
+ */
142
+ private readonly onWillRenderInternal;
11
143
  }
@@ -1,6 +1,6 @@
1
1
  import type { Camera } from "three";
2
2
  import { Mesh, Scene } from "three";
3
- import type { UILayer } from "../layers/UILayer";
3
+ import { type UILayer } from "../layers/UILayer";
4
4
  import { UIElement } from "./UIElement";
5
5
  /**
6
6
  * Update modes for controlling when the 3D scene should be re-rendered.
@@ -196,4 +196,5 @@ export declare class UIScene extends UIElement<Mesh> {
196
196
  * want to trigger a scene re-render without changing any properties.
197
197
  */
198
198
  requestRender(): void;
199
+ private readonly onWillRenderInternal;
199
200
  }
@@ -1,5 +1,5 @@
1
1
  import { Mesh } from "three";
2
- import type { UILayer } from "../layers/UILayer";
2
+ import { type UILayer } from "../layers/UILayer";
3
3
  import type { UITextContent } from "../miscellaneous/textInterfaces";
4
4
  import { type UITextPadding } from "../miscellaneous/UITextPadding";
5
5
  import { type UITextStyle } from "../miscellaneous/UITextStyle";
@@ -14,6 +14,10 @@ export interface UITextOptions {
14
14
  padding: Partial<UITextPadding>;
15
15
  /** Common style properties applied to all text content. */
16
16
  commonStyle: Partial<UITextStyle>;
17
+ /** X-coordinate of the text element. */
18
+ x: number;
19
+ /** Y-coordinate of the text element. */
20
+ y: number;
17
21
  }
18
22
  /**
19
23
  * UI element for rendering dynamic text with canvas-based rendering.
@@ -64,7 +68,7 @@ export declare class UIText extends UIElement<Mesh> {
64
68
  * @param y - Initial y-coordinate position (defaults to 0)
65
69
  * @throws Will throw an error if canvas context creation fails
66
70
  */
67
- constructor(layer: UILayer, content: UITextContent, options?: Partial<UITextOptions>, x?: number, y?: number);
71
+ constructor(layer: UILayer, content: UITextContent, options?: Partial<UITextOptions>);
68
72
  /**
69
73
  * Gets the current color tint applied to the text.
70
74
  * @returns The color value as a number (e.g., 0xFFFFFF for white)
@@ -144,6 +148,7 @@ export declare class UIText extends UIElement<Mesh> {
144
148
  * the text element should not be used anymore.
145
149
  */
146
150
  destroy(): void;
151
+ private readonly onWillRenderInternal;
147
152
  /**
148
153
  * Rebuilds the text canvas and texture based on current content and settings.
149
154
  *
package/dist/index.d.ts CHANGED
@@ -1,4 +1,6 @@
1
1
  export * from "./builders/UIConstraint2DBuilder";
2
+ export * from "./builders/UICoverConstraintBuilder";
3
+ export * from "./builders/UIFitConstraintBuilder";
2
4
  export * from "./constraints/UIAspectConstraint";
3
5
  export * from "./constraints/UIConstraint";
4
6
  export * from "./constraints/UICustomConstraint";