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,72 +0,0 @@
1
- import { UIElement } from "../elements/UIElement";
2
- import type { UILayer } from "../layers/UILayer";
3
- import { UIOrientation } from "../miscellaneous/UIOrientation";
4
- import { UIConstraint } from "./UIConstraint";
5
- /**
6
- * Configuration options for cover constraints.
7
- */
8
- export interface UICoverOptions {
9
- /** Whether to force equal height (true) or allow stretching (false) */
10
- isStrict: boolean;
11
- /** Horizontal anchor point (0-1) for alignment between elements */
12
- horizontalAnchor: number;
13
- /** Vertical anchor point (0-1) for alignment between elements */
14
- verticalAnchor: number;
15
- /** Screen orientation when this constraint should be active */
16
- orientation: UIOrientation;
17
- }
18
- /**
19
- * Constraint that makes an element cover another element or layer.
20
- *
21
- * The covering element will:
22
- * - Be aligned with the covered element using the specified anchors
23
- * - Have at least the same width and height as the covered element
24
- * - Optionally maintain strict proportions
25
- *
26
- * This is similar to CSS's "cover" object-fit behavior.
27
- */
28
- export declare class UICoverConstraint extends UIConstraint {
29
- private readonly elementOne;
30
- private readonly elementTwo;
31
- /** The configuration options for this constraint */
32
- private readonly options;
33
- /** Constraint for X-axis alignment */
34
- private constraintX?;
35
- /** Constraint for Y-axis alignment */
36
- private constraintY?;
37
- /** Constraint for width relationship */
38
- private constraintW?;
39
- /** Constraint for height relationship */
40
- private constraintH?;
41
- /** Optional constraint for maintaining strict proportions */
42
- private constraintStrict?;
43
- /**
44
- * Creates a new cover constraint.
45
- *
46
- * @param elementOne - The element or layer to be covered (the reference)
47
- * @param elementTwo - The element that will cover the reference
48
- * @param options - Configuration options
49
- */
50
- constructor(elementOne: UIElement | UILayer, elementTwo: UIElement, options?: Partial<UICoverOptions>);
51
- /**
52
- * Destroys this constraint, removing it from the constraint system.
53
- */
54
- destroy(): void;
55
- /**
56
- * Builds and adds the cover constraints to the constraint solver.
57
- *
58
- * Creates five constraints:
59
- * 1. X alignment between the elements
60
- * 2. Y alignment between the elements
61
- * 3. Width covering (elementTwo width ≥ elementOne width)
62
- * 4. Height covering (elementTwo height ≥ elementOne height)
63
- * 5. Optional strict proportions (if isStrict = false)
64
- *
65
- */
66
- protected buildConstraints(): void;
67
- /**
68
- * Removes all cover constraints from the constraint solver.
69
- *
70
- */
71
- protected destroyConstraints(): void;
72
- }
@@ -0,0 +1,60 @@
1
+ import type { UILayer } from "../layers/UILayer";
2
+ import type { UIExpression } from "../miscellaneous/UIExpression";
3
+ import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
4
+ import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
5
+ /**
6
+ * Constraint that allows custom mathematical relationships between UI elements.
7
+ *
8
+ * UICustomConstraint provides maximum flexibility by allowing direct specification
9
+ * of the left-hand side (LHS) and right-hand side (RHS) expressions for constraint
10
+ * equations. This enables creation of complex mathematical relationships that may
11
+ * not be covered by the specialized constraint types. The constraint equation is:
12
+ * LHS relation RHS (e.g., LHS = RHS, LHS ≤ RHS, or LHS ≥ RHS)
13
+ *
14
+ * This is useful for implementing custom layout logic, complex mathematical
15
+ * relationships between multiple elements, or prototype new constraint types.
16
+ *
17
+ * @see {@link UISingleParameterConstraint} - Base class for single-parameter constraints
18
+ * @see {@link UIExpression} - Mathematical expressions for constraint equations
19
+ * @see {@link UILayer} - Container layer for constraints
20
+ */
21
+ export declare class UICustomConstraint extends UISingleParameterConstraint {
22
+ /** The constraint descriptor managed by the solver system. */
23
+ protected readonly constraint: number;
24
+ /** Internal storage for the left-hand side expression. */
25
+ private lhsInternal;
26
+ /** Internal storage for the right-hand side expression. */
27
+ private rhsInternal;
28
+ /**
29
+ * Creates a new UICustomConstraint instance with custom expressions.
30
+ *
31
+ * The constraint will enforce the relationship: LHS relation RHS, where
32
+ * the relation is determined by the options (defaults to equality).
33
+ *
34
+ * @param layer - The UI layer that contains this constraint
35
+ * @param lhs - The left-hand side expression of the constraint equation
36
+ * @param rhs - The right-hand side expression of the constraint equation
37
+ * @param options - Configuration options for the constraint
38
+ */
39
+ constructor(layer: UILayer, lhs: UIExpression, rhs: UIExpression, options?: Partial<UISingleParameterConstraintOptions>);
40
+ /**
41
+ * Gets the current left-hand side expression.
42
+ * @returns The LHS expression of the constraint equation
43
+ */
44
+ get lhs(): UIExpression;
45
+ /**
46
+ * Gets the current right-hand side expression.
47
+ * @returns The RHS expression of the constraint equation
48
+ */
49
+ get rhs(): UIExpression;
50
+ /**
51
+ * Sets a new left-hand side expression and updates the constraint.
52
+ * @param value - The new LHS expression for the constraint equation
53
+ */
54
+ setLHS(value: UIExpression): void;
55
+ /**
56
+ * Sets a new right-hand side expression and updates the constraint.
57
+ * @param value - The new RHS expression for the constraint equation
58
+ */
59
+ setRHS(value: UIExpression): void;
60
+ }
@@ -1,72 +0,0 @@
1
- import { UIElement } from "../elements/UIElement";
2
- import type { UILayer } from "../layers/UILayer";
3
- import { UIOrientation } from "../miscellaneous/UIOrientation";
4
- import { UIConstraint } from "./UIConstraint";
5
- /**
6
- * Configuration options for fit constraints.
7
- */
8
- export interface UIFitOptions {
9
- /** Whether to force equal height (true) or allow stretching (false) */
10
- isStrict: boolean;
11
- /** Horizontal anchor point (0-1) for alignment between elements */
12
- horizontalAnchor: number;
13
- /** Vertical anchor point (0-1) for alignment between elements */
14
- verticalAnchor: number;
15
- /** Screen orientation when this constraint should be active */
16
- orientation: UIOrientation;
17
- }
18
- /**
19
- * Constraint that makes an element fit within another element or layer.
20
- *
21
- * The fitting element will:
22
- * - Be aligned with the container element using the specified anchors
23
- * - Have at most the same width and height as the container element
24
- * - Optionally maintain strict proportions
25
- *
26
- * This is similar to CSS's "contain" object-fit behavior.
27
- */
28
- export declare class UIFitConstraint extends UIConstraint {
29
- private readonly elementOne;
30
- private readonly elementTwo;
31
- /** The configuration options for this constraint */
32
- private readonly options;
33
- /** Constraint for X-axis alignment */
34
- private constraintX?;
35
- /** Constraint for Y-axis alignment */
36
- private constraintY?;
37
- /** Constraint for width relationship */
38
- private constraintW?;
39
- /** Constraint for height relationship */
40
- private constraintH?;
41
- /** Optional constraint for maintaining strict proportions */
42
- private constraintStrict?;
43
- /**
44
- * Creates a new fit constraint.
45
- *
46
- * @param elementOne - The element or layer that contains the fitting element (the container)
47
- * @param elementTwo - The element that will fit within the container
48
- * @param options - Configuration options
49
- */
50
- constructor(elementOne: UIElement | UILayer, elementTwo: UIElement, options?: Partial<UIFitOptions>);
51
- /**
52
- * Destroys this constraint, removing it from the constraint system.
53
- */
54
- destroy(): void;
55
- /**
56
- * Builds and adds the fit constraints to the constraint solver.
57
- *
58
- * Creates five constraints:
59
- * 1. X alignment between the elements
60
- * 2. Y alignment between the elements
61
- * 3. Width fitting (elementTwo width ≤ elementOne width)
62
- * 4. Height fitting (elementTwo height ≤ elementOne height)
63
- * 5. Optional strict proportions (if isStrict = true)
64
- *
65
- */
66
- protected buildConstraints(): void;
67
- /**
68
- * Removes all fit constraints from the constraint solver.
69
- *
70
- */
71
- protected destroyConstraints(): void;
72
- }
@@ -1,55 +1,49 @@
1
1
  import type { UIElement } from "../elements/UIElement";
