### Full Layout Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

A comprehensive example demonstrating how to lay out multiple views using OrbitalLayout's chaining and layout methods. This includes setting top, leading, trailing, size, and bottom constraints with priorities.

```swift
view.orbit(avatar, nameLabel, bioLabel, followButton) {
    avatar.orbital.layout(
        .top(24).to(view.safeAreaLayoutGuide, .top),
        .leading(16),
        .size(80)
    )

    nameLabel.orbital.layout(
        .top.to(avatar, .top),
        .leading(12).to(avatar, .trailing),
        .trailing(16)
    )

    bioLabel.orbital.layout(
        .top(4).to(nameLabel, .bottom),
        .leading.to(nameLabel, .leading),
        .trailing(16),
        .height(60).orLess
    )

    followButton.orbital.layout(
        .top(16).to(bioLabel, .bottom),
        .leading(16),
        .trailing(16),
        .height(44),
        .bottom(16).to(view.safeAreaLayoutGuide, .bottom).priority(.low)
    )
}
```

--------------------------------

### Standard DocC Comment Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/CLAUDE.md

Illustrates the standard DocC comment format for Swift code, including one-line summaries, extended descriptions, usage examples, parameter documentation, return values, and notes.

```swift
/// Short one-line summary (imperative mood, no period at end).
///
/// Extended description if needed. Explain *why*, not just *what*.
///
/// ```swift
/// // Usage example
/// view.orbital.layout(.top(16), .leading(16))
/// ```
///
/// - Parameters:
///   - constant: The inset value in points.
///   - relation: The relational operator. Defaults to `.equal`.
/// - Returns: The activated `OrbitalConstraint`.
/// - Note: Trailing and bottom constants are auto-negated internally.
```

--------------------------------

### Individual Descriptor Targeting Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/architecture.md

Demonstrates how to use individual descriptors when targeting specific views or guides, as OrbitalDescriptorGroup does not support .to() or .like() due to ambiguous semantics.

```swift
// .edges().to(safeArea) — NOT supported. Use individual descriptors:
view.orbital.layout(
    .top.to(view.safeAreaLayoutGuide),
    .bottom.to(view.safeAreaLayoutGuide),
    .leading.to(view.safeAreaLayoutGuide),
    .trailing.to(view.safeAreaLayoutGuide)
)
```

--------------------------------

### Constraint Coexistence Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/Enums.md

Illustrates how constraints with different relations on the same anchor can coexist and how to retrieve them.

```swift
view.orbital.layout(
    .width(200),          // width == 200 (stored under .equal)
    .width(300).orLess    // width <= 300 (stored under .lessOrEqual)
)

// Retrieve the <= constraint
let lessOrEqual = view.orbital.constraint(for: .width, relation: .lessOrEqual)
```

--------------------------------

### OrbitalProxy Usage Examples

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Demonstrates common OrbitalProxy operations including single constraint shortcuts, batch layout, and accessing stored constraints.

```swift
// Single shortcut
view.orbital.top(16)

// Batch layout
view.orbital.layout(.top(8), .leading(16), .trailing(16), .height(44))

// Stored accessor
view.orbital.heightConstraint?.constant = 100
```

--------------------------------

### OrbitalAnchor Usage Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/Enums.md

Demonstrates how to use OrbitalAnchor to define layout constraints, specifying source and target anchors.

```swift
subtitle.orbital.layout(
    .top(8).to(titleLabel, .bottom),   // source: .top, target: .bottom
    .leading.to(titleLabel, .leading)  // source: .leading, target: .leading (same)
)
```

--------------------------------

### CocoaPods Installation

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/README.md

Install OrbitalLayout in your project using CocoaPods by adding the pod name to your Podfile.

```ruby
pod 'OrbitalLayout'
```

--------------------------------

### Complete OrbitalLayout Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Demonstrates various OrbitalLayout functionalities including single and batch constraint creation, complex chaining, preparing constraints without activation, updating constants, content hugging/compression, accessing stored constraints, and remaking constraints.

```swift
let scrollView = UIScrollView()
let contentView = UIView()
let titleLabel = UILabel()
let descriptionLabel = UILabel()
let actionButton = UIButton()

// Single constraints with shortcuts
view.orbital.layout(.edges(0))

// Batch layout
scrollView.orbital.layout(
    .top(0),
    .leading(0),
    .trailing(0),
    .bottom(0)
)

// Complex chaining
contentView.orbital.layout(
    .top(16).to(scrollView, .top),
    .leading(16),
    .trailing(16),
    .width.like(view, 0.8)
)

// Prepare layout without activation
let constraints = titleLabel.orbital.prepareLayout(.top(8), .height(44))
constraints.activate()

// Update constant later
let h = descriptionLabel.orbital.height(120)
// ... later ...
h.constant = 200

// Content hugging
titleLabel.orbital.hugging(.required, axis: .horizontal)
descriptionLabel.orbital.compression(.high, axis: .vertical)

// Access stored constraints
if let topC = contentView.orbital.topConstraint {
    topC.constant = 24
}

// Update multiple at once
contentView.orbital.update(.edges(20))

