@flourish/facets - npm Package Compare versions

Comparing version 2.0.0-prerelease.2 to 2.0.0-prerelease.4

package.json

 {
   "name": "@flourish/facets",
-  "version": "2.0.0-prerelease.2",
-  "description": "Create grids of things",
+  "version": "2.0.0-prerelease.4",
+  "description": "Create small-multiple grid layouts",
   "main": "facets.js",
@@ -6,0 +6,0 @@ "module": "src/index.js",

README.md

 # Flourish facets module
 
-Create grids of things, such as charts and maps
+A Flourish module for creating grid layouts, typically used for “small multiples” visualizations.
+
+## How to install
+
+`npm install -s @flourish/facets`
+
+Add a `facets` object to your template state, e.g.:
+
+``` js
+export var state = {
+	facets: {},
+	...
+}
+```
+
+Next import the settings into `template.yml` settings, e.g.:
+
+```yml
+- Grid of chart
+- property: facets
+  import: "@flourish/facets"
+```
+
+## How to use
+
+Initialize the layout (only once) outside any function with a _facet settings object_:
+
+``` js
+import initFacets from "@flourish/facets";
+var facets = initLayout(state.facets);
+```
+
+Next, in the `draw` function, append the facets grids to an SVG group element in your visualization, e.g.:
+
+```js
+facets.appendTo(my_svg_g_element);
+```
+
+## API reference
+
+The `facets` object has a number of methods:
+
+### Getter/setters
+
+### `facets.height(number)`
+When called with `number`, sets the overall height of the facet grid in pixels (clearing any value passed in by `facets.facetHeight` or `facets.facetAspect`) and returns the instance. When called without an argument returns the computed height of the grid.
+
+### Setters
+
+### `facets.appendTo(container)`
+Appends the SVG group element containing the facet groups to the specified `container` (which should be an SVG group element), and returns the instance.
+
+### `facets.data(data, accessor)`
+Sets the facets in the grid and returns the instance. `data` should be an array of strings containing the names of the facets. Alternatively, `data` can be a richer array, in which case also provide an `accessor` function that takes each entry as an argument and returns the name.
+
+### `facets.width(number)`
+Sets the overall width of the facet grid, and returns the instance.
+
+### `facets.facetHeight(number)`
+When called with `number`, sets the height of each facet in the grid in pixels (clearing any value passed in by `facets.height` or `facets.facetAspect`) and returns the instance. The specified height excludes the facet header, if present.
+
+### `facetAspect(number, padding)`
+When called with `number`, sets the aspect ratio of each facet in the grid (clearing any value passed in by `facets.height` or `facets.facetAspect`) and returns the instance. The aspect applies to the main part of the facet (i.e. excluding the header, if present) and should be in the format where 1 is square. The optional `padding` object, if provided, can contain any combination of `top`, `right`, `left` and `right` properties. These will be taken account of when setting the aspect ratio - useful for example to set a square plot with uneven margins around the edge for the axes.
+
+### `facets.duration(number)`
+Sets the duration, in milliseconds, of the animations in the update function, and returns the instance.
+
+### `facets.autoTitleAlign(callback)`
+Sets how the titles should be aligned when the relevant setting is set to “Auto”, and returns the instance. `callback` is a function that should return "left", "center" or "right".
+
+### `facets.titleColor(function)`
+By default facet titles are all the same and can be specified in the settings. This methods allows you to change that by passing in a `function` that takes the facet name as an argument and returns a color. A typical use case is to pass in the `getColor` function from an instance of `@flourish/colors`.
+
+### `facets.axisSpaceTop(number)`, `facets.axisSpaceBottom(number)`, `facets.axisSpaceLeft(number)`, `facets.axisSpaceRight(number)`
+Creates optional blank space around the grid, typically used to house axes that area shared across whole rows/columns of facets, and returns the instance. `number` is the size in pixels. The margins default to zero.
+
+### `facets.debug(debug)`
+If `debug` is truthy, adds fills to the facets to make it possible to see the grid, and returns the instance.
+
+### `facets.update(callback)`
+Renders/updates the facet grid based on the current state, and returns the instance.
+
+### Getters
+
+### `facets.numColumns()`
+Returns the number of columns in the grid.
+
+### `facets.numRows()`
+Returns the number of rows in the grid.
+
+### `facets.facets()`
+Returns an array of objects representing each facet.
+
+### `facets.facetWidth()`
+Returns the width of the facets in the grid.
+
+### `facets.getFacet(name)`
+Returns an object representing the facet with the specified `name`.
+
+### `facets.isRagged()`
+Returns `false` if the grid is "complete" (i.e. the last row has an cell for every column). Otherwise returns `true`.

RELEASE_NOTES.md

@@ -11,3 +11,3 @@ # 2.0.0
 * Add setting for title size unit
+* Add README
 
-

src/index.js

@@ -75,2 +75,3 @@ import { select } from "d3-selection";
 	container.appendChild(this._container);
+	return this;
 };
