@urban-toolkit/autk-grammar 4.1.0 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -41,6 +41,47 @@ requestAnimationFrame(() => {
41
41
  });
42
42
  ```
43
43
 
44
+ ## Layer styling
45
+
46
+ Besides `dataRef`, a layer of `map.layerRefs` takes these styling options:
47
+
48
+ | Option | Effect |
49
+ |---|---|
50
+ | `title` | The layer's id in its map, which its legend shows as its title. Without a title, the id is the `dataRef`. Two layers of one map cannot have the same id. |
51
+ | `color` | The layer's color, `#rrggbb`. The layer is drawn in it rather than by its `getFnv` value, unless `isColorMap` is `true`. |
52
+ | `stroke` | A polygon layer's outline: its color, `#rrggbb`, or `false` for none. |
53
+ | `width` | The width of a polylines or roads layer's lines, in the map's planar units (autk-map's `polylinesWidth`). |
54
+ | `colorMapInterpolator` | The color scheme. A raster layer's cells and its legend's labels follow it. |
55
+ | `colorMapCenter` | On a raster layer, the value at the middle of the color scale. The scale then runs from the center less the farthest value's distance to it, to the center plus that distance. |
56
+ | `colorMapReverse` | On a raster layer, runs the color scale from the highest value to the lowest. |
57
+ | `transferFunction` | On a raster layer, how opaque its cells are by value: autk-map's transfer function (`mode`, `opacityMin`, `opacityMax`, `gamma`, `zeroCenter`). `{ opacityMin: 1, opacityMax: 1 }` draws every cell with a value fully opaque. |
58
+
59
+ After a run, `grammar.mapLayer(dataRef)` finds the layer a map draws for a table: the `AutkMap` and the layer's id in it. `highlightOnMap`, `clearHighlightOnMap` and a plot's `mapRef` also name a layer by its `dataRef`.
60
+
61
+ ```ts
62
+ await grammar.run({
63
+ data: [/* tables named routes and parcels, and a heatmap raster named change */],
64
+ map: {
65
+ layerRefs: [
66
+ { dataRef: 'parcels', color: '#4e79a7', stroke: false },
67
+ { dataRef: 'routes', title: 'Fastest route', color: '#e15759', width: 30 },
68
+ { dataRef: 'change', title: 'Change', colorMapInterpolator: ColorMapInterpolator.DIV_RED_BLUE, colorMapCenter: 0, colorMapReverse: true },
69
+ ],
70
+ },
71
+ });
72
+ const { map, layerId } = grammar.mapLayer('routes')!; // layerId is 'Fastest route'
73
+ map.updateRenderInfo(layerId, { opacity: 0.5 });
74
+ ```
75
+
76
+ ## Interactions
77
+
78
+ A layer with `isPick` and a plot with `events` report what the user selects on `grammar.interactions`: `map:picking` and `plot:selection` give feature ids, the positions of the selected features among those the layer or the plot draws (a map layer leaves out features without a geometry). To link a selection to other tables, name the columns whose values identify those rows with `selectFields` on the layer or the plot, for example `selectFields: ['nta2020']`. The grammar does not read it; the events still report feature ids, and the app reads the key values from those rows.
79
+
80
+ ```ts
81
+ grammar.interactions.on('map:picking', ({ layerId, selection }) => { /* feature ids */ });
82
+ grammar.interactions.on('plot:selection', ({ plotId, event, selection }) => { /* feature ids */ });
83
+ ```
84
+
44
85
  ## JSON Schema
45
86
 
46
87
  The package ships the grammar's JSON Schema (draft-07) as `@urban-toolkit/autk-grammar/build/autk-grammar-schema.json`, with `$id` `https://autarkjs.org/schema/autk-grammar/v1.json`. Validate a spec with any draft-07 validator:
@@ -66,7 +66,7 @@
66
66
  "type": "number"
67
67
  },
