Add docs & examples for ordinal fit, top-level width and height.

Fix #1356

examples/specs/bar_size_default.json

@@ -0,0 +1,15 @@
+{
+  "data": {"url": "data/cars.json"},
+  "mark": "bar",
+  "encoding": {
+    "x": {
+      "field": "Origin",
+      "type": "nominal"
+    },
+    "y": {
+      "aggregate": "count",
+      "field": "*",
+      "type": "quantitative"
+    }
+  }
+}

examples/specs/bar_size_explicit.json

@@ -0,0 +1,17 @@
+{
+  "width": 120,
+  "height": 120,
+  "data": {"url": "data/cars.json"},
+  "mark": "bar",
+  "encoding": {
+    "x": {
+      "field": "Origin",
+      "type": "nominal"
+    },
+    "y": {
+      "aggregate": "count",
+      "field": "*",
+      "type": "quantitative"
+    }
+  }
+}

examples/specs/bar_size_fit.json

@@ -0,0 +1,16 @@
+{
+  "data": {"url": "data/cars.json"},
+  "mark": "bar",
+  "encoding": {
+    "x": {
+      "field": "Origin",
+      "type": "nominal",
+      "scale": {"bandSize": "fit"}
+    },
+    "y": {
+      "aggregate": "count",
+      "field": "*",
+      "type": "quantitative"
+    }
+  }
+}

site/docs/config.md

@@ -63,8 +63,8 @@ Each plot in either a single plot or a trellis plot is called a _cell_. Cell con
 
 | Property      | Type          | Description    |
 | :------------ |:-------------:| :------------- |