// Remake with new target
contentView.orbital.remake(.top.to(navigationBar, .bottom))
```

--------------------------------

### OrbitalDescriptor Chaining Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/architecture.md

Demonstrates the chaining mechanism for OrbitalDescriptor, where each modifier creates a copy of the descriptor with updated properties.

```swift
// .top(8).to(header, .bottom).orMore.priority(.high).labeled("x")

func to(_ view: OrbitalView, _ anchor: OrbitalAnchor? = nil) -> OrbitalDescriptor {
    var copy = self
    copy.targetView = view
    copy.targetAnchor = anchor
    return copy
}
```

--------------------------------

### Complete View Controller Layout Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/Extensions.md

Demonstrates adding multiple subviews to a view controller using layout closures, inline constraints, and child-side additions. Also shows constraint preparation, activation, and constant updates.

```swift
// ViewController
class MyViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        let scrollView = UIScrollView()
        let contentView = UIView()
        let titleLabel = UILabel()
        let descriptionLabel = UILabel()
        let actionButton = UIButton()
        
        // Add multiple subviews to controller with layout closure
        self.orbit(scrollView, contentView) {
            scrollView.orbital.layout(.edges(0))
            contentView.orbital.layout(
                .top(16).to(scrollView, .top),
                .leading(16),
                .trailing(16)
            )
        }
        
        // Add individual subview with inline constraints
        self.orbit(add: titleLabel, .top(8), .leading(16), .trailing(16), .height(44))
        
        // Add from child perspective
        descriptionLabel.orbit(to: self, [
            .top(4).to(titleLabel, .bottom),
            .leading(16),
            .trailing(16),
            .height(120)
        ])
        
        // Manage constraints post-creation
        let constraints = contentView.orbital.prepareLayout(.bottom(16))
        // ... conditions ...
        constraints.activate()
        
        // Update constants
        titleLabel.orbital.heightConstraint?.constant = 50
        
        // Set content sizing priorities
        titleLabel.orbital.hugging(.required, axis: .horizontal)
        descriptionLabel.orbital.compression(.high, axis: .vertical)
    }
}

// View setup from another view
let containerView = UIView()
let childView1 = UIView()
let childView2 = UIView()
let childView3 = UIView()

// Parent-side add with inline constraints
containerView.orbit(add: childView1, .top(16), .leading(16), .width(100), .height(100))

// Parent-side add with array
let constraints = [OrbitalDescriptor.size(80), OrbitalDescriptor.center()]
containerView.orbit(add: childView2, constraints)

// Child-side add to parent
childView3.orbit(to: containerView, .bottom(16), .trailing(16), .size(44))

// Multiple children with layout closure
containerView.orbit(childView1, childView2, childView3) {
    childView1.orbital.layout(.top(16), .leading(16), .size(80))
    childView2.orbital.layout(.top.to(childView1, .bottom), .leading(16), .height(44))
    childView3.orbital.layout(.top(16), .trailing(16), .size(60))
}

// Deferred activation
let deferred = containerView.orbital.prepareLayout(.edges(20), .height(300))
// ... setup complete ...
deferred.activate()
deferred.deactivate()  // Toggle state

```

--------------------------------

### Constraining to Safe Area Layout Guide

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Demonstrates how to use the `safeAreaLayoutGuide` to set constraints relative to the view's safe area.

```swift
.top(16).to(view.safeAreaLayoutGuide, .top)
.bottom(16).to(view.safeAreaLayoutGuide, .bottom)
```

--------------------------------

### Redirect to a layout guide's anchor

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

Use `.to()` to redirect a constraint to a specific anchor on a layout guide, such as the safe area. The anchor on the target guide can be inferred if omitted.

```swift
public func to(_ guide: OrbitalLayoutGuide, _ anchor: OrbitalAnchor? = nil) -> OrbitalDescriptor
```

```swift
.top(16).to(view.safeAreaLayoutGuide, .top)
.bottom(16).to(view.safeAreaLayoutGuide, .bottom)
```

--------------------------------

### Swift Package Manager Installation

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/README.md

Add OrbitalLayout to your project using Swift Package Manager by specifying the repository URL and version.

```swift
.package(url: "https://github.com/dimayurkovski/OrbitalLayout.git", from: "1.0.0")
```

--------------------------------

### Aligning to Safe Area Layout Guide (iOS)

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

Pins view edges to the safe area layout guide. Note that `.edges().to(safeArea)` is not supported; use individual descriptors instead.

```swift
view.orbital.layout(
    .top.to(view.safeAreaLayoutGuide, .top),
    .bottom.to(view.safeAreaLayoutGuide, .bottom),
    .leading,
    .trailing
)
```

```swift
// Note: .edges().to(safeArea) is NOT supported — group descriptors don't support .to().
// Use individual descriptors to pin all edges to a layout guide:
view.orbital.layout(
    .top.to(view.safeAreaLayoutGuide),
    .bottom.to(view.safeAreaLayoutGuide),
    .leading.to(view.safeAreaLayoutGuide),
    .trailing.to(view.safeAreaLayoutGuide)
)
```

--------------------------------

### to(_:_:)

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

Redirects the constraint to a specific anchor on another view or layout guide.

```APIDOC
## to(_:_:) (View)

