laymur 0.2.17 → 0.3.0

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 (43) hide show
  1. package/README.md +31 -24
  2. package/dist/builders/UIConstraint2DBuilder.d.ts +1 -1
  3. package/dist/builders/UICoverConstraintBuilder.d.ts +3 -1
  4. package/dist/builders/UIFitConstraintBuilder.d.ts +3 -1
  5. package/dist/constraints/UIAspectConstraint.d.ts +0 -1
  6. package/dist/constraints/UIConstraint.d.ts +3 -0
  7. package/dist/constraints/UIHorizontalDistanceConstraint.d.ts +0 -1
  8. package/dist/constraints/UIHorizontalProportionConstraint.d.ts +2 -3
  9. package/dist/constraints/UISingleParameterConstraint.d.ts +0 -2
  10. package/dist/constraints/UIVerticalDistanceConstraint.d.ts +0 -1
  11. package/dist/constraints/UIVerticalProportionConstraint.d.ts +2 -3
  12. package/dist/elements/UIDummy.d.ts +7 -1
  13. package/dist/elements/UIElement.d.ts +52 -38
  14. package/dist/elements/UIImage.d.ts +30 -42
  15. package/dist/elements/UINineSline.d.ts +61 -68
  16. package/dist/elements/UIProgress.d.ts +86 -110
  17. package/dist/elements/UIScene.d.ts +21 -30
  18. package/dist/elements/UIText.d.ts +27 -41
  19. package/dist/index.d.ts +4 -1
  20. package/dist/index.js +1237 -942
  21. package/dist/index.js.map +1 -1
  22. package/dist/index.min.js +1 -1
  23. package/dist/index.min.js.map +1 -1
  24. package/dist/layers/UIFullscreenLayer.d.ts +0 -4
  25. package/dist/layers/UILayer.d.ts +50 -3
  26. package/dist/miscellaneous/UIColor.d.ts +171 -0
  27. package/dist/miscellaneous/UIInputEvent.d.ts +7 -0
  28. package/dist/miscellaneous/UIMicro.d.ts +3 -3
  29. package/dist/miscellaneous/{UIAnchorMode.d.ts → UIMicroAnchorMode.d.ts} +1 -1
  30. package/dist/miscellaneous/UINineSliceBorder.d.ts +6 -6
  31. package/dist/miscellaneous/UISceneWrapperClientAPI.d.ts +10 -0
  32. package/dist/miscellaneous/UITextPadding.d.ts +1 -1
  33. package/dist/miscellaneous/UITransparencyMode.d.ts +26 -0
  34. package/dist/miscellaneous/textTools.d.ts +4 -4
  35. package/dist/scalable/UIScalableMesh.d.ts +0 -16
  36. package/dist/scalable/UIScalablePlaneMesh.d.ts +0 -14
  37. package/dist/wrappers/UISceneWrapper.d.ts +17 -15
  38. package/dist/wrappers/UISolverWrapper.d.ts +185 -0
  39. package/package.json +1 -1
  40. package/dist/materials/UIMaterial.d.ts +0 -13
  41. package/dist/materials/UINineSliceMaterial.d.ts +0 -27
  42. package/dist/materials/UIProgressMaterial.d.ts +0 -29
  43. package/dist/miscellaneous/threeInstances.d.ts +0 -2
@@ -1,29 +1,214 @@
1
1
  import { UIExpression } from "../miscellaneous/UIExpression";
2
2
  import { UIPriority } from "../miscellaneous/UIPriority";
3
3
  import { UIRelation } from "../miscellaneous/UIRelation";
