@kosdev-code/kos-ui-sdk 2.0.44 → 2.0.45

package/core/core/decorators/kos-state-machine.d.ts

@@ -0,0 +1,534 @@
+import { DependencyLifecycle } from '../../types';
+
+/**
+ * Configuration for a KOS state machine.
+ *
+ * @template TState Union type of valid state strings
+ * @template TEvent Union type of valid event strings
+ *
+ * @example
+ * ```typescript
+ * const config: KosStateMachineConfig<'idle' | 'active', 'START' | 'STOP'> = {
+ *   initial: 'idle',
+ *   initializeAt: DependencyLifecycle.READY,
+ *   states: {
+ *     idle: { on: { START: 'active' } },
+ *     active: { on: { STOP: 'idle' } }
+ *   }
+ * };
+ * ```
+ *
+ * @kosService core.state-machine
+ * @kosApiLevel 15
+ */
+export interface KosStateMachineConfig<TState extends string, TEvent extends string> {
+    /**
+     * The initial state when the state machine is initialized.
+     * This state will be set when the FSM reaches its configured lifecycle phase.
+     */
+    initial: TState;
+    /**
+     * The lifecycle phase at which the state machine should be initialized.
+     * Before this phase, currentState will be undefined and isFsmInitialized will be false.
+     *
+     * @default DependencyLifecycle.READY
+     *
+     * @example
+     * ```typescript
+     * // FSM initializes when model is ready (most common)
+     * initializeAt: DependencyLifecycle.READY
+     *
+     * // FSM initializes only when UI activates the model
+     * initializeAt: DependencyLifecycle.ACTIVATE
+     *
+     * // FSM initializes during model initialization (rare)
+     * initializeAt: DependencyLifecycle.INIT
+     * ```
+     */
+    initializeAt?: DependencyLifecycle;
+    /**
+     * State machine definition mapping states to their allowed transitions.
+     *
+     * @example
+     * ```typescript
+     * states: {
+     *   idle: { on: { PREPARE: 'preparing' } },
+     *   preparing: { on: { READY: 'ready', ERROR: 'error' } },
+     *   ready: { on: { POUR: 'pouring' } },
+     *   pouring: { on: { COMPLETE: 'idle', ERROR: 'error' } },
+     *   error: { on: { RESET: 'idle' } }
+     * }
+     * ```
+     */
+    states: Record<TState, {
+        /**
+         * Mapping of events to target states.
+         * When an event occurs in this state, transition to the target state.
+         */
+        on?: Partial<Record<TEvent, TState>>;
+        /**
+         * Event to auto-send when an async @kosStateEntry handler resolves.
+         * Only triggers if the FSM is still in this state when the handler completes.
+         *
+         * @example
+         * ```typescript
+         * cancelling: {
+         *   on: { CANCELLED: 'cancelled', FAIL: 'error' },
+         *   onDone: 'CANCELLED',  // auto-transition on success
+         *   onError: 'FAIL',      // auto-transition on failure
+         * }
+         * ```
+         */
+        onDone?: TEvent;
+        /**
+         * Event to auto-send when an async @kosStateEntry handler rejects.
+         * Only triggers if the FSM is still in this state when the handler fails.
+         */
+        onError?: TEvent;
+    }>;
+}
+/**
+ * Options for configuring state machine behavior.
+ *
+ * @kosService core.state-machine
+ * @kosApiLevel 15
+ */
+export interface KosStateMachineOptions {
+    /**
+     * Property name for storing the current state.
+     *
+     * @default "currentState"
+     */
+    stateProperty?: string;
+    /**
+     * Whether to track state history.
+     * When enabled, a stateHistory array is maintained with timestamps and events.
+     *
+     * @default false
+     */
+    trackHistory?: boolean;
+    /**
+     * Whether to throw errors on invalid transitions.
+     * When false, invalid transitions are logged as warnings instead.
+     *
+     * @default true
+     */
+    throwOnInvalid?: boolean;
+    /**
+     * Optional function to compute the initial FSM state dynamically at instance creation time.
+     * When provided, this function is called with the model instance and its return value
+     * is used as the initial state instead of the static `initial` from the config.
+     *
+     * This is useful for ViewModels that wrap an existing model which may already be in
+     * a non-default state (e.g., a connection that is already CONNECTED on app load).
+     *
+     * Note: Entry handlers are NOT called for the computed initial state since it
+     * represents current state, not a transition.
+     *
+     * @param instance The model/ViewModel instance (after constructor, before makeAutoObservable)
+     * @returns The initial FSM state to use
+     *
+     * @example
+     * ```typescript
+     * @kosStateMachine(fsmConfig, {
+     *   computeInitialState: (instance) => {
+     *     const state = instance.connection?.state;
+     *     return state === 'CONNECTED' ? 'connected' : 'inactive';
+     *   }
+     * })
+     * ```
+     * @kosApiLevel 21
+     */
+    computeInitialState?: (instance: any) => string;
+}
+/**
+ * Interface for models using the @kosStateMachine decorator.
+ *
+ * **IMPORTANT**: Use TypeScript interface merging to add FSM properties to your model class.
+ * This provides full type safety and IntelliSense support for all injected FSM functionality.
+ *
+ * ## Interface Merging Pattern
+ *
+ * ```typescript
+ * // 1. Define state and event types
+ * type PourState = 'idle' | 'preparing' | 'ready' | 'pouring' | 'error';
+ * type PourEvent = 'PREPARE' | 'READY' | 'POUR' | 'COMPLETE' | 'ERROR';
+ *
+ * // 2. Declare interface merging BEFORE the class
+ * interface DispenserModelImpl extends KosStateMachineAware<PourState, PourEvent> {}
+ *
+ * // 3. Apply decorators and implement the class
+ * @kosModel({ modelTypeId: "dispenser-model" })
+ * @kosStateMachine<PourState, PourEvent>({
+ *   initial: 'idle',
+ *   initializeAt: DependencyLifecycle.READY,
+ *   states: {
+ *     idle: { on: { PREPARE: 'preparing' } },
+ *     preparing: { on: { READY: 'ready', ERROR: 'error' } },
+ *     ready: { on: { POUR: 'pouring' } },
+ *     pouring: { on: { COMPLETE: 'idle', ERROR: 'error' } },
+ *     error: {}
+ *   }
+ * })
+ * export class DispenserModelImpl implements IKosDataModel {
+ *   // All FSM properties are now available with full type safety
+ * }
+ * ```
+ *
+ * ## Lifecycle-Aware Initialization
+ *
+ * The FSM is uninitialized until the configured lifecycle phase:
+ * - Before initialization: `currentState === undefined`, `isFsmInitialized === false`
+ * - After initialization: `currentState === initial`, `isFsmInitialized === true`
+ *
+ * ```typescript
+ * @kosStateMachine({
+ *   initial: 'idle',
+ *   initializeAt: DependencyLifecycle.READY, // FSM starts when model is ready
+ *   states: { ... }
+ * })
+ * class MyModel {
+ *   async ready(): Promise<void> {
+ *     // Before this completes: this.currentState === undefined
+ *     // After this completes: this.currentState === 'idle'
+ *   }
+ * }
+ * ```
+ *
+ * ## Injected Properties and Methods
+ *
+ * The decorator automatically injects the following members:
+ *
+ * - **`currentState`**: Current state (undefined until FSM initialized, observable)
+ * - **`isFsmInitialized`**: Boolean indicating if FSM has been initialized
+ * - **`isTransitioning`**: Boolean indicating if a transition is in progress
+ * - **`allowedTransitions`**: Computed array of valid events for current state
+ * - **`transition(event)`**: Method to trigger state transitions
+ * - **`canTransition(event)`**: Check if a transition is valid from current state
+ * - **`isInState(state)`**: Check if currently in a specific state
+ * - **`stateHistory`**: Array of historical states (if trackHistory enabled)
+ *
+ * All properties are reactive and will automatically update UI components when state changes.
+ *
+ * @template TState Union type of valid state strings
+ * @template TEvent Union type of valid event strings
+ *
+ * @see {@link kosStateMachine} - The decorator function
+ * @see {@link KosStateMachineConfig} - Configuration interface
+ * @see {@link KosStateMachineOptions} - Options interface
+ *
+ * @kosService core.state-machine
+ * @kosApiLevel 15
+ */
+export interface KosStateMachineAware<TState extends string, TEvent extends string> {
+    /**
+     * Current state of the state machine.
+     * Observable property that updates automatically via @kosModel.
+     * Always initialized to the initial state immediately.
+     */
+    currentState: TState;
+    /**
+     * Indicates whether the state machine has been initialized.
+     * FSM initializes at the configured lifecycle phase (READY, ACTIVATE, etc.).
+     *
+     * - Before initialization: `false`, `currentState === undefined`
+     * - After initialization: `true`, `currentState === initial`
+     */
+    readonly isFsmInitialized: boolean;
+    /**
+     * Indicates whether a state transition is currently in progress.
+     * Observable property that updates during transitions.
+     */
+    isTransitioning: boolean;
+    /**
+     * Computed array of valid events that can be triggered from the current state.
+     * Updates automatically when state changes.
+     * Returns empty array if FSM is not initialized.
+     */
+    readonly allowedTransitions: TEvent[];
+    /**
+     * Trigger a state transition by event.
+     *
+     * @param event The event to trigger
+     * @throws Error if FSM not initialized (unless `throwOnInvalid` is false)
+     * @throws Error if transition is invalid (unless `throwOnInvalid` is false)
+     *
+     * @example
+     * ```typescript
+     * this.transition('START'); // idle -> active
+     * this.transition('STOP');  // active -> idle
+     * ```
+     */
+    transition(event: TEvent): void;
+    /**
+     * Check if a transition is valid from the current state.
+     * Returns false if FSM is not initialized.
+     *
+     * @param event The event to check
+     * @returns true if the transition is valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (this.canTransition('START')) {
+     *   this.transition('START');
+     * }
+     * ```
+     */
+    canTransition(event: TEvent): boolean;
+    /**
+     * Check if the state machine is currently in a specific state.
+     * Returns false if FSM is not initialized.
+     *
+     * @param state The state to check
+     * @returns true if currently in the specified state, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (this.isInState('idle')) {
+     *   console.log('System is idle');
+     * }
+     * ```
+     */
+    isInState(state: TState): boolean;
+    /**
+     * History of state transitions (if trackHistory is enabled).
+     * Each entry contains the state, timestamp, and optional event that caused the transition.
+     *
+     * Only available when `trackHistory: true` is set in options.
+     */
+    stateHistory?: Array<{
+        state: TState;
+        timestamp: Date;
+        event?: TEvent;
+    }>;
+}
+/**
+ * Class decorator that adds finite state machine capabilities to a KOS model.
+ *
+ * This decorator eliminates manual state management boilerplate by:
+ * - **Adding lifecycle-aware FSM initialization** at configured phase (READY, ACTIVATE, etc.)
+ * - **Managing state transitions** automatically with validation
+ * - **Providing observable state** that integrates with @kosModel reactive system
+ * - **Supporting entry/exit handlers** via @kosStateEntry and @kosStateExit decorators
+ * - **Enabling state guards** via @kosStateGuard decorator
+ *
+ * ## Two-Level State System
+ *
+ * **Framework Lifecycle (Universal, Not Customizable):**
+ * - CREATED → INIT → LOAD → READY → ACTIVATE → UNLOAD → DESTROY
+ * - Managed by KOS framework
+ * - Same for all models
+ *
+ * **Application FSM (This Decorator):**
+ * - Runs WITHIN an active model
+ * - Application-specific business logic
+ * - Different for each model type
+ * - Examples: Pour states, connection states, workflow states
+ *
+ * ## Lifecycle Integration
+ *
+ * The FSM initializes at the configured lifecycle phase:
+ *
+ * ```typescript
+ * @kosStateMachine({
+ *   initial: 'idle',
+ *   initializeAt: DependencyLifecycle.READY, // Default
+ *   states: { ... }
+ * })
+ * ```
+ *
+ * - **INIT**: FSM needs to be active during model initialization (rare)
+ * - **READY**: FSM operational as soon as data loaded (most common)
+ * - **ACTIVATE**: FSM only relevant when UI is active (UI-bound models)
+ *
+ * ## TypeScript Usage
+ *
+ * **IMPORTANT**: Use TypeScript interface merging to get proper type information:
+ *
+ * ```typescript
+ * type MyState = 'idle' | 'active';
+ * type MyEvent = 'START' | 'STOP';
+ *
+ * interface MyModelImpl extends KosStateMachineAware<MyState, MyEvent> {}
+ *
+ * @kosStateMachine<MyState, MyEvent>({ ... })
+ * class MyModelImpl implements IKosDataModel {
+ *   // All FSM properties are now available with full type safety
+ * }
+ * ```
+ *
+ * @param config State machine configuration
+ * @param options Optional configuration for FSM behavior
+ * @returns A class decorator that modifies the target class prototype
+ *
+ * @see {@link KosStateMachineAware} - Interface for TypeScript merging
+ * @see {@link KosStateMachineConfig} - Configuration interface
+ * @see {@link KosStateMachineOptions} - Options interface
+ *
+ * @example
+ * ```typescript
+ * // Basic FSM with default READY initialization
+ * type PourState = 'idle' | 'pouring' | 'complete';
+ * type PourEvent = 'START' | 'FINISH';
+ *
+ * interface PourModelImpl extends KosStateMachineAware<PourState, PourEvent> {}
+ *
+ * @kosModel({ modelTypeId: "pour-model" })
+ * @kosStateMachine<PourState, PourEvent>({
+ *   initial: 'idle',
+ *   states: {
+ *     idle: { on: { START: 'pouring' } },
+ *     pouring: { on: { FINISH: 'complete' } },
+ *     complete: {}
+ *   }
+ * })
+ * class PourModelImpl implements IKosDataModel {
+ *   async ready(): Promise<void> {
+ *     // After this completes, FSM is initialized to 'idle'
+ *   }
+ *
+ *   startPour(): void {
+ *     this.transition('START'); // idle -> pouring
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // UI-bound FSM with ACTIVATE initialization
+ * type WorkflowState = 'draft' | 'review' | 'approved';
+ * type WorkflowEvent = 'SUBMIT' | 'APPROVE' | 'REJECT';
+ *
+ * interface DocumentModelImpl extends KosStateMachineAware<WorkflowState, WorkflowEvent> {}
+ *
+ * @kosModel({ modelTypeId: "document-model" })
+ * @kosStateMachine<WorkflowState, WorkflowEvent>({
+ *   initial: 'draft',
+ *   initializeAt: DependencyLifecycle.ACTIVATE, // UI-bound
+ *   states: {
+ *     draft: { on: { SUBMIT: 'review' } },
+ *     review: { on: { APPROVE: 'approved', REJECT: 'draft' } },
+ *     approved: {}
+ *   }
+ * })
+ * class DocumentModelImpl implements IKosDataModel {
+ *   // FSM only initializes when UI activates this model
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // FSM with history tracking
+ * interface HistoryModelImpl extends KosStateMachineAware<'idle' | 'active', 'TOGGLE'> {}
+ *
+ * @kosStateMachine<'idle' | 'active', 'TOGGLE'>(
+ *   {
+ *     initial: 'idle',
+ *     states: {
+ *       idle: { on: { TOGGLE: 'active' } },
+ *       active: { on: { TOGGLE: 'idle' } }
+ *     }
+ *   },
+ *   {
+ *     trackHistory: true,
+ *     stateProperty: 'status'
+ *   }
+ * )
+ * class HistoryModelImpl implements IKosDataModel {
+ *   // Access via this.stateHistory
+ * }
+ * ```
+ *
+ * @category KOS Model Decorator
+ * @since 2.1.0
+ * @kosService core.state-machine
+ * @kosApiLevel 15
+ */
+export declare function kosStateMachine<TState extends string, TEvent extends string>(config: KosStateMachineConfig<TState, TEvent>, options?: KosStateMachineOptions): ClassDecorator;
+/**
+ * Method decorator that marks a method as a state entry handler.
+ * The decorated method will be called when the state machine enters the specified state.
+ *
+ * @param state The state to handle entry for
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * @kosStateEntry('pouring')
+ * handlePouringStart(): void {
+ *   this.logger.info('Pour started');
+ *   EventBus.publish(TOPIC_POUR_STARTED, { id: this.id });
+ * }
+ * ```
+ *
+ * @kosService core.state-machine
+ * @kosApiLevel 15
+ */
+export declare function kosStateEntry<TState extends string>(state: TState): MethodDecorator;
+/**
+ * Method decorator that marks a method as a state exit handler.
+ * The decorated method will be called when the state machine exits the specified state.
+ *
+ * @param state The state to handle exit for
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * @kosStateExit('pouring')
+ * handlePouringEnd(): void {
+ *   this.logger.info('Pour ended');
+ *   EventBus.publish(TOPIC_POUR_ENDED, { id: this.id });
+ * }
+ * ```
+ *
+ * @kosService core.state-machine
+ * @kosApiLevel 15
+ */
+export declare function kosStateExit<TState extends string>(state: TState): MethodDecorator;
+/**
+ * Options for @kosStateGuard decorator.
+ *
+ * @kosService core.state-machine
+ * @kosApiLevel 15
+ */
+export interface KosStateGuardOptions<TState extends string> {
+    /**
+     * Array of states in which the decorated method can be called.
+     * The method will throw an error (or log a warning) if called from any other state.
+     */
+    allowedStates: TState[];
+    /**
+     * Whether to throw an error on invalid state.
+     * When false, logs a warning instead.
+     *
+     * @default true (uses the FSM's throwOnInvalid setting)
+     */
+    throwOnInvalid?: boolean;
+}
+/**
+ * Method decorator that guards a method with state validation.
+ * The decorated method can only be called when the state machine is in one of the allowed states.
+ *
+ * **IMPORTANT**: This decorator gracefully handles uninitialized FSM:
+ * - If FSM is not yet initialized, the guard allows the method to proceed
+ * - Once FSM is initialized, the guard enforces state validation
+ *
+ * @param options Guard configuration
+ * @returns A method decorator
+ *
+ * @example
+ * ```typescript
+ * @kosStateGuard({ allowedStates: ['ready'] })
+ * async pourBeverage(bevId: string): Promise<void> {
+ *   // This method can only be called when currentState === 'ready'
+ *   this.transition('POUR');
+ *   await this.deviceService.dispense(bevId);
+ *   this.transition('COMPLETE');
+ * }
+ * ```
+ *
+ * @kosService core.state-machine
+ * @kosApiLevel 15
+ */
+export declare function kosStateGuard<TState extends string>(options: KosStateGuardOptions<TState>): MethodDecorator;
+//# sourceMappingURL=kos-state-machine.d.ts.map

