diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4a0a0f6..5ec9058 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,19 @@ All notable changes to gitbonsai are recorded here. Any change to how a tree
grows or looks is at least a minor version, because people will notice their
tree changing.
+## 0.1.1
+
+Trees change look in this release: smoother wood and softer leaves.
+
+- An optional legend beside the tree (`[render] legend = "left"` or `"right"`,
+ or `render --legend`): each language's leaf color and what the signs mean.
+ Off by default; the PNG leaves it out.
+- Smoother wood: curved outlines, no knobs where pieces meet, side branches
+ that start at their own girth instead of as thorns, and tapered tips.
+- Softer leaves: each pad is lit as one volume in three soft tones, with cool
+ shadows and warm light.
+- Smaller SVGs.
+
## 0.1.0
The first release.
diff --git a/Cargo.lock b/Cargo.lock
index 9c3ccbd..d7e9a85 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -204,7 +204,7 @@ checksum = "98de4bbd547a563b716d8dfa9aad1cb19bfab00f4fa09a6a4ed21dbcf44ce9c4"
[[package]]
name = "gitbonsai"
-version = "0.1.0"
+version = "0.1.1"
dependencies = [
"anyhow",
"clap",
diff --git a/Cargo.toml b/Cargo.toml
index d52d1a7..7c67f99 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
[package]
name = "gitbonsai"
-version = "0.1.0"
+version = "0.1.1"
edition = "2024"
rust-version = "1.99.0"
license = "MIT OR Apache-2.0"
diff --git a/README.md b/README.md
index ad41a66..36affb0 100644
--- a/README.md
+++ b/README.md
@@ -4,13 +4,18 @@ Grow a Japanese maple bonsai from your GitHub activity: an animated SVG for your
-
-
+
+
The tree is yours: it grows from your own GitHub activity, week by week. The trunk rises with the years you've been active and thickens with every contribution you've ever made. Each language you write grows branches on its own side, with leaves in that language's color. Your last few months decide how full the leaves are, so busy stretches show and quiet ones thin the crown. Wood never shrinks, so the tree remembers everything.
+| Newbie | Comeback | Veteran |
+| :---: | :---: | :---: |
+| | | |
+| a few months in | quiet for two years, then back | 16 years, busy since 2023 |
+
What every part shows
@@ -55,7 +60,7 @@ On your profile, copy [examples/profile-workflow.yml](examples/profile-workflow.
On its own, `width="600"` suits a desktop column, and phones scale it down to fit. Next to other cards, use `400`.
-Styles, leaf colors and the pot glaze go in a `bonsai.toml`; see [examples/bonsai.toml](examples/bonsai.toml).
+Styles, leaf colors, the pot glaze and an optional legend (left or right of the tree) go in a `bonsai.toml`; see [examples/bonsai.toml](examples/bonsai.toml).
## Credits
diff --git a/assets/comeback-dark.svg b/assets/comeback-dark.svg
new file mode 100644
index 0000000..e585e09
--- /dev/null
+++ b/assets/comeback-dark.svg
@@ -0,0 +1 @@
+
diff --git a/assets/comeback-light.svg b/assets/comeback-light.svg
new file mode 100644
index 0000000..f88b2df
--- /dev/null
+++ b/assets/comeback-light.svg
@@ -0,0 +1 @@
+
diff --git a/assets/newbie-dark.svg b/assets/newbie-dark.svg
new file mode 100644
index 0000000..14f287f
--- /dev/null
+++ b/assets/newbie-dark.svg
@@ -0,0 +1 @@
+
diff --git a/assets/newbie-light.svg b/assets/newbie-light.svg
new file mode 100644
index 0000000..173a4bf
--- /dev/null
+++ b/assets/newbie-light.svg
@@ -0,0 +1 @@
+
diff --git a/assets/veteran-dark.svg b/assets/veteran-dark.svg
index 48be06d..e3453b3 100644
--- a/assets/veteran-dark.svg
+++ b/assets/veteran-dark.svg
@@ -1 +1 @@
-
+
diff --git a/assets/veteran-legend-dark.svg b/assets/veteran-legend-dark.svg
new file mode 100644
index 0000000..58633b1
--- /dev/null
+++ b/assets/veteran-legend-dark.svg
@@ -0,0 +1 @@
+
diff --git a/assets/veteran-legend-light.svg b/assets/veteran-legend-light.svg
new file mode 100644
index 0000000..a0327bc
--- /dev/null
+++ b/assets/veteran-legend-light.svg
@@ -0,0 +1 @@
+
diff --git a/assets/veteran-light.svg b/assets/veteran-light.svg
index 7eb054f..3cfdfe0 100644
--- a/assets/veteran-light.svg
+++ b/assets/veteran-light.svg
@@ -1 +1 @@
-
+
diff --git a/examples/bonsai.toml b/examples/bonsai.toml
index 39bb236..baf9095 100644
--- a/examples/bonsai.toml
+++ b/examples/bonsai.toml
@@ -20,4 +20,5 @@ color = "#F4C7D3"
[render]
animate = true
-size = 400 # display width in px; the viewBox stays 512
+size = 400 # display width in px; the height follows the tree
+legend = "off" # "left" or "right": what the colors and signs mean
diff --git a/src/config.rs b/src/config.rs
index b4526ca..f52893f 100644
--- a/src/config.rs
+++ b/src/config.rs
@@ -97,6 +97,8 @@ pub struct RenderConfig {
pub animate: bool,
/// Display width in pixels; the height follows the tree's frame.
pub size: u32,
+ /// A legend beside the tree: what the colors and signs mean.
+ pub legend: Legend,
}
impl Default for RenderConfig {
@@ -104,6 +106,33 @@ impl Default for RenderConfig {
Self {
animate: true,
size: 400,
+ legend: Legend::Off,
+ }
+ }
+}
+
+/// Where the legend goes, if anywhere.
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Legend {
+ /// No legend: just the tree.
+ #[default]
+ Off,
+ /// Left of the tree.
+ Left,
+ /// Right of the tree.
+ Right,
+}
+
+impl std::str::FromStr for Legend {
+ type Err = String;
+
+ fn from_str(s: &str) -> Result {
+ match s {
+ "off" => Ok(Self::Off),
+ "left" => Ok(Self::Left),
+ "right" => Ok(Self::Right),
+ _ => Err(format!("legend must be off, left or right, not {s:?}")),
}
}
}
diff --git a/src/eggs.rs b/src/eggs.rs
index e231757..b66d530 100644
--- a/src/eggs.rs
+++ b/src/eggs.rs
@@ -27,6 +27,7 @@ use std::fmt::Write as _;
use crate::Bonsai;
use crate::color::Rgb;
+use crate::config::Legend;
use crate::growth::GOLDEN;
use crate::math;
use crate::noise::{fbm, hash01, noise1};
@@ -139,8 +140,9 @@ fn take_spot(
/// The easter eggs of `b`'s achievements.
/// Where the moon hangs: the clearer of the frame's top corners. When both
/// are crowded, the frame grows upward until the moon's disc stands clear.
-/// `k` is the moon's size relative to a full-grown frame.
-fn moon_spot(scene: &Scene, frame: &mut Frame, k: f64) -> (f64, f64) {
+/// `k` is the moon's size relative to a full-grown frame. With a legend, the
+/// corner away from it wins whenever it is clear.
+fn moon_spot(scene: &Scene, frame: &mut Frame, k: f64, legend: Legend) -> (f64, f64) {
let inset = 34.0 * k;
let clear = 30.0 * k;
let mut pts: Vec<(f64, f64)> = scene
@@ -165,10 +167,15 @@ fn moon_spot(scene: &Scene, frame: &mut Frame, k: f64) -> (f64, f64) {
let top = frame.1 + inset;
let left = (frame.0 + inset, top);
let right = (frame.0 + frame.2 - inset, top);
- let (spot, room) = if clearance(left) > clearance(right) {
- (left, clearance(left))
- } else {
- (right, clearance(right))
+ let away = match legend {
+ Legend::Right => Some(left),
+ Legend::Left => Some(right),
+ Legend::Off => None,
+ };
+ let (spot, room) = match away {
+ Some(c) if clearance(c) >= clear => (c, clearance(c)),
+ _ if clearance(left) > clearance(right) => (left, clearance(left)),
+ _ => (right, clearance(right)),
};
if room >= clear {
return spot;
@@ -179,8 +186,16 @@ fn moon_spot(scene: &Scene, frame: &mut Frame, k: f64) -> (f64, f64) {
(spot.0, spot.1 - lift)
}
-/// The easter eggs of `b`'s achievements. The moon may grow `frame` upward.
-pub fn eggs(b: &Bonsai, scene: &Scene, paints: &Paints, pot: &Pot, frame: &mut Frame) -> Eggs {
+/// The easter eggs of `b`'s achievements. The moon may grow `frame` upward,
+/// and keeps clear of the legend's side.
+pub fn eggs(
+ b: &Bonsai,
+ scene: &Scene,
+ paints: &Paints,
+ pot: &Pot,
+ frame: &mut Frame,
+ legend: Legend,
+) -> Eggs {
let mut e = Eggs::default();
let tier = |slug: &str| b.achievements.get(slug).copied();
if !DRAWN.iter().any(|slug| tier(slug).is_some()) {
@@ -350,7 +365,7 @@ pub fn eggs(b: &Bonsai, scene: &Scene, paints: &Paints, pot: &Pot, frame: &mut F
if t >= 3 {
// Sized to the frame, so it never looms over a young tree.
let k = (frame.2 / 480.0).clamp(0.5, 1.0);
- let at = moon_spot(scene, frame, k);
+ let at = moon_spot(scene, frame, k, legend);
// Golden with a halo on light backgrounds, pale on dark: visible on both.
let (body, halo, crater) = if dark {
("#f3e3a3", "#f6e9b2", "#d9c47e")
diff --git a/src/legend.rs b/src/legend.rs
new file mode 100644
index 0000000..73b699e
--- /dev/null
+++ b/src/legend.rs
@@ -0,0 +1,408 @@
+//! The optional legend: each language's leaf color and what the tree's signs
+//! mean, set beside the tree. Only signs this tree actually shows are listed,
+//! and the surprises around the pot are never explained.
+
+#![allow(
+ clippy::cast_precision_loss,
+ clippy::cast_possible_truncation,
+ clippy::cast_sign_loss,
+ reason = "positions on a 512-unit canvas; contribution totals are small and positive"
+)]
+
+use std::collections::BTreeMap;
+use std::fmt::Write as _;
+
+use crate::Bonsai;
+use crate::color::Rgb;
+use crate::config::Legend;
+use crate::foliage::LanguageState;
+use crate::maple::MAPLE_GREEN;
+use crate::paint::{Frame, Paints};
+use crate::render::{Num, escape};
+
+/// The most languages listed; the rest are counted.
+const MAX_LANGUAGES: usize = 8;
+
+/// What the tree shows besides its languages.
+#[derive(Debug, Clone, Copy, Default)]
+pub struct Signs {
+ /// Bronze tips: leaves that grew last week.
+ pub fresh: bool,
+ /// Leaves falling: a level crossed this week.
+ pub falling: bool,
+ /// The pot's glaze.
+ pub glaze: Option,
+}
+
+/// A row's marker, drawn left of its words.
+enum Mark {
+ Leaf(Rgb),
+ Twig(Rgb),
+ Trunk,
+ Seeds,
+ Falling,
+ Moss,
+ Pot(Rgb),
+}
+
+/// One row: a heading, a marked line, or a plain line under the marks.
+struct Row {
+ heading: bool,
+ mark: Option,
+ text: String,
+ note: Option<&'static str>,
+}
+
+impl Row {
+ fn heading(text: &str) -> Self {
+ Self {
+ heading: true,
+ mark: None,
+ text: text.to_string(),
+ note: None,
+ }
+ }
+
+ fn sign(mark: Mark, text: String) -> Self {
+ Self {
+ heading: false,
+ mark: Some(mark),
+ text,
+ note: None,
+ }
+ }
+}
+
+/// `n` with thousands separators.
+fn thousands(n: u64) -> String {
+ let digits = n.to_string();
+ let mut out = String::new();
+ for (i, c) in digits.chars().enumerate() {
+ if i > 0 && (digits.len() - i).is_multiple_of(3) {
+ out.push(',');
+ }
+ out.push(c);
+ }
+ out
+}
+
+/// An age in words: weeks, then months, then years.
+fn age(weeks: u32) -> String {
+ let plural = |n: u32, unit: &str| format!("{n} {unit}{}", if n == 1 { "" } else { "s" });
+ if weeks < 9 {
+ plural(weeks, "week")
+ } else if weeks < 104 {
+ plural(weeks * 700 / 3044, "month")
+ } else {
+ plural(weeks * 100 / 5218, "year")
+ }
+}
+
+/// A language name, cut to `max` characters.
+fn short(name: &str, max: usize) -> String {
+ let mut out: String = name.chars().take(max).collect();
+ if name.chars().count() > max {
+ out.push('…');
+ }
+ out
+}
+
+fn rows(b: &Bonsai, paints: &Paints, signs: Signs) -> Vec {
+ // Living languages first, busiest first; then resting ones by lifetime.
+ // Deadwood shares one line: it is history, not what the tree is now.
+ let mut lifetime: BTreeMap<&str, f64> = BTreeMap::new();
+ for day in &b.timeline.days {
+ for (language, amount) in &day.by_language {
+ *lifetime.entry(language.as_str()).or_default() += amount;
+ }
+ }
+ let total = |l: &str| lifetime.get(l).copied().unwrap_or(0.0);
+ let of = |state: LanguageState| -> Vec<&String> {
+ let mut v: Vec<&String> = b
+ .order
+ .iter()
+ .filter(|l| b.state(Some(l)) == state)
+ .collect();
+ v.sort_by(|x, y| {
+ let key = |l: &str| {
+ if state == LanguageState::Alive {
+ b.window.of_language(Some(l))
+ } else {
+ total(l)
+ }
+ };
+ key(y).total_cmp(&key(x)).then(x.cmp(y))
+ });
+ v
+ };
+ let (alive, resting, dead) = (
+ of(LanguageState::Alive),
+ of(LanguageState::Bare),
+ of(LanguageState::Jin),
+ );
+
+ let mut rows = vec![Row::heading("Leaves")];
+ let shown: Vec<&String> = alive.iter().chain(&resting).copied().collect();
+ for language in shown.iter().take(MAX_LANGUAGES) {
+ let (mark, note) = if b.state(Some(language)) == LanguageState::Alive {
+ let leaf = b
+ .maple
+ .leaf(Some(language), 0.5)
+ .shift(paints.leaf_shift, 0.0);
+ (Mark::Leaf(leaf), None)
+ } else {
+ (Mark::Twig(paints.bark), Some("resting"))
+ };
+ rows.push(Row {
+ heading: false,
+ mark: Some(mark),
+ text: short(language, 16),
+ note,
+ });
+ }
+ if shown.len() > MAX_LANGUAGES {
+ rows.push(Row {
+ heading: false,
+ mark: None,
+ text: format!("+{} more", shown.len() - MAX_LANGUAGES),
+ note: None,
+ });
+ }
+ if !dead.is_empty() {
+ let mut names: Vec = dead.iter().take(2).map(|l| short(l, 12)).collect();
+ if dead.len() > 2 {
+ names.push(format!("+{}", dead.len() - 2));
+ }
+ rows.push(Row::sign(
+ Mark::Twig(paints.jin),
+ format!("deadwood: {}", names.join(", ")),
+ ));
+ }
+
+ rows.push(Row::heading("Signs"));
+ rows.push(Row::sign(
+ Mark::Trunk,
+ format!(
+ "{}, {} contributions",
+ age(b.timeline.age_weeks()),
+ thousands(b.timeline.capped_lifetime().round() as u64)
+ ),
+ ));
+ if signs.fresh {
+ let bronze = MAPLE_GREEN
+ .mix(Rgb::hex(0xc8553d), 0.45)
+ .shift(0.06 + paints.leaf_shift, 0.0);
+ rows.push(Row::sign(Mark::Leaf(bronze), "new growth this week".into()));
+ }
+ if b.extras.level >= 3 {
+ rows.push(Row::sign(
+ Mark::Seeds,
+ format!("lifetime level {}", b.extras.level),
+ ));
+ }
+ if signs.falling {
+ rows.push(Row::sign(Mark::Falling, "a new level this week".into()));
+ }
+ if b.extras.current_streak > 0 && b.extras.moss > 0.0 {
+ rows.push(Row::sign(
+ Mark::Moss,
+ format!("{}-week streak", b.extras.current_streak),
+ ));
+ }
+ if let Some(glaze) = signs.glaze {
+ rows.push(Row::sign(
+ Mark::Pot(glaze),
+ format!("longest streak {} weeks", b.extras.longest_streak),
+ ));
+ }
+ rows
+}
+
+/// The legend's markup, beside `frame` on `side`; `frame` grows to hold it.
+/// Empty when the legend is off or the tree has nothing to explain yet.
+pub fn legend(
+ b: &Bonsai,
+ paints: &Paints,
+ signs: Signs,
+ side: Legend,
+ frame: &mut Frame,
+) -> String {
+ if side == Legend::Off || b.is_empty() {
+ return String::new();
+ }
+ let rows = rows(b, paints, signs);
+ // Sized to the tree, so the words read the same at any tree size.
+ let fs = (frame.2.max(frame.3 * 1.2) * 0.036).clamp(10.0, 24.0);
+ let lh = fs * 1.7;
+ let mark = fs * 1.2;
+ let indent = mark + fs * 0.7;
+ let width = rows
+ .iter()
+ .map(|r| {
+ let words = r.text.chars().count() + r.note.map_or(0, |n| n.len() + 3);
+ let left = if r.heading { 0.0 } else { indent };
+ left + words as f64 * fs * 0.52
+ })
+ .fold(0.0, f64::max);
+ let gap = fs * 1.6;
+ let height = rows.len() as f64 * lh;
+
+ // Make room: beside the tree, and taller when the list is.
+ let grid = |v: f64| (v / 8.0).ceil() * 8.0;
+ let room = grid(width + gap);
+ let x0 = match side {
+ Legend::Left => {
+ frame.0 -= room;
+ frame.0 + fs * 0.6
+ }
+ _ => frame.0 + frame.2 + gap,
+ };
+ frame.2 += room;
+ let need = height + 2.0 * fs;
+ if need > frame.3 {
+ let grow = grid(need - frame.3);
+ frame.1 -= grow;
+ frame.3 += grow;
+ }
+ let top = frame.1 + (frame.3 - height) / 2.0;
+
+ let (ink, muted) = if paints.dark {
+ ("#d4cbb9", "#988e7c")
+ } else {
+ ("#4f473b", "#8c816e")
+ };
+ let mut s = format!(
+ r#""#,
+ Num(fs)
+ );
+ for (i, row) in rows.iter().enumerate() {
+ let cy = top + (i as f64 + 0.5) * lh;
+ let baseline = cy + fs * 0.35;
+ let Some(m) = &row.mark else {
+ // Headings sit flush left and bold; a plain line lines up with the words.
+ let _ = write!(
+ s,
+ r#"{}"#,
+ Num(if row.heading { x0 } else { x0 + indent }),
+ Num(baseline),
+ if row.heading {
+ r#" font-weight="600" letter-spacing=".04em""#
+ } else {
+ ""
+ },
+ escape(&row.text)
+ );
+ continue;
+ };
+ let mx = x0 + mark / 2.0;
+ s.push_str(&marker(m, mx, cy, mark, paints));
+ let _ = write!(
+ s,
+ r#"{}"#,
+ Num(x0 + indent),
+ Num(baseline),
+ escape(&row.text)
+ );
+ if let Some(note) = row.note {
+ let _ = write!(s, r#" · {note}"#);
+ }
+ s.push_str("");
+ }
+ s.push_str("");
+ s
+}
+
+/// A row's marker, `size` across, centered on `(x, y)`.
+fn marker(mark: &Mark, x: f64, y: f64, size: f64, paints: &Paints) -> String {
+ let h = size / 2.0;
+ match mark {
+ Mark::Leaf(color) => format!(
+ r##""##,
+ Num(x),
+ Num(y + h),
+ Num(size / 5.2)
+ ),
+ Mark::Twig(color) => format!(
+ r#""#,
+ Num(x - h),
+ Num(y + h * 0.8),
+ Num(x + h),
+ Num(y - h * 0.8),
+ Num(x),
+ Num(y),
+ Num(x + h * 0.15),
+ Num(y - h * 0.9),
+ Num(size * 0.14)
+ ),
+ Mark::Trunk => format!(
+ r#""#,
+ Num(x - h * 0.55),
+ Num(y + h),
+ Num(x - h * 0.1),
+ Num(y),
+ Num(x - h * 0.15),
+ Num(y - h),
+ Num(x + h * 0.2),
+ Num(y - h),
+ Num(x + h * 0.15),
+ Num(y),
+ Num(x + h * 0.6),
+ Num(y + h),
+ paints.bark
+ ),
+ Mark::Seeds => format!(
+ r##""##,
+ Num(x),
+ Num(y - h * 0.7),
+ Num(size / 9.0),
+ paints.crimson
+ ),
+ Mark::Falling => format!(
+ r##""##,
+ Num(x),
+ Num(y - h * 0.4),
+ Num(size / 5.6),
+ paints.crimson
+ ),
+ Mark::Moss => format!(
+ r#""#,
+ Num(x - h * 0.3),
+ Num(y + h * 0.3),
+ Num(h * 0.6),
+ Num(h * 0.3),
+ paints.moss[0],
+ Num(x + h * 0.35),
+ Num(y + h * 0.15),
+ Num(h * 0.45),
+ Num(h * 0.25),
+ paints.moss[1]
+ ),
+ Mark::Pot(glaze) => format!(
+ r#""#,
+ Num(x - h),
+ Num(y - h * 0.35),
+ Num(x + h),
+ Num(x + h * 0.7),
+ Num(y + h * 0.55),
+ Num(x - h * 0.7)
+ ),
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn numbers_and_ages_read_naturally() {
+ assert_eq!(thousands(0), "0");
+ assert_eq!(thousands(999), "999");
+ assert_eq!(thousands(1_000), "1,000");
+ assert_eq!(thousands(26_301), "26,301");
+ assert_eq!(thousands(1_234_567), "1,234,567");
+ assert_eq!(age(1), "1 week");
+ assert_eq!(age(5), "5 weeks");
+ assert_eq!(age(96), "22 months");
+ assert_eq!(age(869), "16 years");
+ }
+}
diff --git a/src/lib.rs b/src/lib.rs
index 0ecf439..b44edf9 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -36,6 +36,7 @@ pub mod fixtures;
pub mod foliage;
pub mod growth;
pub mod html;
+pub mod legend;
pub mod maple;
pub mod math;
pub mod noise;
diff --git a/src/main.rs b/src/main.rs
index 6edc099..78dd56b 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -9,6 +9,7 @@ use std::process::ExitCode;
use anyhow::Result;
use clap::{Parser, Subcommand};
+use gitbonsai::config::Legend;
use gitbonsai::date::Date;
use gitbonsai::{
Bonsai, Config, Error, Snapshot, Style, Theme, collect, explain, fixtures, html, output, render,
@@ -75,6 +76,10 @@ enum Command {
/// Leave every animation rule out
#[arg(long)]
no_animate: bool,
+
+ /// Override [render] legend: off, left or right
+ #[arg(long)]
+ legend: Option