feat: more options and examples for how marks and scales represent in…

…valid data (e.g., nulls, NaNs) (#9342)

- Add more spec options for handling invalid data 
  - extend `mark.invalid`
  - add new `config.scale.invalid`

- See [docs's pdf file from
invalid.md](https://github.com/vega/vega-lite/files/15329038/Modes.for.Handling.Invalid.Data._.Vega-Lite.pdf)
or the actual doc for explanation of the behavior. (Given the complexity
of the PR, reviewers should check out the branch and test the spec
locally.)

refactor:
- Adjust how we generate rules for invalid data to handle these options,
per channel type.
    - data's invalid filter
    - `defined` encoding (for breaking paths)

- Make wrapCondition accept invalidValueRef for "include" mode.
- Remove the hidden/screen "hide" mode for invalid data (Given this is a
hidden feature, it's not a breaking change.)## PR Description

bug fixes:
- fix #8254  -- correctly place invalid point as zero, when included. 

Known issues / Follow up items: 
- Tooltip doesn't show null correctly
(#6417) -- I'll fix this
separately in a follow up PR
- Should Vega-lite always include color for invalid by default?
(#9351)


## Checklist

Tests:
- [x] Integration tests -- added a bunch of examples
- [x] Unit tests (in progress) -- I'll re-review the code and add more
unit tests.

Docs: 
- [x] Has documentation under `site/docs/` + examples.

---------

Co-authored-by: GitHub Actions Bot <[email protected]>

examples/compiled/area_invalid_null.vg.json

@@ -61,7 +61,7 @@
           "x": [
             {
               "test": "!isValid(datum[\"x\"]) || !isFinite(+datum[\"x\"])",
-              "value": 0
+              "signal": "scale('x', inrange(0, domain('x')) ? 0 : domain('x')[0])"
             },
             {"scale": "x", "field": "x"}
           ],

examples/compiled/bar_distinct.vg.json

@@ -16,10 +16,6 @@
           "ops": ["distinct"],
           "fields": ["Name"],
           "as": ["distinct_Name"]
-        },
-        {
-          "type": "filter",
-          "expr": "isValid(datum[\"distinct_Name\"]) && isFinite(+datum[\"distinct_Name\"])"
         }
       ]
     }

examples/compiled/bar_grouped_repeated.vg.json

@@ -52,7 +52,8 @@
           "y": [
             {
               "test": "!isValid(datum[\"sum_Worldwide Gross\"]) || !isFinite(+datum[\"sum_Worldwide Gross\"])",
-              "field": {"group": "height"}
+              "scale": "y",
+              "value": 0
             },
             {"scale": "y", "field": "sum_Worldwide Gross"}
           ],
@@ -81,7 +82,8 @@
           "y": [
             {
               "test": "!isValid(datum[\"sum_US Gross\"]) || !isFinite(+datum[\"sum_US Gross\"])",
-              "field": {"group": "height"}
+              "scale": "y",
+              "value": 0
             },
             {"scale": "y", "field": "sum_US Gross"}
           ],

examples/compiled/bar_grouped_thin.vg.json

@@ -49,7 +49,8 @@
           "y": [
             {
               "test": "!isValid(datum[\"mean_Rotten Tomatoes Rating\"]) || !isFinite(+datum[\"mean_Rotten Tomatoes Rating\"])",
-              "field": {"group": "height"}
+              "scale": "y",
+              "value": 0
             },
             {"scale": "y", "field": "mean_Rotten Tomatoes Rating"}
           ],

examples/compiled/bar_grouped_thin_minBandSize.vg.json

@@ -49,7 +49,8 @@
           "y": [
             {
               "test": "!isValid(datum[\"mean_Rotten Tomatoes Rating\"]) || !isFinite(+datum[\"mean_Rotten Tomatoes Rating\"])",
-              "field": {"group": "height"}
+              "scale": "y",
+              "value": 0
             },
             {"scale": "y", "field": "mean_Rotten Tomatoes Rating"}
           ],

examples/compiled/bar_invalid_color_show.vg.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://vega.github.io/schema/vega/v5.json",
+  "description": "Testing invalid",
+  "background": "white",
+  "padding": 5,
+  "width": 200,
+  "height": 200,
+  "style": "cell",
+  "data": [
+    {
+      "name": "source_0",
+      "values": [
+        {"a": 1, "b": 15, "c": 1},
+        {"a": 2, "b": 25, "c": 1},
+        {"a": 3, "b": 20, "c": 1},
+        {"a": 1, "b": 12, "c": 2},
+        {"a": 2, "b": 21, "c": 2},
+        {"a": 3, "b": 29, "c": 2},
+        {"a": 1, "b": 8, "c": null},
+        {"a": 2, "b": 31, "c": null},
+        {"a": 3, "b": 49, "c": null}
+      ]
+    },
+    {
+      "name": "data_0",
+      "source": "source_0",
+      "transform": [
+        {
+          "type": "stack",
+          "groupby": ["a"],
+          "field": "b",
+          "sort": {"field": ["c"], "order": ["descending"]},
+          "as": ["b_start", "b_end"],
+          "offset": "zero"
+        }
+      ]
+    }
+  ],
+  "marks": [
+    {
+      "name": "marks",
+      "type": "rect",
+      "style": ["bar"],
+      "from": {"data": "data_0"},
+      "encode": {
+        "update": {
+          "fill": [
+            {
+              "test": "!isValid(datum[\"c\"]) || !isFinite(+datum[\"c\"])",
+              "signal": "scale('color', inrange(0, domain('color')) ? 0 : domain('color')[0])"
+            },
+            {"scale": "color", "field": "c"}
+          ],
+          "tooltip": {
+            "signal": "{\"a\": format(datum[\"a\"], \"\"), \"b\": format(datum[\"b\"], \"\"), \"c\": format(datum[\"c\"], \"\")}"
+          },
+          "ariaRoleDescription": {"value": "bar"},
+          "description": {
+            "signal": "\"a: \" + (format(datum[\"a\"], \"\")) + \"; b: \" + (format(datum[\"b\"], \"\")) + \"; c: \" + (format(datum[\"c\"], \"\"))"
+          },
+          "xc": [
+            {
+              "test": "!isValid(datum[\"a\"]) || !isFinite(+datum[\"a\"])",
+              "signal": "scale('x', inrange(0, domain('x')) ? 0 : domain('x')[0])"
+            },
+            {"scale": "x", "field": "a"}
+          ],
+          "width": {"value": 5},
+          "y": {"scale": "y", "field": "b_end"},
+          "y2": {"scale": "y", "field": "b_start"}
+        }
+      }
+    }
+  ],
+  "scales": [
+    {
+      "name": "x",
+      "type": "linear",
+      "domain": {"data": "data_0", "field": "a"},
+      "range": [0, {"signal": "width"}],
+      "nice": true,
+      "zero": false,
+      "padding": 5
+    },
+    {
+      "name": "y",
+      "type": "linear",
+      "domain": {"data": "data_0", "fields": ["b_start", "b_end"]},
+      "range": [{"signal": "height"}, 0],
+      "nice": true,
+      "zero": true
+    },
+    {
+      "name": "color",
+      "type": "linear",
+      "domain": {"data": "data_0", "field": "c"},
+      "range": "ramp",
+      "interpolate": "hcl",
+      "zero": false
+    }
+  ],
+  "axes": [
+    {
+      "scale": "x",
+      "orient": "bottom",
+      "gridScale": "y",
+      "grid": true,
+      "tickCount": {"signal": "ceil(width/40)"},
+      "domain": false,
+      "labels": false,
+      "aria": false,
+      "maxExtent": 0,
+      "minExtent": 0,
+      "ticks": false,
+      "zindex": 0
+    },
+    {
+      "scale": "y",
+      "orient": "left",
+      "gridScale": "x",
+      "grid": true,
+      "tickCount": {"signal": "ceil(height/40)"},
+      "domain": false,
+      "labels": false,
+      "aria": false,
+      "maxExtent": 0,
+      "minExtent": 0,
+      "ticks": false,
+      "zindex": 0
+    },
+    {
+      "scale": "x",
+      "orient": "bottom",
+      "grid": false,
+      "title": "a",
+      "labelFlush": true,
+      "labelOverlap": true,
+      "tickCount": {"signal": "ceil(width/40)"},
+      "zindex": 0
+    },
+    {
+      "scale": "y",
+      "orient": "left",
+      "grid": false,
+      "title": "b",
+      "labelOverlap": true,
+      "tickCount": {"signal": "ceil(height/40)"},
+      "zindex": 0
+    }
+  ],
+  "legends": [
+    {
+      "fill": "color",
+      "gradientLength": {"signal": "clamp(height, 64, 200)"},
+      "title": "c"
+    }
+  ],
+  "config": {"mark": {"tooltip": true}}
+}