ofs-object 0.1.3 → 0.1.5

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.
      */
@@ -351,6 +364,9 @@ export declare abstract class BaseGLAdapter implements IMapAdapter {
      */
     protected listen(event: string, handler: (e: any) => void): void;
     protected setupMapEventListeners(): void;
+    /** undefined = not worked out yet for the current style */
+    private styleFontCache;
+    getStyleFont(): string[] | null;
     getRawMap<T = any>(): T;
     /**
      * Take every source and layer this adapter added off a map it does not own, so the host is
@@ -393,27 +409,18 @@ export declare function bulgePoints(p1: Position, p2: Position, bulge: number, m
 export declare function bulgeThroughPoint(start: Coordinate, through: Coordinate, end: Coordinate, projection?: PlanarProjection): number;
 
 export declare class CADOperations {
-    /**
-     * Split a Polygon using a LineString.
-     * Creates a hairline buffer "blade" to perform difference, then flattens into pieces.
-     */
-    /**
-     * Extend a ray from startPt through endPt until safely outside the polygon's bounding box.
-     * Uses Cartesian unit vector in coordinate space to avoid spherical bearing drift.
-     */
-    private static extendRayOutside;
-    /**
-     * Prepare cutting line: ensures head and tail pierce outside the polygon if they stop inside.
-     * The cutting line is ALWAYS kept as a single continuous LineString (never decomposed into separate rays).
-     */
-    private static prepareCuttingLine;
     /**
      * Split a single Polygon by a single LineString using planar graph noded polygonization.
      */
     private static splitSinglePolygonByLine;
     /**
-     * Split a Polygon using a LineString.
-     * Ensures cutting lines pierce completely through boundaries without leaving unsevered edges or dead-end slits.
+     * Split a Polygon using a LineString. Returns null when the line does not cut it.
+     *
+     * The line has to cross the polygon from one side to the other, as in QGIS. An end that stops
+     * inside used to be carried on in a straight line - 1.5 times the polygon's diagonal, worked out in
+     * degrees - so a line that only poked in still cut, along a path nobody drew. Now it does not cut.
+     * An end on the boundary is fine, snapped or computed onto an edge: that is a crossing, and the
+     * noding below finds it without any extension.
      */
     static splitPolygonByLine(polygon: Feature<Polygon | MultiPolygon>, cuttingLine: Feature<LineString>): Feature<Polygon>[] | null;
     /**
@@ -782,6 +789,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 +1137,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;
 
@@ -1222,8 +1242,11 @@ export declare interface DrawGuideSettings {
     angles: boolean;
     /** How far off the segment the dimension line sits, in screen pixels */
     dimensionOffsetPixels: number;
-    /** Glyph names for the labels; the map style must provide them */
-    font: string[];
+    /**
+     * Glyph font stack for the labels; the map style's glyph server must have it. null (the default)
+     * uses the font the basemap's own labels use - see `IMapAdapter.getStyleFont`.
+     */
+    font: string[] | null;
 }
 
 /** Minimal 2D context surface used by the drawing helpers (so they can be tested without a DOM) */
@@ -1754,6 +1777,12 @@ export declare interface IMapAdapter {
     setDoubleClickZoom(enabled: boolean): void;
     /** Raw map engine access */
     getRawMap<T = any>(): T;
+    /**
+     * The glyph font stack the basemap's own labels use, so text added on top is drawn in a font its
+     * glyph server has. Null when the style names none. Optional: an adapter without it gets the
+     * engine default font.
+     */
+    getStyleFont?(): string[] | null;
     /** Cleanup */
     destroy(): void;
 }
@@ -1998,6 +2027,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 +2074,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 +2264,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 +2819,7 @@ export declare class OFSDataSource extends TypedEventEmitter<OFSDataSourceEvents
      * Remove a layer by ID
      */
     removeLayer(layerId: string): boolean;
+    private detachLayer;
     /**
      * Get layer by ID
      */
@@ -2876,6 +2978,8 @@ export declare class OFSDataSource extends TypedEventEmitter<OFSDataSourceEvents
      * Create buffer around feature and add as new feature or replace
      */
     buffer(layerId: string, featureId: string | number, distance: number, units?: turf.Units, targetLayerId?: string): Feature<Polygon | MultiPolygon>;
+    /** The polygon layer that buffers of a line or point layer go into, created on first use */
+    private bufferLayerFor;
     /**
      * Calculate polygon area in square meters or hectares
      */
@@ -2922,8 +3026,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;
@@ -3403,7 +3513,6 @@ export declare class OFSDrawTools extends TypedEventEmitter<DrawEvents> {
         result: Feature<Geometry>;
     };
     private replaceLineWithPieces;
-    private safeRawMap;
     /** Segments of all visible features except `exclude` (used as cutting edges / boundaries) */
     private boundarySegments;
     /**
@@ -3485,6 +3594,8 @@ export declare class OFSDrawTools extends TypedEventEmitter<DrawEvents> {
      * in any mode), then the active drawing mode, and nothing at all when no tool is running.
      */
     private applyCursor;
+    /** The font the guide labels are drawn in: the one set, else the basemap's, else the engine default */
+    private guideFont;
     /** Current guide settings (a copy: change them through `setGuides`) */
     getGuides(): DrawGuideSettings;
     /**
@@ -3719,6 +3830,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 +4200,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
      */
@@ -4098,6 +4241,13 @@ export declare class OFSThematicEngine extends TypedEventEmitter<ThematicEvents>
     exportThemes(): ThematicDefinition[];
     /** Restore themes saved with exportThemes */
     importThemes(themes: ThematicDefinition[]): void;
+    /**
+     * Settings that belong to the layer rather than to the way it is classified, carried over when the
+     * renderer changes. In QGIS labels are a tab of their own and switching Single / Categorized /
+     * Graduated never touches them; here switching used to drop them, along with the selection
+     * highlight colour.
+     */
+    private carriedLayerSettings;
     private carriedSymbol;
     /**
      * Create a simple uniform color theme
@@ -4120,6 +4270,11 @@ export declare class OFSThematicEngine extends TypedEventEmitter<ThematicEvents>
      * symbol overrides are kept where the same category value / class position still exists.
      */
     reclassify(layer: OFSLayerData): ThematicDefinition | undefined;
+    /**
+     * The first colour of `palette` that is clearly different from every colour in `inUse`; when the
+     * palette has none left, the colour furthest from them all.
+     */
+    private unusedClassColor;
     private createCategoricalThemeData;
     /**
      * Merge changes into the base symbol (creates a simple theme when the layer has none)
@@ -4144,6 +4299,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 +4653,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 +4846,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 +5444,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;