@@ -123,3 +124,2 @@
 Facets.prototype.axisSpaceTop = function(height) {
-	if (typeof height == "undefined") return this._axis_space_top;
 	this._axis_space_top = height;
@@ -130,3 +130,2 @@ return this;
 Facets.prototype.axisSpaceBottom = function(height) {
-	if (typeof height == "undefined") return this._axis_space_bottom;
 	this._axis_space_bottom = height;
@@ -137,3 +136,2 @@ return this;
 Facets.prototype.axisSpaceLeft = function(width) {
-	if (typeof width == "undefined") return this._axis_space_left;
 	this._axis_space_left = width;
@@ -144,3 +142,2 @@ return this;
 Facets.prototype.axisSpaceRight = function(width) {
-	if (typeof width == "undefined") return this._axis_space_right;
 	this._axis_space_right = width;
@@ -241,3 +238,4 @@ return this;
 	// Calculate the height of each facet (and its title)
-	var title_h = show_titles ? getFontSize(state.title_size + state.title_padding_top + state.title_padding_bottom) : 0,
+	var title_size = state.title_unit == "rem" ? remToPx(state.title_size) : (state.title_size * facet_w/15),
+	    title_h = show_titles ? title_size * (1 + state.title_padding_top + state.title_padding_bottom) : 0,
 	    facet_h = 100; // Fallback in case height and aspect are both null
@@ -280,5 +278,4 @@ if (grid_height != null) {
 
-	var title_bg_padding_px = state.title_bg == "none" ? 0 : getFontSize(state.title_bg_padding),
-	    title_size_px = getFontSize(state.title_size),
-	    facet_title_dy_px = getFontSize(state.title_size * 0.8 + state.title_padding_top);
+	var title_bg_padding_px = state.title_bg == "none" ? 0 : title_size * state.title_bg_padding,
+	    title_dy_px = (title_size * 0.8) + (title_size * state.title_padding_top);
 		// 0.8 is about right with most fonts to vertically centre-align the
@@ -292,7 +289,7 @@ // ascenders and descenders inside the background
 		.text(function(d) { return d; })
-		.attr("font-size", title_size_px)
+		.attr("font-size", title_size)
 		.attr("font-weight", state.title_weight)
 		.attr("fill", facetTitleColor)
 		.attr("dx", title_align == "center" ? 0 : title_bg_padding_px)
-		.attr("dy", facet_title_dy_px)
+		.attr("dy", title_dy_px)
 		.each(setWidthOfFacetTitle)
@@ -336,6 +333,6 @@ .attr("x", facetTitleX)
 		.text(function(d) { return d; })
-		.attr("font-size", title_size_px)
+		.attr("font-size", title_size)
 		.attr("font-weight", state.title_weight)
 		.attr("dx", title_align == "center" ? 0 : title_bg_padding_px)
-		.attr("dy", facet_title_dy_px)
+		.attr("dy", title_dy_px)
 		.each(setWidthOfFacetTitle)
@@ -465,10 +462,6 @@ .transition().duration(duration)
 		    current_font_size = parseFloat(this.getAttribute("font-size")),
-		    target_font_size = getFontSize(state.title_size);
+		    target_font_size = title_size;
 		this.parentNode.__title_width = current_text_width * target_font_size/current_font_size;
 	}
 
-	function getFontSize(size) {
-		return size * (state.title_unit == "rem" ? remToPx(size) : facet_w/15);
-	}
-
 	// Finally, store the updated facet_inner data
@@ -475,0 +468,0 @@ this._facets = facets_update.select(".fl-facet-primary").nodes().map(function(d) { return d.__facet_inner__; });

No alert changes

Improved metrics

Total package byte prevSize

114599

increased by3.22%

Number of lines in readme file

103

increased by2475%

Worsened metrics

Lines of code

3044

decreased by-0.39%

No dependency changes