@windborne/grapher 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windborne/grapher",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Graphing library",
   "main": "bundle.js",
   "publishConfig": {},

package/readme.md

@@ -15,31 +15,11 @@ You _shouldn't_ use this package if:
  - You don't want to add a react dependency (though the rendering engine may be used without react). 
  - Asset size is a big concern. Despite not having dependencies, this is a relatively heavy engine compared to alternatives.
 
-## As a user
-
-### Range selection
-
-### Axes
-
-### Tooltips
-
-### Options
-Percentile
-
-Auto-scale Y
-
-## As a developer
+## As a developer importing this package
 
 ### Installing
 
-The package is hosted on github, so things are marginally more tricky than usual.
-Add an .npmrc with the following contents:
-```
-@windborne:registry=https://npm.pkg.github.com
-registry=https://registry.npmjs.org
-```
-
-Then, `npm install @windborne/grapher`.
+`npm install @windborne/grapher`.
 
 It also requires React version 16.8 or greater as a peer dependency
 
@@ -65,60 +45,257 @@ You can find a full list in the package.json devDependencies, but they can be su
  - React and babel (include @babel/polyfill, @babel/preset-react, etc). You likely already have this in your project
  - Sass support (eg node-sass, sass-loader)
  - Webgl loader (webpack-glsl-loader)
- 
-### props
-Like any react component, grapher is primarily configured via props.
-Refer to the grapher proptypes for information
 
-**series**. This sets the data for the graph and is the only property that is truly required.
-See passing in data section for more details.
+# Grapher Component
+
+## Props
+Like any React component, Grapher is primarily configured via props.
+Refer to the Grapher PropTypes for complete type information.
+
+### Core Props
+
+**series** (required)
+This sets the data for the graph and is the only property that is truly required.
+See "Series" section for more details.
 
-**webgl**. If true, will render with webgl rather than a 2d context. 
+**webgl**
+If true, will render with WebGL rather than a 2D context.
 This is more performant, but uses more resources.
 
-**requireWASM**. If true, will wait until the WASM extensions are ready before it renders.
+**requireWASM**
+If true, will wait until the WASM extensions are ready before it renders.
 This can be useful when your app has expensive initialization.
 
-**onAxisChange**. If passed in, this function will be called every time the axes change.
+### Series Format
+The `series` prop requires an array of objects, where each object represents a data series with the following properties:
+
+- **data** (required): The actual data points (see Data Formats below)
+- **type**: Data type or 'infer' to automatically detect
+- **xKey**: Property name for x-values when using object data
+- **yKey**: Property name for y-values when using object data
+- **xUnixDates**: Whether x-values are Unix timestamps (boolean)
+- **color**: Series color (string or number)
+- **name**: Series name for display in legend
+- **xLabel**: Label for x-axis
+- **yLabel**: Label for y-axis
+- **rendering**: Visual representation ('line', 'bar', or 'area', defaults to 'line')
+- **ignoreDiscontinuities**: Whether to connect points across gaps (boolean)
+- **dashed**: Whether to use dashed lines (boolean)
+- **dashPattern**: Array defining dash pattern (array of numbers)
+- **width**: Line width (number)
+- **axis**: Axis specification for the series (string or object)
+- **rangeSelectorWidth**: Width of the range selector for this series (number)
+- **expandYWith**: Values to include when calculating y-axis range (array of numbers)
+- **defaultAlwaysTooltipped**: Whether to always show tooltip for this series (boolean)
+- **square**: Whether to render the series with square points (boolean)
+- **shiftXBy**: Value to shift x-coordinates by (number)
+- **graph**: Affects which graph this series belongs to in multigrapher (number)
+- **background**: Background configuration (object)
+- **hideFromKey**: Whether to hide this series from the legend (boolean)
+- **showIndividualPoints**: Whether to show individual data points (boolean)
+- **negativeColor**: Color for negative values
+- **gradient**: Gradient configuration, only applies to area rendering (array)
+- **zeroLineWidth**: Width of the zero line, only applies to bar and area rendering (number)
+- **zeroLineColor**: Color of the zero line, only applies to bar and area rendering (string)
+- **pointRadius**: Radius of points, only applies to area rendering (number)
+- **tooltipWidth**: Expected width of the tooltip (number). Will make the tooltip switch sides when this width plus the tooltip left position is greater than the graph width.
+
+#### Series Data Formats
+Grapher supports multiple data formats within a series:
+
+1. **Array of y-values**: Simple array where index is used as x-value
+2. **Array of [x,y] tuples**: Each point defined as [x, y] pair
+3. **Array of objects**: Objects with properties for x and y values (as per the xKey and yKey properties)
+4. **Observable**: Object with an observe method, which may emit tuples or objects
+5. **Generator function**: Function that generates an array data points as a function of zoom
+
+### Event Handlers
+
+**onAxisChange**
+If passed in, this function will be called every time the axes change.
 It will be called with an array of objects, where each object is a single series object with the `axis`
 property set to {left, right}-{index}. This can be useful for saving state between reloads.
 