### Description
Redirects the constraint to a specific anchor on another view.

### Parameters
#### Path Parameters
- `view` (OrbitalView) - The target view
- `anchor` (OrbitalAnchor?) - Optional: The anchor on the target; inferred if omitted

### Returns
A new descriptor targeting `view` at `anchor`.

### Example
```swift
.top(8).to(header, .bottom)
.leading(8).to(avatar, .trailing)
.width.to(otherView)
```

## to(_:_:) (Layout Guide)

### Description
Redirects the constraint to a specific anchor on a layout guide.

### Parameters
#### Path Parameters
- `guide` (OrbitalLayoutGuide) - The target layout guide
- `anchor` (OrbitalAnchor?) - Optional: The anchor on the guide; inferred if omitted

### Returns
A new descriptor targeting `guide` at `anchor`.

### Example
```swift
.top(16).to(view.safeAreaLayoutGuide, .top)
.bottom(16).to(view.safeAreaLayoutGuide, .bottom)
```
```

--------------------------------

### OrbitalDescriptor TargetGuide Property

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

The target layout guide for this constraint, if any. Mutually exclusive with targetView.

```swift
public let targetGuide: OrbitalLayoutGuide?
```

--------------------------------

### Update Constraints Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Shows how to update existing constraints by modifying their constants. This method only changes constants and does not create new constraints. It ignores relation, priority, target, label, and multiplier.

```swift
view.orbital.update(
    .height(300),
    .top(24)
)
```

--------------------------------

### Remake Constraints Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Demonstrates how to remake constraints, which deactivates and replaces existing constraints for specified anchors. If no previous constraint exists, a new one is created. This is useful for changing any aspect of a constraint, not just the constant.

```swift
view.orbital.remake(
    .top(8),
    .leading(16),
    .trailing(16),
    .height(200)
)
```

--------------------------------

### Constant Sign Convention: Auto-negation Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/architecture.md

Illustrates the auto-negation of constants for .trailing, .bottom, and .right anchors when the source and target anchors are the same (same-edge constraint).

```swift
| Expression | Source | Target anchor | Same-edge? | `signOverride` | Constant |
|---|---|---|---|---|---|
| `.trailing(16)` | trailing | trailing *(inferred)* | ✅ | nil | **−16** |
| `.bottom(16)` | bottom | bottom *(inferred)* | ✅ | nil | **−16** |
| `.bottom(16).to(safeArea, .bottom)` | bottom | bottom | ✅ | nil | **−16** |
| `.trailing(8).to(avatar, .trailing)` | trailing | trailing | ✅ | nil | **−8** |
| `.bottom(16).to(header, .top)` | bottom | top | ❌ | nil | **+16** |
| `.leading(8).to(avatar, .trailing)` | leading | trailing | ❌ | nil | **+8** |
| `.trailing(8).to(avatar, .leading)` | trailing | leading | ❌ | nil | **+8** |
| `.top(16)` | top | top *(inferred)* | — | nil | **+16** *(never negated)* |
| `.centerX(16)` | centerX | centerX *(inferred)* | — | nil | **+16** *(never negated)* |
| `.width(100)` | width | width *(inferred)* | — | nil | **+100** *(never negated)* |
| `.trailing(16).asOffset` | trailing | trailing | ✅ | `.offset` | **+16** *(override)* |
| `.bottom(16).to(header, .top).asInset` | bottom | top | ❌ | `.inset` | **−16** *(override)* |
```

--------------------------------

### Constraint Sign Convention Examples

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/Internal.md

Illustrates the automatic sign negation applied by `ConstraintFactory` for same-edge constraints and reverse-spacer pairs. This convention allows users to consistently pass positive values.

```swift
// Same-edge: auto-negated
.trailing(16)  // view.trailing = superview.trailing − 16
```

```swift
// Reverse-spacer: auto-negated
.bottom(8).to(header, .top)  // view.bottom = header.top − 8
```

```swift
// Cross-anchor (non-reverse): not negated
.bottom(8).to(header, .bottom)  // view.bottom = header.bottom + 8
```

--------------------------------

### Animating Constraint Changes

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Provides an example of how to animate changes to a constraint's constant value. Ensure `layoutIfNeeded()` is called within the animation block.

```swift
view.orbital.heightConstraint?.constant = 300
UIView.animate(withDuration: 0.3) {
    view.superview?.layoutIfNeeded()
}
```

--------------------------------

### OrbitalLayoutGuide Type Alias

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/types.md

Defines a platform-agnostic layout guide type. It resolves to UILayoutGuide on iOS/tvOS and NSLayoutGuide on macOS. Used for constraining views to safe areas or other layout guides.

```swift
#if canImport(UIKit)
public typealias OrbitalLayoutGuide = UILayoutGuide
#elseif canImport(AppKit)
public typealias OrbitalLayoutGuide = NSLayoutGuide
#endif
```

--------------------------------

### Multi-Anchor Shortcuts

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/README.md

Demonstrates the use of convenient multi-anchor shortcuts for common layout patterns like edges, size, and centering.

```APIDOC
## Multi-Anchor Shortcuts

### Description
Utilizes multi-anchor shortcuts for defining common layout configurations like edges, size, and centering with optional offsets.

