Expand the docs around @quicklayout usage and the manual integration

Summary: People have reported to me that Devmate often uses .applyFrame when using QuickLayout. However, it's against the recommendation. I updated the docs so that it's even more clear.

Differential Revision: D87983350

fbshipit-source-id: f7dd2c18a5e4de9c8b671447c9b845cadeaba4d1

Author: constantine-fry

Sources/QuickLayout/docs/docs/how-to-use/manual-layout-integration-uiviewcontrollers.mdx

@@ -0,0 +1,32 @@
+---
+id: manual-layout-integration-uiviewcontrollers
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# UIViewControllers
+
+Since the macro is not available for view controllers, you need to manually manage the view hierarchy and override `viewDidLayoutSubviews`.
+In the example below, note how `viewDidLayoutSubviews` insets the `view.bounds` by the `safeAreaInsets` and then applies the frame to the body.
+```swift
+final class MyViewController: UIViewController {
+
+  var body: Layout {
+    ...
+  }
+
+  override func viewDidLoad() {
+    super.viewDidLoad()
+    view.addSubviews {
+      view1
+      view2
+    }
+  }
+
+  override func viewDidLayoutSubviews() {
+    super.viewDidLayoutSubviews()
+    let layoutRect = view.bounds.inset(by: view.safeAreaInsets)
+    body.applyFrame(layoutRect)
+  }
+}
+```

Sources/QuickLayout/docs/docs/how-to-use/quick-layout-without-macro.mdx renamed to Sources/QuickLayout/docs/docs/how-to-use/manual-layout-integration.mdx

@@ -4,9 +4,10 @@ id: manual-layout-integration
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-# Manual Layout Integration
+# Manual Integration
+
+When needed, you can still use QuickLayout without the macro by manually managing the view hierarchy and overriding the `layoutSubviews` and `sizeThatFits` methods.
 
