### UIKit Sparkline Graph Setup and Data Push

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Demonstrates how to initialize a DSFSparklineLineGraphView, configure its appearance, set up a data source, and add data points. Use this for basic UIKit integration.

```swift
let sparklineView = DSFSparklineLineGraphView(…)
sparklineView.graphColor = UIColor.blue
sparklineView.showZeroLine = true

let sparklineDataSource = DSFSparklineDataSource(windowSize: 30, range: -1.0 ... 1.0)
sparklineView.dataSource = sparklineDataSource

sparklineDataSource.push(value: 0.7)

sparklineDataSource.push(values: [0.3, -0.2, 1.0])

sparklineDataSource.set(values: [0.2, -0.2, 0.0, 0.9, 0.8])
```

--------------------------------

### SwiftUI Sparkline Graph Integration

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Shows how to integrate DSFSparkline graphs within a SwiftUI view hierarchy. This example includes both line and bar graph types with custom zero-line definitions.

```swift
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)
      }
   }
}
```

--------------------------------

### Custom Marker Drawing for Line Sparkline

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Use this block to define custom drawing logic for markers on a line sparkline. It allows specifying which markers to draw and how, for example, highlighting only the minimum and maximum data points.

```swift
self.myLineView.markerDrawingBlock = {
   context, markerFrames in
   // Get the frames containing the minimum and maximum values
   if let minMarker = markerFrames.min(by: { (a, b) -> Bool in a.value < b.value }),
      let maxMarker = markerFrames.min(by: { (a, b) -> Bool in a.value > b.value }) {

      // Draw minimum marker

      context.setFillColor(DSFColor.systemRed.cgColor)
      context.fill(minMarker.rect)
      context.setLineWidth(0.5)
      context.setStrokeColor(DSFColor.white.cgColor)
      context.stroke(minMarker.rect)

      // Draw maximum marker

      context.setFillColor(DSFColor.systemGreen.cgColor)
      context.fill(maxMarker.rect)

      context.setLineWidth(0.5)
      context.setStrokeColor(DSFColor.white.cgColor)
      context.stroke(maxMarker.rect)
   }
}
```

--------------------------------

### Create and Configure StackLine Overlay

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

This code demonstrates creating a StackLine overlay. It requires a bitmap surface, a datasource, and primary fill color. The image generation parameters (width, height, scale) can be adjusted.

```swift
let bitmap = DSFSparklineSurface.Bitmap()    // Create a bitmap surface
let stack = DSFSparklineOverlay.Stackline()  // Create a stackline overlay
stack.dataSource = source                    // Assign the datasource to the overlay
stack.strokeWidth = 1
stack.primaryFill = primaryFill
bitmap.addOverlay(stack)                     // And add the overlay to the surface.

// Generate an image with retina scale
let image = bitmap.image(width: 50, height: 25, scale: 2)!
```

--------------------------------

### Create and Configure Tablet Overlay

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

This code demonstrates creating a Tablet overlay. It requires a bitmap surface and a datasource. The image generation parameters, including width, height, and scale, can be adjusted as needed.

```swift
let bitmap = DSFSparklineSurface.Bitmap()    // Create a bitmap surface
let stack = DSFSparklineOverlay.Tablet()     // Create a tablet overlay
stack.dataSource = winloss                   // Assign a datasource to the overlay
bitmap.addOverlay(stack)                     // And add the overlay to the surface.

// Generate an image with retina scale
let image = bitmap.image(width: 90, height: 16, scale: 2)!
```

--------------------------------

### Create and Configure WinLossTie Overlay

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Use this snippet to create a win-loss-tie overlay. It requires a bitmap surface and a specific datasource. The image generation parameters for width, height, and scale can be modified.

```swift
let bitmap = DSFSparklineSurface.Bitmap()          // Create a bitmap surface
let winLossTie = DSFSparklineOverlay.WinLossTie()  // Create a win-loss-tie overlay
winLossTie.dataSource = winloss                    // Assign the datasource
bitmap.addOverlay(winLossTie)                      // And add the overlay to the surface.

// Generate an image with retina scale
let image = bitmap.image(width: 75, height: 12, scale: 2)!
```

--------------------------------

### Create and Manage Static Data Source

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Initialize a static data source with an immutable array of values. Supports optional value clamping and provides methods to calculate fractional values based on the source's range. Infinite values are treated as gaps.

```swift
let staticSource = DSFSparkline.StaticDataSource([10, 55, 20, 15])
print(staticSource.total)     
print(staticSource.minValue)  
print(staticSource.maxValue)  

let bounded = DSFSparkline.StaticDataSource([25, 50, 75, 110], lowerBound: 0, upperBound: 100)

let frac = bounded.fractionalValue(for: 50)   
let fracAt = bounded.fractionalValue(at: 1)   

let gridSource = DSFSparkline.StaticDataSource([1, 2, .infinity, 4, 5])
```

--------------------------------