### Method
Implicit (via property access and method call)

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```swift
view.orbital.layout(.edges(16))           // all 4 edges, 16pt inset
view.orbital.layout(.size(width: 320, height: 180))
view.orbital.layout(.center(offset: CGPoint(x: 10, y: -5)))
```

### Response
#### Success Response
N/A (Constraints are activated)

#### Response Example
None
```

--------------------------------

### Batch Layout Creation

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/README.md

Shows how to define and activate multiple layout constraints simultaneously using the `.layout()` method. This is useful for setting up multiple constraints for a view at once.

```APIDOC
## Batch Layout Creation

### Description
Defines and activates multiple layout constraints for a view in a single call.

### Method
Implicit (via property access and method call)

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```swift
view.orbital.layout(
    .top(8),
    .leading(16),
    .trailing(16),
    .height(200)
)
```

### Response
#### Success Response
N/A (Constraints are activated)

#### Response Example
None
```

--------------------------------

### Setting Size and Aspect Ratio

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

Utilize size shortcuts for square dimensions, explicit width/height, or aspect ratios. Match superview dimensions by omitting arguments.

```swift
// Square
iconView.orbital.layout(.size(44))

// Explicit width and height
bannerView.orbital.layout(.size(width: 320, height: 180))

// Aspect ratio: width = height * 16/9
videoView.orbital.layout(
    .aspectRatio(16.0 / 9.0),
    .leading,
    .trailing
)

// .width / .height without args = match superview's dimension
childView.orbital.layout(.width)   // width == superview.width
childView.orbital.layout(.height)  // height == superview.height
```

--------------------------------

### Size Shortcuts

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Offers shortcuts for defining view sizes, including equal width and height, explicit width and height, aspect ratio, and matching the dimensions of another view.

```APIDOC
## 5. Size Shortcuts

```swift
.size(_ side: CGFloat)                              // width == height == side
.size(width: CGFloat, height: CGFloat)               // explicit width and height
.aspectRatio(_ ratio: CGFloat)                       // self.width == self.height * ratio
.width.to(otherView)                                 // width == other view's width
.height.to(otherView)                                // height == other view's height
```
```

--------------------------------

### OrbitalRelation Usage Example

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/Enums.md

Demonstrates using OrbitalRelation modifiers like 'orLess' and 'orMore' to set constraint relations.

```swift
descriptionLabel.orbital.layout(
    .height(120).orLess   // NSLayoutRelation.lessThanOrEqual
)

button.orbital.layout(
    .width(100).orMore,   // NSLayoutRelation.greaterThanOrEqual
    .height(44)           // NSLayoutRelation.equal (default)
)
```

--------------------------------

### Import OrbitalLayout

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Import the OrbitalLayout library to use its functionalities.

```swift
import OrbitalLayout
```

--------------------------------

### prepareLayout(_:)

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Array-accepting overload for preparing layouts without activation. This is useful for dynamically built descriptor lists.

```APIDOC
## prepareLayout(_:)

### Description
Array-accepting overload for dynamic descriptor lists.

### Method Signature
```swift
@discardableResult
public func prepareLayout(_ items: [any OrbitalConstraintConvertible]) -> [OrbitalConstraint]
```

### Parameters
#### Path Parameters
- **items** (`[any OrbitalConstraintConvertible]`) - Required - An array of constraint descriptors

### Returns
- `[OrbitalConstraint]` - All created (inactive) `OrbitalConstraint` instances.
```

--------------------------------

### prepareLayout(_:)

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Creates and stores constraints without activating them. Constraints created with this method can be activated later by calling `.activate()` on the returned array.

```APIDOC
## prepareLayout(_:)

### Description
Creates and stores constraints **without activating them**. Named accessors (`topConstraint`, etc.) will return these constraints even while inactive. Call `.activate()` on the returned array when ready.

### Method Signature
```swift
@discardableResult
public func prepareLayout(_ items: any OrbitalConstraintConvertible...) -> [OrbitalConstraint]
```

### Parameters
#### Path Parameters
- **items** (`any OrbitalConstraintConvertible...`) - Required - One or more constraint descriptors