4
+ /**
5
+ * Wrapper around the Kiwi constraint solver providing enhanced UI-specific functionality.
6
+ *
7
+ * UISolverWrapper abstracts the Kiwi (Cassowary) constraint solver to provide a more
8
+ * UI-friendly interface with additional features like dynamic constraint modification,
9
+ * required variables (P0 priority), partial constraint updates, and automatic solver
10
+ * recovery. It manages variables and constraints through index-based references,
11
+ * allowing for easy tracking and modification of layout constraints.
12
+ *
13
+ * Key features:
14
+ * - Index-based variable and constraint management
15
+ * - Required variables with P0 priority (always satisfied)
16
+ * - Dynamic constraint modification without full rebuilds
17
+ * - Automatic solver recovery on constraint conflicts
18
+ * - Lazy evaluation with recalculation flags
19
+ *
20
+ * @see {@link UIExpression} - Expression system for constraint definitions
21
+ * @see {@link UIPriority} - Priority levels for variables and constraints
22
+ * @see {@link UIRelation} - Relational operators for constraints
23
+ */
4
24
  export declare class UISolverWrapper {
25
+ /** The underlying Kiwi solver instance, undefined when solver needs rebuilding. */
5
26
  private solver?;
27
+ /** Flag indicating whether variable values need recalculation. */
6
28
  private recalculationRequired;
29
+ /** Map of variable indices to their descriptions. */
7
30
  private readonly variables;
31
+ /** Counter for generating unique variable indices. */
8
32
  private lastVariableIndex;
33
+ /** Map of constraint indices to their descriptions. */
9
34
  private readonly constraints;
35
+ /** Counter for generating unique constraint indices. */
10
36
  private lastConstraintIndex;
37
+ /**
38
+ * Creates a new solver variable with the specified value and priority.
39
+ *
40
+ * Variables with P0 priority are treated as required (must be satisfied exactly)
41
+ * and are implemented using equality constraints. Other priorities use edit
42
+ * variables that can be adjusted by the solver.
43
+ *
44
+ * @param value - Initial value for the variable
45
+ * @param priority - Priority level for constraint solving
46
+ * @returns Unique index identifier for the created variable
47
+ */
11
48
  createVariable(value: number, priority: UIPriority): number;
49
+ /**
50
+ * Removes a variable from the solver system.
51
+ *
52
+ * The variable must not be referenced by any existing constraints.
53
+ * Cleans up both the variable itself and any associated required constraint.
54
+ *
55
+ * @param index - Index of the variable to remove
56
+ * @throws Will throw an error if the variable doesn't exist or is still in use
57
+ */
12
58
  removeVariable(index: number): void;
59
+ /**
60
+ * Suggests a new value for an existing variable.
61
+ *
62
+ * For P0 priority variables, rebuilds the associated constraint.
63
+ * For other priorities, suggests the value to the solver's edit system.
64
+ * Only triggers updates if the value actually changes.
65
+ *
66
+ * @param index - Index of the variable to update
67
+ * @param value - New suggested value
68
+ * @throws Will throw an error if the variable doesn't exist
69
+ */
13
70
  suggestVariableValue(index: number, value: number): void;
71
+ /**
72
+ * Changes the priority of an existing variable.
73
+ *
74
+ * Switching to/from P0 priority changes how the variable is handled:
75
+ * - P0: Creates required constraint (must be satisfied exactly)
76
+ * - Other: Uses edit variable system (can be adjusted by solver)
77
+ *
78
+ * @param index - Index of the variable to modify
79
+ * @param priority - New priority level
80
+ * @throws Will throw an error if the variable doesn't exist
81
+ */
14
82
  setVariablePriority(index: number, priority: UIPriority): void;
83
+ /**
84
+ * Reads the current solved value of a variable.
85
+ *
86
+ * Triggers solver recalculation if needed and rebuilds the solver
87
+ * if it was invalidated due to constraint conflicts.
88
+ *
89
+ * @param index - Index of the variable to read
90
+ * @returns Current solved value of the variable
91
+ * @throws Will throw an error if the variable doesn't exist
92
+ */
15
93
  readVariableValue(index: number): number;
94
+ /**
95
+ * Creates a new constraint between two expressions.
96
+ *
97
+ * Constraints can be enabled or disabled, and all properties can be
98
+ * modified later without recreating the constraint.
99
+ *
100
+ * @param lhs - Left-hand side expression
101
+ * @param rhs - Right-hand side expression
102
+ * @param relation - Relational operator (equal, less than, greater than)
103
+ * @param priority - Priority level for constraint solving
104
+ * @param enabled - Whether the constraint is initially active
105
+ * @returns Unique index identifier for the created constraint
106
+ */
16
107
  createConstraint(lhs: UIExpression, rhs: UIExpression, relation: UIRelation, priority: UIPriority, enabled: boolean): number;
108
+ /**
109
+ * Removes a constraint from the solver system.
110
+ *
111
+ * If the constraint is currently enabled, it will be removed from
112
+ * the active solver before deletion.
113
+ *
114
+ * @param index - Index of the constraint to remove
115
+ * @throws Will throw an error if the constraint doesn't exist
116
+ */
17
117
  removeConstraint(index: number): void;
118
+ /**
119
+ * Updates the left-hand side expression of an existing constraint.
120
+ *
121
+ * Rebuilds the underlying constraint with the new expression while
122
+ * preserving all other properties.
123
+ *
124
+ * @param index - Index of the constraint to modify
125
+ * @param lhs - New left-hand side expression
126
+ * @throws Will throw an error if the constraint doesn't exist
127
+ */
18
128
  setConstraintLHS(index: number, lhs: UIExpression): void;
129
+ /**
130
+ * Updates the right-hand side expression of an existing constraint.
131
+ *
132
+ * Rebuilds the underlying constraint with the new expression while
133
+ * preserving all other properties.
134
+ *
135
+ * @param index - Index of the constraint to modify
136
+ * @param rhs - New right-hand side expression
137
+ * @throws Will throw an error if the constraint doesn't exist
138
+ */
19
139
  setConstraintRHS(index: number, rhs: UIExpression): void;
140
+ /**
141
+ * Updates the relational operator of an existing constraint.
142
+ *
143
+ * Changes how the left and right expressions are compared
144
+ * (equal, less than, greater than).
145
+ *
146
+ * @param index - Index of the constraint to modify
147
+ * @param relation - New relational operator
148
+ * @throws Will throw an error if the constraint doesn't exist
149
+ */
20
150
  setConstraintRelation(index: number, relation: UIRelation): void;
151
+ /**
152
+ * Updates the priority level of an existing constraint.
153
+ *
154
+ * Higher priority constraints are more likely to be satisfied
155
+ * when conflicts arise.
156
+ *
157
+ * @param index - Index of the constraint to modify
158
+ * @param priority - New priority level
159
+ * @throws Will throw an error if the constraint doesn't exist
160
+ */
21
161
  setConstraintPriority(index: number, priority: UIPriority): void;
162
+ /**
163
+ * Enables or disables an existing constraint.
164
+ *
165
+ * Disabled constraints are not considered during solving but
166
+ * remain in the system for potential re-enabling.
167
+ *
168
+ * @param index - Index of the constraint to modify
169
+ * @param enabled - Whether the constraint should be active
170
+ * @throws Will throw an error if the constraint doesn't exist
171
+ */
22
172
  setConstraintEnabled(index: number, enabled: boolean): void;
173
+ /**
174
+ * Rebuilds a variable in the solver system with new properties.
175
+ *
176
+ * Temporarily removes all constraints that reference the variable,
177
+ * updates the variable configuration, then rebuilds and re-adds
178
+ * the dependent constraints.
179
+ */
23
180
  private rebuildVariable;
181
+ /**
182
+ * Rebuilds a constraint based on its current description.
183
+ *
184
+ * Uses different rebuild strategies depending on whether the
185
+ * constraint is currently enabled.
186
+ */
24
187
  private rebuildConstraintByDescription;
188
+ /**
189
+ * Rebuilds a constraint by removing the old one and creating a new one.
190
+ *
191
+ * Safely handles solver state transitions and constraint replacement.
192
+ */
25
193
  private rebuildConstraint;
194
+ /**
195
+ * Creates a new Kiwi constraint from UI expressions and parameters.
196
+ *
197
+ * Converts UI-level expressions and enums to Kiwi-compatible formats.
198
+ */
26
199
  private buildConstraint;
200
+ /**
201
+ * Converts a UIExpression to a Kiwi Expression.
202
+ *
203
+ * Maps variable indices to their corresponding Kiwi Variable instances
204
+ * and preserves coefficients and constants.
205
+ */
27
206
  private convertExpression;
207
+ /**
208
+ * Completely rebuilds the solver from scratch.
209
+ *
210
+ * Re-adds all variables and constraints to a fresh solver instance.
211
+ * Used for recovery when the solver enters an invalid state.
212
+ */
28
213
  private rebuildSolver;
29
214
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "laymur",
3
- "version": "0.2.17",
3
+ "version": "0.3.0",
4
4
  "description": "Lightweight Three.js UI toolkit mainly for mobile ads",
5
5
  "scripts": {
6
6
  "clean": "rm -rf dist",
@@ -1,13 +0,0 @@
1
- import type { Texture } from "three";
2
- import { ShaderMaterial } from "three";
3
- export declare class UIMaterial extends ShaderMaterial {
4
- constructor(map?: Texture);
5
- getTexture(): Texture;
6
- getColor(): number;
7
- getOpacity(): number;
8
- getTransparency(): boolean;
9
- setTexture(value: Texture): this;
10
- setColor(value: number): this;
11
- setOpacity(value: number): this;
12
- setTransparency(value: boolean): this;
13
- }
@@ -1,27 +0,0 @@
1
- import type { Texture } from "three";
2
- import { ShaderMaterial } from "three";
3
- export declare class UINineSliceMaterial extends ShaderMaterial {
4
- constructor(texture: Texture);
5
- getSliceBorderLeft(): number;
6
- getSliceBorderRight(): number;
7
- getSliceBorderTop(): number;
8
- getSliceBorderBottom(): number;
9
- getQuadSize(): {
10
- w: number;
11
- h: number;
12
- };
13
- getTexture(): Texture;
14
- getColor(): number;
15
- getOpacity(): number;
16
- getTransparency(): boolean;
17
- setSliceBorderLeft(l: number): this;
18
- setSliceBorderRight(r: number): this;
19
- setSliceBorderTop(t: number): this;
20
- setSliceBorderBottom(b: number): this;
21
- setSliceBorder(l: number, r: number, t: number, b: number): this;
22
- setQuadSize(w: number, h: number): this;
23
- setTexture(value: Texture): this;
24
- setColor(color: number): this;
25
- setOpacity(opacity: number): this;
26
- setTransparency(value: boolean): this;
27
- }
@@ -1,29 +0,0 @@
1
- import type { Texture } from "three";
2
- import { ShaderMaterial } from "three";
3
- export declare class UIProgressMaterial extends ShaderMaterial {
4
- constructor(foregroundTexture: Texture, backgroundTexture?: Texture);
5
- getProgress(): number;
6
- getBackgroundTexture(): Texture | undefined;
7
- getForegroundTexture(): Texture;
8
- getColor(): number;
9
- getBackgroundColor(): number;
10
- getForegroundColor(): number;
11
- getOpacity(): number;
12
- getBackgroundOpacity(): number;
13
- getForegroundOpacity(): number;
14
- getTransparency(): boolean;
15
- getAngle(): number;
16
- getIsForwardDirection(): boolean;
17
- setProgress(value: number): void;
18
- setBackgroundTexture(value: Texture | undefined): void;
19
- setForegroundTexture(value: Texture): void;
20
- setColor(value: number): void;
21
- setBackgroundColor(value: number): void;
22
- setForegroundColor(value: number): void;
23
- setOpacity(value: number): void;
24
- setBackgroundOpacity(value: number): void;
25
- setForegroundOpacity(value: number): void;
26
- setTransparency(value: boolean): this;
27
- setAngle(value: number): void;
28
- setIsForwardDirection(value: boolean): void;
29
- }
@@ -1,2 +0,0 @@
1
- import { PlaneGeometry } from "three";
2
- export declare const geometry: PlaneGeometry;