### Create and Manage Dynamic Data Source

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Initialize a dynamic data source with a specified window size, range, and zero line value. Supports pushing single or multiple values, replacing all values, and dynamically adjusting the window size and range. Values are automatically normalized to a 0-1 scale for drawing.

```swift
let source = DSFSparkline.DataSource(windowSize: 20, range: -1.0 ... 1.0, zeroLineValue: 0)

source.push(value: 0.75)

source.push(values: [0.3, -0.2, 0.5, -0.8, 1.0])

source.set(values: [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0])

print(source.data)        
print(source.normalized)  

source.windowSize = 30

source.range = -2.0 ... 2.0

source.resetRange()

source.zeroLineValue = 0.5

source.setRange(lowerBound: -1, upperBound: 1, zeroLinePoint: 0)

source.reset()

print("filled: \(source.windowSize - source.emptyValueCount)/\(source.windowSize)")
```

--------------------------------

### Create and Configure Dot Overlay

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

This code shows how to create a dot graph overlay. It requires a bitmap surface and a datasource. Note that the datasource is assigned using a direct assignment, and the image dimensions are adjustable.

```swift
let bitmap = DSFSparklineSurface.Bitmap()  // Create a bitmap surface
let dot = DSFSparklineOverlay.Dot()        // Create a dot graph overlay
dot = biggersource                         // Assign the datasource to the overlay
bitmap.addOverlay(dot)                     // And add the overlay to the surface.

// Generate an image with retina scale
let image = bitmap.image(width: 50, height: 32, scale: 2)!
```

--------------------------------

### Initialize Static Data Source for Sparkline

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Create a data source with a fixed set of values. This is used for sparklines that do not require historical data context.

```swift
/// Swift
let dataSource = DSFSparkline.StaticDataSource([1, 2, 3])
```

```objc
/// Objective-C
DSFSparklineStaticDataSource* dataSource = [[DSFSparklineStaticDataSource alloc] init: @[@(1), @(2), @(3)]];
```

--------------------------------

### Create and Configure Bar Overlay

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Use this snippet to create a bar overlay for a dynamic graph. It requires a bitmap surface, a datasource, and a primary fill color. The output image dimensions and scale are configurable.

```swift
let bitmap = DSFSparklineSurface.Bitmap()   // Create a bitmap surface
let bar = DSFSparklineOverlay.Bar()         // Create a bar overlay
bar.dataSource = source                     // Assign the datasource to the overlay
bar.primaryFill = primaryFill
bitmap.addOverlay(bar)                      // And add the overlay to the surface.

// Generate an image with retina scale
let image = bitmap.image(width: 50, height: 25, scale: 2)!
```

--------------------------------

### Create Static Activity Grid Sparkline

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Initialize `DSFSparklineOverlay.ActivityGrid` and assign a `StaticDataSource` to it. Configure `verticalCellCount` and add the overlay to the bitmap surface.

```swift
let bitmap = DSFSparklineSurface.Bitmap()
let activityGrid = DSFSparklineOverlay.ActivityGrid()
activityGrid.dataSource = DSFSparkline.StaticDataSource(values: [...])
activityGrid.verticalCellCount = 1

bitmap.addOverlay(activityGrid)

// Generate an image of the wiper gauge with retina scale
let image = bitmap.image(width: 200, height: 14, scale: 2)
```

--------------------------------

### Create and Configure Line Overlay

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Use this snippet to create a line overlay for a dynamic graph. Ensure a datasource and primary fill color are available. The generated image can be customized by width, height, and scale.

```swift
let bitmap = DSFSparklineSurface.Bitmap()   // Create a bitmap surface
let line = DSFSparklineOverlay.Line()      // Create a line overlay
line.strokeWidth = 1
line.primaryFill = primaryFill
line.dataSource = source                   // Assign the datasource to the overlay
bitmap.addOverlay(line)                    // And add the overlay to the surface.

// Generate an image with retina scale
let image = bitmap.image(width: 50, height: 25, scale: 2)!
```

--------------------------------

### Configure Pie Chart Overlay

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Renders a pie chart from static data. Segments are colored using a provided palette. Supports optional stroke lines and animated reveals.

```swift
let pieSource = DSFSparkline.StaticDataSource([30, 50, 20])

let pie = DSFSparklineOverlay.Pie()
pie.dataSource = pieSource
pie.palette = DSFSparkline.Palette([
    DSFColor.systemBlue,
    DSFColor.systemOrange,
    DSFColor.systemGreen,
])
pie.strokeColor = CGColor.white
pie.lineWidth = 1.0
pie.animationStyle = DSFSparkline.AnimationStyle(duration: 0.5, function: .easeInEaseOut)

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(pie)
let image = bitmap.image(width: 40, height: 40, scale: 2)
```

--------------------------------

### Create Smooth and Quantized Gradients with DSFSparkline.GradientBucket

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Define gradients using color posts at fractional locations. Set bucketCount to quantize the gradient into discrete color steps for heatmap-style fills. Colors can be sampled at specific positions.