2
- import { UIOrientation } from "../miscellaneous/UIOrientation";
3
- import { UIConstraint } from "./UIConstraint";
4
- import type { UIConstraintPower } from "./UIConstraintPower";
5
- import type { UIConstraintRule } from "./UIConstraintRule";
2
+ import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
3
+ import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
6
4
  /**
7
- * Configuration options for height constraints.
5
+ * Configuration options for UIHeightConstraint creation.
8
6
  */
9
- export interface UIHeightOptions {
10
- /** The fixed height value to constrain the element to */
7
+ export interface UIHeightConstraintOptions extends UISingleParameterConstraintOptions {
8
+ /** The desired height value for the element. */
11
9
  height: number;
12
- /** Priority level for this constraint */
13
- power: UIConstraintPower;
14
- /** Rule for the constraint relationship (equal, less than, greater than) */
15
- rule: UIConstraintRule;
16
- /** Screen orientation when this constraint should be active */
17
- orientation: UIOrientation;
18
10
  }
19
11
  /**
20
- * Constraint that enforces a specific height for a UI element.
12
+ * Constraint that enforces a specific height value for UI elements.
21
13
  *
22
- * This constraint can be configured to require an exact height
23
- * or set minimum/maximum height limits using different rules.
14
+ * UIHeightConstraint creates a mathematical relationship that fixes an element's
15
+ * height to a constant value. The constraint equation is: element.height = height.
16
+ * This is useful for ensuring elements maintain a specific height regardless of
17
+ * other layout changes or for setting fixed dimensions in responsive layouts.
18
+ *
19
+ * @see {@link UISingleParameterConstraint} - Base class for single-parameter constraints
20
+ * @see {@link UIElement} - Elements that can have height constraints applied
21
+ * @see {@link UIExpression} - Mathematical expressions for constraint equations
24
22
  */
25
- export declare class UIHeightConstraint extends UIConstraint {
23
+ export declare class UIHeightConstraint extends UISingleParameterConstraint {
26
24
  private readonly element;
27
- /** The configuration options for this constraint */
28
- private readonly options;
29
- /** The Kiwi.js constraint object */
30
- private constraint?;
25
+ /** The constraint descriptor managed by the solver system. */
26
+ protected readonly constraint: number;
27
+ /** Internal storage for the current height value. */
28
+ private heightInternal;
31
29
  /**
32
- * Creates a new height constraint.
30
+ * Creates a new UIHeightConstraint instance.
31
+ *
32
+ * If no height is specified in options, the constraint will use the
33
+ * element's current height as the target height value.
33
34
  *
34
- * @param element - The UI element to constrain
35
- * @param options - Configuration options
35
+ * @param element - The UI element to apply the height constraint to
36
+ * @param options - Configuration options for the constraint
36
37
  */
37
- constructor(element: UIElement, options?: Partial<UIHeightOptions>);
38
+ constructor(element: UIElement, options?: Partial<UIHeightConstraintOptions>);
38
39
  /**
39
- * Destroys this constraint, removing it from the constraint system.
40
+ * Gets the current height value being enforced.
41
+ * @returns The height value in pixels
40
42
  */
41
- destroy(): void;
43
+ get height(): number;
42
44
  /**
43
- * Builds and adds the height constraint to the constraint solver.
44
- *
45
- * Creates a constraint that enforces the element's height based
46
- * on the specified rule (equal to, less than, or greater than).
47
- *
48
- */
49
- protected buildConstraints(): void;
50
- /**
51
- * Removes the height constraint from the constraint solver.
52
- *
45
+ * Sets a new height value and updates the constraint equation.
46
+ * @param value - The new height value in pixels
53
47
  */
54
- protected destroyConstraints(): void;
48
+ set height(value: number);
55
49
  }
@@ -1,63 +1,94 @@
1
- import { UIAnchor } from "../elements/UIAnchor";
2
- import { UIElement } from "../elements/UIElement";
3
- import { UILayer } from "../layers/UILayer";
4
- import { UIOrientation } from "../miscellaneous/UIOrientation";
5
- import { UIConstraint } from "./UIConstraint";
6
- import type { UIConstraintPower } from "./UIConstraintPower";
7
- import type { UIConstraintRule } from "./UIConstraintRule";
1
+ import type { UIPlaneElement, UIPointElement } from "../miscellaneous/asserts";
2
+ import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
3
+ import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
8
4
  /**
9
- * Configuration options for horizontal distance constraints.
5
+ * Configuration options for UIHorizontalDistanceConstraint creation.
10
6
  */
11
- export interface UIHorizontalDistanceOptions {
12
- /** Horizontal anchor point (0-1) for the first element */
13
- anchorOne: number;
14
- /** Horizontal anchor point (0-1) for the second element */
15
- anchorTwo: number;
16
- /** The target distance between the two elements' anchor points */
7
+ export interface UIHorizontalDistanceConstraintOptions extends UISingleParameterConstraintOptions {
8
+ /** Anchor point for element A (0.0 = left edge, 0.5 = center, 1.0 = right edge). */
9
+ anchorA: number;
10
+ /** Anchor point for element B (0.0 = left edge, 0.5 = center, 1.0 = right edge). */
11
+ anchorB: number;
12
+ /** The desired horizontal distance between the elements. */
17
13
  distance: number;
18
- /** Priority level for this constraint */
19
- power: UIConstraintPower;
20
- /** Rule for the constraint relationship (equal, less than, greater than) */
21
- rule: UIConstraintRule;
22
- /** Screen orientation when this constraint should be active */
23
- orientation: UIOrientation;
24
14
  }
25
15
  /**
26
- * Constraint that enforces a specific horizontal distance between two UI elements.
16
+ * Constraint that enforces horizontal distance between two UI elements.
27
17
  *
28
- * This constraint measures the distance between two anchor points on the x-axis
29
- * and ensures it matches (or is less/greater than) the specified distance value.
18
+ * UIHorizontalDistanceConstraint creates a mathematical relationship that maintains
19
+ * a specific horizontal distance between two elements using configurable anchor points.
20
+ * For plane elements, anchors determine the reference point (0.0 = left, 0.5 = center, 1.0 = right).
21
+ * For point elements, the anchor is always the element's position. The constraint equation is:
22
+ * (elementB.x + elementB.width * anchorB) - (elementA.x + elementA.width * anchorA) = distance
23
+ *
24
+ * @see {@link UISingleParameterConstraint} - Base class for single-parameter constraints
25
+ * @see {@link UIPointElement} - Point elements that can be constrained
26
+ * @see {@link UIPlaneElement} - Plane elements that can be constrained
27
+ * @see {@link UIExpression} - Mathematical expressions for constraint equations
30
28
  */
31
- export declare class UIHorizontalDistanceConstraint extends UIConstraint {
32
- private readonly elementOne;
33
- private readonly elementTwo;
34
- /** The configuration options for this constraint */
35
- private readonly options;
36
- /** The Kiwi.js constraint object */
37
- private constraint?;
38
- /**
39
- * Creates a new horizontal distance constraint.
29
+ export declare class UIHorizontalDistanceConstraint extends UISingleParameterConstraint {
30
+ private readonly a;
31
+ private readonly b;
32
+ /** The constraint descriptor managed by the solver system. */
33
+ protected readonly constraint: number;
34
+ /** Internal storage for element A's anchor point. */
35
+ private anchorAInternal;
36
+ /** Internal storage for element B's anchor point. */
37
+ private anchorBInternal;
38
+ /** Internal storage for the horizontal distance value. */
39
+ private distanceInternal;
40
+ /**
41
+ * Creates a new UIHorizontalDistanceConstraint instance.
40
42
  *
41
- * @param elementOne - The first element or layer
42
- * @param elementTwo - The second element
43
- * @param options - Configuration options
43
+ * The constraint will use default anchor points (0.5 = center) and zero distance
44
+ * if not specified in options. Both elements must be from the same layer.
45
+ *
46
+ * @param a - The first UI element (point or plane element)
47
+ * @param b - The second UI element (point or plane element)
48
+ * @param options - Configuration options for the constraint
49
+ * @throws Will throw an error if elements are not from the same layer
50
+ * @see {@link assertValidConstraintSubjects}
44
51
  */
45
- constructor(elementOne: UIElement | UIAnchor | UILayer, elementTwo: UIElement | UIAnchor, options?: Partial<UIHorizontalDistanceOptions>);
52
+ constructor(a: UIPointElement | UIPlaneElement, b: UIPointElement | UIPlaneElement, options?: Partial<UIHorizontalDistanceConstraintOptions>);
46
53
  /**
47
- * Destroys this constraint, removing it from the constraint system.
54
+ * Gets the current horizontal distance being enforced.
55
+ * @returns The horizontal distance in pixels
48
56
  */
49
- destroy(): void;
57
+ get distance(): number;
50
58
  /**
51
- * Builds and adds the horizontal distance constraint to the constraint solver.
52
- *
53
- * Creates a constraint that enforces the distance between anchor points
54
- * on the x-axis of two elements based on the specified rule.
55
- *
59
+ * Gets the anchor point for element A.
60
+ * @returns The anchor value (0.0 = left, 0.5 = center, 1.0 = right)
61
+ */
62
+ get anchorA(): number;
63
+ /**
64
+ * Gets the anchor point for element B.
65
+ * @returns The anchor value (0.0 = left, 0.5 = center, 1.0 = right)
56
66
  */
57
- protected buildConstraints(): void;
67
+ get anchorB(): number;
58
68
  /**
59
- * Removes the horizontal distance constraint from the constraint solver.
69
+ * Sets a new horizontal distance and updates the constraint equation.
70
+ * @param value - The new horizontal distance in pixels
71
+ */
72
+ set distance(value: number);
73
+ /**
74
+ * Sets a new anchor point for element A and updates the constraint equation.
75
+ * @param value - The new anchor value (0.0 = left, 0.5 = center, 1.0 = right)
76
+ */
77
+ set anchorA(value: number);
78
+ /**
79
+ * Sets a new anchor point for element B and updates the constraint equation.
80
+ * @param value - The new anchor value (0.0 = left, 0.5 = center, 1.0 = right)
81
+ */
82
+ set anchorB(value: number);
83
+ /**
84
+ * Builds the left-hand side expression for the constraint equation.
85
+ *
86
+ * Creates the expression: (elementB.x + elementB.width * anchorB) - (elementA.x + elementA.width * anchorA)
87
+ * For point elements, only the x position is used since they have no width.
88
+ * For plane elements, the anchor determines the reference point within the element's width.
60
89
  *
90
+ * @returns The UIExpression representing the horizontal distance calculation
91
+ * @private
61
92
  */
62
- protected destroyConstraints(): void;
93
+ private buildLHS;
63
94
  }
@@ -1,58 +1,67 @@
1
- import { UIElement } from "../elements/UIElement";
2
- import type { UILayer } from "../layers/UILayer";
3
- import { UIOrientation } from "../miscellaneous/UIOrientation";
4
- import { UIConstraint } from "./UIConstraint";
5
- import type { UIConstraintPower } from "./UIConstraintPower";
6
- import type { UIConstraintRule } from "./UIConstraintRule";
1
+ import type { UIPlaneElement } from "../miscellaneous/asserts";
2
+ import type { UISingleParameterConstraintOptions } from "./UISingleParameterConstraint";
3
+ import { UISingleParameterConstraint } from "./UISingleParameterConstraint";
7
4
  /**
8
- * Configuration options for horizontal proportion constraints.
5
+ * Configuration options for UIHorizontalProportionConstraint creation.
9
6
  */
10
- export interface UIHorizontalProportionOptions {
11
- /** The proportion ratio between elements' widths */
7
+ export interface UIHorizontalProportionConstraintOptions extends UISingleParameterConstraintOptions {
8
+ /** The proportional relationship between element widths (elementA.width = elementB.width * proportion). */
12
9
  proportion: number;
13
- /** Priority level for this constraint */
14
- power: UIConstraintPower;
15
- /** Rule for the constraint relationship (equal, less than, greater than) */
16
- rule: UIConstraintRule;
17
- /** Screen orientation when this constraint should be active */
18
- orientation: UIOrientation;
19
10
  }
20
11
  /**
21
- * Constraint that enforces a proportional relationship between the widths of two elements.
12
+ * Constraint that enforces proportional width relationships between two UI elements.
22
13
  *
23
- * This constraint ensures that the width of one element is proportionally
24
- * related to the width of another element by a specified ratio.
14
+ * UIHorizontalProportionConstraint creates a mathematical relationship that maintains
15
+ * a proportional ratio between the widths of two plane elements. The constraint equation is:
16
+ * elementA.width * proportion = elementB.width, which can be rearranged as:
17
+ * elementA.width * proportion - elementB.width = 0
18
+ *
19
+ * This is useful for creating responsive layouts where elements need to maintain
20
+ * specific width ratios, such as sidebar-to-content ratios or grid column proportions.
21
+ *
22
+ * @see {@link UISingleParameterConstraint} - Base class for single-parameter constraints
23
+ * @see {@link UIPlaneElement} - Plane elements that can have proportional constraints applied
24
+ * @see {@link UIExpression} - Mathematical expressions for constraint equations
25
25
  */
26
- export declare class UIHorizontalProportionConstraint extends UIConstraint {
27
- private readonly elementOne;
28
- private readonly elementTwo;
29
- /** The configuration options for this constraint */
30
- private readonly options;
31
- /** The Kiwi.js constraint object */
32
- private constraint?;
26
+ export declare class UIHorizontalProportionConstraint extends UISingleParameterConstraint {
27
+ private readonly a;
28
+ private readonly b;
29
+ /** The constraint descriptor managed by the solver system. */
30
+ protected readonly constraint: number;
31
+ /** Internal storage for the current proportion value. */
32
+ private proportionInternal;
33
33
  /**
34
- * Creates a new horizontal proportion constraint.
34
+ * Creates a new UIHorizontalProportionConstraint instance.
35
+ *
36
+ * The constraint will enforce the relationship: elementA.width * proportion = elementB.width.
37
+ * If no proportion is specified, it defaults to 1.0 (equal widths).
38
+ * Both elements must be from the same layer.
35
39
  *
36
- * @param elementOne - The reference element or layer
37
- * @param elementTwo - The element to constrain proportionally
38
- * @param options - Configuration options
40
+ * @param a - The first UI plane element (whose width will be multiplied by proportion)
41
+ * @param b - The second UI plane element (target width for the proportion)
42
+ * @param options - Configuration options for the constraint
43
+ * @throws Will throw an error if elements are not from the same layer
44
+ * @see {@link assertValidConstraintSubjects}
39
45
  */
40
- constructor(elementOne: UIElement | UILayer, elementTwo: UIElement, options?: Partial<UIHorizontalProportionOptions>);
46
+ constructor(a: UIPlaneElement, b: UIPlaneElement, options?: Partial<UIHorizontalProportionConstraintOptions>);
41
47
  /**
42
- * Destroys this constraint, removing it from the constraint system.
48
+ * Gets the current proportion value being enforced.
49
+ * @returns The proportion ratio (elementA.width = elementB.width * proportion)
43
50
  */
44
- destroy(): void;
51
+ get proportion(): number;
45
52
  /**
46
- * Builds and adds the horizontal proportion constraint to the constraint solver.
47
- *
48
- * Creates a constraint expression in the form: (elementOne.width * proportion) - elementTwo.width = 0
49
- * This ensures the width ratio between elements matches the specified proportion.
50
- *
53
+ * Sets a new proportion value and updates the constraint equation.
54
+ * @param value - The new proportion ratio
51
55
  */
52
- protected buildConstraints(): void;
56
+ set proportion(value: number);
53
57
  /**
54
- * Removes the horizontal proportion constraint from the constraint solver.
58
+ * Builds the left-hand side expression for the constraint equation.
59
+ *
60
+ * Creates the expression: (elementA.width * proportion) - elementB.width = 0
61
+ * This enforces the relationship: elementA.width * proportion = elementB.width
55
62
  *
63
+ * @returns The UIExpression representing the proportional width relationship
64
+ * @private
56
65
  */
57
- protected destroyConstraints(): void;
66
+ private buildLHS;
58
67
  }
@@ -0,0 +1,108 @@
1
+ import type { UILayer } from "../layers/UILayer";
2
+ import { UIOrientation } from "../miscellaneous/UIOrientation";
3
+ import { type UIPriority } from "../miscellaneous/UIPriority";
4
+ import { type UIRelation } from "../miscellaneous/UIRelation";
5
+ import { UIConstraint } from "./UIConstraint";
6
+ /**
7
+ * Configuration options for UISingleParameterConstraint creation.
8
+ */
9
+ export interface UISingleParameterConstraintOptions {
10
+ /** Priority level for the constraint in the solver hierarchy. */
11
+ priority: UIPriority;
12
+ /** Mathematical relation type for the constraint equation. */
13
+ relation: UIRelation;
14
+ /** Orientation context for when the constraint should be active. */
15
+ orientation: UIOrientation;
16
+ }
17
+ /**
18
+ * Abstract base class for constraints that operate with configurable parameters.
19
+ *
20
+ * UISingleParameterConstraint extends UIConstraint with common functionality
21
+ * for constraints that need priority, relation, and orientation configuration.
22
+ * It provides automatic orientation-based enabling/disabling of constraints
23
+ * and manages the lifecycle of solver constraint descriptors.
24
+ *
25
+ * @see {@link UIConstraint} - Base constraint class
26
+ * @see {@link UIPriority} - Priority level configuration
27
+ * @see {@link UIRelation} - Mathematical relation types
28
+ * @see {@link UIOrientation} - Orientation-based activation
29
+ */
30
+ export declare abstract class UISingleParameterConstraint extends UIConstraint {
31
+ /** Internal storage for the constraint priority level. */
32
+ protected priorityInternal: UIPriority;
33
+ /** Internal storage for the constraint relation type. */
34
+ protected relationInternal: UIRelation;
35
+ /** Internal storage for the constraint orientation setting. */
36
+ protected orientationInternal: UIOrientation;
37
+ /** The constraint descriptor managed by the solver system. */
38
+ protected abstract readonly constraint: number;
39
+ /**
40
+ * Creates a new UISingleParameterConstraint instance.
41
+ *
42
+ * Initializes the constraint with resolved default values and sets up
43
+ * orientation change event handling for dynamic constraint activation.
44
+ *
45
+ * @param layer - The UI layer that contains this constraint
46
+ * @param priority - Optional priority level (defaults to P0)
47
+ * @param relation - Optional relation type (defaults to EQUAL)
48
+ * @param orientation - Optional orientation setting (defaults to ALWAYS)
49
+ */
50
+ constructor(layer: UILayer, priority?: UIPriority, relation?: UIRelation, orientation?: UIOrientation);
51
+ /**
52
+ * Gets the current priority level of the constraint.
53
+ * @returns The constraint priority level
54
+ */
55
+ get priority(): UIPriority;
56
+ /**
57
+ * Gets the current mathematical relation type of the constraint.
58
+ * @returns The constraint relation type
59
+ */
60
+ get relation(): UIRelation;
61
+ /**
62
+ * Gets the current orientation setting of the constraint.
63
+ * @returns The constraint orientation setting
64
+ */
65
+ get orientation(): UIOrientation;
66
+ /**
67
+ * Sets a new priority level for the constraint.
68
+ * @param value - The new priority level
69
+ */
70
+ set priority(value: UIPriority);
71
+ /**
72
+ * Sets a new mathematical relation type for the constraint.
73
+ * @param value - The new relation type
74
+ */
75
+ set relation(value: UIRelation);
76
+ /**
77
+ * Sets a new orientation setting for the constraint.
78
+ * @param value - The new orientation setting
79
+ */
80
+ set orientation(value: UIOrientation);
81
+ /**
82
+ * Destroys the constraint by cleaning up event listeners and solver resources.
83
+ *
84
+ * This method removes the orientation change event listener and removes
85
+ * the constraint from the solver system. After calling this method,
86
+ * the constraint should not be used anymore.
87
+ */
88
+ destroy(): void;
89
+ /**
90
+ * Determines if the constraint should be enabled based on orientation.
91
+ *
92
+ * The constraint is enabled if its orientation is set to ALWAYS or if
93
+ * it matches the current layer orientation.
94
+ *
95
+ * @returns True if the constraint should be enabled, false otherwise
96
+ * @protected
97
+ */
98
+ protected isConstraintEnabled(): boolean;
99
+ /**
100
+ * Event handler for layer orientation changes.
101
+ *
102
+ * Updates the constraint's enabled state in the solver based on the
103
+ * current orientation and the constraint's orientation setting.
104
+ *
105
+ * @private
106
+ */
107
+ private readonly onOrientationChange;
108
+ }