Simplified Chart components

[techniq]

This idea has been in my head for some time, but I figure it's time to formally write it down, as it would simplify the "basic" use cases (especially for exploration or quick visualizations) and enable additional use cases similar to the newly released shadcn/ui Charts. While I was initially adverse to the idea, I think creating BarChart, AreaChart, LineChart, etc will provide a lot of value, including:

• Quick exploration (<BarChart {data} />) if you align with conventions
• Good initial defaults for common chart types (setting up scales, tooltip modes, and even axis, legends, etc)
• Provide convenient ways to remove abstractions as you want (override accessors, slots, styling, etc)
• Reduce imports (d3-scale, many LayerChart components, ...)

The general idea is

<script>
  import { BarChart, ... } from 'layerchart';
</script>

<BarChart {data} x="date" y="value">
  ...
</BarChart>

is a streamlined instance of

<script>
  import { Chart, ... } from 'layerchart';
  import { scaleBand, scaleLinear } from 'd3-scale';
</script>

<Chart
  {data}
  x="date"
  xScale={scaleBand()}
  y="value"
  yScale={scaleLinear()}
  yDomain={[0, null]}
  padding={{ left: 16, bottom: 24 }}
  tooltip={{ mode: 'band' }}
>
  ...
</Chart>

Possibly also provide a default slot impl, so

<script>
  import { BarChart } from 'layerchart';
</script>

<BarChart {data} x="date" y="value" />

is a streamlined instance of

<script>
  import { Chart, Svg, Axis, Bars, Highlight, Tooltip, TooltipItem } from 'layerchart';
  import { scaleBand, scaleLinear } from 'd3-scale';
</script>

<Chart
  {data}
  x="date"
  xScale={scaleBand()}
  y="value"
  yScale={scaleLinear()}
  yDomain={[0, null]}
  padding={{ left: 16, bottom: 24 }}
  tooltip={{ mode: 'band' }}
>
  <Svg>
    <Axis placement="left" grid rule />
    <Axis placement="bottom" rule />
    <Bars radius={4} strokeWidth={1} class="fill-primary" />
    <Highlight area />
  </Svg>
  <Tooltip header={(data) => format(data.date, "eee, MMMM do")} let:data>
    <TooltipItem label="value" value={data.value} />
  </Tooltip>
</Chart>

Items to consider

