@emuanalytics/flow-rdf-core 4.2.0 → 4.3.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.mts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as Annotation, F as FlowStyleLayerType, a as FlowLayerStyleBuilder, b as FlowStyleDataDriven, c as FlowStyleIssue, M as MapStyleSpecification, S as StateStore, d as MapDataSource, e as MapLayer, f as FlowContextOptions, g as FlowContext } from './shared/flow-rdf-core.c45eb675.mjs';
2
- export { N as BackgroundLayerStyleBuilder, G as CircleLayerStyleBuilder, D as DEFAULT_CONTEXT_ID, aa as FeatureStreamOptions, I as FillExtrusionLayerStyleBuilder, C as FillLayerStyleBuilder, h as FlowCoreError, l as FlowCoreExpressionCustomFunction, m as FlowCoreExpressionCustomFunctionSignature, n as FlowCoreExpressionCustomFunctions, i as FlowCoreExpressionError, ac as FlowCoreMap, z as FlowEngineEndpoint, j as FlowMapError, s as FlowStyle, t as FlowStyleDataDrivenOptions, u as FlowStyleExpression, v as FlowStyleNamedSize, w as FlowStyleProperty, x as FlowStyleSize, y as FlowValue, H as HeatmapLayerStyleBuilder, K as HillshadeLayerStyleBuilder, L as LineLayerStyleBuilder, a3 as MapAnimationOptions, a4 as MapCenterOptions, a0 as MapDataSourceOptions, a1 as MapDataSourceSpecification, $ as MapDataSourceType, af as MapEvent, ae as MapEventType, ad as MapEventTypes, a5 as MapFeature, a6 as MapFeatureIdentifier, a9 as MapFeatureStream, a2 as MapGeojsonData, Y as MapLayerExpression, W as MapLayerOptions, _ as MapLayerPropertyMetadataIndex, Z as MapLayerSpecification, T as MapLayerStyleBuilder, B as MapLayerType, ai as MapLoadingEvent, ag as MapMouseEvent, ab as MapOptions, a7 as MapPaddingOptions, am as MapPopup, al as MapPopupOptions, ak as MapPopupTemplateFn, k as MapRegistry, ah as MapSourceEvent, a8 as MapSourceIdentifier, aj as MapStyleChangeEvent, X as MapSubLayerOptions, P as ParserExpression, o as ParserExpressionWithIndex, p as ParserFunctionExpression, q as ParserIndex, r as ParserProgram, aC as Path, aD as PathValue, an as Query, as as QueryAttribute, ax as QueryDefinition, az as QueryDefinitionFn, au as QueryExtraParams, ay as QueryOptions, av as QueryOrderClause, Q as QueryRegistry, ar as QueryResultFormat, aA as QueryResultTransformFn, aw as QuerySampleOptions, at as QueryWhereClauses, J as RasterLayerStyleBuilder, R as ReactiveExpression, aG as SerializationFormat, aF as StoreAnnotations, aE as StoreConstructor, U as StyleExpression, E as SymbolLayerStyleBuilder, V as expr, O as layerStyle, ao as query, ap as queryMany, aq as queryOne, aB as traceReaction } from './shared/flow-rdf-core.c45eb675.mjs';
1
+ import { A as Annotation, C as CompositeLayerSpecBuilder, a as CompositeLayerSpecification, F as FlowStyle, b as FlowStyleIssue, c as FlowStyleLayerType, d as FlowLayerStyleBuilder, e as FlowStyleDataDriven, M as MapDataSource, f as MapStyleSpecification, S as StateStore, g as MapLayer, h as FlowContextOptions, i as FlowContext } from './shared/flow-rdf-core.62a36d8b.mjs';
2
+ export { X as BackgroundLayerStyleBuilder, O as CircleLayerStyleBuilder, u as CompositeDataSourceSpecification, a1 as CompositeLayerOptions, v as CompositeSubLayerBase, w as CompositeSubLayerSpecification, x as CompositeSubLayerSpecificationV1, D as DEFAULT_CONTEXT_ID, aj as FeatureStreamOptions, U as FillExtrusionLayerStyleBuilder, K as FillLayerStyleBuilder, j as FlowCoreError, n as FlowCoreExpressionCustomFunction, o as FlowCoreExpressionCustomFunctionSignature, p as FlowCoreExpressionCustomFunctions, k as FlowCoreExpressionError, al as FlowCoreMap, I as FlowEngineEndpoint, l as FlowMapError, y as FlowStyleDataDrivenOptions, z as FlowStyleExpression, B as FlowStyleNamedSize, E as FlowStyleProperty, G as FlowStyleSize, H as FlowValue, T as HeatmapLayerStyleBuilder, W as HillshadeLayerStyleBuilder, L as LineLayerStyleBuilder, ac as MapAnimationOptions, ad as MapCenterOptions, a7 as MapDataSourceOptions, aa as MapDataSourceSpecification, a6 as MapDataSourceType, ao as MapEvent, an as MapEventType, am as MapEventTypes, ae as MapFeature, af as MapFeatureIdentifier, ai as MapFeatureStream, ab as MapGeojsonData, a3 as MapLayerExpression, a0 as MapLayerOptions, a5 as MapLayerPropertyMetadataIndex, a4 as MapLayerSpecification, Z as MapLayerStyleBuilder, J as MapLayerType, ar as MapLoadingEvent, ap as MapMouseEvent, ak as MapOptions, ag as MapPaddingOptions, av as MapPopup, au as MapPopupOptions, at as MapPopupTemplateFn, m as MapRegistry, aq as MapSourceEvent, ah as MapSourceIdentifier, as as MapStyleChangeEvent, a2 as MapSubLayerOptions, P as ParserExpression, q as ParserExpressionWithIndex, r as ParserFunctionExpression, s as ParserIndex, t as ParserProgram, aL as Path, aM as PathValue, aw as Query, aB as QueryAttribute, aG as QueryDefinition, aI as QueryDefinitionFn, aD as QueryExtraParams, aH as QueryOptions, aE as QueryOrderClause, Q as QueryRegistry, aA as QueryResultFormat, aJ as QueryResultTransformFn, aF as QuerySampleOptions, aC as QueryWhereClauses, V as RasterLayerStyleBuilder, R as ReactiveExpression, a8 as SelectionMode, a9 as SelectionOptions, aP as SerializationFormat, aO as StoreAnnotations, aN as StoreConstructor, _ as StyleExpression, N as SymbolLayerStyleBuilder, $ as expr, Y as layerStyle, ax as query, ay as queryMany, az as queryOne, aK as traceReaction } from './shared/flow-rdf-core.62a36d8b.mjs';
3
3
  export { IDisposer, IObservableStream, ISubscription } from 'mobx-utils';