```swift
// Smooth gradient: blue → white → red
let smooth = DSFSparkline.GradientBucket(posts: [
    DSFSparkline.GradientBucket.Post(color: DSFColor.systemBlue.cgColor, location: 0),
    DSFSparkline.GradientBucket.Post(color: DSFColor.white.cgColor, location: 0.5),
    DSFSparkline.GradientBucket.Post(color: DSFColor.systemRed.cgColor, location: 1.0),
])

// Quantized into 5 discrete color steps
let bucketed = DSFSparkline.GradientBucket(posts: [
    DSFSparkline.GradientBucket.Post(color: DSFColor.systemGreen.cgColor, location: 0),
    DSFSparkline.GradientBucket.Post(color: DSFColor.systemYellow.cgColor, location: 0.5),
    DSFSparkline.GradientBucket.Post(color: DSFColor.systemRed.cgColor, location: 1.0),
], bucketCount: 5)

// Sample a color at a fractional position
let midColor = smooth.color(at: 0.5)  // ≈ white

// Create from a plain array of CGColor evenly spaced
let rainbow = DSFSparkline.GradientBucket(
    colors: [DSFColor.red.cgColor, DSFColor.orange.cgColor, DSFColor.yellow.cgColor,
             DSFColor.green.cgColor, DSFColor.blue.cgColor, DSFColor.purple.cgColor]
)
```

--------------------------------

### Create Bitmap Image with Stripes Overlay

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Create a bitmap surface, add a stripes overlay with data, and generate a retina-scaled image. Use this for dynamic chart generation.

```swift
let bitmap = DSFSparklineSurface.Bitmap()    // Create a bitmap surface
let stack = DSFSparklineOverlay.Stripes()    // Create a stripes overlay
stack.dataSource = .init(values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
bitmap.addOverlay(stack)                     // And add the overlay to the surface.

// Generate an image with retina scale
let image = bitmap.image(width: 90, height: 16, scale: 2)

// Do something with 'image'
```

--------------------------------

### Create Static Pie Chart Sparkline

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Use `DSFSparklineOverlay.Pie` with a `StaticDataSource` to create a pie chart. Configure line width and stroke color before adding it to the bitmap surface.

```swift
let bitmap = DSFSparklineSurface.Bitmap()
let pie = DSFSparklineOverlay.Pie()
pie.dataSource = DSFSparkline.StaticDataSource([10, 55, 20])
pie.lineWidth = 0.5
pie.strokeColor = CGColor.black

bitmap.addOverlay(pie)

// Generate an image with retina scale
let image = bitmap.image(width: 18, height: 18, scale: 2)!
```

--------------------------------

### Set DataSource Window Size (Swift)

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Configure the maximum number of values to be drawn. Values exceeding this limit are discarded. If the window size is reduced, data is truncated; if increased, it's padded with zeros.

```swift
/// Swift
dataSource.windowSize = 30
assert(dataSource.windowSize == 30)
```

--------------------------------

### GitHub-Style Activity Grid Overlay

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Renders a grid of colored cells from a StaticDataSource, mapping values to a ValueBasedFill color scheme. Supports GitHub-style (column-major) and defrag-style (row-major) layouts. Use .infinity for gap cells.

```swift
// 52 weeks × 7 days = 364 cells, some gaps marked with .infinity
var activityValues: [CGFloat] = (0 ..< 364).map { _ in CGFloat.random(in: 0 ... 1) }
activityValues[0] = .infinity  // skip cell

let actSource = DSFSparkline.StaticDataSource(activityValues)

let grid = DSFSparklineOverlay.ActivityGrid()
grid.dataSource = actSource
grid.verticalCellCount = 7
grid.layoutStyle = .github
grid.cellDimension = 10
grid.cellSpacing = 2
grid.cellCornerRadius = 2
grid.cellFillScheme = DSFSparkline.ValueBasedFill(
    DSFSparkline.GradientBucket(posts: [
        DSFSparkline.GradientBucket.Post(color: DSFColor.systemGray.withAlphaComponent(0.2).cgColor, location: 0),
        DSFSparkline.GradientBucket.Post(color: DSFColor.systemGreen.cgColor, location: 1),
    ])
)

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(grid)
let image = bitmap.image(size: grid.intrinsicSize, scale: 2)

// Hit-test (useful in a live view)
// let idx = grid.indexAtPoint(touchPoint)  // -1 if no cell or gap
// let frame = grid.cellFrame(for: idx)
```

--------------------------------

### Set DataSource Window Size (Objective-C)

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Configure the maximum number of values to be drawn. Values exceeding this limit are discarded. If the window size is reduced, data is truncated; if increased, it's padded with zeros.

```objective-c
/// Objective-C
[dataSource setWindowSize:30];
assert([dataSource windowSize] == 30);
```

--------------------------------

