Merge pull request #38 from inDriver/feature_docs

doc: Book of UDF

Author: alexey1312

Package.swift

@@ -1,4 +1,4 @@
-// swift-tools-version:5.2
+// swift-tools-version:5.5
 // The swift-tools-version declares the minimum version of Swift required to build this package.
 
 import PackageDescription

UDF/Documentation.docc/Action.md

@@ -0,0 +1,232 @@
+# Action
+
+Events that describe what happened in your application and trigger state updates.
+
+## Overview
+
+`Action` is a marker protocol that represents events or intentions in your application. Actions are the only way to update the state in a UDF application. They describe what happened (not how to update the state), making your application's behavior predictable and testable.
+
+### Key Principles
+
+- **Descriptive**: Actions describe what happened, not how to handle it
+- **Immutable**: Actions should be immutable data structures
+- **Serializable**: Actions should be easily serializable for debugging
+- **Type-Safe**: Use specific action types for different events
+
+## Example
+
+```swift
+// Simple actions
+struct IncrementCounterAction: Action {}
+struct DecrementCounterAction: Action {}
+
+// Actions with data
+struct LoadUserAction: Action {
+    let userId: String
+}
+
+struct UserLoadedAction: Action {
+    let user: User
+}
+
+struct UserLoadErrorAction: Action {
+    let message: String
+}
+
+// Complex actions
+struct UpdateUserProfileAction: Action {
+    let userId: String
+    let name: String
+    let email: String
+    let avatar: URL?
+}
+```
+
+## Action Categories
+
+### User Actions
+Actions triggered by user interactions:
+
+```swift
+struct ButtonTappedAction: Action {
+    let buttonId: String
+}
+
+struct TextFieldChangedAction: Action {
+    let fieldId: String
+    let text: String
+}
+
+struct SwipeGestureAction: Action {
+    let direction: SwipeDirection
+}
+```
+
+### System Actions
+Actions triggered by system events:
+
+```swift
+struct AppDidBecomeActiveAction: Action {}
+struct AppWillResignActiveAction: Action {}
+struct NetworkStatusChangedAction: Action {
+    let isConnected: Bool
+}
+```
+
+### Async Actions
+Actions that represent asynchronous operations:
+
+```swift
+struct APIRequestStartedAction: Action {
+    let requestId: String
+    let endpoint: String
+}
+
+struct APIRequestCompletedAction: Action {
+    let requestId: String
+    let data: Data
+}
+
+struct APIRequestFailedAction: Action {
+    let requestId: String
+    let error: Error
+}
+```
+
+## Dispatching Actions
+
+Actions are dispatched through the store:
+
+```swift
+// Dispatch simple actions
+store.dispatch(IncrementCounterAction())
+store.dispatch(DecrementCounterAction())
+
+// Dispatch actions with data
+store.dispatch(LoadUserAction(userId: "123"))
+
+// Dispatch from components
+class UserViewController: UIViewController, ViewComponent {
+    let disposer = Disposer()
+    var props: UserProps = UserProps()
+    
+    @IBAction func loadUserButtonTapped() {
+        // Dispatch action through the store
+        store.dispatch(LoadUserAction(userId: "123"))
+    }
+}
+```
+
+## Action Handling in Reducers
+
+Actions are handled in reducers to update state:
+
+```swift
+let userReducer: Reducer<AppState> = { state, action in
+    switch action {
+    case let action as LoadUserAction:
+        state.isLoading = true
+        state.error = nil
+        // Trigger async operation here
+        
+    case let action as UserLoadedAction:
+        state.user = action.user
+        state.isLoading = false
+        
+    case let action as UserLoadErrorAction:
+        state.error = action.message
+        state.isLoading = false
+        
+    default:
+        break
+    }
+}
+```
+
+## Action Observation
+
+You can observe actions for logging, analytics, or side effects:
+
+```swift
+store.onAction { state, action in
+    // Log all actions
+    print("Action: \(type(of: action))")
+    
+    // Track analytics
+    Analytics.track(action: action)
+    
+    // Handle side effects
+    switch action {
+    case is AppDidBecomeActiveAction:
+        // Refresh data when app becomes active
+        store.dispatch(RefreshDataAction())
+    default:
+        break
+    }
+}.dispose(on: disposer)
+```
+
+## Best Practices
+
+### Action Naming
+- Use descriptive names that explain what happened
+- Use past tense for completed actions
+- Use present tense for ongoing actions
+
+```swift
+// Good
+struct UserProfileUpdatedAction: Action {}
+struct DataLoadingStartedAction: Action {}
+
+// Avoid
+struct UpdateUserAction: Action {}
+struct LoadDataAction: Action {}
+```
+
+### Action Structure
+- Keep actions simple and focused
+- Include only necessary data
+- Make actions immutable
+
+```swift
+// Good - focused and immutable
+struct UserNameChangedAction: Action {
+    let newName: String
+}
+
+// Avoid - too complex
+struct UserAction: Action {
+    var name: String
+    var email: String
+    var avatar: URL?
+    var isEditing: Bool
+}
+```
+
+### Action Organization
+- Group related actions together
+- Use namespaces for large applications
+- Consider using enums for related actions
+
+```swift
+// Using enums for related actions
+enum UserAction {
+    case load(userId: String)
+    case loaded(user: User)
+    case loadFailed(error: String)
+    case update(profile: UserProfile)
+    case updateCompleted(user: User)
+    case updateFailed(error: String)
+}
+```
+
+## Summary
+
+Actions are the foundation of the unidirectional data flow pattern:
+
+- **Describe events**: Actions describe what happened in your app
+- **Trigger updates**: Actions are the only way to update state
+- **Enable testing**: Actions make behavior predictable and testable
+- **Support debugging**: Actions provide a clear audit trail
+
+Design your actions to be descriptive, immutable, and focused on specific events in your application.

