aur-openlayers 0.0.2 → 1.0.0

package/lib/map-framework/public/types.d.ts

@@ -14,6 +14,13 @@ import type { TranslateEvent } from 'ol/interaction/Translate';
  * const state: FeatureStyleState = 'SELECTED';
  */
 export type FeatureStyleState = string;
+/**
+ * Идентификатор доменной модели.
+ *
+ * @example
+ * const id: Id = 'point-1';
+ */
+export type Id = string | number;
 /**
  * Значение или функция, которая его вычисляет.
  *
@@ -140,6 +147,100 @@ export type ModelChange<M> = {
     /** Причина изменения. */
     reason: ModelChangeReason;
 };
+/**
+ * Причина внешнего изменения коллекции моделей слоя.
+ *
+ * @example
+ * const reason: ModelsSetReason = 'add';
+ */
+export type ModelsSetReason = 'set' | 'add' | 'remove' | 'clear';
+/**
+ * Ошибка, выбрасываемая при нарушении уникальности id моделей слоя.
+ *
+ * Возникает при попытке:
+ * - добавить модель с уже существующим id;
+ * - передать в setModels массив с дублирующимися id.
+ */
+export declare class DuplicateModelIdError extends Error {
+    /** Дублирующийся id. */
+    readonly id: Id;
+    /** Идентификатор слоя. */
+    readonly layerId: string;
+    readonly name = "DuplicateModelIdError";
+    constructor(
+    /** Дублирующийся id. */
+    id: Id, 
+    /** Идентификатор слоя. */
+    layerId: string, message?: string);
+}
+/**
+ * Событие внешнего изменения коллекции моделей слоя.
+ */
+export type ModelsCollectionEvent<M> = {
+    /** Снимок коллекции до изменения. */
+    prev: readonly M[];
+    /** Снимок коллекции после изменения. */
+    next: readonly M[];
+    /** Причина изменения. */
+    reason: ModelsSetReason;
+    /**
+     * Опциональный diff.
+     *
+     * Гарантируется для reason = 'add' | 'remove' | 'clear'.
+     * Может отсутствовать для reason = 'set'.
+     */
+    added?: readonly M[];
+    removed?: readonly M[];
+};
+/**
+ * API управления коллекцией моделей слоя.
+ */
+export interface VectorLayerCollectionApi<M> {
+    /** Текущий иммутабельный снимок моделей слоя. */
+    getAllModels: () => readonly M[];
+    /**
+     * Полная замена набора моделей.
+     *
+     * Требования:
+     * - Все id в массиве должны быть уникальны.
+     * - При обнаружении дубликата выбрасывается DuplicateModelIdError.
+     */
+    setModels: (models: readonly M[]) => void;
+    /**
+     * Подписка на внешние изменения коллекции моделей
+     * (set / add / remove / clear).
+     */
+    onModelsCollectionChanged: (cb: (e: ModelsCollectionEvent<M>) => void) => Unsubscribe;
+    /**
+     * Добавляет модель в конец коллекции.
+     *
+     * @throws DuplicateModelIdError если модель с таким id уже существует.
+     */
+    addModel: (model: M) => void;
+    /**
+     * Добавляет несколько моделей в конец коллекции
+     * (в порядке входного массива).
+     *
+     * @throws DuplicateModelIdError
+     */
+    addModels: (models: readonly M[]) => void;
+    /**
+     * Удаляет модели по id.
+     *
+     * @returns Количество реально удалённых моделей.
+     */
+    removeModelsById: (ids: readonly Id[]) => number;
+    /**
+     * Полностью очищает слой.
+     */
+    clear: () => void;
+}
+export type MutateOptions = {
+    /** Причина изменения (по умолчанию 'mutate'). */
+    reason?: ModelChangeReason;
+    /** Без оповещения подписчиков (по умолчанию false). */
+    silent?: boolean;
+};
 /**
  * Паддинги для операций fit/center.
  *
@@ -184,22 +285,18 @@ export type Unsubscribe = () => void;
  * @example
  * ctx.layers.points.mutate(id, (prev) => ({ ...prev, active: true }));
  */