-**onRenderTime**. If passed in, this function will be called every time the grapher renders.
+**onRenderTime**
+If passed in, this function will be called every time the grapher renders.
 It will be called with diagnostic information about how long rendering took.
 
-**timingFrameCount**. This will set the number of frames for when the state controller's 
-`averageLoopTime` method is called.
+**onPointDrag**
+Callback function that fires when draggable points are moved.
 
-**theme**. Sets the theme of grapher to either day or night. 
-You can also override any css property directly in a stylesheet.
+**onDraggablePointsDoubleClick**
+Callback function that fires when draggable points are double-clicked.
 
-**bodyHeight**. Sets the height of the graph body (ie excluding range graph, series controls, etc).
+**timingFrameCount**
+Sets the number of frames for when the state controller's `averageLoopTime` method is called.
 
-**height**. Sets the height of the entire graph.
+### Appearance
 
-**width**. Sets the width of the graph.
+**theme**
+Sets the theme of grapher to either 'day', 'night', or 'export'.
+You can also override any CSS property directly in a stylesheet.
 
-**showAxes**. Whether to show the axes on the graph.
+**title**
+Sets the title text for the graph.
 
-**showRangeGraph**. Whether to show the smaller range graph below the main graph.
+**fullscreen**
+If true, displays the graph in fullscreen mode.
 
-**showRangeSelectors**. Whether to show the top bar with range selection (eg last day button) and other options.
+**bodyHeight**
+Sets the height of the graph body (i.e., excluding range graph, series controls, etc.).
 
-**showSeriesKey**. Whether to show the key of which series have which colors.
+**height**
+Sets the height of the entire graph.
 
-**showGrid**
+**width**
+Sets the width of the graph.
+
+### Display Options
+
+**showAxes**
+Whether to show the axes on the graph.
+
+**showRangeGraph**
+Whether to show the smaller range graph below the main graph.
+
+**showRangeSelectors**
+Whether to show the top bar with range selection (e.g., "last day" button) and other options.
+
+**showSeriesKey**
+Whether to show the key of which series have which colors.
 
 **showTooltips**
+Whether to display tooltips when hovering over data points.
 
-**boundsSelectionEnabled**
+**showGrid**
+Whether to show grid lines on the graph.
+
+**showAxisColors**
+Whether to color-code axes based on the series they represent.
+
+**bigLabels**
+If true, uses larger text for labels.
+
+**xTickUnit**
+Specifies the unit for x-axis ticks. Currently supports 'year'.
+
+**xAxisIntegersOnly**
+If true, only displays integer values on the x-axis.
+
+**clockStyle**
+Format for displaying time, either '12h' or '24h'.
+
+**timeZone**
+Time zone for date/time display. Can be 'local', 'utc', or a full timezone string.
+
+**markRangeGraphDates**
+Whether to mark significant dates on the range graph.
 
 **tooltipOptions**