4
4
  export { makeAutoObservable, makeObservable } from 'mobx';
5
5
  import 'eventemitter3';
@@ -43,6 +43,157 @@ declare const computed: PropertyDecorator & ReactiveAnnotation & {
43
43
  /** @function */
44
44
  declare const action: PropertyDecorator & ReactiveAnnotation;
45
45
 
46
+ /**
47
+ * Creates a builder for a version 2 {@link CompositeLayerSpecification}: a composite layer's sub-layers and data
48
+ * sources, in its stored format.
49
+ *
50
+ * Add data sources with `dataSource()` and sub-layers with `layer()`, bottom to top. A sub-layer has the shape of
51
+ * `MapLayerOptions`: a flow style sub-layer is `{id, type: 'flow', source, style}` with a {@link FlowStyle}, such as one
52
+ * built with {@link flowLayerStyle}, and a MapLibre one is `{id, type, source, style}` with a MapLibre layer type and a
53
+ * style program, such as one built with {@link layerStyle}. `build()` returns a copy of the spec, with `version`,
54
+ * `layers` and `dataSources` always set; the builder copies what it's given, so changing an object after adding it
55
+ * doesn't change the spec.
56
+ *
57
+ * The builder doesn't check the spec. Use {@link validateCompositeLayer} to check the result.
58
+ *
59
+ * @example
60
+ * Airports as points with labels, and an icon for each:
61
+ * ```js
62
+ * const spec = compositeLayerSpec()
63
+ * .dataSource({ id: 'uk_airports', type: 'vector', src: 'uk_airports', featureId: 'name' })
64
+ * .layer({
65
+ * id: 'points',
66
+ * type: 'flow',
67
+ * source: 'uk_airports',
68
+ * style: flowLayerStyle('circle').radius('medium').labelText(expr('@name')).build()
69
+ * })
70
+ * .layer({ id: 'icons', type: 'symbol', source: 'uk_airports', style: layerStyle('symbol').iconImage('airport').build() })
71
+ * .build();
72
+ * ```
73
+ *
74
+ * @param options - Builder options. `version` is the stored format version to write. Defaults to `2`, the latest.
75
+ * @returns A new composite layer spec builder.
76
+ *
77
+ * @experimental
78
+ */
79
+ declare function compositeLayerSpec(options?: {
80
+ version?: 2;
81
+ }): CompositeLayerSpecBuilder;
82
+
83
+ /**
84
+ * Returns the flow style of one sub-layer of a composite layer spec, as a version 2 {@link FlowStyle}, for an editor to
85
+ * show. `undefined` when the spec has no sub-layer with that ID, or the sub-layer has a MapLibre style.
86
+ *
87
+ * A version 2 sub-layer's style is returned as it is stored. A version 1 sub-layer's style is returned in version 2
88
+ * form, with the sub-layer's geometry as `type`, so an editor reads every spec the same way: a plain value is a
89
+ * literal, and anything computed is an expression (a version 1 `@name` is the expression `@name`; a version 1
90
+ * data-driven table is an expression with the table as `dataDriven`). Each value draws what the stored one does, and
91
+ * writing it back with {@link updateCompositeFlowStyle} gives a version 1 value that draws the same. A value that
92
+ * version 2 can't write the same way becomes an expression of what version 1 draws, and an invalid value is returned
93
+ * as it is stored. Unknown keys are kept.
94
+ *
95
+ * The result is a copy: change the spec with {@link updateCompositeFlowStyle}.
96
+ *
97
+ * @example
98
+ * Showing a stored sub-layer's fill color in an editor:
99
+ * ```js
100
+ * const style = getCompositeFlowStyle(row.layerSpec, 'circle-layer');
101
+ * colorPicker.value = style?.fillColor;
102
+ * ```
103
+ *
104
+ * @param spec - Composite layer spec, version 1 or 2.
105
+ * @param layerId - Sub-layer ID.
106
+ * @returns The sub-layer's flow style in version 2 form, or `undefined`.
107
+ *
108
+ * @experimental
109
+ */
110
+ declare function getCompositeFlowStyle(spec: CompositeLayerSpecification, layerId: string): FlowStyle | undefined;
111
+ /**
112
+ * Returns a copy of a composite layer spec with one sub-layer's flow style changed. The spec isn't changed.
113
+ *
114
+ * `changes` maps flow style property names to values, which follow flow rules, as in {@link flowLayerStyle}: a plain
115
+ * value is a literal, an `expr()` value a reactive expression, and a {@link FlowStyleDataDriven} table an expression
116
+ * with the table attached. `undefined` or `null` removes the property. The style's `type` and `version` can't be
117
+ * changed: keys with those names are ignored.
118
+ *
119
+ * The style is written in its own version, which is the spec's. A version 1 sub-layer gets version 1 forms that draw
120
+ * the same as the values given (and `version: 1` in its style, which legacy ignores), so the spec still saves as version
121
+ * 1 and legacy apps still load it. Everything else in the spec, unknown keys included, is left as it was.
122
+ *
123
+ * @example
124
+ * A live preview of a new fill color, saved as the same version:
125
+ * ```js
126
+ * const edited = updateCompositeFlowStyle(layer.compositeSpec, 'circle-layer', { fillColor: '#bbff00' });
127
+ * layer.setStyle(edited);
128
+ * ```
129
+ *
130
+ * @param spec - Composite layer spec, version 1 or 2.
131
+ * @param layerId - ID of a sub-layer with a flow style.
132
+ * @param changes - Flow style property names and their new values.
133
+ * @returns The edited copy of the spec.
134
+ * @throws {@link FlowCoreError} if the spec has no sub-layer with that ID, or the sub-layer has a MapLibre style.
135
+ *
136
+ * @experimental
137
+ */
138
+ declare function updateCompositeFlowStyle(spec: CompositeLayerSpecification, layerId: string, changes: Record<string, unknown>): CompositeLayerSpecification;
139
+ /**
140
+ * Returns a copy of a composite layer spec with one sub-layer's filter changed. The spec isn't changed.
141
+ *
142
+ * The filter is a reactive expression, which the composite layer ANDs with its own filter. `null` or an empty string
143
+ * removes it. The filter isn't checked: {@link validateCompositeLayer} reports a filter that doesn't parse. Everything
144
+ * else in the spec, its version and unknown keys included, is left as it was.
145
+ *
146
+ * @example
147
+ * Showing only some features of a sub-layer:
148
+ * ```js
149
+ * const edited = setCompositeSubLayerFilter(layer.compositeSpec, 'fill-layer', 'in(@ogc_fid, literal([1, 2, 3]))');
150
+ * ```
151
+ *
152
+ * @param spec - Composite layer spec, version 1 or 2.
153
+ * @param layerId - Sub-layer ID.
154
+ * @param filter - Reactive expression, or `null` or `''` for no filter.
155
+ * @returns The edited copy of the spec.
156
+ * @throws {@link FlowCoreError} if the spec has no sub-layer with that ID.
157
+ *
158
+ * @experimental
159
+ */
160
+ declare function setCompositeSubLayerFilter(spec: CompositeLayerSpecification, layerId: string, filter: string | null): CompositeLayerSpecification;
161
+
162
+ /**
163
+ * Checks a composite layer spec and returns its problems. Use it on a spec read from storage or written by hand, before
164
+ * showing it in an editor or to report why a composite layer doesn't draw what you expect.
165
+ *
166
+ * It accepts version 2 specs and version 1 specs, the legacy stored format (see {@link CompositeLayerSpecification}).
167
+ * A spec with no `version` is version 1. Flow-style sub-layers are checked with {@link validateFlowStyle}: in version 1
168
+ * with the sub-layer's `type` as their geometry. MapLibre-style sub-layers' style programs and every filter are parsed.
169
+ *
170
+ * Each issue's path starts at the spec, such as `layers[1].style.fillColor` or `dataSources[0].src`. An `error` means
171
+ * that part isn't rendered: the whole composite layer when the path is empty or `version`, a sub-layer when it's the
172
+ * sub-layer's `id`, `type`, `source` or `style` (a flow style's own errors leave out only the property), and a data
173
+ * source when it's the source's `id`, `type` or `src`. A `warning` means it's rendered anyway: unknown keys, for
174
+ * example, are kept and reported as warnings.
175
+ *
176
+ * A sub-layer's `source` that isn't in the spec's `dataSources` is a warning, because it may name a data source the
177
+ * application has added to the map. The composite layer reports it as an error when the data source isn't on the map.
178
+ *
179
+ * This function never throws.
180
+ *
181
+ * @example
182
+ * Checking a spec read from storage:
183
+ * ```js
184
+ * const issues = validateCompositeLayer(row.layerSpec);
185
+ * if (issues.some((issue) => issue.severity === 'error')) {
186
+ * console.warn(issues);
187
+ * }
188
+ * ```
189
+ *
190
+ * @param spec - Composite layer spec to check, of any type.
191
+ * @returns The problems found, or an empty array.
192
+ *
193
+ * @experimental
194
+ */
195
+ declare function validateCompositeLayer(spec: unknown): FlowStyleIssue[];
196
+
46
197
  /**
47
198
  * Creates a builder for a {@link FlowStyle}, as {@link layerStyle} does for MapLibre styles.
48
199
  *
@@ -137,11 +288,30 @@ declare function validateFlowStyle(style: unknown): FlowStyleIssue[];
137
288
  interface MapStyleOptions {
138
289
  id: string;
139
290
  }
291
+ /**
292
+ * What a map does as {@link MapStyle} adds and removes the data sources that layers bring (see
293
+ * {@link MapLayer.setOwnedSources}).
294
+ *
295
+ * @internal
296
+ */
297
+ interface OwnedSourceHooks {
298
+ /** Prepares a new source before it's added: the map gives it its Flo.w endpoint. */
299
+ prepare?(source: MapDataSource): void;
300
+ /**
301
+ * Called before and after each source is added or removed, inside the MobX action that changes the style: the map
302
+ * emits its source events, so plugins see the sources come and go.
303
+ */
304
+ event?(type: 'beforeSourceAdded' | 'sourceAdded' | 'beforeSourceRemoved' | 'sourceRemoved', id: string): void;
305
+ }
140
306
  declare class MapStyle {
141
307
  private static _defaultBaseStyle;
142
308
  private _state;
143
309
  private _baseStyle;
310
+ private _hooks;
144
311
  private _sources;
312
+ private _ownedSources;
313
+ private _ownedSourceOptions;
314
+ private _ownedSourceDisposers;
145
315
  private _layers;
146
316
  private _layerOrder;
147
317
  get styleSpecification(): MapStyleSpecification;
@@ -162,17 +332,50 @@ declare class MapStyle {
162
332
  /** The style specification, the problems found while building it, and which MapLayer rendered each MapLibre layer. */
163
333
  private get renderedStyle();
164
334
  get formattedName(): string;
165
- constructor();
335
+ /**
336
+ * Each map creates its own map style, with hooks of its own.
337
+ *
338
+ * @param hooks - What the map does as the style adds and removes the data sources that layers bring.
339
+ *
340
+ * @internal
341
+ */
342
+ constructor(hooks?: OwnedSourceHooks);
166
343
  bindState(state: StateStore): this;
167
344
  setBaseStyle(style?: MapStyleSpecification): this;
345
+ /**
346
+ * Adds a data source. A source that layers brought with the same ID is removed: the app's takes its place.
347
+ */
168
348
  addSource(source: MapDataSource): this;
349
+ /**
350
+ * Removes a data source, the app's or one that layers brought.
351
+ *
352
+ * @param id - Data source ID.
353
+ * @param removeLayers - Also remove the layers that display or bring the source.
354
+ * @throws {@link FlowCoreError} if there's no source with the ID, or, unless `removeLayers`, a layer displays or
355
+ * brings it.
356
+ */
169
357
  removeSource(id: string, removeLayers?: boolean): this;
358
+ /**
359
+ * Whether the source with the ID is one that layers brought (see {@link MapLayer.setOwnedSources}), rather than
360
+ * one the app added.
361
+ *
362
+ * @internal
363
+ */
364
+ isOwnedSource(id: string): boolean;
170
365
  getSource(id: string): MapDataSource;
171
366
  getSources(filter?: (source: MapDataSource) => boolean): MapDataSource[];
172
367
  addLayer(layer: MapLayer): this;
173
368
  removeLayer(id: string): this;
174
369
  getLayer(id: string): MapLayer;
175
370
  getLayers(filter?: (layer: MapLayer) => boolean): MapLayer[];
371
+ /**
372
+ * Adds and removes the sources that layers bring, so that each ID that a layer on the map brings, and that neither
373
+ * the app nor the base style has, is on the map once, with the options of the first layer added that brings it. A
374
+ * source whose options are unchanged keeps its instance, so MapLibre doesn't reload it.
375
+ */
376
+ private syncOwnedSources;
377
+ /** A problem for each layer that brings a source with options other than those of the source on the map. */
378
+ private ownedSourceConflicts;
176
379
  private duplicateIdProblem;
177
380
  /** Defaults the source layer to 'geometry' if missing and the source type is 'vector'. */
178
381
  private withDefaultSourceLayer;
@@ -218,4 +421,4 @@ declare const uninitializeContext: (contextId?: string) => void;
218
421
  /** @function */
219
422
  declare const getContext: <TState extends StateStore = StateStore>(id?: string) => Promise<FlowContext<TState>>;
220
423
 
221
- export { ContextRegistry, FlowContext, FlowContextOptions, FlowLayerStyleBuilder, FlowRdfCoreGlobals, FlowStyleDataDriven, FlowStyleIssue, FlowStyleLayerType, MapDataSource, MapLayer, MapStyle, type MapStyleOptions, MapStyleSpecification, StateStore, action, computed, dataDrivenExpression, flowLayerStyle, getContext, getGlobalState, initializeContext, isolateGlobalState, observable, serialize, uninitializeContext, validateFlowStyle };
424
+ export { CompositeLayerSpecBuilder, CompositeLayerSpecification, ContextRegistry, FlowContext, FlowContextOptions, FlowLayerStyleBuilder, FlowRdfCoreGlobals, FlowStyle, FlowStyleDataDriven, FlowStyleIssue, FlowStyleLayerType, MapDataSource, MapLayer, MapStyle, type MapStyleOptions, MapStyleSpecification, type OwnedSourceHooks, StateStore, action, compositeLayerSpec, computed, dataDrivenExpression, flowLayerStyle, getCompositeFlowStyle, getContext, getGlobalState, initializeContext, isolateGlobalState, observable, serialize, setCompositeSubLayerFilter, uninitializeContext, updateCompositeFlowStyle, validateCompositeLayer, validateFlowStyle };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { A as Annotation, F as FlowStyleLayerType, a as FlowLayerStyleBuilder, b as FlowStyleDataDriven, c as FlowStyleIssue, M as MapStyleSpecification, S as StateStore, d as MapDataSource, e as MapLayer, f as FlowContextOptions, g as FlowContext } from './shared/flow-rdf-core.c45eb675.js';
2
- export { N as BackgroundLayerStyleBuilder, G as CircleLayerStyleBuilder, D as DEFAULT_CONTEXT_ID, aa as FeatureStreamOptions, I as FillExtrusionLayerStyleBuilder, C as FillLayerStyleBuilder, h as FlowCoreError, l as FlowCoreExpressionCustomFunction, m as FlowCoreExpressionCustomFunctionSignature, n as FlowCoreExpressionCustomFunctions, i as FlowCoreExpressionError, ac as FlowCoreMap, z as FlowEngineEndpoint, j as FlowMapError, s as FlowStyle, t as FlowStyleDataDrivenOptions, u as FlowStyleExpression, v as FlowStyleNamedSize, w as FlowStyleProperty, x as FlowStyleSize, y as FlowValue, H as HeatmapLayerStyleBuilder, K as HillshadeLayerStyleBuilder, L as LineLayerStyleBuilder, a3 as MapAnimationOptions, a4 as MapCenterOptions, a0 as MapDataSourceOptions, a1 as MapDataSourceSpecification, $ as MapDataSourceType, af as MapEvent, ae as MapEventType, ad as MapEventTypes, a5 as MapFeature, a6 as MapFeatureIdentifier, a9 as MapFeatureStream, a2 as MapGeojsonData, Y as MapLayerExpression, W as MapLayerOptions, _ as MapLayerPropertyMetadataIndex, Z as MapLayerSpecification, T as MapLayerStyleBuilder, B as MapLayerType, ai as MapLoadingEvent, ag as MapMouseEvent, ab as MapOptions, a7 as MapPaddingOptions, am as MapPopup, al as MapPopupOptions, ak as MapPopupTemplateFn, k as MapRegistry, ah as MapSourceEvent, a8 as MapSourceIdentifier, aj as MapStyleChangeEvent, X as MapSubLayerOptions, P as ParserExpression, o as ParserExpressionWithIndex, p as ParserFunctionExpression, q as ParserIndex, r as ParserProgram, aC as Path, aD as PathValue, an as Query, as as QueryAttribute, ax as QueryDefinition, az as QueryDefinitionFn, au as QueryExtraParams, ay as QueryOptions, av as QueryOrderClause, Q as QueryRegistry, ar as QueryResultFormat, aA as QueryResultTransformFn, aw as QuerySampleOptions, at as QueryWhereClauses, J as RasterLayerStyleBuilder, R as ReactiveExpression, aG as SerializationFormat, aF as StoreAnnotations, aE as StoreConstructor, U as StyleExpression, E as SymbolLayerStyleBuilder, V as expr, O as layerStyle, ao as query, ap as queryMany, aq as queryOne, aB as traceReaction } from './shared/flow-rdf-core.c45eb675.js';
1
+ import { A as Annotation, C as CompositeLayerSpecBuilder, a as CompositeLayerSpecification, F as FlowStyle, b as FlowStyleIssue, c as FlowStyleLayerType, d as FlowLayerStyleBuilder, e as FlowStyleDataDriven, M as MapDataSource, f as MapStyleSpecification, S as StateStore, g as MapLayer, h as FlowContextOptions, i as FlowContext } from './shared/flow-rdf-core.62a36d8b.js';
2
+ export { X as BackgroundLayerStyleBuilder, O as CircleLayerStyleBuilder, u as CompositeDataSourceSpecification, a1 as CompositeLayerOptions, v as CompositeSubLayerBase, w as CompositeSubLayerSpecification, x as CompositeSubLayerSpecificationV1, D as DEFAULT_CONTEXT_ID, aj as FeatureStreamOptions, U as FillExtrusionLayerStyleBuilder, K as FillLayerStyleBuilder, j as FlowCoreError, n as FlowCoreExpressionCustomFunction, o as FlowCoreExpressionCustomFunctionSignature, p as FlowCoreExpressionCustomFunctions, k as FlowCoreExpressionError, al as FlowCoreMap, I as FlowEngineEndpoint, l as FlowMapError, y as FlowStyleDataDrivenOptions, z as FlowStyleExpression, B as FlowStyleNamedSize, E as FlowStyleProperty, G as FlowStyleSize, H as FlowValue, T as HeatmapLayerStyleBuilder, W as HillshadeLayerStyleBuilder, L as LineLayerStyleBuilder, ac as MapAnimationOptions, ad as MapCenterOptions, a7 as MapDataSourceOptions, aa as MapDataSourceSpecification, a6 as MapDataSourceType, ao as MapEvent, an as MapEventType, am as MapEventTypes, ae as MapFeature, af as MapFeatureIdentifier, ai as MapFeatureStream, ab as MapGeojsonData, a3 as MapLayerExpression, a0 as MapLayerOptions, a5 as MapLayerPropertyMetadataIndex, a4 as MapLayerSpecification, Z as MapLayerStyleBuilder, J as MapLayerType, ar as MapLoadingEvent, ap as MapMouseEvent, ak as MapOptions, ag as MapPaddingOptions, av as MapPopup, au as MapPopupOptions, at as MapPopupTemplateFn, m as MapRegistry, aq as MapSourceEvent, ah as MapSourceIdentifier, as as MapStyleChangeEvent, a2 as MapSubLayerOptions, P as ParserExpression, q as ParserExpressionWithIndex, r as ParserFunctionExpression, s as ParserIndex, t as ParserProgram, aL as Path, aM as PathValue, aw as Query, aB as QueryAttribute, aG as QueryDefinition, aI as QueryDefinitionFn, aD as QueryExtraParams, aH as QueryOptions, aE as QueryOrderClause, Q as QueryRegistry, aA as QueryResultFormat, aJ as QueryResultTransformFn, aF as QuerySampleOptions, aC as QueryWhereClauses, V as RasterLayerStyleBuilder, R as ReactiveExpression, a8 as SelectionMode, a9 as SelectionOptions, aP as SerializationFormat, aO as StoreAnnotations, aN as StoreConstructor, _ as StyleExpression, N as SymbolLayerStyleBuilder, $ as expr, Y as layerStyle, ax as query, ay as queryMany, az as queryOne, aK as traceReaction } from './shared/flow-rdf-core.62a36d8b.js';
3
3
  export { IDisposer, IObservableStream, ISubscription } from 'mobx-utils';
4
4
  export { makeAutoObservable, makeObservable } from 'mobx';
5
5
  import 'eventemitter3';
@@ -43,6 +43,157 @@ declare const computed: PropertyDecorator & ReactiveAnnotation & {
43
43
  /** @function */
44
44
  declare const action: PropertyDecorator & ReactiveAnnotation;
45
45
 
46
+ /**
47
+ * Creates a builder for a version 2 {@link CompositeLayerSpecification}: a composite layer's sub-layers and data
48
+ * sources, in its stored format.
49
+ *
50
+ * Add data sources with `dataSource()` and sub-layers with `layer()`, bottom to top. A sub-layer has the shape of
51
+ * `MapLayerOptions`: a flow style sub-layer is `{id, type: 'flow', source, style}` with a {@link FlowStyle}, such as one
52
+ * built with {@link flowLayerStyle}, and a MapLibre one is `{id, type, source, style}` with a MapLibre layer type and a
53
+ * style program, such as one built with {@link layerStyle}. `build()` returns a copy of the spec, with `version`,
54
+ * `layers` and `dataSources` always set; the builder copies what it's given, so changing an object after adding it
55
+ * doesn't change the spec.
56
+ *
57
+ * The builder doesn't check the spec. Use {@link validateCompositeLayer} to check the result.
58
+ *
59
+ * @example
60
+ * Airports as points with labels, and an icon for each:
61
+ * ```js
62
+ * const spec = compositeLayerSpec()
63
+ * .dataSource({ id: 'uk_airports', type: 'vector', src: 'uk_airports', featureId: 'name' })
64
+ * .layer({
65
+ * id: 'points',
66
+ * type: 'flow',
67
+ * source: 'uk_airports',
68
+ * style: flowLayerStyle('circle').radius('medium').labelText(expr('@name')).build()
69
+ * })
70
+ * .layer({ id: 'icons', type: 'symbol', source: 'uk_airports', style: layerStyle('symbol').iconImage('airport').build() })
71
+ * .build();
72
+ * ```
73
+ *
74
+ * @param options - Builder options. `version` is the stored format version to write. Defaults to `2`, the latest.
75
+ * @returns A new composite layer spec builder.
76
+ *
77
+ * @experimental
78
+ */
79
+ declare function compositeLayerSpec(options?: {
80
+ version?: 2;
81
+ }): CompositeLayerSpecBuilder;
82
+
83
+ /**
84
+ * Returns the flow style of one sub-layer of a composite layer spec, as a version 2 {@link FlowStyle}, for an editor to
85
+ * show. `undefined` when the spec has no sub-layer with that ID, or the sub-layer has a MapLibre style.
86
+ *
87
+ * A version 2 sub-layer's style is returned as it is stored. A version 1 sub-layer's style is returned in version 2
88
+ * form, with the sub-layer's geometry as `type`, so an editor reads every spec the same way: a plain value is a
89
+ * literal, and anything computed is an expression (a version 1 `@name` is the expression `@name`; a version 1
90
+ * data-driven table is an expression with the table as `dataDriven`). Each value draws what the stored one does, and
91
+ * writing it back with {@link updateCompositeFlowStyle} gives a version 1 value that draws the same. A value that
92
+ * version 2 can't write the same way becomes an expression of what version 1 draws, and an invalid value is returned
93
+ * as it is stored. Unknown keys are kept.
94
+ *
95
+ * The result is a copy: change the spec with {@link updateCompositeFlowStyle}.
96
+ *
97
+ * @example
98
+ * Showing a stored sub-layer's fill color in an editor:
99
+ * ```js
100
+ * const style = getCompositeFlowStyle(row.layerSpec, 'circle-layer');
101
+ * colorPicker.value = style?.fillColor;
102
+ * ```
103
+ *
104
+ * @param spec - Composite layer spec, version 1 or 2.
105
+ * @param layerId - Sub-layer ID.
106
+ * @returns The sub-layer's flow style in version 2 form, or `undefined`.
107
+ *
108
+ * @experimental
109
+ */
110
+ declare function getCompositeFlowStyle(spec: CompositeLayerSpecification, layerId: string): FlowStyle | undefined;
111
+ /**
112
+ * Returns a copy of a composite layer spec with one sub-layer's flow style changed. The spec isn't changed.
113
+ *
114
+ * `changes` maps flow style property names to values, which follow flow rules, as in {@link flowLayerStyle}: a plain
115
+ * value is a literal, an `expr()` value a reactive expression, and a {@link FlowStyleDataDriven} table an expression
116
+ * with the table attached. `undefined` or `null` removes the property. The style's `type` and `version` can't be
117
+ * changed: keys with those names are ignored.
118
+ *
119
+ * The style is written in its own version, which is the spec's. A version 1 sub-layer gets version 1 forms that draw
120
+ * the same as the values given (and `version: 1` in its style, which legacy ignores), so the spec still saves as version
121
+ * 1 and legacy apps still load it. Everything else in the spec, unknown keys included, is left as it was.
122
+ *
123
+ * @example
124
+ * A live preview of a new fill color, saved as the same version:
125
+ * ```js
126
+ * const edited = updateCompositeFlowStyle(layer.compositeSpec, 'circle-layer', { fillColor: '#bbff00' });
127
+ * layer.setStyle(edited);
128
+ * ```
129
+ *
130
+ * @param spec - Composite layer spec, version 1 or 2.
131
+ * @param layerId - ID of a sub-layer with a flow style.
132
+ * @param changes - Flow style property names and their new values.
133
+ * @returns The edited copy of the spec.
134
+ * @throws {@link FlowCoreError} if the spec has no sub-layer with that ID, or the sub-layer has a MapLibre style.
135
+ *
136
+ * @experimental
137
+ */
138
+ declare function updateCompositeFlowStyle(spec: CompositeLayerSpecification, layerId: string, changes: Record<string, unknown>): CompositeLayerSpecification;
139
+ /**
140
+ * Returns a copy of a composite layer spec with one sub-layer's filter changed. The spec isn't changed.
141
+ *
142
+ * The filter is a reactive expression, which the composite layer ANDs with its own filter. `null` or an empty string
143
+ * removes it. The filter isn't checked: {@link validateCompositeLayer} reports a filter that doesn't parse. Everything
144
+ * else in the spec, its version and unknown keys included, is left as it was.
145
+ *
146
+ * @example
147
+ * Showing only some features of a sub-layer:
148
+ * ```js
149
+ * const edited = setCompositeSubLayerFilter(layer.compositeSpec, 'fill-layer', 'in(@ogc_fid, literal([1, 2, 3]))');
150
+ * ```
151
+ *
152
+ * @param spec - Composite layer spec, version 1 or 2.
153
+ * @param layerId - Sub-layer ID.
154
+ * @param filter - Reactive expression, or `null` or `''` for no filter.
155
+ * @returns The edited copy of the spec.
156
+ * @throws {@link FlowCoreError} if the spec has no sub-layer with that ID.
157
+ *
158
+ * @experimental
159
+ */
160
+ declare function setCompositeSubLayerFilter(spec: CompositeLayerSpecification, layerId: string, filter: string | null): CompositeLayerSpecification;
161
+
162
+ /**
163
+ * Checks a composite layer spec and returns its problems. Use it on a spec read from storage or written by hand, before
164
+ * showing it in an editor or to report why a composite layer doesn't draw what you expect.
165
+ *
166
+ * It accepts version 2 specs and version 1 specs, the legacy stored format (see {@link CompositeLayerSpecification}).
167
+ * A spec with no `version` is version 1. Flow-style sub-layers are checked with {@link validateFlowStyle}: in version 1
168
+ * with the sub-layer's `type` as their geometry. MapLibre-style sub-layers' style programs and every filter are parsed.
169
+ *
170
+ * Each issue's path starts at the spec, such as `layers[1].style.fillColor` or `dataSources[0].src`. An `error` means
171
+ * that part isn't rendered: the whole composite layer when the path is empty or `version`, a sub-layer when it's the
172
+ * sub-layer's `id`, `type`, `source` or `style` (a flow style's own errors leave out only the property), and a data
173
+ * source when it's the source's `id`, `type` or `src`. A `warning` means it's rendered anyway: unknown keys, for
174
+ * example, are kept and reported as warnings.
175
+ *
176
+ * A sub-layer's `source` that isn't in the spec's `dataSources` is a warning, because it may name a data source the
177
+ * application has added to the map. The composite layer reports it as an error when the data source isn't on the map.
178
+ *
179
+ * This function never throws.
180
+ *
181
+ * @example
182
+ * Checking a spec read from storage:
183
+ * ```js
184
+ * const issues = validateCompositeLayer(row.layerSpec);
185
+ * if (issues.some((issue) => issue.severity === 'error')) {
186
+ * console.warn(issues);
187
+ * }
188
+ * ```
189
+ *
190
+ * @param spec - Composite layer spec to check, of any type.
191
+ * @returns The problems found, or an empty array.
192
+ *
193
+ * @experimental
194
+ */
195
+ declare function validateCompositeLayer(spec: unknown): FlowStyleIssue[];
196
+
46
197
  /**
47
198
  * Creates a builder for a {@link FlowStyle}, as {@link layerStyle} does for MapLibre styles.
48
199
  *
@@ -137,11 +288,30 @@ declare function validateFlowStyle(style: unknown): FlowStyleIssue[];
137
288
  interface MapStyleOptions {
138
289
  id: string;
139
290
  }
291
+ /**
292
+ * What a map does as {@link MapStyle} adds and removes the data sources that layers bring (see
293
+ * {@link MapLayer.setOwnedSources}).
294
+ *
295
+ * @internal
296
+ */
297
+ interface OwnedSourceHooks {
298
+ /** Prepares a new source before it's added: the map gives it its Flo.w endpoint. */
299
+ prepare?(source: MapDataSource): void;
300
+ /**
301
+ * Called before and after each source is added or removed, inside the MobX action that changes the style: the map
302
+ * emits its source events, so plugins see the sources come and go.
303
+ */
304
+ event?(type: 'beforeSourceAdded' | 'sourceAdded' | 'beforeSourceRemoved' | 'sourceRemoved', id: string): void;
305
+ }
140
306
  declare class MapStyle {
141
307
  private static _defaultBaseStyle;
142
308
  private _state;
143
309
  private _baseStyle;
310
+ private _hooks;
144
311
  private _sources;
312
+ private _ownedSources;
313
+ private _ownedSourceOptions;
314
+ private _ownedSourceDisposers;
145
315
  private _layers;
146
316
  private _layerOrder;
147
317
  get styleSpecification(): MapStyleSpecification;
@@ -162,17 +332,50 @@ declare class MapStyle {
162
332
  /** The style specification, the problems found while building it, and which MapLayer rendered each MapLibre layer. */
163
333
  private get renderedStyle();
164
334
  get formattedName(): string;
165
- constructor();
335
+ /**
336
+ * Each map creates its own map style, with hooks of its own.
337
+ *
338
+ * @param hooks - What the map does as the style adds and removes the data sources that layers bring.
339
+ *
340
+ * @internal
341
+ */
342
+ constructor(hooks?: OwnedSourceHooks);
166
343
  bindState(state: StateStore): this;
167
344
  setBaseStyle(style?: MapStyleSpecification): this;
345
+ /**
346
+ * Adds a data source. A source that layers brought with the same ID is removed: the app's takes its place.
347
+ */
168
348
  addSource(source: MapDataSource): this;
349
+ /**
350
+ * Removes a data source, the app's or one that layers brought.
351
+ *
352
+ * @param id - Data source ID.
353
+ * @param removeLayers - Also remove the layers that display or bring the source.
354
+ * @throws {@link FlowCoreError} if there's no source with the ID, or, unless `removeLayers`, a layer displays or
355
+ * brings it.
356
+ */
169
357
  removeSource(id: string, removeLayers?: boolean): this;
358
+ /**
359
+ * Whether the source with the ID is one that layers brought (see {@link MapLayer.setOwnedSources}), rather than
360
+ * one the app added.
361
+ *
362
+ * @internal
363
+ */
364
+ isOwnedSource(id: string): boolean;
170
365
  getSource(id: string): MapDataSource;
171
366
  getSources(filter?: (source: MapDataSource) => boolean): MapDataSource[];
172
367
  addLayer(layer: MapLayer): this;
173
368
  removeLayer(id: string): this;
174
369
  getLayer(id: string): MapLayer;
175
370
  getLayers(filter?: (layer: MapLayer) => boolean): MapLayer[];
371
+ /**
372
+ * Adds and removes the sources that layers bring, so that each ID that a layer on the map brings, and that neither
373
+ * the app nor the base style has, is on the map once, with the options of the first layer added that brings it. A
374
+ * source whose options are unchanged keeps its instance, so MapLibre doesn't reload it.
375
+ */
376
+ private syncOwnedSources;
377
+ /** A problem for each layer that brings a source with options other than those of the source on the map. */
378
+ private ownedSourceConflicts;
176
379
  private duplicateIdProblem;
177
380
  /** Defaults the source layer to 'geometry' if missing and the source type is 'vector'. */
178
381
  private withDefaultSourceLayer;
@@ -218,4 +421,4 @@ declare const uninitializeContext: (contextId?: string) => void;
218
421
  /** @function */
219
422
  declare const getContext: <TState extends StateStore = StateStore>(id?: string) => Promise<FlowContext<TState>>;
220
423
 
221
- export { ContextRegistry, FlowContext, FlowContextOptions, FlowLayerStyleBuilder, FlowRdfCoreGlobals, FlowStyleDataDriven, FlowStyleIssue, FlowStyleLayerType, MapDataSource, MapLayer, MapStyle, type MapStyleOptions, MapStyleSpecification, StateStore, action, computed, dataDrivenExpression, flowLayerStyle, getContext, getGlobalState, initializeContext, isolateGlobalState, observable, serialize, uninitializeContext, validateFlowStyle };
424
+ export { CompositeLayerSpecBuilder, CompositeLayerSpecification, ContextRegistry, FlowContext, FlowContextOptions, FlowLayerStyleBuilder, FlowRdfCoreGlobals, FlowStyle, FlowStyleDataDriven, FlowStyleIssue, FlowStyleLayerType, MapDataSource, MapLayer, MapStyle, type MapStyleOptions, MapStyleSpecification, type OwnedSourceHooks, StateStore, action, compositeLayerSpec, computed, dataDrivenExpression, flowLayerStyle, getCompositeFlowStyle, getContext, getGlobalState, initializeContext, isolateGlobalState, observable, serialize, setCompositeSubLayerFilter, uninitializeContext, updateCompositeFlowStyle, validateCompositeLayer, validateFlowStyle };
package/dist/index.mjs CHANGED
@@ -7,6 +7,9 @@ export { DEFAULT_CONTEXT_ID, FlowContext } from './lib/context/flow-context.mjs'
7
7
  export { MapRegistry } from './lib/context/map-registry.mjs';
8
8
  export { QueryRegistry } from './lib/context/query-registry.mjs';
9
9
  export { ReactiveExpression } from './lib/expressions/reactive-expression.mjs';
10
+ export { compositeLayerSpec } from './lib/map-style/composite/builder.mjs';
11
+ export { getCompositeFlowStyle, setCompositeSubLayerFilter, updateCompositeFlowStyle } from './lib/map-style/composite/editing.mjs';
12
+ export { validateCompositeLayer } from './lib/map-style/composite/validate.mjs';
10
13
  export { flowLayerStyle } from './lib/map-style/flow-style/builder.mjs';
11
14
  export { dataDrivenExpression } from './lib/map-style/flow-style/data-driven.mjs';
12
15
  export { validateFlowStyle } from './lib/map-style/flow-style/validate.mjs';