### Configure Color Gradient Stripes Overlay

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Visualizes data values as colored stripes based on a gradient. Set `integral` to `true` for crisp pixel-aligned rendering. Configure bar spacing and the gradient itself.

```swift
let source = DSFSparkline.DataSource(windowSize: 20, range: 0 ... 10)
source.push(values: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1])

let gradient = DSFSparkline.GradientBucket(posts: [
    DSFSparkline.GradientBucket.Post(color: DSFColor.systemBlue.cgColor, location: 0),
    DSFSparkline.GradientBucket.Post(color: DSFColor.white.cgColor, location: 0.5),
    DSFSparkline.GradientBucket.Post(color: DSFColor.systemRed.cgColor, location: 1.0),
])

let stripes = DSFSparklineOverlay.Stripes()
stripes.dataSource = source
stripes.gradient = gradient
stripes.integral = true
stripes.barSpacing = 1

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(stripes)
let image = bitmap.image(width: 100, height: 30, scale: 2)
```

--------------------------------

### DSFSparklineOverlay.Line Configuration

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Configure a line graph overlay with options for interpolation, fills, markers, and custom drawing. Use centeredAtZeroLine to split fills above and below the zero line. A markerDrawingBlock allows for custom rendering of individual data points.

```swift
let source = DSFSparkline.DataSource(windowSize: 15, range: -1 ... 1, zeroLineValue: 0)
source.push(values: [0.2, -0.4, 0.7, -0.9, 0.5, -0.1, 0.8, -0.3, 0.6, -0.5])

let line = DSFSparklineOverlay.Line()
line.dataSource = source
line.strokeWidth = 1.5
line.interpolated = true       // smooth Hermite curve
line.markerSize = 5
line.centeredAtZeroLine = true // splits fills above/below zero line

line.primaryStrokeColor = DSFColor.systemGreen.cgColor
line.primaryFill = DSFSparkline.Fill.Color(DSFColor.systemGreen.withAlphaComponent(0.3).cgColor)
line.secondaryStrokeColor = DSFColor.systemRed.cgColor
line.secondaryFill = DSFSparkline.Fill.Color(DSFColor.systemRed.withAlphaComponent(0.3).cgColor)

// Custom marker drawing: highlight only min and max
line.markerDrawingBlock = { context, markers in
    if let maxM = markers.max(by: { $0.value < $1.value }),
       let minM = markers.min(by: { $0.value < $1.value }) {
        context.setFillColor(DSFColor.systemGreen.cgColor)
        context.fill(maxM.rect)
        context.setFillColor(DSFColor.systemRed.cgColor)
        context.fill(minM.rect)
    }
}

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(line)
let image = bitmap.image(width: 120, height: 40, scale: 2)
```

--------------------------------

### Create SwiftUI Line Graph Sparkline

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Creates a SwiftUI view displaying a line graph sparkline with customizable overlays for zero-line and range highlighting. The DataSource should be configured with window size, range, and zero-line value.

```swift
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 {
   // The overlay representing the zero-line for the data source
   var zeroOverlay: DSFSparklineOverlay = {
      let zeroLine = DSFSparklineOverlay.ZeroLine()
      zeroLine.dataSource = SwiftUIDemoDataSource
      zeroLine.dashStyle = []
      return zeroLine
   }()

   // The overlay to draw a highlight between range 0 ..< 0.2
   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
   }()

   // The actual line graph
   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,    // range highlight overlay
         zeroOverlay,     // zero-line overlay
         lineOverlay,     // line graph overlay
      ])
      .frame(width: 150, height: 40)
   }
}
```

--------------------------------

### Create Bitmap Sparkline with Line Overlay

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Generates a bitmap image with a simple line graph overlay. Requires a DataSource and a Line overlay. Can also generate an NSAttributedString representation.

```swift
// A datasource with a simple set of data
let source = DSFSparkline.DataSource(values: [4, 1, 8, 7, 5, 9, 3], range: 0 ... 10)

let bitmap = DSFSparklineSurface.Bitmap()   // Create a bitmap surface
let stack = DSFSparklineOverlay.Line()      // Create a line overlay
stack.dataSource = source                   // Assign the datasource to the overlay
bitmap.addOverlay(stack)                    // And add the overlay to the surface.

// Generate an image with retina scale
let image = bitmap.image(width: 50, height: 25, scale: 2)

// Embed a sparkline in an NSAttributedString
let attributedString = bitmap.attributedString(size: CGSize(width: 40, height: 18), scale: 2)
```

--------------------------------

### Configure Bar Graph Overlay

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Use for visualizing positive and negative values with configurable bar spacing, stroke, and fill colors. Centered mode is enabled by default.

