ofs-object 0.1.3 → 0.1.4

package/dist/index.d.ts

@@ -317,9 +317,22 @@ export declare abstract class BaseGLAdapter implements IMapAdapter {
      * whole source has to be resent (every feature's label text changes at once).
      */
     protected syncLabelSource(layer: OFSLayerData): boolean;
+    /** Extra options for a layer's new GeoJSON source; an engine that needs some overrides this */
+    protected sourceOptionsFor(_layer: OFSLayerData): Record<string, unknown>;
+    /**
+     * Whether changes to this layer's source can be sent as a diff instead of the whole collection.
+     * The default is MapLibre's, whose `updateData` takes a diff on any GeoJSON source. Mapbox's
+     * takes something else and only on some sources, so MapboxAdapter overrides this and the next.
+     */
+    protected supportsPartialUpdate(_layer: OFSLayerData, source: any): boolean;
+    /** Send a diff worked out by `updateSourceData`, in the form the engine takes it */
+    protected sendPartialUpdate(source: any, diff: {
+        add: Feature<Geometry, any>[];
+        remove: (string | number)[];
+    }): void;
     /**
-     * Send changes of a layer to its map source. Uses GeoJSONSource.updateData (MapLibre) with only
-     * the added / changed / removed features when possible, otherwise falls back to setData.
+     * Send changes of a layer to its map source: only the added / changed / removed features when the
+     * engine can take a diff (see `supportsPartialUpdate`), otherwise the whole collection via setData.
      * Changed features are detected by object identity: OFSLayerData replaces the stored object on
      * every add or update.
      */
@@ -782,6 +795,16 @@ export declare function colorRampGradientCss(name: string, reverse?: boolean): s
  */
 export declare type ColorRampType = 'sequential' | 'diverging' | 'qualitative';
 
+/**
+ * The colours a theme actually puts on the map, for a layer of the given geometry.
+ *
+ * A simple theme is one colour, but which one depends on the geometry: the fill of a polygon (or
+ * its outline when it is drawn unfilled), the stroke of a line, the marker of a point. A
+ * categorised or graduated theme puts every class colour it shows on the map. (New layers do not
+ * avoid those: see `OFSThematicEngine.defaultColorFor`.)
+ */
+export declare function colorsOfTheme(theme: ThematicDefinition, geometry: LayerGeometryType): string[];
+
 export declare interface CommandArgSpec {
     /** Schema properties filled from the words before any --option, in order */
     positional?: string[];
@@ -1120,6 +1143,9 @@ export declare interface DistanceMeasure {
     closingMeters: number;
 }
 
+/** Below this CIEDE2000 distance two map colours are easy to confuse at a glance */
+export declare const DISTINCT_DELTA_E = 20;
+
 /** Save an exported image in the browser */
 export declare function downloadMapImage(image: MapImage): void;
 
@@ -1998,6 +2024,21 @@ export declare interface LandAreaMeasure {
     raiNganWa: string;
 }
 
+/**
+ * Chosen by greedy max-min selection in CIEDE2000 over the Tailwind 400-800 chromatic families,
+ * starting from a blue. Every pair is at least 20 apart and every colour is at least 22 from the
+ * reserved colours below.
+ *
+ * The blue is `#2563eb`, not the `#3b82f6` every layer used to get: that one is only 16.8 from the
+ * slate grey used for "all other values", which is too close to tell apart in a legend.
+ *
+ * It stops at 11 because that is where the space runs out: the twelfth pick is already under 20
+ * from its nearest neighbour, and every pick after it is closer still. Past this many layers the
+ * picker generates colours instead (see `pickLayerColor`), and they are as far apart as the space
+ * allows rather than clearly distinct.
+ */
+export declare const LAYER_COLOR_PALETTE: readonly string[];
+
 export declare type LayerGeometryType = 'point' | 'line' | 'polygon' | 'circle' | 'symbol';
 
 /** Legend group of layers; groups can be nested */
@@ -2030,6 +2071,11 @@ export declare interface LayerMetadata {
     sourceFile?: string;
     /** Attribute schema in source order (kept for export; edited through OFSAttributeTools) */
     fields?: FieldSchema[];
+    /**
+     * Colour to draw the layer with (any CSS colour). Left out, the layer gets one chosen to stand
+     * apart from the layers already on the map - see `pickLayerColor`.
+     */
+    color?: string;
     [key: string]: unknown;
 }
 
@@ -2215,8 +2261,60 @@ export declare function looksGeographic(bounds: [number, number, number, number]
  */
 export declare function makeCurve(vertices: Coordinate[], bulges: number[], sagToleranceMeters?: number): OfsCurveMeta | null;
 
+/**
+ * Largest layer given a dynamic source by default. A judgement call rather than a measurement - see
+ * the class comment - and adjustable per adapter through `dynamicSourceMaxFeatures`.
+ */
+export declare const MAPBOX_DYNAMIC_MAX_FEATURES = 5000;
+
+/**
+ * Mapbox GL adapter.
+ *
+ * ## Sending only what changed
+ *
+ * MapLibre's `updateData` takes a diff on any GeoJSON source. Mapbox's is a different thing: it
+ * takes a FeatureCollection to merge in by id (a feature with a null geometry deletes), and only on a
+ * source created with `dynamic: true` - on any other source it fires an error event and the update is
+ * silently lost.
+ *
+ * And `dynamic: true` does not just switch that method on. It replaces geojson-vt, which cuts the data
+ * into tiles and simplifies it for low zooms, with an index that scans every feature for every tile
+ * and does not simplify at all; Mapbox's own source calls it the mode for "small data, frequently
+ * updated". For a layer of tens of thousands of parcels that makes every zoomed-out tile carry every
+ * parcel at full detail - far worse than resending the data.
+ *
+ * So a layer gets a dynamic source only while it is small (`dynamicSourceMaxFeatures`) - the drawing
+ * and editing layers that change on every drag, which is what the mode is for - and every other layer
+ * keeps the default source and `setData`. A dynamic layer that grows past the limit, or gains a
+ * GeometryCollection (which dynamic mode cannot take), has its source rebuilt in the default mode. It
+ * is not switched back if it shrinks: `setData` on a small layer is cheap anyway.
+ */
 export declare class MapboxAdapter extends BaseGLAdapter {
     readonly engineName: "mapbox";
+    /** Layers larger than this keep the default source (0 turns dynamic sources off) */
+    dynamicSourceMaxFeatures: number;
+    /** Layers whose source was created with `dynamic: true` */
+    private dynamicSources;
+    protected sourceOptionsFor(layer: OFSLayerData): Record<string, unknown>;
+    protected supportsPartialUpdate(layer: OFSLayerData, source: any): boolean;
+    /** Mapbox merges features in by id; a feature with no geometry is how it is told to delete one */
+    protected sendPartialUpdate(source: any, diff: {
+        add: Feature<Geometry, any>[];
+        remove: (string | number)[];
+    }): void;
+    syncLayer(layer: OFSLayerData): void;
+    protected updateSourceData(layer: OFSLayerData): void;
+    removeLayer(layerId: string): void;
+    private outgrewDynamicSource;
+    /**
+     * Replace a layer's source with one in the default mode. A source cannot change mode in place, and
+     * its GL layers cannot outlive it, so all of them are removed and built again; feature state goes
+     * with the old source, so the selection is put back afterwards.
+     */
+    private rebuildSource;
+    private fitsDynamicSource;
+    /** Mapbox before 3.4 has neither the option nor the method; `peerDependencies` allows >= 3.0 */
+    private engineHasDynamicSources;
     /**
      * Build a map in `container`.
      *
@@ -2718,6 +2816,7 @@ export declare class OFSDataSource extends TypedEventEmitter<OFSDataSourceEvents
      * Remove a layer by ID
      */
     removeLayer(layerId: string): boolean;
+    private detachLayer;
     /**
      * Get layer by ID
      */
@@ -2922,8 +3021,14 @@ export declare interface OFSDataSourceEvents {
     'layer:added': {
         layer: OFSLayerData;
     };
+    /**
+     * `replaced` is true when the layer went because `addLayer` was given its id again: the same layer
+     * is coming straight back with new data, so whatever is kept per layer (its styling, say) should
+     * stay. False when it was removed for good.
+     */
     'layer:removed': {
         layerId: string;
+        replaced: boolean;
     };
     'layer:updated': {
         layer: OFSLayerData;
@@ -3719,6 +3824,11 @@ export declare class OFSLayerData {
     sourceCrs?: string;
     sourceFile?: string;
     fields?: LayerMetadata['fields'];
+    /**
+     * The colour the layer was added with, if one was given. This is the starting point only: once
+     * the layer is on the map its colour lives in its theme, and restyling it does not update this.
+     */
+    readonly color?: string;
     private featuresMap;
     private spatialIndex;
     private indexItems;
@@ -4084,7 +4194,34 @@ export declare class OFSSymbologyPanel {
 
 export declare class OFSThematicEngine extends TypedEventEmitter<ThematicEvents> {
     private themes;
-    constructor();
+    private readonly random;
+    private dataSource;
+    private unbindDataSource;
+    constructor(options?: ThematicEngineOptions);
+    /**
+     * Let the engine see the layers on the map.
+     *
+     * Without this it cannot know what colours are already in use, so every layer added without a
+     * colour comes out the same default blue. With it, such a layer gets a colour that stands apart
+     * from the others (see `pickLayerColor`), and a colour given in `addLayer({ color })` is applied.
+     *
+     * It also lets the engine forget the theme of a layer that is removed. An engine that is not bound
+     * cannot see removals, and keeps every theme until `removeTheme` is called.
+     *
+     * OFSObject, the map adapter and the legend all call this, so it rarely needs calling by hand.
+     * Binding the data source that is already bound does nothing.
+     */
+    bindDataSource(dataSource: OFSDataSource): void;
+    /**
+     * Give a new layer its theme as it is added rather than when it is first drawn. Colours are then
+     * chosen in the order layers arrive - not the order some view happens to render them - and they
+     * are in the theme from the start, so a project saved before the map has drawn still keeps them.
+     *
+     * When `addLayer` replaces a layer with the same id, the theme is still there. A colour passed to
+     * `addLayer` is explicit, so it wins; without one, the layer keeps the styling it had - refreshing
+     * a layer's data should not undo the way someone classified it.
+     */
+    private styleNewLayer;
     /**
      * Get current theme definition for a layer
      */
@@ -4144,6 +4281,17 @@ export declare class OFSThematicEngine extends TypedEventEmitter<ThematicEvents>
     private classList;
     private requireTheme;
     private defaultTheme;
+    /**
+     * Colour for a layer that has no theme yet: the one it was added with; otherwise, when the engine
+     * can see the map, one clear of the colours the other layers show; otherwise the default blue.
+     *
+     * Only layers still on the map count, which is why this walks the layers rather than the themes.
+     *
+     * Only simple (single-colour) layers count, too. A categorised or graduated layer is read by its
+     * legend - its colours stand for values, not for the layer - and a single ramp can take up most
+     * of the palette, which would leave every new layer with a leftover colour.
+     */
+    private defaultColorFor;
     /**
      * Theme of a layer, creating the default simple theme silently (no event) when it has none
      */
@@ -4487,6 +4635,30 @@ export declare function parseXml(source: string): XmlElement;
 /** Boundary paths: polygon rings or line parts */
 export declare function pathsOf(geometry: Geometry): Position[][];
 
+/**
+ * A colour for a new layer that is clearly different from the layers already on the map.
+ *
+ * In order, it takes a random palette colour that is distinct from:
+ *   1. every layer on the map, visible or hidden;
+ *   2. every visible layer (it may match a hidden one);
+ * and when neither exists - more than about eleven layers - the colour furthest from the visible layers, out of the palette and a batch of random
+ * colours. It always returns a colour: a layer that looks like another is a nuisance, a layer that
+ * cannot be added is a failure.
+ */
+export declare function pickLayerColor(options?: PickLayerColorOptions): string;
+
+export declare interface PickLayerColorOptions {
+    /** Colours of the layers currently shown. The new colour keeps clear of these first. */
+    visible?: readonly string[];
+    /**
+     * Colours of layers that are loaded but hidden. Avoided as well while that is possible - a hidden
+     * layer is one click from being shown - but given up before the visible ones are.
+     */
+    hidden?: readonly string[];
+    /** Source of randomness in [0, 1); pass a seeded one to make the choice reproducible */
+    random?: () => number;
+}
+
 export declare interface PlanarArc {
     center: PlanarPoint;
     radius: number;
@@ -4656,6 +4828,13 @@ export declare function reportInternalError(scope: string, error: unknown): void
 /** The engine to build a map with, or an error saying how to supply one */
 export declare function requireMapEngine(global: MapEngineGlobal, options?: Record<string, any>): any;
 
+/**
+ * Colours a layer must never be given, whatever else is on the map: the selection highlight (a
+ * yellow layer hides what is selected on it), the grey used for "all other values" in a categorised
+ * layer, and white and black, which vanish against light and dark basemaps.
+ */
+export declare const RESERVED_LAYER_COLORS: readonly string[];
+
 /**
  * Resolves all selected features across all layers in the dataset,
  * prioritizing active layer features first, followed by other layers,
@@ -5247,6 +5426,14 @@ export declare interface ThematicDefinition {
     label?: LabelSettings;
 }
 
+export declare interface ThematicEngineOptions {
+    /**
+     * Randomness behind the colours given to layers added without one, in [0, 1). Pass a seeded
+     * function to get the same colours every run (tests, screenshots, demos).
+     */
+    random?: () => number;
+}
+
 export declare interface ThematicEvents {
     'theme:changed': {
         layerId: string;