68
68
  "mapRef": {
69
- "description": "Layer id of a map this plot links its selection to.",
69
+ "description": "`dataRef` of the map layer this plot links its selection to.",
70
70
  "type": "string"
71
71
  },
72
72
  "margins": {
@@ -96,6 +96,14 @@
96
96
  "const": "bar",
97
97
  "type": "string"
98
98
  },
99
+ "selectFields": {
100
+ "description": "Columns whose values name the rows a selection in this plot selects, so an app can link the selection to other tables that hold those columns. Neither adapter reads it: the Autark adapter's `plot:selection` events still report feature ids.",
101
+ "items": {
102
+ "type": "string"
103
+ },
104
+ "minItems": 1,
105
+ "type": "array"
106
+ },
99
107
  "title": {
100
108
  "type": "string"
101
109
  },
@@ -895,7 +903,7 @@
895
903
  "type": "number"
896
904
  },
897
905
  "mapRef": {
898
- "description": "Layer id of a map this plot links its selection to.",
906
+ "description": "`dataRef` of the map layer this plot links its selection to.",
899
907
  "type": "string"
900
908
  },
901
909
  "margins": {
@@ -925,6 +933,14 @@
925
933
  "const": "heatmatrix",
926
934
  "type": "string"
927
935
  },
936
+ "selectFields": {
937
+ "description": "Columns whose values name the rows a selection in this plot selects, so an app can link the selection to other tables that hold those columns. Neither adapter reads it: the Autark adapter's `plot:selection` events still report feature ids.",
938
+ "items": {
939
+ "type": "string"
940
+ },
941
+ "minItems": 1,
942
+ "type": "array"
943
+ },
928
944
  "title": {
929
945
  "type": "string"
930
946
  },
@@ -943,6 +959,11 @@
943
959
  ],
944
960
  "type": "object"
945
961
  },
962
+ "HexColor": {
963
+ "description": "A color as `#rrggbb`.",
964
+ "pattern": "^#[0-9a-fA-F]{6}$",
965
+ "type": "string"
966
+ },
946
967
  "InlineFeature": {
947
968
  "description": "A GeoJSON feature as the loader accepts it: `geometry` may be null and `properties` may be omitted.",
948
969
  "properties": {
@@ -1171,7 +1192,7 @@
1171
1192
  "type": "number"
1172
1193
  },
1173
1194
  "mapRef": {
1174
- "description": "Layer id of a map this plot links its selection to.",
1195
+ "description": "`dataRef` of the map layer this plot links its selection to.",
1175
1196
  "type": "string"
1176
1197
  },
1177
1198
  "margins": {
@@ -1204,6 +1225,14 @@
1204
1225
  ],
1205
1226
  "type": "string"
1206
1227
  },
1228
+ "selectFields": {
1229
+ "description": "Columns whose values name the rows a selection in this plot selects, so an app can link the selection to other tables that hold those columns. Neither adapter reads it: the Autark adapter's `plot:selection` events still report feature ids.",
1230
+ "items": {
1231
+ "type": "string"
1232
+ },
1233
+ "minItems": 1,
1234
+ "type": "array"
1235
+ },
1207
1236
  "title": {
1208
1237
  "type": "string"
1209
1238
  },
@@ -1253,6 +1282,14 @@
1253
1282
  "catchAllCategory": {
1254
1283
  "type": "string"
1255
1284
  },
1285
+ "color": {
1286
+ "$ref": "#/definitions/HexColor",
1287
+ "description": "Color of the layer, as `#rrggbb`. A layer with a color is drawn in it rather than by its `getFnv` value, unless `isColorMap` is `true`. Raster layers are always colored by value. Read by the Autark adapter; the deck.gl adapter ignores it."
1288
+ },
1289
+ "colorMapCenter": {
1290
+ "description": "Value at the middle of a raster layer's color scale: the scale runs from this value less the farthest value's distance to it, to this value plus that distance, so a diverging scheme's middle color marks it. Read by the Autark adapter for raster layers; other layers and the deck.gl adapter ignore it.",
1291
+ "type": "number"
1292
+ },
1256
1293
  "colorMapDomain": {
1257
1294
  "description": "Allowed category values; anything else is drawn as the catch-all category. Only used when `getFnvType` is `categorical`.",
1258
1295
  "items": {
@@ -1271,6 +1308,10 @@
1271
1308
  },
1272
1309
  "type": "array"
1273
1310
  },