-| width         | Integer       | The width of the single plot or each plot in a trellis plot when the visualization has continuous x-scale. (If the plot has ordinal x-scale, the width is determined by the x-scale's [`bandSize`](scale.html#ordinal) and the cardinality of the x-scale. If the plot does not have a field on `x`, the width is derived from [scale config](#scale-config)'s  `bandSize` for all marks except `text` and from [scale config](#scale-config)'s `textBandWidth` for `text` mark.) <span class="note-line">__Default value:__ `200`</span> |
-| height        | Integer       | The height of the single plot or each plot in a trellis plot when the visualization has continuous y-scale. (If the visualization has ordinal y-scale, the height is determined by the `bandSize` and the cardinality of the y-scale. If the plot does not have a field on `y`, the height is [scale config](#scale-config)'s `bandSize`.) <span class="note-line">__Default value:__ `200`</span> |
+| width         | Integer       | The default width of the single plot or each plot in a trellis plot when the visualization has a continuous (non-ordinal) x-scale or ordinal x-scale with `bandSize` = `"fit"`. <span class="note-line">__Default value:__ `200`</span> |
+| height        | Integer       | The default height of the single plot or each plot in a trellis plot when the visualization has a continuous (non-ordinal) y-scale with `bandSize` = `"fit"`. <span class="note-line">__Default value:__ `200`</span> |
 
 **For more information about visualization's size, please see [Customizing Size](size.html) page.**
 

site/docs/scale.md

@@ -218,7 +218,7 @@ For ordinal, quantitative, and time fields, `range` can be a two-element array d
 
 | Property      | Type          | Description    |
 | :------------ |:-------------:| :------------- |
-| bandSize     | Number        | Width for each `x` or `y` ordinal band. <span class="note-line">__Default value:__ for `x` ordinal scale of a `text` mark, derived from [scale config](config.html#scale-config)'s `textBandWidth`; otherwise, derived from [scale config](config.html#scale-config)'s `bandSize`.</span> |
+| bandSize      | Integer &#124; String | Width for each `x` or `y` ordinal band.  This can be an integer value or a string `"fit"`.  For `"fit"`, the band size will be automatically adjusted to fit the scale for the specified width (for x-axis) or height (for y-axis). <span class="note-line">__Default value:__ for `x` ordinal scale of a `text` mark, derived from [scale config](config.html#scale-config)'s `textBandWidth`; otherwise, derived from [scale config](config.html#scale-config)'s `bandSize`.</span> <span class="note-line">__Warning__: Numeric `bandSize` will be applied only if the top-level `width` (for x-scale) or `height` (for y-scale) is not specified.  If `width` (for x-scale) or `height` (for y-scale) is specified, `bandWidth` will always be `"fit"`. </span>|
 | padding       | Number        | • For `x` and `y` channels, the padding is a multiple of the spacing between points. A reasonable value is 1.0, such that the first and last point will be offset from the minimum and maximum value by half the distance between points. (See D3's [`ordinalRangePoints()`](https://github.com/mbostock/d3/wiki/Ordinal-Scales#ordinal_rangePoints) for illustration.) <span class="note-line">__Default value:__ derived from [scale config](config.html#scale-config)'s `padding`</span> <br/> • For `row` and `column`, padding is a pixel value for padding between cells in the trellis plots. <span class="note-line">__Default value:__ derived from  [facet scale config](config.html#facet-scale-config)'s `padding`.</span>  |
 
 {:#ex-bandwidth}

site/docs/size.md

@@ -9,20 +9,38 @@ At its core, a Vega-Lite specification describes a single plot. When a [facet ch
 
 ## Width and Height of a Single Plot
 
-The width of a single plot or each cell of a trellis plot is determined by the properties of the `x` channel:
+This includes the width of a single plot or each cell of a trellis plot.
 
-- If the `x` channel has an ordinal scale, the width is a product of the scale's [`bandSize`]((scale.html#ordinal)) and the field's cardinality, or number of possible distinct values of the field mapped to the `x` channel, plus the scale's padding. (_bandWidth * (xCardinality + xPadding)_).
-- If `x` has a continuous scale (either quantitative or time), the width is drawn directly from the `width` property of the [cell configuration](config.html#cell-config).
-- If `x` is not mapped to a field, the width is derived from [scale config](#scale-config)'s `bandSize` for all marks except `text` and from [scale config](#scale-config)'s `textBandWidth` for `text` mark.
+### Explicitly Specified Width and Height
 
-Similarly, the height of a single plot or each cell of a trellis plot is determined by the properties of the `y` channel:
+When the top-level `width` property is specified, the width of the single plot is the specified value for all scale types of the x-axis.  Similarly, when the top-level `height` property is specified, the height of the single plot is the specified value for all scale types of the y-axis.
 
-- If the `y` channel has an ordinal scale, the height is a product of the scale's [`bandSize`]((scale.html#ordinal)) and the field's cardinality, or number of possible distinct values of the field mapped to the `y` channel, plus the scale's padding. (_bandHeight * (yCardinality + yPadding)_).
-- If `y` has a continuous scale (either quantitative or time), the height is drawn directly from the `height` property of the [cell configuration](config.html#cell-config).
-- If `y` is not mapped to a field, the height is derived from [scale config](#scale-config)'s `bandSize`.
+<span class="vl-example" data-name="bar_size_explicit"></span>
+
+Note: If numeric `bandSize` for an ordinal x/y-scale is specified when `width` / `height` is specified, the `bandSize` will be overridden with `"fit"`.
+
+### Default Width and Height
+
+If the top-level `width` / `height` property is not specified, the width / height of a single plot or each cell of a trellis plot is determined by the properties of the `x` / `y` channel:
+
+- If `x` / `y` axis has a continuous scale (either quantitative or time), the width is drawn directly from the [`config.cell.width`](config.html#cell-config) / [`config.cell.height`](config.html#cell-config) property.
+
+- If the `x` / `y` channel has an ordinal scale with a numeric `bandSize` value (default), the width / height is a product of the scale's [`bandSize`]((scale.html#ordinal)) and the field's cardinality, or number of possible distinct values of the field mapped to the `x` / `y` channel, plus the scale's padding. (_bandWidth * (cardinality + padding)_).
+
+<span class="vl-example" data-name="bar_size_default"></span>
+
+- If the `x` / `y` channel has an ordinal scale with `bandSize` = `"fit"`, the width / height is drawn directly from the [`config.cell.width`](config.html#cell-config) / [`config.cell.height`](config.html#cell-config) property and the band of the scale will be adjusted to fit to the width.
+
+<span class="vl-example" data-name="bar_size_fit"></span>
+
+- If `x` / `y` is not mapped to a field, the width / height is derived from [config.scale.bandSize](#scale-config) except when the mark is `text`.  In that case, the width will be drawn from [config.scale.textBandWidth](#scale-config).
+
+<span class="vl-example" data-name="bar_1d"></span>
 
 ## Total Width and Height of a Trellis Plots
 
  The total width of the visualization is the product of the cell's width plus the `column` scale's `padding` and the cardinality of the `column` (_(cellWidth + columnPadding) * columnCardinality_).
 
  Similarly, the total height of the visualization is the product of the cell's height plus the `row` scale's `padding` and the cardinality of the `row` (_(cellHeight + rowPadding) * rowCardinality_).
+
+<span class="vl-example" data-name="trellis_bar"></span>

site/docs/spec.md

@@ -37,7 +37,9 @@ In Vega-Lite, a specification can have the following top-level properties.
 
 | Property             | Type          | Description    |
 | :------------        |:-------------:| :------------- |
-| description   | String     | An _optional_ description of this mark for commenting purpose. This property has no effect on the output visualization. |
+| description          | String     | An _optional_ description of this mark for commenting purpose. This property has no effect on the output visualization. |
+| [width](size.html)   | Integer       | Width of a single visualization.  (For faceted plot, this represents the width of a single cell.)  If not specified (`undefined`), this will be determined by the following rules: <br/>  • For x-axis with a continuous (non-ordinal) scale, the width will be the value of [`config.cell.width`](config.html#cell-config). <br/>  • For x-axis with an ordinal scale: if [`bandSize`](scale.html#ordinal) is a numeric value (default), the width is determined by the value of `bandSize` and the cardinality of the field mapped to x-channel.   Otherwise, if the `bandSize` is `"fit"`, the width will be the value of [`config.cell.width`](config.html#cell-config). <br/>  • If no field is mapped to `x` channel, the `width` will be the value of `textBandWidth` for `text` mark and the value of `bandSize` for other marks. <span class="note-line"> __Default value:__ `undefined` </span>. |
+| [height](size.html)  | Integer       | Height of a single visualization.  (For faceted plot, this represents the height of a single cell.)  If not specified (`undefined`), this will be determined by the following rules: <br/>  • For y-axis with a continuous (non-ordinal) scale, the height will be the value of [`config.cell.height`](config.html#cell-config). <br/>  • For y-axis with an ordinal scale: if [`bandSize`](scale.html#ordinal) is a numeric value (default), the height is determined by the value of `bandSize` and the cardinality of the field mapped to y-channel.   Otherwise, if the `bandSize` is `"fit"`, the height will be the value of [`config.cell.height`](config.html#cell-config). <br/>  • If no field is mapped to `x` channel, the `height` will be the value of `bandSize`. <span class="note-line"> __Default value:__ `undefined` </span>. |
 | [data](data.html)    | Object        | An object describing the data source. |
 | [transform](transform.html) | Object | An object describing filter and new field calculation. |
 | [mark](mark.html)    | String        | The mark type. One of `"bar"`, `"circle"`, `"square"`, `"tick"`, `"line"`, `"area"`, `"point"`, and `"text"`. |