### Returns
- `[OrbitalConstraint]` - All created (inactive) `OrbitalConstraint` instances.
```

--------------------------------

### Prepare and Activate Constraints

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/README.md

Prepare layout constraints for a view and then activate or deactivate them. This is useful for managing dynamic layout changes.

```swift
let constraints = view.orbital.prepareLayout(.top(8), .leading(16))
// ... conditions ...
constraints.activate()
constraints.deactivate()
```

--------------------------------

### Get Constraint by Anchor and Relation

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Retrieves a stored constraint for a specific anchor and relation. Useful for accessing constraints with non-equal relations like <= or >=.

```swift
public func constraint(for anchor: OrbitalAnchor, relation: OrbitalRelation) -> OrbitalConstraint?
```

```swift
view.orbital.layout(
    .width(200),
    .width(300).orLess
)
view.orbital.constraint(for: .width, relation: .lessOrEqual)  // → <= 300
```

--------------------------------

### Batch Layout Constraints

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/architecture.md

Provides methods for applying multiple constraints at once. `layout` activates constraints immediately, while `prepareLayout` creates and stores them without activation.

```swift
@discardableResult func layout(_ items: OrbitalConstraintConvertible...) -> [OrbitalConstraint]
@discardableResult func prepareLayout(_ items: OrbitalConstraintConvertible...) -> [OrbitalConstraint]
```

--------------------------------

### Get Stored Constraint from OrbitalLayout Storage

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/Internal.md

Retrieves a stored constraint based on the anchor and relation. Returns nil if no constraint matches the key.

```swift
@MainActor
func get(_ anchor: OrbitalAnchor, relation: OrbitalRelation = .equal) -> OrbitalConstraint?
```

--------------------------------

### Size Constraint Shortcuts

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Shortcuts for defining width, height, aspect ratio, or matching the size of another view.

```swift
.size(_ side: CGFloat) // width == height == side
.size(width: CGFloat, height: CGFloat) // explicit width and height
.aspectRatio(_ ratio: CGFloat) // self.width == self.height * ratio
.width.to(otherView) // width == other view's width
.height.to(otherView) // height == other view's height
```

--------------------------------

### Redirect Constraint Target with .to()

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Redirects a constraint to a different view's anchor or a specific layout guide. Useful for aligning to superview edges or other views.

```swift
.top(8).to(header, .bottom) // view.top = header.bottom + 8
.bottom(16).to(view.safeAreaLayoutGuide, .bottom)
.leading(8).to(avatar, .trailing) // view.leading = avatar.trailing + 8
.width().to(otherView) // width == otherView.width
```

--------------------------------

### Single Constraint Creation

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/README.md

Demonstrates the basic usage of creating a single layout constraint using the OrbitalLayout DSL. This is the simplest way to add a constraint.

```APIDOC
## Single Constraint Creation

### Description
Creates a single layout constraint using the OrbitalLayout DSL.

### Method
Implicit (via property access and method call)

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```swift
view.orbital.top(16)
```

### Response
#### Success Response
N/A (Constraint is activated)

#### Response Example
None
```

--------------------------------

### Layout with Sign Convention

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/README.md

Demonstrates how to use positive values for layout constraints, with auto-negation for same-edge constraints. Use `.asOffset` to suppress negation and `.asInset` to force negation.

```swift
view.orbital.layout(
    .trailing(16),                                // view.trailing = superview.trailing − 16
    .bottom(16)                                   // view.bottom   = superview.bottom   − 16
)

// cross-anchor overrides
.trailing(8).to(avatar, .trailing).asOffset      // suppress negation
.bottom(16).to(header, .top).asInset             // force negation
```

--------------------------------

### Creating a Layout Constraint with OrbitalDescriptor

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

Example of chaining modifiers on an OrbitalDescriptor to define a layout constraint. This snippet shows how to set the top anchor, a constant, a target view and anchor, and priority.

```swift
view.orbital.layout(
    .top(8).to(header, .bottom).orMore.priority(.high).labeled("contentTop")
)
```

--------------------------------

### Practical: Card with Shadow Layout

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

Demonstrates laying out a card view with its title and subtitle labels, including constraints relative to the superview's safe area and each other.

```swift
view.orbit(card) {
    card.orbital.layout(
        .top(16).to(view.safeAreaLayoutGuide, .top),
        .leading(20),
        .trailing(20),
        .height(120)
    )
}

card.orbit(titleLabel, subtitleLabel) {
    titleLabel.orbital.layout(
        .top(16),
        .leading(16),
        .trailing(16)
    )
    subtitleLabel.orbital.layout(
        .top(8).to(titleLabel, .bottom),
        .leading(16),
        .trailing(16),
        .bottom(16).priority(.low)
    )
}
```

--------------------------------

### Multi-Anchor Layout Shortcuts

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/README.md

Apply layout constraints for edges, size, and center using convenient multi-anchor shortcuts.

```swift
view.orbital.layout(.edges(16))           // all 4 edges, 16pt inset
view.orbital.layout(.size(width: 320, height: 180))
view.orbital.layout(.center(offset: CGPoint(x: 10, y: -5)))
```

--------------------------------

### Add Single Child with Variadic Constraints

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

Adds a subview to a parent view and applies constraints using a variadic list of constraint definitions. Useful for quick, inline constraint setup.

```swift
// Add label as subview of view with constraints to superview (variadic)
view.orbit(add: label, .top(16), .leading(16), .trailing(16))
```

--------------------------------

### Pin to Target Anchor

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

Defines constraints by relating anchors of one view to anchors of another view or a layout guide. Supports various relationships including edge-to-edge, side-by-side, and dimension matching.

```swift
// Pin to another view's anchor
subtitle.orbital.layout(
    .top(8).to(titleLabel, .bottom),
    .leading.to(titleLabel, .leading)
)

// Pin to layout guide
// same-anchor → auto-negated: top = +16, bottom = -16 (insets from safe area edges)
view.orbital.layout(
    .top(16).to(view.safeAreaLayoutGuide, .top),
    .bottom(16).to(view.safeAreaLayoutGuide, .bottom)
)

// Leading to trailing (side by side)
badge.orbital.layout(
    .leading(8).to(icon, .trailing),
    .centerY.to(icon, .centerY)
)

