@theseam/ui-common 2.0.1-beta.110 → 2.0.1-beta.111

package/google-maps/index.d.ts

@@ -7,6 +7,7 @@ import { Observable } from 'rxjs';
 import { CanDisableCtor, CanDisable } from '@theseam/ui-common/core';
 import * as i10 from '@theseam/ui-common/menu';
 import { MenuComponent } from '@theseam/ui-common/menu';
+import { Feature, Polygon, MultiPolygon } from 'geojson';
 import { ComponentType } from '@theseam/ui-common/models';
 import * as i11 from '@theseam/ui-common/icon';
 import { SeamIcon } from '@theseam/ui-common/icon';
@@ -16,12 +17,50 @@ import * as i7 from '@angular/common';
 import * as i8 from '@angular/cdk/observers';
 import * as i9 from '@theseam/ui-common/shared';
 import * as i13 from '@angular/google-maps';
-import { Polygon } from 'geojson';
+
+/** A set of features that belong to the same logical thing, such as one field. */
+interface TheSeamMapFeatureGroup {
+    /**
+     * `properties[featureGroupProperty]`.
+     *
+     * Falls back to a map-assigned key for features that carry no group value —
+     * always the case when no group property is configured, and for imported
+     * features the consumer did not assign one to. An assigned key is
+     * session-scoped: it does not survive an external value write, so it must not
+     * be persisted or held across a write and passed back to `selectGroup()`.
+     */
+    key: string;
+    features: Feature<Polygon | MultiPolygon>[];
+}
+/** A group, plus the individual feature an interaction landed on. */
+interface TheSeamMapGroupTarget {
+    group: TheSeamMapFeatureGroup;
+    /**
+     * The polygon the interaction landed on. For a selection this is the one
+     * `Delete` acts on; for a hover, the one under the cursor.
+     *
+     * A reference into `group.features`, not a copy.
+     */
+    feature: Feature<Polygon | MultiPolygon> | null;
+}
 
 declare abstract class TheSeamGoogleMapsApiLoader {
     abstract load(): Observable<void>;
 }
 
