DSFSparkline

DSFSparkline provides a wide variety of specialized sparkline types for different data visualizations:

• Line: Simple line charts. Supports centering around zero, interpolation, and custom markers via markerDrawingBlock.
• Bar: Simple bar charts. Can be centered around zero.
• Stackline: Similar to bar charts but without separating individual columns; can be centered around zero.
• Stripes: Maps values to a gradient (e.g., 'warming stripes' climate graphs). Supports integral pixel boundaries.
• Dot: Dot-based sparklines (similar to Activity Viewer CPU history). Supports inverted modes.
• Win/Loss/Tie: Represents positive as 'win', negative as 'loss', and zero as 'tie'.
• Tablet: Uses filled circles for positive values and unfilled circles for negative values.
• Pie: Basic pie chart sparkline.
• DataBar: Supports 'percentage' and 'total' types.
• PercentBar: A horizontal bar for a single value (0...1) with an optional text label.
• WiperGauge: A gauge for a single value (0...1) with flat, gradient, or bucketed color mapping.
• Activity Grid: GitHub-style grid with configurable cell counts, spacing, and fill schemes.
• Circular Progress: Circular graphs with configurable track width, background, and padding (supports layering for 'health ring' effects).
• Circular Gauge: Circular gauges with configurable track/line width, fill/stroke schemes, shadows, and animatable changes.
• Dot: Dot-based sparklines (similar to Activity Viewer CPU history). Supports inverted modes.

A sparkline is composed of one or more Overlays. Overlays represent the individual visual components of a sparkline (e.g., a line graph, a bar graph, or grid lines).

Key behaviors:

• Composition: You can add multiple overlays to a single DSFSparklineSurface. You can even overlay different graph types on the same surface.
• Z-Order: The order in which you call addOverlay(_:) determines the drawing order. Overlays added later will appear on top of those added earlier.
• Data Synchronization: Overlays can share the same dataSource. If the data changes (e.g., via a push), all overlays using that source will automatically update.
• Components: Some overlays are not graphs themselves but are "components" used to augment a graph, such as ZeroLine, RangeHighlight, or GridLines. These typically use the same dataSource to ensure they align correctly with the graph data.

Every prebuilt sparkline view has a SwiftUI companion view accessible via the .SwiftUI property (e.g., DSFSparklineLineGraphView.SwiftUI). You can pass a DSFSparkline.DataSource and various styling parameters like graphColor, lineWidth, or zeroLineDefinition directly into the view's initializer.

struct SparklineView: View {

   let leftDataSource: DSFSparkline.DataSource
   let rightDataSource: DSFSparkline.DataSource
   
   let BigCyanZeroLine = DSFSparkline.ZeroLineDefinition(
      color: .cyan,
      lineWidth: 3,
      lineDashStyle: [4,1,2,1]
   )
   
   var body: some View {
      HStack {
         DSFSparklineLineGraphView.SwiftUI(
            dataSource: leftDataSource,
            graphColor: DSFColor.red,
            interpolated: true)
         DSFSparklineBarGraphView.SwiftUI(
            dataSource: rightDataSource,
            graphColor: DSFColor.blue,
            lineWidth: 2,
            showZeroLine: true,
            zeroLineDefinition: BigCyanZeroLine)
      }
   }
}

DSFSparkline provides several 'prebuilt' views designed for quick integration. These views have a limited scope compared to custom implementations but are easier to set up. To use them in UIKit, instantiate the view, configure its properties (like graphColor or showZeroLine), and assign a DSFSparklineDataSource to its dataSource property. The view automatically updates whenever data is pushed to or set on the data source.

// Create the view
let sparklineView = DSFSparklineLineGraphView(…)
sparklineView.graphColor = UIColor.blue
sparklineView.showZeroLine = true

// Create the datasource and assign to the view
let sparklineDataSource = DSFSparklineDataSource(windowSize: 30, range: -1.0 ... 1.0)
sparklineView.dataSource = sparklineDataSource

// Add a single new data element to the sparkline
sparklineDataSource.push(value: 0.7)                          // view automatically updates with new data

// Add a set of data to the sparkline
sparklineDataSource.push(values: [0.3, -0.2, 1.0])            // view automatically updates with new data

// Completely replace the sparkline data with a new set of data
sparklineDataSource.set(values: [0.2, -0.2, 0.0, 0.9, 0.8])   // view automatically resets to new data

Use DSFSparklineSurface.SwiftUI to render sparklines in SwiftUI. You compose the final view by passing an array of DSFSparklineOverlay objects. Common overlays include:

• DSFSparklineOverlay.Line: The primary data line.
• DSFSparklineOverlay.ZeroLine: A line representing a specific value (e.g., 0 or a midpoint).
• DSFSparklineOverlay.RangeHighlight: A colored area highlighting a specific range of values.

Overlays are layered in the order they appear in the array.

fileprivate let SwiftUIDemoDataSource: DSFSparkline.DataSource = {
   let d = DSFSparkline.DataSource(windowSize: 20, range: 0 ... 1, zeroLineValue: 0.5)
     d.push(values: [0.72, 0.84, 0.15, 0.16, 0.30, 0.58, 0.87, 0.44, 0.02, 0.27, 0.48, 0.16, 0.15, 0.14, 0.81, 0.53, 0.67, 0.52, 0.07, 0.50])
     return d
  }()

struct SuperCoolLineSpark: View {
   var zeroOverlay: DSFSparklineOverlay = {
      let zeroLine = DSFSparklineOverlay.ZeroLine()
      zeroLine.dataSource = SwiftUIDemoDataSource
      zeroLine.dashStyle = []
      return zeroLine
   }()

   var rangeOverlay: DSFSparklineOverlay = {
      let highlight = DSFSparklineOverlay.RangeHighlight()
      highlight.dataSource = SwiftUIDemoDataSource
      highlight.highlightRange = 0.0 ..< 0.2
      highlight.fill = DSFSparkline.Fill.Color(DSFColor.gray.withAlphaComponent(0.4).cgColor)
      return highlight
   }()

   var lineOverlay: DSFSparklineOverlay = {
      let lineOverlay = DSFSparklineOverlay.Line()
      lineOverlay.dataSource = SwiftUIDemoDataSource
      lineOverlay.primaryStrokeColor = DSFColor.systemBlue.cgColor
      lineOverlay.primaryFill = DSFSparkline.Fill.Color(DSFColor.systemBlue.withAlphaComponent(0.3).cgColor)
      lineOverlay.secondaryStrokeColor = DSFColor.systemYellow.cgColor
      lineOverlay.secondaryFill = DSFSparkline.Fill.Color(DSFColor.systemYellow.withAlphaComponent(0.3).cgColor)
      lineOverlay.strokeWidth = 1
      lineOverlay.markerSize = 4
      lineOverlay.centeredAtZeroLine = true
      return lineOverlay
   }()

   var body: some View {
      DSFSparklineSurface.SwiftUI([
         rangeOverlay,
         zeroOverlay,
         lineOverlay,
      ])
      .frame(width: 150, height: 40)
   }
}