package/core/core/decorators/kos-state-machine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-state-machine.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-state-machine.ts"],"names":[],"mappings":"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"}

package/core/core/decorators/kos-topic-handler-flow-control.d.ts

@@ -1,8 +1,11 @@
-import { IKosDataModel } from '../kosModel';
 import { IKosTopicHandlerParams } from './kosTopicHandler';
+import { IKosDataModel } from '../kosModel';
 
 /**
  * Advanced flow control options for kosTopicHandler
+ *
+ * @kosService core.topic-handler
+ * @kosApiLevel 12
  */
 export interface FlowControlOptions<T = any, R = T> {
     /**
@@ -66,6 +69,10 @@ export interface FlowControlOptions<T = any, R = T> {
         continueOnError?: boolean;
     };
 }
+/**
+ * @kosService core.topic-handler
+ * @kosApiLevel 12
+ */
 export interface FilterContext {
     /** Previous events in the filter history */
     history: any[];
@@ -76,6 +83,9 @@ export interface FilterContext {
 }
 /**
  * Enhanced kosTopicHandler params with flow control
+ *
+ * @kosService core.topic-handler
+ * @kosApiLevel 12
  */
 export interface IKosTopicHandlerFlowParams<T = any, Model extends IKosDataModel = any, R = T> extends IKosTopicHandlerParams<T, Model, R> {
     /**
@@ -85,6 +95,9 @@ export interface IKosTopicHandlerFlowParams<T = any, Model extends IKosDataModel
 }
 /**
  * Statistics for monitoring flow control performance
+ *
+ * @kosService core.topic-handler
+ * @kosApiLevel 12
  */
 export interface FlowControlStats {
     /** Total events received */
@@ -104,6 +117,9 @@ export interface FlowControlStats {
 }
 /**
  * Internal flow control manager
+ *
+ * @kosService core.topic-handler
+ * @kosApiLevel 12
  */
 export declare class FlowControlManager<T = any, R = T> {
     private config;

package/core/core/decorators/kos-topic-handler-flow-control.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kos-topic-handler-flow-control.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-topic-handler-flow-control.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"kos-topic-handler-flow-control.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-topic-handler-flow-control.ts"],"names":[],"mappings":"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"}

package/core/core/decorators/kos-trouble-aware.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @kosService core.trouble-aware
+ * @kosApiLevel 13
+ */
+export interface KosTroubleAwareOptions {
+    /** Path property name to use for trouble resolution. Default: 'path' */
+    pathProperty?: string;
+}
+/**
+ * Class decorator that automatically adds TroubleAware capabilities to a KOS model.
+ *
+ * This decorator eliminates the need for manual TroubleAware interface implementation by:
+ * - Adding troubleContainer dependency injection (internal, not exposed)
+ * - Adding troubles getter that filters by model path
+ * - Adding troubleStatus getter (returns empty string by default)
+ * - Adding troublesByType getter that groups troubles by type
+ *
+ * **Important**: Use TypeScript interface merging to get proper type information:
+ *
+ * ```typescript
+ * // Add ESLint disable comment at top of file, then:
+ * interface MyModelImpl extends TroubleAware {}
+ *
+ * @kosTroubleAware()
+ * class MyModelImpl implements IKosDataModel {
+ *   path: string; // Required for trouble resolution
+ *
+ *   constructor(modelId: string, options: MyOptions) {
+ *     this.path = options.path;
+ *     // All TroubleAware properties are now available with full type safety
+ *   }
+ * }
+ * ```
+ *
+ * The decorator requires the model to have a path property (default) or specify
+ * a custom path property via options.
+ *
+ * @param options Configuration options for the decorator
+ * @returns A class decorator
+ *
+ * @example
+ * ```typescript
+ * // Default usage - uses this.path
+ * interface HolderModelImpl extends TroubleAware {}
+ *
+ * @kosTroubleAware()
+ * class HolderModelImpl implements IKosDataModel {
+ *   path: string; // Required for trouble path resolution
+ *
+ *   constructor(modelId: string, options: HolderOptions) {
+ *     this.path = options.path;
+ *   }
+ * }
+ *
+ * // Custom path property
+ * interface CustomModelImpl extends TroubleAware {}
+ *
+ * @kosTroubleAware({ pathProperty: 'devicePath' })
+ * class CustomModelImpl implements IKosDataModel {
+ *   devicePath: string; // Custom path property
+ *
+ *   constructor(modelId: string, options: CustomOptions) {
+ *     this.devicePath = options.devicePath;
+ *   }
+ * }
+ *
+ * // Type-safe external interface
+ * export type HolderModel = PublicModelInterface<HolderModelImpl> & TroubleAware;
+ * ```
+ *
+ * @category KOS Model Decorator
+ * @since 2.0.0
+ * @kosService core.trouble-aware
+ * @kosApiLevel 13
+ */
+export declare function kosTroubleAware(options?: KosTroubleAwareOptions): ClassDecorator;
+//# sourceMappingURL=kos-trouble-aware.d.ts.map

package/core/core/decorators/kos-trouble-aware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kos-trouble-aware.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/core/core/decorators/kos-trouble-aware.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,cAAc,CAsBhB"}