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

package/models/models/storage-device/storage-device-model.d.ts

@@ -2,26 +2,108 @@ import { StorageDeviceOptions } from './types';
 import { IKosDataModel, IKosIdentifiable, KosCreationContext, PublicModelInterface } from '../../../core';
 
 export declare const MODEL_TYPE = "storage-device-model";
+/**
+ * StorageDevice - Manages individual USB/external storage device information and state.
+ *
+ * The StorageDevice model represents individual storage devices (USB drives, SD cards,
+ * external drives) connected to the KOS system. It tracks device hardware information,
+ * mount status, and provides access to device metadata including vendor, model, runtime
+ * statistics, and file system details.
+ *
+ * ## Key Features
+ * - **Hardware Information** - Vendor, model, and system path details
+ * - **Mount Management** - Track mount directory and removal status
+ * - **Runtime Statistics** - Device runtime and usage metrics
+ * - **Node Awareness** - Multi-node device distribution tracking
+ * - **File System Integration** - Label and mount point management
+ * - **Parent-Aware Architecture** - Designed for container model management
+ *
+ * ## Device Properties
+ * Storage devices expose comprehensive hardware and state information:
+ * - **Physical Details**: vendor, model, syspath for hardware identification
+ * - **Mount Information**: mountDir, label for file system access
+ * - **Status Tracking**: removed flag, local/remote node distribution
+ * - **Runtime Metrics**: runTimeMs for usage analytics
+ *
+ * ## Common Use Cases
+ * - **Storage Management UI** - Display available storage devices and capacity
+ * - **File Transfer Operations** - Access mount points for file operations
+ * - **System Monitoring** - Track device insertion/removal events
+ * - **Backup Management** - Identify backup destination devices
+ * - **Multi-node Systems** - Manage storage across distributed KOS nodes
+ * - **Device Diagnostics** - Runtime statistics and health monitoring
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const usbDrive = StorageDevice.instance('usb-drive-1')
+ *   .options({
+ *     mountDir: '/media/usb1',
+ *     vendor: 'SanDisk',
+ *     model: 'Ultra USB 3.0',
+ *     label: 'BACKUP_DRIVE',
+ *     nodeId: 'primary',
+ *     local: true,
+ *     removed: false,
+ *     runTimeMs: 1800000,
+ *     syspath: '/sys/devices/usb1'
+ *   })
+ *   .build();
+ *
+ * // Access device properties
+ * console.log(`${usbDrive.vendor} ${usbDrive.model} at ${usbDrive.mountDir}`);
+ * ```
+ *
+ * @group KOS Model
+ * @category Device Management
+ * @useDeclaredType
+ *
+ * @see {@link StorageDeviceOptions} - Configuration options for StorageDevice instances
+ * @see {@link StorageDeviceContainerModel} - Container for managing multiple storage devices
+ * @see {@link StorageDeviceResponse} - API response structure for device data
+ */
+export type StorageDevice = PublicModelInterface<StorageDeviceModelImpl>;
 export type StorageDeviceModel = PublicModelInterface<StorageDeviceModelImpl>;
 /**
- * Storage Device Model
- * @category Model
+ * @ignore
+ * @internal
  */
 export declare class StorageDeviceModelImpl implements IKosDataModel, IKosIdentifiable {
+    /** Unique identifier for the storage device model instance */
     id: string;
+    /** File system mount directory path where device is accessible */
     mountDir: string;
+    /** Whether the device has been physically removed from the system */
     removed: boolean;
+    /** Device manufacturer name (e.g., 'SanDisk', 'Western Digital') */
     vendor: string;
+    /** Total device runtime in milliseconds for usage tracking */
     runTimeMs: number;
+    /** Device model name or identifier (e.g., 'Ultra USB 3.0', 'My Passport') */
     model: string;
+    /** KOS node identifier where this device is connected */
     nodeId: string;
+    /** Whether the device is connected to the local node */
     local: boolean;
+    /** File system label or volume name for the device */
     label: string;
+    /** System path for hardware identification and low-level access */
     syspath: string;
+    /** Context logger for debugging and diagnostics */
     private logger;
     constructor(modelId: string, options: StorageDeviceOptions, context: KosCreationContext);
+    /**
+     * Updates the storage device model with new configuration options.
+     * @param options New configuration options to apply to the device
+     */
     updateModel(options: StorageDeviceOptions): void;
+    /**
+     * @internal
+     */
     init(): Promise<void>;
+    /**
+     * @internal
+     */
     load(): Promise<void>;
 }
 //# sourceMappingURL=storage-device-model.d.ts.map