// Width equal to another view (anchor inferred)
thumbnailView.orbital.layout(
    .width.to(headerView)              // width == headerView.width
)

// Width equal — explicit anchor
thumbnailView.orbital.layout(
    .width.to(headerView, .width)      // same result, explicit
)

// Width equal to another view's height (cross-dimension)
thumbnailView.orbital.layout(
    .width.to(headerView, .height)     // width == headerView.height
)

// Width equal to another view's width + offset
thumbnailView.orbital.layout(
    .width(40).to(headerView, .width)  // width == headerView.width + 40
)
```

--------------------------------

### Target Anchor (`.to(...)`)

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Specifies the target anchor for a constraint, allowing it to be relative to another view's anchor or a specific layout guide. This is used for creating relationships between different UI elements.

```APIDOC
## 7. `.to(...)` — Target Anchor

Redirects a constraint to another view or anchor.

```swift
.top(8).to(header, .bottom)          // view.top = header.bottom + 8
.bottom(16).to(view.safeAreaLayoutGuide, .bottom)
.leading(8).to(avatar, .trailing)    // view.leading = avatar.trailing + 8
.width().to(otherView)               // width == otherView.width
```
```

--------------------------------

### OrbitalProxy Initializer

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Initializes an OrbitalProxy for a given view. The view is held weakly to prevent retain cycles.

```APIDOC
## init(view:)

### Description
Creates a proxy for the given view.

### Parameters
#### Path Parameters
- **view** (OrbitalView) - The view whose constraints this proxy manages

### Returns
An OrbitalProxy instance.
```

--------------------------------

### Content Hugging and Compression Resistance in Orbital Layout

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Configure content hugging and compression resistance priorities for views along specified axes using shortcuts provided by the library.

```swift
.hugging(.high, axis: .horizontal)
.hugging(.low, axis: .vertical)
.compression(.required, axis: .horizontal)
.compression(.low, axis: .vertical)
```

--------------------------------

### Access and Mutate Stored Edge Constraints

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Access stored edge constraints to read or mutate properties like 'constant'. This example first lays out constraints and then modifies the height constraint's constant.

```swift
view.orbital.layout(.top(16), .height(200))
view.orbital.heightConstraint?.constant = 300
```

--------------------------------

### layout(_:)

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Creates, activates, and stores constraints from an array of descriptors. This overload is useful when the list of descriptors is built dynamically.

```APIDOC
## layout(_:)

### Description
Array-accepting overload. Useful when the descriptor list is built dynamically.

### Method Signature
```swift
@discardableResult
public func layout(_ items: [any OrbitalConstraintConvertible]) -> [OrbitalConstraint]
```

### Parameters
#### Path Parameters
- **items** (`[any OrbitalConstraintConvertible]`) - Required - An array of constraint descriptors or groups

### Returns
- `[OrbitalConstraint]` - All activated `OrbitalConstraint` instances.
```

--------------------------------

### width, height - Match view dimensions to superview

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

Creates descriptors to match the view's width or height to the superview's corresponding dimension.

```APIDOC
## width, height - Match view dimensions to superview

### Description
Descriptors that match the view's dimensions to the superview's dimensions.

### Method
`width`, `height`

### Request Example
```swift
view.orbital.layout(.width)
view.orbital.layout(.height)
```
```

--------------------------------

### width(_:), height(_:) - Fixed dimensions

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

Creates descriptors for setting a fixed width or height for the view, specified in points.

```APIDOC
## width(_:), height(_:) - Fixed dimensions

### Description
Create descriptors for fixed width and height constraints.

### Method
`width(_:)`, `height(_:)

### Parameters
#### Path Parameters
- **constant** (`CGFloat`) - Required - The dimension in points

### Request Example
```swift
view.orbital.layout(.width(100))
view.orbital.layout(.height(44))
```

### Returns
An `OrbitalDescriptor` for the specified dimension.
```

--------------------------------

### Prepare Constraints Without Immediate Activation in Orbital Layout

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Use `prepareLayout()` to create constraints and store them in `ConstraintStorage` without activating them immediately. Call `.activate()` later when ready.

```swift
let constraints = view.orbital.prepareLayout(
    .top(8),
    .leading(16),
    .trailing(16)
)
// activate later
constraints.activate()
```

--------------------------------

### width(_:), height(_:)

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Sets fixed dimension constraints for the view's width and height. Returns the activated, stored OrbitalConstraint.

```APIDOC
## width(_:), height(_:)

### Description
Set fixed dimension constraints.

### Parameters
#### Path Parameters
- **constant** (CGFloat) - The dimension in points.

### Returns
The activated, stored OrbitalConstraint.

### Example
```swift
view.orbital.width(100)   // view.width = 100
view.orbital.height(44)   // view.height = 44
```
```

--------------------------------

### Center X and Center Y Constraint Shortcuts

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Center the view with an optional offset. Returns the activated, stored OrbitalConstraint.

```swift
@discardableResult
public func centerX(_ offset: CGFloat = 0) -> OrbitalConstraint
@discardableResult
public func centerY(_ offset: CGFloat = 0) -> OrbitalConstraint
```

