terezka / charts / Chart.Item

This is an interface for dealing with different chart items, such as bars, dots, or groups of such, like bins or stacks. It comes in handy when dealing with events:

import Chart as C
import Chart.Events as CE
import Chart.Item as CI

C.chart
  [ CE.onMouseMove OnHover (CE.getNearest CI.bars) ]
  [ C.bars [ C.bar .x [] ] data ]

Or when using functions like C.eachBar or C.eachBin:

import Chart as C
import Chart.Events as CE
import Chart.Item as CI
import Svg as S

C.chart
  [ CE.onMouseMove OnHover (CE.getNearest CI.bars) ]
  [ C.bars [ C.bar .x [] ] data
  , C.eachBar <| \plane bar ->
      [ C.label [] [ S.text (String.fromFloat (CI.getY bar)) ] (CI.getTop plane bar) ]
  ]

Single items


type alias One data x =
Internal.Item.One data x

A representation containing information about a certain item on the chart, such as a bar or a dot.

One data Bar -- representation of a single bar
One data Dot -- representation of a single dot
One data Any -- representation of either a dot or a bar

It allows us to know e.g. the exact position of the item, the color, what data it was produced from, and whether it is a representation of missing data or not.


type alias Any =
Internal.Item.Any

Information about a dot or a bar.


type alias Bar =
Internal.Svg.Bar

Information about the configuration of a bar.


type alias Dot =
Internal.Svg.Dot

Information about the configuration of a dot.

getData : One data x -> data

Get the data the item was produced from.

getX : One data x -> Basics.Float

Get the x value of the item.

getX1 : One data x -> Basics.Float

Get the x1 value of the item.

getX2 : One data x -> Basics.Float

Get the x2 value of the item.

getY : One data x -> Basics.Float

Get the y value of the item.

getName : One data x -> String

Get the name of the series which produced the item.

getColor : One data x -> String

Get the color of the item.

getSize : One data Dot -> Basics.Float

Get the size of a dot.

getTooltipValue : One data x -> String

Get the formatted y value.

isReal : One data x -> Basics.Bool

Is the item a representation of missing data? This may be the case if you used e.g. C.scatterMaybe or C.barMaybe.

isSame : One data x -> One data x -> Basics.Bool

Is this item the exact same as the other?

filter : (a -> Maybe b) -> List (One a x) -> List (One b x)

Filter for a certain data type.

Groups of items


type alias Many data x =
Internal.Many.Many (One data x)

A collection of many items.

Many data Bar -- representation of several bars
Many data Dot -- representation of several dots
Many data Any -- representation of several dos or bars

Sometimes it's neccessary to work with a group of items, rather than a single. For example, if you'd like a tooltip to show up on top of a stacked bar, it's helpful to be able to treat all the pieces of that stack at the same time.

getMembers : Many data x -> List (One data x)

Get all members of the group.

getMember : Many data x -> One data x

Get the first members of the group.

This is useful when you know all members of the group share some of the same characteristics. For example, if you have a vertical stack of bars, they will all have the same x values. If you'd like to access those x values, it doesn't matter which one you pick as they are all the same, so the first one is thus fine.

getDatas : Many data x -> List data

Get the data from each member in the group.

getOneData : Many data x -> data

Get the data from the first member in the group.

Filtering and collecting


type alias Remodel a b =
Internal.Many.Remodel a b

Remodeling offers a way to filter and group chart items. For example, if you have a variable items of type List (One Data Any), you can filter it such that it only contains bars:

CI.apply CI.bars items -- List (One Data Bar)

This is the interface used in the events api too. If you'd like to get the nearest bar on mouse move, you'd say:

CE.onMouseMove OnHovering (CE.getNearest CI.bars)

apply : Remodel a b -> List a -> List b

Apply a remodelling.

andThen : Remodel b c -> Remodel a b -> Remodel a c

Chain a remodelling.

Filters

any : Remodel (One data Any) (One data Any)

Keep anything.

dots : Remodel (One data Any) (One data Dot)

Keep only dots.

bars : Remodel (One data Any) (One data Bar)

Keep only bars.

real : Remodel (One data x) (One data x)

Remove representations of missing data.

named : List String -> Remodel (One data x) (One data x)

Keep only items coming from series with the names listed.

Collecters

bins : Remodel (One data x) (Many data x)

Group into bins. Items are in the same bin if they are produced from the same element and the same data point.

stacks : Remodel (One data x) (Many data x)

Group into bins. Items are in the same stack if they are produced from the same C.stacked property.

sameX : Remodel (One data x) (Many data x)

Group into items with the same x value.

General


type alias Item x =
Internal.Item.Rendered x

An "item" on the chart. A One Data Bar and Many Data Bar are both instances on this type, so you can use all the fuctions below on those too.

getCenter : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Point

getTop : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Point

getBottom : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Point

getLeft : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Point

getRight : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Point

getTopLeft : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Point

getTopRight : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Point

getBottomLeft : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Point

getBottomRight : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Point

getPosition : Internal.Coordinates.Plane -> Item x -> Internal.Coordinates.Position

getLimits : Item x -> Internal.Coordinates.Position

In a few cases, a rendered item's "position" and "limits" aren't the same.

In the case of a bin, the "position" is the area which the bins bars take up, not inclusing any margin which may be around them. Its "limits" include the margin.

getTooltip : Item x -> List (Html Basics.Never)

Get the default tooltip.