Proposal: Area Charts API

[hdralexandru]

📢 Place of discussion for the Area's Chart API

See the current proposal beneath. React with 👍🏻 if you like it or with 👎🏻 if you don't.
If you 👎🏻 the API, please specify why and suggest an alternative.

The API

We are suggesting the following approach.
Most of the API is the same as in #1

LineChart

@Composable
fun LineChart(
    modifier: Modifier = Modifier,
    data: List<ChartPoint>,
    xAxisLabels: List<ValueLabel>,
    yAxisLabels: List<ValueLabel>,
    yAxisInterval: AxisInterval,
    xAxisInterval: AxisInterval,
    lineChartStyle: AreaChartDefaults.LineChartStyle = AreaChartDefaults.lineChartStyle(),
    background: List<BackgroundStyle> = listOf(),
)

data: List<CharPoint>

Unlike the case with Bar Charts, here we need to compute the value for both axis, not only the Y axis. However, the formula stays the same.

data class ChartPoint(
    val x: Float,
    val y: Float,
)

Through the class, the user will give us the values of the Point and we will use them to compute the position in our chart. Note that the points are NOT equidistant on the X axis.

lineChartStyle: AreaChartDefaults.LineChartStyle

More about this below

AreaChart

@Composable
fun AreaChart(
    modifier: Modifier = Modifier,
    data: List<ChartPoint>,
    xAxisLabels: List<ValueLabel>,
    yAxisLabels: List<ValueLabel>,
    yAxisInterval: AxisInterval,
    xAxisInterval: AxisInterval,
    areaChartStyle: AreaChartDefaults.AreaChartStyle = AreaChartDefaults.areaChartStyle(),
    background: List<BackgroundStyle> = listOf(),
    showPoints: Boolean = false,
    showLine: Boolean = false,
)

areaChartStyle: AreaChartDefaults.AreaChartStyle

More about this below

showPoints: Boolean

Whether or not to show points on the chart.

showLine: Boolean

Whether or not to show the line of the chart.
Setting to true will yield the same UI as the LineChart.

StackedAreaChart

See Stacked Area Graph for more info about StackedAreaChart

@Composable
fun StackedAreaChart(
    modifier: Modifier = Modifier,
    data: List<StackedAreaEntry>,
    xAxisLabels: List<ValueLabel>,
    yAxisLabels: List<ValueLabel>,
    yAxisInterval: AxisInterval,
    xAxisInterval: AxisInterval,
    stackedAreaChartStyle: AreaChartDefaults.StackedAreaChartStyle = AreaChartDefaults.stackedAreaChartStyle(),
    background: List<BackgroundStyle> = listOf(),
    showPoints: Boolean = false,
    showLine: Boolean = false,
    areaColor: Map<DataLabel, Brush>,
    decorationColors: Map<DataLabel, Color>,
)

data: List<StackedAreaEntry>

data class StackedAreaEntry(
    val label: DataLabel,
    val entries: List<ChartPoint>
)

The number of entries in data will represent the number of areas visible on the UI.
entries will represent the points on the UI, just like a plain AreaChart

areaColor: Map<DataLabel, Brush>

Those colours will be used for filling the area between 2 charts.

decorationColors: Map<DataLabel, Color>

Used for the graph's line, points etc.

Styling

When it comes to styling, we decided to adopt the approach used in TextStyle: have a dedicated class for styling, with an easy to use copy method.

For all 3 charts, the styling would look like this:

object AreaChartDefaults {

    data class LineChartStyle internal constructor(
        val labelStyle: TextStyle,
        val axisStyle: AxisStyle,
        val pointBrush: Brush,
        val pointRadius: Dp,
        val lineBrush: Brush,
        val lineWidth: Dp,
        val linePathEffect: PathEffect? = null
    )

    data class AreaChartStyle internal constructor(
        val labelStyle: TextStyle,
        val axisStyle: AxisStyle,
        val pointBrush: Brush,
        val pointRadius: Dp,
        val lineBrush: Brush,
        val lineWidth: Dp,
        val linePathEffect: PathEffect? = null,
        val fillStyle: Brush,
    )

    data class StackedAreaChartStyle internal constructor(
        val labelStyle: TextStyle,
        val axisStyle: AxisStyle,
        val pointRadius: Dp,
        val lineBrush: Brush,
        val lineWidth: Dp,
        val linePathEffect: PathEffect? = null,
    )

    fun lineChartStyle(
        labelStyle: TextStyle = TODO(),
        axisStyle: AxisStyle = TODO(),
        pointBrush: Brush = TODO(),
        pointRadius: Dp = TODO(),
        lineBrush: Brush = TODO(),
        lineWidth: Dp = TODO(),
        linePathEffect: PathEffect? = null
    ): LineChartStyle = TODO()

    fun areaChartStyle(
        labelStyle: TextStyle = TODO(),
        axisStyle: AxisStyle = TODO(),
        pointBrush: Brush = TODO(),
        pointRadius: Dp = TODO(),
        lineBrush: Brush = TODO(),
        lineWidth: Dp = TODO(),
        linePathEffect: PathEffect? = null,
        fillStyle: Brush = TODO(),
    ): AreaChartStyle = TODO()

    fun stackedAreaChartStyle(
        labelStyle: TextStyle = TODO(),
        axisStyle: AxisStyle = TODO(),
        pointRadius: Dp = TODO(),
        lineWidth: Dp = TODO(),
        linePathEffect: PathEffect? = null,
    ): StackedAreaChartStyle = TODO()
}

[ateslovan]

Similar to DataLabel, I'm thinking of creating a value class for the coordinates of the ChartPoint too.

[ateslovan]

We should take into account this comment here as well.