```swift
view.orbital.centerX()     // view.centerX = superview.centerX
view.orbital.centerY(8)    // view.centerY = superview.centerY + 8
```

--------------------------------

### Preparing Constraints Without Immediate Activation

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

Use 'prepareLayout' to create constraints without activating them. This allows for later activation or modification. Named accessors remain available.

```swift
// Create but don't activate yet
let constraints = view.orbital.prepareLayout(
    .top(8),
    .leading(16),
    .trailing(16)
)

// Named accessors still work while inactive
print(view.orbital.topConstraint)  // not nil, but inactive

// Activate when ready
constraints.activate()
```

--------------------------------

### OrbitalProxy Initializer

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Initializes an OrbitalProxy for a given view. The view is held weakly to prevent retain cycles.

```swift
@MainActor
public init(view: OrbitalView)
```

--------------------------------

### Dynamic Leading Constraint Swap

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

Shows how to initially align an icon view to the superview's leading edge and then remake the constraint to align it with another view's trailing edge on an event.

```swift
// Setup: leading to superview
iconView.orbital.layout(
    .leading(16),
    .centerY
)

// On some event: remake to align with another view
iconView.orbital.remake(
    .leading(8).to(badgeView, .trailing)
)
```

--------------------------------

### Width and Height Constraint Shortcuts

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Set fixed dimension constraints for the view. Returns the activated, stored OrbitalConstraint.

```swift
@discardableResult
public func width(_ constant: CGFloat) -> OrbitalConstraint
@discardableResult
public func height(_ constant: CGFloat) -> OrbitalConstraint
```

```swift
view.orbital.width(100)   // view.width = 100
view.orbital.height(44)   // view.height = 44
```

--------------------------------

### Size Layout

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

Methods for setting the size constraints of a view.

```APIDOC
## Size Layout

### Description
Methods for setting the size constraints of a view.

### Methods

- `static func size(_ side: CGFloat) -> OrbitalDescriptorGroup`
  Sets equal width and height constraints (square).
  Example: `view.orbital.layout(.size(80))`
  #### Parameters
  - `side` (CGFloat) - Required - The value applied to both width and height

- `static func size(width: CGFloat, height: CGFloat) -> OrbitalDescriptorGroup`
  Sets explicit width and height constraints.
  Example: `view.orbital.layout(.size(width: 320, height: 180))`
  #### Parameters
  - `width` (CGFloat) - Required - The width in points
  - `height` (CGFloat) - Required - The height in points
```

--------------------------------

### Applying Priorities to Layout Constraints

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/Enums.md

Demonstrates how to assign different priority levels (.high, .custom, .low, default .required) to layout constraints using the .priority() modifier.

```swift
view.orbital.layout(
    .top(16).priority(.high),         // 750 — can be broken if needed
    .height(44).priority(.custom(600))
    .bottom(16).priority(.low),       // 250 — easily sacrificed
    .height(44),                      // 1000 — required (default)
)
```

--------------------------------

### Practical: Expandable Panel Implementation

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

A custom UIView subclass that can expand and collapse. It uses OrbitalLayout to manage its height and animates the changes.

```swift
class ExpandablePanel: UIView {
    let contentView = UIView()

    func setup(in parent: UIView) {
        parent.orbit(add: self, .top, .leading, .trailing)
        orbit(contentView, .edges)
        orbital.layout(.height(60))
    }

    func expand() {
        orbital.update(.height(200))
        UIView.animate(withDuration: 0.3) {
            self.superview?.layoutIfNeeded()
        }
    }

    func collapse() {
        orbital.update(.height(60))
        UIView.animate(withDuration: 0.3) {
            self.superview?.layoutIfNeeded()
        }
    }
}
```

--------------------------------

### Using Multipliers with Constraints

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/requirements.md

Illustrates how to use multipliers with constraints, especially for dimensions. The `.like()` method can be used with any anchor type, falling back to the `NSLayoutConstraint` initializer for non-dimension anchors.

```swift
.width.like(superview, 0.4)
.height.like(otherView, 2)
.width.like(otherView)
.height.like(imageView)
.height.like(otherView, .width, 0.5)   // height == otherView.width * 0.5
.height.like(.width, 0.4)             // height == self.width * 0.4
```

--------------------------------

### Single Constraint Shortcuts

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

Provides direct methods for applying common single constraints like top, bottom, leading, trailing, width, height, and centering. These can be used to discard the constraint result or capture it for later modification or animation.

```swift
// Discard result (layout only)
view.orbital.top(16)
view.orbital.bottom(16)
view.orbital.leading(16)
view.orbital.trailing(16)

// Capture for later use (animate, toggle, update)
let topConstraint = view.orbital.top(16)
let heightConstraint = view.orbital.height(44)

topConstraint.constant = 32
UIView.animate(withDuration: 0.3) { view.superview?.layoutIfNeeded() }

// Size
view.orbital.width(100)
view.orbital.height(44)

// Center
view.orbital.centerX()
view.orbital.centerY(8)     // offset 8pt downward
```

--------------------------------

### Applying SignOverride Modifiers

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/Enums.md

Illustrates how to use .asOffset and .asInset modifiers to control the sign convention of layout constants, overriding the default auto-negation.

