@urban-toolkit/autk-grammar 5.0.0 → 5.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/dist/index.d.ts CHANGED
@@ -13,7 +13,7 @@ export declare type AggregateFunction = 'sum' | 'avg' | 'count' | 'min' | 'max'
13
13
 
14
14
  /**
15
15
  * Moves a map's camera as `camera` says, from the view that fits the map's layers. The camera reports each change,
16
- * so the map redraws without a request.
16
+ * so the map redraws without a request. It refuses a pitch that is not at least 0 and less than 90 degrees.
17
17
  *
18
18
  * The map adapter calls it once the map's layers are loaded and before the map's first `draw()`. A host that builds
19
19
  * its own map from a spec's `map` entry calls it at the same point, so the map looks from where the grammar's would.
@@ -59,7 +59,8 @@ export declare class AutkGrammar {
59
59
  readonly interactions: GrammarEventEmitter;
60
60
  constructor(targets?: Targets);
61
61
  /**
62
- * The coordinate reference system used internally by the autk workspace.
62
+ * The coordinate reference system autk-db stores a workspace's tables in, unless the spec's `workspaces` sets
63
+ * another for it.
63
64
  *
64
65
  * Input data is expected in EPSG:4326 (WGS84) by default and is transformed
65
66
  * to this CRS on load. Consumers that prepare data for injection (e.g. by
@@ -163,6 +164,12 @@ export declare class AutkGrammar {
163
164
  private _selectInLinkedPlots;
164
165
  /** Wires each entry of `links` between a plot and a layer of a map, both now drawn. */
165
166
  private _wireLinks;
167
+ /**
168
+ * Applies each plot's `selection` once the plots and their links exist, as `setPlotSelection` does: the plot selects
169
+ * the rows, and the layers it is linked to, by `mapRef` or `links`, highlight them. autk-plot's `setSelection` emits
170
+ * no event, so no `plot:selection` reports it.
171
+ */
172
+ private _selectFromTheStart;
166
173
  private _rewireInteractions;
167
174
  }
168
175
 