package/models/models/storage-device/storage-device-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-device-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/storage-device/storage-device-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAEhB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD,eAAO,MAAM,UAAU,yBAAyB,CAAC;AAEjD,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AAE9E;;;GAGG;AACH,qBAEa,sBAAuB,YAAW,aAAa,EAAE,gBAAgB;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IAEjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,MAAM,CAAmB;gBAE/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,kBAAkB;IAe7B,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAc1C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}
+{"version":3,"file":"storage-device-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/storage-device/storage-device-model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAEhB,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD,eAAO,MAAM,UAAU,yBAAyB,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,MAAM,aAAa,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AAEzE,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,CAAC,sBAAsB,CAAC,CAAC;AAE9E;;;GAGG;AACH,qBAEa,sBAAuB,YAAW,aAAa,EAAE,gBAAgB;IAC5E,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,EAAE,OAAO,CAAC;IACf,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,OAAO,CAAC,MAAM,CAAmB;gBAE/B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,EAC7B,OAAO,EAAE,kBAAkB;IAe7B;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAchD;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAG5B"}

package/models/models/storage-device/types/index.d.ts

@@ -3,18 +3,130 @@ import { KosParentAware } from '../../../../core';
 
 // ---------------  StorageDevice ---------------
 
+/**
+ * Configuration options for StorageDevice model instances.
+ *
+ * This interface defines the complete configuration structure for individual storage devices,
+ * including hardware identification, mount information, and runtime metrics. These options
+ * are typically populated from storage device discovery services and WebSocket updates.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const device = StorageDevice.instance('usb-backup')
+ *   .options({
+ *     mountDir: '/media/usb-drive',
+ *     vendor: 'SanDisk',
+ *     model: 'Ultra USB 3.0',
+ *     label: 'BACKUP_DRIVE',
+ *     nodeId: 'primary',
+ *     local: true,
+ *     removed: false,
+ *     runTimeMs: 1800000,
+ *     syspath: '/sys/devices/usb1'
+ *   })
+ *   .build();
+ * ```
+ *
+ * @category Model Configuration
+ * @category Device Management
+ */
 export interface StorageDeviceOptions extends KosParentAware {
+  /**
+   * File system mount directory path where the device is accessible.
+   * Empty string indicates the device is not currently mounted.
+   *
+   * @example "/media/usb-drive"
+   * @example "/mnt/backup-storage"
+   * @example "" // Not mounted
+   */
   mountDir: string;
+
+  /**
+   * Indicates whether the storage device has been physically removed.
+   * When true, the device is no longer accessible and mount operations will fail.
+   *
+   * @default false
+   */
   removed: boolean;
+
+  /**
+   * Hardware vendor/manufacturer name of the storage device.
+   * Used for device identification and display purposes.
+   *
+   * @example "SanDisk"
+   * @example "Western Digital"
+   * @example "Samsung"
+   */
   vendor: string;
+
+  /**
+   * Total runtime in milliseconds since the device was first connected.
+   * Tracks cumulative usage time for analytics and maintenance scheduling.
+   *
+   * @example 1800000 // 30 minutes
+   * @example 3600000 // 1 hour
+   */
   runTimeMs: number;
+
+  /**
+   * Hardware model name/number of the storage device.
+   * Combined with vendor for complete device identification.
+   *
+   * @example "Ultra USB 3.0"
+   * @example "My Passport"
+   * @example "EVO Select 64GB"
+   */
   model: string;
+
+  /**
+   * KOS node identifier where this storage device is physically connected.
+   * Used in multi-node systems to track device distribution.
+   *
+   * @example "primary"
+   * @example "secondary"
+   * @example "embedded-node-1"
+   */
   nodeId: string;
+
+  /**
+   * Indicates if the device is connected to the local node (true) or remote node (false).
+   * Determines accessibility and operation capabilities from current context.
+   *
+   * @default true
+   */
   local: boolean;
+
+  /**
+   * File system label/name assigned to the storage device.
+   * Used for user-friendly identification and mount point organization.
+   *
+   * @example "BACKUP_DRIVE"
+   * @example "CONFIG_STORAGE"
+   * @example "DATA_ARCHIVE"
+   */
   label: string;
+
+  /**
+   * System device path in the Linux device tree.
+   * Low-level hardware identifier for device tracking and diagnostics.
+   *
+   * @example "/sys/devices/pci0000:00/usb1/1-2"
+   * @example "/sys/devices/mmc0/mmc0:0001"
+   * @example "/sys/devices/platform/sdhci"
+   */
   syspath: string;
 }
 
 // ---------------  StorageDeviceContainer ---------------
 