+Configures tooltip appearance and behavior with properties including:
+- `includeSeriesLabel`: Whether to show series name in tooltip
+- `includeXLabel`: Whether to show x-axis label in tooltip
+- `includeYLabel`: Whether to show y-axis label in tooltip
+- `includeXValue`: Whether to show x-axis value in tooltip
+- `includeYValue`: Whether to show y-axis value in tooltip
+- `floating`: Whether tooltip floats or is fixed position
+- `alwaysFixedPosition`: Forces tooltip to always use fixed position
+- `floatPosition`: Placement of floating tooltip ('top' or 'bottom')
+- `floatDelta`: Pixel offset for floating tooltip positioning
+- `savingDisabled`: Prevents tooltip settings from being saved
+- `customTooltip`: A react component to use as a custom tooltip. See [examples/custom_tooltips_graph.js](examples/custom_tooltips_graph.js) for an example. If used in conjunction with `combineTooltips`, see [examples/combined_tooltips_graph.js](examples/combined_tooltips_graph.js) 
+- `combineTooltips`: If true, combines multiple tooltips into one when multiple series are shown. Can alternatively be set to a threshold in pixels for how close values need to be in order to be combined.
+
+**customBoundsSelectors**
+Array of custom range selector objects with properties:
+- `label`: Display text for the selector
+- `calculator`: Function that determines the bounds
+- `datesOnly`: If true, only works with date values
+
+**customBoundsSelectorsOnly**
+If true, only displays custom bounds selectors.
+
+**defaultBoundsCalculator**
+String identifier for the default bounds calculator to use.
+
+**defaultShowOptions**
+Default visibility of the options panel.
+
+**defaultShowIndividualPoints**
+Default setting for showing individual data points.
+
+**defaultShowSidebar**
+Default visibility of the sidebar.
+
+**defaultShowAnnotations**
+Default visibility of annotations.
+
+**defaultLineWidth**
+Default width of the lines in the graph.
+
+**boundsSelectionEnabled**
+Whether to enable the bounds selection feature.
+
+**sidebarEnabled**
+Whether to enable the sidebar.
 
-**customBoundsSelectors** 
+**percentile**
+Sets the percentile value for calculations.
 
-### Usage from ruby
 
-### Usage from python
+### Advanced Features
+
+**tooltipOptions**
+Configures tooltip appearance and behavior with properties including:
+- `includeSeriesLabel`: Whether to show series name in tooltip
+- `includeXLabel`: Whether to show x-axis label in tooltip
+- `includeYLabel`: Whether to show y-axis label in tooltip
+- `includeXValue`: Whether to show x-axis value in tooltip
+- `includeYValue`: Whether to show y-axis value in tooltip
+- `floating`: Whether tooltip floats or is fixed position
+- `alwaysFixedPosition`: Forces tooltip to always use fixed position
+- `floatPosition`: Placement of floating tooltip ('top' or 'bottom')
+- `floatDelta`: Pixel offset for floating tooltip positioning
+- `savingDisabled`: Prevents tooltip settings from being saved
+
+**customBoundsSelectors**
+Array of custom range selector objects with properties:
+- `label`: Display text for the selector
+- `calculator`: Function that determines the bounds
+- `datesOnly`: If true, only works with date values
+
+**customBoundsSelectorsOnly**
+If true, only displays custom bounds selectors.
+
+**defaultBoundsCalculator**
+String identifier for the default bounds calculator to use.
+
+**annotations**
+Array of annotation objects to display on the graph with properties:
+- `x`: Position on x-axis (string, number, or Date) where annotation should appear
+- `xEnd`: Optional end position for range annotations
+- `series`: Optional array of series names the annotation applies to
+- `content`: Text content of the annotation
+
+**draggablePoints**
+Array of interactive point objects with properties:
+- `x`: X-coordinate position
+- `y`: Y-coordinate position
+- `radius`: Optional size of the point
+- `fillColor`: Optional interior color
+- `strokeColor`: Optional outline color
+- `strokeWidth`: Optional outline width
+- `onClick`: Optional click handler function
+- `onDoubleClick`: Optional double-click handler function
+
+**verticalLines**
+Array of vertical line objects to display on the graph with properties:
+- `x`: X-coordinate position where the line should appear
+- `color`: Optional line color
+- `width`: Optional line width
+- `markTop`: Whether to add a marker at the top of the line
+- `style`: Optional styling object for the line
+- `markerStyle`: Optional styling object for the marker
 
 ## Developing
 Other than an `npm install`, you'll need to install rust and [wasm-pack](https://rustwasm.github.io/wasm-pack/installer/).