```swift
let source = DSFSparkline.DataSource(windowSize: 12, range: -1 ... 1, zeroLineValue: 0)
source.push(values: [0.5, -0.3, 0.8, -0.6, 0.2, -0.9, 0.7, -0.1, 0.4, -0.5, 0.6, -0.2])

let bar = DSFSparklineOverlay.Bar()
bar.dataSource = source
bar.strokeWidth = 1
bar.barSpacing = 2
bar.centeredAtZeroLine = true

bar.primaryFill = DSFSparkline.Fill.Color(DSFColor.systemBlue.cgColor)
bar.primaryStrokeColor = DSFColor.systemBlue.cgColor
bar.secondaryFill = DSFSparkline.Fill.Color(DSFColor.systemOrange.cgColor)
bar.secondaryStrokeColor = DSFColor.systemOrange.cgColor

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(bar)
let image = bitmap.image(width: 100, height: 30, scale: 2)
```

--------------------------------

### Create Static Percent Bar Sparkline

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Instantiate `DSFSparklineOverlay.PercentBar` with a specific value to represent a percentage. Add it to the bitmap surface to generate an image.

```swift
let bitmap = DSFSparklineSurface.Bitmap()
let percentBar = DSFSparklineOverlay.PercentBar(value: 0.3)

bitmap.addOverlay(percentBar)

// Generate an image with retina scale
let image = bitmap.image(width: 50, height: 18, scale: 2)!
```

--------------------------------

### Configure Win/Loss/Tie Overlay

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Use for sports records or A/B comparisons, representing positive, negative, and zero values with distinct bars. Customize stroke and fill colors for each state.

```swift
let source = DSFSparkline.DataSource(windowSize: 10, range: -1 ... 1)
source.push(values: [1, -1, 1, 0, 1, -1, -1, 1, 0, 1])

let wlt = DSFSparklineOverlay.WinLossTie()
wlt.dataSource = source
wlt.lineWidth = 1
wlt.barSpacing = 2
wlt.winStroke = DSFColor.systemGreen.cgColor
wlt.winFill = DSFSparkline.Fill.Color(DSFColor.systemGreen.withAlphaComponent(0.4).cgColor)
wlt.lossStroke = DSFColor.systemRed.cgColor
wlt.lossFill = DSFSparkline.Fill.Color(DSFColor.systemRed.withAlphaComponent(0.4).cgColor)
wlt.tieStroke = DSFColor.systemGray.cgColor
wlt.tieFill = DSFSparkline.Fill.Color(DSFColor.systemGray.withAlphaComponent(0.4).cgColor)

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(wlt)
let image = bitmap.image(width: 80, height: 20, scale: 2)
```

--------------------------------

### Circular Progress Ring Overlay

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Renders a full-circle progress ring. Supports values over 1.0 for multiple laps, configurable track width, padding for stacking, and custom fill styles. Use padding to stack multiple rings.

```swift
let ring = DSFSparklineOverlay.CircularProgress()
ring.value = 1.35    // 135% = one full lap plus 35%
ring.trackWidth = 12
ring.padding = 2
ring.fillStyle = DSFSparkline.Fill.Color(
    DSFSparkline.GradientBucket(colors: [
        DSFColor.systemGreen.cgColor,
        DSFColor.systemTeal.cgColor,
    ])
)
ring.trackColor = DSFColor.systemGreen.withAlphaComponent(0.15).cgColor

// Stack three rings (health-ring style) by using padding offset
let ring2 = DSFSparklineOverlay.CircularProgress()
ring2.value = 0.80
ring2.trackWidth = 12
ring2.padding = 16
ring2.fillStyle = DSFSparkline.Fill.Color(DSFColor.systemOrange.cgColor)

let ring3 = DSFSparklineOverlay.CircularProgress()
ring3.value = 0.55
ring3.trackWidth = 12
ring3.padding = 30
ring3.fillStyle = DSFSparkline.Fill.Color(DSFColor.systemRed.cgColor)

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(ring3)
bitmap.addOverlay(ring2)
bitmap.addOverlay(ring)
let image = bitmap.image(width: 80, height: 80, scale: 2)
```

--------------------------------

### Configure Dot Matrix Overlay

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Ideal for activity-monitor style visualizations. Configure the number of vertical dots, and colors for active and inactive states. The `upsideDown` property inverts the fill direction.

```swift
let source = DSFSparkline.DataSource(windowSize: 20, range: 0 ... 1)
source.push(values: [0.9, 0.4, 0.6, 0.1, 0.8, 0.3, 0.7, 0.5, 0.2, 0.95])

let dot = DSFSparklineOverlay.Dot()
dot.dataSource = source
dot.verticalDotCount = 8
dot.onColor = DSFColor.systemGreen.cgColor
dot.offColor = DSFColor.systemGreen.withAlphaComponent(0.15).cgColor
dot.upsideDown = false

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(dot)
let image = bitmap.image(width: 80, height: 24, scale: 2)
```

--------------------------------

### Create Static Data Bar Sparkline

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Utilize `DSFSparklineOverlay.DataBar` with `StaticDataSource` for creating a data bar graph. Set line width and stroke color for the bars.

