@ulm/core 1.0.0

package/dist/core.d.ts

@@ -0,0 +1,1293 @@
+import { ActorRef } from 'xstate';
+import { ActorRefFrom } from 'xstate';
+import { ActorRefFromLogic } from 'xstate';
+import { DateValue } from '@internationalized/date';
+import { EventObject } from 'xstate';
+import { MachineSnapshot } from 'xstate';
+import { MetaObject } from 'xstate';
+import { NonReducibleUnknown } from 'xstate';
+import { Snapshot } from 'xstate';
+import { StateMachine } from 'xstate';
+
+export declare interface AddGroupLayerParams<TGroup> extends BaseAddLayerParams {
+    layerConfig: LayerGroupConfig<TGroup>;
+}
+
+export declare interface AddLayerParams<TLayer> extends BaseAddLayerParams {
+    layerConfig: LayerConfig<TLayer>;
+}
+
+export declare type AddManagedLayerParams<TLayer, TGroup = TLayer> = AddLayerParams<TLayer> | AddGroupLayerParams<TGroup>;
+
+declare interface BaseAddLayerParams {
+    visible?: boolean;
+    enabled?: boolean;
+    index?: number;
+    position?: 'top' | 'bottom';
+}
+
+export declare interface BaseLayerConfig<T> {
+    layerId: string;
+    layerName: string;
+    parentId: string | null;
+    layerData: T;
+    timeInfo?: LayerTimeInfo;
+    opacity?: number;
+}
+
+export declare interface BaseTimeInfo {
+    precision: 'date' | 'datetime';
+}
+
+/**
+ * Calculates the computed opacity for a layer by multiplying its own opacity
+ * with the parent's computed opacity (if a parent exists).
+ *
+ * @param parentRef - The parent layer actor reference, or null if no parent.
+ * @param ownOpacity - The layer's own opacity value (0-1).
+ * @returns The computed opacity value (0-1).
+ */
+export declare function calculateComputedOpacity(parentRef: ParentLayerActor | null, ownOpacity: number): number;
+
+/**
+ * Checks if a layer can be safely removed.
+ * Prevents removal of Groups that still contain children.
+ *
+ * @param layer - The layer to check.
+ * @returns True if removable.
+ */
+export declare function canRemoveLayer<TLayer, TGroup = TLayer>(layer: ManagedItem<TLayer, TGroup>): boolean;
+
+export declare type ChildEvent = {
+    type: 'LAYER.ENABLED';
+} | {
+    type: 'LAYER.DISABLED';
+} | {
+    type: 'PARENT.VISIBLE';
+} | {
+    type: 'PARENT.HIDDEN';
+} | {
+    type: 'PARENT.OPACITY_CHANGED';
+    opacity: number;
+};
+
+export declare type ChildLayerActor = ActorRef<MachineSnapshot<LayerContext<any, any> | LayerGroupContext<any, any>, any, any, any, any, any, any, any>, ChildEvent>;
+
+/**
+ * Handles cleanup when a layer is removed.
+ * Sends a removal event to the parent actor if one exists.
+ */
+export declare function cleanupLayerReferences<TLayer, TGroup = TLayer>(layer: ManagedItem<TLayer, TGroup>): void;
+
+export declare function createLayerManagerMachine<TLayer, TGroup = TLayer>(): StateMachine<LayerManagerContext<TLayer, TGroup>, {
+type: "LAYER.REMOVE";
+layerId: string;
+} | {
+type: "LAYER.UPDATE_VISIBILITY";
+layerId: string;
+visible: boolean;
+} | {
+type: "LAYER.UPDATE_OPACITY";
+layerId: string;
+opacity: number;
+computedOpacity: number;
+} | {
+type: "LAYER.UPDATE_TIME_INFO";
+layerId: string;
+timeInfo: LayerTimeInfo;
+} | {
+type: "RESET";
+} | {
+type: "LAYER.ADD";
+params: AddManagedLayerParams<TLayer, TGroup>;
+} | {
+type: "LAYER.UPDATE_LAYER_DATA";
+layerId: string;
+layerData: TLayer | TGroup;
+}, {
+[x: string]: ActorRefFromLogic<StateMachine<LayerContext<TLayer, TGroup>, {
+type: "LAYER.ENABLED";
+} | {
+type: "LAYER.DISABLED";
+} | {
+type: "PARENT.VISIBLE";
+} | {
+type: "PARENT.HIDDEN";
+} | {
+type: "PARENT.OPACITY_CHANGED";
+opacity: number;
+} | {
+type: "LAYER.SET_OPACITY";
+opacity: number;
+} | {
+type: "LAYER.SET_TIME_INFO";
+timeInfo: LayerTimeInfo;
+} | {
+type: "LAYER.SET_LAYER_DATA";
+layerData: TLayer;
+}, {}, never, {
+type: "Notify Parent that layer is visible";
+params: NonReducibleUnknown;
+} | {
+type: "Notify Manager of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Update Computed Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Time Info";
+params: {
+timeInfo: LayerTimeInfo;
+};
+} | {
+type: "Change Layer Data";
+params: {
+layerData: TLayer;
+};
+}, never, never, {
+enabled: "visible" | "hidden";
+} | {
+disabled: "hidden";
+}, string, {
+layerManagerRef: LayerManagerRef<TLayer, TGroup>;
+layerId: string;
+parentRef: ParentLayerActor | null;
+layerName: string;
+listMode?: "show" | "hide";
+opacity?: number;
+timeInfo?: LayerTimeInfo;
+layerData: TLayer;
+}, NonReducibleUnknown, EventObject, MetaObject, {
+id: "layer";
+states: {
+readonly enabled: {
+states: {
+readonly visible: {};
+readonly hidden: {};
+};
+};
+readonly disabled: {
+states: {
+readonly hidden: {};
+};
+};
+};
+}>> | ActorRefFromLogic<StateMachine<LayerGroupContext<TLayer, TGroup>, {
+type: "LAYER.ENABLED";
+} | {
+type: "LAYER.DISABLED";
+} | {
+type: "PARENT.VISIBLE";
+} | {
+type: "PARENT.HIDDEN";
+} | {
+type: "PARENT.OPACITY_CHANGED";
+opacity: number;
+} | {
+type: "LAYER.SET_OPACITY";
+opacity: number;
+} | {
+type: "LAYER.SET_TIME_INFO";
+timeInfo: LayerTimeInfo;
+} | {
+type: "CHILD.VISIBLE";
+layerId: string;
+} | {
+type: "LAYERS.ADD_CHILD";
+child: ChildLayerActor;
+index?: number;
+position?: "top" | "bottom";
+} | {
+type: "LAYERS.REMOVE_CHILD";
+id: string;
+} | {
+type: "LAYER.SET_LAYER_DATA";
+layerData: TGroup;
+}, {}, never, {
+type: "Notify Manager of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Update Computed Opacity";
+params: NonReducibleUnknown;
+} | {
+type: "Change Layer Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Time Info";
+params: {
+timeInfo: LayerTimeInfo;
+};
+} | {
+type: "Change Layer Data";
+params: {
+layerData: TGroup;
+};
+} | {
+type: "Notify children of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Notify children of opacity change";
+params: NonReducibleUnknown;
+} | {
+type: "Notify Parent of visibility change";
+params: NonReducibleUnknown;
+} | {
+type: "Update Children";
+params: {
+child: ChildLayerActor;
+index?: number;
+position?: "top" | "bottom";
+};
+} | {
+type: "Remove Child";
+params: {
+id: string;
+};
+}, never, never, {
+enabled: "visible" | "hidden";
+} | {
+disabled: "hidden";
+}, string, {
+layerId: string;
+parentRef: ParentLayerActor | null;
+layerName: string;
+layerManagerRef: LayerManagerRef<TLayer, TGroup>;
+listMode?: "show" | "hide" | "hide-children";
+timeInfo?: LayerTimeInfo;
+opacity?: number;
+layerData: TGroup;
+}, NonReducibleUnknown, EventObject, MetaObject, {
+id: "layerGroup";
+states: {
+readonly enabled: {
+states: {
+readonly visible: {};
+readonly hidden: {};
+};
+};
+readonly disabled: {
+states: {
+readonly hidden: {};
+};
+};
+};
+}>> | undefined;
+}, {
+src: "layerMachineEnabledVisible";
+logic: StateMachine<LayerContext<TLayer, TGroup>, {
+type: "LAYER.ENABLED";
+} | {
+type: "LAYER.DISABLED";
+} | {
+type: "PARENT.VISIBLE";
+} | {
+type: "PARENT.HIDDEN";
+} | {
+type: "PARENT.OPACITY_CHANGED";
+opacity: number;
+} | {
+type: "LAYER.SET_OPACITY";
+opacity: number;
+} | {
+type: "LAYER.SET_TIME_INFO";
+timeInfo: LayerTimeInfo;
+} | {
+type: "LAYER.SET_LAYER_DATA";
+layerData: TLayer;
+}, {}, never, {
+type: "Notify Parent that layer is visible";
+params: NonReducibleUnknown;
+} | {
+type: "Notify Manager of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Update Computed Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Time Info";
+params: {
+timeInfo: LayerTimeInfo;
+};
+} | {
+type: "Change Layer Data";
+params: {
+layerData: TLayer;
+};
+}, never, never, {
+enabled: "visible" | "hidden";
+} | {
+disabled: "hidden";
+}, string, {
+layerManagerRef: LayerManagerRef<TLayer, TGroup>;
+layerId: string;
+parentRef: ParentLayerActor | null;
+layerName: string;
+listMode?: "show" | "hide";
+opacity?: number;
+timeInfo?: LayerTimeInfo;
+layerData: TLayer;
+}, NonReducibleUnknown, EventObject, MetaObject, {
+id: "layer";
+states: {
+readonly enabled: {
+states: {
+readonly visible: {};
+readonly hidden: {};
+};
+};
+readonly disabled: {
+states: {
+readonly hidden: {};
+};
+};
+};
+}>;
+id: string | undefined;
+} | {
+src: "layerMachineEnabledHidden";
+logic: StateMachine<LayerContext<TLayer, TGroup>, {
+type: "LAYER.ENABLED";
+} | {
+type: "LAYER.DISABLED";
+} | {
+type: "PARENT.VISIBLE";
+} | {
+type: "PARENT.HIDDEN";
+} | {
+type: "PARENT.OPACITY_CHANGED";
+opacity: number;
+} | {
+type: "LAYER.SET_OPACITY";
+opacity: number;
+} | {
+type: "LAYER.SET_TIME_INFO";
+timeInfo: LayerTimeInfo;
+} | {
+type: "LAYER.SET_LAYER_DATA";
+layerData: TLayer;
+}, {}, never, {
+type: "Notify Parent that layer is visible";
+params: NonReducibleUnknown;
+} | {
+type: "Notify Manager of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Update Computed Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Time Info";
+params: {
+timeInfo: LayerTimeInfo;
+};
+} | {
+type: "Change Layer Data";
+params: {
+layerData: TLayer;
+};
+}, never, never, {
+enabled: "visible" | "hidden";
+} | {
+disabled: "hidden";
+}, string, {
+layerManagerRef: LayerManagerRef<TLayer, TGroup>;
+layerId: string;
+parentRef: ParentLayerActor | null;
+layerName: string;
+listMode?: "show" | "hide";
+opacity?: number;
+timeInfo?: LayerTimeInfo;
+layerData: TLayer;
+}, NonReducibleUnknown, EventObject, MetaObject, {
+id: "layer";
+states: {
+readonly enabled: {
+states: {
+readonly visible: {};
+readonly hidden: {};
+};
+};
+readonly disabled: {
+states: {
+readonly hidden: {};
+};
+};
+};
+}>;
+id: string | undefined;
+} | {
+src: "layerMachineDisabled";
+logic: StateMachine<LayerContext<TLayer, TGroup>, {
+type: "LAYER.ENABLED";
+} | {
+type: "LAYER.DISABLED";
+} | {
+type: "PARENT.VISIBLE";
+} | {
+type: "PARENT.HIDDEN";
+} | {
+type: "PARENT.OPACITY_CHANGED";
+opacity: number;
+} | {
+type: "LAYER.SET_OPACITY";
+opacity: number;
+} | {
+type: "LAYER.SET_TIME_INFO";
+timeInfo: LayerTimeInfo;
+} | {
+type: "LAYER.SET_LAYER_DATA";
+layerData: TLayer;
+}, {}, never, {
+type: "Notify Parent that layer is visible";
+params: NonReducibleUnknown;
+} | {
+type: "Notify Manager of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Update Computed Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Time Info";
+params: {
+timeInfo: LayerTimeInfo;
+};
+} | {
+type: "Change Layer Data";
+params: {
+layerData: TLayer;
+};
+}, never, never, {
+enabled: "visible" | "hidden";
+} | {
+disabled: "hidden";
+}, string, {
+layerManagerRef: LayerManagerRef<TLayer, TGroup>;
+layerId: string;
+parentRef: ParentLayerActor | null;
+layerName: string;
+listMode?: "show" | "hide";
+opacity?: number;
+timeInfo?: LayerTimeInfo;
+layerData: TLayer;
+}, NonReducibleUnknown, EventObject, MetaObject, {
+id: "layer";
+states: {
+readonly enabled: {
+states: {
+readonly visible: {};
+readonly hidden: {};
+};
+};
+readonly disabled: {
+states: {
+readonly hidden: {};
+};
+};
+};
+}>;
+id: string | undefined;
+} | {
+src: "layerGroupMachine";
+logic: StateMachine<LayerGroupContext<TLayer, TGroup>, {
+type: "LAYER.ENABLED";
+} | {
+type: "LAYER.DISABLED";
+} | {
+type: "PARENT.VISIBLE";
+} | {
+type: "PARENT.HIDDEN";
+} | {
+type: "PARENT.OPACITY_CHANGED";
+opacity: number;
+} | {
+type: "LAYER.SET_OPACITY";
+opacity: number;
+} | {
+type: "LAYER.SET_TIME_INFO";
+timeInfo: LayerTimeInfo;
+} | {
+type: "CHILD.VISIBLE";
+layerId: string;
+} | {
+type: "LAYERS.ADD_CHILD";
+child: ChildLayerActor;
+index?: number;
+position?: "top" | "bottom";
+} | {
+type: "LAYERS.REMOVE_CHILD";
+id: string;
+} | {
+type: "LAYER.SET_LAYER_DATA";
+layerData: TGroup;
+}, {}, never, {
+type: "Notify Manager of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Update Computed Opacity";
+params: NonReducibleUnknown;
+} | {
+type: "Change Layer Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Time Info";
+params: {
+timeInfo: LayerTimeInfo;
+};
+} | {
+type: "Change Layer Data";
+params: {
+layerData: TGroup;
+};
+} | {
+type: "Notify children of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Notify children of opacity change";
+params: NonReducibleUnknown;
+} | {
+type: "Notify Parent of visibility change";
+params: NonReducibleUnknown;
+} | {
+type: "Update Children";
+params: {
+child: ChildLayerActor;
+index?: number;
+position?: "top" | "bottom";
+};
+} | {
+type: "Remove Child";
+params: {
+id: string;
+};
+}, never, never, {
+enabled: "visible" | "hidden";
+} | {
+disabled: "hidden";
+}, string, {
+layerId: string;
+parentRef: ParentLayerActor | null;
+layerName: string;
+layerManagerRef: LayerManagerRef<TLayer, TGroup>;
+listMode?: "show" | "hide" | "hide-children";
+timeInfo?: LayerTimeInfo;
+opacity?: number;
+layerData: TGroup;
+}, NonReducibleUnknown, EventObject, MetaObject, {
+id: "layerGroup";
+states: {
+readonly enabled: {
+states: {
+readonly visible: {};
+readonly hidden: {};
+};
+};
+readonly disabled: {
+states: {
+readonly hidden: {};
+};
+};
+};
+}>;
+id: string | undefined;
+}, {
+type: "Add new layer";
+params: AddManagedLayerParams<TLayer, TGroup>;
+} | {
+type: "Remove layer";
+params: {
+layerId: string;
+};
+} | {
+type: "Emit update layer order";
+params: NonReducibleUnknown;
+} | {
+type: "Reset layer manager";
+params: NonReducibleUnknown;
+}, {
+type: "isValidLayerConfig";
+params: AddManagedLayerParams<TLayer, TGroup>;
+}, never, {}, string, {
+allowNestedGroupLayers: boolean;
+}, NonReducibleUnknown, {
+type: "LAYER.ADDED";
+layerId: string;
+visible: boolean;
+} | {
+type: "LAYER.REMOVED";
+layerId: string;
+} | {
+type: "LAYER.ORDER_CHANGED";
+layerOrder: string[];
+} | {
+type: "LAYER.VISIBILITY_CHANGED";
+layerId: string;
+visible: boolean;
+} | {
+type: "LAYER.OPACITY_CHANGED";
+layerId: string;
+opacity: number;
+computedOpacity: number;
+} | {
+type: "LAYER.TIME_INFO_CHANGED";
+layerId: string;
+timeInfo: LayerTimeInfo;
+} | {
+type: "LAYER.LAYER_DATA_CHANGED";
+layerId: string;
+layerData: TLayer | TGroup;
+}, MetaObject, {
+id: "layerManager";
+}>;
+
+/**
+ * Finds a managed layer item by its ID.
+ *
+ * @param layers - The array of managed items to search.
+ * @param layerId - The unique ID of the layer to find.
+ * @returns The ManagedItem if found, otherwise undefined.
+ */
+export declare function findManagedLayerById<TLayer, TGroup = TLayer>(layers: ManagedItem<TLayer, TGroup>[], layerId: string): ManagedItem<TLayer, TGroup> | undefined;
+
+/**
+ * Resolves the parent actor for a given configuration.
+ *
+ * @param layers - The list of existing layers.
+ * @param layerConfig - The configuration containing the `parentId`.
+ * @returns The parent LayerGroupMachineActor if valid, otherwise null.
+ */
+export declare function findParentActor<TLayer, TGroup = TLayer>(layers: ManagedItem<TLayer, TGroup>[], layerConfig: LayerConfig<TLayer> | LayerGroupConfig<TLayer, TGroup>): LayerGroupMachineActor<TLayer, TGroup> | null;
+
+/**
+ * Specific helper to find an actor strictly if it is a Layer Group.
+ *
+ * @param layers - The list of layers.
+ * @param parentId - The ID of the potential parent.
+ * @returns The LayerGroup actor if found and is a group, otherwise null.
+ */
+export declare function findParentLayerGroupActor<TLayer, TGroup = TLayer>(layers: ManagedItem<TLayer, TGroup>[], parentId: string): LayerGroupMachineActor<TLayer, TGroup> | null;
+
+/**
+ * Recursively flattens the layer tree into a single list of IDs.
+ * Traverses into Group Layers to find children.
+ *
+ * @param layers - The full map of managed layers.
+ * @param topLevelLayerOrder - The root order array.
+ * @returns A flat array of all Layer IDs in depth-first order.
+ */
+export declare function getFlatLayerOrder<TLayer, TGroup = TLayer>(layers: ManagedItem<TLayer, TGroup>[], topLevelLayerOrder: string[]): string[];
+
+/**
+ * Extracts the layer data (context) from a specific layer ID.
+ *
+ * @param layers - The array of managed items.
+ * @param layerId - The ID of the target layer.
+ * @returns The layer data (TLayer or TGroup) if found, otherwise undefined.
+ */
+export declare function getLayerDataFromLayerId<TLayer, TGroup = TLayer>(layers: ManagedItem<TLayer, TGroup>[], layerId: string): TLayer | TGroup | undefined;
+
+/**
+ * Maps a Group's child order array to actual ChildLayerActor objects.
+ */
+export declare function getLayerGroupChildrenInOrder(childLayerOrder: string[], layers: ChildLayerActor[]): ChildLayerActor[];
+
+/**
+ * Maps the top-level order array of strings to actual ManagedItem objects.
+ */
+export declare function getTopLevelLayersInOrder<TLayer, TGroup = TLayer>(layerOrder: string[], layers: ManagedItem<TLayer, TGroup>[]): ManagedItem<TLayer, TGroup>[];
+
+/**
+ * Calculates the new state for the Layer Manager after adding a layer.
+ *
+ * NOTE: If `parentRef` is provided, this function has a SIDE EFFECT
+ * of sending an event to that parent actor.
+ *
+ * @param context - Current manager context.
+ * @param newManagedLayer - The new layer wrapper to add.
+ * @param parentRef - The parent actor (if adding to a group).
+ * @param index - Optional index.
+ * @param position - Optional position ('top' | 'bottom').
+ * @returns A partial context update (layers list and potentially order).
+ */
+export declare function getUpdatedLayerStructure<TLayer, TGroup = TLayer>(context: LayerManagerContext<TLayer, TGroup>, newManagedLayer: ManagedItem<TLayer, TGroup>, parentRef: LayerGroupMachineActor<TLayer, TGroup> | null, index?: number, position?: 'top' | 'bottom'): Partial<LayerManagerContext<TLayer, TGroup>>;
+
+/**
+ * Calculates the new state after removing a layer.
+ * Removes the layer from the main list and the top-level order array.
+ */
+export declare function getUpdatedLayerStructureAfterRemoval<TLayer, TGroup = TLayer>(context: LayerManagerContext<TLayer, TGroup>, layerId: string): Partial<LayerManagerContext<TLayer, TGroup>>;
+
+export declare function isLayerGroupMachine<TLayer, TGroup = TLayer>(layer: LayerActor<TLayer, TGroup>): layer is LayerGroupMachineActor<TLayer, TGroup>;
+
+export declare function isLayerMachine<TLayer, TGroup = TLayer>(layer: LayerActor<TLayer, TGroup>): layer is LayerMachineActor<TLayer, TGroup>;
+
+export declare function isRangeTimeInfo(timeInfo?: LayerTimeInfo): timeInfo is RangeTimeInfo;
+
+export declare function isSingleTimeInfo(timeInfo?: LayerTimeInfo): timeInfo is SingleTimeInfo;
+
+/**
+ * Validates if a layer configuration can be added to the current context.
+ * Checks for duplicate IDs and nested group permissions.
+ *
+ * @param layerConfig - The proposed new layer configuration.
+ * @param context - The current Layer Manager context.
+ * @returns True if valid, false otherwise (logs warnings on failure).
+ */
+export declare function isValidLayerConfig<TLayer, TGroup = TLayer>(layerConfig: LayerConfig<TLayer> | LayerGroupConfig<TLayer, TGroup>, { layers, allowNestedGroupLayers }: LayerManagerContext<TLayer, TGroup>): boolean;
+
+/**
+ * Checks if a provided index is within the bounds of the array.
+ */
+export declare function isValidLayerIndex(index: number, length: number): boolean;
+
+/**
+ * Ensures that if a parentId was requested, a valid parent actor exists.
+ *
+ * @param layerConfig - The layer config.
+ * @param parentRef - The resolved parent actor reference.
+ * @returns False if parentId exists but parentRef is missing.
+ */
+export declare function isValidParentRef<TLayer, TGroup = TLayer>(layerConfig: LayerConfig<TLayer> | LayerGroupConfig<TLayer, TGroup>, parentRef: LayerGroupMachineActor<TLayer, TGroup> | null): boolean;
+
+export declare type LayerActor<TLayer = any, TGroup = any> = LayerMachineActor<TLayer, TGroup> | LayerGroupMachineActor<TLayer, TGroup>;
+
+export declare interface LayerConfig<TLayer> extends BaseLayerConfig<TLayer> {
+    layerType: 'layer';
+}
+
+export declare interface LayerContext<TLayer, TGroup = TLayer> extends LayerContextBase<TLayer, TGroup> {
+    layerType: 'layer';
+    layerData: TLayer;
+    listMode: 'show' | 'hide';
+}
+
+export declare interface LayerContextBase<TLayer, TGroup = TLayer> {
+    layerManagerRef: LayerManagerRef<TLayer, TGroup>;
+    parentRef: ParentLayerActor | null;
+    layerId: string;
+    layerName: string;
+    layerType: LayerType;
+    layerData: TLayer | TGroup;
+    timeInfo?: LayerTimeInfo;
+    opacity: number;
+    computedOpacity: number;
+}
+
+export declare type LayerEvent<TLayer> = ChildEvent | LayerEventBase<TLayer>;
+
+export declare type LayerEventBase<T> = {
+    type: 'LAYER.SET_OPACITY';
+    opacity: number;
+} | {
+    type: 'LAYER.SET_TIME_INFO';
+    timeInfo: LayerTimeInfo;
+} | {
+    type: 'LAYER.SET_LAYER_DATA';
+    layerData: T;
+};
+
+export declare interface LayerGroupConfig<TLayer, TGroup = TLayer> extends BaseLayerConfig<TGroup> {
+    layerType: 'layerGroup';
+    listMode?: 'show' | 'hide' | 'hide-children';
+}
+
+export declare interface LayerGroupContext<TLayer, TGroup = TLayer> extends LayerContextBase<TLayer, TGroup> {
+    layerType: 'layerGroup';
+    layerData: TGroup;
+    children: ChildLayerActor[];
+    childLayerOrder: string[];
+    listMode: 'show' | 'hide' | 'hide-children';
+}
+
+export declare type LayerGroupEvent<TGroup> = ChildEvent | ParentEvent | LayerEventBase<TGroup>;
+
+export declare type LayerGroupInfo<TLayer = unknown, TGroup = TLayer> = Omit<LayerGroupContext<TLayer, TGroup>, 'layerManagerRef' | 'parentRef' | 'children' | 'childLayerOrder'> & {
+    enabled: boolean;
+    visible: boolean;
+    parentId: string | null;
+};
+
+export declare function layerGroupMachine<TLayer, TGroup = TLayer>(): StateMachine<LayerGroupContext<TLayer, TGroup>, {
+type: "LAYER.ENABLED";
+} | {
+type: "LAYER.DISABLED";
+} | {
+type: "PARENT.VISIBLE";
+} | {
+type: "PARENT.HIDDEN";
+} | {
+type: "PARENT.OPACITY_CHANGED";
+opacity: number;
+} | {
+type: "LAYER.SET_OPACITY";
+opacity: number;
+} | {
+type: "LAYER.SET_TIME_INFO";
+timeInfo: LayerTimeInfo;
+} | {
+type: "CHILD.VISIBLE";
+layerId: string;
+} | {
+type: "LAYERS.ADD_CHILD";
+child: ChildLayerActor;
+index?: number;
+position?: "top" | "bottom";
+} | {
+type: "LAYERS.REMOVE_CHILD";
+id: string;
+} | {
+type: "LAYER.SET_LAYER_DATA";
+layerData: TGroup;
+}, {}, never, {
+type: "Notify Manager of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Update Computed Opacity";
+params: NonReducibleUnknown;
+} | {
+type: "Change Layer Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Time Info";
+params: {
+timeInfo: LayerTimeInfo;
+};
+} | {
+type: "Change Layer Data";
+params: {
+layerData: TGroup;
+};
+} | {
+type: "Notify children of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Notify children of opacity change";
+params: NonReducibleUnknown;
+} | {
+type: "Notify Parent of visibility change";
+params: NonReducibleUnknown;
+} | {
+type: "Update Children";
+params: {
+child: ChildLayerActor;
+index?: number;
+position?: "top" | "bottom";
+};
+} | {
+type: "Remove Child";
+params: {
+id: string;
+};
+}, never, never, {
+enabled: "visible" | "hidden";
+} | {
+disabled: "hidden";
+}, string, {
+layerId: string;
+parentRef: ParentLayerActor | null;
+layerName: string;
+layerManagerRef: LayerManagerRef<TLayer, TGroup>;
+listMode?: "show" | "hide" | "hide-children";
+timeInfo?: LayerTimeInfo;
+opacity?: number;
+layerData: TGroup;
+}, NonReducibleUnknown, EventObject, MetaObject, {
+id: "layerGroup";
+states: {
+readonly enabled: {
+states: {
+readonly visible: {};
+readonly hidden: {};
+};
+};
+readonly disabled: {
+states: {
+readonly hidden: {};
+};
+};
+};
+}>;
+
+export declare type LayerGroupMachineActor<TLayer = any, TGroup = any> = ActorRefFrom<ReturnType<typeof layerGroupMachine<TLayer, TGroup>>>;
+
+export declare type LayerInfo<TLayer = unknown, TGroup = TLayer> = Omit<LayerContext<TLayer, TGroup>, 'layerManagerRef' | 'parentRef'> & {
+    enabled: boolean;
+    visible: boolean;
+    parentId: string | null;
+};
+
+export declare function layerMachine<TLayer, TGroup = TLayer>(initialEnabledState: 'enabled' | 'disabled', initialVisibleState: 'visible' | 'hidden'): StateMachine<LayerContext<TLayer, TGroup>, {
+type: "LAYER.ENABLED";
+} | {
+type: "LAYER.DISABLED";
+} | {
+type: "PARENT.VISIBLE";
+} | {
+type: "PARENT.HIDDEN";
+} | {
+type: "PARENT.OPACITY_CHANGED";
+opacity: number;
+} | {
+type: "LAYER.SET_OPACITY";
+opacity: number;
+} | {
+type: "LAYER.SET_TIME_INFO";
+timeInfo: LayerTimeInfo;
+} | {
+type: "LAYER.SET_LAYER_DATA";
+layerData: TLayer;
+}, {}, never, {
+type: "Notify Parent that layer is visible";
+params: NonReducibleUnknown;
+} | {
+type: "Notify Manager of visibility change";
+params: {
+visible: boolean;
+};
+} | {
+type: "Update Computed Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Opacity";
+params: {
+opacity: number;
+};
+} | {
+type: "Change Layer Time Info";
+params: {
+timeInfo: LayerTimeInfo;
+};
+} | {
+type: "Change Layer Data";
+params: {
+layerData: TLayer;
+};
+}, never, never, {
+enabled: "visible" | "hidden";
+} | {
+disabled: "hidden";
+}, string, {
+layerManagerRef: LayerManagerRef<TLayer, TGroup>;
+layerId: string;
+parentRef: ParentLayerActor | null;
+layerName: string;
+listMode?: "show" | "hide";
+opacity?: number;
+timeInfo?: LayerTimeInfo;
+layerData: TLayer;
+}, NonReducibleUnknown, EventObject, MetaObject, {
+id: "layer";
+states: {
+readonly enabled: {
+states: {
+readonly visible: {};
+readonly hidden: {};
+};
+};
+readonly disabled: {
+states: {
+readonly hidden: {};
+};
+};
+};
+}>;
+
+export declare type LayerMachineActor<TLayer = any, TGroup = any> = ActorRefFrom<ReturnType<typeof layerMachine<TLayer, TGroup>>>;
+
+/**
+ * Framework-agnostic manager for an ordered collection of layers and layer groups.
+ *
+ * `TLayer` is the consumer's layer data type; `TGroup` is the group data type
+ * (defaults to `TLayer` when omitted). Lifecycle events are forwarded to both
+ * the optional {@link LayerManagerAdapter} and the callbacks in
+ * {@link LayerManagerOptions}.
+ */
+export declare class LayerManager<TLayer, TGroup = undefined> {
+    private readonly _actor;
+    private readonly _options;
+    private _adapter;
+    /** Cleanup functions for each active XState actor event subscription. */
+    private readonly _subscriptions;
+    private _destroyed;
+    constructor(options?: LayerManagerOptions<TLayer, TGroup>);
+    /**
+     * Escape hatch for `@xstate/react` integration (e.g. `useSelector`).
+     * Prefer the typed methods on this class for all other use cases.
+     */
+    get actor(): LayerManagerActor<TLayer, TGroup>;
+    /** `true` while the underlying XState actor is running (i.e. not yet stopped). */
+    get isReady(): boolean;
+    /** `true` after {@link destroy} has been called. The instance cannot be reused once destroyed. */
+    get destroyed(): boolean;
+    /** The current top-level layers in their display order. */
+    get layers(): ManagedItem<TLayer, TGroup>[];
+    /** Returns the managed item for `id`, or `undefined` if it does not exist. */
+    getLayer(id: string): ManagedItem<TLayer, TGroup> | undefined;
+    /** Starts the XState actor, wires event subscriptions, and registers any pending adapter. */
+    private start;
+    /** Alias for {@link destroy}. */
+    stop(): void;
+    /** Resets layer state, unregisters the adapter, cancels all subscriptions, and stops the actor. */
+    destroy(): void;
+    /** Removes all layers and groups, returning the manager to its initial empty state. */
+    reset(): void;
+    /**
+     * Attach or replace the adapter at any time.
+     * Pass `null` to detach the current adapter.
+     */
+    setAdapter(adapter: LayerManagerAdapter<TLayer, TGroup> | null): void;
+    /** Adds a single layer to the manager. */
+    addLayer(params: AddLayerParams<TLayer>): void;
+    /** Adds a layer group to the manager. */
+    addGroup(params: AddGroupLayerParams<TGroup>): void;
+    /** Removes the layer or group with the given `layerId`. */
+    removeLayer(layerId: string): void;
+    /** Shows or hides the layer with the given `layerId`. */
+    setVisibility(layerId: string, visible: boolean): void;
+    /** Alias for {@link setVisibility}. */
+    setEnabled(layerId: string, enabled: boolean): void;
+    /** Sets the opacity (0–1) for the layer with the given `layerId`. */
+    setOpacity(layerId: string, opacity: number): void;
+    /** Sets the time info for the layer with the given `layerId`. */
+    setTimeInfo(layerId: string, timeInfo: LayerTimeInfo): void;
+    /** Replaces the `layerData` payload for the layer or group with the given `layerId`. */
+    updateLayerData(layerId: string, layerData: TLayer | TGroup): void;
+    /** Subscribes to machine-emitted events and forwards them to the adapter and options callbacks. */
+    private _wireSubscriptions;
+    private _cleanupSubscriptions;
+    private _registerAdapter;
+    /**
+     * Converts an internal XState actor context into the stable
+     * {@link ManagedLayerInfo} shape exposed to adapters and option callbacks.
+     * The `isLayerMachine` branch is required for TypeScript to narrow `ctx`
+     * to the correct discriminated union member.
+     */
+    private _toManagedLayerInfo;
+}
+
+export declare type LayerManagerActor<TLayer, TGroup = TLayer> = ActorRefFrom<LayerManagerMachine<TLayer, TGroup>>;
+
+export declare interface LayerManagerAdapter<TLayer = unknown, TGroup = unknown> {
+    /**
+     * Called by LayerManager.start() (or setAdapter()) to give the adapter
+     * a reference back into the manager for querying state.
+     */
+    register?: (layerManager: LayerManager<TLayer, TGroup>, callbacks: LayerManagerCallbacks<TLayer, TGroup>) => void;
+    /** Called by LayerManager.dispose() or setAdapter(null) to clean up. */
+    unregister?: () => void;
+    /** Called when a new layer is added and ready. */
+    onLayerAdded?: (info: ManagedLayerInfo<TLayer, TGroup>) => void;
+    /** Called when a layer is removed. */
+    onLayerRemoved?: (layerId: string) => void;
+    /** Called when a layer's visibility changes. */
+    onVisibilityChanged?: (info: ManagedLayerInfo<TLayer, TGroup>, visible: boolean) => void;
+    /** Called when a layer's computed opacity changes. */
+    onOpacityChanged?: (info: ManagedLayerInfo<TLayer, TGroup>, computedOpacity: number) => void;
+    /** Called when a layer's time info is updated. */
+    onTimeInfoChanged?: (info: ManagedLayerInfo<TLayer, TGroup>, timeInfo: LayerTimeInfo) => void;
+    /** Called when a layer's data payload is updated. */
+    onLayerDataChanged?: (info: ManagedLayerInfo<TLayer, TGroup>) => void;
+}
+
+export declare interface LayerManagerCallbacks<TLayer, TGroup> {
+    /** Returns the current ordered top-level layer snapshot. */
+    getSnapshot: () => ManagedItem<TLayer, TGroup>[];
+    /** Returns a single managed item by ID, or undefined if not found. */
+    getLayer: (id: string) => ManagedItem<TLayer, TGroup> | undefined;
+}
+
+export declare interface LayerManagerContext<TLayer, TGroup = TLayer> {
+    layers: ManagedItem<TLayer, TGroup>[];
+    childLayerOrder: string[];
+    allowNestedGroupLayers: boolean;
+}
+
+export declare type LayerManagerEmittedEvent<TLayer, TGroup = TLayer> = {
+    type: 'LAYER.ADDED';
+    layerId: string;
+    visible: boolean;
+} | {
+    type: 'LAYER.REMOVED';
+    layerId: string;
+} | {
+    type: 'LAYER.ORDER_CHANGED';
+    layerOrder: string[];
+} | {
+    type: 'LAYER.VISIBILITY_CHANGED';
+    layerId: string;
+    visible: boolean;
+} | {
+    type: 'LAYER.OPACITY_CHANGED';
+    layerId: string;
+    opacity: number;
+    computedOpacity: number;
+} | {
+    type: 'LAYER.TIME_INFO_CHANGED';
+    layerId: string;
+    timeInfo: LayerTimeInfo;
+} | {
+    type: 'LAYER.LAYER_DATA_CHANGED';
+    layerId: string;
+    layerData: TLayer | TGroup;
+};
+
+export declare type LayerManagerEvent<TLayer, TGroup = TLayer> = {
+    type: 'LAYER.ADD';
+    params: AddManagedLayerParams<TLayer, TGroup>;
+} | {
+    type: 'LAYER.REMOVE';
+    layerId: string;
+} | {
+    type: 'LAYER.UPDATE_VISIBILITY';
+    layerId: string;
+    visible: boolean;
+} | {
+    type: 'LAYER.UPDATE_OPACITY';
+    layerId: string;
+    opacity: number;
+    computedOpacity: number;
+} | {
+    type: 'LAYER.UPDATE_TIME_INFO';
+    layerId: string;
+    timeInfo: LayerTimeInfo;
+} | {
+    type: 'LAYER.UPDATE_LAYER_DATA';
+    layerId: string;
+    layerData: TLayer | TGroup;
+} | {
+    type: 'RESET';
+};
+
+export declare type LayerManagerMachine<TLayer, TGroup = TLayer> = ReturnType<typeof createLayerManagerMachine<TLayer, TGroup>>;
+
+export declare interface LayerManagerOptions<TLayer, TGroup = TLayer> {
+    /** Allow layer groups to be nested inside other layer groups. */
+    allowNestedGroupLayers?: boolean;
+    /** Called whenever a new layer is added. */
+    onLayerAdded?: (info: ManagedLayerInfo<TLayer, TGroup>) => void;
+    /** Called whenever a layer is removed. */
+    onLayerRemoved?: (layerId: string) => void;
+    /** Called whenever a layer's visibility changes. */
+    onVisibilityChanged?: (info: ManagedLayerInfo<TLayer, TGroup>, visible: boolean) => void;
+    /** Called whenever a layer's computed opacity changes. */
+    onOpacityChanged?: (info: ManagedLayerInfo<TLayer, TGroup>, computedOpacity: number) => void;
+    /** Called whenever a layer's time info changes. */
+    onTimeInfoChanged?: (info: ManagedLayerInfo<TLayer, TGroup>, timeInfo: LayerTimeInfo) => void;
+    /** Called when an internal error occurs. */
+    onError?: (error: Error) => void;
+}
+
+export declare type LayerManagerRef<TLayer, TGroup = TLayer> = ActorRef<Snapshot<unknown>, LayerManagerEvent<TLayer, TGroup>>;
+
+export declare type LayerTimeInfo = BaseTimeInfo & (SingleTimeInfo | RangeTimeInfo);
+
+export declare type LayerType = 'layer' | 'layerGroup';
+
+export declare type ManagedItem<TLayer, TGroup = TLayer> = ManagedLayer<TLayer, TGroup> | ManagedLayerGroup<TLayer, TGroup>;
+
+export declare interface ManagedLayer<TLayer, TGroup = TLayer> {
+    type: 'layer';
+    layerActor: LayerMachineActor<TLayer, TGroup>;
+}
+
+export declare interface ManagedLayerGroup<TLayer, TGroup = TLayer> {
+    type: 'layerGroup';
+    layerActor: LayerGroupMachineActor<TLayer, TGroup>;
+}
+
+export declare type ManagedLayerInfo<TLayer = unknown, TGroup = TLayer> = LayerInfo<TLayer, TGroup> | LayerGroupInfo<TLayer, TGroup>;
+
+export declare type ParentEvent = {
+    type: 'CHILD.VISIBLE';
+    layerId: string;
+} | {
+    type: 'LAYERS.ADD_CHILD';
+    child: ChildLayerActor;
+    index?: number;
+    position?: 'top' | 'bottom';
+} | {
+    type: 'LAYERS.REMOVE_CHILD';
+    id: string;
+};
+
+export declare type ParentLayerActor = ActorRef<MachineSnapshot<LayerGroupContext<any, any>, any, any, any, any, any, any, any>, ParentEvent>;
+
+/** Duration or span of time */
+export declare interface RangeTimeInfo extends BaseTimeInfo {
+    type: 'range';
+    start: DateValue;
+    end: DateValue;
+}
+
+/** Single point in time */
+export declare interface SingleTimeInfo extends BaseTimeInfo {
+    type: 'single';
+    value: DateValue;
+}
+
+/**
+ * Updates an array of layer IDs to include a new ID at a specific location.
+ *
+ * @param currentOrder - The existing array of IDs.
+ * @param newLayerId - The ID to insert.
+ * @param index - (Optional) Specific index to insert at.
+ * @param position - (Optional) 'top' (end of array) or 'bottom' (start of array).
+ * @returns A new array with the order updated.
+ */
+export declare function updateLayerOrder(currentOrder: string[], newLayerId: string, index?: number, position?: 'top' | 'bottom'): string[];
+
+export { }