1311
+ "colorMapReverse": {
1312
+ "description": "Run a raster layer's color scale from its highest value to its lowest, so the scheme's first color marks the highest value. Read by the Autark adapter for raster layers; other layers and the deck.gl adapter ignore it.",
1313
+ "type": "boolean"
1314
+ },
1274
1315
  "dataRef": {
1275
1316
  "description": "Name of the table to draw, as produced by a data source or a compute pass.",
1276
1317
  "type": "string"
@@ -1334,6 +1375,40 @@
1334
1375
  "type": "number"
1335
1376
  },
1336
1377
  "type": "array"
1378
+ },
1379
+ "selectFields": {
1380
+ "description": "Columns whose values name the rows a pick on this layer selects, so an app can link the selection to other tables that hold those columns. Neither adapter reads it: the Autark adapter's `map:picking` events still report feature ids.",
1381
+ "items": {
1382
+ "type": "string"
1383
+ },
1384
+ "minItems": 1,
1385
+ "type": "array"
1386
+ },
1387
+ "stroke": {
1388
+ "anyOf": [
1389
+ {
1390
+ "$ref": "#/definitions/HexColor"
1391
+ },
1392
+ {
1393
+ "const": false,
1394
+ "type": "boolean"
1395
+ }
1396
+ ],
1397
+ "description": "Outline of a polygon layer: its color, as `#rrggbb`, or `false` to draw no outline. Read by the Autark adapter, which outlines polygon layers only; the deck.gl adapter ignores it."
1398
+ },
1399
+ "title": {
1400
+ "description": "Name of the layer, shown as its legend's title. It becomes the layer's id in the map, so two layers of one map cannot have the same title, and a title cannot be another layer's `dataRef` in that map. Without it, the layer's id is its `dataRef`. Read by the Autark adapter; the deck.gl adapter ignores it.",
1401
+ "minLength": 1,
1402
+ "type": "string"
1403
+ },
1404
+ "transferFunction": {
1405
+ "$ref": "#/definitions/RasterTransferFunction",
1406
+ "description": "How opaque a raster layer's cells are by value, as autk-map's transfer function: for example `{ opacityMin: 1, opacityMax: 1 }` draws every cell with a value fully opaque. Read by the Autark adapter for raster layers; other layers and the deck.gl adapter ignore it."
1407
+ },
1408
+ "width": {
1409
+ "description": "Width of the lines of a polylines or roads layer, in the map's planar units (about meters). It replaces the widths a roads layer gives each kind of road. Read by the Autark adapter; the deck.gl adapter ignores it.",
1410
+ "exclusiveMinimum": 0,
1411
+ "type": "number"
1337
1412
  }
1338
1413
  },
1339
1414
  "required": [
@@ -1545,7 +1620,7 @@
1545
1620
  "type": "number"
1546
1621
  },
1547
1622
  "mapRef": {
1548
- "description": "Layer id of a map this plot links its selection to.",
1623
+ "description": "`dataRef` of the map layer this plot links its selection to.",
1549
1624
  "type": "string"
1550
1625
  },
1551
1626
  "margins": {
@@ -1575,6 +1650,14 @@
1575
1650
  "const": "parallel-coordinates",
1576
1651
  "type": "string"
1577
1652
  },
1653
+ "selectFields": {
1654
+ "description": "Columns whose values name the rows a selection in this plot selects, so an app can link the selection to other tables that hold those columns. Neither adapter reads it: the Autark adapter's `plot:selection` events still report feature ids.",
1655
+ "items": {
1656
+ "type": "string"
1657
+ },
1658
+ "minItems": 1,
1659
+ "type": "array"
1660
+ },
1578
1661
  "title": {
1579
1662
  "type": "string"
1580
1663
  },