+/**
+ * Configuration options for StorageDeviceContainer model instances.
+ *
+ * The container model manages collections of storage devices and handles real-time
+ * updates via WebSocket topics. Currently uses an empty configuration object as
+ * the container's behavior is primarily driven by discovered storage devices.
+ *
+ * @category Model Configuration
+ * @category Device Management
+ */
 export type StorageDeviceContainerOptions = object;

package/models/models/studio-properties/studio-properties-model.d.ts

@@ -4,19 +4,94 @@ import { IKosIdentifiable } from '../../../core/core/types';
 import { IKosDataModel, KosCreationContext } from '../../../core/core/kosModel';
 
 export declare const MODEL_TYPE = "studio-properties-model";
+/**
+ * StudioPropertiesModel - Real-time KOS Studio properties management with WebSocket synchronization.
+ *
+ * This model provides centralized access to KOS Studio's runtime properties and configuration
+ * values, enabling applications to access Studio-specific settings, tool states, and integration
+ * parameters. Properties are synchronized in real-time via WebSocket topics, ensuring all
+ * connected clients maintain consistent Studio state information.
+ *
+ * ## Key Features
+ * - **Real-time synchronization** - Properties update automatically via `/kos/studio/properties` topic
+ * - **Connection-scoped access** - Properties are specific to individual Studio VM connections
+ * - **Fallback handling** - Graceful degradation with default values when Studio is unavailable
+ * - **Observable properties** - Create reactive computed values for any property key
+ * - **Session management** - Automatic WebSocket session lifecycle with proper cleanup
+ *
+ * ## Topic-Based Reactivity
+ * The model listens to this KOS topic for real-time synchronization:
+ * - **`/kos/studio/properties`** - Broadcasts Studio property changes with connection-specific routing
+ *
+ * ## Common Use Cases
+ * - **Studio integration status** - Check if legacy tools or specific Studio features are enabled
+ * - **Tool configuration** - Access Studio tool settings and preferences for UI adaptation
+ * - **Connection management** - Track Studio connection state and properties for diagnostics
+ * - **Feature flags** - Access Studio-specific feature toggles and experimental settings
+ *
+ * @interface
+ * @example Basic Usage
+ * ```typescript
+ * const studioProps = StudioPropertiesModel.instance('studio-conn-1')
+ *   .options({ connectionId: 'vm-connection-abc123' })
+ *   .build();
+ *
+ * await studioProps.initializePropertiesSession();
+ * const legacyToolSupport = studioProps.get('kos.studio.tool.legacy');
+ * ```
+ *
+ * @group KOS Model
+ * @category System Integration
+ * @useDeclaredType
+ *
+ * @see {@link StudioPropertiesOptions} - Configuration options for StudioPropertiesModel instances
+ */
 export type StudioPropertiesModel = PublicModelInterface<StudioPropertiesModelImpl>;
+/**
+ * @ignore
+ * @internal
+ */
 export declare class StudioPropertiesModelImpl implements IKosDataModel, IKosIdentifiable {
+    /** Unique identifier for the model instance */
     id: string;
+    /** Studio VM connection identifier for property routing */
     connectionId: string;
+    /** WebSocket subscription cleanup function */
     private unsubscribe;
+    /** Context logger for debugging and diagnostics */
     private logger;
+    /** Observable data store for Studio properties */
     private data;
     constructor(modelId: string, options: StudioPropertiesOptions, context: KosCreationContext);
+    /**
+     * @internal
+     */
     init(): Promise<void>;
+    /**
+     * @internal
+     */
     load(): Promise<void>;
+    /**
+     * Terminates the WebSocket session for Studio properties.
+     * Cleans up subscriptions to prevent memory leaks.
+     */
     terminatePropertiesSession(): Promise<void>;
+    /**
+     * Initializes WebSocket session for real-time Studio property synchronization.
+     * Loads initial properties and subscribes to update topics.
+     */
     initializePropertiesSession(): Promise<void>;
+    /**
+     * Retrieves a Studio property value by key.
+     * @param key Property key to retrieve
+     * @returns The property value or undefined if not set
+     */
     get(key: string): any;
+    /**
+     * Creates an observable computed property for reactive updates.
+     * @param key Property key to observe
+     * @returns Observable that emits when the property changes
+     */
     createObservableProperty(key: string): import('mobx').IComputedValue<any>;
 }
 //# sourceMappingURL=studio-properties-model.d.ts.map

