Merge pull request #19 from colinc86/develop

Styles and better preloading.

Author: colinc86

Package.resolved

@@ -15,7 +15,7 @@ let package = Package(
       targets: ["LaTeXSwiftUI"]),
   ],
   dependencies: [
-     .package(url: "https://github.com/colinc86/MathJaxSwift", from: "3.3.0"),
+     .package(url: "https://github.com/colinc86/MathJaxSwift", from: "3.4.0"),
      .package(url: "https://github.com/exyte/SVGView", from: "1.0.4"),
      .package(url: "https://github.com/Kitura/swift-html-entities", from: "4.0.1")
   ],

Package.swift

@@ -24,6 +24,7 @@ A SwiftUI view that renders LaTeX equations.
     - [Unencode HTML](#🔗-unencode-html)
     - [Rendering Style](#🕶️-rendering-style)
     - [Rendering Animation](#🪩-animated)
+  - [Styles](#🪮-styles)
   - [Caching](#🗄️-caching)
   - [Preloading](#🏃‍♀️-preloading)
 
@@ -47,7 +48,7 @@ It won't
 Add the dependency to your package manifest file.
 
 ```swift
-.package(url: "https://github.com/colinc86/LaTeXSwiftUI", from: "1.2.3")
+.package(url: "https://github.com/colinc86/LaTeXSwiftUI", from: "1.3.0")
 ```
 
 ## ⌨️ Usage
@@ -249,6 +250,44 @@ LaTeX(input)
 
 > In the above example, the input text will be displayed until the SVGs have been rendered at which point the rendered views will animate in to view.
 
+### 🪮 Styles
+
+You can use the provided view styles or create your own.
+
+```swift
+// The default view style.
+LaTeX(input)
+  .latexStyle(.automatic)
+
+// A "standard" style with HTML elements unencoded and block equations numbered.
+LaTeX(input)
+  .latexStyle(.standard)  
+```
+
+To create your own style, conform to the `LaTeXStyle` protocol. Its `makeBody(content:)` method takes a `LaTeX` view and returns a stylized version of the view.
+
+The following would create a style for the first title used at the [top](#latexswiftui) of this README.
+
+```swift
+@available(iOS 16.1, *)
+public struct TitleLaTeXStyle: LaTeXStyle {
+  
+  public func makeBody(content: LaTeX) -> some View {
+    content
+      .fontDesign(.serif)
+      .font(.largeTitle)
+      .foregroundStyle(
+          LinearGradient(
+            colors: [.red, .orange, .yellow, .green, .blue, .indigo, .purple],
+            startPoint: .leading,
+            endPoint: .trailing
+          )
+        )
+  }
+  
+}
+```
+
 ### 🗄️ Caching
 
 `LaTeXSwiftUI` caches its SVG responses from MathJax and the images rendered as a result of the view's environment. If you want to control the cache, then you can access the static `dataCache` and `imageCache` properties.

README.md

@@ -50,6 +50,7 @@ public struct LaTeX: View {
     case blockViews
   }
 
+  /// The view's equation number mode.
   public enum EquationNumberMode {
 
     /// The view should not number named block equations.
@@ -85,6 +86,7 @@ public struct LaTeX: View {
     case onlyEquations
   }
 
+  /// The view's rendering style.
   public enum RenderingStyle {
 
     /// The view remains empty until its finished rendering.
@@ -159,6 +161,9 @@ public struct LaTeX: View {
   /// The view's renderer.
   @StateObject private var renderer: Renderer
 
+  /// The view's preload task, if any.
+  @State private var preloadTask: Task<(), Never>?
+  
   // MARK: Initializers
 
   /// Initializes a view with a LaTeX input string.
@@ -195,6 +200,7 @@ public struct LaTeX: View {
     }
     .animation(renderingAnimation, value: renderer.rendered)
     .environmentObject(renderer)
+    .onDisappear(perform: preloadTask?.cancel)
   }
 
 }
@@ -205,10 +211,19 @@ extension LaTeX {
 
   /// Preloads the view's SVG and image data.
   public func preload() {
-    Task {
-      await renderAsync()
-    }
+    preloadTask?.cancel()
+    preloadTask = Task { await renderAsync() }
+    Task { await preloadTask?.value }
+  }
+  
+  /// Configures the `LaTeX` view with the given style.
+  ///
+  /// - Parameter style: The `LaTeX` view style to use.
+  /// - Returns: A stylized view.
+  public func latexStyle<S>(_ style: S) -> some View where S: LaTeXStyle {
+    style.makeBody(content: self)
   }
+  
 }
 
 // MARK: Private methods
@@ -271,6 +286,9 @@ extension LaTeX {
     }
   }
 
+  /// The view to display while its content is rendering.
+  ///
+  /// - Returns: The view's body.
   @MainActor @ViewBuilder private func loadingView() -> some View {
     switch renderingStyle {
     case .empty:
@@ -285,135 +303,3 @@ extension LaTeX {
   }
 
 }
-
-@available(iOS 16.1, *)
-struct LaTeX_Previews: PreviewProvider {
-  static var previews: some View {
-    VStack {
-      LaTeX("Hello, $\\LaTeX$!")
-        .font(.largeTitle)
-        .foregroundStyle(
-          LinearGradient(
-            colors: [.red, .orange, .yellow, .green, .blue, .indigo, .purple],
-            startPoint: .leading,
-            endPoint: .trailing
-          )
-        )
-      
-      LaTeX("Hello, $\\LaTeX$!")
-        .font(.title)
-        .foregroundColor(.red)
-      
-      LaTeX("Hello, $\\LaTeX$!")
-        .font(.title2)
-        .foregroundColor(.orange)
-      
-      LaTeX("Hello, $\\LaTeX$!")
-        .font(.title3)
-        .foregroundColor(.yellow)
-      
-      LaTeX("Hello, $\\LaTeX$!")
-        .font(.body)
-        .foregroundColor(.green)
-      
-      LaTeX("Hello, $\\LaTeX$!")
-        .font(.caption)
-        .foregroundColor(.indigo)
-      
-      LaTeX("Hello, $\\LaTeX$!")
-        .font(.caption2)
-        .foregroundColor(.purple)
-    }
-    .fontDesign(.serif)
-    .previewLayout(.sizeThatFits)
-    .previewDisplayName("Hello, LaTeX!")
-    
-    VStack {
-      LaTeX("Hello, $\\color{blue}\\LaTeX$")
-        .imageRenderingMode(.original)
-        
-      LaTeX("Hello, $\\LaTeX$")
-        .imageRenderingMode(.template)
-    }
-    .previewDisplayName("Image Rendering Mode")
-    
-    VStack {
-      LaTeX("$\\asdf$")
-        .errorMode(.error)
-      
-      LaTeX("$\\asdf$")
-        .errorMode(.original)
-      
-      LaTeX("$\\asdf$")
-        .errorMode(.rendered)
-    }
-    .previewDisplayName("Error Mode")
-    
-    VStack {
-      LaTeX("$x&lt;0$")
-        .errorMode(.error)
-      
-      LaTeX("$x&lt;0$")
-        .unencoded()
-        .errorMode(.error)
-    }
-    .previewDisplayName("Unencoded")
-    
-    VStack {
-      LaTeX("$a^2 + b^2 = c^2$")
-        .parsingMode(.onlyEquations)
-      
-      LaTeX("a^2 + b^2 = c^2")
-        .parsingMode(.all)
-    }
-    .previewDisplayName("Parsing Mode")
-    
-    VStack {
-      LaTeX("Equation 1: $$x = 3$$")
-        .blockMode(.blockViews)
-      
-      LaTeX("Equation 1: $$x = 3$$")
-        .blockMode(.blockText)
-      
-      LaTeX("Equation 1: $$x = 3$$")
-        .blockMode(.alwaysInline)
-    }
-    .previewDisplayName("Block Mode")
-    
-    VStack {
-      LaTeX("$$E = mc^2$$")
-        .equationNumberMode(.right)
-        .equationNumberOffset(10)
-        .padding([.bottom])
-      
-      LaTeX("\\begin{equation} E = mc^2 \\end{equation} \\begin{equation} E = mc^2 \\end{equation}")
-        .equationNumberMode(.right)
-        .equationNumberOffset(10)
-        .equationNumberStart(2)
-    }
-    .fontDesign(.serif)
-    .previewLayout(.sizeThatFits)
-    .previewDisplayName("Equation Numbers")
-    .formatEquationNumber { n in
-      return "~[\(n)]~"
-    }
-    
-    VStack {
-      LaTeX("Hello, $\\LaTeX$!")
-        .renderingStyle(.wait)
-      
-      LaTeX("Hello, $\\LaTeX$!")
-        .renderingStyle(.empty)
-      
-      LaTeX("Hello, $\\LaTeX$!")
-        .renderingStyle(.original)
-        .renderingAnimation(.default)
-      
-      LaTeX("Hello, $\\LaTeX$!")
-        .renderingStyle(.progress)
-        .renderingAnimation(.easeIn)
-    }
-    .previewDisplayName("Rendering Style and Animated")
-  }
-  
-}

Sources/LaTeXSwiftUI/LaTeX.swift

@@ -0,0 +1,70 @@
+//
+//  LaTeX_Previews+Color.swift
+//  LaTeXSwiftUI
+//
+//  Copyright (c) 2023 Colin Campbell
+//
+//  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.
+//
+
+import SwiftUI
+
+struct LaTeX_Previews_Color: PreviewProvider {
+  
+  static var previews: some View {
+    VStack {
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.largeTitle)
+        .foregroundStyle(
+          LinearGradient(
+            colors: [.red, .orange, .yellow, .green, .blue, .indigo, .purple],
+            startPoint: .leading,
+            endPoint: .trailing
+          )
+        )
+      
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.title)
+        .foregroundColor(.red)
+      
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.title2)
+        .foregroundColor(.orange)
+      
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.title3)
+        .foregroundColor(.yellow)
+      
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.body)
+        .foregroundColor(.green)
+      
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.caption)
+        .foregroundColor(.indigo)
+      
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.caption2)
+        .foregroundColor(.purple)
+    }
+    .previewLayout(.sizeThatFits)
+    .previewDisplayName("Hello, LaTeX!")
+  }
+  
+}