package/src/components/context_menu.js

@@ -41,7 +41,7 @@ export default class ContextMenu extends React.PureComponent {
 
         const style = { left: x, top: y, width: '150px'};
         
-        if (!showing || !value || value.toLocaleString() === 'Invalid Date') {
+        if (!showing || !value || value.toLocaleString() === 'Invalid Date' || isNaN(x) || isNaN(y)) {
             return null;
         }
 
@@ -61,9 +61,9 @@ export default class ContextMenu extends React.PureComponent {
 
 ContextMenu.propTypes = {
     contextMenu: PropTypes.shape({
-        x: PropTypes.number.isRequired,
-        y: PropTypes.number.isRequired,
-        showing: PropTypes.bool.isRequired,
+        x: PropTypes.number,
+        y: PropTypes.number,
+        showing: PropTypes.bool,
         value: PropTypes.oneOfType([
             PropTypes.instanceOf(Date),
             PropTypes.number,

package/src/components/tooltip.js

@@ -25,6 +25,10 @@ function getYLabelContent({ yLabel, y, fullYPrecision}) {
         }
     }
 
+    if (typeof yLabel === 'object') {
+        return formatY(y);
+    }
+
     return yLabel || formatY(y);
 }
 
@@ -73,7 +77,8 @@ TooltipLabel.propTypes = {
 export default class Tooltip extends React.PureComponent {
 
     render() {
-        let height = 12*3 + 6;
+        const textPadding = 3;
+        let height = 12*3 + 2*textPadding;
 
         if (!this.props.includeSeriesLabel) {
             height -= 12;
@@ -91,7 +96,7 @@ export default class Tooltip extends React.PureComponent {
         const halfHeight = height/2;
         const caretPadding = 4;
 
-        const textTop = -halfHeight + 3;
+        const textTop = -halfHeight + textPadding;
 
         const formatXOptions = {
             clockStyle: this.props.clockStyle,
@@ -107,76 +112,187 @@ export default class Tooltip extends React.PureComponent {
             formatXOptions
         };
 
-        return (
-            <div className="grapher-tooltip">
-                <svg>
-                    {
-                        this.props.tooltips.map(({ x, y, color, pixelY, pixelX, series, index, xLabel, yLabel, fullYPrecision }, i) => {
-                            const axisLabel = (series.name || series.yKey || index).toString();
-                            const width = Math.max(axisLabel.length, (xLabel || formatX(x, formatXOptions)).length + 4, getYLabelContent({ yLabel, y, fullYPrecision}).length + 4) * 7.5;
+        const preparedTooltips = this.props.tooltips.map((tooltip) => {
+            const { x, y, pixelY, pixelX, series, index, xLabel, yLabel, fullYPrecision } = tooltip;
 
-                            let fixedPosition = this.props.elementWidth < (width + 2*caretSize + 2*caretPadding);
+            const axisLabel = (series.name || series.yKey || index).toString();
+            let width = Math.max(axisLabel.length, (xLabel || formatX(x, formatXOptions)).length + 4, getYLabelContent({ yLabel, y, fullYPrecision}).length + 4) * 7.5;
+            if (series.tooltipWidth) {
+                width = series.tooltipWidth;
+            }
 
-                            let multiplier = 1;
-                            if (pixelX >= this.props.elementWidth - (width + 2*caretSize + caretPadding)) {
-                                multiplier = -1;
-                            }
+            let fixedPosition = this.props.elementWidth < (width + 2*caretSize + 2*caretPadding);
 
-                            if (pixelX < width + 2*caretSize + caretPadding && multiplier === -1) {
-                                fixedPosition = true;
-                            }
+            let multiplier = 1;
+            if (pixelX >= this.props.elementWidth - (width + 2*caretSize + caretPadding)) {
+                multiplier = -1;
+            }
 
-                            if (y === null) {
-                                fixedPosition = true;
-                            }
+            if (pixelX < width + 2*caretSize + caretPadding && multiplier === -1) {
+                fixedPosition = true;
+            }
 
-                            let textLeft = caretSize + caretPadding;
-                            if (multiplier < 0) {
-                                textLeft = -width - textLeft;
-                            } else {
-                                textLeft += 6;
-                            }
+            if (y === null) {
+                fixedPosition = true;
+            }
 
-                            if (!isFinite(pixelX)) {
-                                return null;
-                            }
+            if (this.props.alwaysFixedPosition) {
+                fixedPosition = true;
+            }
 
-                            const transform = `translate(${pixelX},${pixelY})`;
+            let textLeft = caretSize + caretPadding;
+            if (multiplier < 0) {
+                textLeft = -width - textLeft;
+            } else {
+                textLeft += 6;
+            }
 
-                            const commonLabelProps = {
-                                fullYPrecision: fullYPrecision || this.props.maxPrecision,
-                                x,
-                                y,
-                                axisLabel,
-                                xLabel,
-                                yLabel,
-                                ...passThroughProps
-                            };
+            if (!isFinite(pixelX)) {
+                return null;
+            }
 
-                            // display in a fixed position if not wide enough
-                            if (fixedPosition || this.props.alwaysFixedPosition) {
-                                textLeft = 6;
+            const transform = `translate(${pixelX},${pixelY})`;
 
-                                let baseLeft = this.props.elementWidth/2 - width/2;
+            const commonLabelProps = {
+                fullYPrecision: fullYPrecision || this.props.maxPrecision,
+                x,
+                y,
+                axisLabel,
+                xLabel,
+                yLabel,
+                ...passThroughProps
+            };
 
-                                if (width > this.props.elementWidth && !this.props.floating) {
-                                    baseLeft -= Y_AXIS_WIDTH*this.props.axisCount/2;
-                                }
+            let yTranslation = 0;
+            let baseLeft;
 
-                                let yTranslation = 18;
+            if (fixedPosition) {
+                textLeft = 6;
 
-                                if (this.props.floating) {
-                                    if (this.props.floatPosition === 'bottom') {
-                                        yTranslation = this.props.elementHeight + halfHeight + 4;
-                                    } else {
-                                        yTranslation = -height;
-                                    }
+                baseLeft = this.props.elementWidth / 2 - width / 2;
 
-                                    if (this.props.floatDelta) {
-                                        yTranslation += this.props.floatDelta;
-                                    }
-                                }
+                if (width > this.props.elementWidth && !this.props.floating) {
+                    baseLeft -= Y_AXIS_WIDTH * this.props.axisCount / 2;
+                }
+
+                yTranslation = 18;
+
+                if (this.props.floating) {
+                    if (this.props.floatPosition === 'bottom') {
+                        yTranslation = this.props.elementHeight + halfHeight + 4;
+                    } else {
+                        yTranslation = -height;
+                    }
+
+                    if (this.props.floatDelta) {
+                        yTranslation += this.props.floatDelta;
+                    }
+                }
+            }
+
+            return {
+                ...tooltip,
+                label: axisLabel,
+                indexInAxis: series.axis.series.indexOf(series),
+                axisLabel,
+                width,
+                fixedPosition,
+                multiplier,
+                textLeft,
+                transform,
+                commonLabelProps,
+                textTop,
+                height,
+                caretSize,
+                halfHeight,
+                caretPadding,
+                yTranslation,
+                baseLeft
+            };
+        });
+
+        const CustomTooltipComponent = this.props.customTooltip;
+
+        let groupedTooltips;
+        if (this.props.combineTooltips) {
+            let combinationThreshold = 50; // in px how close tooltips should be to combine
+            if (typeof this.props.combineTooltips === 'number') {
+                combinationThreshold = this.props.combineTooltips;
+            }
 
+            groupedTooltips = [];
+
+            for (let tooltip of preparedTooltips) {
+                let added = false;
+                for (let group of groupedTooltips) {
+                    if (Math.abs(group.pixelX - tooltip.pixelX) <= combinationThreshold) {
+                        group.tooltips.push(tooltip);
+                        if (tooltip.pixelX > group.pixelX) {
+                            group.pixelX = tooltip.pixelX;
+                            group.multiplier = tooltip.multiplier;
+                        }
+
+                        if (tooltip.pixelY < group.pixelY) {
+                            group.pixelY = tooltip.pixelY;
+                        }
+
+                        added = true;
+                        break;
+                    }
+                }
+
+                if (!added) {
+                    groupedTooltips.push({
+                        pixelX: tooltip.pixelX,
+                        pixelY: tooltip.pixelY,
+                        multiplier: tooltip.multiplier,
+                        tooltips: [tooltip]
+                    });
+                }
+            }
+
+            for (let group of groupedTooltips) {
+                let totalHeight = 0;
+                let maxWidth = 0;
+
+                // sort by indexInAxis
+                group.tooltips.sort((a, b) => a.indexInAxis - b.indexInAxis);
+
+                for (let i = 0; i < group.tooltips.length; i++) {
+                    group.tooltips[i].textTop = totalHeight;
+                    totalHeight += group.tooltips[i].height;
+                    maxWidth = Math.max(maxWidth, group.tooltips[i].width);
+                }
+
+                for (let i = 0; i < group.tooltips.length; i++) {
+                    group.tooltips[i].textTop -= totalHeight/2;
+                    group.tooltips[i].textTop += textPadding;
+                }
+
+                group.height = totalHeight;
+                group.halfHeight = totalHeight / 2;
+                group.caretSize = caretSize;
+                group.width = maxWidth;
+            }
+        }
+
+        return (
+            <div className="grapher-tooltip">
+                <svg>
+                    {
+                        preparedTooltips.map((tooltip, i) => {
+                            const { color, fixedPosition, width, transform, baseLeft, commonLabelProps, yTranslation, multiplier, textLeft, textTop } = tooltip;
+
+                            if (this.props.customTooltip || groupedTooltips) {
+                                return (
+                                    <g key={i} transform={transform} className="tooltip-item">
+                                        <circle r={4} fill={color}/>
+                                    </g>
+                                );
+                            }
+
+                            // display in a fixed position if not wide enough
+                            if (fixedPosition) {
                                 return (
                                     <g key={i} className="tooltip-item tooltip-item-fixed">
                                         <circle r={4} fill={color} transform={transform} />
@@ -207,7 +323,40 @@ export default class Tooltip extends React.PureComponent {
                             );
                         })
                     }
+
+                    {
+                        !this.props.customTooltip && groupedTooltips &&
+                        groupedTooltips.map(({ tooltips, pixelX, pixelY, halfHeight, multiplier, color, width }, i) =>
+                            <g key={i} transform={`translate(${pixelX},${pixelY})`} className="tooltip-item">
+                                <path stroke={color} d={`M${multiplier*caretPadding},0 L${multiplier*caretSize*2},-${caretSize} V-${halfHeight} h${multiplier*width} V${halfHeight} h${multiplier*-width} V${caretSize} L${multiplier*caretPadding},0`} />
+
+                                {
+                                    tooltips.map((tooltip, j) =>
+                                        <TooltipLabel
+                                            key={j}
+                                            textTop={tooltip.textTop}
+                                            textLeft={tooltip.textLeft}
+                                            {...tooltip.commonLabelProps}
+                                        />
+                                    )
+                                }
+                            </g>
+                        )
+                    }
                 </svg>
+
+                {
+                    this.props.customTooltip &&
+                    (groupedTooltips || preparedTooltips).map((tooltip, i) =>
+                        <div
+                            key={i}
+                            className="custom-tooltip-container"
+                            style={{top: tooltip.pixelY, left: tooltip.pixelX}}
+                        >
+                            <CustomTooltipComponent {...tooltip} />
+                        </div>
+                    )
+                }
             </div>
         );
     }
@@ -233,7 +382,7 @@ Tooltip.propTypes = {
         pixelY: PropTypes.number,
         color: PropTypes.string,
         xLabel: PropTypes.string,
-        yLabel: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
+        yLabel: PropTypes.any,
         fullYPrecision: PropTypes.bool
     })),
     axisCount: PropTypes.number.isRequired,