```swift
let bitmap = DSFSparklineSurface.Bitmap()
let stack = DSFSparklineOverlay.DataBar()
stack.dataSource = DSFSparkline.StaticDataSource([10, 20, 30])
stack.lineWidth = 0.5
stack.strokeColor = CGColor.black

bitmap.addOverlay(stack)

// Generate an image with retina scale
let image = bitmap.image(width: 50, height: 18, scale: 2)!
```

--------------------------------

### Create Range Highlights with DSFSparklineOverlay.RangeHighlight

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Use RangeHighlight to shade horizontal bands between specified y-values. Multiple overlays can be stacked. Ensure a DataSource is assigned to the overlay.

```swift
let source = DSFSparkline.DataSource(windowSize: 20, range: 0 ... 100)
source.push(values: [10, 30, 55, 80, 95, 70, 45, 20, 35, 60, 85, 50])

// Highlight the "danger" band 80 … 100
let danger = DSFSparklineOverlay.RangeHighlight(
    lowerBound: 80, upperBound: 100,
    fill: DSFSparkline.Fill.Color(DSFColor.systemRed.withAlphaComponent(0.15).cgColor)
)
danger.dataSource = source

// Highlight the "caution" band 60 … 80
let caution = DSFSparklineOverlay.RangeHighlight(
    lowerBound: 60, upperBound: 80,
    fill: DSFSparkline.Fill.Color(DSFColor.systemYellow.withAlphaComponent(0.15).cgColor)
)
caution.dataSource = source

let line = DSFSparklineOverlay.Line()
line.dataSource = source
line.primaryStrokeColor = DSFColor.systemBlue.cgColor

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(danger)
bitmap.addOverlay(caution)
bitmap.addOverlay(line)
let image = bitmap.image(width: 120, height: 40, scale: 2)
```

--------------------------------

### Set All Values in Sparkline Data Source

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Replace all existing values in the data source with a new array. This also updates the window size to match the provided array's size. Overlays update automatically.

```swift
/// Swift
datasource.set(values: [
   0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0,
   0.0, -0.1, -0.2, -0.3, -0.4, -0.5, -0.6, -0.7, -0.8, -0.9, -1.0
])
```

```objective-c
/// Objective-C
[datasource setWithValues:
   @[@(0.0), @(0.1), @(0.2), @(0.3), @(0.4), @(0.5), @(0.6), @(0.7), @(0.8), @(0.9), @(1),
     @(0.0), @(-0.1), @(-0.2), @(-0.3), @(-0.4), @(-0.5), @(-0.6), @(-0.7), @(-0.8), @(-0.9), @(-1)]];
```

--------------------------------

### DSFSparkline.StaticDataSource

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

A data source that holds an immutable array of CGFloat values, suitable for overlays representing a complete snapshot like pie charts or activity grids. Supports value clamping and provides methods to calculate fractional values.

```APIDOC
## DSFSparkline.StaticDataSource

### Description
Holds an immutable array of `CGFloat` values used by overlays that represent a complete snapshot (pie chart, data bar, activity grid). Infinite values (`.infinity`) act as skip/gap cells in activity grids. An optional `valueBounds` range clamps values at construction time.

### Initialization
```swift
// Basic static source (auto min/max from values)
let staticSource = DSFSparkline.StaticDataSource([10, 55, 20, 15])
print(staticSource.total)     // 100
print(staticSource.minValue)  // 10
print(staticSource.maxValue)  // 55

// Bounded source: values clamped to 0 … 100
let bounded = DSFSparkline.StaticDataSource([25, 50, 75, 110], lowerBound: 0, upperBound: 100)
// 110 is clamped to 100
```

### Value Calculation
```swift
// Fractional value for a given raw value within the source's range
let frac = bounded.fractionalValue(for: 50)   // 0.5
let fracAt = bounded.fractionalValue(at: 1)   // 0.5 (index 1 → value 50)
```

### Special Values
```swift
// Infinite values are gap/skip cells (used in ActivityGrid)
let gridSource = DSFSparkline.StaticDataSource([1, 2, .infinity, 4, 5])
// The cell at index 2 will be blank in an ActivityGrid overlay
```
```

--------------------------------

### Use Indexed Color Palettes with DSFSparkline.Palette

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Employ a cyclic list of colors for segment-indexed graphs like pie charts. Access colors by offset with automatic wrap-around. Two shared default palettes are available, or create a custom one.

```swift
// Use the built-in shared palette (red, orange, yellow, green, blue, purple, pink)
let defaultPalette = DSFSparkline.Palette.shared

// Custom palette
let customPalette = DSFSparkline.Palette([
    DSFColor(red: 0.22, green: 0.58, blue: 0.95, alpha: 1),
    DSFColor(red: 0.95, green: 0.42, blue: 0.22, alpha: 1),
    DSFColor(red: 0.22, green: 0.85, blue: 0.42, alpha: 1),
])

// Access color for a given data-point index (wraps automatically)
let c0 = customPalette.colorAtOffset(0)   // first color
let c3 = customPalette.colorAtOffset(3)   // wraps to first color again

let pie = DSFSparklineOverlay.Pie()
pie.dataSource = DSFSparkline.StaticDataSource([25, 40, 35])
pie.palette = customPalette
```