-The @QuickLayout macro is available for all view instances, but not view controllers. When needed, you can still use QuickLayout without this macro. In that case, you will need to manually manage the view hierarchy and override the `layoutSubviews` and `sizeThatFits` methods. The snippet below demonstrates a view that does not utilize the @QuickLayout macro, but still utilizes a declarative syntax for layout.
 ```swift
 import QuickLayout
 

Sources/QuickLayout/docs/docs/how-to-use/quick-layout-macro-bodyContainerView.mdx

@@ -0,0 +1,33 @@
+---
+id: macro-layout-integration-bodyContainerView
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# Custom Content View
+
+By default, QuickLayout adds subviews directly within the view itself.
+However, some views may require a different container view for their subviews.
+You can override the `bodyContainerView` property to specify an alternative container view.
+For example, collection view and table view cells use this to ensure views are added to the `contentView`.
+
+```swift
+@QuickLayout
+final class ExperimentedView: UIView {
+
+  let contentView = UIView()
+
+  init() {
+    super.init(frame: .zero)
+    addsSubview(contentView)
+  }
+
+  override public var bodyContainerView: UIView {
+    contentView /// This will be the container view for the body.
+  }
+
+  var body: Layout {
+    ...
+  }
+}
+```

Sources/QuickLayout/docs/docs/how-to-use/quick-layout-macro-donts.mdx

@@ -0,0 +1,57 @@
+---
+id: macro-layout-integration-donts
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# Traps
+
+:::danger Don't use @QuickLayout macro on UIViewControllers
+[See this page for integration with UIViewControllers](manual-layout-integration-uiviewcontrollers.mdx).
+```swift
+@QuickLayout /// <-- 🛑 Don't use the macro on UIViewControllers
+final class MyViewController: UIViewController {
+
+  var body: Layout {
+    ...
+  }
+}
+```
+:::
+
+:::danger DON'T
+When using @QuickLayout, don't call `body.applyFrame()`.
+This will result in double measurements.
+
+
+```swift
+@QuickLayout
+final class VerySlowView: UIView {
+
+  var body: Layout {
+    ...
+  }
+
+  /// @QuickLayout macro will insert additional
+  /// _QuickLayoutViewImplementation call into this method.
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    body.applyFrame(self.bounds) /// <-- 🛑 Don't call applyFrame when using @QuickLayout macro
+  }
+}
+```
+:::
+
+:::danger Don't create views in the body
+```swift
+@QuickLayout
+final class MyView: UIView {
+
+  var body: Layout {
+    HStack {
+      UIView() /// <-- 🛑 Don't create views in the body
+    }
+  }
+}
+```
+:::

Sources/QuickLayout/docs/docs/how-to-use/quick-layout-macro-dos.mdx

@@ -0,0 +1,50 @@
+---
+id: macro-layout-integration-dos
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# Tips
+
+:::tip It's OK to override layoutSubviews
+
+This is a great way to add custom layout logic to your view.
+```swift
+@QuickLayout
+final class ViewWithAdditionalLayoutBehaviour: UIView {
+
+  let label = UILabel()
+
+  var body: Layout {
+    ...
+  }
+
+  /// Feel free to override layoutSubviews to customize your layout.
+  override func layoutSubviews() {
+    super.layoutSubviews()
+    label.frame = ....
+  }
+}
+```
+:::
+
+:::tip It's OK to override sizeThatFits
+
+```swift
+@QuickLayout
+final class ViewWithFixedSize: UIView {
+
+  var body: Layout {
+    ...
+  }
+
+  /// 👍 It's OK to override sizeThatFits
+  override func sizeThatFits(_ size: CGSize) -> CGSize {
+    /// Note you can achieve the same result
+    /// by using the `.frame(height: 100)` modifier in the body.
+    CGSize(width: size.widith, height: 100)
+  }
+}
+```
+
+:::

Sources/QuickLayout/docs/docs/how-to-use/quick-layout-macro-isBodyEnabled.mdx

@@ -0,0 +1,53 @@
+---
+id: macro-layout-integration-isBodyEnabled
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+
+# Experimentation
+
+To help you experiment with QuickLayout, the macro provides a way to disable QuickLayout on a specific view.
+This is achieved by overriding the `isBodyEnabled` property.
+
+```swift
+@QuickLayout
+final class ExperimentedView: UIView {
+
+  override var isBodyEnabled: Bool {
+    featureFlags.isQuickLayoutEnabled
+  }
+
+  init() {
+    super.init(frame: .zero)
+    if !isBodyEnabled {
+      self.addSubviews {
+        label
+        image
+      }
+    }
+  }
+
+  var body: Layout {
+    ...
+  }
+
+  override public func layoutSubviews() {
+    super.layoutSubviews()
+    /// Note: you don't need to call
+    /// _QuickLayoutViewImplementation.layoutSubviews(self)
+    /// because it's automatically injected by the macro.
+    if !isBodyEnabled {
+      imperativeManualLayoutSubviews()
+    }
+  }
+
+  override public func sizeThatFits(_ size: CGSize) -> CGSize {
+    if !isBodyEnabled {
+      imperativeManualSizeThatFits(size)
+    }
+    /// OK to call for migration.
+    _QuickLayoutViewImplementation.sizeThatFits(self, size: size) ?? .zero
+  }
+}
+```

Sources/QuickLayout/docs/docs/how-to-use/quick-layout-macro-state-updates.mdx

@@ -0,0 +1,66 @@
+---
+id: macro-layout-integration-state-updates
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# State Updates
+
+When the state of a view changes, call `setNeedsLayout` to trigger a layout update. This applies whether you're using the `@QuickLayout` macro or manual integration.
+
+With the `@QuickLayout` macro, calling `setNeedsLayout` will:
+- Update the view hierarchy based on the current state
+- Animate any views that are added or removed
+- Re-layout all subviews
+
+The example below demonstrates a stateful view that lazily creates a `label` when the user presses the `increaseButton` for the first time, and updates the layout accordingly.
+
+```swift
+@QuickLayout
+final class CounterView: UIView {
+
+  private var count = 0
+
+  private lazy var label {
+    // This view will only be created when the count is set to 1 for the first time.
+    UILabel()
+  }
+
+  private lazy var increaseButton = {
+    let button = UIButton(type: .system)
+    button.setTitle("Increase", for: .normal)
+    button.addTarget(self, action: #selector(addCount), for: .touchUpInside)
+    return button
+  }()
+
+  private lazy var resetButton = {
+    let button = UIButton(type: .system)
+    button.setTitle("Reset", for: .normal)
+    button.addTarget(self, action: #selector(resetCount), for: .touchUpInside)
+    return button
+  }()
+
+  var body: Layout {
+    VStack(spacing: 8) {
+      if count > 0 {
+        label
+      }
+      HStack(spacing: 8) {
+        increaseButton
+        resetButton
+      }
+    }
+  }
+
+  @objc private func addCount() {
+    count += 1
+    label.text = "Count: \(count)"
+    setNeedsLayout() // <-- This is the key line.
+  }
+
+  @objc private func resetCount() {
+    count = 0
+    setNeedsLayout() // <-- This is the key line.
+  }
+}
+```