Add documentation

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mariana Piz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,200 @@
+# CardFlipster
+
+CardFlipster is a customizable SwiftUI framework that makes building flashcard-based learning apps both simple and captivating. 
+With smooth card-flipping animations, progress tracking via a built-in progress bar, and the ability to retry incorrect flashcards, 
+it offers a dynamic learning experience. Whether using predefined themes or customizing every detail, CardFlipster empowers developers 
+to create visually stunning and interactive applications.
+
+## Features
+
+- <b>Predefined Themes:</b> Includes ready-to-use Light and Dark themes for quick setup
+- <b>Custom Themes:</b> Offers full flexibility to customize the appearance of flashcards and the statistics screen, including colors, fonts, and texts
+- <b>Flip Animation:</b> Flashcards include a smooth horizontal flip animation when tapped
+- <b>Interactive Flashcards:</b> Features intuitive swipe gestures — swipe right to mark as correct, swipe left to mark as incorrect — along with dedicated "checkmark" and "cross" buttons for marking answers
+- <b>Progress Tracking:</b> Displays a progress bar indicating how many flashcards have been already reviewed and their total number
+- <b>Round Summary:</b> After each round, view statistics on your progress, including the number of flashcards learned and those marked as incorrect
+- <b>Restart with Incorrect Cards:</b> Start a new round with only the flashcards that were marked as incorrect
+
+## Requirements
+
+- iOS 15.0 or later
+- Xcode 15.0 or later
+- Swift 5.5 or later
+
+## Installation
+### Swift Package Manager (SPM)
+1. Open your Xcode project
+2. Go to File -> Add Packages
+3. In the search bar, paste the GitHub repository URL:
+```bash
+https://github.com/mariana0412/CardFlipster.git
+```
+5. Choose the latest version or specify a version range if necessary
+6. Click Add Package to integrate the framework into your project
+
+### Cocoapods
+1. Install CocoaPods (if not already installed)  
+Using RubyGems:
+```bash
+sudo gem install cocoapods
+```
+Or using Homebrew:
+```bash
+brew install cocoapods
+```
+2. Initialize CocoaPods in your project - navigate to your project's root directory in the terminal and run:
+```ruby
+pod init
+```
+3. Open the newly created Podfile in your project directory and add the following line under your target:
+```ruby
+pod 'CardFlipster', '~> 1.0.0'
+```
+4. Install the Pod - save the Podfile and run the following command in the terminal:
+```ruby
+pod install
+```
+5. After installation completes, open the newly created .xcworkspace file in Xcode instead of your .xcodeproj.
+
+## Usage
+
+### 1. Import the Framework
+To get started, import the framework into your Swift file:
+```swift
+import CardFlipster
+```
+
+### 2. Define the flashcards
+Create an array of flashcards using the Flashcard structure:
+```swift
+let flashcards: [Flashcard] = [
+    Flashcard(frontText: "What is the capital of Ukraine?", backText: "Kyiv"),
+    Flashcard(frontText: "What is the capital of France?", backText: "Paris"),
+    Flashcard(frontText: "What is the capital of Italy?", backText: "Rome")
+]
+```
+
+### 3. Create a Flashcard Deck View
+#### a. Use a Predefined Theme (.light or .dark)
+```swift
+FlashcardDeckView(flashcards: flashcards, theme: .dark)
+```
+#### b. Use a Customized Theme
+
+For a fully personalized appearance, define a custom theme by configuring the flashcards and statistics screens separately.
+
+##### i. Customize Flashcards Appearance
+Use FlashcardUIConfig to define how the flashcards should look:
+
+```swift
+let flashcardConfig = FlashcardUIConfig(
+    frontColor: .purple,
+    backColor: .pink,
+    font: .title,
+    frontFontColor: .white,
+    backFontColor: .white,
+    progressBarColor: .pink
+)
+```
+
+##### ii. Customize Statistics Screen Appearance
+Use StatisticsScreenUIConfig to style the statistics screen:
+```swift
+let statisticsConfig = StatisticsScreenUIConfig(
+    backgroundColor: LinearGradient(
+        gradient: Gradient(colors: [.purple, .pink]),
+        startPoint: .top,
+        endPoint: .bottom
+    ),
+    titleFont: .largeTitle,
+    subtitleFont: .headline,
+    textColor: .white,
+    buttonBackgroundColor: .purple,
+    buttonTextColor: .white
+)
+```
+
+##### iii. Combine Configurations to Create a Custom Theme
+Use FlashcardDeckUIConfig to bring together the flashcard and statistics screen customizations:
+```swift
+FlashcardDeckView(
+    flashcards: flashcards,
+    theme: .custom(FlashcardDeckUIConfig(
+        flashcardConfig: flashcardConfig,
+        statisticsConfig: statisticsConfig)
+    )
+)
+```
+
+## Examples
+### Using Predefined Themes
+This example demonstrates how to use a predefined dark theme for the flashcard deck:
+```swift
+import SwiftUI
+import CardFlipster
+
+struct CardFlipsterDarkTheme: View {
+
+    let flashcards: [Flashcard] = [
+        Flashcard(frontText: "What is the capital of Ukraine?", backText: "Kyiv"),
+        Flashcard(frontText: "What is the capital of France?", backText: "Paris"),
+        Flashcard(frontText: "What is the capital of Italy?", backText: "Rome")
+    ]
+
+
+    var body: some View {
+        FlashcardDeckView(flashcards: flashcards, theme: .dark)
+    }
+}
+```
+
+### Using Custom Themes
+This example showcases how to create a custom theme by specifying the appearance for both flashcards and statistics:
+```swift
+import SwiftUI
+import CardFlipster
+
+struct CardFlipsterCustomTheme: View {
+
+    let flashcards: [Flashcard] = [
+        Flashcard(frontText: "What is the capital of Ukraine?", backText: "Kyiv"),
+        Flashcard(frontText: "What is the capital of France?", backText: "Paris"),
+        Flashcard(frontText: "What is the capital of Italy?", backText: "Rome")
+    ]
+
+    let flashcardConfig = FlashcardUIConfig(
+        frontColor: .purple,
+        backColor: .pink,
+        font: .title,
+        frontFontColor: .white,
+        backFontColor: .white,
+        progressBarColor: .pink
+    )
+
+    let statisticsConfig = StatisticsScreenUIConfig(
+        backgroundColor: LinearGradient(
+            gradient: Gradient(colors: [.purple, .pink]),
+            startPoint: .top,
+            endPoint: .bottom
+        ),
+        titleFont: .largeTitle,
+        subtitleFont: .headline,
+        textColor: .white,
+        buttonBackgroundColor: .purple,
+        buttonTextColor: .white
+    )
+
+    var body: some View {
+        FlashcardDeckView(
+            flashcards: flashcards,
+            theme: .custom(FlashcardDeckUIConfig(
+                flashcardConfig: flashcardConfig,
+                statisticsConfig: statisticsConfig)
+            )
+        )
+    }
+}
+```
+
+## License
+CardFlipster is licensed under the [MIT License](https://github.com/mariana0412/CardFlipster/blob/main/LICENSE).

Sources/CardFlipster/Config/FlashcardDeckTheme.swift

@@ -7,9 +7,15 @@
 
 import SwiftUI
 
+/// A theme for `FlashcardDeckView`.
 public enum FlashcardDeckTheme {
+
+    /// A light theme with default light colors.
     case light
+    /// A dark theme with default dark colors.
     case dark
+    /// A custom theme with user-defined configurations.
+        /// - Parameter config: The `FlashcardDeckUIConfig` containing custom configurations.
     case custom(FlashcardDeckUIConfig)
 
     var config: FlashcardDeckUIConfig {

Sources/CardFlipster/Config/FlashcardDeckUIConfig.swift

@@ -7,15 +7,27 @@
 
 import SwiftUI
 
+/// A configuration object for customizing the appearance of the flashcard deck and statistics screen.
 public struct FlashcardDeckUIConfig {
+
+    /// The appearance configuration for the flashcards.
     public let flashcardConfig: FlashcardUIConfig
+
+    /// The appearance configuration for the statistics screen.
     public let statisticsConfig: StatisticsScreenUIConfig
 
+    /**
+     Initializes a new configuration object for the flashcard deck.
+     - Parameters:
+       - flashcardConfig: The appearance configuration for the flashcards.
+       - statisticsConfig: The appearance configuration for the statistics screen.
+     */
     public init(
         flashcardConfig: FlashcardUIConfig,
         statisticsConfig: StatisticsScreenUIConfig
     ) {
         self.flashcardConfig = flashcardConfig
         self.statisticsConfig = statisticsConfig
     }
+
 }

Sources/CardFlipster/Config/FlashcardUIConfig.swift

@@ -7,14 +7,37 @@
 
 import SwiftUI
 
+/// Configuration for customizing the appearance of the flashcard view.
 public struct FlashcardUIConfig {
+
+    /// The background color of the front side of the flashcard.
     public let frontColor: Color
+
+    /// The background color of the back side of the flashcard.
     public let backColor: Color
+
+    /// The font used for the text on both sides of the flashcard.
     public let font: Font
+
+    /// The color of the text on the front side of the flashcard.
     public let frontFontColor: Color
+
+    /// The color of the text on the back side of the flashcard.
     public let backFontColor: Color
+
+    /// The color of the progress bar displayed during the round.
     public let progressBarColor: Color
 
+    /**
+     Initializes a new configuration for a flashcard.
+     - Parameters:
+       - frontColor: The background color of the front side of the flashcard.
+       - backColor: The background color of the back side of the flashcard.
+       - font: The font used for the text on both sides of the flashcard.
+       - frontFontColor: The color of the text on the front side of the flashcard.
+       - backFontColor: The color of the text on the back side of the flashcard.
+       - progressBarColor: The color of the progress bar displayed during the round.
+     */
     public init(
         frontColor: Color,
         backColor: Color,

Sources/CardFlipster/Config/StatisticsScreenUIConfig.swift

@@ -7,18 +7,53 @@
 
 import SwiftUI
 
+/// Configuration for customizing the appearance of the statistics screen.
 public struct StatisticsScreenUIConfig {
+
+    /// The background color of the statistics screen.
     public let backgroundColor: LinearGradient
+
+    /// The font used for the title text.
     public let titleFont: Font
+
+    /// The font used for the subtitle text.
     public let subtitleFont: Font
+
+    /// The color of the text displayed on the statistics screen.
     public let textColor: Color
-    public let buttonBackgroundColor: Color
-    public let buttonTextColor: Color
+
+    /// The background color for the button that allows users to retry with flashcards marked as answered incorrectly.
+    public let continueButtonBackgroundColor: Color
+
+    /// The text color for the button that allows users to retry with flashcards marked as answered incorrectly.
+    public let continueButtonTextColor: Color
+
+    /// The title displayed at the top of the statistics screen.
     public let roundSummaryTitle: String
+
+    /// The label text for correct answers on the statistics screen.
     public let correctText: String
+
+    /// The label text for incorrect answers on the statistics screen.
     public let incorrectText: String
+
+    /// The text displayed on the button that allows users to retry with flashcards marked as answered incorrectly.
     public let continueLearningButtonText: String
 
+    /**
+     Initializes a new configuration for the statistics screen.
+     - Parameters:
+       - backgroundColor: The background color of the statistics screen.
+       - titleFont: The font used for the title text.
+       - subtitleFont: The font used for the subtitle text.
+       - textColor: The color of the text displayed on the statistics screen.
+       - continueButtonBackgroundColor: The background color for the retry button for incorrectly answered flashcards.
+       - continueButtonTextColor: The text color for the retry button for incorrectly answered flashcards.
+       - roundSummaryTitle: The title displayed at the top of the statistics screen. Defaults to "Round Summary".
+       - correctText: The label text for correct answers. Defaults to "Correct".
+       - incorrectText: The label text for incorrect answers. Defaults to "Incorrect".
+       - continueLearningButtonText: The text on the retry button for incorrectly answered flashcards.
+     */
     public init(
         backgroundColor: LinearGradient,
         titleFont: Font,
@@ -35,8 +70,8 @@ public struct StatisticsScreenUIConfig {
         self.titleFont = titleFont
         self.subtitleFont = subtitleFont
         self.textColor = textColor
-        self.buttonBackgroundColor = buttonBackgroundColor
-        self.buttonTextColor = buttonTextColor
+        self.continueButtonBackgroundColor = buttonBackgroundColor
+        self.continueButtonTextColor = buttonTextColor
         self.roundSummaryTitle = roundSummaryTitle
         self.correctText = correctText
         self.incorrectText = incorrectText

Sources/CardFlipster/Model/Flashcard.swift

@@ -5,7 +5,24 @@
 //  Created by Mariana Piz on 16.11.2024.
 //
 
+/// A model representing a single flashcard with a question (front side) and an answer (back side).
 public struct Flashcard {
-    let frontText: String
-    let backText: String
+
+    /// The text displayed on the front of the flashcard (e.g., a question or term).
+    public let frontText: String
+
+    /// The text displayed on the back of the flashcard (e.g., an answer or definition).
+    public let backText: String
+
+    /**
+     Initializes a new flashcard with a question and answer.
+     - Parameters:
+       - frontText: The text displayed on the front of the flashcard.
+       - backText: The text displayed on the back of the flashcard.
+     */
+    public init(frontText: String, backText: String) {
+        self.frontText = frontText
+        self.backText = backText
+    }
+
 }