@kosdev-code/kos-ui-sdk 2.0.41 → 2.1.1

package/models/models/translation/types/index.d.ts

@@ -5,13 +5,146 @@ import { KosContext, KosParentAware } from '../../../../core';
 
 // ---------------  Translation ---------------
 
+/**
+ * Configuration options for Translation model instances.
+ *
+ * This interface defines the complete configuration structure for individual translation
+ * namespace models, including locale settings, resolution strategies, and custom loading
+ * mechanisms. Translation models handle the actual key resolution and interpolation for
+ * specific functional areas within KOS applications.
+ *
+ * @example Basic Translation Configuration
+ * ```typescript
+ * // Device status translations with English fallback
+ * const statusOptions: TranslationOptions = {
+ *   namespace: 'device-status',
+ *   currentLocale: 'es',
+ *   defaultLocale: 'en',
+ *   descriptor: {
+ *     'es': {
+ *       fallbacks: ['en']
+ *     },
+ *     'en': {
+ *       fallbacks: []
+ *     }
+ *   },
+ *   kosParentId: 'translation-container'
+ * };
+ *
+ * const statusTranslation = Translation.instance('status-translations')
+ *   .options(statusOptions)
+ *   .build();
+ * ```
+ *
+ * @example Custom Bundle Resolution
+ * ```typescript
+ * // API-based translation loading
+ * const apiBundleResolver = async (
+ *   namespace: string,
+ *   locale: string,
+ *   context?: KosContext
+ * ): Promise<TranslationResponse> => {
+ *   const response = await fetch(`/api/translations/${namespace}/${locale}`);
+ *   return await response.json();
+ * };
+ *
+ * const apiOptions: TranslationOptions = {
+ *   namespace: 'alerts',
+ *   currentLocale: 'fr',
+ *   defaultLocale: 'en',
+ *   descriptor: {
+ *     'fr': { fallbacks: ['en'] },
+ *     'en': { fallbacks: [] }
+ *   },
+ *   bundleResolver: apiBundleResolver,
+ *   kosParentId: 'translation-container'
+ * };
+ * ```
+ *
+ * @example Multi-Regional Configuration
+ * ```typescript
+ * // Complex fallback chains for regional variations
+ * const regionalOptions: TranslationOptions = {
+ *   namespace: 'regional-ui',
+ *   currentLocale: 'pt-BR',
+ *   defaultLocale: 'en',
+ *   descriptor: {
+ *     'pt-BR': { fallbacks: ['pt', 'es', 'en'] },
+ *     'pt-PT': { fallbacks: ['pt', 'es', 'en'] },
+ *     'pt': { fallbacks: ['es', 'en'] },
+ *     'es': { fallbacks: ['en'] },
+ *     'en': { fallbacks: [] }
+ *   },
+ *   kosParentId: 'translation-container'
+ * };
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
+ */
 export interface TranslationOptions extends KosParentAware {
+  /**
+   * Translation namespace identifier, typically corresponding to a feature area.
+   * Used to organize translations by functional domain and prevent key conflicts.
+   *
+   * @example "device-status"
+   * @example "user-settings"
+   * @example "maintenance-scheduler"
+   */
   namespace: string;
+
+  /**
+   * Current active locale for this translation model.
+   * Determines which language variant to load and display.
+   *
+   * @example "en" - English
+   * @example "es" - Spanish
+   * @example "pt-BR" - Brazilian Portuguese
+   */
   currentLocale: string;
+
+  /**
+   * Default fallback locale when translations are missing in the current locale.
+   * Typically set to the primary application language.
+   *
+   * @default "en"
+   */
   defaultLocale: string;
+
+  /**
+   * Optional base URL for translation file loading.
+   * Used with default file-based resolution strategy.
+   *
+   * @example "/assets/locales"
+   * @example "https://cdn.example.com/translations"
+   */
   rootUrl?: string;
+
+  /**
+   * Locale descriptors defining fallback chains and configuration for each locale.
+   * Maps locale codes to their fallback hierarchy and metadata.
+   */
   descriptor: Record<string, LocaleDescriptor>;
+
+  /**
+   * Optional custom path resolver for translation file loading.
+   * Overrides default path construction logic.
+   *
+   * @param namespace - Target translation namespace
+   * @param locale - Target locale code
+   * @returns Full path to translation resource
+   */
   resolver?: (namespace: string, locale: string) => string;
+
+  /**
+   * Optional custom bundle resolver for advanced translation loading strategies.
+   * Enables loading from APIs, device storage, or custom sources.
+   *
+   * @param namespace - Target translation namespace
+   * @param locale - Target locale code
+   * @param context - KOS context for accessing shared data
+   * @returns Promise resolving to translation data
+   */
   bundleResolver?: (
     namespace: string,
     locale: string,
@@ -20,12 +153,159 @@ export interface TranslationOptions extends KosParentAware {
 }
 
 // ---------------  TranslationContainer ---------------
+
+/**
+ * Configuration options for TranslationContainer model instances.
+ *
+ * This interface defines the configuration structure for translation container models,
+ * which manage multiple translation namespaces and coordinate global locale switching.
+ * Containers serve as the central orchestration point for internationalization in KOS
+ * applications.
+ *
+ * @example Basic Container Configuration
+ * ```typescript
+ * // Multi-namespace application translations
+ * const containerOptions: TranslationContainerOptions = {
+ *   lang: 'es',
+ *   defaultNamespace: 'common',
+ *   descriptor: {
+ *     namespaces: {
+ *       'common': {
+ *         basePath: '/assets/locales',
+ *         locales: {
+ *           'en': { file: 'en/common.json', defaultLocale: 'en' },
+ *           'es': { file: 'es/common.json', defaultLocale: 'en' },
+ *           'fr': { file: 'fr/common.json', defaultLocale: 'en' }
+ *         }
+ *       },
+ *       'dashboard': {
+ *         basePath: '/assets/locales',
+ *         locales: {
+ *           'en': { file: 'en/dashboard.json', defaultLocale: 'en' },
+ *           'es': { file: 'es/dashboard.json', defaultLocale: 'en' },
+ *           'fr': { file: 'fr/dashboard.json', defaultLocale: 'en' }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ *
+ * const appTranslations = TranslationContainer.instance('app-i18n')
+ *   .options(containerOptions)
+ *   .build();
+ * ```
+ *
+ * @example CDN-Based Translation Loading
+ * ```typescript
+ * // Custom resolver for CDN-hosted translations
+ * const cdnResolver = function(
+ *   namespace: string,
+ *   locale: string
+ * ): string {
+ *   return `https://cdn.example.com/translations/${namespace}/${locale}.json`;
+ * };
+ *
+ * const cdnOptions: TranslationContainerOptions = {
+ *   lang: 'ja',
+ *   resolver: cdnResolver,
+ *   descriptor: {
+ *     namespaces: {
+ *       'device-control': {
+ *         basePath: '', // Ignored with custom resolver
+ *         locales: {
+ *           'ja': { file: '', defaultLocale: 'en' },
+ *           'en': { file: '', defaultLocale: 'en' }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @example Development Environment Setup
+ * ```typescript
+ * // Hot-reload friendly configuration for development
+ * const devOptions: TranslationContainerOptions = {
+ *   lang: 'en',
+ *   rootUrl: '/dev-translations',
+ *   descriptor: {
+ *     namespaces: {
+ *       'ui': {
+ *         basePath: '/ui-translations',
+ *         locales: {
+ *           'en': { file: 'en/ui.json', defaultLocale: 'en' },
+ *           'es': { file: 'es/ui.json', defaultLocale: 'en' }
+ *         }
+ *       },
+ *       'forms': {
+ *         basePath: '/form-translations',
+ *         locales: {
+ *           'en': { file: 'en/forms.json', defaultLocale: 'en' },
+ *           'es': { file: 'es/forms.json', defaultLocale: 'en' }
+ *         }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
+ */
 export interface TranslationContainerOptions {
+  /**
+   * Current application-wide locale setting.
+   * Applied to all child translation models when they are created or updated.
+   *
+   * @example "en" - English
+   * @example "es" - Spanish
+   * @example "pt-BR" - Brazilian Portuguese
+   */
   lang: string;
+
+  /**
+   * Comprehensive locale and namespace descriptor defining the complete
+   * translation structure for the application.
+   */
   descriptor: Localization;
+
+  /**
+   * Optional default namespace for application-wide common translations.
+   * When specified, provides easy access to shared UI elements and messages.
+   *
+   * @example "common"
+   * @example "shared"
+   * @example "ui-elements"
+   */
   defaultNamespace?: string;
+
+  /**
+   * Optional base URL for all translation file loading.
+   * Applied as prefix to all translation resource paths.
+   *
+   * @example "/assets/locales"
+   * @example "https://cdn.example.com/app-translations"
+   * @example "/tenant-specific/translations"
+   */
   rootUrl?: string;
+
+  /**
+   * Optional URL for loading translation descriptor dynamically.
+   * Enables runtime configuration of translation structure.
+   *
+   * @example "/api/translations/descriptor"
+   * @example "https://config.example.com/translation-manifest.json"
+   */
   descriptorUrl?: string;
+
+  /**
+   * Optional custom resolver for translation file path construction.
+   * Overrides default path resolution logic for all namespaces.
+   *
+   * @param namespace - Target translation namespace
+   * @param locale - Target locale code
+   * @returns Full path to translation resource
+   */
   resolver?: (
     this: TranslationContainerModel,
     namespace: string,
@@ -33,6 +313,66 @@ export interface TranslationContainerOptions {
   ) => string;
 }
 
+/**
+ * Type definitions for variable interpolation in translation keys.
+ *
+ * Translation models support sophisticated variable substitution patterns
+ * for dynamic content in internationalized applications.
+ *
+ * @group KOS Model
+ * @category Internationalization
+ */
+export type ResolveTranslationOptions<T = string> =
+  | {
+      /**
+       * Context variables for template-based interpolation using {{variable}} syntax.
+       *
+       * @example
+       * ```typescript
+       * t('welcome.message', {
+       *   context: { username: 'John', unreadCount: 5 }
+       * })
+       * // "Welcome {{username}}, you have {{unreadCount}} messages"
+       * // Result: "Welcome John, you have 5 messages"
+       * ```
+       */
+      context?: Record<string, any>;
+
+      /**
+       * Data variables for macro-based interpolation using __variable__ syntax.
+       *
+       * @example
+       * ```typescript
+       * t('system.info', {
+       *   data: { version: '2.1.0', platform: 'Linux' }
+       * })
+       * // "System __version__ running on __platform__"
+       * // Result: "System 2.1.0 running on Linux"
+       * ```
+       */
+      data?: Record<string, any>;
+
+      /**
+       * Contextual modifier for conditional key resolution.
+       * Enables different translations based on application state.
+       *
+       * @example
+       * ```typescript
+       * // Translation file: { "title": "Create", "title_edit": "Update" }
+       * t('title', { context: 'edit' })
+       * // Resolves to "title_edit" key, returns "Update"
+       * ```
+       */
+      context?: string;
+
+      /**
+       * Fallback value when translation key is not found.
+       * Ensures graceful degradation for missing translations.
+       */
+      defaultValue?: T;
+    }
+  | string;
+
 declare global {
   interface AbstractModelFactory {
     createTranslation: (id: string, options: TranslationOptions) => Translation;

package/models/models/trouble/services/trouble-services.d.ts

@@ -17,7 +17,7 @@ export interface TroubleResponse {
  * @internal
  * Retrieves the initial Trouble data.
  */
-export declare const getTroubles: () => Promise<KosServiceResponse<TroubleResponse[]> | undefined>;
-export declare const resolveTrouble: (troubleId: string, tracker?: string) => Promise<FutureResponse>;
-export declare const bulkResolveTroubles: (troubleIds: string[], tracker?: string) => Promise<FutureResponse>;
+export declare const getTroubles: (servicePath: string) => Promise<KosServiceResponse<TroubleResponse[]> | undefined>;
+export declare const resolveTrouble: (troubleId: string, servicePath?: string, tracker?: string) => Promise<FutureResponse>;
+export declare const bulkResolveTroubles: (troubleIds: string[], servicePath?: string, tracker?: string) => Promise<FutureResponse>;
 //# sourceMappingURL=trouble-services.d.ts.map

package/models/models/trouble/services/trouble-services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trouble-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/services/trouble-services.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,kBAAkB,EAGnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAkB,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAO1E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,GAAG,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,GAAG,CAAC;CACX;AACD;;;;GAIG;AACH,eAAO,MAAM,WAAW,kEAGvB,CAAC;AAEF,eAAO,MAAM,cAAc,cAAqB,MAAM,YAAY,MAAM,4BAqBvE,CAAC;AAEF,eAAO,MAAM,mBAAmB,eAClB,MAAM,EAAE,YACV,MAAM,4BAuBjB,CAAC"}
+{"version":3,"file":"trouble-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/services/trouble-services.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,kBAAkB,EAGnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAkB,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAO1E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,GAAG,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,GAAG,CAAC;CACX;AACD;;;;GAIG;AACH,eAAO,MAAM,WAAW,gBAAuB,MAAM,+DAKpD,CAAC;AAEF,eAAO,MAAM,cAAc,cACd,MAAM,kCAEP,MAAM,4BAsBjB,CAAC;AAEF,eAAO,MAAM,mBAAmB,eAClB,MAAM,EAAE,kCAEV,MAAM,4BAuBjB,CAAC"}

package/models/models/trouble/trouble-model.d.ts

@@ -18,10 +18,11 @@ export declare class TroubleModelImpl<AdditionalData extends object = any> imple
     tags: string[];
     data: AdditionalData;
     rank: number;
+    servicePath: string;
     group?: string;
     createTime?: string;
     private _mapped;
-    constructor(modelId: string, { resolvable, tags, info, id, clientData, rank, ifaces, type, group, createTime, role, color, ...rest }: TroubleOptions, context: KosCreationContext);
+    constructor(modelId: string, { resolvable, tags, info, id, clientData, rank, ifaces, type, group, createTime, role, color, servicePath, ...rest }: TroubleOptions, context: KosCreationContext);
     getTitleWithContext(context: string): string;
     getSubtitleWithContext(context: string): string;
     get rawId(): string;

package/models/models/trouble/trouble-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trouble-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/trouble-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAInE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAExE,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAM1C,qBACa,gBAAgB,CAAC,cAAc,SAAS,MAAM,GAAG,GAAG,CAC/D,YAAW,YAAY,CAAC,cAAc,CAAC,EAAE,eAAe;IAExD,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAU;IAE7B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,oBAAoB,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IAEb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,OAAO,CAAwB;gBAErC,OAAO,EAAE,MAAM,EACf,EACE,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,UAAU,EACV,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,KAAK,EACL,UAAU,EACV,IAAI,EACJ,KAAK,EACL,GAAG,IAAI,EACR,EAAE,cAAc,EACjB,OAAO,EAAE,kBAAkB;IAyB7B,mBAAmB,CAAC,OAAO,EAAE,MAAM;IAWnC,sBAAsB,CAAC,OAAO,EAAE,MAAM;IAWtC,IAAI,KAAK,WAER;IACD,IAAI,KAAK,WAER;IAED,IAAI,QAAQ,WAEX;IAED,IAAI,SAAS,WAEZ;IAED,IAAI,UAAU,YAEb;IAED,IAAI,MAAM,uFAET;IAEK,iBAAiB;IAIvB,IAAI,iBAAiB,qEAMpB;IACD,IAAI,QAAQ,YAKX;IACD,IAAI,WAAW,IAAI,OAAO,CAMzB;IAED,UAAU;IAGV,KAAK;IAIL,WAAW;IAML,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM;CAc/B"}
+{"version":3,"file":"trouble-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/trouble-model.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AAGvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAInE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAExE,eAAO,MAAM,UAAU,kBAAkB,CAAC;AAM1C,qBACa,gBAAgB,CAAC,cAAc,SAAS,MAAM,GAAG,GAAG,CAC/D,YAAW,YAAY,CAAC,cAAc,CAAC,EAAE,eAAe;IAExD,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,WAAW,CAAU;IAE7B,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,oBAAoB,CAAC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,OAAO,CAAwB;gBAErC,OAAO,EAAE,MAAM,EACf,EACE,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,EAAE,EACF,UAAU,EACV,IAAI,EACJ,MAAM,EACN,IAAI,EACJ,KAAK,EACL,UAAU,EACV,IAAI,EACJ,KAAK,EACL,WAAW,EACX,GAAG,IAAI,EACR,EAAE,cAAc,EACjB,OAAO,EAAE,kBAAkB;IAyB7B,mBAAmB,CAAC,OAAO,EAAE,MAAM;IAWnC,sBAAsB,CAAC,OAAO,EAAE,MAAM;IAWtC,IAAI,KAAK,WAER;IACD,IAAI,KAAK,WAER;IAED,IAAI,QAAQ,WAEX;IAED,IAAI,SAAS,WAEZ;IAED,IAAI,UAAU,YAEb;IAED,IAAI,MAAM,uFAET;IAEK,iBAAiB;IAIvB,IAAI,iBAAiB,qEAMpB;IACD,IAAI,QAAQ,YAKX;IACD,IAAI,WAAW,IAAI,OAAO,CAMzB;IAED,UAAU;IAGV,KAAK;IAIL,WAAW;IAML,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM;CAc/B"}

package/models/models/trouble/types/index.d.ts

@@ -28,8 +28,8 @@ import { IKosDataModel } from '../../../core';
  * };
  * ```
  *
- * @category Trouble Management
- * @subcategory Types
+ * @group KOS Model
+ * @category Types
  */
 export interface TroubleOptions<AdditionalData extends object = any> {
   /** Whether this trouble can be resolved through user action */
@@ -58,6 +58,8 @@ export interface TroubleOptions<AdditionalData extends object = any> {
   info: unknown;
   /** Optional grouping identifier for related troubles */
   group?: string;
+  /** Service path for the trouble instance */
+  servicePath?: string;
   /** Index signature for additional domain-specific data */
   [key: keyof AdditionalData]: AdditionalData[key];
 }
@@ -80,96 +82,23 @@ export interface TroubleOptions<AdditionalData extends object = any> {
  *
  * @template AdditionalData - Type parameter for domain-specific trouble data
  *
- * @example
+ * @interface
+ * @example Basic Usage
  * ```typescript
- * // Check trouble severity
  * function handleTrouble(trouble: TroubleModel) {
  *   if (trouble.rank >= 8) {
  *     console.error(`Critical trouble: ${trouble.reason}`);
- *     notifyOperator(trouble);
- *   } else if (trouble.rank >= 5) {
- *     console.warn(`Warning: ${trouble.reason}`);
- *   }
- *
- *   // Check if user can resolve
- *   if (trouble.resolvable && hasRole(trouble.role)) {
- *     showResolveButton(trouble);
- *   }
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Resolve a trouble with proper future handling
- * async function resolveTrouble(trouble: TroubleModel) {
- *   if (!trouble.resolvable) {
- *     throw new Error('Trouble is not resolvable');
  *   }
  *
- *   try {
- *     // Resolution returns a FutureResponse with future tracking
+ *   if (trouble.resolvable) {
  *     const futureResponse = await trouble.resolve();
- *     if (futureResponse) {
- *       console.log(`Resolution started, future ID: ${futureResponse.id}`);
- *
- *       // The trouble's future property will be updated with the resolution future
- *       // You can track progress through the future model
- *       if (trouble.future) {
- *         const endState = await trouble.future.waitForCompletion();
- *         if (endState === 'COMPLETED') {
- *           console.log('Trouble resolved successfully');
- *         } else if (endState === 'FAILED') {
- *           console.error('Resolution failed');
- *         }
- *       }
- *     }
- *   } catch (error) {
- *     console.error('Failed to initiate resolution:', error);
- *   }
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Using cancellable promise utilities with trouble resolution
- * import { createCancellablePromise } from '@kosdev-code/kos-ui-sdk';
- *
- * async function resolveTroubleWithCancel(trouble: TroubleModel) {
- *   const futureResponse = await trouble.resolve();
- *
- *   if (futureResponse && trouble.future) {
- *     // Create a cancellable promise for the resolution
- *     const cancellableResolve = createCancellablePromise(
- *       trouble.future.waitForCompletion(),
- *       undefined,
- *       () => trouble.future?.cancelFuture(),
- *       trouble.future
- *     );
- *
- *     // Subscribe to progress updates
- *     const unsubscribe = cancellableResolve.onProgressUpdate((progress, status) => {
- *       console.log(`Resolution progress: ${(progress * 100).toFixed(0)}% - ${status}`);
- *     });
- *
- *     try {
- *       const endState = await cancellableResolve;
- *       console.log(`Resolution completed with state: ${endState}`);
- *     } catch (error) {
- *       if (cancellableResolve.isCancelled()) {
- *         console.log('Resolution was cancelled');
- *       } else {
- *         console.error('Resolution failed:', error);
- *       }
- *     } finally {
- *       unsubscribe();
- *     }
  *   }
  * }
  * ```
  *
- *
- * @category KOS Model
- * @subcategory Trouble Management
+ * @useDeclaredType
+ * @group KOS Model
+ * @category Trouble Management
  *
  * @see {@link TroubleAware} - Interface for models that can have troubles
  * @see {@link DeferAware} - Deferral capabilities
@@ -220,8 +149,8 @@ export interface TroubleModel<AdditionalData extends object = any>
 /**
  * Domain-specific trouble data for handle-related issues.
  *
- * @category Trouble Management
- * @subcategory Domain Data
+ * @group KOS Model
+ * @category Domain Data
  */
 export interface HandleTroubleData {
   /** Path to the affected handle component */
@@ -231,8 +160,8 @@ export interface HandleTroubleData {
 /**
  * Domain-specific trouble data for nozzle-related issues.
  *
- * @category Trouble Management
- * @subcategory Domain Data
+ * @group KOS Model
+ * @category Domain Data
  */
 export interface NozzleTroubleData {
   /** Path to the affected nozzle component */
@@ -242,8 +171,8 @@ export interface NozzleTroubleData {
 /**
  * Domain-specific trouble data for container-related issues.
  *
- * @category Trouble Management
- * @subcategory Domain Data
+ * @group KOS Model
+ * @category Domain Data
  */
 export interface ContainerTroubleData {
   /** Identifier of the affected container */
@@ -270,8 +199,8 @@ export interface ContainerTroubleData {
  * }
  * ```
  *
- * @category Trouble Management
- * @subcategory Capabilities
+ * @group KOS Model
+ * @category Capabilities
  */
 export interface ResolveAware {
   /**
@@ -314,8 +243,8 @@ export interface ResolveAware {
  * }
  * ```
  *
- * @category Trouble Management
- * @subcategory Capabilities
+ * @group KOS Model
+ * @category Capabilities
  */
 export interface DeferAware {
   /** Whether this item should be deferred based on current conditions */
@@ -410,8 +339,8 @@ export interface DeferAware {
  * }
  * ```
  *
- * @category Trouble Management
- * @subcategory Interfaces
+ * @group KOS Model
+ * @category Interfaces
  *
  * @see {@link TroubleModel} - The trouble model interface
  * @see {@link isTroubleAware} - Type guard for checking TroubleAware

package/models/models/trouble/utils/is-trouble-aware.d.ts

@@ -9,7 +9,7 @@ import { TroubleAware } from '../types';
  * object, which are required by the TroubleAware interface.
  *
  * @category Utilities
- * @subcategory Trouble Management
+ * @category Trouble Management
  *
  * @param obj - The object to check for trouble awareness. Can be any type.
  *
@@ -94,5 +94,5 @@ import { TroubleAware } from '../types';
  * @see {@link TroubleAware} - The interface this function checks for
  * @see {@link useTroubleDecoration} - Hook that uses this guard internally
  */
-export declare function isTroubleAware(obj: any): obj is TroubleAware;
+export declare function isTroubleAware(obj?: any): obj is TroubleAware;
 //# sourceMappingURL=is-trouble-aware.d.ts.map

package/models/models/trouble/utils/is-trouble-aware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"is-trouble-aware.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/utils/is-trouble-aware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,IAAI,YAAY,CAO5D"}
+{"version":3,"file":"is-trouble-aware.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble/utils/is-trouble-aware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,wBAAgB,cAAc,CAAC,GAAG,CAAC,EAAE,GAAG,GAAG,GAAG,IAAI,YAAY,CAO7D"}

package/models/models/trouble-container/index.d.ts

@@ -1,4 +1,5 @@
-export { Troubles } from './trouble-container-model';
-export { TroubleContainer } from './trouble-container-registration';
-export type { TroubleContainerModel, TroubleContainerOptions } from './types';
+import { TroubleContainerModelImpl } from './trouble-container-model';
+export { Troubles, type TroubleContainerModel, } from './trouble-container-model';
+export type { TroubleContainerOptions } from './types';
+export declare const TroubleContainer: import('../../..').KosModelRegistrationType<TroubleContainerModelImpl, import('./types').TroubleContainerOptions>;
 //# sourceMappingURL=index.d.ts.map

package/models/models/trouble-container/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble-container/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,YAAY,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble-container/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,qBAAqB,GAC3B,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,eAAO,MAAM,gBAAgB,mHAAyC,CAAC"}

package/models/models/trouble-container/trouble-container-model.d.ts

@@ -1,9 +1,12 @@
-import { TroubleContainerModel } from './types';
+import { TroubleContainerOptions } from './types';
 import { TroubleModel } from '../trouble/types';
 import { TroubleResponse } from '../trouble/services';
-import { IKosModelContainer } from '../../../core/core/kos-container-model';
+import { IKosDataModel, IKosIdentifiable, KosContainerAwareWithProp, KosLoggerAware, KosModelRegistrationType, PublicModelInterface } from '../../../core';
 
 export declare const MODEL_TYPE = "trouble-container-model";
+export type TroubleContainerModel = PublicModelInterface<TroubleContainerModelImpl>;
+export interface TroubleContainerModelImpl extends KosContainerAwareWithProp<TroubleModel, "troubles">, KosLoggerAware {
+}
 export declare class Troubles {
     static readonly INDEX_TROUBLES_BY_IFACE = "byIface";
     static readonly INDEX_TROUBLES_BY_TYPE = "byType";
@@ -12,10 +15,11 @@ export declare class Troubles {
     static readonly SORT_KEY_RANK = "rank";
     static readonly TROUBLES_DEFERRED = "true";
 }
-export declare class TroubleContainerModelImpl implements TroubleContainerModel {
+export declare class TroubleContainerModelImpl implements IKosIdentifiable, IKosDataModel {
+    static Registration: KosModelRegistrationType<TroubleContainerModelImpl, TroubleContainerOptions>;
     id: string;
-    troubles: IKosModelContainer<TroubleModel>;
-    constructor(modelId: string);
+    servicePath: string;
+    constructor(modelId: string, options: TroubleContainerOptions);
     load(): Promise<void>;
     handleTroubleRemoved(id: string): void;
     handleTroubleAdded(trouble: TroubleResponse): void;

package/models/models/trouble-container/trouble-container-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trouble-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble-container/trouble-container-model.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC;AAOjF,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAuCrD,eAAO,MAAM,UAAU,4BAA4B,CAAC;AAEpD,qBAAa,QAAQ;IACnB,MAAM,CAAC,QAAQ,CAAC,uBAAuB,aAAa;IACpD,MAAM,CAAC,QAAQ,CAAC,sBAAsB,YAAY;IAClD,MAAM,CAAC,QAAQ,CAAC,uBAAuB,aAAa;IACpD,MAAM,CAAC,QAAQ,CAAC,0BAA0B,gBAAgB;IAC1D,MAAM,CAAC,QAAQ,CAAC,aAAa,UAAU;IACvC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,UAAU;CAC5C;AACD,qBACa,yBAA0B,YAAW,qBAAqB;IACrE,EAAE,EAAE,MAAM,CAAC;IAED,QAAQ,EAAE,kBAAkB,CAAC,YAAY,CAAC,CAAC;gBACzC,OAAO,EAAE,MAAM;IAiBrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B3B,oBAAoB,CAAC,EAAE,EAAE,MAAM;IAW/B,kBAAkB,CAAC,OAAO,EAAE,eAAe;CAe5C"}
+{"version":3,"file":"trouble-container-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/trouble-container/trouble-container-model.ts"],"names":[],"mappings":"AACA,OAAO,EAQL,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AAQvB,OAAO,EAAe,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAExE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAqCvD,eAAO,MAAM,UAAU,4BAA4B,CAAC;AAEpD,MAAM,MAAM,qBAAqB,GAC/B,oBAAoB,CAAC,yBAAyB,CAAC,CAAC;AAClD,MAAM,WAAW,yBACf,SAAQ,yBAAyB,CAAC,YAAY,EAAE,UAAU,CAAC,EACzD,cAAc;CAAG;AACrB,qBAAa,QAAQ;IACnB,MAAM,CAAC,QAAQ,CAAC,uBAAuB,aAAa;IACpD,MAAM,CAAC,QAAQ,CAAC,sBAAsB,YAAY;IAClD,MAAM,CAAC,QAAQ,CAAC,uBAAuB,aAAa;IACpD,MAAM,CAAC,QAAQ,CAAC,0BAA0B,gBAAgB;IAC1D,MAAM,CAAC,QAAQ,CAAC,aAAa,UAAU;IACvC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,UAAU;CAC5C;AACD,qBAca,yBACX,YAAW,gBAAgB,EAAE,aAAa;IAE1C,MAAM,CAAC,YAAY,EAAE,wBAAwB,CAC3C,yBAAyB,EACzB,uBAAuB,CACxB,CAAC;IACF,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,SAAuB;gBACtB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,uBAAuB;IAOvD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B3B,oBAAoB,CAAC,EAAE,EAAE,MAAM;IAW/B,kBAAkB,CAAC,OAAO,EAAE,eAAe;CAgB5C"}