-export type VectorLayerApi<M, G extends Geometry> = {
-    /** Заменить весь набор моделей в слое. */
-    setModels: (models: readonly M[]) => void;
+export type VectorLayerApi<M, G extends Geometry> = VectorLayerCollectionApi<M> & {
     /** Запросить пересчёт слоя/стилей. */
     invalidate: () => void;
-    /** Синхронизировать модель в фичу при внешнем изменении модели. */
-    syncFeatureFromModel: (model: M) => void;
     /** Найти модель по фиче слоя. */
     getModelByFeature: (feature: Feature<G>) => M | undefined;
     /**
      * Иммутабельное обновление модели по id.
      * `update` обязан вернуть новый объект (или тот же для no-op).
      */
-    mutate: (id: string | number, update: (prev: M) => M, reason?: ModelChangeReason) => void;
+    mutate: (id: Id, update: (prev: M) => M, opts?: MutateOptions) => void;
     /** Массовая мутация (опционально). */
-    mutateMany?: (ids: Array<string | number>, update: (prev: M) => M, reason?: ModelChangeReason) => void;
+    mutateMany?: (ids: Array<Id>, update: (prev: M) => M, opts?: MutateOptions) => void;
     /**
      * Переключение кластеризации (если слой её поддерживает).
      */
@@ -217,11 +314,11 @@ export type VectorLayerApi<M, G extends Geometry> = {
     /**
      * Центрирует карту на одной фиче по id.
      */
-    centerOnModel: (id: string | number, opts?: ViewFitOptions) => void;
+    centerOnModel: (id: Id, opts?: ViewFitOptions) => void;
     /**
      * Центрирует карту на наборе фичей по списку id.
      */
-    centerOnModels: (ids: ReadonlyArray<string | number>, opts?: ViewFitOptions) => void;
+    centerOnModels: (ids: ReadonlyArray<Id>, opts?: ViewFitOptions) => void;
     /**
      * Управление видимостью слоя.
      */
@@ -249,23 +346,19 @@ export type VectorLayerApi<M, G extends Geometry> = {
     /**
      * Получить модель по id.
      */
-    getModelById: (id: string | number) => M | undefined;
+    getModelById: (id: Id) => M | undefined;
     /**
      * Проверить наличие модели по id.
      */
-    hasModel: (id: string | number) => boolean;
-    /**
-     * Получить текущий снимок моделей.
-     */
-    getAllModels: () => readonly M[];
+    hasModel: (id: Id) => boolean;
     /**
      * Получить текущий снимок id моделей.
      */
-    getAllModelIds: () => Array<string | number>;
+    getAllModelIds: () => Array<Id>;
     /**
      * Применить состояния стиля к фичам по id.
      */
-    setFeatureStates: (ids: string | number | ReadonlyArray<string | number>, states?: FeatureState) => void;
+    setFeatureStates: (ids: Id | ReadonlyArray<Id>, states?: FeatureState) => void;
 };
 /**
  * Источник появления popup-элемента.
@@ -290,7 +383,7 @@ export type PopupItem<M> = {
     /** Смещение popup относительно координаты. */
     offset?: number[];
     /** Ключ дедупликации элементов. */
-    dedupKey?: string | number;
+    dedupKey?: Id;
     /** Приоритет сортировки (чем больше, тем выше). */
     priority?: number;
     /** Источник элемента. */
@@ -310,7 +403,7 @@ export interface PopupHostApi {
     /** Очистить список. */
     clear: () => void;
     /** Удалить элемент по ключу. */
-    remove: (key: string | number) => void;
+    remove: (key: Id) => void;
     /** Получить текущие элементы. */
     getItems: () => PopupItem<any>[];
     /** Примонтировать popup-хост к DOM-узлу. */
@@ -356,7 +449,7 @@ export type MapController = {
  */
 export interface FeatureDescriptor<M, G extends Geometry, OPTS extends object> {
     /** Получение идентификатора модели. */
-    id: (model: M) => string | number;
+    id: (model: M) => Id;
     /** Синхронизация модели и геометрии. */
     geometry: {
         /** Преобразование модели в геометрию. */
@@ -389,12 +482,14 @@ export interface FeatureDescriptor<M, G extends Geometry, OPTS extends object> {
      */
     interactions?: {
         /**
-         * Обработка клика по фиче.
+         * Обработка клика по карте в контексте слоя.
+         * Коллбек вызывается даже при отсутствии фич под курсором
+         * (в этом случае `items` будет пустым массивом).
          */
         click?: InteractionBase & {
             /** Переопределение hitTolerance для клика. */
             hitTolerance?: number;
-            /** Коллбек клика по фичам текущего слоя. */
+            /** Коллбек клика по текущему слою. */
             onClick: (args: {
                 items: Array<HitItem<M, G>>;
                 ctx: MapContext;
@@ -402,12 +497,14 @@ export interface FeatureDescriptor<M, G extends Geometry, OPTS extends object> {
             }) => InteractionHandlerResult;
         };
         /**
-         * Обработка двойного клика по фиче.
+         * Обработка двойного клика по карте в контексте слоя.
+         * Коллбек вызывается даже при отсутствии фич под курсором
+         * (в этом случае `items` будет пустым массивом).
          */
         doubleClick?: InteractionBase & {
             /** Переопределение hitTolerance для doubleClick. */
             hitTolerance?: number;
-            /** Коллбек двойного клика по фичам текущего слоя. */
+            /** Коллбек двойного клика по текущему слою. */
             onDoubleClick: (args: {
                 items: Array<HitItem<M, G>>;
                 ctx: MapContext;

package/lib/map-framework/runtime/interaction-manager.d.ts

@@ -95,6 +95,7 @@ export declare class InteractionManager<Layers extends readonly VectorLayerDescr
     private getOrderedLayers;
     private getHitTolerance;
     private isEnabled;
+    private isMaybeEnabled;
     private processHover;
     private processSelect;
     private processClick;

package/lib/map-framework/runtime/vector-layer-base.d.ts

@@ -2,7 +2,7 @@ import Feature from 'ol/Feature';
 import type Geometry from 'ol/geom/Geometry';
 import type VectorLayer from 'ol/layer/Vector';
 import type VectorSource from 'ol/source/Vector';
-import type { FeatureDescriptor, MapContext, ModelChange, VectorLayerApi, VectorLayerDescriptor, ViewFitOptions } from '../public/types';
+import { type FeatureDescriptor, type Id, type MapContext, type ModelChange, type ModelsCollectionEvent, type MutateOptions, type VectorLayerApi, type VectorLayerDescriptor, type ViewFitOptions } from '../public/types';
 import { FeatureRegistry } from './feature-registry';
 export type VectorLayerBaseOptions<M, G extends Geometry, OPTS extends object> = {
     descriptor: VectorLayerDescriptor<M, G, OPTS>;
@@ -18,15 +18,23 @@ export declare abstract class VectorLayerBase<M, G extends Geometry, OPTS extend
     protected readonly registry: FeatureRegistry<M, G>;
     protected readonly scheduleInvalidate: () => void;
     protected readonly ctx: MapContext;
+    protected readonly layerId: string;
     private readonly changeHandlers;
+    private readonly collectionHandlers;
+    private models;
     constructor(options: VectorLayerBaseOptions<M, G, OPTS>);
     setModels(models: readonly M[]): void;
     invalidate(): void;
-    syncFeatureFromModel(model: M): void;
+    protected syncFeatureFromModel(model: M): void;
     getModelByFeature(feature: Feature<G>): M | undefined;
-    mutate(id: string | number, update: (prev: M) => M, reason?: ModelChange<M>['reason']): void;
-    mutateMany(ids: Array<string | number>, update: (prev: M) => M, reason?: ModelChange<M>['reason']): void;
+    mutate(id: Id, update: (prev: M) => M, opts?: MutateOptions): void;
+    mutateMany(ids: Array<Id>, update: (prev: M) => M, opts?: MutateOptions): void;
     onModelsChanged(cb: (changes: ModelChange<M>[]) => void): () => void;
+    onModelsCollectionChanged(cb: (event: ModelsCollectionEvent<M>) => void): () => void;
+    addModel(model: M): void;
+    addModels(models: readonly M[]): void;
+    removeModelsById(ids: readonly Id[]): number;
+    clear(): void;
     /** Fit view to all features on the layer. No-op if extent is empty. */
     centerOnAllModels(opts?: ViewFitOptions): void;
     /** Fit view to a single feature by id. No-op if feature/geometry is missing. */
@@ -42,12 +50,17 @@ export declare abstract class VectorLayerBase<M, G extends Geometry, OPTS extend
     getOpacity(): number;
     getZIndex(): number | undefined;
     setZIndex(z: number): void;
-    getModelById(id: string | number): M | undefined;
-    hasModel(id: string | number): boolean;
+    getModelById(id: Id): M | undefined;
+    hasModel(id: Id): boolean;
     getAllModels(): readonly M[];
-    getAllModelIds(): Array<string | number>;
-    setFeatureStates(ids: string | number | ReadonlyArray<string | number>, states?: string | string[]): void;
+    getAllModelIds(): Array<Id>;
+    setFeatureStates(ids: Id | ReadonlyArray<Id>, states?: string | string[]): void;
     protected setModelsInternal(models: readonly M[]): void;
     protected getCenterOnAllModelsSource(): VectorSource<G> | null;
     private emitModelChanges;
+    private emitCollectionChange;
+    private assertUniqueIds;
+    private throwDuplicateId;
+    private applyModelsUpdate;
+    private replaceModelSnapshot;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aur-openlayers",
-  "version": "0.0.2",
+  "version": "1.0.0",
   "peerDependencies": {
     "@angular/common": "^19.2.0",
     "@angular/core": "^19.2.0",