Update custom configuration documentation (#874)

tinder-cfuller · web-flow · commit 5390b1446a3d · 2025-01-30T11:04:12.000-08:00
* Update custom configuration documentation

* Fix RxSwift documentation

* Add “and setup”

* Add line breaks in perceptible preview store

* Update perception documentation

* Fix relative link

* Use GitHub styles alerts in markdown

* Improve header

* Turn optional guidance into tip
diff --git a/Customization/Configuration.md b/Customization/Configuration.md
@@ -1,10 +1,12 @@
 # Nodes Configuration
 
-While Nodes works out-of-the-box with [UIKit](https://developer.apple.com/documentation/uikit) and [SwiftUI](https://developer.apple.com/xcode/swiftui) (for iOS), the following custom configuration is required to use other UI frameworks, such as [AppKit](https://developer.apple.com/documentation/appkit).
+Nodes is easily customized using a YAML configuration file. The [sample](#sample-config-file) below demonstrates the available options.
+
+While Nodes is configured by default for iOS with [UIKit](https://developer.apple.com/documentation/uikit) and [SwiftUI](https://developer.apple.com/xcode/swiftui), UI frameworks for [AppKit](https://developer.apple.com/documentation/appkit) or other platforms may be enabled. 
 
 ## Configure the Xcode Templates Generator
 
-Specify a path to a custom config file by providing the `--config` option when executing `nodes-xcode-templates-gen`.
+Specify a path to a custom config file by providing the `--config` option when executing the `nodes-xcode-templates-gen` command.
 
 <details>
 
@@ -18,7 +20,7 @@ If utilizing the [quick start project setup](https://github.com/Tinder/Nodes#qui
 swift run --skip-build -- nodes-xcode-templates-gen --id "Custom" --config "nodes.yml"
 ```
 
-> TIP: The provided `id` value is used to uniquely identify different sets of templates within the new file dialog in Xcode.
+> The provided `id` value is used to uniquely identify different sets of templates within the new file dialog in Xcode.
 
 The script that creates the presets in the quick start project should use the same config file:
 
@@ -28,16 +30,17 @@ swift run --skip-build -- nodes-code-gen --preset "$PRESET" --author "$AUTHOR" -
 
 </details>
 
-### Sample Config File
+## Sample Config File
 
-All values shown in the samples below are the defaults.
+All values shown in the sample are the defaults.
 
-> TIP: It is only necessary to include config options that are different from the defaults.
+> [!TIP]
+> It is only necessary to include config options that are different from the defaults.
 
 ```yaml
 uiFrameworks:
   - framework: UIKit
-  - framework: SwiftUI
+  - framework: UIKit (SwiftUI)
 baseImports: []
 baseTestImports:
   - Nimble
@@ -83,36 +86,28 @@ isTestTemplatesGenerationEnabled: true
 isPeripheryCommentEnabled: false
 ```
 
-To control which UI Frameworks are made available within the new file dialog in Xcode, include AppKit, UIKit, or SwiftUI as shown below; or a fully custom UI framework may be configured for unique use cases. More than one UI framework can be included in the configuration. And by default, without providing any UI framework configuration, UIKit and SwiftUI (for iOS) are automatically configured.
+## UI Frameworks
 
-> TIP: For use in an iOS app that allows both UIKit and SwiftUI, both may be enabled simultaneously if desired.
+The UI framework presets available to enable in the config file are `AppKit`, `AppKit (SwiftUI)`, `UIKit` and `UIKit (SwiftUI)`. A fully custom UI framework may be configured for unique use cases.
 
-#### AppKit
+More than one UI framework may be included in the configuration. Without specifying any UI frameworks, `UIKit` and `UIKit (SwiftUI)` are enabled by default.
 
 ```yaml
   - framework: AppKit
 ```
 
-#### UIKit
+```yaml
+  - framework: AppKit (SwiftUI)
+```
 
 ```yaml
   - framework: UIKit
 ```
 
-#### SwiftUI
-
-> IMPORTANT: SwiftUI is only supported in iOS apps currently (SwiftUI support for macOS apps may be added in the future).
-
 ```yaml
-  - framework: SwiftUI
+  - framework: UIKit (SwiftUI)
 ```
 
-#### Custom
-
-> IMPORTANT: A non-empty string must be provided for `name`, `import` and `viewControllerType`.
-
-> TIP: The `viewControllerSuperParameters` and `viewControllerMethods` keys may be omitted.
-
 ```yaml
   - framework:
       custom:
@@ -122,3 +117,9 @@ To control which UI Frameworks are made available within the new file dialog in
         viewControllerSuperParameters: ""
         viewControllerMethods: ""
 ```
+
+> [!IMPORTANT]
+> A non-empty string must be provided for `name`, `import` and `viewControllerType`.
+
+> [!TIP]
+> The `viewControllerSuperParameters` and `viewControllerMethods` keys may be omitted.
diff --git a/Customization/Perception.md b/Customization/Perception.md
@@ -1,4 +1,10 @@
-A store compatible with [Perception](https://github.com/pointfreeco/swift-perception).
+# Using Perception with Nodes
+
+While Nodes is compatible with the [Observation](https://developer.apple.com/documentation/observation) framework for newer operating system versions or can be [configured](Configuration.md) to use [`ObservableObject`](https://developer.apple.com/documentation/Combine/ObservableObject) for backward compatibility, other observation libraries such [Perception](https://github.com/pointfreeco/swift-perception) require custom setup.
+
+## Add Supporting Types
+
+Add the following types to the application:
 
 ```swift
 //
@@ -149,7 +155,9 @@ private class PerceptibleViewStateStoreBase<
 @Perceptible
 @preconcurrency
 @MainActor
-public final class PerceptiblePreviewStore<ViewState: Equatable>: PerceptibleViewStateStore {
+public final class PerceptiblePreviewStore<
+    ViewState: Equatable
+>: PerceptibleViewStateStore {
 
     public var viewState: ViewState
 
diff --git a/Customization/RxSwift.md b/Customization/RxSwift.md
@@ -1,10 +1,10 @@
 # Using RxSwift with Nodes
 
-While Nodes works out-of-the-box with [Combine](https://developer.apple.com/documentation/combine), the following custom configuration and setup is required to use other reactive frameworks, such [RxSwift](https://github.com/ReactiveX/RxSwift).
+While Nodes is configured by default for [Combine](https://developer.apple.com/documentation/combine), other reactive frameworks such [RxSwift](https://github.com/ReactiveX/RxSwift) require custom configuration and setup.
 
 ## Configure the Xcode Templates Generator
 
-Specify a path to a custom config file by providing the `--config` option when executing `nodes-xcode-templates-gen`.
+Specify a path to a custom config file by providing the `--config` option when executing the `nodes-xcode-templates-gen` command.
 
 <details>
 
@@ -18,7 +18,7 @@ If utilizing the [quick start project setup](https://github.com/Tinder/Nodes#qui
 swift run --skip-build -- nodes-xcode-templates-gen --id "RxSwift" --config "nodes.yml"
 ```
 
-> TIP: The provided `id` value is used to uniquely identify different sets of templates within the new file dialog in Xcode.
+> The provided `id` value is used to uniquely identify different sets of templates within the new file dialog in Xcode.
 
 The script that creates the presets in the quick start project should use the same config file:
 
@@ -28,13 +28,13 @@ swift run --skip-build -- nodes-code-gen --preset "$PRESET" --author "$AUTHOR" -
 
 </details>
 
-### Sample Config File
+## Sample Config File
 
 ```yaml
 uiFrameworks:
   - framework:
       custom:
-        name: UIKit
+        name: UIKit (RxSwift)
         import: UIKit
         viewControllerType: UIViewController
         viewControllerSuperParameters: "nibName: nil, bundle: nil"
@@ -60,7 +60,6 @@ uiFrameworks:
               LeakDetector.detect(disposeBag)
               disposeBag = DisposeBag()
           }
-  - framework: SwiftUI
 reactiveImports:
   - RxSwift
 viewControllerSubscriptionsProperty: |-
@@ -72,7 +71,7 @@ viewStateOperators: |-
   .observe(on: MainScheduler.instance)
 viewStatePropertyComment: The view state observable
 viewStatePropertyName: stateObservable
-viewStateTransform: context.$state.map { viewStateFactory($0) }
+viewStateTransform: store.viewStatePublisher.asObservable()
 publisherType: Observable
 publisherFailureType: ""
 contextGenericTypes: []
@@ -138,6 +137,27 @@ extension StateObserver {
     }
 }
 
+extension Publisher {
+
+    public func asObservable() -> Observable<Output> {
+        Observable.create { observer in
+            let cancellable: AnyCancellable = sink { completion in
+                switch completion {
+                case .finished:
+                    observer.onCompleted()
+                case let .failure(error):
+                    observer.onError(error)
+                }
+            } receiveValue: { value in
+                observer.onNext(value)
+            }
+            return Disposables.create {
+                cancellable.cancel()
+            }
+        }
+    }
+}
+
 extension Observable: Publisher {
 
     public typealias Output = Element
diff --git a/README.md b/README.md
@@ -56,11 +56,12 @@ Each node is comprised of a few pre-defined types working in conjunction to powe
 
 Nodes' Xcode templates are required to ensure correct use of the Nodes framework and to guarantee that every created node is properly defined.
 
-Installation of the templates is performed by the Xcode templates generator (the `nodes-xcode-templates-gen` executable in the Swift package). Without customizing the generator, Xcode templates for UIKit and SwiftUI (for iOS) are installed by default. The generator supports [optional customization](#optional-customization) if needed.
+Installation of the templates is performed by the Xcode templates generator (the `nodes-xcode-templates-gen` executable in the Swift package). Without customizing the generator, Xcode templates for iOS with [UIKit](https://developer.apple.com/documentation/uikit) and [SwiftUI](https://developer.apple.com/xcode/swiftui) are installed by default. The generator supports [optional customization](#optional-customization) if needed.
 
 #### Xcode Templates Installation
 
-> TIP: After completing the [Quick Start](#quick-start) setup (below), Nodes' Xcode templates will be ***installed automatically***, so these instructions to manually install the Xcode templates ***may be skipped*** and are included here simply as a reference.
+> [!TIP]
+> After completing the [Quick Start](#quick-start) setup (below), Nodes' Xcode templates will be ***installed automatically***, so these instructions to manually install the Xcode templates ***may be skipped*** and are included here simply as a reference.
 
 <details>
 
@@ -92,7 +93,8 @@ The Xcode templates will be installed to the following location to be made avail
 
 Documentation is available online at: [https://Tinder.github.io/Nodes](https://Tinder.github.io/Nodes)
 
-> TIP: After completing the [Quick Start](#quick-start) setup (below), documentation is viewable in Xcode by selecting `Build Documentation` from the `Product` menu.
+> [!TIP]
+> After completing the [Quick Start](#quick-start) setup (below), documentation is viewable in Xcode by selecting `Build Documentation` from the `Product` menu.
 
 ## Quick Start
 
@@ -139,7 +141,8 @@ mint run genesis generate <path>/genesis.yml --options "author:$(git config user
 
 When prompted, enter the latest Nodes version, a name for the new iOS Xcode project and an organization identifier (which is the bundle ID prefix such as `com.tinder`).
 
-**OPTIONAL:** The cloned Nodes repository is no longer needed at this point and may be removed if there is no plan to create additional projects.
+> [!TIP]
+> The cloned Nodes repository is no longer needed at this point and may be removed if there is no plan to create additional projects.
 
 ### Generate Xcode Project
 
@@ -178,11 +181,15 @@ brew reinstall --build-from-source mockolo
 
 ### UI Frameworks
 
-While Nodes works out-of-the-box with [UIKit](https://developer.apple.com/documentation/uikit) and [SwiftUI](https://developer.apple.com/xcode/swiftui) (for iOS), custom [configuration is required](Customization/Configuration.md) to use other UI frameworks, such as [AppKit](https://developer.apple.com/documentation/appkit).
+While Nodes is configured by default for iOS with [UIKit](https://developer.apple.com/documentation/uikit) and [SwiftUI](https://developer.apple.com/xcode/swiftui), UI frameworks for [AppKit](https://developer.apple.com/documentation/appkit) or other platforms may be enabled with [custom configuration](Customization/Configuration.md). 
+
+### Observation Frameworks
+
+While Nodes is compatible with the [Observation](https://developer.apple.com/documentation/observation) framework for newer operating system versions or can be [configured](Customization/Configuration.md) to use [`ObservableObject`](https://developer.apple.com/documentation/Combine/ObservableObject) for backward compatibility, other observation libraries such [Perception](https://github.com/pointfreeco/swift-perception) require [custom setup](Customization/Perception.md).
 
 ### Reactive Frameworks
 
-While Nodes works out-of-the-box with [Combine](https://developer.apple.com/documentation/combine), custom [configuration and setup is required](Customization/RxSwift.md) to use other reactive frameworks, such [RxSwift](https://github.com/ReactiveX/RxSwift).
+While Nodes is configured by default for [Combine](https://developer.apple.com/documentation/combine), other reactive frameworks such [RxSwift](https://github.com/ReactiveX/RxSwift) require [custom configuration and setup](Customization/RxSwift.md).
 
 ## Extras 
 