```swift
// Default: auto-negation applies
.trailing(8)  // view.trailing = superview.trailing − 8

// Override with .asOffset
.trailing(8).asOffset  // view.trailing = superview.trailing + 8

// Override with .asInset on cross-anchor
.bottom(16).to(header, .top).asInset  // view.bottom = header.top − 16
```

--------------------------------

### Apply Orbital Layout Constraints to a View

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

Demonstrates how to use the `orbit` and `orbital.layout` methods to define layout constraints for a content view within its superview. This is useful for setting up spacing and alignment relative to other views or edges.

```swift
let contentView = UIView()
let header = UIView()
let button = UIButton()

self.view.orbit(contentView) {
    contentView.orbital.layout(
        .top(8).to(header, .bottom),
        .leading(16),
        .trailing(16),
        .bottomLess(16).priority(.high),
        .labeled("contentView.layout")
    )
}

button.orbit(to: contentView, [
    .top(20),
    .leading(16),
    .trailing(16),
    .height(44)
])

// Update constant later
contentView.orbital.heightConstraint?.constant = 300
```

--------------------------------

### layout(_:)

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalProxy.md

Creates, activates, and stores constraints for multiple descriptors. If a constraint for the same anchor and relation already exists, it is deactivated and replaced.

```APIDOC
## layout(_:)

### Description
Creates, activates, stores, and returns constraints for all given descriptors. If a constraint for the same `anchor + relation` combination was stored previously, the previous constraint is **deactivated and replaced** by the new one.

### Method Signature
```swift
@discardableResult
public func layout(_ items: any OrbitalConstraintConvertible...) -> [OrbitalConstraint]
```

### Parameters
#### Path Parameters
- **items** (`any OrbitalConstraintConvertible...`) - Required - One or more constraint descriptors or groups

### Returns
- `[OrbitalConstraint]` - All activated `OrbitalConstraint` instances, in declaration order.
```

--------------------------------

### OrbitalLayout File Structure

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/README.md

This snippet displays the directory structure of the OrbitalLayout project. It helps understand the organization of source files across different modules.

```plaintext
Sources/
├── Core/
│   ├── OrbitalAnchor.swift
│   ├── OrbitalRelation.swift
│   ├── OrbitalPriority.swift
│   ├── OrbitalDescriptor.swift
│   └── ConstraintFactory.swift
├── Proxy/
│   └── OrbitalProxy.swift
├── Extensions/
│   ├── PlatformAliases.swift
│   ├── OrbitalView+Orbital.swift
│   ├── OrbitalViewController+Orbital.swift
│   └── OrbitalConstraint+Orbital.swift
└── Storage/
    └── ConstraintStorage.swift
```

--------------------------------

### bottom, leading, trailing, left, right - Pin edges to superview

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

Creates descriptors to pin edges (bottom, leading, trailing, left, right) to the superview with zero inset. Note that `bottom` and `trailing` constants are auto-negated internally.

```APIDOC
## bottom, leading, trailing, left, right - Pin edges to superview

### Description
Descriptors that pin edges to the superview with zero inset. `bottom` and `trailing` constants are auto-negated internally.

### Method
`bottom`, `leading`, `trailing`, `left`, `right`
```

--------------------------------

### Configuring Content Hugging and Compression Resistance

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/Docs/examples.md

Controls how views behave when their intrinsic content size differs from the available space. Use `.high` or `.low` for hugging and `.required` or `.low` for compression resistance.

```swift
// Prevent label from stretching horizontally
titleLabel.orbital.hugging(.high, axis: .horizontal)
titleLabel.orbital.compression(.required, axis: .horizontal)

// Allow subtitle to compress before title
subtitleLabel.orbital.hugging(.low, axis: .horizontal)
subtitleLabel.orbital.compression(.low, axis: .horizontal)
```

--------------------------------

### Add and Layout Subview

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/README.md

Shows how to add a subview to a parent view and define its constraints in a single, combined operation using `orbit(add:)` or `orbit(to:)`.

```APIDOC
## Add and Layout Subview

### Description
Adds a subview to a parent view and defines its layout constraints in a single operation, simplifying view hierarchy management.

### Method
Implicit (via extension methods)

### Endpoint
N/A (SDK methods)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```swift
// Parent-side
view.orbit(add: label, .top(16), .leading(16), .trailing(16))
view.orbit(add: imageView, [.edges(4), .aspectRatio(1)])

// Child-side
label.orbit(to: view, .top(16), .leading(16), .trailing(16))
```

### Response
#### Success Response
N/A (Subview is added and constraints are activated)

#### Response Example
None
```

--------------------------------

### priority(_:)

Source: https://github.com/dimayurkovski/orbitallayout/blob/main/_autodocs/api-reference/OrbitalDescriptor.md

Sets the layout priority of the constraint.

```APIDOC
## priority(_:)

### Description
Sets the layout priority of the constraint.

### Parameters
#### Path Parameters
- `p` (OrbitalPriority) - The desired priority

### Returns
A new descriptor with the specified priority.

### Example
```swift
.height(200).priority(.high)
.top(16).priority(.custom(600))
.bottom(16).priority(.low)
```
```