--------------------------------

### Create Static Wiper Gauge Sparkline

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Use `DSFSparklineOverlay.WiperGauge` and set its `value` property to create a wiper gauge visualization. The image can be generated with a specified size and scale.

```swift
let bitmap = DSFSparklineSurface.Bitmap()
let wiperGauge = DSFSparklineOverlay.WiperGauge()
wiperGauge.value = 0.75

bitmap.addOverlay(wiperGauge)

// Generate an image of the wiper gauge with retina scale
let image = bitmap.image(width: 50, height: 25, scale: 2)
```

--------------------------------

### Push New Values to Sparkline Data Source

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Add new data points to the sparkline's data source. Values older than the window size are automatically discarded. Overlays update automatically.

```swift
/// Swift
dataSource.push(value: 4.5)
dataSource.push(values: [6, 7, 8])
```

```objective-c
/// Objective-C
[dataSource pushWithValue:@(4.5)];
```

--------------------------------

### Zero Line Reference Overlay

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Draws a horizontal dashed or solid reference line at the data source's zeroLineValue. Useful for marking baselines alongside graph overlays. Configure dash style with an array of dash and gap lengths.

```swift
let source = DSFSparkline.DataSource(windowSize: 15, range: -1 ... 1, zeroLineValue: 0)
source.push(values: [0.2, -0.5, 0.8, -0.3, 0.6, -0.9, 0.4, -0.1])

let zeroLine = DSFSparklineOverlay.ZeroLine()
zeroLine.dataSource = source
zeroLine.strokeColor = DSFColor.systemGray.cgColor
zeroLine.strokeWidth = 1.0
zeroLine.dashStyle = [4, 2]    // dashes 4pt, gaps 2pt; use [] for solid line

let lineGraph = DSFSparklineOverlay.Line()
lineGraph.dataSource = source
lineGraph.primaryStrokeColor = DSFColor.systemBlue.cgColor

let bitmap = DSFSparklineSurface.Bitmap()
bitmap.addOverlay(zeroLine)   // drawn first (behind graph)
bitmap.addOverlay(lineGraph)
let image = bitmap.image(width: 100, height: 30, scale: 2)
```

--------------------------------

### AppKit/UIKit Line Graph Usage

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Instantiates and configures a DSFSparklineLineGraphView for AppKit or UIKit. Pushing new values to the data source automatically redraws the view.

```swift
// MARK: AppKit/UIKit usage
let lineView = DSFSparklineLineGraphView(frame: CGRect(x: 0, y: 0, width: 150, height: 40))
lineView.graphColor = DSFColor.systemBlue
lineView.showZeroLine = true
lineView.zeroLineColor = DSFColor.systemGray
lineView.zeroLineDashStyle = [4, 2]
lineView.lineWidth = 1.5
lineView.interpolated = true
lineView.lineShading = true
lineView.centeredAtZeroLine = true
lineView.lowerGraphColor = DSFColor.systemOrange  // color for values < zero line

let source = DSFSparkline.DataSource(windowSize: 30, range: -1 ... 1, zeroLineValue: 0)
lineView.dataSource = source

// Pushing new values automatically redraws the view
source.push(value: 0.4)
source.push(values: [-0.2, 0.6, -0.8, 0.1])
```

--------------------------------

### Create Static Circular Gauge Sparkline

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Create a `DSFSparklineOverlay.CircularGauge` by setting its `value` property. Add the gauge to the bitmap surface to generate an image.

```swift
let bitmap = DSFSparklineSurface.Bitmap()
let gauge = DSFSparklineOverlay.CircularGauge()
gauge.value = 0.66

bitmap.addOverlay(gauge)

// Generate an image of the wiper gauge with retina scale
let image = bitmap.image(width: 40, height: 40, scale: 2)
```

--------------------------------

### Set Zero-Line Value for Sparkline Data Source

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Configure the zero-line value for a sparkline's data source. This value determines the center point for centered graph types.

```swift
/// Swift
dataSource.zeroLineValue = 0.2
```

```objc
/// Objective-C
[dataSource setZeroLineValue:0.2];
```

--------------------------------

### SwiftUI Bar Graph Usage with Timer

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Implements a SwiftUI view for a bar graph using DSFSparklineBarGraphView.SwiftUI. A timer is used to push random values to the data source, causing the graph to update in real-time.

