Last batch of housekeeping (#265)

* Fix vertical width in boxplots

* Fix #248

* minor tweaks to docs

* Fix empty terminal bins

* reformat

Author: thomasp85

doc/syntax/coord/polar.qmd

@@ -63,7 +63,8 @@ DRAW bar
 PROJECT TO polar 
   SETTING start => -90, end => 90
 ```
-This creates a gauge chart spanning from the 9 o'clock to 3 o'clock position (a 180° arc at the top).
+
+This creates a gauge chart spanning from the 9 o'clock to 3 o'clock position (a 180° arc at the top). Note that scale expansion is applied by default so the data does not fill the whole half-circle.
 
 ### Three-quarter pie chart
 ```{ggsql}

doc/syntax/layer/type/point.qmd

@@ -57,6 +57,8 @@ DRAW point
   FILTER sex = 'female'
 ```
 
+When points are plotted on a discrete scale you will likely see a lot of overplotting. Use jitter position to introduce a bit of random offset to counter that.
+
 ```{ggsql}
 VISUALISE species AS x, sex AS y, island AS fill FROM ggsql:penguins
 DRAW point

doc/syntax/scale/aesthetic/0_position.qmd

@@ -2,7 +2,9 @@
 title: "Position"
 ---
 
-Position aesthetics (`x` and `y`, plus all their variants) relate data to placement in the coordinate system of the plot. All layers need at least one of each positional aesthetic mapped in order to show its data. However, the layer may compute positional aesthetics from the mapping. For example, a bar plot calculates the `y` aesthetic by counting the number of records in each group.
+Position aesthetics relate data to placement in the coordinate system of the plot. All layers need at least one of each positional aesthetic mapped in order to show its data. However, the layer may compute positional aesthetics from the mapping. For example, a bar plot calculates the `y` aesthetic by counting the number of records in each group defined by the mapped `x` aesthetic.
+
+In the above we use `x`and `y` as examples of position aesthetics but in reality the position aesthetic names are defined by the coordinate system in use. A Cartesian coordinate system recognizes `x` and `y` whereas a polar coordinate system recognizes `radius` and `angle`. You can implicitly choose the coordinate system by mapping to the aesthetics that it uses, i.e. if you map to `radius` and `angle` then a polar coordinate system will be chosen for you.
 
 ## Literal values
 Scales for position aesthetics never use an output range and always relate to the input range. This is a practical decision by ggsql because different writers may treat the positional aesthetic in different ways. ^[In reality one could easily think of positional literal values as either normalized position along the x or y axis, or absolute units of distance from the bottom left corner of the coordinate system.]
@@ -12,14 +14,10 @@ The lack of true literal values in position means that it is currently hard to p
 :::
 
 ## Aesthetic families
-Positional aesthetics consist of two families: The `x` and `y` family. Each of these consist of their primary aesthetic along with a range of sub aesthetic defined by their suffix:
+Positional aesthetics have variants defined by a suffix attached to the primary name (e.g. `x`). The recognized suffixes are:
 
-* `2`
 * `end`
 * `min`
 * `max`
 
-Which version of aesthetic to use depends on the layer, but all aesthetics within a family is scaled by the same scale, which is named after its primary aesthetic. This means that even when rendering a layer that only uses `xmin` and `xmax`, you will still scale it by writing `SCALE x ...` and label it by writing `LABEL x => ...`
-
-## Coordinate system
-Another thing that makes positional aesthetics different from other aesthetic is that they are dependent on a coordinate system which takes position scales and defines how values should be converted to a location on a plane. The default Cartesian coordinate system does what is generally expected: it places points along two perpendicular axes in a 2D plane. Other systems such as polar coordinates may dramatically change the look of a layer, transforming both the straightness of lines and positional relation of data.
+Which version of an aesthetic to use depends on the layer, but all aesthetics within a family is scaled by the same scale, which is named after its primary aesthetic. This means that even when rendering a layer that only uses `xmin` and `xmax`, you will still scale it by writing `SCALE x ...` and label it by writing `LABEL x => ...`

doc/syntax/scale/aesthetic/Z_faceting.qmd

@@ -4,7 +4,7 @@ title: Faceting
 
 ggsql provides one or two aesthetics related to faceting. These are special in the sense that they do not alter the display of the single data values, but rather alter in which plot they appear. While it is possible to map to these aesthetics in a layer they are most often applied globally as part of the [`FACET` clause](../../clause/facet.qmd).
 
-The aesthetics provided are either `panel` (for 1-dimensional faceting) or `row` and `column` (for 2-dimensional faceting). These aesthetics have to compatible with the facet clause: it is not possible to map to `panel` in a 2-dimensional faceting plot nor is it possible to map `row` and `column` in a 1-dimensional plot.
+The aesthetics provided are either `panel` (for 1-dimensional faceting) or `row` and `column` (for 2-dimensional faceting). These aesthetics have to be compatible with the facet clause: it is not possible to map to `panel` in a 2-dimensional faceting plot nor is it possible to map `row` and `column` in a 1-dimensional plot.
 
 ## Literal values
 Scales for facet aesthetics never use an output range and always relate to the input range. This means that no concept of literal values applies.

doc/syntax/scale/type/binned.qmd

@@ -167,8 +167,8 @@ If `oob => 'squish'` then the terminal labels are formatted as e.g. "≥ 10" to
 ```{ggsql}
 VISUALISE bill_dep AS x FROM ggsql:penguins
 DRAW bar
-SCALE BINNED x 
-  RENAMING 50 => 'Fifty'
+SCALE BINNED x
+  RENAMING 20 => 'Twenty'
 ```
 
 #### Adding suffix to break labels

src/plot/scale/scale_type/binned.rs

@@ -332,11 +332,15 @@ impl ScaleTypeTrait for Binned {
         match scale.properties.get("breaks") {
             Some(ParameterValue::Number(_)) => {
                 // Scalar count → calculate actual breaks and store as Array
-                if let Some(breaks) = self.resolve_breaks(
-                    scale.input_range.as_deref(),
-                    &scale.properties,
-                    scale.transform.as_ref(),
-                ) {
+                // Use raw data range (not expanded input_range) so breaks align
+                // to actual data extent; expansion happens later in step 5b.
+                let break_range = match &context.range {
+                    Some(InputRange::Continuous(r)) => Some(r.as_slice()),
+                    _ => scale.input_range.as_deref(),
+                };
+                if let Some(breaks) =
+                    self.resolve_breaks(break_range, &scale.properties, scale.transform.as_ref())
+                {
                     // For binned implicit, keep all breaks (they extend past data).
                     // For binned explicit, filter to input range.
                     let filtered = if binned_implicit {
@@ -387,7 +391,13 @@ impl ScaleTypeTrait for Binned {
                 };
 
                 if let Some(interval) = TemporalInterval::create_from_str(interval_str) {
-                    if let Some(ref range) = scale.input_range {
+                    // Use raw data range (not expanded input_range) so breaks align
+                    // to actual data extent; expansion happens later in step 5b.
+                    let break_range: Option<&[ArrayElement]> = match &context.range {
+                        Some(InputRange::Continuous(r)) => Some(r.as_slice()),
+                        _ => scale.input_range.as_deref(),
+                    };
+                    if let Some(range) = break_range {
                         let breaks: Vec<ArrayElement> = match resolved_transform.transform_kind() {
                             TransformKind::Date => {
                                 let min = range[0].to_f64().unwrap_or(0.0) as i32;
@@ -422,10 +432,18 @@ impl ScaleTypeTrait for Binned {
                                 .iter()
                                 .map(|elem| resolved_transform.parse_value(elem))
                                 .collect();
-                            // Filter to input range
-                            let filtered = super::super::super::breaks::filter_breaks_to_range(
-                                &converted, range,
-                            );
+                            // Only filter to input range when user provided explicit FROM clause
+                            let filtered = if scale.explicit_input_range {
+                                if let Some(ref ir) = scale.input_range {
+                                    super::super::super::breaks::filter_breaks_to_range(
+                                        &converted, ir,
+                                    )
+                                } else {
+                                    converted
+                                }
+                            } else {
+                                converted
+                            };
                             scale
                                 .properties
                                 .insert("breaks".to_string(), ParameterValue::Array(filtered));

src/writer/vegalite/layer.rs

@@ -1540,20 +1540,20 @@ impl GeomRenderer for ErrorBarRenderer {
         let mut layers = vec![layer_spec.clone()];
 
         // Determine if this is a vertical or horizontal error bar and set up parameters
-        let is_vertical = layer_spec["encoding"]["x2"].is_null();
+        let is_vertical = !is_transposed(layer);
         let (orient, position, min_field, max_field) = if is_vertical {
             (
                 "horizontal",
                 "y",
-                naming::aesthetic_column("ymin"),
-                naming::aesthetic_column("ymax"),
+                naming::aesthetic_column("pos2min"),
+                naming::aesthetic_column("pos2max"),
             )
         } else {
             (
                 "vertical",
                 "x",
-                naming::aesthetic_column("xmin"),
-                naming::aesthetic_column("xmax"),
+                naming::aesthetic_column("pos1min"),
+                naming::aesthetic_column("pos1max"),
             )
         };
 
@@ -1817,11 +1817,19 @@ impl BoxplotRenderer {
         let mut box_part = create_layer(
             &summary_prototype,
             "box",
-            json!({
-                "type": "bar",
-                "width": width_value,
-                "align": "center"
-            }),
+            if is_horizontal {
+                json!({
+                    "type": "bar",
+                    "height": width_value,
+                    "baseline": "middle"
+                })
+            } else {
+                json!({
+                    "type": "bar",
+                    "width": width_value,
+                    "align": "center"
+                })
+            },
         );
         box_part["encoding"][value_var1] = y_encoding.clone();
         box_part["encoding"][value_var2] = y2_encoding.clone();
@@ -1830,11 +1838,19 @@ impl BoxplotRenderer {
         let mut median_line = create_layer(
             &summary_prototype,
             "median",
-            json!({
-                "type": "tick",
-                "width": width_value,
-                "align": "center"
-            }),
+            if is_horizontal {
+                json!({
+                    "type": "tick",
+                    "height": width_value,
+                    "baseline": "middle"
+                })
+            } else {
+                json!({
+                    "type": "tick",
+                    "width": width_value,
+                    "align": "center"
+                })
+            },
         );
         median_line["encoding"][value_var1] = y_encoding;