7. Charts and timelines from data

Plot series data with `barchart and put real dates on a timeline — both inside a diagram`._

Before you start: Your first diagram

The chart kinds — bar_chart, line_chart, pie_chart — are diagram shapes, so each sits inside a diagram sharing its size. Bar and line charts take a series list of { name, values } records with categories labelling the x-axis; a pie takes slices of { label, value }. Bare { … } records are enough — the variant is inferred from the shape.

A timeline is a real-time axis: dates are ISO strings, a unit (:minutes … :years) sets the tick granularity, items are point events, and phases are labelled spans drawn as bands.

§ 1Exercise: A chart and a roadmap

Plot two series over four quarters, then lay a kickoff and a release on a year-long timeline with one phase.

page metrics { sites = [:docs]
  h1 "Metrics"
  diagram { width = 360  height = 200
    bar_chart { width = 360.0  height = 200.0
      title = "Revenue"  x_label = "Quarter"  y_label = "$k"
      categories = ["Q1", "Q2", "Q3", "Q4"]
      series = [
        { name: "2025", values: [42.0, 55.0, 61.0, 78.0] },
        { name: "2026", values: [30.0, 48.0, 52.0, 66.0] },
      ]
    }
  }
  diagram { width = 560  height = 220
    timeline { width = 560.0  height = 220.0
      title = "2026 roadmap"
      start = "2026-01-01"
      end   = "2026-12-31"
      unit  = :months
      items = [
        { label: "Kickoff", on: "2026-02-20" },
        { label: "Release", on: "2026-09-20" },
      ]
      phases = [ { label: "Build", from: "2026-02-01", to: "2026-06-15" } ]
    }
  }
}