@@ -1860,6 +1943,42 @@
1860
1943
  },
1861
1944
  "type": "array"
1862
1945
  },
1946
+ "RasterTransferFunction": {
1947
+ "description": "How opaque a raster layer's cells are by value: autk-map's transfer function. A cell with no value is clear.",
1948
+ "properties": {
1949
+ "gamma": {
1950
+ "description": "Exponent applied to a cell's place between the lowest and highest opacity. Defaults to 1.",
1951
+ "exclusiveMinimum": 0,
1952
+ "type": "number"
1953
+ },
1954
+ "mode": {
1955
+ "description": "`far-zero`: cells farther from `zeroCenter` are more opaque (autk-map's default). `near-zero`: cells closer to `zeroCenter` are more opaque. `linear`: opacity grows from the lowest value to the highest.",
1956
+ "enum": [
1957
+ "near-zero",
1958
+ "far-zero",
1959
+ "linear"
1960
+ ],
1961
+ "type": "string"
1962
+ },
1963
+ "opacityMax": {
1964
+ "description": "Highest opacity, from 0 to 1. Defaults to 1.",
1965
+ "maximum": 1,
1966
+ "minimum": 0,
1967
+ "type": "number"
1968
+ },
1969
+ "opacityMin": {
1970
+ "description": "Lowest opacity, from 0 to 1. Defaults to 0.",
1971
+ "maximum": 1,
1972
+ "minimum": 0,
1973
+ "type": "number"
1974
+ },
1975
+ "zeroCenter": {
1976
+ "description": "Value the `far-zero` and `near-zero` modes measure from. Defaults to 0.",
1977
+ "type": "number"
1978
+ }
1979
+ },
1980
+ "type": "object"
1981
+ },
1863
1982
  "ScatterPlotSpec": {
1864
1983
  "description": "A scatterplot of two or more columns.",
1865
1984
  "properties": {
@@ -1889,7 +2008,7 @@
1889
2008
  "type": "number"
1890
2009
  },
1891
2010
  "mapRef": {
1892
- "description": "Layer id of a map this plot links its selection to.",
2011
+ "description": "`dataRef` of the map layer this plot links its selection to.",
1893
2012
  "type": "string"
1894
2013
  },
1895
2014
  "margins": {
@@ -1919,6 +2038,14 @@
1919
2038
  "const": "scatter",
1920
2039
  "type": "string"
1921
2040
  },
2041
+ "selectFields": {
2042
+ "description": "Columns whose values name the rows a selection in this plot selects, so an app can link the selection to other tables that hold those columns. Neither adapter reads it: the Autark adapter's `plot:selection` events still report feature ids.",
2043
+ "items": {
2044
+ "type": "string"
2045
+ },
2046
+ "minItems": 1,
2047
+ "type": "array"
2048
+ },
1922
2049
  "title": {
1923
2050
  "type": "string"
1924
2051
  },
@@ -1965,7 +2092,7 @@
1965
2092
  "type": "number"
1966
2093
  },
1967
2094
  "mapRef": {
1968
- "description": "Layer id of a map this plot links its selection to.",
2095
+ "description": "`dataRef` of the map layer this plot links its selection to.",
1969
2096
  "type": "string"
1970
2097
  },
1971
2098
  "margins": {
@@ -1995,6 +2122,14 @@
1995
2122
  "const": "table",
1996
2123
  "type": "string"
1997
2124
  },
2125
+ "selectFields": {
2126
+ "description": "Columns whose values name the rows a selection in this plot selects, so an app can link the selection to other tables that hold those columns. Neither adapter reads it: the Autark adapter's `plot:selection` events still report feature ids.",
2127
+ "items": {
2128
+ "type": "string"
2129
+ },
2130
+ "minItems": 1,
2131
+ "type": "array"
2132
+ },
1998
2133
  "title": {
1999
2134
  "type": "string"
2000
2135
  },