UDF/Documentation.docc/Book of UDF.md

@@ -0,0 +1,36 @@
+# Book of UDF
+
+@Metadata {
+    @CallToAction (
+                   purpose: link,
+                   url: https://github.com/inDriver/UDF
+                   )
+    @PageImage(
+               purpose: icon,
+               source: "https://github.com/inDriver/UDF/blob/master/Docs/img/logo.svg",
+               alt: "A technology icon representing UDF framework"
+               )
+}
+
+
+
+
+## Overview
+
+Unidirectional Data Flow (UDF) is an architectural approach that focuses on how data is stored and transferred within an application. The main principle of Unidirectional Data Flow is to pass immutable data in only one direction. This allows for efficient state management in an application and simplifies the testing of its components.
+There are many ways to implement an application based on unidirectional data flow, but this approach reveals its full potential when combined with functional programming. However, mastering and using Unidirectional Data Flow does not require deep academic knowledge of mathematics. To ease the learning process, we will start with an application that does not follow the UDF principle and refactor it step by step. At each stage, we will analyze the current state of the project and gradually move towards the most optimal solution. So, let’s get started!
+
+
+### Topics
+
+- <doc:Getting-started>
+- <doc:Store>
+- <doc:Action>
+- <doc:Reducer>
+- <doc:Props>
+- <doc:Service-Component>
+
+
+## See Also
+
+- ``Taxi App tutorial``

UDF/Documentation.docc/Getting started.md

@@ -0,0 +1,90 @@
+# Getting started
+
+Learn how to set up and use the UDF framework in your iOS application.
+
+## Overview
+
+UDF (Unidirectional Data Flow) is a Swift framework that implements the unidirectional data flow architecture pattern. This pattern ensures that data flows in only one direction through your application, making state management predictable and testable.
+
+The framework consists of several core components:
+- **Store**: The central state container
+- **Action**: Events that describe what happened
+- **Reducer**: Pure functions that update state based on actions
+- **Component**: UI or service components that connect to the store
+- **Connector**: Objects that transform state into props for components
+
+### Key Benefits
+
+- **Predictable State Management**: All state changes flow through a single path
+- **Testability**: Pure functions and isolated components make testing easier
+- **Debugging**: Clear data flow makes it easier to track down issues
+- **Scalability**: Modular architecture supports large applications
+
+## Example
+
+Here's a simple example of how to set up a UDF application:
+
+```swift
+// 1. Define your state
+struct AppState {
+    var counter: Int = 0
+}
+
+// 2. Define actions
+struct IncrementAction: Action {}
+struct DecrementAction: Action {}
+
+// 3. Create a reducer
+let appReducer: Reducer<AppState> = { state, action in
+    switch action {
+    case is IncrementAction:
+        state.counter += 1
+    case is DecrementAction:
+        state.counter -= 1
+    default:
+        break
+    }
+}
+
+// 4. Create the store
+let store = Store(
+    state: AppState(),
+    reducer: appReducer
+)
+
+// 5. Create a component
+class CounterViewController: UIViewController, ViewComponent {
+    let disposer = Disposer()
+    var props: CounterProps = CounterProps(count: 0)
+    
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        
+        // Connect to store
+        connect(to: store) { state in
+            CounterProps(count: state.counter)
+        }
+    }
+    
+    func updateProps() {
+        // Update UI with props.count
+    }
+}
+
+struct CounterProps: Equatable {
+    let count: Int
+}
+```
+
+## Summary
+
+The UDF framework provides a robust foundation for building iOS applications with predictable state management. By following the unidirectional data flow pattern, you can create maintainable, testable, and scalable applications.
+
+The main concepts to understand are:
+- **Store**: Holds your application state and dispatches actions
+- **Action**: Describes what happened in your app
+- **Reducer**: Pure functions that update state based on actions
+- **Component**: UI or service components that react to state changes
+- **Connector**: Transforms state into props for components
+
+Start with a simple example and gradually add complexity as you become more familiar with the patterns.