@@ -209,9 +216,10 @@ export declare type CameraSpec = {
209
216
  */
210
217
  zoom?: number;
211
218
  /**
212
- * Tilt from straight down, in degrees.
219
+ * Tilt from straight down, in degrees, less than 90: at 90 the eye would sit on the ground, edge-on to the map's flat
220
+ * layers, and the map could not pan.
213
221
  * @minimum 0
214
- * @maximum 90
222
+ * @exclusiveMaximum 90
215
223
  */
216
224
  pitch?: number;
217
225
  /**
@@ -222,6 +230,9 @@ export declare type CameraSpec = {
222
230
  bearing?: number;
223
231
  };
224
232
 
233
+ /** A categorical color scheme: a `scheme*` name, one color for each category. */
234
+ export declare type CategoricalColorMapInterpolator = ColorMapInterpolator.CAT_ACCENT | ColorMapInterpolator.CAT_DARK2 | ColorMapInterpolator.CAT_CATEGORY10 | ColorMapInterpolator.CAT_OBSERVABLE10 | ColorMapInterpolator.CAT_PAIRED | ColorMapInterpolator.CAT_PASTEL1 | ColorMapInterpolator.CAT_PASTEL2 | ColorMapInterpolator.CAT_SET1 | ColorMapInterpolator.CAT_SET2 | ColorMapInterpolator.CAT_SET3 | ColorMapInterpolator.CAT_TABLEAU10;
235
+
225
236
  /** Color scheme for a colored map layer: `scheme*` names are categorical, `interpolate*` names are sequential or diverging. */
226
237
  export declare enum ColorMapInterpolator {
227
238
  CAT_ACCENT = "schemeAccent",
@@ -308,6 +319,9 @@ export declare type ComputeRunner = (params: GpgpuPipelineParams) => Promise<Fea
308
319
  /** One entry of `compute`. A pass with `type: 'render'` is a {@link RenderComputeSpec}, any other a {@link GpgpuComputeSpec}. */
309
320
  export declare type ComputeSpec = GpgpuComputeSpec | RenderComputeSpec;
310
321
 
322
+ /** A sequential or diverging color scheme: an `interpolate*` name, a color for each number of a scale. */
323
+ export declare type ContinuousColorMapInterpolator = ColorMapInterpolator.SEQ_REDS | ColorMapInterpolator.SEQ_BLUES | ColorMapInterpolator.SEQ_GREENS | ColorMapInterpolator.SEQ_GREYS | ColorMapInterpolator.SEQ_ORANGES | ColorMapInterpolator.SEQ_PURPLES | ColorMapInterpolator.SEQ_TURBO | ColorMapInterpolator.SEQ_VIRIDIS | ColorMapInterpolator.SEQ_INFERNO | ColorMapInterpolator.SEQ_MAGMA | ColorMapInterpolator.SEQ_PLASMA | ColorMapInterpolator.SEQ_CIVIDIS | ColorMapInterpolator.SEQ_WARM | ColorMapInterpolator.SEQ_COOL | ColorMapInterpolator.SEQ_CUBEHELIX_DEFAULT | ColorMapInterpolator.SEQ_BU_GN | ColorMapInterpolator.SEQ_BU_PU | ColorMapInterpolator.SEQ_GN_BU | ColorMapInterpolator.SEQ_OR_RD | ColorMapInterpolator.SEQ_PU_BU_GN | ColorMapInterpolator.SEQ_PU_BU | ColorMapInterpolator.SEQ_PU_RD | ColorMapInterpolator.SEQ_RD_PU | ColorMapInterpolator.SEQ_YL_GN_BU | ColorMapInterpolator.SEQ_YL_GN | ColorMapInterpolator.SEQ_YL_OR_BR | ColorMapInterpolator.SEQ_YL_OR_RD | ColorMapInterpolator.DIV_BR_BG | ColorMapInterpolator.DIV_PR_GN | ColorMapInterpolator.DIV_PI_YG | ColorMapInterpolator.DIV_PU_OR | ColorMapInterpolator.DIV_RED_BLUE | ColorMapInterpolator.DIV_RED_GREY | ColorMapInterpolator.DIV_RED_YELLOW_BLUE | ColorMapInterpolator.DIV_RED_YELLOW_GREEN | ColorMapInterpolator.DIV_SPECTRAL;
324
+
311
325
  /**
312
326
  * The compute adapter `AutkGrammar` runs. Its `resolveCompute(db, pass)` runs one entry of a spec's `compute`, a
313
327
  * GPGPU pass or a render pass, on autk-compute, in the pass's workspace, which it leaves current. It does nothing
@@ -316,21 +330,24 @@ export declare type ComputeSpec = GpgpuComputeSpec | RenderComputeSpec;
316
330
  * A host calls it to run compute passes exactly as the grammar does. The passes need WebGPU, and their results are
317
331
  * kept only in the caches: `cache` receives each pass's result under {@link tableKey} of its `outputTableName`, or of
318
332
  * the table it computed over, and a later pass reads a table from it first. `types` receives the layer type of each
319
- * table a pass wrote under its own `outputTableName`, which a map needs to draw it.
333
+ * table a pass wrote under its own `outputTableName`, which a map needs to draw it. `sources` is the cache the data
334
+ * adapter fills: a pass reads a `fromFeature` table from it next, as its plots read theirs, when a GeoJSON source put
335
+ * the table there with its coordinates in the workspace's CRS.
320
336
  */
321
- export declare function createComputeAdapter(cache?: ComputeCache, types?: ComputeLayerTypes): ComputeAdapter;
337
+ export declare function createComputeAdapter(cache?: ComputeCache, types?: ComputeLayerTypes, sources?: GeoJsonCache): ComputeAdapter;
322
338
 
323
339
  /**
324
340
  * The data adapter `AutkGrammar` runs. Its `resolveSource(db, source)` loads one entry of a spec's `data` into the
325
341
  * autk-db database `db` (a new one when `db` is undefined), in the entry's workspace, which it leaves current, and
326
- * returns the database.
342
+ * returns the database. Its `resolveWorkspaces(db, workspaces)` sets each workspace a spec's `workspaces` lists to its
343
+ * CRS and precision grid, before the first source loads, leaves the default workspace current and returns the database.
327
344
  *
328
345
  * A host calls it to load a spec's tables exactly as the grammar does, for example on a server without a map: the
329
346
  * `./data` entry exports it with autk-db as its only import. `targets.db` names an element that lists the tables
330
- * after each load. `cache`, when given, receives each GeoJSON table and each table a join wrote, under
331
- * {@link tableKey}.
347
+ * after each load. `cache`, when given, receives each GeoJSON table and each table a join or an update wrote, under
348
+ * {@link tableKey}, and loses each table a `sql` source replaces or a `drop` source drops.
332
349
  */
333
- export declare function createDataAdapter(targets?: Targets, cache?: GeoJsonCache): DataAdapter;
350
+ export declare function createDataAdapter(targets?: Targets, cache?: GeoJsonCache): Required<DataAdapter>;
334
351
 
335
352
  export declare function createEngine(options: EngineOptions): IEngine;
336
353
 
@@ -388,16 +405,33 @@ export declare interface CustomDataSourceSpec extends TableSourceBase {
388
405
 
389
406
  export declare interface DataAdapter {
390
407
  resolveSource(context: unknown, spec: DataSourceSpec): Promise<unknown>;
408
+ /**
409
+ * Sets up the workspaces a spec's `workspaces` lists, before its first source loads, and returns the context. An
410
+ * adapter without workspaces leaves it out, and the engine then skips `workspaces`.
411
+ */
412
+ resolveWorkspaces?(context: unknown, workspaces: WorkspaceSpec[]): Promise<unknown>;
391
413
  }
392
414
 
393
415
  /**
394
416
  * One entry of `data`. The `type` field selects which fields apply.
395
417
  * @discriminator type
396
418
  */
397
- export declare type DataSourceSpec = OsmDataSourceSpec | CsvDataSourceSpec | JsonDataSourceSpec | CustomDataSourceSpec | GeoTiffDataSourceSpec | HeatmapSourceSpec | JoinSourceSpec;
419
+ export declare type DataSourceSpec = OsmDataSourceSpec | CsvDataSourceSpec | JsonDataSourceSpec | CustomDataSourceSpec | GeoTiffDataSourceSpec | HeatmapSourceSpec | JoinSourceSpec | SqlSourceSpec | UpdateSourceSpec | DropSourceSpec;
398
420
 
399
421
  /** Kind of data source; selects which fields a `data` entry takes. */
400
- export declare type DataSourceType = 'osm' | 'csv' | 'json' | 'geojson' | 'geotiff' | 'heatmap' | 'join';
422
+ export declare type DataSourceType = 'osm' | 'csv' | 'json' | 'geojson' | 'geotiff' | 'heatmap' | 'join' | 'sql' | 'update' | 'drop';
423
+
424
+ /**
425
+ * Drops a table, so the sources, compute passes, maps and plots after it no longer find it, and `AutkGrammar.data` no
426
+ * longer lists it. Read by the Autark adapter only.
427
+ */
428
+ export declare interface DropSourceSpec {
429
+ type: 'drop';
430
+ /** Workspace of the table. */
431
+ workspace?: WorkspaceName;
432
+ /** The table to drop. */
433
+ dataRef: string;
434
+ }
401
435
 
402
436
  export declare type EngineOptions = {
403
437
  spec: UrbanSpec;
@@ -433,7 +467,11 @@ export declare function findIterateSource(block: GpgpuComputeSpec): {
433
467
  */
434
468
  export declare type FromFeatureDirective = {
435
469
  fromFeature: {
436
- /** Table to read from. */
470
+ /**
471
+ * Table to read from. The Autark adapter reads it as an earlier compute pass wrote it; else, when a GeoJSON source
472
+ * loaded it with its coordinates in its workspace's CRS, as the source gave its features, each building part with
473
+ * its own outline; else as autk-db keeps it, a buildings table's geometry inside a GeometryCollection.
474
+ */
437
475
  layer: string;
438
476
  /** Dot path from the feature root, for example `properties.height` or `geometry.coordinates.0`. */
439
477
  path: string;
@@ -589,6 +627,12 @@ export declare interface HeatmapSourceSpec extends TableSourceBase {
589
627
  column: string;
590
628
  /** How the rows combine into the cell's value: any aggregate but `collect`, which lists rows, while a cell holds one value. */
591
629
  aggregateFn?: HeatmapAggregateFunction;
630
+ /**
631
+ * Rescale the band's values from 0 to 1 across the grid's cells. It needs an autk-db with
632
+ * urban-toolkit/autark#132, which also adds `_norm` to the band's label; autk-db 4.1.1 builds the band from the
633
+ * values as they are.
634
+ */
635
+ normalize?: boolean;
592
636
  }>;
593
637
  /** Grid resolution. */
594
638
  grid: {
@@ -877,6 +921,13 @@ export declare type MapLayerSpec = {
877
921
  * @minItems 1
878
922
  */
879
923
  selectFields?: string[];
924
+ /**
925
+ * Draw an OpenStreetMap layer table as one feature per OSM element it was built from, each with the element's tags,
926
+ * `osm_type` and `osm_id` as its properties (and `building_id` in a buildings table, whose parts are elements of
927
+ * their own), rather than one feature per row. A table that is not an OSM layer, a surface, and an OSM table an
928
+ * update changed are drawn row by row, as without it. Read by the Autark adapter only.
929
+ */
930
+ osmElements?: boolean;
880
931
  /** Dot path to the thematic value, relative to `feature.properties` (for example `tags.highway` or `compute.result`). */
881
932
  getFnv?: string;
882
933
  /** `categorical` reads the value as a string for discrete palettes; `quantitative` reads it as a number for continuous scales. Read by the deck.gl adapter; the Autark adapter ignores it. */
@@ -943,15 +994,36 @@ export declare interface OsmBoundingBoxArea {
943
994
 
944
995
  /**
945
996
  * Loads OpenStreetMap data for a named area or a box, from Overpass or from a PBF extract.
997
+ * @if { "required": ["pbfFileUrl"] }
998
+ * @then { "not": { "required": ["tagSets"], "properties": { "tagSets": { "minItems": 1 } } } }
946
999
  */
947
1000
  export declare interface OsmDataSourceSpec extends TableSourceBase {
948
1001
  type: 'osm';
949
1002
  /** URL of a local or remote `.osm.pbf` extract to read instead of querying Overpass. */
950
1003
  pbfFileUrl?: string;
1004
+ /**
1005
+ * Features chosen by their tags, each set as a table of its own, `<outputTableName>_<name>_<type>`, cut to the
1006
+ * area. A set that matches no feature in the area makes no table. Read from the Overpass API only: a source with
1007
+ * `pbfFileUrl` cannot take them. Read by the Autark adapter only.
1008
+ * @maxItems 8
1009
+ */
1010
+ tagSets?: OsmTagSet[];
1011
+ /**
1012
+ * Query the Overpass API again rather than read the answer the browser cached for this area, its layers and its tag
1013
+ * sets, which autk-db keeps for 24 hours. A source with `pbfFileUrl` reads its file each time and ignores it. Read
1014
+ * by the Autark adapter only.
1015
+ */
1016
+ forceRefresh?: boolean;
951
1017
  /** Split the raw OSM table into one table per layer, named `<outputTableName>_<layer>`. */
952
1018
  autoLoadLayers?: {
953
1019
  /** Currently ignored by both adapters. */
954
1020
  dropOsmTable?: boolean;
1021
+ /**
1022
+ * CRS of the OpenStreetMap data's coordinates, as an EPSG string. Defaults to `'EPSG:4326'`, the degrees the
1023
+ * Overpass API and OpenStreetMap's extracts give. The layers and the tag sets are read in it. Read by the Autark
1024
+ * adapter only.
1025
+ */
1026
+ coordinateFormat?: string;
955
1027
  layers: Array<LayerType>;
956
1028
  };
957
1029
  /** Area to load: sub-areas inside a geocoded region (`geocodeArea` with `areas`), or a box (`bbox`), not both. */
@@ -970,6 +1042,49 @@ export declare interface OsmNamedArea {
970
1042
  bbox?: undefined;
971
1043
  }
972
1044
 
1045
+ /**
1046
+ * An OpenStreetMap tag a tag set matches: the tag `key` with the value `value`, or with any value when `value` is
1047
+ * omitted.
1048
+ */
1049
+ export declare type OsmTagFilter = {
1050
+ /**
1051
+ * The tag's key, such as `amenity` or `addr:street`: letters, digits, `_`, `:`, `.` and `-`, starting with a letter
1052
+ * or a digit.
1053
+ * @pattern ^[A-Za-z0-9][A-Za-z0-9_:.-]{0,254}$
1054
+ */
1055
+ key: string;
1056
+ /**
1057
+ * The tag's value, such as `cafe`. Without it, the key with any value matches.
1058
+ * @minLength 1
1059
+ * @maxLength 255
1060
+ */
1061
+ value?: string;
1062
+ };
1063
+
1064
+ /**
1065
+ * OpenStreetMap features chosen by their tags, as one table of one geometry type.
1066
+ */
1067
+ export declare type OsmTagSet = {
1068
+ /**
1069
+ * Names the set's table, `<outputTableName>_<name>_<type>`: a lowercase letter, then up to 31 lowercase letters,
1070
+ * digits or `_`. No two sets of a source share a name.
1071
+ * @pattern ^[a-z][a-z0-9_]{0,31}$
1072
+ */
1073
+ name: string;
1074
+ /**
1075
+ * The geometry the table holds: `points`, the tagged nodes; `polylines`, the open ways and the ways tagged as
1076
+ * lines (`highway`, `barrier`, `railway`, `waterway`, or `area=no`); `polygons`, the other closed ways and the
1077
+ * multipolygon relations.
1078
+ */
1079
+ type: 'points' | 'polylines' | 'polygons';
1080
+ /**
1081
+ * The tags a feature is chosen by: it is in the set when it has any one of them.
1082
+ * @minItems 1
1083
+ * @maxItems 64
1084
+ */
1085
+ tags: OsmTagFilter[];
1086
+ };
1087
+
973
1088
  /** Parallel coordinates over the plotted columns. */
974
1089
  export declare interface ParallelCoordinatesPlotSpec extends PlotBase {
975
1090
  mark: 'parallel-coordinates';
@@ -1004,7 +1119,79 @@ export declare interface PlotBase {
1004
1119
  * @minItems 1
1005
1120
  */
1006
1121
  axis: string[];
1122
+ /**
1123
+ * Column whose values color the marks: a scatter plot's points, a bar chart's bars, and the lines of parallel
1124
+ * coordinates, which a click on an axis's title colors by that axis instead. When every value is a number, or a
1125
+ * string that reads as one, the marks take `colorMapInterpolator`'s scheme; otherwise the values are categories,
1126
+ * and take `categoricalColorMapInterpolator`'s. A heat matrix colors its cells by their values, which `@transform`
1127
+ * names. Line charts and tables color no mark by value.
1128
+ */
1007
1129
  color?: string;
1130
+ /**
1131
+ * Color scheme of marks colored by numbers: a sequential or diverging `interpolate*` scheme, `interpolateReds` by
1132
+ * default. The scale's low end takes the scheme's first color and its high end its last: the lowest and highest
1133
+ * values, unless `colorMapRange` or `normalization` sets them. A categorical `scheme*` name is refused, since
1134
+ * categories take `categoricalColorMapInterpolator`. Read by the Autark adapter; the deck.gl adapter ignores it.
1135
+ */
1136
+ colorMapInterpolator?: ContinuousColorMapInterpolator;
1137
+ /**
1138
+ * Color scheme of marks colored by categories: a categorical `scheme*` scheme, `schemeObservable10` by default.
1139
+ * The categories take the scheme's colors in the order they first appear, or in `colorMapDomain`'s order, and those
1140
+ * past the scheme's last color take that one. A sequential or diverging `interpolate*` name is refused. Read by the
1141
+ * Autark adapter; the deck.gl adapter ignores it.
1142
+ */
1143
+ categoricalColorMapInterpolator?: CategoricalColorMapInterpolator;
1144
+ /**
1145
+ * How the ends of the color scale of numbers are found: `minMax`, the default, takes the lowest and highest
1146
+ * values; `percentile` takes the values at the `lowerPercentile` and `upperPercentile` percentiles, 2 and 98 when
1147
+ * it gives neither, else 0 and 100 for the one it leaves out. Categories ignore it. A map layer's `normalization`
1148
+ * reads the same way. Read by the Autark adapter; the deck.gl adapter ignores it.
1149
+ */
1150
+ normalization?: MapLayerSpec['normalization'];
1151
+ /**
1152
+ * Ends of the color scale of numbers, as `[low, high]` with low less than high. The plot is colored over this range
1153
+ * instead of its lowest and highest values, so plots and map layers that set the same range color the same value
1154
+ * alike. Values that are categories ignore it, as a layer with a categorical scheme does, and it cannot be set with
1155
+ * `colorMapDomain`. Read by the Autark adapter; the deck.gl adapter ignores it.
1156
+ * @uniqueItems true
1157
+ */
1158
+ colorMapRange?: [low: number, high: number];
1159
+ /**
1160
+ * Categories the plot is colored over, in order: the first takes the categorical scheme's first color, and so on.
1161
+ * The values are read as categories, numbers too, and a mark whose value is not among them is drawn in the mark
1162
+ * color. It cannot be set with `colorMapRange`. Read by the Autark adapter; the deck.gl adapter ignores it.
1163
+ */
1164
+ colorMapDomain?: string[];
1165
+ /**
1166
+ * Color of the marks that are neither colored by value nor selected, as `#rrggbb`: `#bfbfbf` by default. autk-plot
1167
+ * keeps one mark color for the page, so every plot it draws there takes it: a run refuses two plots that set
1168
+ * different ones, and a run whose plots set none gives back autk-plot's. Read by the Autark adapter; the deck.gl
1169
+ * adapter ignores it.
1170
+ */
1171
+ markColor?: HexColor;
1172
+ /**
1173
+ * Color of the selected marks, and of a table's selected rows, as `#rrggbb`: `#5dade2` by default. autk-plot keeps
1174
+ * one highlight color for the page, so every plot it draws there takes it: a run refuses two plots that set
1175
+ * different ones, and a run whose plots set none gives back autk-plot's. Read by the Autark adapter; the deck.gl
1176
+ * adapter ignores it.
1177
+ */
1178
+ highlightColor?: HexColor;
1179
+ /**
1180
+ * d3-format specifiers of the tick labels of the plot's axes, `[x, y]`: a scatter plot's x and y axes; a bar or line
1181
+ * chart's x axis, for labels that read as numbers, and its y axis; and every axis of numbers of parallel coordinates,
1182
+ * which read only the first. Heat matrices and tables ignore it. Without it, `['~s', '~s']`. Read by the Autark
1183
+ * adapter; the deck.gl adapter ignores it.
1184
+ */
1185
+ tickFormats?: [x: TickFormat, y: TickFormat];
1186
+ /**
1187
+ * Titles of the plot's axes, in the order of `axis`, in place of the column names: the x and y axes' titles of a
1188
+ * scatter plot, a bar chart, a line chart and a heat matrix, each axis's title of parallel coordinates, and a table's
1189
+ * column headers. An axis without a title keeps its column's name, and an axis that holds a transform's output,
1190
+ * `@transform`, is titled `value`. A run refuses more titles than `axis` has columns, and two titles alike, since a
1191
+ * table finds the column to sort by its header. Read by the Autark adapter; the deck.gl adapter ignores it.
1192
+ * @uniqueItems true
1193
+ */
1194
+ axisLabels?: string[];
1008
1195
  title?: string;
1009
1196
  /** Interactions the plot emits. */
1010
1197
  events?: PlotEvent[];
@@ -1025,6 +1212,21 @@ export declare interface PlotBase {
1025
1212
  };
1026
1213
  /** `dataRef` of the map layer this plot links its selection to. A shorthand for a link in `links`. */
1027
1214
  mapRef?: string;
1215
+ /**
1216
+ * Rows selected when the plot is drawn, by their positions among the rows it draws, as `plot:selection` events and
1217
+ * `setPlotSelection` name them. The plot draws them in its highlight color (a binned plot, the bins that hold them),
1218
+ * and the map layers it is linked to, by `mapRef` or `links`, highlight the same rows, as after `setPlotSelection`.
1219
+ * No `plot:selection` event reports it. A run refuses a position past the plot's last row. Read by the Autark
1220
+ * adapter; the deck.gl adapter ignores it.
1221
+ */
1222
+ selection?: RowPosition[];
1223
+ /**
1224
+ * Plot an OpenStreetMap layer table as one row per OSM element it was built from, each with the element's tags,
1225
+ * `osm_type` and `osm_id` (and `building_id` in a buildings table), rather than one row per table row. A table that
1226
+ * is not an OSM layer, a surface, and an OSM table an update changed are plotted row by row, as without it. Read by
1227
+ * the Autark adapter only.
1228
+ */
1229
+ osmElements?: boolean;
1028
1230
  }
1029
1231
 
1030
1232
  /** Interaction a plot emits. */
@@ -1038,6 +1240,8 @@ export declare type PlotRegistry = Map<string, AutkPlot>;
1038
1240
  /**
1039
1241
  * A plot view. The `mark` field selects which transforms apply.
1040
1242
  * @discriminator mark
1243
+ * @if { "required": ["colorMapRange"] }
1244
+ * @then { "not": { "required": ["colorMapDomain"] } }
1041
1245
  */
1042
1246
  export declare type PlotSpec = ScatterPlotSpec | BarPlotSpec | LinePlotSpec | ParallelCoordinatesPlotSpec | TablePlotSpec | HeatmatrixPlotSpec;
1043
1247
 
@@ -1210,6 +1414,13 @@ export declare function resolveUniformMatrices(matrices: Record<string, MatrixEn
1210
1414
  */
1211
1415
  export declare function resolveUniforms(uniforms: Record<string, UniformEntry> | undefined, layers: ComputeLayers, iterateIndex?: number): Record<string, number> | undefined;
1212
1416
 
1417
+ /**
1418
+ * A row of a table as a view draws it: its position among the rows the view draws, from 0.
1419
+ * @minimum 0
1420
+ * @multipleOf 1
1421
+ */
1422
+ declare type RowPosition = number;
1423
+
1213
1424
  /**
1214
1425
  * Runs a compute pass. Without iteration, or with `batched`, that is one dispatch. With `all` it is
1215
1426
  * one dispatch per feature of the iterated layer, and each output column holds the sum over them.
@@ -1227,6 +1438,26 @@ export declare interface ScatterPlotSpec extends PlotBase {
1227
1438
  transform?: PlotTransformSpec;
1228
1439
  }
1229
1440
 
1441
+ /**
1442
+ * Saves the rows of a SQL query over the workspace's tables as a new table. Read by the Autark adapter only.
1443
+ */
1444
+ export declare interface SqlSourceSpec extends TableSourceBase {
1445
+ type: 'sql';
1446
+ /**
1447
+ * A `SELECT`, or a `WITH` query that ends in one, in DuckDB's SQL, over the tables of the source's workspace by their
1448
+ * names. autk-db refuses any other statement, and any query in which `insert`, `update`, `delete`, `create`,
1449
+ * `alter`, `drop`, `truncate` or `replace` appears as a word, even inside a string.
1450
+ * @minLength 1
1451
+ */
1452
+ query: string;
1453
+ /**
1454
+ * How a map draws the new table, whose geometry must then be in a column named `geometry`, in the workspace's CRS,
1455
+ * as the workspace's tables hold it. Without it, the table has no layer type: a plot draws its rows, while a map
1456
+ * does not draw it and `AutkGrammar.data` does not list it.
1457
+ */
1458
+ layerType?: LayerType;
1459
+ }
1460
+
1230
1461
  /**
1231
1462
  * The storage buffer binding every WebGPU device supports: the default
1232
1463
  * `maxStorageBufferBindingSize`, 128 MiB. autk-compute 4 reads each array a `batched` directive
@@ -1282,8 +1513,52 @@ export declare type Targets = {
1282
1513
  plot?: string[] | string;
1283
1514
  };
1284
1515
 
1516
+ /**
1517
+ * A d3-format specifier, such as `~s`, `,d`, `.2f` or `.0%`: d3-format's
1518
+ * `[[fill]align][sign][symbol][0][width][,][.precision][~][type]`.
1519
+ * @pattern ^(?:.?[<>=^])?[-+( ]?[$#]?0?\d*,?(?:\.\d+)?~?[a-zA-Z%]?$
1520
+ */
1521
+ declare type TickFormat = string;
1522
+
1285
1523
  declare type UniformEntry = number | FromFeatureDirective;
1286
1524
 
1525
+ /**
1526
+ * Replaces or changes the rows of a table already loaded, with rows given inline: a FeatureCollection for a table with
1527
+ * a geometry, an array of objects for a table without one. Read by the Autark adapter only.
1528
+ * @if { "required": ["geojsonObject"] }
1529
+ * @then { "not": { "required": ["jsonObject"] }, "if": { "required": ["strategy"], "properties": { "strategy": { "const": "update" } } }, "then": { "required": ["idColumn"] } }
1530
+ * @else { "required": ["jsonObject"], "if": { "required": ["strategy"], "properties": { "strategy": { "const": "update" } } }, "then": { "required": ["idColumn"] } }
1531
+ */
1532
+ export declare interface UpdateSourceSpec {
1533
+ type: 'update';
1534
+ /** Workspace of the table. */
1535
+ workspace?: WorkspaceName;
1536
+ /** The table to change. */
1537
+ dataRef: string;
1538
+ /**
1539
+ * `replace` swaps every row of the table for the given rows. `update` changes the rows whose `idColumn` value a
1540
+ * given row has: in a table with a geometry, each takes the given row's geometry and properties, and no row is
1541
+ * added; in a table without one, the given rows replace them, and those that match no row are added.
1542
+ */
1543
+ strategy: 'replace' | 'update';
1544
+ /**
1545
+ * With `update`, the column that matches a given row to the table's rows: a column such as `month`, or a feature
1546
+ * property as `properties.<name>`, such as `properties.parcel_id`.
1547
+ * @minLength 1
1548
+ */
1549
+ idColumn?: string;
1550
+ /**
1551
+ * The rows of a table with a geometry. autk-db stores their coordinates as they come, so they are in the
1552
+ * workspace's CRS, as `AutkGrammar.data` gives a table's features.
1553
+ */
1554
+ geojsonObject?: InlineFeatureCollection;
1555
+ /**
1556
+ * The rows of a table without a geometry, such as a CSV or JSON table loaded without `geometryColumns`.
1557
+ * @minItems 1
1558
+ */
1559
+ jsonObject?: Array<Record<string, unknown>>;
1560
+ }
1561
+
1287
1562
  /**
1288
1563
  * An Autark grammar specification. It names at least one of `data`, `compute`, `map` or `plot`.
1289
1564
  */
@@ -1292,6 +1567,11 @@ export declare type UrbanSpec = {
1292
1567
  $schema?: string;
1293
1568
  /** How the host arranges the maps and plots. */
1294
1569
  layout?: LayoutSpec;
1570
+ /**
1571
+ * How workspaces store their tables, one entry per workspace, set before the first source loads. A workspace
1572
+ * without an entry keeps autk-db's CRS and grid. Read by the Autark adapter only.
1573
+ */
1574
+ workspaces?: WorkspaceSpec[];
1295
1575
  /** Tables to load, in order. */
1296
1576
  data?: DataSourceSpec[];
1297
1577
  /** Compute passes, run in order after the data is loaded. */
@@ -1365,4 +1645,26 @@ export declare type WktGeometryColumns = {
1365
1645
  */
1366
1646
  export declare type WorkspaceName = string;
1367
1647
 
1648
+ /**
1649
+ * How a workspace stores its tables: the coordinate system they are kept in, and the grid their coordinates are rounded
1650
+ * to. Read by the Autark adapter only.
1651
+ */
1652
+ export declare type WorkspaceSpec = {
1653
+ /** The workspace, by the name sources, compute passes, maps and plots give as their `workspace`. Without it, the default workspace. */
1654
+ name?: WorkspaceName;
1655
+ /**
1656
+ * CRS the workspace stores its tables in, as an EPSG string such as `'EPSG:3857'`. Each source is transformed to
1657
+ * it as it loads, its maps draw in its units, and so are the lengths given in workspace units, such as a join's
1658
+ * `near.distance`. autk-db's default is `'EPSG:3395'`, World Mercator, in meters.
1659
+ * @minLength 1
1660
+ */
1661
+ coordinateFormat: string;
1662
+ /**
1663
+ * Grid every stored coordinate is rounded to, in the CRS's units. autk-db's default is `0.01`, a centimeter in World
1664
+ * Mercator. A geometry the grid collapses is refused as it loads.
1665
+ * @exclusiveMinimum 0
1666
+ */
1667
+ precisionGrid: number;
1668
+ };
1669
+
1368
1670
  export { }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@urban-toolkit/autk-grammar",
3
- "version": "5.0.0",
3
+ "version": "5.2.0",
4
4
  "description": "A declarative grammar for urban visual analytics, built on Autark",
5
5
  "license": "MIT",
6
6
  "author": "Gustavo Moreira",