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

Fix #1356

_includes/docs_toc.md

@@ -6,6 +6,7 @@
 - [Data]({{site.baseurl}}/docs/data.html)
     - [Inline Data]({{site.baseurl}}/docs/data.html#inline)
     - [Data from URL]({{site.baseurl}}/docs/data.html#url)
+    - [Format]({{site.baseurl}}/docs/data.html#format)
 - [Transform]({{site.baseurl}}/docs/transform.html)
     - [Top-level Transform Property]({{site.baseurl}}/docs/transform.html#top-level-transform-property)
 - [Mark]({{site.baseurl}}/docs/mark.html)
@@ -25,6 +26,7 @@
         - [Continuous Scale]({{site.baseurl}}/docs/sort.html#continuous-scale)
         - [Ordinal Scale]({{site.baseurl}}/docs/sort.html#ordinal-scale)
     - [Time Unit]({{site.baseurl}}/docs/timeunit.html)
+        - [Date/Time Units]({{site.baseurl}}/docs/timeunit.html#datetime-units)
     - [Scale]({{site.baseurl}}/docs/scale.html)
         - [Scale Type]({{site.baseurl}}/docs/scale.html#type)
         - [Scale Domain]({{site.baseurl}}/docs/scale.html#domain)
@@ -37,11 +39,11 @@
 - [Config]({{site.baseurl}}/docs/config.html)
     - [Top-level Configuration  (config.*)]({{site.baseurl}}/docs/config.html#top-level-config)
     - [Cell Configuration  (config.cell.*)]({{site.baseurl}}/docs/config.html#cell-config)
-    - [Mark Configuration (config.mark.*)]({{site.baseurl}}/docs/config.html#mark-configuration-)
+    - [Mark Configuration (config.mark.*)]({{site.baseurl}}/docs/config.html#mark-config)
     - [Scale Configuration  (config.scale.*)]({{site.baseurl}}/docs/config.html#scale-config)
     - [Axis Configuration  (config.axis.*)]({{site.baseurl}}/docs/config.html#axis-config)
     - [Legend Configuration  (config.legend.*)]({{site.baseurl}}/docs/config.html#legend-config)
-    - [Facet Configuration  (config.facet.*)]({{site.baseurl}}/docs/config.html#facet-configuration--)
+    - [Facet Configuration  (config.facet.*)]({{site.baseurl}}/docs/config.html#facet-config)
 - [Customizing Size]({{site.baseurl}}/docs/size.html)
     - [Width and Height of a Single Plot]({{site.baseurl}}/docs/size.html#width-and-height-of-a-single-plot)
     - [Total Width and Height of a Trellis Plots]({{site.baseurl}}/docs/size.html#total-width-and-height-of-a-trellis-plots)

examples/specs/bar_1d_bandsize_config.json

@@ -0,0 +1,13 @@
+{
+  "data": { "url": "data/population.json"},
+  "transform": {
+    "filter": "datum.year == 2000"
+  },
+  "mark": "bar",
+  "encoding": {
+    "x": {
+      "aggregate": "sum", "field": "people", "type": "quantitative",
+      "axis": {"title": "population"}}
+  },
+  "config": {"scale": {"bandSize": 21}}
+}

examples/specs/bar_size_bandsize_small.json

@@ -0,0 +1,18 @@
+{
+  "description": "A simple bar chart with embedded data.",
+  "data": {
+    "values": [
+      {"a": "A","b": 28}, {"a": "B","b": 55}, {"a": "C","b": 43},
+      {"a": "D","b": 91}, {"a": "E","b": 81}, {"a": "F","b": 53},
+      {"a": "G","b": 19}, {"a": "H","b": 87}, {"a": "I","b": 52}
+    ]
+  },
+  "mark": "bar",
+  "encoding": {
+    "x": {
+      "field": "a", "type": "ordinal",
+      "scale": {"bandSize": 11}
+    },
+    "y": {"field": "b", "type": "quantitative"}
+  }
+}

examples/specs/bar_size_default.json

@@ -0,0 +1,19 @@
+{
+  "data": {"url": "data/cars.json"},
+  "mark": "bar",
+  "encoding": {
+    "x": {
+      "field": "Origin",
+      "type": "nominal",
+      "scale": {"bandSize": 25}
+    },
+    "y": {
+      "aggregate": "count",
+      "field": "*",
+      "type": "quantitative"
+    }
+  },
+  "config": {
+    "cell": {"width": 200, "height": 200}
+  }
+}

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_explicit_bad.json

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

examples/specs/bar_size_fit.json

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

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,8 +218,8 @@ 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> |
-| 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>  |
+| 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__: <br/> 1) 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"`. <br/> 2) If the cardinality of the scale domain is too high, the bandSize might become less than one pixel and the mark might not appear correctly. </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">&nbsp;&nbsp; • __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">&nbsp;&nbsp; •__Default value:__ derived from  [facet scale config](config.html#facet-scale-config)'s `padding`.</span>  |
 
 {:#ex-bandwidth}
 #### Example: Custom Band Width
@@ -230,23 +230,6 @@ Given a bar chart:
 
 We can make the band for each bar smaller by providing `scale`'s `bandSize`.
 
-<div class="vl-example">
-{
-  "description": "A simple bar chart with embedded data.",
-  "data": {
-    "values": [
-      {"a": "A","b": 28}, {"a": "B","b": 55}, {"a": "C","b": 43},
-      {"a": "D","b": 91}, {"a": "E","b": 81}, {"a": "F","b": 53},
-      {"a": "G","b": 19}, {"a": "H","b": 87}, {"a": "I","b": 52}
-    ]
-  },
-  "mark": "bar",
-  "encoding": {
-    "x": {
-      "field": "a", "type": "ordinal",
-      "scale": {"bandSize": 11}
-    },
-    "y": {"field": "b", "type": "quantitative"}
-  }
-}
-</div>
+<span class="vl-example" data-name="bar_size_bandsize_small"></span>
+
+For more information about adjusting size of a visualization, please see [this page](size.html).

site/docs/size.md

@@ -9,20 +9,44 @@ 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"`.
+
+**Warning**: If the cardinality of the x/y-field's domain is too high, the `bandSize` might become less than one pixel and the mark might not appear correctly.
+
+<span class="vl-example" data-name="bar_size_explicit_bad"></span>
+
+### 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)_).
+
+This example shows continuous y-scale and ordinal x-scale:
+
+<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_bandsize_config"></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><span class="note-line">__Examples:__ Please see [Customizing Size](size.html) page.</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><span class="note-line">__Examples:__ Please see [Customizing Size](size.html) page.</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"`. |