iofficeai--officecli/examples/excel/charts/charts-waterfall.md

Waterfall Charts Showcase

This demo consists of three files that work together:

• charts-waterfall.py — Python script that calls officecli commands to generate the workbook. Each chart command is shown as a copyable shell command in the comments.
• charts-waterfall.xlsx — The generated workbook with 5 sheets (1 default + 4 chart sheets, 16 charts total).
• charts-waterfall.md — This file. Maps each sheet to the features it demonstrates.

Regenerate

cd examples/excel
python3 charts-waterfall.py
# → charts-waterfall.xlsx

Chart Sheets

Sheet: 1-Waterfall Fundamentals

Four waterfall chart variants covering basic P&L, budget analysis, quarterly flow, and title styling.

# Basic P&L waterfall with increase/decrease/total colors
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop data="Start:1000,Revenue:500,Costs:-300,Tax:-100,Net:1100" \
  --prop increaseColor=70AD47 \
  --prop decreaseColor=FF0000 \
  --prop totalColor=4472C4 \
  --prop dataLabels=true

# Budget waterfall with blue/red/amber theme
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop data="Budget:5000,Sales:2000,Marketing:-800,Ops:-600,Net:5600" \
  --prop increaseColor=2E75B6 \
  --prop decreaseColor=C00000 \
  --prop totalColor=FFC000 \
  --prop legend=bottom

# Quarterly cash flow with 10 data points
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop data="Opening:3000,Q1 Sales:1200,Q1 Costs:-500,...,Closing:6000" \
  --prop increaseColor=70AD47 --prop decreaseColor=ED7D31 --prop totalColor=4472C4

# Waterfall with styled title
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop title.font=Georgia --prop title.size=16 \
  --prop title.color=1F4E79 --prop title.bold=true

Features: chartType=waterfall, data= name:value pairs (positive=increase, negative=decrease), increaseColor, decreaseColor, totalColor, dataLabels, legend=bottom, title.font/size/color/bold

Sheet: 2-Waterfall Styling

Four waterfall charts demonstrating visual styling options.

# Title with font, size, color, bold, and shadow
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop title.font=Trebuchet MS --prop title.size=18 \
  --prop title.color=833C0B --prop title.bold=true \
  --prop title.shadow=000000-3-315-2-30

# Series shadow, plot/chart fills, rounded corners
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop series.shadow=000000-4-315-2-30 \
  --prop plotFill=F0F0F0 --prop chartFill=FAFAFA \
  --prop roundedCorners=true

# Gridline color and axis font
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop gridlineColor=CCCCCC \
  --prop axisfont=10:333333:Calibri

# Chart area and plot area borders
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop chartArea.border=4472C4-2 \
  --prop plotArea.border=A5A5A5-1

Features: title.shadow, series.shadow, plotFill, chartFill, roundedCorners, gridlineColor, axisfont, chartArea.border, plotArea.border

Sheet: 3-Waterfall Labels & Axis

Four waterfall charts demonstrating data labels, axis configuration, and layout control.

# Data labels with font and number format
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop dataLabels=true \
  --prop labelFont=10:333333:true \
  --prop dataLabels.numFmt=#,##0

# Custom axis range and tick interval
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop axisMin=0 --prop axisMax=3500 --prop majorUnit=500

# Legend position and font
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop legend=right \
  --prop legendfont=10:1F4E79:Helvetica

# Manual plot area layout
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop plotArea.x=0.15 --prop plotArea.y=0.15 \
  --prop plotArea.w=0.75 --prop plotArea.h=0.70

Features: dataLabels, labelFont, dataLabels.numFmt, axisMin, axisMax, majorUnit, legend=right, legendfont, plotArea.x/y/w/h

Sheet: 4-Waterfall Advanced

Four waterfall charts demonstrating advanced features and large datasets.

# Reference line overlay
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop referenceLine=2000:Target-FF0000-dash-2

# Value axis and category axis line styling
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop axisLine=333333-2 \
  --prop catAxisLine=333333-2

# Title glow and shadow effects
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop title.glow=4472C4-8 \
  --prop title.shadow=000000-3-315-2-30

# Large dataset (12 categories) with small axis font
officecli add data.xlsx /Sheet --type chart \
  --prop chartType=waterfall \
  --prop data="Revenue:8500,COGS:-3400,...,Net Income:1050" \
  --prop dataLabels=true \
  --prop axisfont=8:333333:Calibri

Features: referenceLine, axisLine, catAxisLine, title.glow, title.shadow, large dataset (12 categories)

Property Coverage

Property	Sheet
chartType=waterfall	1, 2, 3, 4
data= (name:value pairs)	1, 2, 3, 4
increaseColor	1, 2, 3, 4
decreaseColor	1, 2, 3, 4
totalColor	1, 2, 3, 4
dataLabels	1, 3, 4
legend	1, 3
title.font/size/color/bold	1, 2
title.shadow	2, 4
title.glow	4
series.shadow	2
plotFill, chartFill	2
roundedCorners	2
gridlineColor	2
axisfont	2, 4
chartArea.border	2
plotArea.border	2
labelFont	3
dataLabels.numFmt	3
axisMin/Max, majorUnit	3
legendfont	3
plotArea.x/y/w/h	3
referenceLine	4
axisLine, catAxisLine	4

Inspect the Generated File

officecli query charts-waterfall.xlsx chart
officecli get charts-waterfall.xlsx "/1-Waterfall Fundamentals/chart[1]"