package/models/models/studio-properties/studio-properties-model.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"studio-properties-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/studio-properties/studio-properties-model.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEvD,eAAO,MAAM,UAAU,4BAA4B,CAAC;AAGpD,MAAM,MAAM,qBAAqB,GAC/B,oBAAoB,CAAC,yBAAyB,CAAC,CAAC;AAMlD,qBACa,yBACX,YAAW,aAAa,EAAE,gBAAgB;IAE1C,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,MAAM,CAAmB;IAEjC,OAAO,CAAC,IAAI,CAA+B;gBAEzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,kBAAkB;IAWvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAG3C,2BAA2B;IA8BjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;IAIrB,wBAAwB,CAAC,GAAG,EAAE,MAAM;CAGrC"}
+{"version":3,"file":"studio-properties-model.d.ts","sourceRoot":"","sources":["../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/studio-properties/studio-properties-model.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,aAAa,EAEb,kBAAkB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AAEvD,eAAO,MAAM,UAAU,4BAA4B,CAAC;AAIpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,MAAM,qBAAqB,GAC/B,oBAAoB,CAAC,yBAAyB,CAAC,CAAC;AAMlD;;;GAGG;AACH,qBACa,yBACX,YAAW,aAAa,EAAE,gBAAgB;IAE1C,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,OAAO,CAAC,WAAW,CAA6B;IAChD,mDAAmD;IACnD,OAAO,CAAC,MAAM,CAAmB;IACjC,kDAAkD;IAClD,OAAO,CAAC,IAAI,CAA+B;gBAEzC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,kBAAkB;IAW7B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;;OAGG;IACG,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjD;;;OAGG;IACG,2BAA2B;IA8BjC;;;;OAIG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;IAIrB;;;;OAIG;IACH,wBAAwB,CAAC,GAAG,EAAE,MAAM;CAGrC"}

package/models/models/studio-properties/types/index.d.ts

@@ -1,3 +1,32 @@
+/**
+ * Configuration options for StudioPropertiesModel instances.
+ *
+ * This interface defines the configuration structure for Studio properties models,
+ * which manage real-time access to KOS Studio runtime properties and settings.
+ * The connection ID serves as the primary routing mechanism for Studio-specific
+ * property synchronization.
+ *
+ * @example Basic Usage
+ * ```typescript
+ * const studioProps = StudioPropertiesModel.instance('dev-studio')
+ *   .options({ connectionId: 'vm-development-001' })
+ *   .build();
+ * ```
+ *
+ * @category Model Configuration
+ * @category System Integration
+ */
 export interface StudioPropertiesOptions {
+  /**
+   * Studio VM connection identifier for property routing and WebSocket targeting.
+   * 
+   * This ID corresponds to an active Studio connection and determines which Studio
+   * instance provides the properties. Each Studio VM connection has unique runtime
+   * properties and configuration values.
+   *
+   * @example "vm-development-local-001"
+   * @example "studio-connection-abc123" 
+   * @example "primary-studio-instance"
+   */
   connectionId: string;
 }

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

@@ -1,25 +1,151 @@
+/**
+ * @fileoverview Translation service functions for internationalization and localization.
+ *
+ * This module provides service functions for loading translation data, managing locale
+ * descriptors, and handling multi-language content in KOS applications. Supports both
+ * static file-based translations and dynamic translation service integration.
+ *
+ * @module TranslationServices
+ */
+/**
+ * Generic translation data response format.
+ *
+ * Represents the structure of translation data returned from various translation
+ * endpoints, supporting flexible key-value structures for different locales
+ * and translation namespaces.
+ *
+ * @group KOS Model
+ * @category i18n
+ */
 export type TranslationResponse = Record<string, any>;
+/**
+ * Locale descriptor defining translation file location and fallback behavior.
+ *
+ * Describes how to locate and load translation files for a specific locale,
+ * including fallback chains for graceful degradation when translations are
+ * missing or incomplete.
+ *
+ * @group KOS Model
+ * @category i18n
+ */
 export interface LocaleDescriptor {
+    /** Default locale to use when this locale's translations are unavailable */
     defaultLocale: string;
+    /** Path to the translation file for this locale */
     file: string;
+    /** Optional array of fallback locales to try in order */
     fallbacks?: string[];
 }
+/**
+ * Complete localization configuration for organizing translation namespaces.
+ *
+ * Defines the structure for managing multiple translation namespaces with
+ * locale-specific configurations. Enables organized translation management
+ * across different features or components of an application.
+ *
+ * @group KOS Model
+ * @category i18n
+ */
 export interface Localization {
+    /**
+     * Translation namespaces organized by feature or component.
+     * Each namespace contains locale configurations and file paths.
+     */
     namespaces: {
         [key: string]: {
+            /** Locale-specific configuration for this namespace */
             locales: {
                 [key: string]: LocaleDescriptor;
             };
+            /** Base path for translation files in this namespace */
             basePath: string;
         };
     };
+    /** Root path for the localization configuration */
     path: string;
 }
 /**
- * @category Service
- * Retrieves the initial translation data.
+ * Loads translation data from a specified URL.
+ *
+ * Fetches translation JSON files from static resources or translation services.
+ * Handles network errors gracefully by returning empty objects rather than
+ * throwing exceptions, enabling fallback behavior in translation systems.
+ *
+ * @param url - Relative or absolute URL to the translation file
+ * @param root - Optional root URL override (defaults to current window origin)
+ * @returns Promise resolving to translation data object
+ *
+ * @throws {Error} When network request fails unexpectedly (non-200 responses return empty object)
+ *
+ * @example Load Translation File
+ * ```typescript
+ * const frenchTranslations = await getTranslations('/assets/locales/fr/common.json');
+ * console.log('Welcome message:', frenchTranslations.welcome);
+ *
+ * const customTranslations = await getTranslations('/api/translations/dashboard', 'https://translations.example.com');
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
  */
 export declare const getTranslations: (url: string, root?: string) => Promise<any>;
+/**
+ * Retrieves the system-wide localization configuration descriptor.
+ *
+ * Fetches the complete localization configuration from the KOS system,
+ * including namespace definitions, locale mappings, and file path information.
+ * Used for initializing translation containers with proper configuration.
+ *
+ * @returns Promise resolving to complete localization descriptor
+ *
+ * @throws {Error} When service request fails or returns non-200 status
+ *
+ * @example Initialize Translation System
+ * ```typescript
+ * const localizationConfig = await getLocalizationDescriptor();
+ * const translationContainer = TranslationContainer.instance('app-i18n')
+ *   .options({
+ *     lang: 'en',
+ *     descriptor: localizationConfig
+ *   })
+ *   .build();
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
+ */
 export declare const getLocalizationDescriptor: () => Promise<Localization>;
+/**
+ * Creates a context-specific localization descriptor retrieval function.
+ *
+ * Returns a curried function that fetches localization configuration for a
+ * specific context from the KOS system. Useful for creating context-aware
+ * translation loaders that can be configured once and used multiple times.
+ *
+ * @param context - Context identifier for localization configuration
+ * @returns Async function that retrieves context-specific localization descriptor
+ *
+ * @throws {Error} When service request fails or context is not found
+ *
+ * @example Create Context-Specific Loader
+ * ```typescript
+ * const getStudioTranslations = getKosLocalizationDescriptor('studio');
+ * const studioConfig = await getStudioTranslations();
+ *
+ * const getDeviceTranslations = getKosLocalizationDescriptor('device');
+ * const deviceConfig = await getDeviceTranslations();
+ *
+ * // Use in translation container initialization
+ * const container = TranslationContainer.instance('context-aware')
+ *   .options({
+ *     lang: 'es',
+ *     descriptor: studioConfig
+ *   })
+ *   .build();
+ * ```
+ *
+ * @group KOS Model
+ * @category i18n
+ */
 export declare const getKosLocalizationDescriptor: (context: string) => () => Promise<Localization>;
 //# sourceMappingURL=translation-services.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"translation-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/translation/services/translation-services.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEtD,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AACD,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE;QACV,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,OAAO,EAAE;gBACP,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAC;aACjC,CAAC;YACF,QAAQ,EAAE,MAAM,CAAC;SAClB,CAAC;KACH,CAAC;IACF,IAAI,EAAE,MAAM,CAAC;CACd;AASD;;;GAGG;AACH,eAAO,MAAM,eAAe,QAAe,MAAM,SAAS,MAAM,iBAgB/D,CAAC;AAEF,eAAO,MAAM,yBAAyB,6BAYrC,CAAC;AAEF,eAAO,MAAM,4BAA4B,YAAa,MAAM,gCAY3D,CAAC"}
+{"version":3,"file":"translation-services.d.ts","sourceRoot":"","sources":["../../../../../../../../packages/sdk/kos-ui-sdk/src/models/models/translation/services/translation-services.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAuBH;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,UAAU,EAAE;QACV,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,uDAAuD;YACvD,OAAO,EAAE;gBACP,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAC;aACjC,CAAC;YACF,wDAAwD;YACxD,QAAQ,EAAE,MAAM,CAAC;SAClB,CAAC;KACH,CAAC;IACF,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;CACd;AAoBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,QAAe,MAAM,SAAS,MAAM,iBAgB/D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,yBAAyB,6BAYrC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,4BAA4B,YAAa,MAAM,gCAY3D,CAAC"}