Merge pull request #14 from colinc86/develop

Develop

Author: colinc86

Package.resolved

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

Package.swift

@@ -2,7 +2,7 @@
 
 A SwiftUI view that renders LaTeX equations.
 
-![Swift Version](https://img.shields.io/badge/Swift-5.7-orange?logo=swift) ![iOS Version](https://img.shields.io/badge/iOS-16-informational) ![macOS Version](https://img.shields.io/badge/macOS-13-informational)
+[![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fcolinc86%2FLaTeXSwiftUI%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/colinc86/LaTeXSwiftUI) [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fcolinc86%2FLaTeXSwiftUI%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/colinc86/LaTeXSwiftUI)
 
 <center><img src="./assets/images/device.png" width="362"></center>
 
@@ -20,7 +20,10 @@ A SwiftUI view that renders LaTeX equations.
       - [Equation Number Mode](#equation-number-mode)
       - [Equation Number Start](#equation-number-start)
       - [Equation Number Offset](#equation-number-offset)
+      - [Format Equation Number](#format-equation-number)
     - [Unencode HTML](#🔗-unencode-html)
+    - [Rendering Style](#🕶️-rendering-style)
+    - [Animated](#🪩-animated)
   - [Caching](#🗄️-caching)
   - [Preloading](#🏃‍♀️-preloading)
 
@@ -33,7 +36,7 @@ The view utilizes the [MathJaxSwift](https://www.github.com/colinc86/MathJaxSwif
 It will
 - render TeX and LaTeX equations (math-mode macros),
 - render the `\text{}` macro within equations,
-- attempt to render block equations as a Tex or LaTeX engine would,
+- attempt to render block equations as a TeX or LaTeX engine would,
 - and number block equations (if desired).
 
 It won't
@@ -44,7 +47,7 @@ It won't
 Add the dependency to your package manifest file.
 
 ```swift
-.package(url: "https://github.com/colinc86/LaTeXSwiftUI", from: "1.1.0")
+.package(url: "https://github.com/colinc86/LaTeXSwiftUI", from: "1.2.0")
 ```
 
 ## ⌨️ Usage
@@ -186,24 +189,26 @@ The default starting number is `1`, but if you need to start at a different valu
 
 To change the left or right offset of the equation number, use the `equationNumberOffset` modifier.
 
-```swift
-// Don't number block equations (default)
-LaTeX("$$a + b = c$$")
-  .equationNumberMode(.none)
+##### Format Equation Number
+
+You can set a closure on the view to do your own custom formatting. The `formatEquationNumber` modifier takes a closure that is passed the equation number and returns a string.
 
-// Add left numbers and a leading offset
-LaTeX("$$d + e = f$$")
-  .equationNumberMode(.left)
+```swift
+LaTeX("$$E = mc^2$$")
+  .equationNumberMode(.right)
   .equationNumberOffset(10)
+  .padding([.bottom])
 
-// Add right numbers, a leading offset, and start at 2
-LaTeX("$$h + i = j$$ $$k + l = m$$")
+LaTeX("$$E = mc^2$$ $$E = mc^2$$")
   .equationNumberMode(.right)
+  .equationNumberOffset(10)
   .equationNumberStart(2)
-  .equationNumberOffset(20)
+  .formatEquationNumber { n in
+    return "~[\(n)]~"
+  }
 ```
 
-> <img src="./assets/images/numbers.png" width="428" height="152">
+> <img src="./assets/images/numbers.png" width="433" height="153">
 
 #### 🔗 Unencode HTML
 
@@ -220,6 +225,30 @@ LaTeX("$x^2&lt;1$")
 
 > <img src="./assets/images/unencoded.png" width="72.5" height="34">
 
+#### 🕶️ Rendering Style
+
+The view has four rendering styles. The `wait` style is the default style, and loads the view synchronously on the main queue. To get better performance and move SVG rendering off of the main queue, use any of the other three styles.
+
+| Style      | Asynchronous | Description                                                              |
+|:-----------|:-------------|:-------------------------------------------------------------------------|
+| `empty`    | Yes          | The view remains empty until its finished rendering.                     |
+| `original` | Yes          | The view displays the input text until its finished rendering.           |
+| `progress` | Yes          | The view displays a progress view until its finished rendering.          |
+| `wait`     | No           | *(default)* The view blocks the main queue until its finished rendering. |
+
+
+#### 🪩 Animated
+
+The `animated` modifier applies to the view when using the asynchronous rendering styles `empty`, `original`, or `progress`.
+
+```swift
+LaTeX(input)
+  .renderingStyle(.original)
+  .animated()
+```
+
+> 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.
+
 ### 🗄️ 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.
@@ -240,8 +269,6 @@ LaTeX.imageCache.removeAll()
 
 SVGs and images are rendered and cached on demand, but there may be situations where you want to preload the data so that there is minimal lag when the view appears.
 
-SVGs and images are rendered as a result of the view's environment, so it is important to call the `preload` method last in the view's modifier chain if you use it.
-
 ```swift
 VStack {
   ForEach(expressions, id: \.self) { expression in
@@ -255,3 +282,5 @@ VStack {
   }
 }
 ```
+
+SVGs and images are rendered as a result of the view's environment, so it is important to call the `preload` method last in the view's modifier chain if you use it.

README.md

@@ -62,6 +62,18 @@ private struct EquationNumberOffsetKey: EnvironmentKey {
   static let defaultValue: CGFloat = 0.0
 }
 
+private struct FormatEquationNumberKey: EnvironmentKey {
+  static let defaultValue: LaTeX.FormatEquationNumber = { "(\($0))" }
+}
+
+private struct RenderingStyleKey: EnvironmentKey {
+  static let defaultValue: LaTeX.RenderingStyle = .wait
+}
+
+private struct AnimatedKey: EnvironmentKey {
+  static let defaultValue: Bool = false
+}
+
 extension EnvironmentValues {
 
   /// The image rendering mode of this environment.
@@ -118,4 +130,22 @@ extension EnvironmentValues {
     set { self[EquationNumberOffsetKey.self] = newValue }
   }
 
+  /// The closure used to format equation number before displaying them.
+  var formatEquationNumber: LaTeX.FormatEquationNumber {
+    get { self[FormatEquationNumberKey.self] }
+    set { self[FormatEquationNumberKey.self] = newValue }
+  }
+  
+  /// The rendering style of this environment.
+  var renderingStyle: LaTeX.RenderingStyle {
+    get { self[RenderingStyleKey.self] }
+    set { self[RenderingStyleKey.self] = newValue }
+  }
+  
+  /// Whether or not rendering should be animated.
+  var animated: Bool {
+    get { self[AnimatedKey.self] }
+    set { self[AnimatedKey.self] = newValue }
+  }
+  
 }

Sources/LaTeXSwiftUI/Extensions/EnvironmentValues+Extensions.swift

@@ -0,0 +1,41 @@
+//
+//  Range+Extensions.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 Foundation
+
+extension Range<String.Index> {
+  
+  /// Evaluates whether or not this range is a subrange of the given range.
+  ///
+  /// - Parameter range: The range this range is a subset of.
+  /// - Returns: Whether or not the receiver is a subset.
+  func isSubrange(of range: Self) -> Bool {
+    guard range.lowerBound != lowerBound || range.upperBound != upperBound else {
+      return false
+    }
+    return range.lowerBound <= lowerBound && upperBound <= range.upperBound
+  }
+  
+}

Sources/LaTeXSwiftUI/Extensions/Range+Extensions.swift

@@ -0,0 +1,53 @@
+//
+//  TeXInputProcessorOptions+Extensions.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 Foundation
+import MathJaxSwift
+
+extension TeXInputProcessorOptions {
+  
+  /// Initializes a set of options with the correct properties set for rendering
+  /// a `LaTeX` view.
+  ///
+  /// - Parameters:
+  ///   - processEscapes: Whether or not escapes should be processed.
+  ///   - errorMode: The view's error mode.
+  convenience init(processEscapes: Bool, errorMode: LaTeX.ErrorMode) {
+    self.init()
+    self.processEscapes = processEscapes
+    
+    var packages = TeXInputProcessorOptions.Packages.all
+    if errorMode != .rendered {
+      if let noErrorsIndex = packages.firstIndex(of: TeXInputProcessorOptions.Packages.noerrors) {
+        packages.remove(at: noErrorsIndex)
+      }
+      if let noUndefinedIndex = packages.firstIndex(of: TeXInputProcessorOptions.Packages.noundefined) {
+        packages.remove(at: noUndefinedIndex)
+      }
+    }
+    loadPackages = packages
+  }
+  
+}

Sources/LaTeXSwiftUI/Extensions/TeXInputProcessorOptions+Extensions.swift

@@ -46,7 +46,7 @@ public extension View {
   ///   nothing.
   ///
   /// - Returns: A preloaded view.
-  @MainActor func preload() -> some View {
+  func preload() -> some View {
     if let latex = self as? LaTeX {
       latex.preload()
     }
@@ -137,4 +137,29 @@ public extension View {
     environment(\.equationNumberOffset, offset)
   }
 
+  /// Sets a block that lets you format the equation number that will be
+  /// displayed for named block equations.
+  ///
+  /// - Parameter perform: The block that will format the equation number.
+  /// - Returns: A view that formats its equation numbers.
+  func formatEquationNumber(_ perform: @escaping LaTeX.FormatEquationNumber) -> some View {
+    environment(\.formatEquationNumber, perform)
+  }
+  
+  /// Sets the view rendering style.
+  ///
+  /// - Parameter style: The rendering style to use.
+  /// - Returns: A view that renders its content.
+  func renderingStyle(_ style: LaTeX.RenderingStyle) -> some View {
+    environment(\.renderingStyle, style)
+  }
+  
+  /// Sets whether or not the view will animate its render state changes.
+  ///
+  /// - Parameter animate: Whether animations are enabled.
+  /// - Returns: A view that animates its rendering.
+  func animated(_ animate: Bool = true) -> some View {
+    environment(\.animated, animate)
+  }
+  
 }