+interface FeatureGroupRegistryOptions {
+    /**
+     * Name of the GeoJSON property that groups features. When unset, every
+     * feature is its own group.
+     */
+    groupProperty?: string | null;
+    /** Generates the key written for a newly created group. */
+    newGroupKeyFactory?: () => string;
+}
+
+/** Which interaction model a map uses. */
+type TheSeamMapInteractionMode = 'legacy' | 'grouped';
+
 declare enum MapValueSource {
     Input = "input",
     FeatureChange = "featurechange"
@@ -51,6 +90,26 @@ declare class GoogleMapsService implements OnDestroy {
     private readonly _editingEnabledSubject;
     private _terraDraw?;
     private _terraDrawReady;
+    private _pendingStartDrawing;
+    /**
+     * One-shot suppression for the map `click` listener, armed the instant a
+     * draw finishes (see `_armMapClickSuppression()` for why, and its call
+     * site in `_onDrawFinished()`).
+     *
+     * `domEvent.timeStamp` was tried first, since it is a `DOMHighResTimeStamp`
+     * on the same origin as `performance.now()` and looks like a clean,
+     * delay-free discriminator: a stale click's timestamp should predate the
+     * moment the draw finished. It does not hold up empirically. Driving real
+     * mouse draws against the live Storybook and logging both the map `click`
+     * listener and `stopDrawing()` (see .superpowers/closing-click-report.md)
+     * caught the echo repeatedly, and every single time its `domEvent.timeStamp`
+     * was a few milliseconds AFTER `stopDrawing()`'s own timestamp, not before
+     * — indistinguishable from a genuinely fresh click by timestamp alone.
+     * Google appears to stamp its own synthetic `click` at the moment IT
+     * dispatches, not at the original pointer event's time, so there is no
+     * "stale-looking" timestamp to compare against.
+     */
+    private _suppressNextMapClick;
     private readonly _drawingSubject;
     readonly drawing$: Observable<boolean>;
     private _featureContextMenu;
@@ -58,6 +117,47 @@ declare class GoogleMapsService implements OnDestroy {
     private _baseLatLng?;
     private _padding?;
     private _allowDrawingHoleInPolygon;
+    private _model;
+    private readonly _interactionModeSubject;
+    readonly interactionMode$: Observable<TheSeamMapInteractionMode>;
+    private _groups?;
+    private _groupOptions;
+    private _focusedFeature;
+    private _styleFn?;
+    private _labelProperty;
+    private _labelsOverlay?;
+    private _warnedAboutLabelDisagreement;
+    private readonly _selectionSubject;
+    /**
+     * `distinctUntilChanged` collapses repeated `null`s. Several paths clear the
+     * selection defensively — `setData`, `clearSelection`, the declarative
+     * `selectedGroupKey` application on map-ready — and each would otherwise
+     * emit its own `null` to consumers before the user has touched anything.
+     *
+     * Non-null targets are rebuilt on every change, so reference equality never
+     * suppresses a real one, including re-selecting the same group with a
+     * different focused polygon.
+     */
+    readonly selection$: Observable<TheSeamMapGroupTarget | null>;
+    private readonly _hoverSubject;
+    /** Same reasoning as `selection$`; `mouseout` repeats `null` freely. */
+    readonly hover$: Observable<TheSeamMapGroupTarget | null>;
+    /**
+     * The group of the feature a `contextmenu` event last landed on. Kept
+     * distinct from `selection$` even though `allowsContextMenu()` now requires
+     * the right-clicked feature's group to already be the selection — so, for
+     * as long as the menu stays open, the two are provably the same group.
+     * Collapsing onto `selection$` would re-couple "what the menu acts on" to
+     * "whatever is currently selected", which is exactly the coupling this
+     * subject was introduced to break when the menu could still open for a
+     * non-selected group. That rule has already moved twice; keeping this
+     * separate means a future loosening of `allowsContextMenu()` does not have
+     * to re-invent it.
+     */
+    private readonly _contextMenuTargetSubject;
+    readonly contextMenuTarget$: Observable<TheSeamMapGroupTarget | null>;
+    private readonly _editModeSubject;
+    readonly editMode$: Observable<boolean>;
     private _fileInputHandler;
     googleMap?: google.maps.Map;
     readonly mapReady$: Observable<boolean>;
@@ -77,26 +177,192 @@ declare class GoogleMapsService implements OnDestroy {
      * Iterates the map's features and removes any that are selected.
      */
     deleteSelection(): void;
-    /** Whether polygon drawing mode is currently active. */
+    /**
+     * Delete every feature in `key`'s group. Backs the grouped "Delete Field"
+     * context-menu item.
+     *
+     * `allowsContextMenu()` now requires the right-clicked feature's group to
+     * already be the selection, so `key` here is always the selected group's
+     * key by the time this runs — making this call equivalent in practice to
+     * `deleteSelection()`. Kept as its own method anyway: it names the thing
+     * the menu item actually acts on (the group the menu opened for) rather
+     * than relying on the coincidence that it currently matches whatever is
+     * selected, a coincidence this design has already stopped being true once
+     * before and could again.
+     */
+    deleteGroup(key: string): void;
+    /**
+     * Whether polygon drawing mode is currently active.
+     *
+     * Reads `_drawingSubject` — set by `startDrawing()`/`stopDrawing()`, which
+     * this service fully controls — rather than asking Terra Draw's own
+     * `getMode()`. The two are kept in lockstep by every call to those two
+     * methods, so this is not a behaviour change; it exists so a stuck Terra
+     * Draw mode can never silently disagree with, and disarm, the rest of this
+     * service's drawing-state bookkeeping (F3's `geometryEditingArmed`
+     * included). `stopDrawing()` still always calls `_terraDraw.setMode('static')`
+     * to make Terra Draw itself release its cursor override and any
+     * in-progress geometry, regardless of which source `isDrawing()` reads.
+     */
     isDrawing(): boolean;
     /** Enter polygon drawing mode. */
     startDrawing(): void;
+    /**
+     * Clear any selection when entering drawing mode, but only in 'legacy'
+     * mode. There, a selected feature and the shape being drawn are unrelated,
+     * so leaving the old one visibly selected would read as one shape. In
+     * 'grouped' mode they are related: the selected group is exactly the
+     * target the drawn polygon will join, so it keeps its selected styling —
+     * `GroupedInteractionModel.featureFlags()` disarms its edit handles for
+     * the duration instead (F3), so they don't compete with Terra Draw for
+     * pointer events.
+     *
+     * Split out of `startDrawing()` so a recreate-in-flight (see
+     * `_pendingStartDrawing`) can defer this until the new instance's `ready`
+     * event actually fires, instead of entering drawing mode against an
+     * instance that isn't ready yet.
+     */
+    private _enterDrawingMode;
     /**
      * Cancel any in-progress drawing and leave drawing mode. Switching to the
      * `static` mode clears an unfinished line.
      */
     stopDrawing(): void;
+    /**
+     * Whether the active Terra Draw mode has actually placed a coordinate.
+     * Terra Draw's own mode state machine transitions from `'started'`
+     * (armed, no coordinate committed yet) to `'drawing'` the instant the
+     * first vertex lands (`TerraDrawPolyLineMode`'s internal `setDrawing()`,
+     * confirmed against `terra-draw`'s own source). Read directly from Terra
+     * Draw's state rather than inferred from this service's own flags, so it
+     * reflects whether the adapter's pointer capture was actually
+     * engaged — the thing terra-draw#710 is actually about — rather than
+     * merely whether this service thought a draw was armed.
+     */
+    private _hasPlacedVertex;
+    /**
+     * Stop (if running) and drop the current `TerraDraw` instance. `TerraDraw#
+     * stop()` deregisters its adapter, which for the Google Maps adapter's
+     * `isolatedData: true` mode calls `this._data.setMap(null)` and drops the
+     * reference — so this never leaves an orphaned or duplicate Data layer
+     * behind, across any number of calls.
+     */
+    private _disposeTerraDraw;
+    /**
+     * Dispose the current `TerraDraw` instance (and its adapter) and build a
+     * fresh one in its place. This is the terra-draw#710 recovery: the old
+     * instance's listeners die with it (its adapter is deregistered by
+     * `stop()`, so nothing further reaches it), and `_createTerraDraw()` wires
+     * up brand new `ready`/`finish` listeners on the new instance — never the
+     * stale closures from a previous instance.
+     */
+    private _recreateTerraDraw;
     private _initTerraDraw;
+    /**
+     * Build and start a new `TerraDraw` instance with its Google Maps adapter,
+     * wiring up this instance's own `ready`/`finish` listeners. Called both by
+     * `_initTerraDraw()` (first-ever init, guarded against running twice) and
+     * by `_recreateTerraDraw()` (every terra-draw#710 recovery afterward) —
+     * the guard against accidental double-init only lives in `_initTerraDraw()`
+     * itself, so recreation is free to call this as many times as needed.
+     */
+    private _createTerraDraw;
     addControl(element: HTMLElement, position: google.maps.ControlPosition): void;
     setData(data: any): Promise<void>;
     reCenterOnFeatures(): void;
     allowDrawingHoleInPolygon(allow: boolean): void;
     setFileInputHandler(handler: ((file: File) => void) | undefined | null): void;
     getFileInputHandler(): ((file: File) => void) | undefined | null;
+    setInteractionMode(mode: TheSeamMapInteractionMode): void;
+    setGroupOptions(options: FeatureGroupRegistryOptions): void;
+    /**
+     * Name of the GeoJSON property to render as a per-group label. `undefined`
+     * removes labels entirely (and, until now set, means the overlay is never
+     * even constructed).
+     */
+    setLabelProperty(property: string | undefined): void;
+    private _ensureLabelsOverlay;
+    private _buildLabels;
+    private _warnAboutLabelDisagreement;
+    isEditMode(): boolean;
+    setEditMode(enabled: boolean): void;
+    /**
+     * Re-run the style callback for every feature.
+     *
+     * Google re-evaluates the callback whenever the style is set, so handing
+     * back the same stored function is enough to repaint after a mode change.
+     */
+    private _refreshStyles;
+    private get _registry();
+    private _interactionContext;
+    /**
+     * Find an existing feature that fully contains `polygon`, restricted to a
+     * group when `groupKey` is given and to features `accept` returns true for
+     * when given. Matches any part of a MultiPolygon.
+     *
+     * `accept` is applied DURING iteration — a rejected candidate is skipped,
+     * not treated as ending the search — so legacy mode's Polygon-only filter
+     * can let a later Polygon candidate still match.
+     */
+    private _findContainingFeature;
+    private _applySelection;
+    /**
+     * Pair a group with the emitted GeoJSON for one of its `Data.Feature`s.
+     *
+     * Indexes into the returned source array rather than `featuresIn()`, because
+     * a feature with unsupported geometry is dropped from the emitted list and
+     * would shift every index after it.
+     */
+    private _targetFor;
+    selectGroup(key: string | null): boolean;
+    clearSelection(): void;
+    getGroups(): TheSeamMapFeatureGroup[];
+    private _boundsForGroup;
+    fitGroup(key: string, padding?: number | google.maps.Padding): boolean;
+    panToGroup(key: string): boolean;
+    /**
+     * Delete only the polygon the last interaction landed on.
+     *
+     * Re-applies the selection's group key afterward (with no focused feature)
+     * rather than leaving `selection$` holding a `TheSeamMapGroupTarget` whose
+     * `feature` no longer exists — `_applySelection` naturally clears to null
+     * when the group is now empty, via `groupWithSources`.
+     */
+    deleteFocusedFeature(): void;
+    /** Escape cascades: cancel a draw, then clear selection, then leave edit mode. */
+    handleEscape(): void;
+    /**
+     * `startDrawing()` raw-deselects every feature (via `setFeatureSelected`)
+     * without touching `_selectionSubject`, so that `onDrawFinished` can still
+     * read `getSelectedKey()` for the group being drawn into. When a draw ends
+     * WITHOUT producing a finished feature — cancelled by `Escape` or
+     * `setEditMode(false)`, or a `finish` event with no valid geometry — nothing
+     * else re-applies those raw flags, so the map renders the selection as gone
+     * while `selection$`/`getSelectedKey()` still report it. Call this at every
+     * such stopping point to bring the two back in sync.
+     *
+     * Not called from the successful-finish path in `_onDrawFinished`: that
+     * path calls `_applySelection` itself with the new/joined selection, and
+     * doing it here first would only add a redundant, momentarily-stale
+     * `selectionChange` emission ahead of the real one.
+     */
+    private _reapplyCurrentSelection;
     private _initFeatureStyling;
     setFeatureHoveredStyleOverride(feature: google.maps.Data.Feature): void;
-    private _mergeStyleOptions;
     private _initFeatureChangeListeners;
+    /**
+     * Establish `feature` as what the context menu is about to open for:
+     * `_focusedFeature` (what "Delete Polygon" acts on) and
+     * `contextMenuTarget$` (what "Delete Field" is gated on and acts on) both
+     * follow it. Shared by the `contextmenu` mouse listener and
+     * `openContextMenu()`'s keyboard path so the two establish the target
+     * identically — the menu's target must always be the feature the menu was
+     * opened for, on either path. Before this, only the mouse listener set
+     * `contextMenuTarget$`, so pressing the `ContextMenu` key could open a menu
+     * over whatever was CURRENTLY selected while still offering "Delete Field"
+     * for whatever a PRIOR right-click had targeted.
+     */
+    private _setContextMenuTarget;
     hasSelectedFeature(): boolean;
     getSelectedFeature(): google.maps.Data.Feature | null;
     openContextMenu(): void;
@@ -105,6 +371,21 @@ declare class GoogleMapsService implements OnDestroy {
     getGeoJson(removeAppProperties?: boolean): Promise<object>;
     /** Asserts that the map has been initialized. */
     private _assertInitialized;
+    /**
+     * Arm `_suppressNextMapClick`, and guarantee it cannot linger forever if
+     * the echo it exists for never arrives — confirmed to be the normal case
+     * for most real closes, and true of every synthetic/`play()`-driven draw,
+     * per .superpowers/closing-click-report.md. A `setTimeout` would "solve"
+     * this by guessing a safe wall-clock delay, which is exactly the kind of
+     * timing window this fix is trying to avoid introducing. Two
+     * `requestAnimationFrame` callbacks bound the window instead: the observed
+     * echo arrives a few milliseconds after `stopDrawing()`, comfortably
+     * inside a single frame, so two frames is generous headroom without
+     * guessing at a duration — and two real user actions (even fast automated
+     * ones) are never going to land within two animation frames of each other,
+     * so an unrelated later click is never at risk of being swallowed.
+     */
+    private _armMapClickSuppression;
     private _onDrawFinished;
     /**
      * Normalize a finished Terra Draw geometry into a Polygon. A Polygon (the
@@ -113,12 +394,6 @@ declare class GoogleMapsService implements OnDestroy {
      * they drew is discarded. Any other geometry type yields undefined.
      */
     private _toDrawnPolygon;
-    /**
-     * Find an existing Polygon feature that fully contains the drawn polygon, so
-     * the drawing can be applied as a cutout. Returns the existing feature
-     * instance (never a copy).
-     */
-    private _getPossibleExteriorFeature;
     static ɵfac: i0.ɵɵFactoryDeclaration<GoogleMapsService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<GoogleMapsService>;
 }
@@ -164,6 +439,7 @@ declare class TheSeamGoogleMapsComponent extends _TheSeamGoogleMapsMixinBase imp
     static ngAcceptInputType_streetViewControlEnabled: BooleanInput;
     static ngAcceptInputType_allowDrawingHoleInPolygon: BooleanInput;
     static ngAcceptInputType_editingEnabled: BooleanInput;
+    static ngAcceptInputType_selectedGroupKey: string | null;
     private readonly _changeDetectorRef;
     private readonly _ngUnsubscribe;
     readonly _gmApiLoaded: Observable<boolean>;
@@ -198,7 +474,32 @@ declare class TheSeamGoogleMapsComponent extends _TheSeamGoogleMapsMixinBase imp
     longitude: number;
     latitude: number;
     padding: number | google.maps.Padding | undefined;
+    /**
+     * Which interaction model the map uses.
+     *
+     * `'legacy'` is the single-boundary behaviour this component has always had
+     * and is the default, so existing consumers are unaffected. `'grouped'`
+     * separates selection from geometry editing; see the design doc.
+     */
+    interactionMode: TheSeamMapInteractionMode;
+    /**
+     * Name of the GeoJSON property that groups features into one logical thing,
+     * such as a field. Features sharing a value select, style, and edit together.
+     * Unset means every feature is its own group.
+     */
+    featureGroupProperty: string | undefined;
+    /** Name of the GeoJSON property holding a group's label text. */
+    featureLabelProperty: string | undefined;
+    /**
+     * Generates the key written to `featureGroupProperty` for a newly drawn
+     * group. Consumer-supplied so the format is one the app recognises.
+     */
+    newGroupKeyFactory: (() => string) | undefined;
+    /** Preselect a group. Applied on map-ready and after each external value write. */
+    selectedGroupKey: string | null;
     mapReady: EventEmitter<google.maps.Map | undefined>;
+    selectionChange: EventEmitter<TheSeamMapGroupTarget | null>;
+    featureHoverChange: EventEmitter<TheSeamMapGroupTarget | null>;
     featureContextMenu: MenuComponent;
     _options: {
         mapTypeControl: boolean;
@@ -212,6 +513,7 @@ declare class TheSeamGoogleMapsComponent extends _TheSeamGoogleMapsMixinBase imp
     ngOnInit(): void;
     ngOnDestroy(): void;
     ngOnChanges(changes: SimpleChanges): void;
+    private _applySelectedGroupKey;
     writeValue(value: MapValue): void;
     registerOnChange(fn: any): void;
     registerOnTouched(fn: any): void;
@@ -224,8 +526,18 @@ declare class TheSeamGoogleMapsComponent extends _TheSeamGoogleMapsMixinBase imp
     private _getHostElement;
     _onMapReady(theMap: google.maps.Map): void;
     _onClickDeleteFeature(): void;
+    /** Select a group by key. Returns false when no such group exists. */
+    selectGroup(key: string): boolean;
+    clearSelection(): void;
+    /** Fit the viewport to a group. Returns false when no such group exists. */
+    fitGroup(key: string, padding?: number | google.maps.Padding): boolean;
+    /** Pan to a group's centre. Returns false when no such group exists. */
+    panToGroup(key: string): boolean;
+    getGroups(): TheSeamMapFeatureGroup[];
+    setEditMode(enabled: boolean): void;
+    isEditMode(): boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<TheSeamGoogleMapsComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<TheSeamGoogleMapsComponent, "seam-google-maps", ["seamGoogleMaps"], { "disabled": { "alias": "disabled"; "required": false; }; "value": { "alias": "value"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "fileDropEnabled": { "alias": "fileDropEnabled"; "required": false; }; "fileUploadControlEnabled": { "alias": "fileUploadControlEnabled"; "required": false; }; "fullscreenControlEnabled": { "alias": "fullscreenControlEnabled"; "required": false; }; "reCenterControlEnabled": { "alias": "reCenterControlEnabled"; "required": false; }; "mapTypeControlEnabled": { "alias": "mapTypeControlEnabled"; "required": false; }; "streetViewControlEnabled": { "alias": "streetViewControlEnabled"; "required": false; }; "allowDrawingHoleInPolygon": { "alias": "allowDrawingHoleInPolygon"; "required": false; }; "editingEnabled": { "alias": "editingEnabled"; "required": false; }; "fileImportHandler": { "alias": "fileImportHandler"; "required": false; }; "zoom": { "alias": "zoom"; "required": false; }; "longitude": { "alias": "longitude"; "required": false; }; "latitude": { "alias": "latitude"; "required": false; }; "padding": { "alias": "padding"; "required": false; }; }, { "mapReady": "mapReady"; }, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<TheSeamGoogleMapsComponent, "seam-google-maps", ["seamGoogleMaps"], { "disabled": { "alias": "disabled"; "required": false; }; "value": { "alias": "value"; "required": false; }; "tabIndex": { "alias": "tabIndex"; "required": false; }; "fileDropEnabled": { "alias": "fileDropEnabled"; "required": false; }; "fileUploadControlEnabled": { "alias": "fileUploadControlEnabled"; "required": false; }; "fullscreenControlEnabled": { "alias": "fullscreenControlEnabled"; "required": false; }; "reCenterControlEnabled": { "alias": "reCenterControlEnabled"; "required": false; }; "mapTypeControlEnabled": { "alias": "mapTypeControlEnabled"; "required": false; }; "streetViewControlEnabled": { "alias": "streetViewControlEnabled"; "required": false; }; "allowDrawingHoleInPolygon": { "alias": "allowDrawingHoleInPolygon"; "required": false; }; "editingEnabled": { "alias": "editingEnabled"; "required": false; }; "fileImportHandler": { "alias": "fileImportHandler"; "required": false; }; "zoom": { "alias": "zoom"; "required": false; }; "longitude": { "alias": "longitude"; "required": false; }; "latitude": { "alias": "latitude"; "required": false; }; "padding": { "alias": "padding"; "required": false; }; "interactionMode": { "alias": "interactionMode"; "required": false; }; "featureGroupProperty": { "alias": "featureGroupProperty"; "required": false; }; "featureLabelProperty": { "alias": "featureLabelProperty"; "required": false; }; "newGroupKeyFactory": { "alias": "newGroupKeyFactory"; "required": false; }; "selectedGroupKey": { "alias": "selectedGroupKey"; "required": false; }; }, { "mapReady": "mapReady"; "selectionChange": "selectionChange"; "featureHoverChange": "featureHoverChange"; }, never, never, false, never>;
 }
 
 /**
@@ -542,7 +854,8 @@ declare class TheSeamGoogleMapsModule {
 }
 
 declare enum AppFeaturePropertyName {
-    IsSelected = "__app__isSelected"
+    IsSelected = "__app__isSelected",
+    GroupKey = "__app__groupKey"
 }
 declare function isAppFeatureProperty(propertyName: string): propertyName is AppFeaturePropertyName;
 declare function isFeatureSelected(feature: google.maps.Data.Feature): boolean;
@@ -560,6 +873,34 @@ declare function dataPolygonFromGeoJson(polygon: Polygon): google.maps.Data.Poly
  * Returns undefined for non-Polygon geometries. Does not mutate the feature.
  */
 declare function geoJsonPolygonFromDataFeature(feature: google.maps.Data.Feature): Polygon | undefined;
+/** Build a google.maps.Data.MultiPolygon from a GeoJSON MultiPolygon. */
+declare function dataMultiPolygonFromGeoJson(multiPolygon: MultiPolygon): google.maps.Data.MultiPolygon;
+/**
+ * Every Polygon part of a feature, as closed GeoJSON. A Polygon feature yields
+ * one; a MultiPolygon yields one per part; anything else yields none.
+ *
+ * Callers that need to match a drawn shape against existing geometry must use
+ * this rather than `geoJsonPolygonFromDataFeature`, which sees only Polygons
+ * and silently ignores MultiPolygon features.
+ */
+declare function polygonsFromDataFeature(feature: google.maps.Data.Feature): Polygon[];
+/**
+ * Cut `hole` into whichever part of `feature`'s geometry fully contains it.
+ *
+ * Mutates the EXISTING feature (via `setGeometry`) rather than replacing it,
+ * so its identity and properties survive. A single-part Polygon feature stays
+ * a Polygon; a MultiPolygon feature stays a MultiPolygon with only the
+ * containing part modified. Returns whether a containing part was found —
+ * when none is, the feature is left untouched.
+ */
+declare function applyHoleToFeature(feature: google.maps.Data.Feature, hole: Polygon): boolean;
+/**
+ * Read a feature as a GeoJSON Feature, geometry and properties together.
+ *
+ * `excludeProperty` filters properties out by name — used to keep internal
+ * `__app__` bookkeeping out of anything handed to a consumer.
+ */
+declare function geoJsonFeatureFromDataFeature(feature: google.maps.Data.Feature, excludeProperty?: (name: string) => boolean): Feature<Polygon | MultiPolygon> | undefined;
 declare function getBoundsWithAllFeatures(data: google.maps.Data): google.maps.LatLngBounds;
 declare function getFeatureBounds(feature: google.maps.Data.Feature): google.maps.LatLngBounds;
 declare function getFeatureCenter(feature: google.maps.Data.Feature): google.maps.LatLng;
@@ -570,6 +911,78 @@ declare function getFeaturesCount(data: google.maps.Data): number;
  */
 declare function createFeatureChangeObservable(data: google.maps.Data, ngZone: NgZone): Observable<void>;
 
+declare const FEATURE_STYLE_OPTIONS_DEFAULT: () => google.maps.Data.StyleOptions;
+declare const FEATURE_STYLE_OPTIONS_SELECTED: () => google.maps.Data.StyleOptions;
+declare const FEATURE_STYLE_OVERRIDE_OPTIONS_HOVERED: () => google.maps.Data.StyleOptions;
+/**
+ * Style options a feature may set through its GeoJSON properties.
+ *
+ * `editable`, `draggable`, and `clickable` are here so a feature can opt OUT —
+ * a retired field stays unreshapeable while its neighbours do not. They cannot
+ * opt in: the clamp in `computeFeatureStyle` runs last and only ever narrows.
+ */
+declare const SUPPORTED_PROPERTY_STYLE_OPTIONS: (keyof google.maps.Data.StyleOptions)[];
+/** What the interaction model and the global gate permit for a feature. */
+interface TheSeamMapFeatureStyleContext {
+    /** The `editingEnabled` input. */
+    editingEnabled: boolean;
+    /** Whether the model currently arms geometry editing at all. */
+    geometryEditingArmed: boolean;
+    /** Whether the model lets this feature receive clicks. */
+    clicksAllowed: boolean;
+}
+/** Merge only the supported subset of one options object into another. */
+declare function mergeStyleOptions(target: google.maps.Data.StyleOptions, source: google.maps.Data.StyleOptions | undefined): google.maps.Data.StyleOptions;
+/**
+ * The style for a feature, in a fixed precedence order:
+ *
+ *   defaults
+ *     -> properties.styleOptions
+ *     -> selected defaults          (when selected)
+ *     -> properties.styleOptionsSelected  (when selected)
+ *     -> interaction clamp          (always last)
+ *
+ * That chain governs the *visual* options (colours, etc.) only. The opt-out
+ * flags (`editable`/`draggable`/`clickable`) resolve separately, per key: a
+ * selected feature consults `styleOptionsSelected` first and falls back to
+ * `styleOptions` only for a key `styleOptionsSelected` doesn't itself
+ * mention — never a whole-object fallback. Otherwise a feature that declares
+ * `styleOptionsSelected` for an unrelated reason, such as a different
+ * selected fill colour, would silently lose an unrelated `editable: false`
+ * from `styleOptions` the moment it's selected.
+ *
+ * The clamp is one-directional. A feature can only narrow what the context
+ * permits, never widen it, so no property in an uploaded file can arm editing
+ * when the mode says no.
+ *
+ * A declared `editable: false` also implies `draggable: false`: moving a
+ * polygon changes the map's value exactly as much as reshaping it does, so a
+ * feature that opts out of one opts out of the other. This implication runs
+ * only one way — `draggable: false` alone does not imply `editable: false`, so
+ * a feature may still opt out of dragging while remaining reshapeable via its
+ * vertex handles. Resolved through the same per-key `wants()` lookup as
+ * `editable` itself, so a feature that locks `editable: false` in
+ * `styleOptions` cannot be dragged even if `styleOptionsSelected` declares
+ * `draggable` for an unrelated reason (or not at all).
+ */
+declare function computeFeatureStyle(feature: google.maps.Data.Feature, context: TheSeamMapFeatureStyleContext): google.maps.Data.StyleOptions;
+/**
+ * The hover override, merged with anything the feature declares for hover.
+ *
+ * `mergeStyleOptions` is shared with `computeFeatureStyle`, and
+ * `SUPPORTED_PROPERTY_STYLE_OPTIONS` includes `editable`/`draggable` so a
+ * feature can opt OUT of them via `styleOptions`/`styleOptionsSelected`. But
+ * this override is applied via `overrideStyle`, with no clamp downstream at
+ * all — unlike `computeFeatureStyle`, where the interaction clamp runs last
+ * and narrows whatever came before it. So if a consumer's
+ * `styleOptionsHovered` declared `editable` or `draggable`, it would apply
+ * unclamped: the one path where the "clamp is one-directional and always
+ * runs last" guarantee would not hold. A hover override has no business
+ * touching either, so both are stripped unconditionally, regardless of what
+ * `styleOptionsHovered` declares.
+ */
+declare function computeFeatureHoverStyle(feature: google.maps.Data.Feature): google.maps.Data.StyleOptions;
+
 declare class GoogleMapsContextMenu {
     private readonly _map;
     private readonly _menu;
@@ -665,5 +1078,5 @@ declare class TheSeamNoopGoogleMapsAPILoader extends TheSeamGoogleMapsApiLoader
     static ɵprov: i0.ɵɵInjectableDeclaration<TheSeamNoopGoogleMapsAPILoader>;
 }
 
-export { AppFeaturePropertyName, GoogleMapsContextMenu, GoogleMapsControlsService, GoogleMapsService, MAP_CONTROLS_SERVICE, MAP_CONTROL_DATA, MapControlRef, MapValueManagerService, MapValueSource, SEAM_GOOGLE_PLACES_AUTOCOMPLETE_DEFAULT_OPTIONS, THESEAM_LAZY_MAPS_API_CONFIG, TheSeamGoogleMapsApiLoader, TheSeamGoogleMapsComponent, TheSeamGoogleMapsModule, TheSeamGoogleMapsPlacesAutoCompleteComponent, TheSeamGoogleMapsPlacesAutocompleteDirective, TheSeamGoogleMapsRecenterButtonControlComponent, TheSeamGoogleMapsUploadButtonControlComponent, TheSeamLazyMapsApiLoader, TheSeamMapFileDropComponent, TheSeamMapsControlComponent, TheSeamNoopGoogleMapsAPILoader, createFeatureChangeObservable, dataPolygonFromGeoJson, geoJsonPolygonFromDataFeature, getBoundsWithAllFeatures, getFeatureBounds, getFeatureCenter, getFeaturesCount, getHoveredStyleOptionsDefinedByFeature, getSelectedStyleOptionsDefinedByFeature, getStyleOptionsDefinedByFeature, isAppFeatureProperty, isFeatureSelected, polygonCoordinates, polygonHasValidPathsLengths, removeAllFeatures, setFeatureSelected, stripAppFeaturePropertiesFromJson };
-export type { GoogleMapsRecenterButtonControlData, GoogleMapsUploadButtonControlData, MapControl, MapControlsService, MapValue, MapValueChange, TheSeamLazyMapsApiLoaderConfig };
+export { AppFeaturePropertyName, FEATURE_STYLE_OPTIONS_DEFAULT, FEATURE_STYLE_OPTIONS_SELECTED, FEATURE_STYLE_OVERRIDE_OPTIONS_HOVERED, GoogleMapsContextMenu, GoogleMapsControlsService, GoogleMapsService, MAP_CONTROLS_SERVICE, MAP_CONTROL_DATA, MapControlRef, MapValueManagerService, MapValueSource, SEAM_GOOGLE_PLACES_AUTOCOMPLETE_DEFAULT_OPTIONS, SUPPORTED_PROPERTY_STYLE_OPTIONS, THESEAM_LAZY_MAPS_API_CONFIG, TheSeamGoogleMapsApiLoader, TheSeamGoogleMapsComponent, TheSeamGoogleMapsModule, TheSeamGoogleMapsPlacesAutoCompleteComponent, TheSeamGoogleMapsPlacesAutocompleteDirective, TheSeamGoogleMapsRecenterButtonControlComponent, TheSeamGoogleMapsUploadButtonControlComponent, TheSeamLazyMapsApiLoader, TheSeamMapFileDropComponent, TheSeamMapsControlComponent, TheSeamNoopGoogleMapsAPILoader, applyHoleToFeature, computeFeatureHoverStyle, computeFeatureStyle, createFeatureChangeObservable, dataMultiPolygonFromGeoJson, dataPolygonFromGeoJson, geoJsonFeatureFromDataFeature, geoJsonPolygonFromDataFeature, getBoundsWithAllFeatures, getFeatureBounds, getFeatureCenter, getFeaturesCount, getHoveredStyleOptionsDefinedByFeature, getSelectedStyleOptionsDefinedByFeature, getStyleOptionsDefinedByFeature, isAppFeatureProperty, isFeatureSelected, mergeStyleOptions, polygonCoordinates, polygonHasValidPathsLengths, polygonsFromDataFeature, removeAllFeatures, setFeatureSelected, stripAppFeaturePropertiesFromJson };
+export type { GoogleMapsRecenterButtonControlData, GoogleMapsUploadButtonControlData, MapControl, MapControlsService, MapValue, MapValueChange, TheSeamLazyMapsApiLoaderConfig, TheSeamMapFeatureGroup, TheSeamMapFeatureStyleContext, TheSeamMapGroupTarget, TheSeamMapInteractionMode };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theseam/ui-common",
-  "version": "2.0.1-beta.110",
+  "version": "2.0.1-beta.111",
   "peerDependencies": {
     "@angular/cdk": "^20.2.3",
     "@angular/common": "^20.3.0",

package/story-helpers/index.d.ts

@@ -1,6 +1,6 @@
 import { HandlerFunction } from 'storybook/actions';
 import * as i0 from '@angular/core';
-import { ModuleWithProviders, Injector, TemplateRef, InjectionToken, ComponentRef } from '@angular/core';
+import { ModuleWithProviders, Injector, TemplateRef, InjectionToken, ComponentRef, Type } from '@angular/core';
 import * as i2 from '@angular/common';
 import * as i3 from '@angular/router';
 import * as i4 from '@theseam/ui-common/scrollbar';
@@ -194,5 +194,7 @@ declare const INJECTOR_TO_ARGS_PROPERTY_NAME = "__getInjector";
 declare const addInjectorGetterToArgs: (argName?: string) => DecoratorFunction<AngularRenderer>;
 declare const getInjectorFromArgs: (args: any, argName?: string) => Injector;
 
-export { INJECTOR_TO_ARGS_PROPERTY_NAME, STORY_INITIAL_ROUTE_URL, StoryEmptyComponent, StoryEmptyWithRouteComponent, StoryHelperComponentsModule, StoryInitialRouteModule, StoryInitialRouteService, StoryModalContainerComponent, StoryPreferencesAccessorService, addInjectorGetterToArgs, argsToTpl, buttonTypeArgType, getInjectorFromArgs, onStoryBootstrappedTrigger, routeButton, routesArgType, sizeArgType, storyInitialRouteFactory, storyModalDecorator, themeArgType, themeWithOutlineArgType };
+declare function getComponentInstance<T>(element: Element | null | undefined, componentType?: Type<T>): T | null;
+
+export { INJECTOR_TO_ARGS_PROPERTY_NAME, STORY_INITIAL_ROUTE_URL, StoryEmptyComponent, StoryEmptyWithRouteComponent, StoryHelperComponentsModule, StoryInitialRouteModule, StoryInitialRouteService, StoryModalContainerComponent, StoryPreferencesAccessorService, addInjectorGetterToArgs, argsToTpl, buttonTypeArgType, getComponentInstance, getInjectorFromArgs, onStoryBootstrappedTrigger, routeButton, routesArgType, sizeArgType, storyInitialRouteFactory, storyModalDecorator, themeArgType, themeWithOutlineArgType };
 export type { ArgsTplOptions, ArgsTplParts, StoryModalDecoratorOptions };