@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/swift-charts/references/charts-patterns.md

@@ -1,262 +1,161 @@
-# Swift Charts Patterns Reference
+# Swift Charts Patterns
 
-Extended patterns, accessibility guidance, and theming for Swift Charts on
-iOS 26+. Import `Charts` in every file that uses these APIs.
-
-```swift
-import SwiftUI
-import Charts
-```
-
----
+Companion to the `swift-charts` skill. Any source file touching these types
+imports `Charts` next to `SwiftUI`.
 
 ## Contents
 
-- [Data Modeling](#data-modeling)
-- [Bar Chart Patterns](#bar-chart-patterns)
-- [Line Chart Patterns](#line-chart-patterns)
-- [Pie and Donut Chart Patterns (SectorMark, iOS 17+)](#pie-and-donut-chart-patterns-sectormark-ios-17)
-- [Combined Chart Patterns](#combined-chart-patterns)
-- [Chart Selection with Overlay Annotation](#chart-selection-with-overlay-annotation)
-- [Scrollable Chart with Visible Domain](#scrollable-chart-with-visible-domain)
-- [Function Plotting (LinePlot, iOS 18+)](#function-plotting-lineplot-ios-18)
-- [3D Charts and Surfaces (Chart3D, iOS 26+)](#3d-charts-and-surfaces-chart3d-ios-26)
+- [Modelling the Data](#modelling-the-data)
+- [Bars](#bars)
+- [Lines](#lines)
+- [Pies and Donuts](#pies-and-donuts)
+- [Combining Marks](#combining-marks)
+- [A Tooltip on Selection](#a-tooltip-on-selection)
+- [Scrolling with a Bound Position](#scrolling-with-a-bound-position)
+- [Function Plots (iOS 18)](#function-plots-ios-18)
+- [3D Charts and Surfaces (iOS 26)](#3d-charts-and-surfaces-ios-26)
 - [Accessibility](#accessibility)
-- [Dynamic Type and Color Considerations](#dynamic-type-and-color-considerations)
-- [Performance: Vectorized Plots for Large Datasets](#performance-vectorized-plots-for-large-datasets)
+- [Dynamic Type and Colour](#dynamic-type-and-colour)
+- [Performance: When to Vectorize](#performance-when-to-vectorize)
 - [Dark Mode and Theming](#dark-mode-and-theming)
-- [Heat Map Pattern](#heat-map-pattern)
-- [Stacking Methods](#stacking-methods)
-- [MarkDimension Options](#markdimension-options)
-- [Symbol Configuration](#symbol-configuration)
-- [ChartProxy and Coordinate Conversion](#chartproxy-and-coordinate-conversion)
-- [Quick Reference: Chart View Modifiers](#quick-reference-chart-view-modifiers)
-- [Apple Documentation Links](#apple-documentation-links)
+- [Heat Map](#heat-map)
+- [Stacking](#stacking)
+- [`MarkDimension`](#markdimension)
+- [Symbols](#symbols)
+- [`ChartProxy` and Coordinates](#chartproxy-and-coordinates)
+- [Modifier Quick Reference](#modifier-quick-reference)
+- [Apple Documentation](#apple-documentation)
 
-## Data Modeling
-
-Use `@Observable` for chart data models. Pair with `@State` in views.
+## Modelling the Data
 
 ```swift
+import Charts
+import SwiftUI
+
+struct MonthlyUsage: Identifiable, Sendable {
+    let id = UUID()
+    let month: Date
+    let kilowattHours: Double
+}
+
+@MainActor
 @Observable
-class SalesModel {
-    var monthlySales: [MonthlySale] = []
+final class UsageModel {
+    private(set) var months: [MonthlyUsage] = []
 
     func load() async {
-        monthlySales = await SalesService.fetchMonthlySales()
+        months = await UsageService.shared.lastTwelveMonths()
     }
 }
 
-struct MonthlySale: Identifiable {
-    let id = UUID()
-    let month: Date
-    let revenue: Double
-    let category: String
-}
-```
-
-```swift
-struct SalesDashboard: View {
-    @State private var model = SalesModel()
+struct UsageChart: View {
+    @State private var model = UsageModel()
 
     var body: some View {
-        Chart(model.monthlySales) { item in
-            BarMark(
-                x: .value("Month", item.month, unit: .month),
-                y: .value("Revenue", item.revenue)
-            )
-            .foregroundStyle(by: .value("Category", item.category))
+        Chart(model.months) { entry in
+            BarMark(x: .value("Month", entry.month, unit: .month),
+                    y: .value("kWh", entry.kilowattHours))
         }
         .task { await model.load() }
     }
 }
 ```
 
----
+The view owns the model with `@State` and starts loading from `.task`.
 
-## Bar Chart Patterns
+## Bars
 
-### Simple vertical bars
+Side by side instead of stacked: combine `.position(by:)` with
+`.foregroundStyle(by:)`.
 
 ```swift
-Chart(data) { item in
-    BarMark(
-        x: .value("Department", item.department),
-        y: .value("Revenue", item.revenue)
-    )
+Chart(results) { row in
+    BarMark(x: .value("Quarter", row.quarter), y: .value("Units", row.units))
+        .foregroundStyle(by: .value("Model", row.model))
+        .position(by: .value("Model", row.model))
 }
 ```
 
-### Stacked bars (automatic)
-
-When multiple bars share the same x value, they stack automatically:
+Horizontal bars with only value labels on the category axis:
 
 ```swift
-Chart(data) { item in
-    BarMark(
-        x: .value("Quarter", item.quarter),
-        y: .value("Sales", item.sales)
-    )
-    .foregroundStyle(by: .value("Product", item.product))
-}
-```
-
-### Grouped bars
-
-Use `.position(by:)` to place bars side by side instead of stacking:
-
-```swift
-Chart(data) { item in
-    BarMark(
-        x: .value("Quarter", item.quarter),
-        y: .value("Sales", item.sales)
-    )
-    .foregroundStyle(by: .value("Product", item.product))
-    .position(by: .value("Product", item.product))
-}
-```
-
-### Horizontal bars
-
-Swap the x and y axes:
-
-```swift
-Chart(data) { item in
-    BarMark(
-        x: .value("Sales", item.sales),
-        y: .value("Region", item.region)
-    )
+Chart(languages) { item in
+    BarMark(x: .value("Speakers", item.speakers), y: .value("Language", item.name))
 }
 .chartYAxis {
-    AxisMarks { _ in
-        AxisValueLabel()
-    }
+    AxisMarks { _ in AxisValueLabel() }
 }
 ```
 
-### Normalized stacked bars (100%)
+Shares of 100 percent per bar: `BarMark(x:y:stacking: .normalized)`.
 
-```swift
-Chart(data) { item in
-    BarMark(
-        x: .value("Quarter", item.quarter),
-        y: .value("Sales", item.sales),
-        stacking: .normalized
-    )
-    .foregroundStyle(by: .value("Product", item.product))
-}
-```
-
-### Bar with annotation
+A value on top of each bar:
 
 ```swift
-Chart(data) { item in
-    BarMark(
-        x: .value("Month", item.month),
-        y: .value("Revenue", item.revenue)
-    )
-    .annotation(position: .top, alignment: .center, spacing: 4) {
-        Text(item.revenue, format: .currency(code: "USD").precision(.fractionLength(0)))
+BarMark(x: .value("Store", row.store), y: .value("Sales", row.sales))
+    .annotation(position: .top) {
+        Text(row.sales, format: .currency(code: "EUR").precision(.fractionLength(0)))
             .font(.caption2)
     }
-}
 ```
 
-### Gantt chart (interval bars)
+A Gantt chart colours interval bars by status:
 
 ```swift
 Chart(tasks) { task in
-    BarMark(
-        xStart: .value("Start", task.startDate),
-        xEnd: .value("End", task.endDate),
-        y: .value("Task", task.name)
-    )
-    .foregroundStyle(by: .value("Status", task.status))
+    BarMark(xStart: .value("Start", task.start),
+            xEnd: .value("End", task.end),
+            y: .value("Task", task.title))
+        .foregroundStyle(by: .value("Phase", task.phase.rawValue))
 }
 ```
 
----
-
-## Line Chart Patterns
+## Lines
 
-### Single line with points
+Points on the line: put a `LineMark` and a `PointMark` in the same closure.
 
 ```swift
-Chart(data) { item in
-    LineMark(
-        x: .value("Date", item.date),
-        y: .value("Price", item.price)
-    )
-    PointMark(
-        x: .value("Date", item.date),
-        y: .value("Price", item.price)
-    )
-    .symbolSize(30)
+Chart(temperatures) { sample in
+    LineMark(x: .value("Hour", sample.hour), y: .value("Celsius", sample.value))
+        .foregroundStyle(by: .value("City", sample.city))
+        .symbol(by: .value("City", sample.city))
+    PointMark(x: .value("Hour", sample.hour), y: .value("Celsius", sample.value))
+        .symbolSize(30)
 }
 ```
 
-### Multi-series lines
+Pairing `.foregroundStyle(by:)` with `.symbol(by:)` keeps series apart for
+people who cannot tell the colours apart.
 
-```swift
-Chart(temperatures) { item in
-    LineMark(
-        x: .value("Date", item.date),
-        y: .value("Temp", item.temperature)
-    )
-    .foregroundStyle(by: .value("City", item.city))
-    .symbol(by: .value("City", item.city))
-}
-```
-
-### Line with area fill
+A line over a fading area:
 
 ```swift
-Chart(data) { item in
-    AreaMark(
-        x: .value("Date", item.date),
-        y: .value("Value", item.value)
-    )
-    .foregroundStyle(
-        .linearGradient(
-            colors: [.blue.opacity(0.3), .blue.opacity(0.05)],
-            startPoint: .top,
-            endPoint: .bottom
-        )
-    )
-    LineMark(
-        x: .value("Date", item.date),
-        y: .value("Value", item.value)
-    )
-    .foregroundStyle(.blue)
+Chart(prices) { point in
+    AreaMark(x: .value("Day", point.day), y: .value("Price", point.close))
+        .foregroundStyle(.linearGradient(
+            colors: [.indigo.opacity(0.35), .indigo.opacity(0.02)],
+            startPoint: .top, endPoint: .bottom))
+    LineMark(x: .value("Day", point.day), y: .value("Price", point.close))
+        .foregroundStyle(.indigo)
 }
 ```
 
-### Interpolation methods
+Interpolation methods:
 
-| Method | Use Case |
-|---|---|
-| `.linear` | Default; straight segments between points |
-| `.monotone` | Smooth curve that preserves monotonicity |
-| `.catmullRom` | Smooth general-purpose curve |
-| `.cardinal` | Smooth with adjustable tension |
-| `.stepStart` | Step function starting at data point |
-| `.stepCenter` | Step function centered on data point |
-| `.stepEnd` | Step function ending at data point |
+| Method | Result |
+|--------|--------|
+| `.linear` | Straight segments (the default) |
+| `.monotone` | Smooth without overshooting; keeps monotonic data monotonic |
+| `.catmullRom` | Smooth curve for general data |
+| `.cardinal` | Smooth curve with adjustable tension |
+| `.stepStart`, `.stepCenter`, `.stepEnd` | Steps placed at the start, middle or end of each interval |
 
-```swift
-LineMark(x: .value("X", item.x), y: .value("Y", item.y))
-    .interpolationMethod(.monotone)
-```
-
-### Sparkline (minimal inline chart)
+A sparkline:
 
 ```swift
-Chart(recentData) { item in
-    LineMark(
-        x: .value("Time", item.time),
-        y: .value("Value", item.value)
-    )
-    .interpolationMethod(.catmullRom)
+Chart(recent) { point in
+    LineMark(x: .value("t", point.index), y: .value("v", point.value))
+        .interpolationMethod(.catmullRom)
 }
 .chartXAxis(.hidden)
 .chartYAxis(.hidden)
@@ -264,625 +163,360 @@ Chart(recentData) { item in
 .frame(width: 80, height: 30)
 ```
 
----
-
-## Pie and Donut Chart Patterns (SectorMark, iOS 17+)
-
-Use strictly positive values for sectors. Filter, aggregate, or show zero and
-negative values outside the pie or donut so angular sizes remain meaningful.
-
-### Basic pie chart
-
-```swift
-Chart(products, id: \.name) { item in
-    SectorMark(angle: .value("Sales", item.sales))
-        .foregroundStyle(by: .value("Product", item.name))
-}
-```
+## Pies and Donuts
 
-### Donut chart with golden ratio inner radius
+An inner radius of 0.618 (the golden ratio) gives a balanced donut. Put a label
+in the hole with `.chartBackground`:
 
 ```swift
-Chart(products, id: \.name) { item in
-    SectorMark(
-        angle: .value("Sales", item.sales),
-        innerRadius: .ratio(0.618),
-        outerRadius: .inset(10),
-        angularInset: 1
-    )
-    .cornerRadius(4)
-    .foregroundStyle(by: .value("Product", item.name))
-}
-```
-
-### Donut chart with center label
-
-```swift
-Chart(products, id: \.name) { item in
-    SectorMark(
-        angle: .value("Sales", item.sales),
-        innerRadius: .ratio(0.618),
-        angularInset: 1
-    )
-    .cornerRadius(4)
-    .foregroundStyle(by: .value("Product", item.name))
+Chart(portfolio) { holding in
+    SectorMark(angle: .value("Value", holding.value), innerRadius: .ratio(0.618))
+        .foregroundStyle(by: .value("Asset", holding.asset))
 }
 .chartBackground { _ in
     VStack {
-        Text("Total")
-            .font(.caption)
-            .foregroundStyle(.secondary)
-        Text("\(totalSales, format: .number)")
-            .font(.title2.bold())
+        Text("Total").font(.caption)
+        Text(portfolioTotal, format: .currency(code: "EUR")).font(.headline)
     }
 }
 ```
 
-### Angular selection on donut
+Selecting a slice. The binding holds a position along the summed values, so
+map it back to a slice:
 
 ```swift
-struct ProductSales: Identifiable {
-    let id = UUID()
-    let name: String
-    let sales: Double
-}
+struct PortfolioDonut: View {
+    let holdings: [Holding]
+    @State private var selectedAngle: Double?
 
-@State private var selectedAngle: Double?
-
-var selectedProduct: ProductSales? {
-    guard let selectedAngle else { return nil }
-    var runningTotal = 0.0
-
-    return products.first { product in
-        let range = runningTotal..<(runningTotal + product.sales)
-        runningTotal += product.sales
-        return range.contains(selectedAngle)
+    private var selectedHolding: Holding? {
+        guard let angle = selectedAngle else { return nil }
+        var start = 0.0
+        for holding in holdings {
+            let end = start + holding.value
+            if (start..<end).contains(angle) { return holding }
+            start = end
+        }
+        return nil
     }
-}
 
-Chart(products, id: \.name) { item in
-    SectorMark(
-        angle: .value("Sales", item.sales),
-        innerRadius: .ratio(0.618),
-        angularInset: 1
-    )
-    .cornerRadius(4)
-    .foregroundStyle(by: .value("Product", item.name))
-    .opacity(selectedProduct == nil || selectedProduct?.name == item.name ? 1.0 : 0.4)
+    var body: some View {
+        Chart(holdings) { holding in
+            SectorMark(angle: .value("Value", holding.value), innerRadius: .ratio(0.6))
+                .foregroundStyle(by: .value("Asset", holding.asset))
+                .opacity(selectedHolding == nil || selectedHolding?.id == holding.id ? 1 : 0.4)
+        }
+        .chartAngleSelection(value: $selectedAngle)
+    }
 }
-.chartAngleSelection(value: $selectedAngle)
 ```
 
-`chartAngleSelection(value:)` binds the selected plottable angle value, not the
-sector label. Convert that value through cumulative sector ranges before using
-it to highlight or annotate a category.
-
-### Grouping small slices
-
-Limit pie/donut charts to 5-7 positive-value sectors. Group the rest into "Other":
+Keep five to seven positive slices:
 
 ```swift
-func groupSmallSlices(_ data: [CategorySales], topN: Int = 5) -> [CategorySales] {
-    let sorted = data.sorted { $0.sales > $1.sales }
-    let top = Array(sorted.prefix(topN))
-    let otherTotal = sorted.dropFirst(topN).reduce(0) { $0 + $1.sales }
-    guard otherTotal > 0 else { return top }
-    return top + [CategorySales(name: "Other", sales: otherTotal)]
+func topSlices(_ items: [Holding], keep limit: Int = 5) -> [Holding] {
+    let ordered = items.filter { $0.value > 0 }.sorted { $0.value > $1.value }
+    let head = Array(ordered.prefix(limit))
+    let remainder = ordered.dropFirst(limit).reduce(0) { $0 + $1.value }
+    guard remainder > 0 else { return head }
+    return head + [Holding(asset: "Other", value: remainder)]
 }
 ```
 
----
-
-## Combined Chart Patterns
+## Combining Marks
 
-### Line + area (trend with fill)
+A range band with an average line:
 
 ```swift
-Chart(data) { item in
-    AreaMark(
-        x: .value("Date", item.date),
-        yStart: .value("Min", item.low),
-        yEnd: .value("Max", item.high)
-    )
-    .foregroundStyle(.blue.opacity(0.15))
-
-    LineMark(
-        x: .value("Date", item.date),
-        y: .value("Average", item.average)
-    )
-    .foregroundStyle(.blue)
-    .lineStyle(StrokeStyle(lineWidth: 2))
+Chart(week) { day in
+    AreaMark(x: .value("Day", day.date),
+             yStart: .value("Low", day.low),
+             yEnd: .value("High", day.high))
+        .opacity(0.15)
+    LineMark(x: .value("Day", day.date), y: .value("Mean", day.mean))
+        .lineStyle(StrokeStyle(lineWidth: 2))
 }
 ```
 
-### Bar + threshold rule
+Bars with a target line:
 
 ```swift
 Chart {
-    ForEach(data) { item in
-        BarMark(
-            x: .value("Month", item.month),
-            y: .value("Revenue", item.revenue)
-        )
+    ForEach(weeks) { week in
+        BarMark(x: .value("Week", week.label), y: .value("Hours", week.hours))
     }
-    RuleMark(y: .value("Target", targetRevenue))
-        .foregroundStyle(.red)
-        .lineStyle(StrokeStyle(lineWidth: 1, dash: [5, 3]))
-        .annotation(position: .top, alignment: .leading) {
-            Text("Target: \(targetRevenue, format: .number)")
-                .font(.caption)
-                .foregroundStyle(.red)
-        }
+    RuleMark(y: .value("Target", 38))
+        .lineStyle(StrokeStyle(lineWidth: 1, dash: [4, 4]))
+        .annotation(position: .top, alignment: .leading) { Text("38 h") }
 }
 ```
 
-### Scatter + trend line
+Observations with a fitted curve; marks and plots can share a chart:
 
 ```swift
 Chart {
-    ForEach(data) { item in
-        PointMark(
-            x: .value("Experience", item.yearsExperience),
-            y: .value("Salary", item.salary)
-        )
-        .opacity(0.6)
+    ForEach(samples) { sample in
+        PointMark(x: .value("Dose", sample.dose), y: .value("Response", sample.response))
     }
-    LinePlot(x: "Experience", y: "Salary", domain: 0...20) { x in
-        baseSalary + x * salaryPerYear  // linear trend
+    LinePlot(x: "Dose", y: "Response", domain: 0...10) { dose in
+        fit.slope * dose + fit.intercept
     }
     .foregroundStyle(.red)
-    .lineStyle(StrokeStyle(lineWidth: 1.5, dash: [4, 2]))
+    .lineStyle(StrokeStyle(lineWidth: 1, dash: [3, 3]))
 }
 ```
 
----
+## A Tooltip on Selection
 
-## Chart Selection with Overlay Annotation
+```swift
+struct ActivityChart: View {
+    let days: [ActivityDay]
+    @State private var focusedDate: Date?
 
-Show a tooltip at the selected position using `chartOverlay`:
+    private var focusedDay: ActivityDay? {
+        guard let focusedDate else { return nil }
+        let calendar = Calendar.current
+        return days.first { calendar.isDate($0.date, inSameDayAs: focusedDate) }
+    }
 
-```swift
-@State private var selectedDate: Date?
-
-var body: some View {
-    Chart(data) { item in
-        LineMark(
-            x: .value("Date", item.date),
-            y: .value("Value", item.value)
-        )
-        if let selectedDate,
-           let match = data.first(where: { Calendar.current.isDate($0.date, inSameDayAs: selectedDate) }) {
-            RuleMark(x: .value("Selected", match.date))
-                .foregroundStyle(.secondary)
-            PointMark(
-                x: .value("Date", match.date),
-                y: .value("Value", match.value)
-            )
-            .symbolSize(60)
-            .annotation(position: .top) {
-                Text("\(match.value, format: .number)")
-                    .font(.caption)
-                    .padding(4)
-                    .background(.ultraThinMaterial, in: RoundedRectangle(cornerRadius: 4))
+    var body: some View {
+        Chart {
+            ForEach(days) { day in
+                LineMark(x: .value("Date", day.date, unit: .day),
+                         y: .value("Minutes", day.minutes))
+            }
+            if let focusedDay {
+                RuleMark(x: .value("Date", focusedDay.date, unit: .day))
+                    .foregroundStyle(.secondary)
+                PointMark(x: .value("Date", focusedDay.date, unit: .day),
+                          y: .value("Minutes", focusedDay.minutes))
+                    .symbolSize(80)
+                    .annotation(position: .top) {
+                        Text("\(focusedDay.minutes) min")
+                            .padding(6)
+                            .background(.regularMaterial, in: .rect(cornerRadius: 6))
+                    }
             }
         }
+        .chartXSelection(value: $focusedDate)
     }
-    .chartXSelection(value: $selectedDate)
 }
 ```
 
----
+## Scrolling with a Bound Position
 
-## Scrollable Chart with Visible Domain
+`chartScrollPosition(x:)` takes a binding to a non-optional `Plottable` value,
+so bind a `Date`, not a `Date?`:
 
 ```swift
-@State private var scrollPosition: Date?
-
-var body: some View {
-    Chart(dailySteps) { item in
-        BarMark(
-            x: .value("Date", item.date, unit: .day),
-            y: .value("Steps", item.steps)
-        )
-    }
-    .chartScrollableAxes(.horizontal)
-    .chartXVisibleDomain(length: 3600 * 24 * 7) // 7 days
-    .chartScrollPosition(x: $scrollPosition)
-    .chartScrollTargetBehavior(
-        .valueAligned(matching: DateComponents(hour: 0), majorAlignment: .page)
-    )
-    .chartXAxis {
-        AxisMarks(values: .stride(by: .day)) { value in
-            AxisGridLine()
-            AxisValueLabel(format: .dateTime.weekday(.abbreviated))
-        }
+@State private var windowStart = Date.now.addingTimeInterval(-7 * 86_400)
+
+Chart(readings) { reading in
+    BarMark(x: .value("Day", reading.date, unit: .day),
+            y: .value("Litres", reading.litres))
+}
+.chartScrollableAxes(.horizontal)
+.chartXVisibleDomain(length: 3600 * 24 * 7)
+.chartScrollPosition(x: $windowStart)
+.chartXAxis {
+    AxisMarks(values: .stride(by: .day)) { value in
+        AxisGridLine()
+        AxisValueLabel(format: .dateTime.weekday(.abbreviated))
     }
 }
 ```
 
----
-
-## Function Plotting (LinePlot, iOS 18+)
-
-### Standard function y = f(x)
+## Function Plots (iOS 18)
 
 ```swift
 Chart {
-    LinePlot(x: "x", y: "y", domain: -2 * .pi ... 2 * .pi) { x in
-        sin(x)
-    }
-    .foregroundStyle(.blue)
+    LinePlot(x: "Angle", y: "Amplitude", domain: -2 * .pi ... 2 * .pi) { cos($0) }
 }
-.chartYScale(domain: -1.5...1.5)
-```
+.chartYScale(domain: -1.2...1.2)
 
-### Parametric function (x, y) = f(t)
-
-```swift
 Chart {
-    LinePlot(x: "x", y: "y", t: "t", domain: 0 ... 2 * .pi) { t in
-        (x: cos(t), y: sin(t))
+    LinePlot(x: "Across", y: "Up", t: "Turn", domain: 0...(2 * .pi)) { turn in
+        (x: 2 * cos(turn), y: 2 * sin(turn))
     }
 }
-.chartXScale(domain: -1.5...1.5)
-.chartYScale(domain: -1.5...1.5)
-```
+.chartXScale(domain: -2.5...2.5)
+.chartYScale(domain: -2.5...2.5)
 
-### Range area function
-
-```swift
 Chart {
-    AreaPlot(x: "x", yStart: "min", yEnd: "max", domain: 0...10) { x in
-        (yStart: sin(x) - 0.5, yEnd: sin(x) + 0.5)
+    AreaPlot(x: "x", yStart: "lower", yEnd: "upper", domain: 0...4) { x in
+        (yStart: x - 0.5, yEnd: x * x / 2 + 0.5)
     }
-    .foregroundStyle(.blue.opacity(0.2))
 }
 ```
 
----
+The last chart fills the band between two functions of x.
 
-## 3D Charts and Surfaces (Chart3D, iOS 26+)
+## 3D Charts and Surfaces (iOS 26)
 
-Use `Chart3D` when the data has a real third dimension, such as `(x, y, z)`
-points, 3D regions, or a bivariate surface. Keep ordinary category comparison,
-time series, and proportions in 2D charts because they are easier to label,
-compare, and make accessible.
-
-### SurfacePlot for bivariate functions
+`Chart3D` is for data with a real third dimension: points in (x, y, z), 3D
+regions, or a surface of two variables. Categories, time series and shares stay
+in 2D: labels, comparisons and VoiceOver all work better there.
 
 ```swift
-@State private var pose: Chart3DPose = .default
+struct SensorCloud: View {
+    let readings: [SensorReading]
 
-Chart3D {
-    SurfacePlot(x: "x", y: "y", z: "z") { x, z in
-        sin(2 * x) * cos(2 * z)
+    var body: some View {
+        Chart3D(readings) { reading in
+            PointMark(x: .value("X", reading.x),
+                      y: .value("Y", reading.y),
+                      z: .value("Z", reading.z))
+                .foregroundStyle(by: .value("Sensor", reading.sensor))
+        }
+        .chart3DCameraProjection(.perspective)
     }
-    .foregroundStyle(.heightBased)
-}
-.chartXScale(domain: -2...2)
-.chartYScale(domain: -1...1)
-.chartZScale(domain: -2...2)
-.chart3DPose($pose)
-```
-
-### 3D point cloud
-
-```swift
-Chart3D(points) { point in
-    PointMark(
-        x: .value("Width", point.x),
-        y: .value("Height", point.y),
-        z: .value("Depth", point.z)
-    )
-    .foregroundStyle(by: .value("Cluster", point.cluster))
 }
-.chart3DCameraProjection(.perspective)
 ```
 
-### 3D review notes
-
-- Confirm the z dimension is meaningful and labeled; do not use depth only for decoration.
-- Set explicit x/y/z domains when users need stable comparisons across states.
-- Bind `Chart3DPose` when users need to inspect the scene interactively.
-- Use `SurfacePlot` for `y = f(x, z)` surfaces; use 3D mark initializers for observed data points or regions.
-
----
+Review notes:
+- The z axis must mean something and carry a label.
+- Set explicit x, y and z domains so charts can be compared.
+- Bind a `Chart3DPose` when users should rotate the chart.
+- `SurfacePlot` draws y as a function of x and z; the 3D mark initialisers
+  draw observed points and regions.
 
 ## Accessibility
 
-### Automatic VoiceOver support
-
-Swift Charts provides automatic VoiceOver descriptions for chart elements. The
-framework reads axis labels and values to visually impaired users without
-additional code. Ensure `.value("Label", ...)` strings are descriptive.
-
-### Custom accessibility labels
-
-```swift
-Chart(data) { item in
-    BarMark(
-        x: .value("Month", item.month),
-        y: .value("Sales", item.sales)
-    )
-    .accessibilityLabel("Sales for \(item.month)")
-    .accessibilityValue("\(item.sales) units sold")
-}
-```
-
-### Accessibility on vectorized plots (KeyPath-based)
-
-```swift
-BarPlot(data, x: .value("Month", \.month), y: .value("Sales", \.sales))
-    .accessibilityLabel(\.accessibilityDescription)
-    .accessibilityValue(\.formattedSales)
-```
-
-### Audio graphs
-
-The system automatically generates audio representations of chart data for
-VoiceOver users. Use clear, consistent data labels to ensure audio graphs
-convey meaningful patterns.
-
-### Best practices
-
-- Use descriptive strings in `.value("Label", ...)` -- these become VoiceOver labels.
-- Add `.accessibilityLabel` and `.accessibilityValue` for context beyond raw numbers.
-- Test with VoiceOver enabled: navigate the chart and verify each element is announced.
-- Avoid `.accessibilityHidden(true)` on data-bearing marks.
-
----
-
-## Dynamic Type and Color Considerations
-
-### Dynamic Type
-
-Charts automatically adjust axis label sizes with Dynamic Type. Avoid fixed
-frame heights that clip labels at larger text sizes.
-
-```swift
-// WRONG -- clips at large text sizes
-Chart(data) { ... }
-    .frame(height: 200)
-
-// CORRECT -- adaptive height
-Chart(data) { ... }
-    .frame(minHeight: 200)
-    .frame(maxHeight: 400)
-```
-
-Test charts at the "Accessibility Extra Extra Extra Large" text size to verify
-axis labels, annotations, and legends remain readable.
-
-### Color
-
-- Avoid encoding meaning solely in color. Pair `.foregroundStyle(by:)` with
-  `.symbol(by:)` or `.lineStyle(by:)` for distinguishability.
-- Use system colors that adapt to both light and dark modes.
-- Test with color blindness simulations in the Accessibility Inspector.
-
-```swift
-LineMark(x: .value("Date", item.date), y: .value("Value", item.value))
-    .foregroundStyle(by: .value("Category", item.category))
-    .symbol(by: .value("Category", item.category))
-    .lineStyle(by: .value("Category", item.category))
-```
-
----
-
-## Performance: Vectorized Plots for Large Datasets
-
-For datasets exceeding 1000 data points, use vectorized plot types instead of
-individual marks. Vectorized plots accept entire collections and render
-efficiently.
-
-### When to use vectorized plots
-
-| Data Points | Recommended Approach |
-|---|---|
-| < 100 | Individual marks (`BarMark`, `LineMark`, etc.) |
-| 100 - 1000 | Either approach; profile if performance matters |
-| > 1000 | Vectorized plots (`BarPlot`, `LinePlot`, etc.) |
-
-### Data-driven vectorized plot
-
-```swift
-struct SensorReading: Identifiable {
+- Swift Charts builds VoiceOver descriptions from axis labels and values, so
+  the strings in `.value("Label", ...)` are what VoiceOver says. Make them
+  descriptive.
+- Add `.accessibilityLabel` and `.accessibilityValue` to marks when the
+  default is not clear enough.
+- Vectorized plots take key paths:
+  `.accessibilityLabel(\.spokenName)` and `.accessibilityValue(\.spokenValue)`.
+- The system creates an audio graph for VoiceOver users automatically; clear,
+  consistent labels make it useful.
+- Move through every element with VoiceOver. Never mark data-bearing marks
+  `.accessibilityHidden(true)`.
+
+## Dynamic Type and Colour
+
+- Axis labels follow Dynamic Type. Avoid fixed heights; give a range such as
+  `.frame(minHeight: 200)` with `.frame(maxHeight: 400)`.
+- Check axes, annotations and legends at the largest accessibility size
+  (Accessibility Extra Extra Extra Large).
+- Colour must not be the only carrier of meaning. Pair
+  `.foregroundStyle(by:)` with `.symbol(by:)`, `.lineStyle(by:)` or both.
+- Prefer system colours, which adapt, and check colour-blindness filters in
+  Accessibility Inspector.
+
+## Performance: When to Vectorize
+
+| Points | Use |
+|--------|-----|
+| Fewer than 100 | Individual marks |
+| 100 to 1,000 | Either; profile if it feels slow |
+| More than 1,000 | Vectorized plots |
+
+```swift
+struct TemperatureSample: Identifiable {
     let id: Int
-    let timestamp: Date
-    let temperature: Double
-    var color: Color { temperature > 30 ? .red : .blue }
-    var accessibilityDescription: Text {
-        Text("\(timestamp.formatted(.dateTime.hour().minute())): \(temperature, specifier: "%.1f") degrees")
-    }
+    let time: Date
+    let celsius: Double
+    var tint: Color { celsius > 30 ? .red : .blue }
+    var spokenValue: Text { Text("\(celsius, specifier: "%.1f") degrees") }
 }
 
 Chart {
-    LinePlot(
-        readings,
-        x: .value("Time", \.timestamp),
-        y: .value("Temperature", \.temperature)
-    )
-    .foregroundStyle(.blue)
+    LinePlot(samples, x: .value("Time", \.time), y: .value("Celsius", \.celsius))
+        .foregroundStyle(\.tint)
+        .accessibilityValue(\.spokenValue)
 }
 ```
 
-### KeyPath modifier ordering
-
-Apply KeyPath-based modifiers before simple-value modifiers:
-
-```swift
-// WRONG
-BarPlot(data, x: .value("X", \.x), y: .value("Y", \.y))
-    .opacity(0.8)                // value modifier
-    .foregroundStyle(\.color)    // KeyPath -- compiler error
-
-// CORRECT
-BarPlot(data, x: .value("X", \.x), y: .value("Y", \.y))
-    .foregroundStyle(\.color)    // KeyPath first
-    .opacity(0.8)                // value modifier second
-```
-
-### Available vectorized plot types
-
-| Plot Type | Mark Equivalent | Available From |
-|---|---|---|
-| `BarPlot` | `BarMark` | iOS 18+ |
-| `LinePlot` | `LineMark` | iOS 18+ |
-| `PointPlot` | `PointMark` | iOS 18+ |
-| `AreaPlot` | `AreaMark` | iOS 18+ |
-| `RulePlot` | `RuleMark` | iOS 18+ |
-| `RectanglePlot` | `RectangleMark` | iOS 18+ |
-| `SectorPlot` | `SectorMark` | iOS 18+ |
-
----
+| Vectorized (iOS 18) | Mark equivalent |
+|---------------------|-----------------|
+| `BarPlot` | `BarMark` |
+| `LinePlot` | `LineMark` |
+| `PointPlot` | `PointMark` |
+| `AreaPlot` | `AreaMark` |
+| `RulePlot` | `RuleMark` |
+| `RectanglePlot` | `RectangleMark` |
+| `SectorPlot` | `SectorMark` |
 
 ## Dark Mode and Theming
 
-### Automatic adaptation
-
-Swift Charts inherits the current color scheme automatically. System colors
-(`.blue`, `.orange`, `.green`) adapt to light and dark modes without extra code.
-
-### Custom color palettes
-
-Use `.chartForegroundStyleScale` to define a consistent palette:
+Charts follow the colour scheme, and system colours adapt on their own.
 
 ```swift
-Chart(data) { item in
-    BarMark(
-        x: .value("Category", item.category),
-        y: .value("Value", item.value)
-    )
-    .foregroundStyle(by: .value("Category", item.category))
+Chart(spending) { entry in
+    BarMark(x: .value("Period", entry.period), y: .value("Spent", entry.amount))
+        .foregroundStyle(by: .value("Kind", entry.kind))
 }
 .chartForegroundStyleScale([
-    "Electronics": .blue,
-    "Clothing": .purple,
-    "Food": .orange,
-    "Books": .green,
-    "Other": .gray
+    "Food": Color.orange,
+    "Travel": Color.teal,
+    "Home": Color.purple,
 ])
-```
-
-### Background and plot area styling
-
-```swift
-Chart(data) { ... }
-.chartPlotStyle { plotArea in
-    plotArea
-        .background(.quaternary.opacity(0.3))
-        .border(.quaternary, width: 0.5)
+.chartPlotStyle { plot in
+    plot.background(.quaternary.opacity(0.3))
+        .border(.separator, width: 0.5)
 }
-```
-
-### Axis styling
-
-```swift
 .chartXAxisStyle { axis in
-    axis.background(.blue.opacity(0.05))
-}
-```
-
-### Testing dark mode
-
-Always preview charts in both light and dark color schemes. In Xcode previews:
-
-```swift
-#Preview {
-    ChartView()
-        .preferredColorScheme(.dark)
+    axis.background(.thinMaterial)
 }
 ```
 
-Verify:
-- Axis labels and grid lines are readable.
-- Data colors maintain sufficient contrast.
-- Annotations and legend text adapt properly.
-
----
+`chartForegroundStyleScale` fixes one colour per category across the app.
+Preview both schemes (`.preferredColorScheme(.dark)` in a `#Preview`) and check
+that labels and grid lines stay readable, data keeps its contrast, and
+annotations and legends adapt.
 
-## Heat Map Pattern
+## Heat Map
 
 ```swift
-Chart(heatMapData) { item in
-    RectangleMark(
-        x: .value("Hour", item.hour),
-        y: .value("Day", item.day)
-    )
-    .foregroundStyle(by: .value("Count", item.count))
+Chart(bookings) { cell in
+    RectangleMark(x: .value("Hour", cell.hour), y: .value("Weekday", cell.weekday))
+        .foregroundStyle(by: .value("Bookings", cell.count))
 }
-.chartForegroundStyleScale(range: Gradient(colors: [.blue, .yellow, .red]))
-```
-
----
-
-## Stacking Methods
-
-| Method | Behavior |
-|---|---|
-| `.standard` | Default. Regions stack on top showing absolute values. |
-| `.normalized` | Scales to 0-100% proportional view. |
-| `.center` | Baseline centered (streamgraph). |
-| `.unstacked` | Overlapping; no stacking. |
-
-```swift
-AreaMark(
-    x: .value("Date", item.date),
-    y: .value("Revenue", item.revenue),
-    stacking: .normalized
-)
-.foregroundStyle(by: .value("Category", item.category))
+.chartForegroundStyleScale(range: Gradient(colors: [.mint, .yellow, .orange]))
 ```
 
----
-
-## MarkDimension Options
+## Stacking
 
-| Dimension | Description |
-|---|---|
-| `.automatic` | Framework decides |
-| `.fixed(CGFloat)` | Exact pixel size |
-| `.inset(CGFloat)` | Inset from available space |
-| `.ratio(CGFloat)` | Proportion of available space (0...1) |
+Pass `stacking:` to `BarMark` or `AreaMark`:
 
-Use for `width`, `height` on `BarMark` and `innerRadius`, `outerRadius` on `SectorMark`.
+| Value | Effect |
+|-------|--------|
+| `.standard` | Absolute values stacked on each other (default) |
+| `.normalized` | Each stack fills 0 to 100 percent |
+| `.center` | Stacks centred on a baseline, as in a streamgraph |
+| `.unstacked` | Series overlap instead of stacking |
 
----
+## `MarkDimension`
 
-## Symbol Configuration
+`.automatic`, `.fixed(CGFloat)`, `.inset(CGFloat)` and `.ratio(CGFloat)` with a
+ratio between 0 and 1. Used for `width` and `height` on `BarMark` and for
+`innerRadius` and `outerRadius` on `SectorMark`.
 
-### Built-in shapes
+## Symbols
 
-`circle`, `square`, `triangle`, `diamond`, `pentagon`, `plus`, `cross`, `asterisk`
+The built-in shapes are `asterisk`, `circle`, `cross`, `diamond`, `pentagon`,
+`plus`, `square` and `triangle`.
 
 ```swift
-PointMark(x: .value("X", item.x), y: .value("Y", item.y))
+PointMark(x: .value("Speed", run.speed), y: .value("Heart rate", run.bpm))
     .symbol(.diamond)
     .symbolSize(80)
-```
 
-### Data-driven symbol encoding
+PointMark(x: .value("Speed", run.speed), y: .value("Heart rate", run.bpm))
+    .symbol(by: .value("Surface", run.surface))
 
-```swift
-PointMark(x: .value("X", item.x), y: .value("Y", item.y))
-    .symbol(by: .value("Category", item.category))
+PointMark(x: .value("Speed", run.speed), y: .value("Heart rate", run.bpm))
+    .symbol { Image(systemName: "figure.run").font(.caption2) }
 ```
 
-### Custom symbol view
+## `ChartProxy` and Coordinates
 
-```swift
-PointMark(x: .value("X", item.x), y: .value("Y", item.y))
-    .symbol {
-        Image(systemName: "star.fill")
-            .font(.caption2)
-    }
-```
-
----
-
-## ChartProxy and Coordinate Conversion
-
-Use `chartOverlay` or `chartBackground` to access `ChartProxy`:
+`chartOverlay` and `chartBackground` pass a `ChartProxy` that converts between
+screen positions and data values. Since iOS 17, `plotFrame` (an optional
+anchor) and `plotSize` replace the deprecated `plotAreaFrame` and
+`plotAreaSize`.
 
 ```swift
 .chartOverlay { proxy in
@@ -891,86 +525,41 @@ Use `chartOverlay` or `chartBackground` to access `ChartProxy`:
             .fill(.clear)
             .contentShape(Rectangle())
             .gesture(
-                DragGesture()
-                    .onChanged { value in
-                        let origin = geometry[proxy.plotAreaFrame].origin
-                        let location = CGPoint(
-                            x: value.location.x - origin.x,
-                            y: value.location.y - origin.y
-                        )
-                        if let date: Date = proxy.value(atX: location.x) {
-                            selectedDate = date
-                        }
-                    }
+                DragGesture(minimumDistance: 0).onChanged { drag in
+                    guard let plotFrame = proxy.plotFrame else { return }
+                    let origin = geometry[plotFrame].origin
+                    let x = drag.location.x - origin.x
+                    scrubbedDate = proxy.value(atX: x, as: Date.self)
+                }
             )
     }
 }
 ```
 
-### Key ChartProxy methods
-
-| Method | Purpose |
-|---|---|
-| `position(forX:)` | Data value to screen x-coordinate |
-| `position(forY:)` | Data value to screen y-coordinate |
-| `value(atX:as:)` | Screen x-coordinate to data value |
-| `value(atY:as:)` | Screen y-coordinate to data value |
-| `plotAreaSize` | Size of the plot area |
-| `plotAreaFrame` | Anchor for the plot area frame |
-
----
-
-## Quick Reference: Chart View Modifiers
-
-### Axes
-- `chartXAxis(_:)` / `chartXAxis(content:)`
-- `chartYAxis(_:)` / `chartYAxis(content:)`
-- `chartXAxisLabel(...)` / `chartYAxisLabel(...)`
-- `chartXAxisStyle(content:)` / `chartYAxisStyle(content:)`
-
-### Scales
-- `chartXScale(domain:range:type:)` and variants
-- `chartYScale(domain:range:type:)` and variants
-- `chartZScale(domain:range:type:)` for `Chart3D`
-- `chartForegroundStyleScale(_:)` -- custom color mapping
-
-### 3D charts (iOS 26+)
-- `Chart3D` with `SurfacePlot` or 3D mark initializers
-- `chart3DPose(_:)` for interactive pose binding
-- `chart3DCameraProjection(_:)` for orthographic/perspective projection
-
-### Legend
-- `chartLegend(_:)` -- visibility
-- `chartLegend(position:alignment:spacing:)` -- positioning
-- `chartLegend(position:alignment:spacing:content:)` -- custom content
-
-### Selection (iOS 17+)
-- `chartXSelection(value:)` / `chartXSelection(range:)`
-- `chartYSelection(value:)` / `chartYSelection(range:)`
-- `chartAngleSelection(value:)` -- for `SectorMark`
-
-### Scrolling (iOS 17+)
-- `chartScrollableAxes(_:)`
-- `chartXVisibleDomain(length:)` / `chartYVisibleDomain(length:)`
-- `chartScrollPosition(initialX:)` / `chartScrollPosition(x:)`
-- `chartScrollTargetBehavior(_:)`
-
-### Overlay and Background
-- `chartOverlay(alignment:content:)` -- with `ChartProxy`
-- `chartBackground(alignment:content:)` -- with `ChartProxy`
-- `chartPlotStyle(content:)` -- plot area styling
-
----
-
-## Apple Documentation Links
-
-- [Swift Charts](https://sosumi.ai/documentation/charts)
-- [Creating a chart using Swift Charts](https://sosumi.ai/documentation/charts/Creating-a-chart-using-Swift-Charts)
-- [BarMark](https://sosumi.ai/documentation/charts/BarMark)
-- [LineMark](https://sosumi.ai/documentation/charts/LineMark)
-- [SectorMark](https://sosumi.ai/documentation/charts/SectorMark)
-- [Chart3D](https://sosumi.ai/documentation/charts/Chart3D)
-- [SurfacePlot](https://sosumi.ai/documentation/charts/SurfacePlot)
-- [LinePlot](https://sosumi.ai/documentation/charts/LinePlot)
-- [AxisMarks](https://sosumi.ai/documentation/charts/AxisMarks)
-- [Swift Charts updates](https://sosumi.ai/documentation/updates/swiftcharts)
+Proxy methods: `position(forX:)`, `position(forY:)`, `value(atX:as:)`,
+`value(atY:as:)`, plus `plotSize` and `plotFrame`.
+
+## Modifier Quick Reference
+
+| Area | Modifiers |
+|------|-----------|
+| Axes | hide or replace: `chartYAxis(_:)`, `chartXAxis(_:)`, and the builder forms `chartYAxis(content:)`, `chartXAxis(content:)`; titles: `chartYAxisLabel`, `chartXAxisLabel`; axis area styling: `chartYAxisStyle(content:)`, `chartXAxisStyle(content:)` |
+| Scales | `chartYScale(domain:range:type:)`, `chartXScale(domain:range:type:)`; for `Chart3D` also `chartZScale(domain:range:type:)`; categorical colours with `chartForegroundStyleScale(_:)` |
+| 3D | `chart3DCameraProjection(_:)` (perspective or orthographic), `chart3DPose(_:)` |
+| Legend | `chartLegend(_:)` for visibility; `chartLegend(position:alignment:spacing:)` for placement; add `content:` for a custom legend view |
+| Selection (iOS 17) | a single value: `chartXSelection(value:)`, `chartYSelection(value:)`; a span: `chartXSelection(range:)`, `chartYSelection(range:)`; pie slices: `chartAngleSelection(value:)` |
+| Scrolling (iOS 17) | turn on with `chartScrollableAxes(_:)`; window size with `chartXVisibleDomain(length:)` or `chartYVisibleDomain(length:)`; position with `chartScrollPosition(initialX:)` or a bound `chartScrollPosition(x:)`; snapping with `chartScrollTargetBehavior(_:)` |
+| Plot area and layers | `chartPlotStyle(content:)`, `chartBackground(alignment:content:)`, `chartOverlay(alignment:content:)` |
+
+## Apple Documentation
+
+- [Swift Charts](https://developer.apple.com/documentation/charts)
+- [Building a first chart](https://developer.apple.com/documentation/charts/creating-a-chart-using-swift-charts)
+- [BarMark](https://developer.apple.com/documentation/charts/barmark)
+- [LineMark](https://developer.apple.com/documentation/charts/linemark)
+- [SectorMark](https://developer.apple.com/documentation/charts/sectormark)
+- [Chart3D](https://developer.apple.com/documentation/charts/chart3d)
+- [SurfacePlot](https://developer.apple.com/documentation/charts/surfaceplot)
+- [LinePlot](https://developer.apple.com/documentation/charts/lineplot)
+- [AxisMarks](https://developer.apple.com/documentation/charts/axismarks)
+- [Swift Charts updates](https://developer.apple.com/documentation/updates/swiftcharts)