• Passing additional props to scales (ex. scaleBand().padding(0.4) maybe as <BarChart bandPadding={0.4}>
• Pass $$restProps to underlying Chart such as <BarChart {data} x="date" y="value">
• Provide a default slot implementation that includes axis, tooltip, etc
• Should we support SVG only, or support Canvas when available (ex. Geo)
  • SVG only ATM, as going full Canvas (axis, etc) would require more component support that is available (focusing on marks first, so it would be blended at first now)
• Not exposing a ton of props. LayerChart's primary goal is composition / composability, and should leverage components directly instead of props with indirection
  • Exposing props to target internal components, but recommend overriding slots (named or default) as use cases become more complicated
• Simplified gradients
  • Expose marks slot for easy styling with <LinearGradient let:url> component
• Do not set explicit 0 min domain if data includes negative values
  • Handled via yBaseline
• Turn off Axis (sparkline, etc)
• Turn off Tooltip
• Support opt-in animations/tweening
  • https://www.layerchart.com/docs/examples/Area#clip_tween_on_mount
  • https://www.layerchart.com/docs/examples/Columns#tween_on_mount
• Smartly show <Rule={x}> unless xDomain does not include 0 in min/max range (same for y)
  • Does this work for all use cases?
• Turn off bottom rule if xDomain includes negative values
• Disable tooltips/highlight? (ex. <AreaChart tooltip={false}>)
• Opt into adding a <Legend> (ex. <Chart legend={....}>)

Initial charts to support

• BarChart
  • default scales: scaleBand / scaleLinear
  • tooltip: band or bisect-x / bisect-y
  • vertical and horizontal orientation
  • examples
    • vertical
    • horizontal
    • series (overlap)
    • series (diverging)
    • series (stack)
    • series (group)
    • series (group and stack)
    • labels
    • sparkbar
    • canvas
• LineChart
  • default scales: scaleTime or scaleLinear / scaleLinear
  • tooltip: bisect-x
  • examples
    • series
    • series (highlight on hover)
    • labels
    • gradient (encoding)
    • gradient (threshold)
    • radial (radar)
    • radial (series)
    • sparkline
    • canvas
• AreaChart
  • default scales: scaleTime or scaleLinear / scaleLinear
  • tooltip: bisect-x
  • examples
    • gradient
    • threshold gradient
    • series
    • series (highlight on hover)
    • series (stack)
    • labels
    • radial
    • sparkline
    • canvas
    • tween
• ScatterChart
  • default scales: scaleLinear
  • tooltip: voronoi or quadtree
  • examples
    • series
    • radius
    • canvas
• PieChart
  • tooltip: manual (path)
  • examples (Pie / Arc)
    • arc
    • donut
    • separate tracks (concentric)
    • series (concentric with different total/max)
    • segmented
    • gradient
    • labels
    • tween
    • canvas
• Other integrations
  • Legend
  • Brush
  • TransformContext
• More?
  • Threshold
  • Hierarchy
  • Force
  • Geo

Related: #68

[mhkeller]

Really neat to see this idea coming together. It's been on my mind, too, over the years. One idea I was kicking around was a way to have both a simplified API and allow for ad hoc customization as discussed here mhkeller/layercake#174. I haven't done a proof of concept with the snippets API but it could be a neat way to swap out the default components with your own once your charts gets more customized.

[techniq]

Really neat to see this idea coming together. It's been on my mind, too, over the years. One idea I was kicking around was a way to have both a simplified API and allow for ad hoc customization as discussed here mhkeller/layercake#174. I haven't done a proof of concept with the snippets API but it could be a neat way to swap out the default components with your own once your charts gets more customized.

@mhkeller That's the goal with these simplified charts 😁 - Provide a great default/initial experience for common use cases, but also provide various extension points as you need to customize:

• Prop overrides for the top-level Chart instance and the inner chart components such as Axis
• Named slots for granular component overrides
• Default slot for full chart control (but still a more simplified setup)

Basically get you setup quickly, but get out of your way.

These simplified charts also provide better integration between components (ex. series prop which adds the additional marks, tooltip items with colors, etc)

Some of the extension/overrides available thus far:

Chart props

Pass any prop to the simplified chart instance that passes down to the underlying <Chart> instance

<AreaChart padding={{ left: 24, bottom: 16 }} ... />

Inner component props (example)

Provide additional props (or overrides) on the inner components without requiring a full component overrides.

<BarChart
  props={{
    axisLeft: { rule: false },
    axisBottom: { format: (value) => format(Math.abs(value), "metric") },
}}>

Named slots

More granular overrides via named slots (such as marks, axis, tooltip, etc)

• Add gradient to Area, but keep default axis, tooltip, etc (example)

<AreaChart data={dateSeriesData} x="date" y="value">
  <svelte:fragment slot="marks">
    <LinearGradient class="from-primary/50 to-primary/0" vertical let:url>
      <Area line={{ class: "stroke-2 stroke-primary" }} fill={url} />
    </LinearGradient>
  </svelte:fragment>
</AreaChart>

• Override just the Tooltip display (example)

<ScatterChart {data} x="x" y="y">
  <svelte:fragment slot="tooltip" let:x let:y let:padding let:height>
    <Tooltip.Root
      x={padding.left}
      y="data"
      anchor="right"
      contained={false}
      class="text-[10px] font-semibold text-primary bg-surface-100 mr-[2px] px-1 py-[2px] border border-primary rounded whitespace-nowrap"
      let:data
    >
      {format(y(data), "integer")}
    </Tooltip.Root>

    <Tooltip.Root
      x="data"
      y={height}
      anchor="top"
      class="text-[10px] font-semibold text-primary bg-surface-100 mt-[1px] px-2 py-[1px] border border-primary rounded whitespace-nowrap"
      contained={false}
      let:data
    >
      {format(x(data), "integer")}
    </Tooltip.Root>
  </svelte:fragment>
</ScatterChart>

Opt into some features (labels, etc) (example)

<BarChart data={dateSeriesData} x="date" y="value" labels />

Full custom chart

Customize all components used, but still include all the benefits of default chart type instance (domains, tooltip mode, series support, etc) and simplified imports (ex. no d3-scale, for example)

<AreaChart data={dateSeriesData} x="date" y="value" let:x let:y>
  <Svg>
    <Axis placement="left" grid rule />
    <Axis
      placement="bottom"
      format={(d) => format(d, PeriodType.Day, { variant: "short" })}
      rule
    />
    <Area
      line={{ class: "stroke-2 stroke-primary" }}
      class="fill-primary/30"
    />
    <Highlight points lines />
  </Svg>

  <Tooltip.Root let:data>
    <Tooltip.Header>{format(x(data), PeriodType.DayTime)}</Tooltip.Header>
    <Tooltip.List>
      <Tooltip.Item label="value" value={y(data)} />
    </Tooltip.List>
  </Tooltip.Root>
</AreaChart>

I'm still feeling this out, but take a look at AreaChart, BarChart, LineChart, PieChart, and ScatterChart for examples of many of these concepts.

I'm currently working on overhauling how stacks (BarChart, AreaChart) and groups (BarChart) are implemented (eyeing derived scales PR for groups 😁). Stacks along with a few additional use cases are likely what will be included in the first release, and will consider adding more chart types (hierarchy, force, geo, etc) over time.