```swift
// MARK: SwiftUI usage
struct BarSparkle: View {
    @StateObject private var src: DSFSparkline.DataSource = {
        let d = DSFSparkline.DataSource(windowSize: 20, range: 0 ... 1)
        d.push(values: [0.3, 0.6, 0.9, 0.4, 0.7, 0.2, 0.5, 0.8])
        return d
    }()

    var body: some View {
        DSFSparklineBarGraphView.SwiftUI(
            dataSource: src,
            graphColor: DSFColor.systemIndigo,
            lineWidth: 1,
            barSpacing: 2,
            showZeroLine: false
        )
        .frame(width: 120, height: 30)
        .onAppear {
            Timer.scheduledTimer(withTimeInterval: 1, repeats: true) { _ in
                src.push(value: CGFloat.random(in: 0 ... 1))
            }
        }
    }
}
```

--------------------------------

### DSFSparkline.DataSource

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

The primary data source for time-series sparklines, maintaining a fixed-size window of CGFloat values. New values can be pushed, and old values are automatically evicted when the window is full. Supports dynamic range and zero-line adjustments.

```APIDOC
## DSFSparkline.DataSource

### Description
The primary data source for time-series sparklines. It maintains a fixed-size window of `CGFloat` values; new values are appended with `push()` and values older than `windowSize` are discarded. An optional `range` clamps the y-axis, and `zeroLineValue` sets the baseline for centered graphs. Any overlay observing the source redraws automatically when data changes.

### Initialization
```swift
// Create a source: window of 20 points, y-range –1 … 1, zero-line at 0
let source = DSFSparkline.DataSource(windowSize: 20, range: -1.0 ... 1.0, zeroLineValue: 0)
```

### Pushing Data
```swift
// Push a single value (oldest is evicted once window is full)
source.push(value: 0.75)

// Push multiple values at once
source.push(values: [0.3, -0.2, 0.5, -0.8, 1.0])

// Replace ALL values and resize the window
source.set(values: [0.0, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0])
```

### Reading Data
```swift
// Read back raw and normalized (0 … 1) values
print(source.data)        // [CGFloat] raw values
print(source.normalized)  // [CGFloat] scaled to 0 … 1
```

### Configuration
```swift
// Change window size dynamically (truncates or pads with zeros)
source.windowSize = 30

// Set a fixed y-range (values are clamped when drawn)
source.range = -2.0 ... 2.0

// Remove range restriction (auto-scales to data extent)
source.resetRange()

// Zero line at 0.5 within a 0 … 1 range
source.zeroLineValue = 0.5

// Objective-C–compatible range setter
source.setRange(lowerBound: -1, upperBound: 1, zeroLinePoint: 0)

// Reset all buckets to the lower bound
source.reset()
```

### State Inspection
```swift
// Inspect window state
print("filled: \(source.windowSize - source.emptyValueCount)/\(source.windowSize)")
```
```

--------------------------------

### Render Sparklines to Bitmap

Source: https://context7.com/dagronf/dsfsparkline/llms.txt

Use DSFSparklineSurface.Bitmap to render sparklines into an image without a live view hierarchy. This is useful for generating thumbnails or embedding in attributed strings. Ensure you have a data source and desired overlays configured before calling image() or cgImage().

```swift
import DSFSparkline

// Build a data source
let source = DSFSparkline.DataSource(values: [4, 1, 8, 7, 5, 9, 3, 6, 2], range: 0 ... 10)

// Create a bitmap surface
let bitmap = DSFSparklineSurface.Bitmap()

// Create and configure a line overlay
let line = DSFSparklineOverlay.Line()
line.dataSource = source
line.strokeWidth = 1.5
line.primaryStrokeColor = DSFColor.systemBlue.cgColor
line.primaryFill = DSFSparkline.Fill.Color(DSFColor.systemBlue.withAlphaComponent(0.3).cgColor)
line.markerSize = 4

// Add overlay to the surface
bitmap.addOverlay(line)

// Generate a retina-scale image (144 dpi)
if let image = bitmap.image(width: 80, height: 30, scale: 2) {
    // use image (NSImage on macOS, UIImage on iOS/tvOS)
}

// Generate a CGImage directly
if let cg = bitmap.cgImage(size: CGSize(width: 80, height: 30), scale: 2) {
    // use cg
}

// Embed in NSAttributedString for use in text views / NSTextField
if let attrStr = bitmap.attributedString(size: CGSize(width: 60, height: 18), scale: 2) {
    myTextView.textStorage?.append(attrStr)
}
```

--------------------------------

### Set DataSource Y-Range (Objective-C)

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Define the upper and lower bounds for displaying values in the sparkline. Values outside this range are capped. If not set, the range automatically adjusts to the min/max values in the source.

```objective-c
/// Objective-C
[dataSource setRangeWithLowerBound:-1.0 upperBound:1.0];
```

--------------------------------

### Set DataSource Y-Range (Swift)

Source: https://github.com/dagronf/dsfsparkline/blob/master/README.md

Define the upper and lower bounds for displaying values in the sparkline. Values outside this range are capped. If not set, the range automatically adjusts to the min/max values in the source.

```swift
/// Swift
dataSource.range = -1.0 ... 1.0
```